simulation module

Base class for a SWMM Simulation.

class pyswmm.simulation.Simulation(inputfile, reportfile=None, outputfile=None, swmm_lib_path=None)[source]

Bases: object

Base class for a SWMM Simulation.

The model object provides several options to run a simulation. User can specified SWMM library path. Uses default lib if not provided.

Initialize the Simulation class.

Parameters:
  • inpfile (str) – Name of SWMM input file (default ‘’)
  • rptfile (str) – Report file to generate (default None)
  • binfile (str) – Optional binary output file (default None)
  • swmm_lib_path (str) – User-specified SWMM library path (default None).

Examples:

Intialize a simulation and iterate through a simulation. This approach requires some clean up.

>>> from pyswmm import Simulation
>>>
>>> sim = Simulation('tests/data/TestModel1_weirSetting.inp')
>>> for step in sim:
...     pass
>>>
>>> sim.report()
>>> sim.close()

Intialize using with statement. This automatically cleans up after a simulation

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     for step in sim:
...         pass
...     sim.report()

Initialize the simulation and execute. This style does not allow the user to interact with the simulation. However, this approach tends to be the fastest.

>>> from pyswmm import Simulation
>>>
>>> sim = Simulation('tests/data/TestModel1_weirSetting.inp')
>>> sim.execute()
add_after_close(callback)[source]

Add callback function/method/object to execute after the simulation is closed. Needs to be callable.

Parameters:callback (func) – Callable Object

(See self.add_before_start() for more details)

add_after_end(callback)[source]

Add callback function/method/object to execute after the simulation ends. Needs to be callable.

Parameters:callback (func) – Callable Object

(See self.add_before_start() for more details)

add_after_step(callback)[source]

Add callback function/method/object to execute after a simlation step. Needs to be callable.

Parameters:callback (func) – Callable Object

(See self.add_before_start() for more details)

add_before_end(callback)[source]

Add callback function/method/object to execute after the simulation ends. Needs to be callable.

Parameters:callback (func) – Callable Object

(See self.add_before_start() for more details)

add_before_start(callback)[source]

Add callback function/method/object to execute before the simlation starts. Needs to be callable.

Parameters:callback (func) – Callable Object
>>> from pyswmm import Simulation
>>>
>>> def test_callback():
...     print("CALLBACK - Executed")
>>>
>>> with Simulation('./TestModel1_weirSetting.inp') as sim:
...
...     sim.before_start(test_callback) #<- pass function handle.
...     print("Waiting to Start")
...     for ind, step in enumerate(sim):
...         print("Step {}".format(ind))
...     print("Complete!")
... print("Closed")
>>>
>>> "Waiting to Start"
>>> "CALLBACK - Executed"
>>> "Step 0"
>>> "Step 1"
>>> ...
>>> "Complete!"
>>> "Closed"
add_before_step(callback)[source]

Add callback function/method/object to execute before a simlation step. Needs to be callable.

Parameters:callback (func) – Callable Object

(See self.add_before_start() for more details)

after_close()[source]

Get After Close Callback.

Returns:Callbacks
after_end()[source]

Get After End Callback.

Returns:Callbacks
after_step()[source]

Get After Step Callback.

Returns:Callbacks
before_end()[source]

Get Before End Callback.

Returns:Callbacks
before_start()[source]

Get Before Start Callback.

Returns:Callbacks
before_step()[source]

Get Before Step Callback.

Returns:Callbacks
close()[source]

Intialize a simulation and iterate through a simulation. This approach requires some clean up.

Examples:

>>> from pyswmm import Simulation
>>>
>>> sim = Simulation('./TestModel1_weirSetting.inp')
>>> for step in sim:
...     pass
>>>
>>> sim.report()
>>> sim.close()
current_time

Get Simulation Current Time.

Returns:Current Simulation Time
Return type:Datetime

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     for step in sim:
...         print(sim.current_time)
...     sim.report()
>>>
>>> 2015-11-01 14:00:30
>>> 2015-11-01 14:01:00
>>> 2015-11-01 14:01:30
>>> 2015-11-01 14:02:00
end_time

Get/set Simulation end time.

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     print sim.end_time
...     sim.end_time = datetime(2016,5,10,15,15,1)
>>>
>>> datetime.datetime(2016,5,10,15,15,1)
engine_version

Retrieves the SWMM Engine Version.

Returns:Engine Version
Return type:StrictVersion

Examples:

>>> sim = PYSWMM(r'\test.inp')
>>> sim.engine_version
StrictVersion("5.1.13")
execute()[source]

Open an input file, run SWMM, then close the file.

Examples:

>>> sim = PYSWMM(r'\test.inp')
>>> sim.execute()
flow_routing_error

Retrieves the Flow Routing Mass Balance Error.

Returns:Flow Routing Mass Balance Error
Return type:float

Examples:

>>> sim = PYSWMM(r'\test.inp')
>>> sim.execute()
>>> sim.flow_routing_error
0.01
flow_units

Get Simulation Units (CFS, GPM, MGD, CMS, LPS, MLD).

Returns:Flow Unit
Return type:str

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     print sim.flow_units
>>>
>>> CFS
initial_conditions(init_conditions)[source]

Intial Conditions for Hydraulics and Hydrology can be set from within the api by setting a function to the initial_conditions property.

>>> from pyswmm import Simulation
>>>
>>> with Simulation('./TestModel1_weirSetting.inp') as sim:
...     nodeJ1 = Nodes(sim)["J1"]
...
...     def init_conditions():
...         nodeJ1.initial_depth = 4
...
...     sim.initial_conditions(init_conditions)
...
...     for step in sim:
...         pass
...     sim.report()
next()

Next

percent_complete

Get Simulation Percent Complete.

Returns:Current Percent Complete
Return type:Datetime

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     for step in sim:
...         print(sim.percent_complete)
...     sim.report()
>>>
>>> 0.01
>>> 0.25
>>> 0.50
>>> 0.75
quality_error

Retrieves the Quality Routing Mass Balance Error.

Returns:Quality Routing Mass Balance Error
Return type:float

Examples:

>>> sim = PYSWMM(r'\test.inp')
>>> sim.execute()
>>> sim.quality_error
0.01
report()[source]

Writes to report file after simulation.

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     for step in sim:
...         pass
...     sim.report()
report_start

Get/set Simulation report start time.

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     print sim.report_start
...     sim.report_start = datetime(2015,5,10,15,15,1)
>>>
>>> datetime.datetime(2015,5,10,15,15,1)
runoff_error

Retrieves the Runoff Mass Balance Error.

Returns:Runoff Mass Balance Error
Return type:float

Examples:

>>> sim = PYSWMM(r'\test.inp')
>>> sim.execute()
>>> sim.runoff_error
0.01
start()[source]

Start Simulation

start_time

Get/set Simulation start time.

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     print sim.start_time
...     sim.start_time = datetime(2015,5,10,15,15,1)
>>>
>>> datetime.datetime(2015,5,10,15,15,1)
step_advance(advance_seconds)[source]

Advances the model by X number of seconds instead of intervening at every routing step. This does not change the routing step for the simulation; only lets python take back control after each advance period.

Parameters:advance_seconds (int) – Seconds to Advance simulation

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     sim.step_advance(300)
...     for step in sim:
...         print(step.current_time)
...         # or here! sim.step_advance(newvalue)
...     sim.report()
>>>
>>> 2015-11-01 14:00:30
>>> 2015-11-01 14:01:00
>>> 2015-11-01 14:01:30
>>> 2015-11-01 14:02:00
system_units

Get system units (US, SI).

Returns:System Unit
Return type:str

Examples:

>>> from pyswmm import Simulation
>>>
>>> with Simulation('tests/data/TestModel1_weirSetting.inp') as sim:
...     print sim.system_units
>>>
>>> US