Installation

Pywr is both a Rust library and a Python package.

Rust

TBC

Python

Pywr requires Python 3.10 or later. It is currently available on PyPI as a pre-release.

Note: That current Pywr v2.x is in pre-release and may not be suitable for production use. If you require Pywr v1.x please use pip install pywr<2.

Installing from PyPI (pre-release)

Using pip and venv

It is recommended to install Pywr into a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
pip install pywr --pre

Using uv

Alternatively, you can use uv to create and manage virtual environments:

uv init my-project
cd my-project
uv add pywr --pre

Installing from a wheel

Alternatively, wheels are available from the GitHub actions page. Navigate to the latest successful build, and download the archive and extract the wheel for your platform.

pip install pywr-2.0.0b0-cp310-abi3-win_amd64.whl

Checking the installation

To verify the installation, run to see the command line help:

python -m pywr --help

Running a model

Pywr is a modelling system for simulating water resources systems. Models are defined using a JSON schema, and can be run using the pywr command line tool. Below is an example of a simple model definition simple1.json:

{
  "metadata": {
    "title": "Simple 1",
    "description": "A very simple example.",
    "minimum_version": "0.1"
  },
  "timestepper": {
    "start": "2015-01-01",
    "end": "2015-12-31",
    "timestep": {
      "type": "Days",
      "days": 1
    }
  },
  "network": {
    "nodes": [
      {
        "meta": {
          "name": "supply1"
        },
        "type": "Input",
        "max_flow": {
          "type": "Literal",
          "value": 15.0
        }
      },
      {
        "meta": {
          "name": "link1"
        },
        "type": "Link"
      },
      {
        "meta": {
          "name": "demand1"
        },
        "type": "Output",
        "max_flow": {
          "type": "Parameter",
          "name": "demand"
        },
        "cost": {
          "type": "Literal",
          "value": -10
        }
      }
    ],
    "edges": [
      {
        "from_node": "supply1",
        "to_node": "link1"
      },
      {
        "from_node": "link1",
        "to_node": "demand1"
      }
    ],
    "parameters": [
      {
        "meta": {
          "name": "demand"
        },
        "type": "Constant",
        "value": {
          "type": "Literal",
          "value": 10.0
        }
      }
    ],
    "metric_sets": [
      {
        "name": "all",
        "filters": {
          "all_nodes": true,
          "all_virtual_nodes": true,
          "all_parameters": true,
          "all_edges": true
        }
      }
    ],
    "outputs": [
      {
        "name": "all",
        "type": "Memory",
        "metric_set": "all"
      },
      {
        "name": "all-hdf5",
        "type": "HDF5",
        "filename": "outputs.h5",
        "metric_set": "all"
      }
    ]
  }
}

To run the model, use the pywr command line tool:

python -m pywr run simple1.json