PYSWMM errors.py Summary

 Below is an extended summary of the code, explaining each custom exception class and how they fit into a broader simulation or output workflow:

---

Overview

This module defines three custom exception classes that extend Python’s built-in Exception:

1. IncompleteSimulation
2. OutputException
3. MultiSimulationError

These classes are intended to provide clear, descriptive error messages for various failure conditions that may arise in a SWMM-based simulation or output-reading context. By encapsulating errors in specialized exceptions, they enable developers to catch and handle these scenarios more gracefully and unambiguously.

---

Exception Classes

1. IncompleteSimulation

• Purpose
  Raised when a SWMM simulation fails to complete or is missing some critical finalization step.

• Usage
  A typical scenario is if a user attempts to retrieve final results or mass balance statistics before the simulation has had a chance to finish. If the SWMM engine ends unexpectedly, or if the user stops the simulation prematurely, this exception informs the developer or end-user that the simulation was never fully completed.

• Attributes

  • message: A string describing why the simulation was deemed incomplete.

• Constructor

  def __init__(self, message):
      self.message = message
      super().__init__(self.message)
  

  By calling super().__init__, this allows custom error messages to be displayed in a standard Pythonic manner.

2. OutputException

• Purpose
  Indicates an error specifically associated with a SWMM output object—often used when reading, parsing, or processing simulation results from a binary or text output file.

• Usage
  Raised if something goes awry when:

  • Reading from an output file that is corrupted or does not exist.
  • Attempting to access data (e.g., subcatchment or node results) that the output file does not contain.
  • Encountering version mismatches or internal inconsistencies within the output data.

• Attributes

  • message: Explains why the output object or reading process has failed.

• Constructor

  def __init__(self, message):
      self.message = message
      super().__init__(self.message)
  

3. MultiSimulationError

• Purpose
  Warns that a second SWMM simulation is attempting to be created or run in the same Python process. This reflects a known architectural limitation in the SWMM engine, which often is not thread-safe or re-entrant.

• Usage
  If a developer tries to instantiate or run more than one SWMM simulation at once—or in overlapping sequences—this exception is triggered. The recommended approach is to run separate simulations in separate Python processes if concurrency is needed.

• Attributes

  • message: A message explaining that multiple simulations cannot be conducted concurrently in one Python process.
  • _multi_sim_message: An additional multiline string providing more context and suggestions (e.g., using subprocesses).

• Constructor

  def __init__(self, message):
      self.message = message + "\n\n" + _multi_sim_message
      super().__init__(self.message)
  

  This merges any custom error message with a predefined _multi_sim_message that clarifies the limitation.

---

Summary of Use Cases

1. IncompleteSimulation

   • Called if the engine halts unexpectedly or a simulation stops before finishing.
   • Common scenario: a user tries to retrieve final results like mass balance or statistical summaries while the simulation is still in progress or prematurely terminated.

2. OutputException

   • Thrown during reading or parsing stages of SWMM output files when file corruption, missing sections, or unexpected data are encountered.
   • E.g., referencing a nonexistent subcatchment ID or pollutant ID in the output file.

3. MultiSimulationError

   • If a second SWMM run is initiated while another is still in memory (in the same Python process), this exception notifies the user of the inherent SWMM restrictions.
   • Encourages using separate processes or queue managers to handle multiple runs.

---

Conclusion

These custom exceptions provide a clear, domain-specific error handling layer for SWMM simulations in Python. By distinguishing common failure modes (incomplete runs, invalid output, multiple simultaneous simulations), they help developers quickly diagnose issues, enforce best practices, and guide users to appropriate solutions—such as completing the simulation or running additional SWMM instances in separate processes.