Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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...).
flow
The amount of water supplied by the catchment node at each timestep
Required, defaults to 0 if not entered.
coming soon...
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.
allocation penalty
The cost per unit flow via the node
Optional
factors
The factors to force on the additional splits. Number of extra_slot is assumed to be one less than the length of factors (as per pywr.nodes.MultiSplitLink documentation)
Optional
slot_names
The identifiers to refer to the slots when connect from this Node. Length must be one more than the number of extra slots required
Optional
flow
The amount of water supplied by the catchment each timestep
Optional
coming soon...
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.
allocation penalty
The cost per unit flow via the node
Optional
max_flow
The maximum flow constraint on the node
Optional
min_flow
The minimum flow constraint on the node
Optional
coming soon...
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.
allocation penalty
The cost per unit flow via the node
Optional
timesteps
Number of timesteps to delay the flow
Optional
days
Number of days to delay the flow. Specifying a number of days (instead of a number of timesteps) is only valid if the number of days is exactly divisible by the model timestep delta
Optional
initial_flow
Flow provided by node for initial timesteps prior to any delayed flow being available. This is constant across all delayed timesteps and any model scenarios. Default is 0.0
Optional
coming soon...
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.
allocation penalty
The cost per unit flow via the node
Optional
max_flow
The maximum flow constraint on the node
Optional
min_flow
The minimum flow constraint on the node
Optional
coming soon...
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.
mrf
The minimum residual flow (MRF) at the gauge
Required
mrf_cost
The cost of the route via the MRF
Required
cost
The cost of the other (unconstrained) route
Required
factors
The factors to force on the additional splits. Number of extra_slot is assumed to be one less than the length of factors (as per MultiSplitLink documentation)
Required
slot_names
The identifiers to refer to the slots when connect from this Node. Length must be one more than the number of extra slots required
Required
coming soon...
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.
Allocation Penalty
The alllocation cost per unit flow via the node
Optional
Max Flow
The maximum flow constraint on the node
Optional
Min Flow
The minimum flow constraint on the node
Optional
coming soon...
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.
This table introduces the most commonly used Pywr node types:
Input Node
Input nodes represent water inputs into the system.
Catchment Node
Catchment nodes are often used to represent river or other type of inflow into the system.
Proportional Input Node
Proportional input node is intended for a simple case of where fixed ratio of flow is required to be distributed to multiple downstream routes.
Link Node
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.
River Node
River node is a node in the river network, which may have multiple upstream nodes (i.e. a confluence) but only one downstream node.
Delay Node
These delay flow for a given number of timesteps or days. This is used when flow propagation time cannot be ignored, for example because time-steps are relatively short.
Storage Node
Storage node is a general node that can store water (like dams or aquifers), which have a minimum and maximum volume restrictions.
Reservoir Node
Reservoir node is a type of storage node with additional functionality to represent evaporation and precipitation.
Output Node
Output nodes are locations where water leaves the system.
Loss Link Node
Loss link allows for the definition of a fixed proportional loss of flow that goes through this node.
Turbine Node
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.
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.
An overview of nodes in Pywr can be found here. The full list of built-in nodes in Pywr can be found here.
The PiecewiseLink node is an extension of Node that represents a non-linear 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. .
This Node is implemented using a compound node structure like so:
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.
coming soon...
The water storage node type allows users to build different reservoirs with different operation modes. Below are the most used water storage nodes:
allocation penalty
The cost per unit flow via the node
Optional
max_flow
The maximum flow constraint on the node
Optional
min_flow
The minimum flow constraint on the node
Optional
allocation penalty
The cost per unit flow via the node
Optional
min_volume
The minimum volume of the storage. Defaults to 0.0
Optional
max_volume
The maximum volume of the storage. Defaults to 0.0
Required, defaults to 0 if not entered
initial_volume, initial_volume_pc
Specify initial volume in either absolute or proportional terms. Both are required if max_volume is a parameter because the parameter will not be evaluated at the first time-step. If both are given and max_volume is not a Parameter, then the absolute value is ignored
One is required
area, level
Optional float or Parameter defining the area and level of the storage node. These values are accessible through the get_area and get_level methods respectively
Optional
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.
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.
allocation penalty
The cost per unit flow via the node
Optional
conversion_factor
The conversion between inflow and outflow for the node
Optional
max_flow
The maximum flow constraint on the node
Optional
min_flow
The minimum flow constraint on the node
Optional
prev_flow
Total flow via this node in the previous timestep
Optional
The RiverGauge node is a river gauging station, with a minimum residual flow (MRF). API Reference.
mrf
The minimum residual flow (MRF) at the gauge
Required
mrf_cost
The cost of the route via the MRF
Required
cost
The cost of the other (unconstrained) route
Required
coming soon...
The reservoir node is a subclass of storage node with additional functionality to represent evaporation and precipitation. API Reference.
allocation penalty
The cost per unit flow via the node
Optional
min_volume
The minimum volume of the storage. Defaults to 0.0
Optional
max_volume
The maximum volume of the storage. Defaults to 0.0
Required, otherwise defaults to 0
initial_volume, initial_volume_pc
Specify initial volume in either absolute or proportional terms. Both are required if max_volume is a parameter because the parameter will not be evaluated at the first time-step. If both are given and max_volume is not a Parameter, then the absolute value is ignored
One is required
area, level
Optional float or Parameter defining the area and level of the storage node. These values are accessible through the get_area and get_level methods respectively
Optional
evaporation, precipitation
Evaporation and precipitation rates (length/day)
Optional
unit_conversion
Conversion factor to convert precipitation and evaporation to required length/day units
Optional, default is 0.001 to convert mm/day for use with km2 reservoir area
evaporation penalty (evaporation cost)
Allocation penalty set on the evaporation output
Optional, defaults to -999
coming soon...
Output nodes are locations where water leaves the system. Below are the most used water output nodes:
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:
The AggregatedStorage node is an aggregated sum of other 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. .
Notes: This node can not be connected to other nodes in the network.
coming soon...
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..
coming soon...
model
`Model` instance
Required
name
str
Required
storage_nodes
The Storage objects which to return the sum total of
Required
reset_day
The day of the month (0-31) when the node starts operating and its volume is reset to the initial value or maximum volume.
Required
reset_month
The month of the year (0-12) when the node starts operating and its volume is reset to the initial value or maximum volume.
Required
reset_to_initial_volume
Reset the volume to the initial volume instead of maximum volume each year (default is False)
Required
end_day
The day of the month (0-31) when the node stops operating
Required
end_month
The month of the year (0-12) when the node stops operating
Required
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.
allocation penalty
The cost per unit flow via the node
Optional
max_flow
The maximum flow constraint on the node
Optional
min_flow
The minimum flow constraint on the node
Optional
coming soon...
The VirtualStorage node is a virtual storage unit. API Reference.
Notes:
TODO: The cost property is not currently respected. See issue #242.
allocation penalty
The cost per unit flow via the node
Optional
nodes
List of inflow/outflow nodes that affect the storage volume
Required
min_volume
The minimum volume the storage is allowed to reach
Optional
max_volume
The maximum volume of the storage
Required, defaults to 0 if not entered
initial_volume
The initial storage volume
One is required
factors
List of factors to multiply node flow by. Positive factors remove water from the storage, negative factors remove it.
Optional
coming soon...
The RollingVirtualStorage node is a rolling virtual storage node useful for implementing rolling licences. API Reference.
Notes:
TODO: The cost property is not currently respected. See issue #242.
allocation penalty
The cost per unit flow via the node
Optional
nodes
List of inflow/outflow nodes that affect the storage volume
Required
min_volume
The minimum volume the storage is allowed to reach
Optional
max_volume
The maximum volume of the storage
Required, defaults to 0 if not entered
initial_volume
The initial storage volume
One is required
factors
List of factors to multiply node flow by. Positive factors remove water from the storage, negative factors remove it.
Optional
timesteps
The number of timesteps to apply to the rolling storage over
Required
days
The number of days to apply the rolling storage over. Specifying a number of days (instead of a number of timesteps) is only valid with models running a timestep of daily frequency
Required
coming soon...
The AnnualVirtualStorage node is a virtual storage which resets annually, useful for licences. API Reference.
reset_day
The day of the month (0-31) to reset the volume to the initial value
Required
reset_month
The month of the year (0-12) to reset the volume to the initial value
Required
reset_to_initial_volume
Reset the volume to the initial volume instead of maximum volume each year (default is False)
Required
coming soon...
The hydropower node type allows users to define relevant details of turbines in the dams and calculate hydropower generation.
The MultiSplitLink node is an extension of PiecewiseLink that includes additional slots to connect from.
Conceptually this node looks like the following internally,
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.
allocation penalty
The cost per unit flow via the node
Optional
max_flow
The maximum flow constraint on the node
Optional
extra_slots
Number of additional slots (and sublinks) to provide. Must be greater than zero.
Optional
slot_names
The names by which to refer to the slots during connection to other nodes. Length must be one more than the number of extra_slots. The first item refers to the PiecewiseLink connection with the following items for each extra slot.
Optional
factors
If given, the length must be equal to one more than the number of extra_slots. Each item is the proportion of total flow to pass through the additional sublinks. If no factor is required for a particular sublink then use None for its items. Factors are normalised prior to use in the solver.
Optional
coming soon...
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.
factors
The factors to force on the additional splits. Number of extra_slot is assumed to be one less than the length of factors (as per pywr.nodes.MultiSplitLink documentation).
Optional
slot_names
The identifiers to refer to the slots when connect from this Node. Length must be one more than the number of extra slots required.
Optional
coming soon...
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).
Allocation Penalty
The cost per unit flow via the node
Optional
Loss factor
loss_factor : float or Parameter. The proportion of flow that is lost through this node. Must be greater than or equal to zero. This value is either a proportion of gross or net flow depending on the value of loss_factor_type.
Optional, defaults to 0
Loss Factor Type
Either "gross" or "net" (default) to specify whether the loss factor is applied as a proportion of gross or net flow respectively.
Optional, defaults to "net"
Max Flow
The maximum flow constraint on the node
Optional
Min Flow
The minimum flow constraint on the node
Optional
In this example 10% of the gross amount of water flowing into the node is lost.
The others node type allows users to get special-designed computation results of the water resource system.
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. API Reference.
allocation penalty
The cost per unit flow via the node
Optional
target
Hydropower production target. Units should be in units of energy per day
Optional
water_elevation_parameter
Elevation of water entering the turbine. The difference of this value with the turbine_elevation gives the working head of the turbine
Optional
max_flow
Upper bounds on the calculated flow. If set the flow returned by this parameter is at most the value of the max_flow parameter
Optional
min_flow
Lower bounds on the calculated flow. If set the flow returned by this parameter is at least the value of the min_flow parameter
Optional
min_head
Minimum head for flow to occur. If actual head is less than this value zero flow is returned
Optional
turbine_elevation
Elevation of the turbine itself. The difference between the water_elevation and this value gives the working head of the turbine
Optional
efficiency
The efficiency of the turbine
Optional
density
The density of water
Optional
flow_unit_conversion
A factor used to transform the units of flow to be compatible with the equation here. This should convert flow to units of m3/day
Optional
energy_unit_conversion
A factor used to transform the units of total energy. Defaults to 1e-6 to return MJ
Optional
coming soon...
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. API Reference.
Notes: This node can not be connected to other nodes in the network.
model
`Model` instance
Required
name
str
Required
storage_nodes
The Node objects which to return the sum total of
Required
coming soon...