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. Builders take the
5//! dense [`IndexedNetwork`] view of a [`BalancedNetwork`]. The crate reexports
6//! [`powerio`] types and functions.
7//!
8//! ```
9//! use powerio_matrix::{parse_file, IndexedNetwork, build_bprime, BuildOptions};
10//!
11//! # let case = concat!(env!("CARGO_MANIFEST_DIR"), "/../tests/data/case14.m");
12//! let net = parse_file(case, None)?.network;   // re-exported from powerio
13//! let g = IndexedNetwork::new(&net);           // dense [0, n) analysis view
14//! let bprime = build_bprime(&g, &BuildOptions::default())?;
15//! assert_eq!(bprime.rows(), g.n());            // Bp is n×n
16//! # Ok::<(), powerio_matrix::Error>(())
17//! ```
18//!
19//! # Conventions
20//!
21//! The DC bus susceptance matrix and other weighted bus Laplacians use the
22//! positive M-matrix form: stored nonzero off-diagonal entries are negative,
23//! diagonals are nonnegative, and `diag = Σ|off-diag|`. Source bus IDs remain on
24//! the model; [`IndexedNetwork`] maps them to dense indices in `[0, n)`. `tap == 0` means
25//! `tap = 1`. `build_bprime` and `build_bdoubleprime` follow MATPOWER `makeB`;
26//! Y_bus keeps tap magnitudes and phase shifts.
27//! Branch terminal admittance is stored per unit. DC incidence uses
28//! `b = x/(r² + x²)` by default. [`DcConvention::Matpower`] uses `1/(x·τ)`, and
29//! both carry phase shift injection. The full reference across every matrix is in
30//! [the matrix guide](https://eigenergy.github.io/powerio/guide/matrices.html).
31
32// Re-export the powerio data layer so one import covers model and matrix types,
33// and so the matrix modules' `crate::network` / `crate::format` paths resolve
34// unchanged after the split. `Error` and `Result` are this crate's own: the
35// variants below are raised here and nowhere in the hub.
36pub use powerio::{
37    BalancedNetwork, Branch, Bus, BusId, BusType, ConnectivityReport, Conversion, DisplayData,
38    DisplayFormat, ErrorCategory, Extras, GenCost, GenCostPatch, GenCostPolicyReport, Generator,
39    Hvdc, IndexCore, IndexedNetwork, Load, MissingGenCostPolicy, NormalizeOptions,
40    NormalizedNetwork, POWER_MODELS_ANGLE_BOUND_PAD, Parsed, PwdDisplay, PwdSubstation,
41    PypsaCsvOutputs, Shunt, SourceFormat, Storage, TargetFormat, WriteOptions, convert_file,
42    convert_file_with_options, convert_str, convert_str_with_options, display_format_from_name,
43    format, gen_cost, geo, indexed, network, parse_bytes, parse_bytes_with_name,
44    parse_display_bytes, parse_display_file, parse_file, parse_gen_cost_csv, parse_matpower,
45    parse_matpower_file, parse_pandapower_json, parse_powermodels_json, parse_powerworld,
46    parse_pslf, parse_psse, parse_str, parse_str_with_name, read_pypsa_csv_folder,
47    target_format_from_name, write_as, write_as_with_options, write_egret_json, write_matpower,
48    write_pandapower_json, write_powermodels_json, write_powerworld, write_psse,
49    write_pypsa_csv_folder,
50};
51
52pub mod error;
53pub use error::{ElementCounts, Error, Result, ScenarioMismatch};
54
55/// The hub's error, so a binding can map both through one taxonomy.
56pub use powerio::Error as CoreError;
57
58/// Compressed sparse row matrix used by the projection builders.
59pub type SparseMatrix = sprs::CsMat<f64>;
60
61pub mod io;
62pub mod matrix;
63pub mod pipeline;
64pub mod synth;
65
66pub use matrix::{
67    BuildOptions, DcConvention, GroundedIndexMap, IncidenceParts, MatrixStats, Scheme,
68    SensitivityMatrices, SensitivityMatrixMetadata, SensitivityMetadata, SensitivityOptions,
69    SensitivitySolver, SensitivitySolverPath, ZeroImpedanceRule, ZeroImpedanceSkips,
70    build_adjacency, build_bdoubleprime, build_bprime, build_flow_map, build_incidence,
71    build_lacpf, build_lodf, build_ptdf, build_ptdf_lodf, build_ptdf_lodf_with_options,
72    build_weighted_laplacian, build_ybus, ground_at, ground_at_each, reference_indicator,
73    sddm_check, skipped_zero_impedance, susceptance_diag, unit_vector,
74};
75pub use pipeline::{
76    MatrixKind, Pipeline, PipelineOutputs, RhsKind, build_kind, matrix_stats_for_kind,
77    sanitize_stem, zero_impedance_rule_for_kind, zero_impedance_skips_for_kind,
78};
79
80#[cfg(feature = "gridfm")]
81pub use io::gridfm::{
82    GridfmOptions, GridfmOutputs, GridfmRead, GridfmSnapshot, GridfmTables, gridfm_base_case,
83    gridfm_record_batches, gridfm_record_batches_batch, gridfm_scenario_ids, numbered_snapshots,
84    read_gridfm_dataset, read_gridfm_network, read_gridfm_scenarios, write_gridfm_batch,
85    write_gridfm_dataset,
86};
87#[cfg(feature = "gridfm")]
88pub use io::{dataset_scenario_ids, read_dataset_dir};
powerio_matrix/lib.rs

powerio_matrix/
lib.rs
