powerio_matrix/
lib.rs

1//! Sparse matrix and graph projections from PowerIO networks.
2//!
3//! Outputs include signed incidence, weighted bus Laplacian, MATPOWER Bp/Bpp,
4//! Y bus, PTDF, LODF, adjacency, LACPF, and petgraph views. Calculations take the
5//! dense [`IndexedNetwork`] view of a [`BalancedNetwork`]. Parsing and emitting
6//! belong to the top level `powerio` facade; this crate owns derived matrix and
7//! graph calculations.
8//!
9//! ```
10//! use powerio_core::Source;
11//! use powerio_matrix::{BuildOptions, IndexedNetwork, calc_bprime_matrix};
12//! use powerio_tx::parse;
13//!
14//! # let case = concat!(env!("CARGO_MANIFEST_DIR"), "/../tests/data/case14.m");
15//! let net = parse(Source::open(case)?)?.into_value();
16//! let g = IndexedNetwork::new(&net);           // dense [0, n) analysis view
17//! let bprime = calc_bprime_matrix(&g, &BuildOptions::default())?;
18//! assert_eq!(bprime.rows(), g.n());            // Bp is n×n
19//! # Ok::<(), Box<dyn std::error::Error>>(())
20//! ```
21//!
22//! # Conventions
23//!
24//! Public DC operators follow PowerModels: an inductive branch has negative
25//! `b`. Their branch by bus incidence matrix `A_pm` gives
26//! `B = A_pmᵀ diag(b) A_pm`, with nonpositive diagonals and nonnegative
27//! off-diagonals. Solver preparation retains its bus by branch factor
28//! `A_s = A_pmᵀ` and uses `w = -b`, so the sparse factor is the positive
29//! M-matrix `L = A_s diag(w) A_sᵀ = -B`. Source bus IDs remain on the model;
30//! [`IndexedNetwork`] maps them to dense indices in `[0, n)`.
31//! `tap == 0` means `tap = 1`. `calc_bprime_matrix` and
32//! `calc_bdoubleprime_matrix` follow MATPOWER `makeB`; Y_bus keeps tap
33//! magnitudes and phase shifts. Branch
34//! terminal admittance is stored per unit. The default public DC formula is
35//! `b = -x/(r² + x²)`. [`BranchSusceptanceFormula::TapAdjustedReactance`] uses
36//! `b = -1/(x·τ)`; both carry phase shift injection. The full reference is in
37//! [the matrix guide](https://eigenergy.github.io/powerio/guide/matrices.html).
38
39// Re-export the balanced model types used by matrix signatures. Parsing,
40// emitting, conversion, and display operations stay on their owning crate and
41// the top level facade. `Error` and `Result` are this crate's own: the variants
42// below are raised here and nowhere in the hub.
43pub use powerio_tx::{
44    BalancedNetwork, Branch, Bus, BusId, BusType, ConnectivityReport, Extras, GenCost, Generator,
45    Hvdc, IndexCore, IndexedNetwork, Load, POWER_MODELS_ANGLE_BOUND_PAD, Shunt, SourceFormat,
46    Storage,
47};
48
49// Internal compatibility paths used throughout the matrix implementation.
50pub(crate) use powerio_tx::{indexed, network};
51
52pub mod diagnostics;
53pub mod error;
54pub use error::{ElementCounts, Error, PiecewiseCostInvalidity, Result, ScenarioMismatch};
55
56/// Compressed sparse row matrix used by the projection calculations.
57pub type SparseMatrix = sprs::CsMat<f64>;
58
59mod ac_jacobian;
60mod acopf;
61mod dc_operators;
62mod dcopf;
63pub mod io;
64mod lindist3flow;
65mod lindist3flow_conic;
66mod lindist3flow_devices;
67mod lindist3flow_standard;
68pub mod matrix;
69mod opf;
70pub mod pipeline;
71pub mod synth;
72
73pub use ac_jacobian::{PowerFlowJacobian, VoltageCoordinates, calc_power_flow_jacobian};
74pub use acopf::{
75    AcBranchData, AcBusData, AcGeneratorData, AcOpfAssemblyOptions, AcOpfPreparation,
76    AcPfAssemblyOptions, AcPfBusData, AcPfGeneratorData, AcPfPreparation, AcStorageData,
77    NodalAcGeneratorData, PreparedAcBusSpecification, build_ac_opf_preparation,
78    build_ac_pf_preparation,
79};
80pub use dc_operators::{DcOperatorOptions, DcOperators, ReferenceConstrainedSystem};
81pub use dcopf::{
82    DcBranchParameters, DcGeneratorParameters, DcOpfAssemblyOptions, DcOpfBundleMetadata,
83    DcOpfBundleOptions, DcOpfMatrices, DcOpfOutputs, DcOpfPreparation, NodalGeneratorParameters,
84    Units, build_dc_opf_preparation, calc_dc_opf_matrices, emit_dcopf_bundle,
85};
86pub use lindist3flow::{
87    AffineScalarCoefficients, ConnectionPowerMap, CrossVoltageCoefficients, LinDist3FlowLineData,
88    LinDist3FlowNetworkData, LinDist3FlowNodeData, LineDropCoefficients,
89    build_lindist3flow_network_data, connection_power_map, cross_voltage_coefficients,
90    evaluate_affine, evaluate_cross_voltage, line_drop_coefficients, winding_voltage_coefficients,
91};
92pub use lindist3flow_conic::{
93    LinDist3FlowCone, LinDist3FlowConeOrigin, LinDist3FlowConicProblem,
94    LinDist3FlowDecisionVariable, LinDist3FlowEquality, LinDist3FlowEqualityOrigin,
95    LinDist3FlowLinearExpression, LinDist3FlowLinearTerm, LinDist3FlowVariableData,
96    build_lindist3flow_conic_problem, lindist3flow_values_from_primal,
97};
98pub use lindist3flow_devices::{
99    LinDist3FlowAffineExpression, LinDist3FlowBalanceEquation, LinDist3FlowBalanceRow,
100    LinDist3FlowBalanceTerm, LinDist3FlowComplexAffinePower, LinDist3FlowDeviceData,
101    LinDist3FlowDispatchChannel, LinDist3FlowGeneratorData, LinDist3FlowLoadData,
102    LinDist3FlowPreparation, LinDist3FlowShuntData, LinDist3FlowSourceData, LinDist3FlowVariable,
103    LinDist3FlowVoltageTerm, build_lindist3flow_device_data, build_lindist3flow_preparation,
104    lindist3flow_connection_incidence,
105};
106pub use lindist3flow_standard::{
107    LinDist3FlowScaling, LinDist3FlowStandardCone, LinDist3FlowStandardForm,
108    LinDist3FlowStandardFormOptions, LinDist3FlowStandardRowOrigin,
109    build_lindist3flow_standard_form, build_lindist3flow_standard_form_with_options,
110    lindist3flow_values_from_standard_primal,
111};
112pub use opf::{AnalysisBranchSource, PiecewiseLinearCost, PreparedObjective};
113
114pub use matrix::multiconductor::{
115    AugmentedSystem, DistNode, MulticonductorAdmittance, MulticonductorNodeIndex, NodeRef,
116    calc_multiconductor_admittance_matrix,
117};
118pub use matrix::{
119    BranchSusceptanceFormula, BuildOptions, GroundedIndexMap, MatrixStats, Scheme,
120    SensitivityMatrices, SensitivityMatrixMetadata, SensitivityMetadata, SensitivityOptions,
121    SensitivitySolver, SensitivitySolverPath, ZeroImpedanceRule, ZeroImpedanceSkips,
122    calc_adjacency_matrix, calc_admittance_matrix, calc_bdoubleprime_matrix, calc_bprime_matrix,
123    calc_diagonal, calc_lacpf_matrix, calc_lodf, calc_ptdf, calc_ptdf_lodf,
124    calc_ptdf_lodf_with_options, calc_reference_indicator, calc_susceptance_diagonal,
125    calc_unit_vector, calc_weighted_laplacian, calc_zero_impedance_skips, check_sddm, ground_at,
126    ground_at_each,
127};
128pub use pipeline::{
129    MatrixKind, Pipeline, PipelineOutputs, RhsKind, calc_matrix, calc_matrix_stats_for_kind,
130    calc_zero_impedance_skips_for_kind, sanitize_stem, select_zero_impedance_rule_for_kind,
131};
132
133#[cfg(feature = "gridfm")]
134pub use io::gridfm::{
135    GridfmDataset, GridfmOptions, GridfmOutputs, GridfmSnapshot, GridfmTables, build_gridfm_batch,
136    build_gridfm_dataset, emit_gridfm_batch, emit_gridfm_dataset, number_snapshots,
137    to_gridfm_record_batches, to_gridfm_record_batches_single,
138};
powerio_matrix/lib.rs

powerio_matrix/
lib.rs
