Crate surge_dc 

Surge DC — DC power flow solver and linear sensitivity analysis.

DC Power Flow: Fundamental Assumptions

The DC power flow model makes three simultaneous approximations to linearize the AC power flow equations:

1. Flat voltage profile — all bus voltage magnitudes are assumed to be 1.0 p.u. (|V_i| = 1.0 for all buses). This eliminates the voltage magnitude unknowns and decouples P from Q.

2. Small angle differences — the sine of the voltage angle difference across each branch is replaced by the angle itself: sin(theta_i - theta_j) ≈ theta_i - theta_j. Valid when angle differences are small (typically < 10-15 degrees).

3. Lossless branches — branch resistance is neglected (r ≈ 0, so that g_ij ≈ 0 and the branch admittance is purely imaginary: y_ij ≈ -j/x_ij). This means real power losses (I^2 R) are not captured.

Together, these yield the linear system:

P = B' * theta

where B' is the bus susceptance matrix (with the slack bus row/column removed) and theta is the vector of bus voltage angles. This system is solved with a single sparse LU factorization (KLU) — no iteration required.

What DC Power Flow Does NOT Compute

Because of the three approximations above, DC power flow does not produce:

• Voltage magnitudes — reported as 1.0 p.u. for all buses (assumed, not computed).
• Reactive power flows — reported as 0.0 for all buses and branches.
• Real power losses — the lossless assumption means branch losses are zero.
• Voltage-dependent load behavior — all loads are treated as constant-power at 1.0 p.u.

For precise power flow results including losses, reactive power, voltage magnitudes, and voltage-dependent loads, use the AC Newton-Raphson solver in surge_ac.

When to Use DC Power Flow

DC power flow is the industry standard for applications where speed and linearity matter more than exact voltage/reactive results:

• ISO/RTO real-time market clearing — all US ISOs (ERCOT, PJM, MISO, CAISO, SPP, NYISO, ISO-NE) use DC power flow in their Security-Constrained Economic Dispatch (SCED) and Locational Marginal Price (LMP) engines.
• Contingency screening — PTDF/LODF-based N-1 and N-2 screening is orders of magnitude faster than AC re-solve for each contingency.
• Transfer capability studies — ATC/TTC/AFC calculations per NERC methodology.
• Shift factor computation — GSF, BLDF, PTDF, LODF for market and planning analysis.
• Injection capability heatmaps — FERC Order 2023 interconnection study requirements.

Module Structure

• Top-level exports provide the canonical public API.
• streaming exposes advanced lazy LODF/N-2 column builders.
• Internal modules cover the DC solver kernel and one-shot sensitivity wrappers.

Transfer capability analysis (ATC/TTC/AFC, DFAX, stability-limited transfer) has been consolidated in the surge_transfer crate.

Modules

streaming

Lazy streaming builders for LODF and N-2 LODF column computation.

Structs

DcAnalysisRequest

Canonical request for a one-pass DC sensitivity workflow.

DcAnalysisResult

Result of the canonical one-pass DC sensitivity workflow.

DcPfOptions

Options controlling the DC power flow solve.

DcPfSolution

Result of a DC power flow computation.

DcSensitivityOptions

Options for PTDF and OTDF sensitivity wrappers.

LodfMatrixRequest

Advanced request for one-shot dense all-pairs LODF computation.

LodfMatrixResult

Dense all-pairs LODF result for one branch set.

LodfPairs

Sparse LODF entries keyed by (monitored_branch_idx, outage_branch_idx).

LodfRequest

Advanced request for one-shot subset LODF computation.

LodfResult

Rectangular LODF result for explicit monitored and outage branch sets.

N2LodfBatchRequest

Advanced request for one-shot batched N-2 computation.

N2LodfBatchResult

Batched N-2 LODF result for ordered outage pairs.

N2LodfRequest

Advanced request for one-shot N-2 computation.

N2LodfResult

N-2 LODF result for one ordered outage pair.

OtdfRequest

Advanced request for one-shot OTDF computation.

OtdfResult

OTDF vectors stored in monitored-by-outage order with dense row-major bus data.

PreparedDcStudy

Prepared DC solve model for a network.

PtdfRequest

Advanced request for one-shot PTDF computation.

PtdfRows

PTDF rows stored in monitored-branch order with dense row-major bus data.

Enums

AngleReference

Reference angle convention for reported bus voltage angles.

DcError

Errors arising from DC power flow or sensitivity computation.

DcSensitivitySlack

Slack-balancing policy for PTDF and OTDF sensitivity wrappers.

DistributedAngleWeight

Weighting scheme for AngleReference::Distributed.

Functions

compute_lodf

Compute LODF values for monitored and outage branch sets.

compute_lodf_matrix

Compute a dense all-pairs LODF matrix.

compute_lodf_pairs

Compute selected LODF entries as a sparse pair map.

compute_loss_sensitivities_adjoint

Compute DC marginal loss sensitivities with one sparse adjoint solve.

compute_n2_lodf

Second-order LODF sensitivity for a simultaneous double outage (N-2).

compute_n2_lodf_batch

Compute batched N-2 LODF for multiple simultaneous double-outage pairs.

compute_otdf

Compute Outage Transfer Distribution Factors (OTDF).

compute_ptdf

Compute PTDF rows for monitored branches.

run_dc_analysis

Compute the canonical DC power flow + sensitivity workflow for one network.

solve_dc

Solve DC power flow for a network using default options (single slack).

solve_dc_opts

Solve DC power flow for a network with explicit options.

to_pf_solution

Convert a DC power flow result into the common PfSolution format.