Contributing#

Thank you for your interest !

Steps for contributing#

The master branch in the repository houses the code that has been completely tested and is bug free to the best of our knowledge. If you encounter a bug in the code, please raise an issue in the repository.

Instructions on raising an issue

Addressing a bug fix#

  1. Fork the repository and clone it into your local machine

git clone https://github.com/kLabUM/pystorms
cd pystorms

  1. Create a new branch for the fix

For example, if I am fixing an issue with the pollutant, I would create a new branch using this command.

git checkout -b abhiramm7_pollutantfix

  1. Add your fixes and push the changes into your fork of the repository.

git add <your changed files>
git push origin abhiramm7_pollutantfix

More details

  1. Once you are confident in the changes, you can create a pull request on the pystorms repository.

Raising a pull request

We can then work through the pull request.

Testing#

Please create a unit test for the code addition or any contribution you wish to make to the library. This repository uses pytest for testing. Unit tests can be found in tests/ and run with

pip install -e . pytest
pytest tests

Continuous integration runs the same suite on Linux, macOS and Windows for every supported Python version on each push to master and to release/** branches. Tests keep their derived networks and SWMM run files in a temporary directory, so they leave nothing behind.

Details on where to include what#

pystorms/networks#

This package provides access to the SWMM input files shipped with the library. To add a network:

  1. Add your processed input file (refer to building scenarios on how to process your input file) as pystorms/networks/<your network>.inp. Once you add your network to the library, it is public. So please be careful about what you upload.

  2. load_network("<your network>") finds the file by name; nothing else has to be registered.

  3. Add a test to tests/test_networks.py

network = pystorms.networks.load_network("<your network>")
assert "inp" == network[-3:]

pystorms/utilities.py#

Any general function you might need in developing scenarios goes in utilities.py.

For example, we use the append_rainfall function for adding rainfall timeseries to input files. This can be used on any input file and is not specific to a particular scenario. Hence, this function lives in utilities.py.

pystorms/scenarios#

One module per scenario, each defining a class of the same name, plus scenario.py with the base class every scenario derives from. Refer to building scenarios for more details on how to build one, and import the new class in pystorms/scenarios/__init__.py.

Anything that is specific to a network or scenario goes here. A scenario that defines a second version builds it inside its constructor and validates the keyword with validate_version; one that does not should still accept the keyword and pass ("1",) as the supported versions.

pystorms/config#

The configuration files, holding the network name, the state and action space and the performance targets, are placed here, one yaml file per scenario. The name is used to find both the yaml file and the network.

# Configuration file for scenario theta

# name of scenario
name: theta
# state definitions
states:
        - !!python/tuple
          - P1
          - depthN
        - !!python/tuple
          - P2
          - depthN
# Action space
action_space:
        - "1"
        - "2"
# Performance Targets
performance_targets:
        - !!python/tuple
          - "8"
          - flow
        - !!python/tuple
          - P1
          - flooding
        - !!python/tuple
          - P2
          - flooding

Add a test that constructs the scenario and runs it to completion to tests/test_scenarios.py, and if it defines a second version, to tests/test_versions_and_levels.py as well.