Feature/add reservoir node

pywr-core/src/metric.rs

@@ -81,6 +81,7 @@ pub enum MetricF64 {
     NodeInFlow(NodeIndex),
     NodeOutFlow(NodeIndex),
     NodeVolume(NodeIndex),
+    NodeMaxVolume(NodeIndex),
     AggregatedNodeInFlow(AggregatedNodeIndex),
     AggregatedNodeOutFlow(AggregatedNodeIndex),
     AggregatedNodeVolume(AggregatedStorageNodeIndex),
@@ -103,6 +104,7 @@ impl MetricF64 {
             MetricF64::NodeInFlow(idx) => Ok(state.get_network_state().get_node_in_flow(idx)?),
             MetricF64::NodeOutFlow(idx) => Ok(state.get_network_state().get_node_out_flow(idx)?),
             MetricF64::NodeVolume(idx) => Ok(state.get_network_state().get_node_volume(idx)?),
+            MetricF64::NodeMaxVolume(idx) => Ok(model.get_node(idx)?.get_current_max_volume(state)?),
             MetricF64::AggregatedNodeInFlow(idx) => {
                 let node = model.get_aggregated_node(idx)?;
                 node.iter_nodes()

pywr-core/src/models/simple.rs

@@ -53,15 +53,15 @@ impl Model {
         &mut self.network
     }
 
-    /// Check whether a solver [`S`] has the required features to run this model.
+    /// Check whether a solver `S` has the required features to run this model.
     pub fn check_solver_features<S>(&self) -> bool
     where
         S: Solver,
     {
         self.network.check_solver_features::<S>()
     }
 
-    /// Check whether a solver [`S`] has the required features to run this model.
+    /// Check whether a solver `S` has the required features to run this model.
     pub fn check_multi_scenario_solver_features<S>(&self) -> bool
     where
         S: MultiStateSolver,

pywr-core/src/network.rs

@@ -213,6 +213,7 @@ impl Network {
     pub fn nodes(&self) -> &NodeVec {
         &self.nodes
     }
+
     pub fn edges(&self) -> &EdgeVec {
         &self.edges
     }
@@ -285,7 +286,7 @@ impl Network {
         Ok(recorder_internal_states)
     }
 
-    /// Check whether a solver [`S`] has the required features to run this network.
+    /// Check whether a solver `S` has the required features to run this network.
     pub fn check_solver_features<S>(&self) -> bool
     where
         S: Solver,
@@ -295,7 +296,7 @@ impl Network {
         required_features.iter().all(|f| S::features().contains(f))
     }
 
-    /// Check whether a solver [`S`] has the required features to run this network.
+    /// Check whether a solver `S` has the required features to run this network.
     pub fn check_multi_scenario_solver_features<S>(&self) -> bool
     where
         S: MultiStateSolver,
@@ -1140,7 +1141,7 @@ impl Network {
         }
     }
 
-    /// Get a [`Parameter<usize>`] from its index.
+    /// Get a `Parameter<usize>` from its index.
     pub fn get_index_parameter(&self, index: ParameterIndex<usize>) -> Result<&dyn parameters::Parameter, PywrError> {
         match self.parameters.get_usize(index) {
             Some(p) => Ok(p),
@@ -1462,7 +1463,7 @@ impl Network {
         Ok(edge_index)
     }
 
-    /// Set the variable values on the parameter [`parameter_index`].
+    /// Set the variable values on the parameter `parameter_index`.
     ///
     /// This will update the internal state of the parameter with the new values for all scenarios.
     pub fn set_f64_parameter_variable_values(
@@ -1492,7 +1493,7 @@ impl Network {
         }
     }
 
-    /// Set the variable values on the parameter [`parameter_index`] and scenario [`scenario_index`].
+    /// Set the variable values on the parameter `parameter_index` and scenario `scenario_index`.
     ///
     /// Only the internal state of the parameter for the given scenario will be updated.
     pub fn set_f64_parameter_variable_values_for_scenario(
@@ -1568,7 +1569,7 @@ impl Network {
         }
     }
 
-    /// Set the variable values on the parameter [`parameter_index`].
+    /// Set the variable values on the parameter `parameter_index`.
     ///
     /// This will update the internal state of the parameter with the new values for scenarios.
     pub fn set_u32_parameter_variable_values(
@@ -1598,7 +1599,7 @@ impl Network {
         }
     }
 
-    /// Set the variable values on the parameter [`parameter_index`] and scenario [`scenario_index`].
+    /// Set the variable values on the parameter `parameter_index` and scenario `scenario_index`.
     ///
     /// Only the internal state of the parameter for the given scenario will be updated.
     pub fn set_u32_parameter_variable_values_for_scenario(

pywr-core/src/recorders/csv.rs

@@ -12,7 +12,7 @@ use std::num::NonZeroU32;
 use std::ops::Deref;
 use std::path::PathBuf;
 
-/// Output the values from a [`MetricSet`] to a CSV file.
+/// Output the values from a [`crate::recorders::MetricSet`] to a CSV file.
 #[derive(Clone, Debug)]
 pub struct CsvWideFmtOutput {
     meta: RecorderMeta,
@@ -196,7 +196,7 @@ pub struct CsvLongFmtRecord {
     value: f64,
 }
 
-/// Output the values from a several [`MetricSet`]s to a CSV file in long format.
+/// Output the values from a several [`crate::recorders::MetricSet`]s to a CSV file in long format.
 ///
 /// The long format contains a row for each value produced by the metric set. This is useful
 /// for analysis in tools like R or Python which can easily read long format data.

pywr-core/src/timestep.rs

@@ -68,7 +68,7 @@ impl PywrDuration {
     }
 
     /// Convert the duration to a string representation that can be parsed by polars
-    /// see: https://docs.rs/polars/latest/polars/prelude/struct.Duration.html#method.parse
+    /// see: <https://docs.rs/polars/latest/polars/prelude/struct.Duration.html#method.parse>
     pub fn duration_string(&self) -> String {
         let milliseconds = self.milliseconds();
         let mut duration = String::new();

pywr-schema/src/error.rs

@@ -65,6 +65,8 @@ pub enum SchemaError {
     OutOfRange(#[from] chrono::OutOfRange),
     #[error("The metric set with name '{0}' contains no metrics")]
     EmptyMetricSet(String),
+    #[error("Missing the following attribute {attr:?} on node {name:?}.")]
+    MissingNodeAttribute { attr: String, name: String },
 }
 
 #[cfg(feature = "core")]

pywr-schema/src/model.rs

@@ -459,10 +459,11 @@ impl PywrNetwork {
                 .ok_or_else(|| SchemaError::NodeNotFound(edge.to_node.clone()))?;
 
             let from_slot = edge.from_slot.as_deref();
+            let to_slot = edge.to_slot.as_deref();
 
             // Connect each "from" connector to each "to" connector
             for from_connector in from_node.output_connectors(from_slot) {
-                for to_connector in to_node.input_connectors() {
+                for to_connector in to_node.input_connectors(to_slot) {
                     let from_node_index =
                         network.get_node_index_by_name(from_connector.0, from_connector.1.as_deref())?;
                     let to_node_index = network.get_node_index_by_name(to_connector.0, to_connector.1.as_deref())?;

pywr-schema/src/nodes/core.rs

@@ -810,6 +810,7 @@ impl StorageNode {
 
         let metric = match attr {
             NodeAttribute::Volume => MetricF64::NodeVolume(idx),
+            NodeAttribute::MaxVolume => MetricF64::NodeMaxVolume(idx),
             NodeAttribute::ProportionalVolume => {
                 let dm = DerivedMetric::NodeProportionalVolume(idx);
                 let derived_metric_idx = network.add_derived_metric(dm);
@@ -931,7 +932,7 @@ impl TryFrom<ReservoirNodeV1> for StorageNode {
 #[doc = svgbobdoc::transform!(
 /// This is used to represent a catchment inflow.
 ///
-/// Catchment nodes create a single [`crate::node::InputNode`] node in the network, but
+/// Catchment nodes create a single [`InputNode`] node in the network, but
 /// ensure that the maximum and minimum flow are equal to [`Self::flow`].
 ///
 /// ```svgbob

pywr-schema/src/nodes/delay.rs

@@ -16,9 +16,9 @@ use schemars::JsonSchema;
 ///
 /// This is often useful in long river reaches as a simply way to model time-of-travel. Internally
 /// an `Output` node is used to terminate flows entering the node and an `Input` node is created
-/// with flow constraints set by a [DelayParameter]. These constraints set the minimum and
+/// with flow constraints set by a [`pywr_core::parameters::DelayParameter`]. These constraints set the minimum and
 /// maximum flow on the `Input` node equal to the flow reaching the `Output` node N time-steps
-/// ago. The internally created [DelayParameter] is created with this node's name and the suffix
+/// ago. The internally created [`pywr_core::parameters::DelayParameter`] is created with this node's name and the suffix
 /// "-delay".
 ///
 ///

pywr-schema/src/nodes/mod.rs

@@ -5,6 +5,7 @@ mod loss_link;
 mod monthly_virtual_storage;
 mod piecewise_link;
 mod piecewise_storage;
+mod reservoir;
 mod river;
 mod river_gauge;
 mod river_split_with_gauge;
@@ -20,6 +21,10 @@ use crate::metric::Metric;
 #[cfg(feature = "core")]
 use crate::model::LoadArgs;
 use crate::model::PywrNetwork;
+pub use crate::nodes::reservoir::{
+    Bathymetry, BathymetryType, Evaporation, Leakage, Rainfall, ReservoirNode, SpillNodeType,
+};
+
 use crate::parameters::TimeseriesV1Data;
 use crate::visit::{VisitMetrics, VisitPaths};
 pub use annual_virtual_storage::{AnnualReset, AnnualVirtualStorageNode};
@@ -96,10 +101,17 @@ pub enum NodeAttribute {
     Inflow,
     Outflow,
     Volume,
+    MaxVolume,
     ProportionalVolume,
     Loss,
     Deficit,
     Power,
+    /// The compensation flow out of a [`ReservoirNode`]
+    Compensation,
+    /// The rainfall volume into a [`ReservoirNode`]
+    Rainfall,
+    /// The evaporation volume out of a [`ReservoirNode`]
+    Evaporation,
 }
 
 pub struct NodeBuilder {
@@ -233,6 +245,7 @@ impl NodeBuilder {
                 meta,
                 ..Default::default()
             }),
+            NodeType::Reservoir => Node::Reservoir(ReservoirNode { ..Default::default() }),
         }
     }
 }
@@ -263,6 +276,7 @@ pub enum Node {
     MonthlyVirtualStorage(MonthlyVirtualStorageNode),
     RollingVirtualStorage(RollingVirtualStorageNode),
     Turbine(TurbineNode),
+    Reservoir(ReservoirNode),
 }
 
 impl Node {
@@ -301,10 +315,11 @@ impl Node {
             Node::MonthlyVirtualStorage(n) => &n.meta,
             Node::RollingVirtualStorage(n) => &n.meta,
             Node::Turbine(n) => &n.meta,
+            Node::Reservoir(n) => n.meta(),
         }
     }
 
-    pub fn input_connectors(&self) -> Vec<(&str, Option<String>)> {
+    pub fn input_connectors(&self, slot: Option<&str>) -> Vec<(&str, Option<String>)> {
         match self {
             Node::Input(n) => n.input_connectors(),
             Node::Link(n) => n.input_connectors(),
@@ -327,6 +342,7 @@ impl Node {
             Node::Delay(n) => n.input_connectors(),
             Node::RollingVirtualStorage(n) => n.input_connectors(),
             Node::Turbine(n) => n.input_connectors(),
+            Node::Reservoir(n) => n.input_connectors(slot),
         }
     }
 
@@ -353,6 +369,7 @@ impl Node {
             Node::Delay(n) => n.output_connectors(),
             Node::RollingVirtualStorage(n) => n.output_connectors(),
             Node::Turbine(n) => n.output_connectors(),
+            Node::Reservoir(n) => n.output_connectors(slot),
         }
     }
 
@@ -378,6 +395,7 @@ impl Node {
             Node::Delay(n) => n.default_metric(),
             Node::RollingVirtualStorage(n) => n.default_metric(),
             Node::Turbine(n) => n.default_metric(),
+            Node::Reservoir(n) => n.default_metric(),
         }
     }
 }
@@ -406,6 +424,7 @@ impl Node {
             Node::Turbine(n) => n.add_to_model(network, args),
             Node::MonthlyVirtualStorage(n) => n.add_to_model(network, args),
             Node::RollingVirtualStorage(n) => n.add_to_model(network, args),
+            Node::Reservoir(n) => n.add_to_model(network),
         }
     }
 
@@ -436,6 +455,7 @@ impl Node {
             Node::Turbine(n) => n.node_indices_for_constraints(network),
             Node::MonthlyVirtualStorage(n) => n.node_indices_for_constraints(network, args),
             Node::RollingVirtualStorage(n) => n.node_indices_for_constraints(network, args),
+            Node::Reservoir(n) => n.node_indices_for_constraints(network),
         }
     }
 
@@ -463,6 +483,7 @@ impl Node {
             Node::PiecewiseStorage(n) => n.set_constraints(network, args),
             Node::Delay(n) => n.set_constraints(network, args),
             Node::Turbine(n) => n.set_constraints(network, args),
+            Node::Reservoir(n) => n.set_constraints(network, args),
             Node::MonthlyVirtualStorage(_) => Ok(()), // TODO
             Node::RollingVirtualStorage(_) => Ok(()), // TODO
         }
@@ -496,6 +517,7 @@ impl Node {
             Node::Delay(n) => n.create_metric(network, attribute),
             Node::RollingVirtualStorage(n) => n.create_metric(network, attribute),
             Node::Turbine(n) => n.create_metric(network, attribute, args),
+            Node::Reservoir(n) => n.create_metric(network, attribute),
         }
     }
 }
@@ -573,6 +595,7 @@ impl VisitMetrics for Node {
             Node::MonthlyVirtualStorage(n) => n.visit_metrics(visitor),
             Node::RollingVirtualStorage(n) => n.visit_metrics(visitor),
             Node::Turbine(n) => n.visit_metrics(visitor),
+            Node::Reservoir(n) => n.visit_metrics(visitor),
         }
     }
 
@@ -598,6 +621,7 @@ impl VisitMetrics for Node {
             Node::MonthlyVirtualStorage(n) => n.visit_metrics_mut(visitor),
             Node::RollingVirtualStorage(n) => n.visit_metrics_mut(visitor),
             Node::Turbine(n) => n.visit_metrics_mut(visitor),
+            Node::Reservoir(n) => n.visit_metrics_mut(visitor),
         }
     }
 }
@@ -625,6 +649,7 @@ impl VisitPaths for Node {
             Node::MonthlyVirtualStorage(n) => n.visit_paths(visitor),
             Node::RollingVirtualStorage(n) => n.visit_paths(visitor),
             Node::Turbine(n) => n.visit_paths(visitor),
+            Node::Reservoir(n) => n.visit_paths(visitor),
         }
     }
 
@@ -650,6 +675,7 @@ impl VisitPaths for Node {
             Node::MonthlyVirtualStorage(n) => n.visit_paths_mut(visitor),
             Node::RollingVirtualStorage(n) => n.visit_paths_mut(visitor),
             Node::Turbine(n) => n.visit_paths_mut(visitor),
+            Node::Reservoir(n) => n.visit_paths_mut(visitor),
         }
     }
 }