Configuration Reference

The benchmark configuration section: repeated-run measurement of a case (enabled, samples, seconds).

DcPowerFlowConfig

Typed configuration for the standalone DC power flow (rundcpf!), used when power_flow.solver == :dc.

angle_reference_deg is the uniform angle offset added to every bus after the slack-referenced linear solve (the slack bus itself is fixed at this reference) — see solve_dc_powerflow for why this post-hoc shift is exact. ignore_out_of_service documents that status == 0 branches are always excluded from the B′ assembly (there is currently no supported way to include them; the field exists for forward compatibility with the YAML schema, not as a live toggle).

The diagnostics configuration section (deprecated keys live on in output); retained so old files keep loading.

MatpowerExportConfig

Typed MATPOWER export configuration.

write_solution selects whether writeMatpowerCasefile writes the solved AC power-flow state back into the exported case:

• true (default): mpc.bus VM/VA reflect the solved node state and mpc.branch gains the standard MATPOWER result columns 14–17 (PF, QF, PT, QT), sourced from the existing branch-flow report path. A mpc.sparlectra.solution_written = 1 marker documents this. If the network has not been solved, the exporter warns and falls back to the 13-column model-only export instead of writing empty result columns.
• false: the export is a pure model file. mpc.branch keeps its historical 13 columns, and VM = 1.0/VA = 0.0 for all non-slack/non-PV buses (slack and PV setpoints are preserved).

MatpowerImportConfig

Typed MATPOWER import/example configuration for case selection and import conventions.

ModelConfig

Typed model-construction configuration, the model: block: how any imported case becomes a network, independent of its format (design decision D6 of the adapter task; the keys lived in matpower_import and transformer before, version-0 files are rewritten through the alias table).

bus_shunt_model selects how bus shunts enter the admittance model.

tap_changer_model selects how transformer tap changers act on the equivalent circuit:

• :ideal — tap steps only change the complex winding ratio; the series impedance keeps its neutral-position value (no impedance feedback; previous Sparlectra behavior).
• :impedance_correction — tap steps additionally re-refer the transformer series impedance through the tapped winding (R and X scaled with |1 + f·e^(jφ)|², implemented centrally in src/equicircuit.jl).

The option applies to all transformers of an imported case and is read by every importer.

auto_profile (:off, :recommend, :apply) drives the read-only import analysis with convention recommendations; auto_profile_log writes its artifact. net_cache_enabled gates the binary net cache (active only while auto_profile is :off). preallocate_network/preallocate_min_buses control container preallocation for large cases.

ObservabilityConfig

State-estimation observability diagnostic configuration.

OutputConfig

Typed output and logfile-format configuration. Console and logfile result streams are intentionally independent so example runners can disable classic logfile tables without suppressing compact console progress.

ParallelRuntimeConfig

Typed configuration of the in-process parallel execution of independent work items (island solves, short-circuit sweeps, contingency batches). enabled = false forces every parallel site onto the serial path (the serial functions themselves, not copies). max_tasks = "auto" resolves to Threads.nthreads(); an integer string caps the task count (applied via chunking, so it caps Threads.@threads sites too). Work lists shorter than min_work_items run serially to avoid task overhead on tiny cases.

PerformanceConfig

Typed performance and diagnostic-volume configuration.

PowerFlowConfig

Typed power-flow configuration. It owns solver tolerances, sparse execution settings, automatic damping, start-mode controls, and Q-limit behavior.

QLimitConfig

Typed reactive-power limit switching configuration used by power-flow runners.

RuntimeConfig

Typed runtime/threading configuration for example and benchmark entry points.

SparlectraConfig

Central typed configuration assembled once at application or example boundaries. Module-specific sections own their parsing and validation through constructors such as PowerFlowConfig(raw) and MatpowerImportConfig(raw).

StartModeConfig

Typed power-flow start-option configuration. These fields collect the flat-start and rectangular start-projection controls that otherwise tend to be forwarded as long keyword lists through example and benchmark call chains.

active_sparlectra_config() -> SparlectraConfig

The configuration the process currently runs with, as set by set_sparlectra_config! or the last load_sparlectra_config!.

benchmark_config() -> BenchmarkConfig

The benchmark section of the active configuration.

configuration_path_from_inputs(; env_var, fallback_paths) -> String

Resolve which configuration file a process should load: the environment variable first, then the first existing fallback path, then the packaged default template.

configured_matpower_cases(config) -> Vector{String}

Return configured cases in deterministic execution order. A non-empty runtime.cases list takes precedence over the compatible single-case runtime.case setting.

diagnostics_config() -> DiagnosticsConfig

The diagnostics section of the active configuration.

load_sparlectra_config(user_path; default_path, reload, cli_overrides, overrides) -> SparlectraConfig

Load the configuration from the user YAML over the packaged defaults, apply overrides, and return it WITHOUT installing it as the active configuration. Results are cached per path unless reload is set.

load_sparlectra_config!(user_path; default_path, reload, cli_overrides, overrides) -> SparlectraConfig

Like load_sparlectra_config, and additionally installs the result as the active configuration of the process.

matpower_export_config() -> MatpowerExportConfig

The matpower_export section of the active configuration.

matpower_import_config() -> MatpowerImportConfig

The matpower_import section of the active configuration.

model_config() -> ModelConfig

The model section of the active configuration: how an imported case becomes a network (bus shunt model, tap changer model, auto profile, net cache, preallocation).

output_config() -> OutputConfig

The output section of the active configuration.

parallel_max_tasks(cfg::ParallelRuntimeConfig) -> Int

Resolve the configured runtime.parallel.max_tasks to a concrete task count: "auto" yields Threads.nthreads(), an integer string yields that number (validation guarantees it is positive).

performance_config() -> PerformanceConfig

The performance section of the active configuration.

powerflow_config() -> PowerFlowConfig

The power_flow section of the active configuration.

print_effective_config([io], config::SparlectraConfig)

Print an Effective Sparlectra Configuration block with typed module sections.

refresh_sparlectra_config_file(path; write=false, backup=true, normalize_deprecated=true, default_path=DEFAULT_SPARLECTRA_CONFIG_PATH)

Compare a user YAML configuration with the current Sparlectra template, add missing keys from the template, and optionally normalize documented deprecated aliases. Dry-run mode returns the refreshed YAML without writing. Writes are explicit and create a timestamped backup unless backup=false is requested.

refresh_sparlectra_config_text(text; normalize_deprecated, default_path) -> String

Rewrite a configuration YAML text against the packaged template: missing keys are added with their defaults and comments, deprecated keys are normalized, user values are kept. Used by the Web UI configuration refresh.

runtime_config() -> RuntimeConfig

The runtime section of the active configuration.

set_sparlectra_config!(cfg) -> SparlectraConfig

Install cfg as the active configuration of the process, replacing the one every *_config() accessor returns.

state_estimation_config() -> StateEstimationConfig

The state_estimation section of the active configuration.

Dotted configuration keys accepted from GUI/API override input.

validate_gui_config_overrides(config_overrides) -> Dict{String,Any}

Validate GUI-supplied dotted configuration keys and return the equivalent nested configuration dictionary. Only GUI_EDITABLE_CONFIG_KEYS are accepted. Invalid keys, types, enum values, and ranges throw ArgumentError before power-flow execution.

as_bool(x)::Bool

Convert YAML booleans or boolean-like strings (true, false, yes, no, on, off) to Bool. Invalid values throw an ArgumentError.

as_int_vector(x)::Vector{Int}

Convert an integer or a one-dimensional vector of integer values to Vector{Int}. Invalid values throw an ArgumentError.

load_yaml_dict(path::AbstractString)::Dict{String,Any}

Load a simple YAML file into a Dict{String,Any}.

Only the subset used by Sparlectra examples is supported: comments beginning with #, 2-space-indented nested dictionaries, scalar key-value pairs, and one-line scalar lists. Invalid indentation and unsupported lines throw clear errors. Use a full YAML package for general YAML documents.

merge_yaml_dict!(dst::Dict{String,Any}, src::Dict{String,Any})

Recursively merge YAML dictionaries from src into dst and return dst. Nested dictionaries are merged; non-dictionary values replace existing values.

parse_yaml_scalar(raw::AbstractString)

Parse one scalar value from Sparlectra's small dependency-free YAML subset.

This parser is intended for example and benchmark configuration files. It is not a general-purpose YAML implementation. Supported scalars are booleans, null/~, integers, floating-point numbers, symbols written as :name, quoted strings, unquoted strings, and one-line scalar lists such as [100, 300, 500].

Current version of the configuration file format. Files declare theirs with the top-level key config_version; a file without it reads as version 0 and the alias tables below are applied stepwise, so old files keep loading while only this file knows old key names (design decision D9 of the adapter task).

ApslfConfig

Typed configuration for the AnalyticLoadFlow.jl-backed analytic power-series solver (ApslfSolver), used when power_flow.solver == :apslf.

ApslfStartConfig

Typed configuration for using the analytic power-series solver as a start-value generator ahead of the rectangular Newton-Raphson solve. Deliberately has no use_pade/nr_polish fields: polishing is left to the downstream NR solve, so the generator always runs with nr_polish=false internally.

CGMESImportConfig

Options of the cgmes_import configuration block — the ENTSO-E CGMES import (see importCGMES). path accepts a folder, a ZIP, or several of both (base case plus boundary set) separated by ;.

Fields

• path::String: delivery location(s); ;-separated for multi-part deliveries.
• base_mva::Float64: system base, which CGMES does not define.
• require_boundary::Bool: fail when topology references stay unresolved.
• tap_control::Bool: start from the SSH tap positions and attach the CGMES-defined outer-loop tap controllers instead of importing the solved SvTapStep positions as fixed taps.
• machine_control::Bool: attach outer-loop remote voltage controllers (MachineVoltageControl) for machines whose voltage RegulatingControl points at a different bus, instead of holding those machines PV at their own bus.
• ignore_connected::Bool: diagnostic override that treats every terminal as connected, for snapshots whose SSH flags contradict their own SV state.
• vset_min_pu, vset_max_pu::Float64: plausibility band for a voltage RegulatingControl.targetValue, in p.u. of the regulated bus's nominal voltage. A target outside the band is treated as a placeholder: it is ignored and the unit is held PV at the bus voltage derived from the nominal data, with a warning: message. Widen the band to accept a delivery's own values, or set vset_min_pu = 0 and a large vset_max_pu to disable the check entirely.
• multi_slack::Bool: give every electrical island its own SV-declared angle reference (at most one per island). Required for multi-island deliveries — without it every island beyond the primary one has no reference and the island-wise power flow refuses to run. Disable only to force the legacy single-reference behavior.
• start_values::Symbol: Newton-Raphson start state for CGMES runs. :flat (default) uses a synthetic flat start — the solver earns the solution itself; :sv starts from the delivery's imported SvVoltage state and force-disables the competing start-value machines for the run. On CGMES runs this key wins over power_flow.flatstart / power_flow.start_mode.flatstart; MATPOWER and DTF runs ignore it. The SV comparison artifact (sv_compare.csv) is written either way.

ContingencyConfig

Configuration of the N-1 contingency batch (issue #331).

Fields

• rescue_ladder::Vector{Symbol}: the per-case start-value ladder, an ordered, duplicate-free subset of (:warm, :apslf, :dc, :flat). Default [:warm] reproduces the pre-#331 single warm solve. Each stage is one bounded solve with a distinct start recipe, tried in order until one converges. The allowed stages and their recipes are documented on runContingencies!; the set is validated (subset, no duplicates) by _validate_contingency_ladder.
• screening_mode::Symbol: contingency screening on the base factorization (scenario task D5): :off (default) gives every scenario the full solve, :flag estimates every non-islanding outage with one Woodbury-corrected Newton step on the base Jacobian and runs the full solve only for flagged scenarios, :only reports the estimates without full runs (islanding and failed-screen scenarios still get the full solve). :off is the default DELIBERATELY: the gate calibration (2026-09-03) showed classes of outages a residual step cannot see (Q-capability loss behind a zero residual), so :flag is an opt-in for networks where the user has checked the screening share and the margins once. This config key drives the SERVICE path; the programmatic keyword default is :off as well.
• screening_margin_pct::Float64: the flagging margin (default 10.0): a scenario is flagged for the full run when an estimated loading reaches 100 - margin percent, or an estimated voltage comes within margin percent of a band limit.

DistributedSlackConfig

Distributed active-power slack (issue #192): the REF bus keeps the angle reference while the island's active-power imbalance is absorbed by a set of participating generators via one scalar lambda_P per island.

Fields

• enabled::Bool: off by default — disabled reproduces the classical single-slack behavior bit-for-bit.
• p_mode::Symbol: how raw participation weights are derived — :pg_weighted (scheduled Pg), :pmax_weighted (maxP), :headroom_weighted (max(maxP − Pg, 0)), :imported (ProSumer.participationFactor, filled from MATPOWER APF / CGMES GeneratingUnit.normalPF), :explicit (the weights table).
• respect_p_limits::Bool: diagnostic only — WARN when a participant's corrected P leaves [minP, maxP]; no re-dispatch.
• fallback::Symbol: :error throws when an island has no valid participant; :ref_only falls back to the classical slack for that island with a warning.
• weights::Dict{String,Float64}: :explicit mode only — bus name (or bus index as string) → weight.

ExternalGridConfig

Compute the marked slack bus as a non-ideal external-grid source (issue #299): the reference voltage moves to a hidden internal bus behind the feeder impedance z = Un²/Sk'', so the connection-bus voltage reacts to loading instead of being held ideally stiff.

Fields

• enabled::Bool: off by default — the classical ideal slack.
• source::Symbol: where Sk''/R/X come from — :auto prefers the values a CGMES delivery declares on the slack bus's ExternalNetworkInjection and falls back to the config numbers below (MATPOWER/DTF carry no such data); :config always uses the config numbers.
• sk_MVA::Float64: initial symmetrical short-circuit power of the feeder.
• rx::Float64: its R/X ratio.

IslandPowerFlowConfig

Configuration for AC-island-aware power-flow diagnostics.

MeritLineSearchConfig

Typed configuration for the optional Armijo merit-function line search used as an alternative acceptance criterion inside the rectangular Newton-Raphson autodamp backtracking loop. Disabled by default; when disabled the solver behaves exactly as before this feature was added. See Merit-Function Line Search for the theoretical background.

ShortCircuitConfig

Options of the short_circuit configuration block — the IEC 60909 balanced short-circuit evaluation (runShortCircuit!).

Fields

• c_factor::Float64: scalar override for the IEC 60909-0 voltage factor c. 0.0 (default) selects the hardcoded Table-1 values by nominal voltage level and case (c_max/c_min); a positive value replaces the table for every bus — intended for expert/verification runs where a worked example prescribes the factor. A configurable per-voltage-level table is not configurable.

StartCurrentIterationConfig

Guarded fixed-point current-injection pre-solve configuration. The stage is disabled by default and, when enabled, only prepares the initial voltage profile before the normal rectangular Newton-Raphson solve.

TrustRegionConfig

Typed configuration for the optional scaled-Newton trust-region step control in the rectangular Newton-Raphson solver: an alternative to autodamp that caps the Newton step norm at an adaptive radius and accepts/rejects steps by merit decrease. Disabled by default; mutually exclusive with autodamp. See Trust-Region Step Control for the theoretical background.

step_mode = :scaled (default) rescales the full Newton direction to the radius when it exceeds it, leaving pre-existing behavior byte-for-byte unchanged. step_mode = :dogleg blends the Newton direction with a steepest-descent (Cauchy) step along the dogleg path when the radius shrinks below the Newton step norm, trading some convergence speed for graceful degradation when the Newton direction becomes a poor descent direction. See Trust-Region Step Control, "Dogleg step mode".

WebUIConfig

Web UI presentation preferences that are not part of the solver/API contract.

_apply_config_aliases!(raw, version, context) -> raw

Rewrite a version-version configuration dictionary to the current layout by applying every alias step in order. A value is moved only when the new key is not set (an explicitly set new key wins over a stale old one).

_config_file_version(raw, context) -> Int

The declared config_version of a configuration dictionary. Missing reads as 0 with one warning (pre-versioning file); a version newer than CONFIG_VERSION_CURRENT is an error, not a guess.

_copy_sparlectra_with_user_keys(cfg, keys) -> SparlectraConfig

Attach the set of dotted keys the USER set explicitly. Kept out of the raw configuration dictionary on purpose: anything in there is written to effective_config.yaml, and a reload of that file would reject an unknown key.

_resolve_parallel_runtime(enabled, max_tasks, min_work_items) -> (on, cap, min_items)

Resolve per-call parallel overrides against the ACTIVE runtime.parallel configuration (nothing = take the configured value). Meant to be called ONCE by the orchestrating (serial) code of a parallel site before any task spawns; workers never touch the config globals.

contingency_config() -> ContingencyConfig

The contingency section of the active configuration.

ConfigResolveError

Wraps a failure of one resolution level of resolve_config with the stable service failure reason for that level (invalid_case_file for the deprecated in-case block, invalid_case_config for the case configuration file, invalid_config_override for override validation, invalid_configuration for the general file), so every service maps failures identically without parsing messages.

case_config_path(case_path) -> String

The case configuration file that belongs to one case: <stem>.config.yaml next to the case file. For the canonical .scf.json double extension the stem strips both parts, so case57.scf.json binds case57.config.yaml.

load_case_config(case_path) -> Dict{String,Any}

The flat dotted case-scope configuration of one case, read from its case_config_path file; empty when no such file exists. The file must open with the header keys config_version, scope: case, and case: <case file basename>; a case value naming a different file is the hard error case_config_mismatch, so a copied config cannot silently steer the wrong case. Keys outside the case scope are refused with the same wording as the in-file sparlectra.config check.

resolve_config(config_file, case_path, overrides) -> NamedTuple

The one configuration precedence of the run path (design decision D5), highest first: explicit API/CLI overrides, the case configuration file, sparlectra.config inside an SCF case (deprecated level, one warning naming the case configuration file as the new place), the general configuration file, packaged defaults. A key not set on one level falls through to the next; no mtime logic anywhere.

Exception, whenever a case configuration FILE exists (issue #1 point 1, decided for defaults; format independent per review point 2): the case is then self-contained, so CASE-scope keys skip the general-file level and fall through from the case levels directly to the packaged defaults, and the same case-plus-config pair computes the same numbers on every installation. Machine-scope keys (output, benchmark, runtime, webui, matpower_export) still come from the general file. A case without a config file, including a bare .scf.json, keeps the full chain, and so does the deprecated in-file block alone (legacy level, legacy semantics).

Returns the effective typed config, the effective_raw dictionary for the effective-config artifact, the merged flat and nested override chains, and the per-level dictionaries for provenance. Level errors propagate; the caller owns the failure mapping.

write_case_config(case_file, config) -> String

Write the case-scope keys of config (flat dotted keys) as the case configuration file of case_file (case_config_path), with the D8 header (config_version, scope: case, case:). Keys outside the case scope are dropped with one warning naming them; an empty case scope removes an existing file instead of leaving a stale one. Returns the file path.