Results and Output Reference

ACPFlowReport

Structured container for AC power flow results.

The vectors (nodes, branches, links, transformer_controls, q_limit_events) are table-like and can be converted directly to DataFrames if DataFrames.jl is available, e.g. DataFrame(report.nodes).

Fields

• metadata: Global run/case metadata (solver, tolerance, elapsed time, losses, ...).
• nodes: Per-bus electrical state and power balance values.
• branches: Per-branch directional flows and losses.
• links: Link-flow values from KCL post-processing.
• transformer_controls: Tap-controller state rows with typed missing for non-applicable engineering values.
• q_limit_events: PV→PQ limit-hit markers.
• hvdc_links: One row per HVDC link (net.hvdcLinks): terminal flows, loss, mode, rating, controller status (see _hvdc_link_flow_rows).

buildACPFlowReport(net::Net; ...)

Builds a structured report object from solved network data. This provides a machine-readable alternative to printACPFlowResults.

printACPFlowResults(net, ...; kwargs...)

Print the solved power-flow result tables (buses, branches, summary) to the console or a file.

printProsumerResults(net)

Print the per-machine result table of the solved network.

calcLinkFlowsKCL!(net::Net; tol::Float64 = 1e-6)

Compute bus-link active/reactive flows from nodal KCL after a power-flow run, without introducing links into the YBUS matrix. Link direction uses the fromBus -> toBus sign convention.

For each bus i: sum(Plink,out - Plink,in) = Pinj(i) - Pbranch,out(i) (and analog for Q).

Algorithm overview:

1. Build net nodal injections P_inj/Q_inj from static generation minus load.
2. Add solved shunt injections (node._pShunt/_qShunt) to nodal injections.
3. Subtract outgoing terminal branch powers to get the link right-hand side b.
4. Build oriented incidence matrix A for active links.
5. Solve per connected link component (BFS) using pinv(A_component) * b_component.
6. If sum(b_component) is not near zero, distribute the residual uniformly before solving so the component system becomes consistent.
7. Write resulting link P/Q flows and derive terminal currents from |S| and V_LL.

Notes:

• tol is only used for the component residual-balancing step.
• For meshed/singular components (e.g., rings), pinv yields the minimum-norm least-squares solution consistent with KCL.

calcLinkFlowsSE!(net; tol=1e-6) -> Union{Nothing,Vector{NamedTuple}}

W2 link-flow allocation with measurements (SE phase 3): the KCL allocation of calcLinkFlowsKCL! extended to a weighted least-squares split per link component. Active link flow measurements on net.measurements (PflowMeas/ QflowMeas with a linkIdx) enter as extra rows f_j = z_j with weight 1/sigma^2 (P rows into the P solve, Q rows into the Q solve); the nodal balance rows keep weight 1. With no link measurements the result equals calcLinkFlowsKCL! exactly (shared core, identical code path).

Link measurements constrain only the flow split, never the system state: the estimator excludes them from the WLS (the link is not in the Ybus).

The balance construction reads solved branch flows (fBranchFlow/ tBranchFlow, filled by calcNetLosses!, which runse!(updateNet = true) calls) and the shunt injections (node._pShunt/_qShunt, refreshed by the SE write-back). Run after runse! with updateNet = true.

Returns one row per active link: (linkIdx, name, pFlow_MW, qFlow_MVar, source, p_meas_residual, q_meas_residual) with source = :kcl (no measurement on that link) or :measured_ls, and the measurement residuals f_est - z (NaN when unmeasured). nothing when the net has no active link.

calcNetLosses!(net::Net, V::Vector{ComplexF64})

Calculates branch flows and network losses using an externally provided complex voltage vector V (typically from the final NR residual).

calcNetLosses!(net::Net)

Calculates branch flows and network losses for the given network.

This default method builds the complex voltage vector internally and forwards to calcNetLosses!(net, V). If the NR solver already has V available, it can call the two-argument variant directly to avoid recomputing V.

_build_transformer_control_rows(net::Net)

Internal helper that mirrors transformer control state into table-like rows for ACPFlowReport.

Notes:

• Rows are intentionally typed for DataFrame conversion.
• Non-applicable controller fields remain missing (not placeholder strings).

_distributed_slack_bus_pgen(net, bus_idx, dp_mw) -> (scheduled, delivered)

Scheduled and delivered active generation (MW) of a bus that takes part in the distributed slack with the correction dp_mw: the schedule of its units and the schedule plus dp_mw. The delivered value holds at every bus type: the solve makes the P residual of each participant, the reference included, equal to its share. It is not read from the solved bus value, which carries the share only where the solver wrote P (a reference bus, also one an island solve promoted from PV) and the schedule elsewhere.

_distributed_slack_bus_shares(net) -> (active::Bool, shares::Dict{Int,NTuple{2,Float64}})

Per-bus distributed-slack participation for the result readers: bus index to (alpha, dp_mw), summed over the participating units of a bus (see _distributed_slack_unit_shares). A unit counts at the bus it sits on in net, which in a link cluster is its own bus, not the representative the solver saw. active is false when the last solve ran without the distributed slack or no solver status exists.

_fitColumn(text, width) -> String

Trim text to width characters, marking the cut with …. Fixed-width @sprintf fields pad but never truncate, so long names — CGMES bus and branch identifiers routinely exceed 25 characters — would otherwise push every following column out of alignment.

_hvdc_link_flow_rows(net) -> Vector{NamedTuple}

One row per HvdcLink for the HVDC Link Flows table, ACPFlowReport, and the CSV export. Sign convention: p_from_MW is the power leaving the from bus into the link (positive for export), p_to_MW the power delivered into the to bus. With an attached controller the values come from its setpoints and live terminal state (mode is the controller mode); without one they come from the terminal prosumers (mode = :fixed, loss = -(P_from_injection + P_to_injection) in the MATPOWER convention where the from injection is negative).

_print_distributed_slack_summary_line(io, net)

One line inside the classical result header when the last solve ran with the distributed slack active: mode, the solved lambda_P, and the participant count. The per-bus participation itself lives in the bus table (columns dSl alpha and Pg eff MW, see _distributed_slack_bus_shares). Prints nothing when the feature was off or the net has no rectangular solver status.

_print_wrong_branch_summary_line(io, net)

Prints a single console/log line summarizing the wrong-branch detection outcome when it is suspect or invalid (status is neither :ok nor :not_checked). Clean runs and disabled detection print nothing, keeping logs stable for the common case.

_closed_branch_flow_pu(V, from, to, br, tapSide) -> ComplexF64

Complex branch power S_ij in per unit from bus from to bus to of a fully CLOSED branch, evaluated on the complex voltage vector V. This is the flow formula calcNetLosses! uses (extracted so the contingency screening can estimate loadings from a trial voltage vector without writing the net); tapSide says which terminal carries the tap (1 = from, 2 = to).

system_csv_format() -> String

The CSV format that output.csv_format = auto resolves to on this machine: excel_de when the user's regional settings use a decimal comma, excel_us when they use a decimal point, technical otherwise.

The regional setting is read where the operating system keeps it. A POSIX locale variable (LC_ALL, then LC_NUMERIC, then LANG) wins on every system; without one, Windows answers from the Region settings of the signed-in user (GetLocaleInfoEx), the source Excel uses. The portable locale (C, POSIX, C.UTF-8), no locale on Linux, and other systems (macOS, BSD) give technical. A locale name the system does not know gives technical with a warning naming it (once per session). Evaluated on every call, so a changed regional setting applies to the next run.

_config_with_request_csv_format(config, csv_format) -> SparlectraConfig

The run's configuration with the request-level CSV format (the Web UI run form field, the deprecated API keyword) folded into output.csv_format: every run type (power flow, state estimation, contingency, short circuit) then writes all of its CSV files in the format the form named, instead of the two detailed exports only. nothing keeps the configuration's value. Throws ArgumentError on an unknown format name.

result_csv_delimiter(line) -> Char

The delimiter a result CSV header line was written with (; or ,), for readers that accept both formats of output.csv_format.

result_csv_format() -> String

The CSV format name of result artifacts, output.csv_format of the active configuration (technical, excel_de, excel_us). Writers that are called without an explicit format take it from here, so a run writes every artifact in one format.

write_result_csv(path, header, rows; format = result_csv_format(), comments = String[]) -> path
write_result_csv(io::IO, header, rows; format = result_csv_format(), comments = String[])

Write one result CSV: optional # comment lines, the header, one line per row. rows is any iterable of iterables (tuples, vectors, generators); every cell goes through the shared formatting (_csv_field): numbers get the decimal and thousands separators of format, strings are quoted when they contain the delimiter, a quote or a line break, nothing/missing become empty cells. format is a format name (technical, excel_de, excel_us) or an already resolved format; the default is the central setting output.csv_format of the active configuration.

_perf_profile_child(profile) -> Dict{Symbol,Any} | nothing

Create a fresh per-worker profile for a parallel work item (thread-safety Phase 1). Returns nothing when profile is not an enabled profile Dict; otherwise a new Dict carrying only the read-only seed keys (_PERF_PROFILE_CHILD_KEYS). Workers write timings, iteration rows, and scalar diagnostics into their child only; the orchestrator folds children back with _perf_profile_merge! after fetch, so the parent Dict is never touched concurrently.

_perf_profile_merge!(parent, child, prefix::AbstractString)

Fold a worker's child profile into the parent (serial, orchestrator-only). :timings rows are SUMMED into the parent's :timings under their original phase names, so the phase-name set of a parallel run stays identical to the serial run (calls/elapsed/bytes accumulate exactly like the serial loop did). :iterations rows are appended in call order. Every other child key is copied under Symbol(prefix, key) so per-worker scalars (backend names, matrix stats, start-projection summaries) stop overwriting each other. The wall-clock of the orchestrating fan-out is accounted separately by the caller via _perf_profile_add!(parent, :parallel_wall_time, elapsed, 0), which keeps serial-sum versus wall-clock visible in performance.log.

runtime_session_kind() -> Symbol

:app inside a packaged application (SPARLECTRA_APP_BUILT is set), :sysimage when the process runs on a custom system image, :native on the stock Julia image. The application layer refines :sysimage with the build time of its image; the core only needs to know whether a first run will pay for compilation.

sparlectra_abort_requested() -> Bool

True when the surrounding Web UI job has been asked to abort. Solver loops call this once per iteration and stop with PowerFlowAborted. Works inside spawned tasks as well, which task-local storage does not.