hydra_sdk/
lib.rs

1//! Hydra — water distribution network simulation engine.
2//!
3//! This crate is the published library for the Hydra workspace. It re-exports the
4//! complete user-facing API so that downstream users depend on a single crate
5//! with all internal dependency versions pre-pinned and known to be compatible.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! use hydra_sdk::{io, Simulation, NodeQuantity, LinkQuantity};
11//!
12//! let bytes = std::fs::read("network.inp").unwrap();
13//! let network = io::parse(&bytes).unwrap();
14//!
15//! let mut sim = Simulation::create();
16//! sim.load(network).unwrap();
17//! sim.run().unwrap();
18//!
19//! for t in sim.snapshot_times() {
20//!     let head = sim.get_node_result("J1", NodeQuantity::Head, t).unwrap();
21//!     let flow = sim.get_link_result("P1", LinkQuantity::Flow, t).unwrap();
22//!     println!("t={t:.0}s  head={head:.3}  flow={flow:.6}");
23//! }
24//! ```
25
26/// The crate version, taken from `Cargo.toml` at compile time.
27pub const HYDRA_VERSION: &str = env!("CARGO_PKG_VERSION");
28
29// ── Session API ───────────────────────────────────────────────────────────────
30
31pub use hydra_engine_wds::{
32    classify_simulation_runtime_millis,
33    estimate_simulation_runtime,
34    estimate_simulation_runtime_from_summary,
35    estimate_simulation_runtime_millis_from_summary,
36    // Accounting result types.
37    FlowBalance,
38    FlowBalanceSummary,
39    HydSnapshot,
40    HydraulicError,
41    LinkProperty,
42    LinkQuantity,
43    // Batch result types.
44    LinkResult,
45    MassBalance,
46    NodeProperty,
47    // Result query enums.
48    NodeQuantity,
49    NodeResult,
50    PumpEnergy,
51    QualityError,
52    // Batch range computation.
53    ResultRanges,
54    // Error types.
55    SessionError,
56    // Non-fatal diagnostics.
57    SimWarning,
58    // Main simulation object.
59    Simulation,
60    WarningKind,
61    // Trait required to call io::write_binary_output / io::write_report.
62    WritableSimulation,
63    HYDRA_HYDRAULICS_VERSION,
64    HYDRA_QUALITY_VERSION,
65    HYDRA_SIMULATION_VERSION,
66};
67
68// ── Analytics ─────────────────────────────────────────────────────────────────
69
70pub use hydra_engine_wds::{
71    compute_demand_reliability_from_out, compute_demand_reliability_from_out_with_options,
72    compute_service_compliance_from_out, estimate_analysis_runtime_millis, AnalysisSelection,
73    DemandReliabilityNode, DemandReliabilityOptions, DemandReliabilityReport,
74    DemandReliabilitySummary, ServiceComplianceNode, ServiceComplianceReport,
75    ServiceComplianceSummary, ServiceComplianceThresholds, HYDRA_ANALYSIS_VERSION,
76};
77
78// ── Data model ────────────────────────────────────────────────────────────────
79
80pub use hydra_engine_wds::{
81    // §2.8 — controls
82    ActionValue,
83    // §2.3 — curves
84    Curve,
85    CurveKind,
86    CurvePoint,
87    // §2.4 / §2.5 — nodes and demands
88    DemandCategory,
89    // §2.1 — top-level options and enums
90    DemandModel,
91    // §2.10 — FAVAD
92    FavadCoeffs,
93    FlowUnits,
94    HeadLossFormula,
95    // §2.4.2 — node subtypes
96    Junction,
97    // §2.6 — links
98    Link,
99    LinkBase,
100    LinkKind,
101    LinkState,
102    LinkStatus,
103    LogicOp,
104    // §2.4.4 — tank mixing
105    MixModel,
106    Network,
107    Node,
108    NodeBase,
109    NodeKind,
110    NodeState,
111    // §2.2 — patterns
112    Pattern,
113    Pipe,
114    Premise,
115    PremiseAttribute,
116    PremiseObject,
117    PremiseOperator,
118    Pump,
119    PumpCurveType,
120    QualityMode,
121    // §2.7 — quality sources
122    QualitySource,
123    // report options
124    ReportFieldOption,
125    ReportOptions,
126    ReportSelection,
127    ReportStatus,
128    Reservoir,
129    Rule,
130    RuleAction,
131    RuntimeEstimate,
132    SimpleControl,
133    SimulationOptions,
134    SourceType,
135    StatisticType,
136    Tank,
137    TriggerType,
138    // §2.9 validation
139    ValidationError,
140    Valve,
141    ValveType,
142    WallOrder,
143};
144
145// ── I/O ───────────────────────────────────────────────────────────────────────
146
147/// Parsing and output-writing utilities.
148///
149/// - [`io::parse`] — parse EPANET `.inp` bytes into a [`Network`].
150/// - [`io::out_writer`] / [`io::rpt_writer`] — write binary `.out` and text `.rpt` output.
151pub mod io {
152    pub use hydra_engine_wds::io::{
153        analysis_io, out_reader, out_writer, parse, rpt_writer, write_inp, ParseError,
154    };
155}
156
157/// Serialise a [`Network`] back to EPANET 2.3 INP bytes.
158///
159/// The inverse of [`io::parse`]: all values are converted from the internal
160/// unit system back to the user-declared unit system.
161pub use hydra_engine_wds::write_inp;
162
163#[cfg(test)]
164mod tests {
165    use super::*;
166
167    #[test]
168    fn facade_reexports_simulation_type() {
169        let _ = Simulation::create();
170    }
171
172    #[test]
173    fn facade_reexports_common_io_parse() {
174        let bytes = b"{\"invalid\":true}";
175        let err = io::parse(bytes).expect_err("invalid model bytes should fail parse");
176        assert!(matches!(err, io::ParseError::UnrecognisedFormat));
177    }
178}
hydra_sdk/lib.rs

hydra_sdk/
lib.rs
