EPyT-Control -- EPANET Python Toolkit - Control

EPyT-Control is a Python package building on top of EPyT-Flow for implementing and evaluating control algorithms & strategies in water distribution networks (WDNs).

Besides related control tasks such as state estimation and event diagnosis, a special focus of this Python package is Reinforcement Learning for data-driven control in WDNs and therefore it provides full compatibility with the Stable-Baselines3 package.

Unique Features

Unique features of EPyT-Control are the following:

• Support of hydraulic and (advanced) water quality simulation (i.e. EPANET and EPANET-MSX are supported)
• Compatibility with Gymnasium and integration of Stable-Baselines3
• Wide variety of pre-defined actions (e.g. pump state actions, pump speed actons, valve state actions, species injection actions, etc.)
• Implementation of classic control aglorithms such as PID and LQR controllers
• Signal processing methods such as state estimation (e.g. Kalman filters) and event diagnosis
• Neural surrogate models for state transition
• High- and low-level interface
• Object-orientated design that is easy to extend and customize

Installation

EPyT-Control supports Python 3.9 - 3.13

PyPI

pip install epyt-control

Git

Download or clone the repository: git clone https://github.com/WaterFutures/EPyT-Control.git cd EPyT-Control

Install all requirements as listed in REQUIREMENTS.txt: pip install -r REQUIREMENTS.txt

Install the toolbox: pip install .

Quick Example

Interface of Environments

Basic example demonstrating the environments' interface:

```python

Define/Specify MyEnv

....

Load hypothetical environment "MyEnv"

with MyEnv() as env: # Show the observation space print(f"Observation space: {env.observation_space}")

# Run 1000 iterations -- assuming that autorest=True
obs, info = env.reset()
for _ in range(1000):
    # Sample and apply a random action from the action space.
    # TODO: Replace with some smart RL/control method
    action = env.action_space.sample()
    obs, reward, terminated, _, _ = env.step(action)

    # Show action and observed reward
    print(action, reward)

```

Applying Reinforcement Learning to a given Environment

Simple example of using Stable-Baselines3 for learning a policy to control the chlorine injection in a given environment called SimpleChlorineInjectionEnv:

```python from stable_baselines3 import PPO from gymnasium.wrappers import NormalizeObservation

Define/Specify SimpleChlorineInjectionEnv

....

Load chlorine injection environment

with SimpleChlorineInjectionEnv() as env: # Wrap environment env = NormalizeObservation(env)

# Apply a simple policy learner
# You might want to add more wrappers (e.g. normalizing inputs, rewards, etc.) and logging here
# Also, inceasing the number of time steps might help as well
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=1000)
model.save("my_model_clinject.zip")  # Save policy

```

Documentation

Documentation is available on readthedocs: https://epyt-control.readthedocs.io/en/stable/

License

MIT license -- see LICENSE

How to Cite?

If you use this software, please cite it as follows:

@misc{github:epytcontrol, author = {André Artelt}, title = {{EPyT-Control -- EPANET Python Toolkit - Control}}, year = {2025}, publisher = {GitHub}, journal = {GitHub repository}, howpublished = {https://github.com/WaterFutures/EPyT-Control} }

How to get Support?

If you come across any bug or need assistance please feel free to open a new issue if non of the existing issues answers your questions.

How to Contribute?

Contributions (e.g. creating issues, pull-requests, etc.) are welcome -- please make sure to read the code of conduct and follow the developers' guidelines.