Short-Circuit Reference

ShortCircuitResult

Result of one runShortCircuit! evaluation (one case, one or many fault buses). Deliberately a separate type — it neither extends nor embeds into ACPFlowReport (precedent: rundcpf! with its own report type).

Fields

• case::Symbol: :max or :min.
• base_mva::Float64: network power base used for the per-unit assembly.
• c_factor_override::Float64: 0.0 = IEC 60909-0 Table 1 by voltage level; positive = the scalar override used for every bus.
• rows::Vector{NamedTuple}: one row per requested fault bus with bus (name), bus_idx, vn_kV, island, status (:ok / :no_source / :isolated), c, zk_ohm, rx_ratio, ik_kA, sk_MVA, kappa, ip_kA, contains_defaulted_data, reasons. Safety-flag contract: whenever a source value was substituted with a documented default or a contribution was skipped, the affected rows carry contains_defaulted_data = true plus the reason list — for the :max case a skipped contribution makes ik_kA a lower bound, which is the non-conservative direction for equipment rating.
• messages::Vector{String}: the run's warnings/notices (same texts that were logged).

_takahashi_diag(F) -> (diagZ::Vector{ComplexF64}, ok::Bool, info::String)

Compute the full diagonal of inv(A) from the UMFPACK factorization F of A via the Takahashi/Erisman-Tinney selected-inverse recurrences on the filled factor pattern: one backward pass over nnz(L) + nnz(U) entries instead of one triangular solve per bus, the algorithmic alternative for all-bus short-circuit sweeps (measured 34x to 264x over the serial sweep between n = 2000 and n = 16000, agreeing with direct solves to about 1e-15 relative).

Applicability guard: requires the symmetric pivot ordering (F.p == F.q) that UMFPACK's symmetric strategy picks on the structurally symmetric Ysc; with an unsymmetric ordering the original-diagonal positions leave the factor pattern. Returns ok = false with the reason in info in that case (or on a pattern-closure violation, counted defensively); callers must fall back to per-bus solves.

printShortCircuitResult(io::IO, result::ShortCircuitResult; max_rows = 50)
printShortCircuitResult(result::ShortCircuitResult; max_rows = 50)

Pretty-print a ShortCircuitResult: one table row per fault bus (Ik'', Sk'', kappa, i_p, flag column), followed by the reason list of every flagged row. The Web UI "Short circuit" run writes the same rows as short_circuit_max.csv / short_circuit_min.csv.

runShortCircuit!(net, sc_data; buses = :all, case = :max, c_factor = 0.0) -> ShortCircuitResult
runShortCircuit!(result::CGMESImporter.CGMESImportResult; kwargs...) -> ShortCircuitResult

Balanced 3-phase initial symmetrical short-circuit current per IEC 60909-0 (issue #277): equivalent voltage source at the fault location, positive sequence only, series impedances only.

• sc_data: the CGMES short-circuit harvest (CGMESImportResult.shortcircuit).
• buses: :all (per-bus sweep as a loop over the per-bus path) or a vector of bus names.
• case: :max (equipment rating, c_max) or :min (protection sensitivity, c_min). Asynchronous machines never contribute to :min.
• c_factor: 0.0 uses the hardcoded IEC 60909-0 Table-1 values per voltage level (short_circuit.c_factor carries the same semantics in YAML); a positive scalar overrides the table for every bus.

Per fault bus the short-circuit impedance is obtained by a Z-bus column solve: one sparse LU factorization per island and case, one triangular solve per fault bus — the full inverse is never formed. Outputs per bus: Ik'' (kA), Sk'' (MVA), and kappa/i_p from the R/X ratio at the fault location (IEC 60909-0 method b: κ = min(1.15·(1.02 + 0.98·e^{-3R/X}), cap) with cap 1.8 below 1 kV and 2.0 above).

Substituted defaults and skipped contributions are flagged on the affected result rows (contains_defaulted_data + reasons), not only logged — for :max a skipped contribution makes the result a lower bound. Buses in islands without any short-circuit source report status = :no_source with NaN currents; isolated buses report status = :isolated.

The function does not modify net; the ! marks it as the acting entry point of the module family (runpf!, rundcpf!). Failure behavior: throws ArgumentError for an unknown bus name or an invalid case.

All-bus sweeps fan out over Julia threads (Phase 3 of the multi-core work): the fault-bus list is split into runtime.parallel.max_tasks chunks, each task solving on its own copy of the island factorization with reusable RHS/solution buffers. Results are row-identical to the serial sweep. The keywords parallel_enabled, parallel_max_tasks, and parallel_min_work_items override the active runtime.parallel.* configuration (nothing = use the configured values); with one Julia thread or below min_work_items fault buses the sweep runs serially.

sweep_method = :takahashi (opt-in; default :solves) computes all Thevenin impedances of an island in ONE selected-inverse pass over the factorization instead of one triangular solve per bus (_takahashi_diag; measured 34x to 264x over the serial sweep, growing with island size). Values agree with :solves to machine precision but not bitwise; islands where the method does not apply (unsymmetric pivot ordering) automatically fall back to solves.

NativeShortCircuitData

Short-circuit source records of a natively built network (addExternalGrid!), consumed by runShortCircuit! exactly like the CGMES harvest.

Deliberately field-identical to CGMESImporter.CGMESShortCircuitData and not related to it through a common supertype: the short-circuit engine is duck-typed over the record contract (issue #299 task decision) — the six Vector{NamedTuple} fields with their tuple keys ARE the interface, and a type hierarchy would suggest a coupling that does not exist. Keep both structs in sync field-by-field when the contract evolves.

All-empty by default; addExternalGrid! fills external_network_injections. The remaining vectors exist so the engine's machine/equivalent loops iterate empty collections instead of needing per-container special cases.