pystorms

A simulation sandbox for the development and evaluation of stormwater control algorithms

Welcome! We’ve developed pystorms with the objective of making the research of stormwater control more accessible. This open-source python package provides a curated collection of diverse stormwater networks and rain events, coupled with a streamlined programming interface and a stormwater simulator to provide a standalone package for developing and evaluating stormwater control algorithms. Please refer to the manuscript for more details on the motivation behind this effort.

Getting Started

pystorms is available on pypi and can be directly installed using pip. It is supported on OSX, Linux, and Windows. pystorms requires Python 3.9 or newer, and installs pyswmm(≥ 1.0.1), swmmio(≥ 0.6.11), numpy(≥ 1.18.4), pandas(≥ 1.0), and PyYAML(≥ 5.3) with it. Please raise an issue on the repository or reach out if you encounter any installation issues.

 pip install pystorms

In pystorms , control of stormwater networks is abstracted as scenarios, named after letters from Greek alphabet.

import pystorms

def controller(state):
    """
    Your control algorithm that generates actions based on state information.
    """
    return actions

env = pystorms.scenarios.theta()
done = False

while not done:
    state = env.state()
    actions = controller(state)
    done = env.step(actions)

Scenario theta is a synthetic example for prototyping control algorithms. Six other scenarios inspired from real-world stormwater are included to provide realistic examples for evaluating stormwater control algorithms. Please refer to the documentation for more details.

What's new in 2.0

Every scenario now takes two keywords. version selects the network: "1" is the scenario as published, and "2" is a harder variant of the same network for theta, alpha, gamma, delta and epsilon. level decides how trustworthy the instrumentation is: "1" reports the true state, "2" adds sensor noise, drift and calibration bias and lets valves stick, and "3" intensifies all of that and adds sensors that drop out. The two are independent, so a controller can be tested on a fixed network while only the measurement quality changes.

env = pystorms.scenarios.theta(version="2", level="3")
done = False

while not done:
    state = env.state()              # noisy, drifting, biased readings
    done = env.step(controller(state))  # stuck valves ignore the command

The faults are drawn from numpy's random state when the scenario is built, so seed it first for a repeatable comparison. The versions and levels page documents the changes to each scenario and what each level does, and the changelog lists everything else that changed.

Version 2 scenarios

Version 2 tightens the objective and modifies the network so that a controller tuned for the original scenario has less room to look good. Version 1 is untouched and stays the default.

The version 2 network is built when the scenario is constructed, by rewriting the shipped SWMM input file. The copy goes to a per user cache directory (PYSTORMS_CACHE, or ~/.cache/pystorms/networks), never into the installed package.

Baseline controllers

Every version 2 scenario ships with two rule based controllers to measure against, plus the uncontrolled response. Their parameters were tuned by Bayesian optimization on level 1 and then evaluated as-is on levels 2 and 3, so the tables below show how much of a controller's benefit survives noisy sensors and sticking valves. The implementations, the tuned parameters, the optimization scripts and the plotting code live in the baseline_controllers directory of the repository.

Performance on the version 2 scenarios, lower is better. Percentages are relative to the uncontrolled response at the same level.

Scenario fixes in 2.0

Preparing the version 2 scenarios turned up a number of problems in the shipped scenarios and in the code that runs them. This table tracks what was wrong, what 2.0 does about it, and whether it changes the numbers a 1.0 script produced. The changelog has the full list, including fixes outside the scenarios.

Jupyter Notebooks

• Theta:
  • Google Colab: Theta.ipynb
  • Github Source: Theta.ipynb
• Alpha:
  • Google Colab: Alpha.ipynb
  • Github Source: Alpha.ipynb
• Beta:
  • Google Colab: Beta.ipynb
  • Github Source: Beta.ipynb
• Gamma:
  • Google Colab: Gamma.ipynb
  • Github Source: Gamma.ipynb
• Delta:
  • Google Colab: Delta.ipynb
  • Github Source: Delta.ipynb
• Epsilon:
  • Google Colab: Epsilon.ipynb
  • Github Source: Epsilon.ipynb
• Zeta:
  • Google Colab: Zeta.ipynb
  • Github Source: Zeta.ipynb
• Versions and levels:
  • Google Colab: Versions_and_Levels.ipynb
  • Github Source: Versions_and_Levels.ipynb
• Rule based control:
  • Google Colab: RuleBasedControl.ipynb
  • Github Source: RuleBasedControl.ipynb
• Reinforcement learning:
  • Google Colab: ReinforcementLearning.ipynb
  • Github Source: ReinforcementLearning.ipynb

UDM 2022: UDS-RTC 101

• Presentation :
  • pdf: udm2022_rtc101.pdf
• pyswmm :
  • Google Colab: pyswmm.ipynb
  • Github Source: pyswmm.ipynb
• pystorms :
  • Google Colab: pystorms.ipynb
  • Github Source: pystorms.ipynb
• Equal Filling :
  • Google Colab: EqualFilling.ipynb
  • Github Source: EqualFilling.ipynb
• Bayesian Optimization :
  • Google Colab: BayesianOptimization.ipynb
  • Github Source: BayesianOptimization.ipynb

Get Involved

If you want to be more involved, please consider the following:

• Submit some of your own scenarios to our repository! We are looking to expand this package to include far more networks/scenarios with more diverse control needs and that have been implemented with a variety of different hydraulic simulators.
• Download our code and hack into it for whatever other needs you may have! We have built this package to be 100% open-source, so if you want to use it for any other application or need that you see fit, by all means, have at it. While the scenarios were built specifically for direct algorithm performance, we have also provided libraries of many other driving events so that you can customize your own research problem.
• Check out our other open-source efforts, including open-storm.org, where we have built open-source sensor nodes for smart stormwater testing and deployment.

Testimonials

About us

pystorms is developed by the open-storm group, a consortium of universities and industry partners developing open-source solutions for smarter stormwater systems.