WaterStrategy
English
English
  • WaterStrategy Documentation
  • Support
  • Getting Started
    • Creating an Account
    • Logging In
    • Tour of WaterStrategy
    • Creating a new Project and Network
    • Sharing Projects and Networks
    • Exporting and Importing Models
    • Dealing with Model Errors
    • Uploading External Data
  • Modeling Basics
    • Water Resource System Modeling?
    • What is Pywr?
    • Pywr Concepts
    • Node Types
      • Water Input
        • Input Node
        • Catchment Node
        • Proportional Input Node
      • Water Transport
        • Link Node
        • River Node
        • Delay Node
        • RiverSplit Node
        • RiverSplitWithGauge Node
        • RiverGauge Node
        • BreakLink Node
        • PiecewiseLink Node
        • MultiSplitLink Node
      • Water Storage
        • Storage Node
        • Reservoir Node
        • VirtualStorage Node
        • RollingVirtualStorage Node
        • AnnualVirtualStorage Node
        • SeasonalVirtualStorage Node
        • AggregatedStorage Node
      • Water Output
        • Output Node
        • Loss Link Node
      • Hydropower
        • Turbine Node
      • Others
        • AggregatedNode
    • Allocation Penalties
    • Scenarios
      • WaterStrategy Scenarios
      • Pywr-Scenarios
        • Parameter and pywr-scenario Integration
    • Parameters
      • Base Parameter Class
        • Parameter
        • IndexParameter
      • Simple Parameters
        • Constant
        • Constant Scenario Parameter
        • Constant Scenario Index Parameter
      • Combining multiple parameters
        • Aggregated Parameter
        • Aggregated Index Parameter
        • Division Parameter
        • Negative Parameter
        • MaxParameter
        • Negative MaxParameter
        • MinParameter
        • Negative MinParameter
        • Offset Parameter
      • Time Series and Profiles
        • Daily Profile
        • Weekly Profile
        • Monthly Profile
        • Uniform Drawdown Profile
        • Scenario Daily Profile
        • Scenario Weekly Profile
        • Scenario Monthly Profile
        • Array Indexed Scenario Monthly Factors
        • RBF Profile
      • DataFrame Parameter
      • HDF5 Parameter
      • Array Based Parameters
        • Array Indexed Parameter
        • Array Indexed Scenario Parameter
        • Indexed Array Parameter
      • Threshold Parameters
        • Abstract Threshold
        • Storage Threshold
        • Node Threshold
        • Parameter Threshold
        • Recorder Threshold
        • Current Year Threshold
        • Current Ordinal Day Threshold
      • Interpolation Parameters
        • Interpolated Parameter
        • Interpolated Quadrature
        • Interpolated Flow
        • Interpolated Volume
      • Control Curve Parameters
        • Base Control Curve
        • Control Curve Interpolated Parameter
        • Control Curve Piecewise Interpolated Parameter
        • Control Curve Index Parameter
      • Hydropower Parameters
      • Others
        • Annual Harmonic Series Parameter
        • Deficit Parameter
        • Scenario Wrapper Parameter
        • Piecewise Integral Parameter
        • Flow Parameter
        • Flow Delay Parameter
        • Discount Factor Parameter
    • Recorders
      • Base Recorder
        • Recorder
        • Node Recorder
        • Storage Recorder
        • Parameter Recorder
        • Index Parameter Recorder
        • Aggregator
      • Numpy Array Recorders
        • Numpy Array Node Recorder
        • Numpy Array Storage Recorder
        • Numpy Array Level Recorder
        • Numpy Array Area Recorder
        • Numpy Array Parameter Recorder
        • Numpy Array Index Parameter Recorder
        • Numpy Array Daily Profile Parameter Recorder
      • Flow Duration Curve Recorders
        • Flow Duration Curve Recorder
        • Storage Duration Curve Recorder
        • Flow Duration Curve Deviation Recorder
        • Seasonal Flow Duration Curve Recorder
      • Deficit Recorders
        • Numpy Array Node Deficit Recorder
        • Numpy Array Node Supplied Ratio Recorder
        • Numpy Array Node Curtailment Ratio Recorder
        • Total Deficit Node Recorder
        • Deficit Frequency Node Recorder
      • Statistical Recorders
        • Aggregated Recorder
        • Mean Flow Node Recorder
        • Total Flow Node Recorder
        • Annual Total Flow Recorder
        • Mean Parameter Recorder
        • Total Parameter Recorder
        • Rolling Mean Flow Node Recorder
        • Minimum Volume Storage Recorder
        • Minimum Threshold Volume Storage Recorder
        • Timestep Count Index Parameter Recorder
        • Annual Count Index Threshold Recorder
        • Rolling Window Parameter Recorder
      • Index Recorders
        • Annual Count Index Parameter Recorder
      • File Recorders
        • CSV Recorder
        • Tables Recorder
      • Hydro-power Recorders
        • Hydropower Recorder
        • Total Hydro Energy Recorder
  • Applied Modeling
    • Reservoir and Storage Nodes
  • Tutorials
    • Creating and running a simple model
      • Creating and Running a Model
        • Setting up a Project and Network
        • Adding Nodes and Links (Edges)
        • Add Data to the Nodes
        • Setting the Time Horizon
        • Running the Model and Visualizing its Outputs
        • Creating a New Scenario
        • Exercise
      • Making Changes to a Model
        • Adding a Reservoir
        • Adding Basic Operating Rules
    • Modelling basin reservoir systems
      • Creating a New Project and Network
      • Adding a Dam (Reservoir)
      • Adding a Demand
      • Adding a Water Treatment Works with Losses
      • Adding a Source Representing Groundwater
      • Additional Exercises
      • Adding reservoir bathymetry, evaporation, and rainfall
        • Background on Evaporation and Precipitation on Reservoirs
        • Adding reservoir bathymetry (Area)
        • Adding reservoir bathymetry (Level)
        • Adding monthly evaporation and rainfall
      • Using allocation penalties and control rules to balance sources
      • Control Curves and Demand Savings
        • Adding reservoir control curves and demand savings (reductions)
    • Using Allocation Penalties to Allocate Water
      • Exercise 1a Two nodes
      • Exercise 1b Two demands
      • Exercise 1c Minimum Flow Properties
      • Exercise 2a Simple system with reservoir draw downs
      • Exercise 2b Simple system with overflow
    • Pywr-scenarios reading external DataFrame and adding Custom Rules
      • Uploading Files
      • Reading CSV DataFrame
      • Running pywr-scenarios
      • Reading h5 DataFrame for pywr-scenarios
      • Create Custom Rule - TranscientDecisionParameter
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. Modeling Basics

Allocation Penalties

PreviousAggregatedNodeNextScenarios

Last updated 5 months ago

Was this helpful?

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.