Catchment simulation

Package include method for simulate subcatchment with different features values from Storm Water Management Model. Currently, some of the 'catchment simulation' functionality available in the app - catchment simulation

Examples of How To Use

Creating SWMM object for analyse

Inslall catchment_simulation package using pip

pip install catchment-simulation

Example of simulation subcatchment area in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_area(start=1, stop=10, step=1)

More code examples at the end of the notebook.

Catchment simulation app

The application was built in django share some of the functionality from the 'catchment simulation' package.

It is designed to analyze and predict water flow behavior in catchments. The application contain two main components: the Catchment Simulation package and Catchment Calculation. On the main page you can find information of the 'catchments simulation' package and examples of use.

Application at - https://catchment-simulations.onrender.com/

Simulations in a web application

The 'Simulations' tab allows the user to upload a file and select components for simulation. Once the simulation is executed, the window will display an interactive graph of the obtained data and a button to download the results in an excel spreadsheet.

Warning

You will be asked to register and log in before performing the simulation.

Appendix - ANN and SWMM predictions

The 'Calculations' tab contains a neural network model trained to predict catchment area runoff. The user, after uploading the file, receives the results of calculations performed SWMM and ANN model prediction.

Warning

You will be asked to register and log in before performing the simulation.

Model and static data artifacts

• The Django app runtime loads ANN weights from cs_app/swmm_model/weights.npz (pure NumPy inference).
• Static chart seed data in cs_app/data is stored as JSON files (*.json).
• Simulation/timeseries downloads are generated in memory on demand (no persistent media files required).

---

Local Development Setup

Running the Django Web Application Locally

Prerequisites

• Python 3.10+
• uv package manager (recommended)

Quick Start

# Clone repository
git clone https://github.com/BuczynskiRafal/catchments_simulation.git
cd catchments_simulation

# Create virtual environment with uv
uv venv --python 3.12  # any Python 3.10+ is supported
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install project dependencies for app development
uv sync --frozen --extra dev --extra web

# Optional: install docs toolchain
uv sync --frozen --extra docs --extra web

# macOS only: Run this only if you see killed process/SIGKILL errors
find .venv -name "*.so" -o -name "*.dylib" | xargs codesign --force --sign -

# Run the app
cd cs_app
uv run python manage.py migrate
uv run python manage.py runserver

Open http://127.0.0.1:8000/ in your browser.

For detailed instructions, see cs_app/README.md.

uv.lock is committed to the repository. If you change dependencies in pyproject.toml, regenerate it with uv lock and commit both files together.

E2E Playwright (Django)

Playwright E2E tests for the Django app are implemented with pytest and are marked as e2e. They are excluded from default pytest runs and should be executed explicitly.

# Install dependencies including E2E tooling
uv sync --frozen --extra dev --extra web --extra e2e

# Install Chromium browser for Playwright
uv run playwright install chromium

# Run E2E tests
uv run pytest cs_app/e2e -m e2e --browser chromium

---

Timeseries (hydrograph) data

Get per-timestep runoff hydrograph from a single simulation.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
ts = model.calculate_timeseries()
# ts is a DataFrame with DatetimeIndex and columns:
# rainfall, runoff, infiltration_loss, evaporation_loss, runon

Collect timeseries for varying subcatchment parameter values.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
results = model.simulate_subcatchment_timeseries("PercImperv", start=0, stop=100, step=25)
# results is a dict[float, DataFrame] — one hydrograph per parameter value
# e.g. results[25.0] returns the timeseries DataFrame for PercImperv=25

Compute time to peak runoff.

from catchment_simulation import FeaturesSimulation
from catchment_simulation.analysis import time_to_peak

with FeaturesSimulation(subcatchment_id="S1", raw_file="example.inp") as model:
    ts = model.calculate_timeseries()
ttp = time_to_peak(ts)
# ttp is a pd.Timedelta, e.g. Timedelta('0 days 02:30:00')

Compute total runoff volume over a time interval.

from datetime import datetime
from catchment_simulation import FeaturesSimulation
from catchment_simulation.analysis import runoff_volume

with FeaturesSimulation(subcatchment_id="S1", raw_file="example.inp") as model:
    ts = model.calculate_timeseries()
volume = runoff_volume(ts)
# volume in flow-unit x seconds (e.g. cubic metres for CMS models)

# restrict to a specific interval (both endpoints inclusive)
partial = runoff_volume(
    ts,
    start=datetime(2022, 6, 17, 2, 0),
    end=datetime(2022, 6, 17, 6, 0),
)

More examples of package usage

Simulate subcatchment percent impervious in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_percent_impervious(start=1, stop=10, step=1)

Simulate subcatchment percent slope in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_percent_slope(start=1, stop=10, step=1)

Simulate subcatchment width in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_width(start=1, stop=10, step=1)

Simulate subcatchment curb length in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_curb_length(start=1, stop=10, step=1)

Simulate subcatchment N-Imperv in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_n_imperv()

Simulate subcatchment N-Perv in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_n_perv()

Simulate subcatchment Destore-Imperv in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_s_imperv()

Simulate subcatchment Destore-Perv in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_s_perv()

Simulate subcatchment Percent Zero Imperv in selected range.

from catchment_simulation.catchment_features_simulation import FeaturesSimulation

subcatchment_id = "S1"
raw_file = "catchment_simulation/example.inp"
model = FeaturesSimulation(subcatchment_id=subcatchment_id, raw_file=raw_file)
df = model.simulate_percent_zero_imperv(start=0, stop=100, step=10)

Bugs

If you encounter any bugs or issues while using our software, please feel free to report them on the project's issue tracker. When reporting a bug, please provide as much information as possible to help us reproduce and resolve the issue, including:

• A clear and concise description of the issue
• Steps to reproduce the problem
• Expected behavior and actual behavior
• Any error messages or logs that may be relevant

Your feedback is invaluable and will help us improve the software for all users.

Contributing

We welcome and appreciate contributions from the community! If you're interested in contributing to this project, please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your changes.
3. Make your changes, including updates to documentation if needed.
4. Write tests to ensure your changes are working as expected.
5. Ensure all tests pass and there are no linting or code style issues.
6. Commit your changes and create a pull request, providing a detailed description of your changes.

We will review your pull request as soon as possible and provide feedback. Once your contribution is approved, it will be merged into the main branch.

For more information about contributing to the project, please see our contributing guide.

License

License This project is licensed under the MIT License. By using, distributing, or contributing to this project, you agree to the terms and conditions of the license. Please refer to the LICENSE.md file for the full text of the license.