pywr 2.0.0rc1

About The Project

Pywr simulates the allocation of water through a network of sources, stores, links and demands. Costs and constraints control allocation at each time step, while parameters describe changing conditions and operating rules across scenarios.

This repository contains Pywr v2. It retains the flexible, parameter-driven modelling approach of Pywr v1.x, with a redesigned Rust core, a typed JSON model schema, and Python interfaces for running models and extending their behaviour.

Benefits over Pywr v1.x

• A reusable computational core. The Rust engine can be used independently of Python, with separate crates for model schemas, project composition and command line tools. Python remains available for custom model logic and analysis.
• Explicit model definitions and validation. A typed JSON schema and structured validation help identify invalid references, connections and parameter types before simulation. JSON Schema can also be exported for external tooling.
• Parallel scenario execution. The engine supports running scenarios in parallel and releases Python's GIL during Rust model execution. Performance depends on the model, solver and use of Python callbacks rather than a universal speedup over v1.x.
• Redesigned outputs and metrics. Metric sets separate the quantities being recorded from their output format, with aggregation and in-memory results alongside CSV, HDF5 and Arrow outputs.
• More explicit Python extensions. Custom Python parameters declare their dependencies and can maintain per-scenario state, making calculation order and state ownership clearer.

Pywr v2 is not a drop-in replacement for v1.x: the JSON schema and Python API have changed. See the migration guidance below before upgrading existing models.

(back to top)

Features

• Network components for reservoirs, catchments, abstractions, losses, treatment works and hydropower, including virtual and aggregated nodes.
• A parameter system with profiles, control curves, thresholds, arithmetic, interpolation, rolling calculations, delays and custom Python functions or classes.
• Delay and Muskingum river routing, and multi-network models with inter-network transfers.
• Multiple optimisation backends, including Clp, HiGHS and Cbc, with additional solver options in the Rust crates.
• Native CSV, Arrow IPC and Parquet time-series input, plus Python-backed data loaders.
• Metric aggregation and CSV, HDF5, Arrow-stream and in-memory outputs for subsequent analysis in Python.
• Multi-file project composition and command line tools for running models, converting v1.x files and exporting schemas.

See the User Guide for model concepts, supported components and examples.

Built With

(back to top)

Getting started

Installing from PyPI

The Python package is named pywr and requires Python 3.11 or later. Use a separate virtual environment when trying v2 alongside an existing v1.x installation.

To install the v2 release candidate (2.0.0rc1) or a newer v2 release from PyPI:

python -m pip install --upgrade "pywr>=2.0.0rc1,<3"

Once the stable v2 release is published, use:

python -m pip install --upgrade "pywr>=2,<3"

The version constraint selects v2 rather than v1.x. To remain on v1.x, use python -m pip install "pywr<2" instead.

Optional extras are available for data integrations: pandas, polars, excel and hdf. For example, to install the v2 release candidate with Pandas and Excel support:

python -m pip install --upgrade "pywr[pandas,excel]>=2.0.0rc1,<3"
python -m pywr --help

Wheel builds target Linux x86-64, Windows x64, and macOS Intel and Apple Silicon. Installing a compatible wheel does not require Rust or a C/C++ compiler. If no wheel is available for your platform and Python version, a source build is required. See the installation guide for more details.

Compiling from source

Source builds require a current stable Rust toolchain, Python 3.11 or later, C/C++ build tools, CMake, and Clang/libclang for native dependencies. The bundled COIN-OR solvers use Git submodules; initialise them before building.

From the repository root, create a Python development installation using Maturin:

git submodule update --init --recursive
python -m venv .venv # create a new virtual environment
source .venv/bin/activate # activate the virtual environment (linux)
# .venv\Scripts\activate # activate the virtual environment (windows)
python -m pip install "maturin>=1.15,<2"
maturin develop --release # build and install the Python extension
python -m pywr --help

(back to top)

Usage

Rust CLI

The pywr-cli crate provides commands for running single-network, multi-network and project models, converting v1.x models, and exporting JSON Schema. The commands below are run from the repository root. The default build includes Python support for models that use Python extensions.

To see the CLI commands available run the following:

cargo run --release -p pywr-cli -- --help

To run a Pywr v2 model use the following:

cargo run --release -p pywr-cli -- run pywr-schema/tests/simple1.json

Python CLI

After installing from PyPI or building from source, run a model with python -m pywr run path/to/model.json. For example, from a checkout of this repository:

python -m pywr run pywr-schema/tests/simple1.json

Use python -m pywr run --help for solver, input-data and output-directory options. The Python CLI supports Clp (the default), HiGHS and Cbc. The example above writes an HDF5 output file.

Porting a Pywr v1.x model to v2.x

Pywr v2 uses a new JSON schema and Python API. Existing v1.x models must be migrated; upgrading the Python package alone is not sufficient. The Rust CLI includes a conversion tool to help translate v1.x JSON models:

cargo run --release -p pywr-cli -- convert old-model.json converted-model.json --stop-on-error

Conversion is a starting point, not a guarantee of an equivalent model. Not all v1.x features are supported, and without --stop-on-error the converter may produce a partial model alongside conversion errors. Review all diagnostics, complete the migration manually, and compare model outputs before relying on the converted model.

In particular:

• Tables and recorders/outputs are not automatically migrated; configure v2 data sources, metric sets and outputs.
• Custom Python parameters need updating to the new interface.
• Input time series must match the model's time resolution; v2 does not automatically resample them as v1.x did.

See the migration guide for details. Feedback on porting models is welcome via GitHub issues.

(back to top)

Crates

This repository contains the following crates:

Pywr-core

A low-level Rust library for constructing network models. This crate interfaces with linear program solvers.

Feature flags (defaults for this crate when used directly):

Pywr-schema

A Rust library for validating Pywr JSON files against a schema, and then building a model from the schema using pywr-core.

Feature flags (defaults for this crate when used directly):

For schema validation and manipulation without the simulation engine, use default-features = false. Solver availability in applications depends on their enabled features and exposed interfaces; OpenCL also requires a suitable runtime and device.

Pywr-cli

A command line interface for running Pywr models.

Pywr-python

A Python extension (and package) for constructing and running Pywr models.

Pywr-project

Schemas and composition tools for projects that assemble models from multiple files and options.

Supporting crates

• pywr-runner-engine, pywr-runner-service, pywr-runner-protocol and pywr-runner-transport: local model execution service, protocol and transport.
• coin-or-sys: bindings to the bundled COIN-OR solvers.
• ipm-common, ipm-simd and ipm-ocl: interior-point solver implementations and shared utilities.
• pywr-schema-macros: procedural macros supporting the model schema.

Release status

Pywr v2 is now at 2.0.0-rc1, its first release candidate (Python version 2.0.0rc1). The core modelling engine, Python bindings, schema validation and redesigned output system are implemented. This marks the transition out of the experimental stage towards the first stable v2.0 release. The release candidate is still a prerelease.

Release readiness does not imply complete feature parity or backwards compatibility with v1.x. Testing representative models, checking migration results and reporting issues with the release candidate are especially valuable ahead of the stable release.

See the changelog, releases and open issues for release notes, planned work and known limitations.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

The Pywr code in this repository is dual-licensed under the Apache 2.0 or MIT license. Bundled third-party components have additional licensing terms, including EPL-2.0 for COIN-OR components in the Python distribution. See NOTICE and the bundled license files for details.

(back to top)

Contact

James Tomlinson - tomo.bbe@gmail.com

Project Link: https://github.com/pywr/pywr-next

(back to top)

Copyright (C) 2020-2026 James Tomlinson Associates Ltd.