klabum/pystorms

Simulation Sandbox for the Design and Evaluation of Stormwater Control Algorithms

pystorms: simulation sandbox for the evaluation and design of stormwater control algorithms

Overview

This library has been developed in an effort to systematize quantitative analysis of stormwater control algorithms. It is a natural extension of the Open-Storm's mission to open up and ease access into the technical world of smart stormwater systems. Our initial efforts allowed us to develop open source and free tools for anyone to be able to deploy flood sensors, measure green infrastructure, or even control storm or sewer systems. Now we have developed a tool to be able to test the performance of algorithms used to coordinate these different sensing and control technologies that have been deployed throughout urban water systems.

For the motivation behind this effort, we refer the reader to our manuscript pystorms. In general, this repo provides a library of scenarios that are built to allow for systematic quantitative evaluation of stormwater control algorithms.

Getting Started

Installation

Requirements

• PyYAML >= 5.3
• numpy >= 18.4
• pyswmm

pip install pystorms

Please raise an issue on the repository or reach out if you run into any issues installing the package.

Example

Here is an example implementation on how you would use this library for evaluating the ability of a rule based control in maintaining the flows in a network below a desired threshold.

import pystorms 
import numpy as np

# Define your awesome controller 
def controller(state):
	actions = np.ones(len(state))
	for i in range(0, len(state)):
		if state[i] > 0.5:
			actions[i] = 1.0
	return actions 
	

env = pystorms.scenarios.theta() # Initialize scenario 

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

performance = env.performance()

Detailed documentation can be found on the webpage

pystorms's Issues

Update pyswmm to 1.0

module 'yaml' has no attribute 'FullLoader'

I got an error when I'm testing the example. Seems like the yaml,py should be renamed?https://stackoverflow.com/questions/9286637/pyyaml-error-attribute-error-no-attribute-load

Add support for simulation time

Webpage and Documentation Updates

1. Remove references to benchmarking
2. Update the links to correspond to the documentation
3. Update code example and list of scenarios
4. Colors could be improved
5. Ensure docs page matches with the paper
6. Update css template of readthedocs file

Scenario Configs

Add metadata into scenario description so that users don't have to open yaml file or documentation to see the number of nodes being controlled. There are multiple ways this can be realized.

1. Doc string in class?
2. meta-data dict that can be read, kinda building on what I have already.

step - arguments

Step function requires action argument. But the environment abstraction lets users run simulation with out requiring actions. Remove the requirement so that uncontrolled actions don't require the users to add np.ones()

Scenario Delta

Assimilate Scenario Delta

Scenario Zeta

1. Populate yaml file
2. Implement step and objective function

Scenario Alpha

Assimilate Scenario Alpha

add google colab support for tutorials

Functionality to save data

Add a method to scenarios to save data as npz/npy format.

Simulation time steps

Add a method in environment to get simulation time steps.

1. Careful with how variable time steps are handled in swmm

update __version__ variable in __init__.py

Update variable string to match actual software version.

Question for 'Theta' case

What does the variable 'potential' represent in the example codes of Theta case below? If the 'state' is the controller action, why did you make the 'state' over 'Max' to get the 'fd'?

`def controller(state, target, MAX=2.0):
fd = state / MAX
avg_fd = np.mean(fd)
potential = fd - avg_fd # [<0, 0, <1]

for i in range(0, 2):
    if potential[i] < -0.001:
        potential[i] = 0.0
    elif potential[i] < 0.001 and potential[i] > -0.001:
        potential[i] = avg_fd

if sum(potential) > 0.0:
    potential = potential / sum(potential)

actions = np.zeros(2)
if state[0] > 0.00:
    flow0 = target * potential[0]
    actions[0] = min(1.0, flow0 / (1.00 * np.sqrt(2.0 * 9.81 * state[0])))
if state[1] > 0.00:
    flow1 = target * potential[1]
    actions[1] = min(1.0, flow1 / (1.00 * np.sqrt(2.0 * 9.81 * state[1])))
return actions`

Scenario Beta

Assimilate Scenario Beta

Add support to dict and list in actions.

Enable users to pass dict or an array for setting control actions.

Dependency Issues

pyswmm or pyswmm_lite dependency needs clean up.

1. Update the setup.py file to incorporate yaml and pyswmm/pyswmm_lite dependency
2. Move over the environments.py file over to pystorms. This should make the transition seamless.

Update Equal-filling with more info

Add action and state dimension

Add variables to return the shape and what is represented in the state.

>>> env.state_space()
(1, 2)

Enable CI

Enable CI and coverage. Current set of test should cover every thing expect rainfall functionality.

Automate Releases

Automate the releases to pypl