Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Contributors Forks Stargazers Issues MIT License Apache License LinkedIn


Pywr-next

The next major release of Pywr, a water-resource allocation modelling system. Pywr v2 combines a Rust computational core with Python bindings and a command line interface. It is now at its first release candidate, moving beyond the experimental stage towards a stable v2.0 release.

User Guide · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Porting a Pywr v1.x model to v2.x
  5. Crates
  6. Release status
  7. Contributing
  8. License
  9. Contact

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

Rust Python

(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):

Feature Description Default
pyo3 Enable Python integration. Yes
clp Enable the Clp LP solver. No
cbc Enable the Cbc MILP solver. No
highs Enable the HiGHS solver. No
microlp Enable the pure-Rust MicroLP solver. No
ipm-ocl Enable the OpenCL IPM solver. No
ipm-simd Enable the SIMD IPM solver. No
hdf5 Enable HDF5 output. No

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):

Feature Description Default
core Build executable models using pywr-core. Yes
pyo3 Enable Python integration. Yes
clp Enable the Clp LP solver. Yes
hdf5 Enable HDF5 support. Yes
cbc Enable the Cbc MILP solver. No
highs Enable the HiGHS solver. No
microlp Enable the pure-Rust MicroLP solver. No
ipm-ocl Enable the OpenCL IPM solver. No
ipm-simd Enable the SIMD IPM solver. No

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.

Metadata

Release files for pywr 2.0.0rc3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pywr 2.0.0rc3
File Size Uploaded Provenance Actions
pywr-2.0.0rc3.tar.gz 8.2 MB With provenance Details for pywr-2.0.0rc3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pywr 2.0.0rc3
File Actions
pywr-2.0.0rc3-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for pywr-2.0.0rc3-cp311-abi3-win_amd64.whl
pywr-2.0.0rc3-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for pywr-2.0.0rc3-cp311-abi3-manylinux_2_28_x86_64.whl
pywr-2.0.0rc3-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for pywr-2.0.0rc3-cp311-abi3-macosx_11_0_arm64.whl
pywr-2.0.0rc3-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for pywr-2.0.0rc3-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 80.4 MB

Release files / pywr-2.0.0rc3.tar.gz

Download URL pywr-2.0.0rc3.tar.gz
Size 8.2 MB
Tags Source
SHA-256 checksum
How to use checksums
75f2c74404bf9f2b6147bd2d827d464e103f81042a876e1655f587e2d1e70697
BLAKE2b-256 checksum
How to use checksums
eea8a459425069a6b213c4661ef3eeef2bfc1bd2e65d4074ecffe1340aad94cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / pywr-2.0.0rc3-cp311-abi3-win_amd64.whl

Download URL pywr-2.0.0rc3-cp311-abi3-win_amd64.whl
Size 18.5 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
b88f0fad4412653419e060d9cfcb2343af9447d3e971d9d794823ad945a92245
BLAKE2b-256 checksum
How to use checksums
bc25d33f6051b54581d1b52c00bb8d27951e17a3e047dd0707457a82a8d412de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / pywr-2.0.0rc3-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL pywr-2.0.0rc3-cp311-abi3-manylinux_2_28_x86_64.whl
Size 19.6 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
ec33c366486830d015b95824b0f90beb109006b252c90d81894f425f53fb0a6a
BLAKE2b-256 checksum
How to use checksums
0bffe2e38258c52ff598bf009b838ce9035f05b175abf56be3dea562ea57f998
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / pywr-2.0.0rc3-cp311-abi3-macosx_11_0_arm64.whl

Download URL pywr-2.0.0rc3-cp311-abi3-macosx_11_0_arm64.whl
Size 16.6 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5fee504ad0540dec51bc6b2d160b828715c152e8fbad5b06d9423f6fd2d78d9c
BLAKE2b-256 checksum
How to use checksums
d9b05d0bdb6fcad1f5d9d30609f7760356c493f997c4a9d66263ce6ccb56f923
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / pywr-2.0.0rc3-cp311-abi3-macosx_10_12_x86_64.whl

Download URL pywr-2.0.0rc3-cp311-abi3-macosx_10_12_x86_64.whl
Size 17.5 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
03256efa4d5e19c22f69846c24ec9eda7c0937af3ec1df89308fa35b9198efe6
BLAKE2b-256 checksum
How to use checksums
3a674d0f57ec2dbc068f80fa215fc59d6f806d1311e229b9c0e3c7a402f008f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for pywr 2.0.0rc3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for pywr-2.0.0rc3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page