Struct Simulation 

pub struct Simulation { /* private fields */ }

A simulation session: owns network, solver context, results, and accounting.

Sessions are not thread-safe with respect to themselves (§8.3 invariants). Multiple independent sessions may coexist in the same process.

Implementations

impl Simulation

pub fn create() -> Simulation

Allocate a new empty session (§8.3 create()).

pub fn from_network(network: Network) -> Result<Simulation, SessionError>

Create a session from a network and validate/load it.

This is a convenience for the common sequence:

1. Simulation::create()
2. session.load(network)

pub fn load(&mut self, network: Network) -> Result<(), SessionError>

Load and validate a network, preparing for simulation. Load and validate a network, preparing for simulation (§8.3 load()).

Runs the §2.9 validation checks. Returns SessionError::ValidationFailed if any check fails. On success the session transitions to Loaded.

pub fn run_hydraulics(&mut self) -> Result<(), SessionError>

Run the complete extended-period hydraulic simulation (§8.3 run_hydraulics()).

Requires the session to be in Loaded phase.

pub fn run(&mut self) -> Result<(), SessionError>

Run the full simulation to completion (hydraulics then quality).

This is the easiest entry point for most users:

1. Simulation::load
2. run()
3. query results via Simulation::snapshot_times, Simulation::get_node_result, and Simulation::get_link_result.

pub fn step_hydraulics(&mut self) -> Result<f64, SessionError>

Advance the hydraulic simulation by one adaptive time step (§8.3 step_hydraulics()).

Returns the duration of the step taken (s). Returns 0.0 when the simulation has reached its end time.

pub fn run_quality(&mut self) -> Result<(), SessionError>

Run the complete quality simulation (§8.3 run_quality()).

Requires hydraulics to be done.

pub fn step_quality(&mut self) -> Result<f64, SessionError>

Advance the quality simulation by one hydraulic time step’s worth of sub-steps (§8.3 step_quality()).

Returns the hydraulic duration advanced (s). Returns 0.0 at end.

impl Simulation

pub fn set_node_property( &mut self, node_id: &str, property: NodeProperty, value: f64, ) -> Result<(), SessionError>

Modify a node property before the simulation is run (§8.3 set_node_property()).

The network must be in the Loaded phase. Returns SessionError::InvalidPhase if no network is loaded, or SessionError::UnknownId if node_id does not exist.

pub fn set_link_property( &mut self, link_id: &str, property: LinkProperty, value: f64, ) -> Result<(), SessionError>

Modify a link property (§8.3 set_link_property()).

pub fn peak_demand_cost(&self) -> f64

Return the total peak demand cost (§7.1).

impl Simulation

pub fn get_node_result( &self, node_id: &str, quantity: NodeQuantity, t: f64, ) -> Result<f64, SessionError>

Query a single scalar result for a node at (or near) simulation time t.

Returns Err(SessionError::UnknownId) if node_id is not in the network and Err(SessionError::NoSnapshotAtTime) if no hydraulic snapshot was recorded at or near t. All returned values are in the internal SI unit system (head/pressure in m, demand in m³/s, quality in mg/L or h or %).

pub fn get_link_result( &self, link_id: &str, quantity: LinkQuantity, t: f64, ) -> Result<f64, SessionError>

Return a link result quantity at the specified simulation time (§8.2.1).

pub fn snapshot_times(&self) -> Vec<f64>

Return the times at which hydraulic snapshots were recorded (§8.2.1).

The returned Vec<f64> is in ascending order and contains one entry per reporting timestep that was stored during run_hydraulics() or successive step_hydraulics() calls.

pub fn result_ranges(&self) -> Result<ResultRanges, SessionError>

Compute global min/max for each display quantity across all snapshots.

Iterates directly over snapshot arrays by index — O(snapshots × elements) with zero string lookups.

pub fn all_node_results_at( &self, t: f64, ) -> Result<Vec<NodeResult>, SessionError>

Return all node results at a given simulation time, indexed by position.

Returns one NodeResult per node in the same order as node_ids(). Uses direct index access — O(N) with no string lookups.

pub fn all_link_results_at( &self, t: f64, ) -> Result<Vec<LinkResult>, SessionError>

Return all link results at a given simulation time, indexed by position.

Returns one LinkResult per link in the same order as link_ids(). Uses direct index access — O(L) with no string lookups.

pub fn node_ids(&self) -> Vec<&str>

Return the node IDs in the order they were indexed at load time.

pub fn link_ids(&self) -> Vec<&str>

Return the link IDs in the order they were indexed at load time.

pub fn pump_ids(&self) -> Vec<&str>

Return the pump link IDs in the order they appear in the network.

pub fn flow_units(&self) -> Option<FlowUnits>

Return the declared FlowUnits of the loaded network.

pub fn get_pump_energy( &self, pump_id: &str, ) -> Result<&PumpEnergy, SessionError>

Return energy statistics for a pump link (§8.2.1).

pub fn get_mass_balance(&self) -> Result<&MassBalance, SessionError>

Return the global mass balance from the quality engine (§8.2.1).

pub fn get_flow_balance(&self) -> Result<&FlowBalance, SessionError>

Return the global volumetric flow balance from accounting (§8.2.1).

pub fn final_tank_volume(&self) -> Result<f64, SessionError>

Return the total tank volume at the end of the simulation (m³).

Sums NodeState::volume from the live state vector for all tank nodes.

pub fn flow_balance_summary(&self) -> Result<FlowBalanceSummary, SessionError>

Return the complete flow balance summary with derived values.

pub fn warnings(&self) -> &[SimWarning]

Borrow the list of simulation warnings.

Trait Implementations

impl Default for Simulation

fn default() -> Simulation

Returns the “default value” for a type.

impl WritableSimulation for Simulation

fn net(&self) -> &Network

The Network data model for this simulation.

fn snapshots(&self) -> &[HydSnapshot]

All hydraulic snapshots stored during the simulation.

fn pump_energy_at(&self, link_index: usize) -> Option<&PumpEnergy>

Pump energy record at link_index, or None if no accounting state is available (e.g. hydraulics not yet run).

fn peak_demand_kw(&self) -> f64

Peak simultaneous electrical demand across all pumps (kW).

fn mass_balance(&self) -> Option<&MassBalance>

Mass balance from the quality engine. None if quality not yet run.

fn warnings(&self) -> &[SimWarning]

Non-fatal diagnostics emitted during the simulation.

fn pump_energy_by_id(&self, pump_id: &str) -> Option<&PumpEnergy>

Look up a pump’s energy record by its string ID. Returns None if the ID is unknown or the link is not a pump.

fn analysis_times(&self) -> (Option<SystemTime>, Option<SystemTime>)

The hydraulic and quality analysis start and finish wall-clock times.

fn flow_balance(&self) -> Option<&FlowBalance>

Flow balance from accounting. None if hydraulics not yet run.

fn flow_balance_summary(&self) -> Option<FlowBalanceSummary>

Derived flow balance summary. None if hydraulics not yet run or if the simulation lacks the data needed to compute final tank volume.