Pywr, a Python library used by WaterStrategy, enables simulating resource allocation by representing a resource system as a network using 'Nodes' and 'Edges'. Resource allocation is driven by operating rules using 'Allocation Penalties', 'Constraints' and 'Parameters' and model outputs are captured and saved using 'Recorders'. Variations of model inputs can be specified and run in parallel using 'Scenarios'.

While the general concepts used to create a resource allocation simulation model in Pywr are similar to those of other tools, the use of terms can differ. In this section, we define key Pywr terms and their roles in simulation models.

Node

Nodes represent locations in the simulated water system where water is added, stored, used, consumed, or transmitted. There are different node types in Pywr to help you build your water system model; you can learn more about them in the Node types section. The data that define the physical characteristics and behavior of a node can be added directly to the node or indirectly by referring to a Parameter (described below).

Edge

To form a network, nodes are connected using links representing water conveyance. Pywr calls these 'Edges'. An edge has a starting and an ending node, and water flows from the starting node to the ending node. Pywr does not assign information to these connections (the edges), rather it assigns data to the source and destination nodes. All data required to simulate water management is stored on nodes, the edges only determine the direction of water flow. A Pywr modeler would say 'Pywr edges determine the network topology' which means 'the connections between nodes determine how water moves in the computer model'.

Constraint

Constraints can be set on various node types to help represent system behavior. For instance, a river node can have maximum and/or minimum flow values to represent the conveyance capacity. In Pywr, many nodes have the 'max_flow' and 'min_flow' attributes to set the upper and lower limits of the flow through the node if needed. The 'max_flow' attribute doesn't require that the flow through this node reach this value, but if the water volume and priority are sufficient, the model will try to meet the 'Max Flow.' Minimum flow constraints should be used carefully as they can result in model infeasibility if the minimum cannot be met.

Allocation Penalty or 'Cost'

Allocation penalties are node attributes that control water allocation priority. These are typically expressed as penalties or 'costs', and the model allocates water first to the node with the lowest penalty. If you prefer allocating by benefit, sending water to where it has the highest benefit first, you'll need to express your priorities in Pywr as negative costs (i.e., use negative numbers). In fact, both can be used together, so for example if 3 nodes have penalties -10, 2, 6, they will get water in that order (the node with a penalty of -10 gets water first, and the node with allocation penalty 6 gets water last).

Parameter

Parameters in Pywr provide a flexible and convenient way to provide inputs to Nodes. For example, a particular parameter type can be used to load inflow or demand data from a Microsoft Excel file. Parameters also offer a flexible and customizable way to define a system's operating rules (e.g., rules governing reservoir releases). Most model input data can be provided using parameters.

Recorder

Pywr Recorders are used to post-process results. By creating a recorder, you can observe and save simulation results. Some recorders enable aggregating results over time (e.g., from daily to annual) and space (e.g., water allocated to a group of nodes).

Scenario

In Pywr you can create and simulate scenarios with different input data on supply, demand or other changes. Water planners increasingly use long-term simulations with many scenarios to evaluate future changes or test possible interventions. Being able to quickly simulate many plausible future scenarios is one of Pywr's main benefits.

Note:

For further details, please refer to the open-access paper entitled: A water resource simulator in Python.

General Description

The catchment node is an another kind of input node with a fixed inflow. Catchment nodes are often used to represent river or other type of inflow into the system. Any flow defined on them has to flow into the system.

Ofthen inflow time series (e.g. Pywr dataframes) are defined on the flow attribute to represent catchment inflows however other parameters can also be used (e.g. constant, monthly profile etc...).

API Reference.

Primary Attributes

Examples

coming soon...

General Description

The proportional input node is intended for a simple case of where fixed ratio of flow is required to be distributed to multiple downstream routes. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The river node is a node in the river network, which may have multiple upstream nodes (i.e. a confluence) but only one downstream node. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The link node represents a link in the water system or other point of interest where a maximum or minimum flow constraint or an allocation priority are assigned. Please note in Pywr, Edges (Links) cannot be assigned flow constraintes and therefore link nodes are often used for this purpose. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The delay node is a node that delays flow for a given number of timesteps or days. This node will be used when the water propagation time cannot be ignored, compared to the selected time scale. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The RiverSplitWithGauge node is a split in the river network with a minimum residual flow (MRF). As per RiverSplit but by default creates another route in the underlying object to model a MRF. This route is such that the MRF is not part of forced ratios. The intent of this object is to model the case where a proportion of flow can be abstracted above the MRF (e.g. 90% of flow above MRF). API Reference.

Primary Attributes

Examples

coming soon...

General Description

Input nodes represent water inputs into the system.

At each time step an input node can provide as much water as set by the Max Flow attribute. However, unlike Catchment nodes which are required to release the volume of water that is defined in their Flow attribute, input nodes are not required to release any water unless they have a non-zero Min Flow.

Input nodes are often used to represent sources that are defined by yields. They are often used to represent groundwater yields.

API Reference.

Primary Attributes

Examples

coming soon...

General Description

The RiverSplit node is a split in the river network. It is intended for a simple case of where fixed ratio of flow is required to be distributed to multiple downstream routes. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The PiecewiseLink node is an extension of Node that represents a non-linear Link with a piece wise cost function. This object is intended to model situations where there is a benefit of supplying certain flow rates but beyond a fixed limit there is a change in (or zero) cost. API Reference.

This Node is implemented using a compound node structure like so:

        | Separate Domain         |
Output -> Sublink 0 -> Sub Output -> Input
       -> Sublink 1 ---^
       ...             |
       -> Sublink n ---|

This means routes do not directly traverse this node due to the separate domain in the middle. Instead several new routes are made for each of the sublinks and connections to the Output/Input node. The reason for this breaking of the route is to avoid an geometric increase in the number of routes when multiple PiecewiseLinks are present in the same route.

Primary Attributes

Examples

coming soon...

General Description

The storage node is a general node that can store water, which have a minimum and maximum volume restrictions. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The BreakLink node can be used to reduce the number of routes in a model.

For instance, in a model with form (3, 1, 3), i.e. 3 (A, B, C) inputs connected to 3 outputs (D, E, F) via a bottleneck (X), there are 3*3 routes = 9 routes.

A -->\ /--> D
B --> X --> E
C -->/ \--> F

If X is a storage, there are only 6 routes: A->X_o, B->X_o, C->X_o and X_i->D_o, X_i->E_o, X_i->F_o.

The BreakLink node is a compound node composed of a Storage with zero volume and a Link. It can be used in place of a normal Link, but with the benefit that it reduces the number of routes in the model (in the situation described above). The resulting LP is easier to solve. API Reference.

Primary Attributes

Examples

Pywr is a free and open-source Python language software library that allows building high quality (detailed and accurate) simulation models of water resource systems.

Pywr models run quickly on your computer or, in the case of WaterStrategy, on the cloud. They can represent small water resource systems, like a city’s water supply, or very large ones, like river basins that span several countries with hundreds of water users and infrastructure assets. Pywr can simulate short periods (like a few months) or longer ones (like 100 years) at a range of time steps (from daily to monthly).

Here's a summary of the Pywr modeling process:

1. Set up the model

First a spatial water system map and associated hydrological and water demand data are needed. WaterStrategy helps you create this network map of all the locations ('nodes') where water is entering the system (‘inflows’), where water is being used (‘water demands’), and where water is managed (locations of infrastructure). These nodes form a network connected by rivers, canals or pipelines (Pywr calls these ‘links’ or ‘edges’). Once you’ve set up your network map, you provide water supply and demand data (typically as time-series).

2. Run a simulation

When all the data is entered, including time-step and time-horizon, the model is ready to simulate (i.e., step through time and perform water accounting throughout the system). At the beginning of each time-step the computer begins by injecting water into all the inflow locations, then this water is routed down the network and allocated to the different water demand and infrastructure locations. This allocation process is performed with a computing technique called linear programing. After one time-step is finished, the model updates storages, records which locations got how much water, then continues to the next time-step until the end of the simulated time-horizon.

Each water demand node is assigned a priority to represent water allocation in the model. Each node has an associated penalty, and the allocation algorithm distributes water throughout the network to minimise the overall penalty. This simple approach allows for fast and maintainable simulations which have the flexibility to represent detailed and realistic water management rules.

3. Review results

Model outputs include how much water enters each location (node) and how much is stored, consumed or passes through it in each time-step. This allows tracking how infrastructure is being used, and whether cities, ecosystems, irrigation areas, power plants, etc. are getting enough water. Results create a detailed picture of how the water management system is working and how water benefits are distributed.

Initially models are poorly parameterised and produce inaccurate predictions (the 'garbage in, garbage out' phase). Over time however, as the model is improved ('calibrated'), it can become a valuable digital twin to help operate or plan a water system. The tool helps your organisation rapidly and inexpensively evaluate the impacts of potential future water changes and interventions, and make good decisions.

Good luck!

General Description

The MultiSplitLink node is an extension of PiecewiseLink that includes additional slots to connect from.

Conceptually this node looks like the following internally,

         / -->-- X0 -->-- \
A -->-- Xo -->-- X1 -->-- Xi -->-- C
         \ -->-- X2 -->-- /
                 |
                 Bo -->-- Bi --> D

An additional sublink in the PiecewiseLink (i.e. X2 above) and nodes (i.e. Bo and Bi) in this class are added for each extra slot.

Finally a mechanism is provided to (optionally) fix the ratio between the last non-split sublink (i.e. X1) and each of the extra sublinks (i.e. X2). This mechanism uses AggregatedNode internally. API Reference.

Notes: Users must be careful when using the factor mechanism. Factors use the last non-split sublink (i.e. X1 but not X0). If this link is constrained with a maximum or minimum flow, or if it there is another unconstrained link (i.e. if X0 is unconstrained) then ratios across this whole node may not be enforced as expected.

Primary Attributes

Examples

coming soon...

General Description

The AggregatedStorage node is an aggregated sum of other Storage nodes

This object should behave like Storage by returning current flow, volume and current_pc. However this object can not be connected to others within the network. API Reference.

Notes: This node can not be connected to other nodes in the network.

Primary Attributes

Examples

coming soon...

General Description

The reservoir node is a subclass of storage node with additional functionality to represent evaporation and precipitation. API Reference.

Primary Attributes

Examples

coming soon...

General Description

The output node (API Reference) is a general output at any point from the network. Output nodes remove water from the system.

Output nodes are required at the end of a river and in this use case generally do not have an allocation penalty or max_flow assigned.

Output nodes are also used to represent consumptive water demands. In this use case, they tend to have negative allocation penalties assigned so that the linear program allocates water to them as well as a max_flow which can be either a constant or a parameter representing the water demand.

Primary Attributes

Examples

coming soon...

General Description

The SeasonalVirtualStorage node is a virtual storage node that operates only for a specified period within a year.

This node is most useful for representing licences that are only enforced during specified periods. The reset_day and reset_month parameters indicate when the node starts operating and the end_day and end_month when it stops operating. For the period when the node is not operating, the volume of the node remains unchanged and the node does not apply any constraints to the model.

The end_day and end_month can represent a date earlier in the year that the reset_day and and reset_month. This situation represents a licence that operates across a year boundary. For example, one that is active between October and March and not active between April and September.API Reference.

Primary Attributes

Examples

coming soon...

General Description

The AnnualVirtualStorage node is a virtual storage which resets annually, useful for licences. API Reference.

Primary Attributes

Examples

coming soon...

Scenarios in WaterStrategy allow users to simulate and explore various water management strategies by adjusting different elements of a model. They provide a framework for understanding how changes in inputs, assumptions, or data might influence outcomes under different conditions.

WaterStrategy offers two types of scenarios to address various needs in water management modeling:

1. WaterStrategy Scenarios: This type is used when users need to adjust specific behaviors, parameters, or data at a localized or smaller scale. These scenarios are ideal for cases where only certain elements of the model need to be tweaked without altering the entire dataset. It allows for targeted modifications, making it easier to test the effects of individual changes within the system.

2. Pywr-scenarios: This scenario type is designed to handle more complex cases, particularly those involving uncertainty. It specializes in combining data across multiple scales, allowing for a comprehensive assessment of different variables. This approach is especially useful when working with uncertain inputs or when modeling future conditions, as it enables you to explore how different combinations of data and assumptions may impact the outcomes.

All the Parameter subclasses in pywr are descended from a common base class.

1. To log in go to https://hydra.org.uk/login (Hydra is the secure server where we currently host WaterStrategy)

2. Enter your WaterStrategy username and password

3. Click on 'Login'

If you forgot your password, click on the 'Forgot password' link.

Please note: Allow cookies when prompted.

Project: Folder that contains related networks, also can contain other project folders (sub-projects).

-Each project folder displays the amount of networks and sub-project folders within it.

Network: Model.

1. At the interface home page, select the “Training Material” project.

2. Select the Demo 1 network.

-Inside the network, at the top of the page, you will see a bar that looks like this below.

-The “Home” and “My Projects” tabs will bring you back to the interface homepage.

-“Documentation and Training” takes you to the interfaces tutorial videos and written instructions page.

-The “Favourites” tab allows you to bookmark projects, networks, and scenarios. It also gives the ability to go to recently accessed and recently modified projects and networks.

-“Back to ‘Training Material’” brings you back to the Training Material project folder.

-The green play button runs a model.

-The wrench button provides access to advanced network utilities, such as importing or exporting network data.

-The downwards arrow into the rectangle button is for downloading the model, this is used to run offline or send to someone.

-The three lines are “View Network Data”.

1. Click on “View Network Data”.

-In “Details” you can change the name of the network.

-Sometimes requires exiting network to update.

-In “Inputs” you can change the start, end, and timestep of your model.

-D=day, M=month, Y=year for timestep.

1. Click on the wrench icon to go to “Settings”.

Display labels- displays node names

Link direction- shows flow direction of links

Show Tooltips- displays node information when hovering over it

Auto Hide Sidebar- hides sidebar when not using it

Always Categorise Attributes by Type- Within a node, will group attributes as scalars, descriptors, etc.

1. Click on the “i” to go to “Info”.

-You can see your “Network ID” and other information.

1. Close the sidebar and go to the scenario section on the left side of the page.

-Scenarios are variations of input data, hydrology, etc. within a model.

-Common to make multiple scenarios within a model.

Button 1(left)- Clone scenario

Button 2- Edit Scenario

Button 3- Delete scenario

Button 4- Refresh scenario list

Button 5- Bookmark scenario

Button 6(right)- Compare scenarios

-To make a new scenario, clone a pre-existing scenario giving it a new name, once created change model input data as desired.

1. Click the “Run a Model” button.

-Keep the baseline scenario.

-Keep all other defaults.

1. Click “Submit”.

-In the “Runs” section on the left side of the page you will see your new run and past runs.

-Yellow=Run in queue

-Blue=Run in progress

-Green=Successful run

-Red=Run failed

1. Click “Build” below the “Run” section.

-This provides all the nodes and links needed to build a model.

-After inserting a node, data needs to be entered.

1. Click “Search” below the “Build” section.

-This allows you to easily find nodes and links in large models.

The bomb button in the upper left hand corner of the map allows you to expand your model to make it less crowded if needed.

Map- Shows model

Resources- Can view your nodes, links, and groups

Metrics- Provides functionalities for aggregation of model outputs

Custom Rules- Custom operating rules

Parameters- Add parameters not included in pywr

Recorders- Add recorders not included in pywr

Members- Shows the members who have to access to the model and the permissions they possess, can also add members in this tab and choose the permissions they have

Analysis- Comparing nodes and links within scenarios

WaterStrategy isn't required to run a Pywr model; it is there to help make it easier to use Pywr models. If you have a Pywr model input file (they are called 'JSON' files), and you have the required Python and Pywr libraries installed on your computer, you can run your Pywr model without WaterStrategy (Note: Python skills are required). Equally, if you have an existing Pywr model (a JSON file), you can import it into WaterStrategy.

This page shows how to export models from WaterStrategy into a Pywr JSON files and how to import existing Pywr models (JSON files) into WaterStrategy

Exporting and Importing Models

Export Pywr files

This section uses the 'demo one network' provided when you create an account.

First click the download button.

Then, we are going to choose our format.

Choose the Hydra JSON format first. If you want to enable line breaks that makes your code or text easier to read. If it's a large file you can zip it.

Submit it.

Next, download the Pywr JSON format.

Then, you can find the two files in the folder you chose to save them in.

Import Pywr files

Let's see how to import Pywr files.

First, click the 'Create Project' to create a project folder in your Water Strategy account.

Name the project and click 'Add'.

Click the created project.

Click 'Create Network'.

Select 'Hydra JSON'.

Click 'Choose File'.

Choose the Hydra JSON file.

Select the template.

Click 'Submit'.

Then, you can find the network is imported.

To import the Pywr JSON file, you can follow these steps.

Click 'Create Network' again.

Choose the 'Pywr JSON'.

Click 'Choose File'.

Choose the Pywr JSON file.

Choose the template.

For projection, you can choose 'None', 'UK', or 'World'. In this case, we will choose the 'World'.

Click 'Submit'.

Finally, you can the imported network here.

In WaterStrategy, users have the flexibility to manage large and complex datasets more efficiently by loading data from external files as DataFrameParameter using the "url" keyword, rather than embedding all the data directly into the interface. The file formats include:

• CSV

• Excel

• HDF5

Note: Among the previous options, Excel files have the slowest performance while HDF5 files have the best performance and are preferred for large datasets.

To upload a file in WaterStrategy, navigate to your project and click on the Files tab. From there, click Choose Files and select the file you want to upload and click .

This will add the file to your project, making it available for use across all networks within the project.

Once the files have been uploaded, they will be displayed in the Files tab within your project. From there, you can easily view, manage, and share them across all networks in the project.

WaterStrategy reports errors when there is either a technical fault, or the model has been incorrectly configured. Learning how to understand and use a model error report to find a problem in a model is an important and essential modelling skill.

This chapter gives an example of how to read an error report to find the part of a model that leads to the error.

How to get the error report

When a run fails, you will see the run turn red in runs section.

Click the red run bar and you will get an overview of the run, including the error report.

Scroll to the end of the report. This is where the run will reports its error.

For this run, it can be found that a monthly profile has not been entered correctly.

In some cases, more detail will be given about an error within the run report. It is important to look back through the run logs to see if there are any clues as to the issue.

Upon scrolling up we see 'CRITICAL'. This is an indication that an error has been recognized. In the same line, it indicates where the error is.

The input 'evaporation' of the 'Example reservoir' node is incorrect.

We can edit the 'evaporation' parameter to solve this problem.

There are 13 values in the monthly profile, we need to remove the value that does not belong. In this case '3.14' was not meant to be in the monthly profile.

Save the parameter and run this model again.

Now the model has run successfully.

Creating a new Project and Network

1. In the interface homepage, click “Create Project” in the upper right hand corner.

2. Type your project name and select “Add”.

3. Enter your new project.

4. Click “Create Network” on the right hand side.

5. Choose the “Manual” tab.

6. Enter a network name.

7. Choose either of these two pywr templates.

-The other templates are for other modeling systems such as power systems.

1. Choose “Use Map” to have the world map displayed for model building.

2. Click “Submit”.

3. Enter the created network.

4. Toggle and zoom to an area along the Nile.

1. Select the “Build” dropdown.

1. Drag a catchment, a link, and two output nodes into the model as seen below.

-The second output node (off-river) will be used as a water abstraction node.

-Notice that the catchment node is upriver, and the output node is downriver.

(the Nile flows north in this part and overall)

1. Using the “Links” feature, connect the nodes in the direction of the flow.

-This is done by clicking the upflow node first and the downflow node second.

Watch the video or follow the text below. WaterStrategy accounts are made on https://hydra.org.uk/register ('Hydra' is the name of our web server).

Creating an Account

1. On the WaterStrategy webpage select "LOGIN" in the upper right corner.

1. Select "Create an account" at the bottom of the webpage "Login" brings you to.

2. In the register page, enter your email, first name, last name, organization type, organization, country or region, create a password, select "I'm not a robot", and check the three boxes.

3. Then select "Register".

4. An email confirmation will be sent to you to confirm your account. Make sure to also check your spam folder.

5. Your account has been created.

Login

1. To log in, visit https://hydra.org.uk/login or use the WaterStrategy webpage “Login”

1. Enter your email and password and check the three bottom boxes again. Choose "Remember Me" if you wish.

2. Then select "Login".

3. You will be at the Water Strategy interface homepage.

Water input nodes are the mechanism by which water can be entered into the system. Here, we introduce the three most commonly used nodes for water input.

Projects: These are like folders that group Sub-projects and Networks.

Networks: Each models with a unique network is called a 'Network' in WaterStrategy.

Person Icon: Indicates you solely have access to the project or network.

People Icon: Indicates multiple people have access to a project or network.

Creator: Created the project or network.

Shared Directly: The project or network was specifically shared to a user.

Inherited from: (“Project Name”): The user has access to this sub-project or network from being shared a project that encases it.

1. In order to share a project, enter the project and click on the members tab.

1. Type in the email of the recipient’s account you would like to share to.

There are two permissions you can choose to grant a recipient.

Allow users to re-share?: Allows them to share the project and the projects/networks inside with others.

Allow users to edit the Project?: Allows them to edit the projects/networks inside the project.

1. Select “Invite” after choosing permissions.

Below you can view who the project has been shared with, manage who has been shared with, view their permissions, and see how they received access.

There are permissions you can choose to grant a recipient.

Allow users to re-share?: Allows them to share the network with others.

Allow users to edit the Project?: Allows them to edit the network.

Clone Network: Creates a duplicate network. Prevents changes to pre-existing network. Has the options below if “Cloned Network” is chosen.

Include Results in new network?: Include run results in cloned network.

Include all Scenarios?: Include the created scenarios in cloned network.

Network Name: Create name of cloned network.

1. Type in the email of the recipient’s account you would like to share to.

2. Click “Share” after choosing permissions.

To understand how a water system performs today and to evaluate the impacts of future changes, planners build water resource system models.

Water resources systems can be small, like a city and its water supply sources, or large, like a country with many different rivers, water infrastructure assets and water users. Whether you're trying to evaluate the reliability of current sources, or evaluating new interventions under plausible future conditions, such a computer model helps track water throughout the system (spatially) and over time.

Given data on hydrological flows and climate, water demands and use, and water management rules and allocation, a water system model outputs water flows and volumes at each modeled location and time-step. When these results are aggregated, they provide an accurate picture of how different water interventions (changes to water policies or infrastructure) might perform.

WaterStrategy's Discord channel is regularly monitored, offering support from developers and users. You can report bugs or request new features there. Sign up via this link:

https://discord.gg/bQVmgkFcf7

Alternatively, you can email support@waterstrategy.org

The water storage node type allows users to build different reservoirs with different operation modes. Below are the most used water storage nodes:

This table introduces the most commonly used Pywr node types:

Pywr Node types can also be further sub-divided into 6 categories: Water Input, Water Transport, Water Storage, Water Output, Hydropower, and Others. You can find more details about these groupings of nodes and nodes types in the sub-sections of the 'Node Types' section.

More details

An overview of nodes in Pywr can be found here. The full list of built-in nodes in Pywr can be found here.

The water transport node type allows users to define how water flows through different nodes according to real-world conditions. Below are the most used water transport nodes:

General Description

The RiverGauge node is a river gauging station, with a minimum residual flow (MRF). API Reference.

Primary Attributes

Examples

coming soon...

The hydropower node type allows users to define relevant details of turbines in the dams and calculate hydropower generation.

General Description

The RollingVirtualStorage node is a rolling virtual storage node useful for implementing rolling licences. .

Notes:

TODO: The cost property is not currently respected. See issue #242.

Primary Attributes

Examples

coming soon...

General Description

The VirtualStorage node is a virtual storage unit. .

Notes:

TODO: The cost property is not currently respected. See issue #242.

Primary Attributes

Examples

coming soon...

General Description

The turbine node can represent a turbine of a hydropower station. It calculates the flow required to generate a particular hydropower production target in each time step. .

Primary Attributes

Examples

coming soon...

Output nodes are locations where water leaves the system. Below are the most used water output nodes:

Allocation penalties are node attributes that allow Pywr to simulate water allocation. They can also be called 'allocation priorities' or 'costs'.

A low penalty will have the highest allocation priority, a high number has the lowest.

So for example if three nodes have priorities 100, 3, and -2, then the node with -2 gets its water first, then 3, then 100.

Here are some questions about water allocation penalties you may have, and some short answers:

1. Why and how does Pywr allocate water like this? At each time step Pywr's allocation algorithm (a linear program), minimizes the allocation penalty of the entire system. Flow through nodes is multiplied by their respective allocation penalties. This technique has been in use since the 1950s by energy, transport and water planners and by logistics companies. They all want systems that operate cheaply, so they typically used financial operating costs as the penalty term. This makes sense, it allows using the model to balance a supply-demand network at the lowest cost.

2. Do you find the idea of a negative penalty confusing? If so, think of a negative penalty as a negative cost, what's that? a benefit! So if you'd like to allocate water to where it generates the most benefits in your Pywr model, you'll be using negative penalties. In this case, rather than calling these node attributes allocation penalties or costs, you could refer to them as allocation priorities. In this case a node with an allocation priority of -99 will get water long before -10. As shown in the example in the third sentence above, both negative and positive allocation penalties can be used in the same model.

3. Do allocation penalties have some special meaning? No, they don't. They are just there to help your model allocate water in a way that make sense to you, the water manager and planner.

4. How do I know if i've set water allocation penalties correctly? If your model is allocating water appropriately under normal conditions, but also during floods and droughts, then you have set appropriate penalities. Congratulations! your model is on its way to becoming 'well-calibrated'.

5. If I make a big change to my model, like add a large new infrastructure, or add a new water user-type, do i need to change the penalties in my model? Yes, some penalties in your model might need some refinement, depending on how significant the change is. Try and see.

6. Can i use any numbers for penalties? like, if my model has 2 nodes, can i use negative and positive one million as my penalties? Yes, but it's a bad idea. Use numbers that are as close together as you can. If not, as your model grows, you could run out of available penalties and your model will begin to make round-off errors. However, if you use penalities that are too similar, your model might be insensitive to them (i.e., not consider them adequately when simulating allocations). With a bit of experience you'll learn to set penalities that work well. To gain that experience, try changing penalties and see how it affects your model's outputs.

Finally, we provide a few more technical details about penalities:

• Reservoir and storage nodes have allocation penalties assigned to them. A negative penalty means the reservoir will tend to accumulate water, unless a lower penalty on another node results in the reservoir storage having lower priority.

• Allocation penalties can be constants (constant parameters) or profiles (monthly, daily, weekly) that change over time. Also, allocation penalties can have different levels defined by different control curves based on the reservoir volume. Despite the reservoir and storage allocation penalties influencing water storage, releases from those nodes will result from a penalty balance in the system considering allocation penalties downstream as the algorithm attempts to minimse the overall system penalty at each time step.

General description

A loss link allows for the definition of a fixed proportional loss of flow that goes through this node. Loss links are often used to represent potable water treatment works which incur some process losses.

The Max and Min flow attributes that are defined are applied to the net output after losses.

The node itself records the net output in its flow attribute (which would be used by any attached recorders).

Primary Attributes

Example

In this example 10% of the gross amount of water flowing into the node is lost.

WaterStrategy Scenarios provide a tool for making targeted adjustments to specific elements within a water management model. These scenarios are particularly useful when you want to experiment with localized changes to parameters, behaviors, or data in a flexible and controlled way.

When a WaterStrategy Scenario is created, it acts as a fork of an existing network model. The original network is assigned to the baseline scenario, which represents the default or starting conditions of the system. From this baseline, a WaterStrategy Scenario allows for precise modifications—whether it’s changing data inputs or adjusting parameters that define the behavior of key elements within the system.

This ability to modify certain aspects of the model while leaving the rest unchanged makes WaterStrategy Scenarios ideal for testing the impact of individual changes. For instance, you can alter reservoir operation rules or modify demand forecasts without needing to reconstruct the entire model. This focused approach helps users quickly assess how specific modifications influence outcomes for refining water management strategies.

Creatin a WaterStrategy Scenario

Begin by clicking on the Clone a Scenario icon.

Select the scenario you wish to clone and name your scenario

pywr scenarios are compatible with the following parameters:

Pywr Scenarios offer a more advanced and comprehensive approach to water management modeling, particularly when working with uncertainty and asessing various combinations of data and system behaviors and data inputs. Unlike WaterStrategy Scenarios, which focus on localized adjustments, Pywr Scenarios allow you to experiment with a wide range of possibilities by varying multiple inputs and combinations simultaneously.

In Pywr Scenarios:

• Users can define multiple scenarios, with each scenario containing multiple variations (or sizes).

• The system will simulate all combinations of these variations unless a specific combination is selected for simulation.

For example, if two Pywr Scenarios are defined, each with three variations (size = 3), the total number of simulations will be 9 (3 x 3). This approach enables users to explore a wide range of potential outcomes and interactions between different factors in the model.

1. Activating Pywr Scenarios

In a Network, click on View Network Data icon

This will open the right panel. In the section Inputs, type "scenarios" and click on Add an Input icon

A window will be displayed, type "scenarios", select the scenarios attribute and click Save as shown in the following image

A new window will pop up, select PYWR_SCENARIOS and click Save

2. Creating pywr-scenarios

Once the scenario customization panel is open, you can define as many Pywr Scenarios as needed. To create a new Pywr Scenario, follow these steps:

Enter a Name for the Pywr-Scenario and specify the Size (number of variations).

The Ensembles attribute is optional and helps keep track of specific index scenarios within the Pywr Scenario

After creating the pywr-scenarios, the system will display the following information:

Clicking on the JSON tab will display the automatic JSON version of the Pywr-Scenario definition

General Description

Initialize self. See help(type(self)) for accurate signature.

Attributes

Example

coming soon...

General Description

The AggregatedNode node is an aggregated sum of other Node nodes.

This object should behave like Node by returning current flow. However this object can not be connected to others within the network. .

Notes: This node can not be connected to other nodes in the network.

Primary Attributes

Examples

coming soon...

General Description

A simple parameter defining a constant value.

Attributes

Example

The others node type allows users to get special-designed computation results of the water resource system.

General Description

Base parameter providing an index method.

Attributes

Example

coming soon...

Paramters are functions that return a value in the model at each time-step. These values can be a constant, based on time (e.g., on the day or month), a calculation based on the time step's reservoir storage and many other calculations. Custom parameter can also be written in Python.

This page describes (most of) the parameter types supported by Pywr. An overview of parameters in Pywr can be found . The full list of built-in Pywr parameters are found .

1. Creating a Parameter

In a Network, click the 'Parameters' Tab:

Next to the 'Parameters-Type Categories' section, click the '+' button and select 'PYWR_PARAMETER'.

A text-input will appear. Enter the name of your parameter:

Modify the parameter as required in the JSON editor provided:

2. Parameter editors in WaterStrategy

To make parameter modifications simpler, WaterStrategy offers editors for commonly used Parameters, such as Monthly Profile parameters, with pre-populated default values, and graphical editors to make entering of data simpler.

Example parameter editor

In the Parameters Tab, when adding a new Parameter, select 'PYWR_PARAMETER_MONTHLY_PROFILE' as shown:

Note that the edior which appears will show a JSON tab, but also a Plot and Table tab. Modifying the data in the table will automaticall update the data in the JSON as shown:

These changes automatically update the JSON:

General Description

A Scenario varying Parameter. The values in this parameter are constant in time, but vary within a single Scenario.

Attributes

Example

coming soon...

General Description

A Scenario varying IndexParameter. The values in this parameter are constant in time, but vary within a single Scenario.

Attributes

Example

coming soon...

General Description

Parameter that takes maximum of another Parameter and constant value (threshold).

This class is a more efficient version of AggregatedParameter where a single Parameter is compared to constant value. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that takes negative of another Parameter. API Reference

Attributes

Example

coming soon...

{

}

General Description

The weekly profile contains 52 weeks per year. The last week of the year will have more than 7 days, as 365 / 7 is not whole. API Reference

Attributes

Example

{
    type: 'weeklyprofile',
    values: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ... ]
}

General Description

A collection of IndexParameters

This class behaves like a set. Parameters can be added or removed from it. Its index is the index of it’s child parameters aggregated using a aggregating function (e.g. sum). API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that takes maximum of the negative of a Parameter and constant value (threshold). API Reference

Attributes

Example

coming soon...

{

}

General Description

A collection of IndexParameters. This class behaves like a set. Parameters can be added or removed from it. It’s value is the value of it’s child parameters aggregated using a aggregating function (e.g. sum). API Reference

Attributes

Example

{
	"type": "AggregatedParameter",
	"agg_func": "product",
	"parameters": [
		"Baseline demand",
		"Control curve demand factor"
	]
}

In this case Aggregated Parameter is multipliying two parameters togther

• Baseline demand

• Control curve demand factor

This example shows a Baseline demand being multiplied by a factor that reduces demand based on a reservoir control curve. You can click on the each of these Parameters to see how they are defined.

General Description

Parameter which provides a daily profile per scenario.

This parameter provides a repeating annual profile with a daily resolution. A different profile is returned for each member of a given scenario. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that offsets another Parameter by a constant value.

This class is a more efficient version of AggregatedParameter where a single Parameter is offset by a constant value. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that divides one Parameter by another. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that takes minimum of another Parameter and constant value (threshold).

This class is a more efficient version of AggregatedParameter where a single Parameter is compared to constant value. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter which provides a daily profile.

The daily profile returns a different value based on the month of the current time-step. API Reference

Attributes

Example

{
    type: 'dailyprofile',
    values: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ... ]
}

General Description

Parameter that takes minimum of the negative of a Parameter and constant value (threshold). API Reference

Attributes

Example

coming soon...

{

}

General Description

Time varying parameter using an array and Timestep.index with multiplicative factors per Scenario.

Values is the baseline timeseries data that is perturbed by a factor. The factor is taken from factors which is shape (scenario.size, 12). Therefore factors vary with the individual scenarios in scenario and month. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter which interpolates a daily profile using a radial basis function (RBF).

The daily profile is computed during model reset using a radial basis function with day-of-year as the independent variables. The days of the year are defined by the user alongside the values to use on each of those days for the interpolation. The first day of the years should always be one, and its value is repeated as the 366th value. In addition the second and penultimate values are mirrored to encourage a consistent gradient to appear across the boundary. The RBF calculations are undertaken using the scipy.interpolate.Rbf object, please refer to Scipy’s documentation for more information. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that provides a monthly profile per scenario.

Behaviour is the same as MonthlyProfileParameter except a different profile is returned for each ensemble in a given scenario. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter which provides a uniformly reducing value from one to zero.

This parameter is intended to be used with an AnnualVirtualStorage node to provide a profile that represents perfect average utilisation of the annual volume. It returns a value of 1 on the reset day, and subsequently reduces by 1/366 every day afterward. API Reference

Attributes

Example

coming soon...

{

}

General Description

Base class for parameters returning one of two values depending on other state. API Reference

Attributes

Example

coming soon...

{

}

General Description

Returns one of two values depending on current volume in a Storage node. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter that provides a weekly profile per scenario

This parameter provides a repeating annual profile with a weekly resolution. A different profile is returned for each member of a given scenario. API Reference

Attributes

Example

coming soon...

{

}

General Description

Returns one of two values depending on the year of the current timestep. API Reference

Attributes

Example

coming soon...

{

}

General Description

Returns one of two values depending on the ordinal of the current timestep. API Reference

Attributes

Example

coming soon...

{

}

General Description

Returns one of two values depending on previous flow in a node. API Reference

Attributes

Example

coming soon...

{

}

General Description

Returns one of two values depending on the value of a Parameter. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter value is equal to the interpolation of another parameter. API Reference

Attributes

Example

coming soon...

{

}

General Description

Generic interpolation parameter that uses a node’s flow at the previous time-step for interpolation. API Reference

Attributes

Example

coming soon...

{

}

General Description

Base class for all Parameters that rely on a the attached Node containing a control_curve Parameter. API Reference

Attributes

Example

coming soon...

{

}

General Description

Parameter which provides a monthly profile. The monthly profile returns a different value based on the month of the current time-step. API Reference

Attributes

Example

{
    type: 'monthlyprofile',
    values: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
}

Water Strategy offers an alternative way to work with Monthly Profiles.

General Description

Timeseries parameter with automatic alignment and resampling. API Reference

Attributes

Example

{
	"type": "DataFrameParameter",
	"url": "Inflows_mm3_day.csv",
	"column": "Catchment River 1",
	"index_col": "timestep",
	"parse_dates": true
}

General Description

This Parameter reads array data from a PyTables HDF database.

The parameter reads data using the PyTables array interface and therefore does not require loading the entire dataset in to memory. This is useful for large model runs. API Reference

By storing HDF5 files in the "fixed" format, users can achieve optimal data access speeds, making HDF5 an effective tool for Pywr-scenarios that use DataFrames as parameters, where fast data retrieval is crucial. HDF5 files are read as a dictionary, where each key represents a pandas DataFrame. For example, the structure of an inflows.h5 file might contain three keys, each representing a different river. Each key holds three time series that can be assigned to a Pywr scenario of size 3.

If using h5 file DataFrame for running pywr-scenarios, please refer to pywr-scenarios section in order to activate this feature

Note: The size of pywr-scenarios must match the number of keys in the h5 file

Attributes

Example

{
	"key": "Catchment River 1",
	"scenario": "Climate Change",
	"type": "DataFrameParameter",
	"url": "inflows.h5",
	"index_col": "timestep",
	"parse_dates": true
}

General Description

Time varying parameter using an array and Timestep.index

The values in this parameter are constant across all scenarios.

Attributes

Example

coming soon...

General Description

Parameter which uses an IndexParameter to index an array of Parameters.

An example use of this parameter is to return a demand saving factor (as a float) based on the current demand saving level (calculated by an IndexParameter).

Attributes

Example

Please see how the Reservoir control curve parameter is defined.

General Description

A control curve Parameter that interpolates between three or more values.

Return values are linearly interpolated between control curves, with the first and last value being 100% and 0% respectively.

Attributes

Example

coming soon...

General Description

Parameter value is equal to the quadrature of the interpolation of another parameter.

Attributes

Example

coming soon...

General Description

Generic interpolation parameter that returns a value based on a Reservoir or Storage nodes current (time step) volume. The

parameter uses an array (table) of Reservoir Volumes and corresponding values. In this case the associated values are the corresponding Reservoir Area for a given Volume.

Attributes

Example

The following Json shows an example Area vs Volume rating cure for a reservoir. This could be used to define the Area attribute of a Storage or Reservoir node.

The Json represents the table below:

When plotted it looks like this:

Below is an example Area rating table

When plotted it looks like this

General Description

Returns one of two values depending on a Recorder value and a threshold.

Attributes

Example

coming soon...