gridoxide 0.2.0__tar.gz → 0.3.0__tar.gz

gridoxide-0.3.0/.dockerignore

@@ -0,0 +1,10 @@
+# The build context of docker/gpu/Dockerfile: the sources cargo needs, not the
+# build output, local environments or test data (the tests mount the checkout).
+target/
+.venv/
+.git/
+probes/cudss_ubatch/work/
+tests/data/
+docs/book/
+editors/
+scripts/bench/.case-cache/

{gridoxide-0.2.0 → gridoxide-0.3.0}/Cargo.lock

@@ -670,13 +670,14 @@ checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
 
 [[package]]
 name = "gridoxide"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "bindgen",
  "cbindgen",
  "cimoxide-model",
  "faer",
  "gridoxide-core",
+ "gridoxide-gpu",
  "gridoxide-sparse",
  "num-complex",
  "pyo3",
@@ -688,7 +689,7 @@ dependencies = [
 
 [[package]]
 name = "gridoxide-core"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "faer",
  "gridoxide-sparse",
@@ -698,9 +699,22 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "gridoxide-gpu"
+version = "0.3.0"
+dependencies = [
+ "bindgen",
+ "cc",
+ "gridoxide",
+ "gridoxide-core",
+ "gridoxide-sparse",
+ "num-complex",
+ "rayon",
+]
+
 [[package]]
 name = "gridoxide-mcp"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "gridoxide",
  "num-complex",
@@ -709,7 +723,7 @@ dependencies = [
 
 [[package]]
 name = "gridoxide-sparse"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "bindgen",
  "cc",

{gridoxide-0.2.0 → gridoxide-0.3.0}/Cargo.toml

@@ -1,9 +1,12 @@
 [workspace]
-members = ["crates/gridoxide-core", "crates/gridoxide-sparse"]
+# gridoxide-gpu is an optional dependency of gridoxide (the `gpu` feature): a
+# plain `cargo build` here builds only this root package, and the GPU crate
+# builds without CUDA unless its `cuda` feature is on.
+members = ["crates/gridoxide-core", "crates/gridoxide-sparse", "crates/gridoxide-gpu"]
 
 # Shared by every crate in the workspace, so they release in lockstep.
 [workspace.package]
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 repository = "https://github.com/m-mirz/gridoxide"
 
@@ -76,10 +79,13 @@ crate-type = ["cdylib", "rlib", "staticlib"]
 # The sparse LU backends and the vendored SuiteSparse they build on — see
 # crates/gridoxide-sparse. Its modules are re-exported under their old names
 # in src/lib.rs, so `gridoxide::sparse` and the rest resolve as before.
-gridoxide-sparse = { path = "crates/gridoxide-sparse", version = "0.2.0" }
+gridoxide-sparse = { path = "crates/gridoxide-sparse", version = "0.3.0" }
 # The solvers — network model, power flow, state estimation, short circuit —
 # re-exported the same way; see crates/gridoxide-core.
-gridoxide-core = { path = "crates/gridoxide-core", version = "0.2.0" }
+gridoxide-core = { path = "crates/gridoxide-core", version = "0.3.0" }
+# Batched AC power flow on an NVIDIA GPU, re-exported as `gridoxide::gpu`; see
+# the `gpu` feature.
+gridoxide-gpu = { path = "crates/gridoxide-gpu", version = "0.3.0", optional = true }
 faer = "0.24.4"
 num-complex = { version = "0.4.6", features = ["serde"] }
 # Powers `crates/gridoxide-core/src/batch.rs`'s across-scenario parallelism. Not a new build cost:
@@ -279,6 +285,18 @@ opf-ipopt = ["opf", "dep:bindgen"]
 # runner has ARPACK installed — the same local/manual-verification-only position
 # `pardiso`, `opf-highs` and `opf-ipopt` are in.
 smallsignal-arpack = ["dynamics"]
+# Batched AC power flow on one NVIDIA GPU (crates/gridoxide-gpu, re-exported
+# as `gridoxide::gpu`): sweeps and N-1 over cuDSS's uniform batch, every
+# scenario stopped at its own convergence. With `python`, the bindings gain
+# `GpuBatchSolver`. Needs cuDSS 1.0 or later (`CUDSS_DIR`), the CUDA 12
+# toolkit with nvcc and libclang at build time — see
+# crates/gridoxide-gpu/build.rs — and an NVIDIA GPU at run time. Not built or
+# tested in CI, which has no GPU; the published wheel does not ship it.
+#
+# cuDSS is NVIDIA's proprietary library, linked dynamically from the user's
+# install like oneMKL for `pardiso`: nothing of it is redistributed by this
+# crate.
+gpu = ["dep:gridoxide-gpu", "gridoxide-gpu/cuda"]
 # Exports a C ABI (src/capi/) so a C++ project can embed gridoxide, plus the
 # `cbindgen`-generated `include/gridoxide.h` that describes it.
 #
@@ -406,3 +424,13 @@ required-features = ["cgmes"]
 # session with `CARGO_PROFILE_DEV_DEBUG=true`.
 [profile.dev]
 debug = "line-tables-only"
+
+[[example]]
+name = "dc_contingencies_bench"
+path = "examples/dc_contingencies_bench.rs"
+required-features = ["matpower"]
+
+[[example]]
+name = "gpu_probe_dump"
+path = "examples/gpu_probe_dump.rs"
+required-features = ["matpower"]

{gridoxide-0.2.0 → gridoxide-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridoxide
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Requires-Dist: numpy>=1.24 ; extra == 'matpower'
@@ -149,6 +149,24 @@ feature to use them:
 - `"klu"` — links vendored SuiteSparse C directly (`--features python,klu`).
 - `"pardiso"` — Intel oneMKL's PARDISO solver (`--features python,pardiso`, needs `MKLROOT` set).
 
+### Batched power flow on an NVIDIA GPU
+
+Not in the published wheel either: `GpuBatchSolver` needs a build with `--features python,gpu`, with
+cuDSS 1.0 or later (`CUDSS_DIR`) and the CUDA 12 toolkit, or the image `docker/gpu/Dockerfile` builds. It
+solves `solve_batch`'s scenarios and `solve_contingencies`' outage lists on the GPU, every scenario to
+its own convergence, from the model's last `solve()`:
+
+```python
+model = gridoxide.PowerFlowModel.from_matpower("case9241pegase.m")
+model.solve()
+gpu = gridoxide.GpuBatchSolver(model, capacity=1024)  # keeps its analysis for every later call
+results = gpu.solve_batch(scenarios)                 # one BatchResult per scenario, as on the CPU
+outages = gpu.solve_contingencies([[b] for b in range(model.n_branches)])
+```
+
+Outages that split the network are solved on the CPU. On an A100 the GPU pays only on large networks and
+large batches; the CPU's `solve_batch` on all cores is faster on most cases.
+
 ## State estimation
 
 `StateEstimationModel` recovers the most likely grid state from measurements, rather than computing

{gridoxide-0.2.0 → gridoxide-0.3.0}/build.rs

@@ -12,6 +12,25 @@ fn main() {
     arpack::build();
     #[cfg(feature = "capi")]
     capi::build();
+    #[cfg(feature = "gpu")]
+    gpu::build();
+}
+
+/// Puts cuDSS's and the CUDA runtime's library directories on the run path
+/// of this package's artifacts, the Python extension among them, when the
+/// `gpu` feature is enabled. gridoxide-gpu links them, but its run path
+/// reaches only its own tests and examples; it hands the directories on as
+/// `DEP_CUDSS_LIB_DIRS` (see crates/gridoxide-gpu/build.rs). An image that
+/// moves the libraries elsewhere sets `LD_LIBRARY_PATH` instead.
+#[cfg(feature = "gpu")]
+mod gpu {
+    pub fn build() {
+        let dirs = std::env::var("DEP_CUDSS_LIB_DIRS")
+            .expect("gridoxide-gpu's build script sets DEP_CUDSS_LIB_DIRS with its `cuda` feature");
+        for dir in dirs.split(':') {
+            println!("cargo:rustc-link-arg=-Wl,-rpath,{dir}");
+        }
+    }
 }
 
 /// Generates `include/gridoxide.h` from the C ABI in `src/capi/`, only when

{gridoxide-0.2.0 → gridoxide-0.3.0}/capi/CMakeLists.txt

@@ -154,7 +154,7 @@ configure_package_config_file(
 
 write_basic_package_version_file(
     "${CMAKE_CURRENT_BINARY_DIR}/gridoxideConfigVersion.cmake"
-    VERSION 0.2.0
+    VERSION 0.3.0
     COMPATIBILITY SameMinorVersion)
 
 install(FILES

{gridoxide-0.2.0 → gridoxide-0.3.0}/crates/gridoxide-core/Cargo.toml

@@ -12,7 +12,7 @@ categories = ["science", "simulation"]
 license = "Apache-2.0"
 
 [dependencies]
-gridoxide-sparse = { path = "../gridoxide-sparse", version = "0.2.0" }
+gridoxide-sparse = { path = "../gridoxide-sparse", version = "0.3.0" }
 faer = "0.24.4"
 num-complex = { version = "0.4.6", features = ["serde"] }
 # The batch solvers — power flow's and state estimation's — run scenarios

{gridoxide-0.2.0 → gridoxide-0.3.0}/crates/gridoxide-core/src/jacobian.rs

@@ -389,6 +389,24 @@ impl JacobianPattern {
         &self.entries
     }
 
+    /// The fill's first pass, for a device that runs it itself: each
+    /// non-slack row bus with its `Y[i][i]`, owning slots `4d..4d + 4`
+    /// (H, N, M, L).
+    pub fn diag_slots(&self) -> &[(u32, Complex<f64>)] {
+        &self.diag
+    }
+
+    /// Each off-diagonal `(i, k)` pair with `Y[i][k]`, pair `p` owning slots
+    /// `4 · diag_slots().len() + 4p ..` (H, N, M, L).
+    pub fn pair_slots(&self) -> &[(u32, u32, Complex<f64>)] {
+        &self.pairs
+    }
+
+    /// The fill's second pass: the slot each entry copies, in entry order.
+    pub fn slot_sources(&self) -> &[u32] {
+        &self.src
+    }
+
     /// Writes this iteration's Jacobian values into `values`, which is
     /// resized to [`len`](Self::len) and otherwise fully overwritten.
     ///

{gridoxide-0.2.0 → gridoxide-0.3.0}/crates/gridoxide-core/src/linear/mod.rs

@@ -36,7 +36,7 @@ pub use btheta::{
     DcBranch, DcIslandReport, DcIslandStatus, DcSolution, DcSolver, dc_branches, dc_power_flow,
 };
 pub use impedance::{LinearIslandReport, LinearIslandStatus, LinearReport, linear_power_flow};
-pub use sensitivity::{DcSensitivity, DenseMatrix};
+pub use sensitivity::{DcContingencies, DcSensitivity, DenseMatrix};
 
 /// Which terms the DC susceptance keeps.
 ///

{gridoxide-0.2.0 → gridoxide-0.3.0}/crates/gridoxide-core/src/linear/sensitivity.rs

@@ -49,7 +49,7 @@
 //! limitation, as a `TODO PTDF: distributed slack` in the equivalent place.
 
 use crate::types::{Bus, BusType};
-use gridoxide_sparse::sparse::RealFactorization;
+use gridoxide_sparse::klu_native::KluNativeSystem;
 
 use super::btheta::{DcBranch, NOT_UNKNOWN, Partition, partition, reduced_b_triplets};
 use crate::network::Verdict;
@@ -86,10 +86,58 @@ impl DenseMatrix {
     }
 }
 
+/// Angles and flows after each outage of
+/// [`DcSensitivity::contingencies`], outage after outage.
+#[derive(Clone, Debug)]
+pub struct DcContingencies {
+    n_buses: usize,
+    n_branches: usize,
+    /// Per outage, one angle per bus (radians), outage-major.
+    pub angles: Vec<f64>,
+    /// Per outage, one from-end flow per flat branch (per unit), outage-major.
+    pub flows: Vec<f64>,
+    /// Per outage, whether it has a post-outage state; an unsolved outage's
+    /// rows are NaN.
+    pub solved: Vec<bool>,
+}
+
+impl DcContingencies {
+    /// From buffers computed elsewhere (gridoxide-gpu's device solver), in
+    /// this layout: `angles` and `flows` outage-major, NaN rows where
+    /// `solved` is false.
+    pub fn from_parts(
+        n_buses: usize,
+        n_branches: usize,
+        angles: Vec<f64>,
+        flows: Vec<f64>,
+        solved: Vec<bool>,
+    ) -> Self {
+        assert_eq!(angles.len(), solved.len() * n_buses);
+        assert_eq!(flows.len(), solved.len() * n_branches);
+        Self {
+            n_buses,
+            n_branches,
+            angles,
+            flows,
+            solved,
+        }
+    }
+
+    /// Outage `k`'s bus angles.
+    pub fn angles(&self, k: usize) -> &[f64] {
+        &self.angles[k * self.n_buses..(k + 1) * self.n_buses]
+    }
+
+    /// Outage `k`'s branch flows.
+    pub fn flows(&self, k: usize) -> &[f64] {
+        &self.flows[k * self.n_branches..(k + 1) * self.n_branches]
+    }
+}
+
 /// One island's factorized reduced system, plus the bookkeeping to map
 /// between global bus indices and its own rows.
 struct Island {
-    factorization: RealFactorization,
+    factorization: KluNativeSystem,
     /// Reduced row -> global bus index.
     unknown: Vec<usize>,
     /// Positions into `DcSensitivity::branches` for this island's branches.
@@ -99,10 +147,11 @@ struct Island {
 /// Precomputed DC sensitivity factors for one network.
 ///
 /// Holds one factorization per island, computed once. Every accessor below is
-/// a solve against those, never a refactorization — which is the entire reason
-/// [`sparse::RealFactorization`](gridoxide_sparse::sparse::RealFactorization) exists
-/// rather than reusing the Newton path's
-/// [`solver::LinearSolver`](crate::solver::LinearSolver).
+/// a solve against those, never a refactorization: gridoxide's KLU port
+/// ([`KluNativeSystem::solve`]), which solves one right-hand side about twice
+/// as fast as faer's sparse LU on these matrices (290 against 585 µs on
+/// case9241pegase's reduced B) and, unlike faer's solve, never parallelises
+/// on its own, so [`contingencies`](Self::contingencies) owns the threads.
 pub struct DcSensitivity {
     n_buses: usize,
     /// Total flat branch count (lines + transformers), the index space every
@@ -189,7 +238,7 @@ impl DcSensitivity {
             }
 
             let triplets = reduced_b_triplets(branches, &island_branches[ci], &reduced_pos);
-            let factorization = RealFactorization::new(m, &triplets)?;
+            let factorization = KluNativeSystem::new(m, &triplets)?;
 
             let idx = islands.len();
             for &i in &c.bus_indices {
@@ -396,6 +445,110 @@ impl DcSensitivity {
         Some(out)
     }
 
+    /// Every single-branch outage of `outages`, each on its own: the bus
+    /// angles and the branch flows after it.
+    ///
+    /// [`outage_flows`](Self::outage_flows) gives the flows; this adds the
+    /// angles, from the same solve. The outage is the transfer
+    /// `c = f_l / (1 − d_l)` across the branch's terminals that the removed
+    /// branch would have carried, so with `θ⁽ˡ⁾` the angle response to a unit
+    /// transfer (the solve `outage_flows` already makes):
+    ///
+    /// \\[ \theta^{new} = \theta + c\,\theta^{(l)}, \qquad
+    ///     f^{new} = f + c\,\psi[:, l], \quad f^{new}_l = 0 \\]
+    ///
+    /// Reference buses keep their angles, and so does every bus outside the
+    /// outaged branch's island. `base_angles` and `base_flows` are the base
+    /// case's (`Bus::voltage_ang` after a DC solve, per bus, and
+    /// [`DcSolution::branch_p`](super::btheta::DcSolution::branch_p)).
+    ///
+    /// The outages run in parallel on the current rayon pool, one triangular
+    /// solve each against the factorization computed once in
+    /// [`new`](Self::new); install a pool around the call to choose the
+    /// thread count. An outage with no post-outage state (a radial branch,
+    /// one out of range or carrying no DC flow) is marked unsolved and its
+    /// rows are NaN. `None` only if the base vectors have the wrong length.
+    pub fn contingencies(
+        &self,
+        base_angles: &[f64],
+        base_flows: &[f64],
+        outages: &[usize],
+    ) -> Option<DcContingencies> {
+        use rayon::prelude::*;
+        if base_angles.len() != self.n_buses || base_flows.len() != self.n_branches {
+            return None;
+        }
+        let (n, m) = (self.n_buses, self.n_branches);
+        // Zeroed, not NaN-filled: a zeroed allocation is mapped lazily, so the
+        // workers touch its pages in parallel, where filling 2.9 GB first
+        // (case9241pegase's full N-1) took a second on one thread.
+        let mut out = DcContingencies {
+            n_buses: n,
+            n_branches: m,
+            angles: vec![0.0; outages.len() * n],
+            flows: vec![0.0; outages.len() * m],
+            solved: vec![false; outages.len()],
+        };
+        out.angles
+            .par_chunks_mut(n.max(1))
+            .zip(out.flows.par_chunks_mut(m.max(1)))
+            .zip(out.solved.par_iter_mut())
+            .zip(outages.par_iter())
+            .for_each(|(((angles, flows), solved), &l)| {
+                *solved = self.one_contingency(base_angles, base_flows, l, angles, flows);
+                if !*solved {
+                    angles.fill(f64::NAN);
+                    flows.fill(f64::NAN);
+                }
+            });
+        Some(out)
+    }
+
+    /// One outage of [`contingencies`](Self::contingencies) into its rows;
+    /// `false` (rows untouched) if it has no post-outage state.
+    fn one_contingency(
+        &self,
+        base_angles: &[f64],
+        base_flows: &[f64],
+        l: usize,
+        angles: &mut [f64],
+        flows: &mut [f64],
+    ) -> bool {
+        let Some((br, island)) = self.branch_and_island(l) else {
+            return false;
+        };
+        let mut rhs = vec![0.0; island.unknown.len()];
+        if self.reduced_pos[br.from] != NOT_UNKNOWN {
+            rhs[self.reduced_pos[br.from]] += 1.0;
+        }
+        if self.reduced_pos[br.to] != NOT_UNKNOWN {
+            rhs[self.reduced_pos[br.to]] -= 1.0;
+        }
+        let Some(theta) = island.factorization.solve(&rhs) else {
+            return false;
+        };
+        let angle = |bus: usize| match self.reduced_pos[bus] {
+            NOT_UNKNOWN => 0.0,
+            r => theta[r],
+        };
+        let d = br.b * (angle(br.from) - angle(br.to));
+        if (1.0 - d).abs() < LODF_BRIDGE_TOL {
+            return false;
+        }
+        let c = base_flows[l] / (1.0 - d);
+        angles.copy_from_slice(base_angles);
+        for (r, &bus) in island.unknown.iter().enumerate() {
+            angles[bus] += c * theta[r];
+        }
+        flows.copy_from_slice(base_flows);
+        for &pos in &island.branch_positions {
+            let b = &self.branches[pos];
+            flows[b.index] += c * b.b * (angle(b.from) - angle(b.to));
+        }
+        flows[l] = 0.0;
+        true
+    }
+
     /// Whether removing every branch in `branches` at once would disconnect the
     /// network, leaving no post-outage flows to compute.
     ///

gridoxide-0.3.0/crates/gridoxide-gpu/Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "gridoxide-gpu"
+description = "gridoxide's batched AC power flow for NVIDIA GPUs: an adaptive Newton loop over cuDSS's uniform batch"
+version.workspace = true
+edition.workspace = true
+repository.workspace = true
+license = "Apache-2.0"
+# Links cuDSS (with the `cuda` feature), and hands its library directories to
+# dependents as DEP_CUDSS_LIB_DIRS; see build.rs.
+links = "cudss"
+# The tests and examples need gridoxide, a dev-dependency the published crate
+# cannot carry (see below), so they stay out of the package.
+exclude = ["tests/", "examples/"]
+
+[dependencies]
+gridoxide-core = { path = "../gridoxide-core", version = "0.3.0" }
+gridoxide-sparse = { path = "../gridoxide-sparse", version = "0.3.0" }
+num-complex = "0.4.6"
+# The CPU hand-off's scenarios in parallel, on the pool gridoxide's CPU
+# BatchSolver shares (already in the dependency tree).
+rayon = "1.12"
+
+[dev-dependencies]
+# The tests and the counting example read MATPOWER cases through gridoxide's
+# reader. A dev-dependency only, and without a version on purpose: gridoxide
+# depends on this crate (its `gpu` feature), so the cycle must not reach the
+# registry, and `cargo publish` drops a dev-dependency that has no version.
+gridoxide = { path = "../..", features = ["matpower"] }
+
+[build-dependencies]
+bindgen = { version = "0.72", optional = true }
+cc = { version = "1.2", optional = true }
+
+[features]
+default = []
+# The cuDSS backend, `CudssUniformBatch` (src/cudss.rs), and the Newton step's
+# kernels, `DeviceBatch` (src/device.rs, cuda/kernels.cu). Off by default so
+# this crate, and the workspace, build and test without CUDA. Needs libclang
+# (for bindgen), CUDSS_DIR and the CUDA 12 toolkit with nvcc (CUDA_ARCH,
+# default sm_80); build.rs says what each is. On a machine without CUDA it can
+# still be type-checked against the probe's stub headers, nvcc skipped:
+#   CUDSS_DIR=<cudss> CUDA_INCLUDE_DIR=$PWD/probes/cudss_ubatch/stub \
+#     GRIDOXIDE_GPU_NO_NVCC=1 cargo check -p gridoxide-gpu --features cuda --all-targets
+cuda = ["dep:bindgen", "dep:cc"]