Power-Flow Configuration

Start-source concepts

Solver core options

Solver selection (rectangular vs. APSLF)

power_flow.solver selects which solver actually computes the power-flow solution; it is independent of power_flow.method, which fixes the AC formulation family (currently always rectangular). apslf routes the run through the external-solver bridge (buildPfModel → solvePf(ApslfSolver(...)) → applyPfSolution!) to AnalyticLoadFlow.jl's analytic power-series solver instead of the internal Newton-Raphson loop. It requires the optional AnalyticLoadFlow.jl dependency to be loaded (using AnalyticLoadFlow); see apslf_solver.

power_flow:
  solver: rectangular   # rectangular | apslf
  apslf:
    order: 40
    use_pade: true
    nr_polish: true
  apslf_start:
    enabled: false
    order: 40

power_flow.apslf_start 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. It also always runs unconstrained (Qmin/Qmax are not passed to the series solve), independent of power_flow.qlimits.enabled or any other Q-limit setting: power_flow.qlimits.* only governs the rectangular NR solve that follows, not the guarded start-value candidate itself. This is a fixed internal behavior, not a separate configurable option — the generator's only job is producing a better starting voltage profile; Q-limit enforcement is entirely the downstream NR solve's responsibility.

Solver selection (DC power flow)

power_flow.solver: dc selects the standalone DC power flow (MATPOWER rundcpf/makeBdc-equivalent) instead of the AC rectangular Newton-Raphson solve: a linear screening model built from branch series reactance only (B', no r, no shunt, no line charging), with transformer phase_shift_deg represented as a phase-shift injection vector rather than inside B' itself. Vm is implicitly 1.0 pu at every bus and there are no losses — both by definition of the DC model, not solver limitations. It can also be called directly, independent of run_sparlectra/power_flow.solver, via rundcpf!.

power_flow:
  solver: dc   # rectangular | apslf | dc
  dc:
    angle_reference_deg: 0.0
    ignore_out_of_service: true

rundcpf! accepts a seed_ac_start::Bool=false keyword (not a YAML option — it only makes sense as a one-off programmatic call): when true, after a successful DC solve it immediately re-seeds and runs the AC rectangular Newton-Raphson solve from the just-computed DC angles, restoring Slack/PV voltage-magnitude setpoints first (the DC write otherwise flattens every bus to 1.0 pu). net then holds the AC-converged solution, not the DC one; the returned DcPowerFlowReport still reflects the DC step's own result, with the AC outcome recorded in report.metadata.ac_converged/ ac_iterations/ac_elapsed_s.

DC results are reported through a dedicated DcPowerFlowReport (angles and lossless branch flows only) and tracked via dc_pf_status(net), a status registry kept separate from rectangular_pf_status so a DC result is never mistaken for an AC one by AC-only reporting code.

Known limitation: with power_flow.solver = :dc and multiple AC islands, the per-island diagnostics CSV (ac_island_solver_summary.csv, see below) is still written but stays cosmetically empty for DC-solved islands — it reads AC-only rectangular_pf_status fields that a DC solve never populates. This does not affect the DC solve or its dc_pf_status result, only that one diagnostics artifact.

AC island diagnostics

power_flow.islands enables structural AC-island diagnostics for imported or constructed networks that contain multiple disconnected AC components. Island diagnostics do not model DC lines as AC branches and do not add artificial admittance bridges. They report the AC topology that the existing rectangular solver sees after import; matpower_import.matpower_dcline_mode: pf_injections remains a fixed terminal-injection approximation only.

power_flow:
  islands:
    enabled: true
    mode: solve_independent
    reference_policy: matpower_like
    diagnostic_continue_after_failure: true

When an island-aware run fails, the API/result message identifies the first failing island with its island id, bus and branch counts, selected reference bus, PV/PQ/REF counts, iteration count, final mismatch, mismatch status (finite, nonfinite, NaN, or Inf), failure reason, stage (before_nr, during_nr, or after_nr_validation), start-projection setting, and the diagnostic artifact path.

Each run output directory receives:

• ac_island_solver_summary.csv: one row per detected AC island, including the selected reference bus, PV/PQ/REF counts, propagated solver settings, final status, final mismatch, and failure reason.
• ac_island_<id>_solver.log: compact per-island details with the same topology, setting, and solve-status fields.

Island-wise solving is structural support, not a convergence guarantee. A large island can fail independently while smaller islands are structurally valid. If any island or the combined solve fails, Sparlectra still reports the combined run as failed and preserves the island artifacts for diagnosis.

For pure SyntheticUSA island diagnostics, start with Q-limit handling disabled so the baseline tests island topology, reference selection, start projection, and rectangular NR behavior before adding active-set effects:

matpower_import:
  matpower_dcline_mode: pf_injections
  auto_profile: apply
  compare_voltage_reference: hybrid

power_flow:
  tol: 1.0e-5
  max_iter: 80
  autodamp: true
  autodamp_min: 0.01

  islands:
    enabled: true
    mode: solve_independent
    reference_policy: matpower_like
    diagnostic_continue_after_failure: true

  qlimits:
    enabled: false

  start_current_iteration:
    enabled: false

  start_mode:
    angle_mode: dc
    voltage_mode: profile_blend
    profile_source: matpower_reference
    start_projection: true
    try_dc_start: true
    try_blend_scan: true
    branch_guard: true
    measure_candidates: true
    reuse_import_data: true

After this pure baseline is understood, enable power_flow.qlimits.enabled to diagnose active-set behavior. Per-island logs then include Q-limit state such as q_limit_processing_status, switching-event counts, active-set changes, reenable events, guarded narrow-range PV buses, final PV voltage residual, and available mismatch metrics.

Start mode options

DC-seeded Newton-Raphson start (dc_seed_unconditional)

power_flow.start_mode.dc_seed_unconditional is a distinct mechanism from angle_mode = dc/try_dc_start above. angle_mode = dc (the default) is one candidate among several inside the measured/guarded start-projection machinery (project_rectangular_start): it builds a lightweight internal DC-angle estimate, compares it against other candidates, and can fall back if it looks bad. dc_seed_unconditional = true instead runs the actual standalone DC power flow (the same solver used for power_flow.solver = dc, including per-island handling) before Newton-Raphson starts, and always uses its resulting bus angles as the NR start point — mirroring rundcpf!(net; seed_ac_start=true)'s behavior, but wired into the config-driven run_sparlectra/Web UI pipeline so Q-limit handling, wrong-branch detection, and diagnostics/artifacts all still apply afterward to the AC solve, unlike calling rundcpf! directly. Voltage magnitudes are unaffected either way: the DC model has no voltage-magnitude solution (Vm = 1.0 pu everywhere by definition), so Slack/PV regulated setpoints are preserved and every other bus still gets its magnitude from the normal voltage_mode/start_projection handling. Only applies when power_flow.solver = rectangular; rejected at configuration time for apslf/dc and when combined with power_flow.apslf_start.enabled, since those are separate, mutually exclusive start-value sources for the same rectangular solve.

In the Web UI, enabling Use DC start values unconditionally runs the full standalone DC power flow before the NR solve and adopts its angles as start values — without the quality-measurement/fallback logic that Start angle mode = dc uses by default. The Start angle mode and Start voltage mode selects are therefore grayed out while it is active (both would have no effect for such a run). The DC power flow never provides voltage magnitudes (angles only) — Slack/PV setpoints and the rest of the voltage start remain unchanged.

Guarded current-iteration start pre-solve

power_flow.start_current_iteration enables an optional guarded current-injection/current-iteration pre-solve for start values. It is a start-value preconditioner, not a new power-flow solver. The final AC power-flow solve remains the rectangular Newton-Raphson path.

The rectangular power-flow start sequence is:

Start Voltage Mode + Start Angle Mode
→ optional start projection / candidate selection
→ optional current-iteration pre-solve
→ Newton-Raphson power flow
→ optional Q-limit handling / outer loop logic

Current iteration does not introduce a new start_voltage_mode, start_angle_mode, power_flow.start_mode.voltage_mode, or power_flow.start_mode.angle_mode value. It consumes the voltage profile prepared by the existing start-mode and start-projection settings, then attempts a limited PQ-bus current update before Newton-Raphson starts. The candidate is used only when the guarded checks accept it. If a guard rejects the candidate or the mismatch does not improve enough, Sparlectra restores the original start values before entering Newton-Raphson.

Configuration block

power_flow:
  start_current_iteration:
    enabled: false
    max_iter: 10
    tol: 1.0e-3
    damping: 0.5
    accept_only_if_improved: true
    min_improvement_factor: 0.98
    vm_min_pu: 0.5
    vm_max_pu: 1.5
    max_angle_step_deg: 30.0
    only_for_large_cases: false

Recommended usage

For difficult MATPOWER starts, a conservative setup is:

power_flow:
  start_mode:
    voltage_mode: profile_blend
    angle_mode: dc
    profile_source: matpower_reference
  start_current_iteration:
    enabled: true
    max_iter: 10
    damping: 0.5
    accept_only_if_improved: true

This combination may reduce the initial mismatch for difficult imported cases, but it is experimental and is not guaranteed to rescue a non-converging case. If the candidate violates guards or does not improve the mismatch enough, the pre-solve is rejected and Newton-Raphson starts from the original start values. It does not replace MATPOWER auto-profile selection, DC angle starts, or start projection.

Diagnostics and interpretation

When a run has an output directory in its performance profile, the pre-solve writes current_iteration_start.log. The artifact records:

• current_iteration_enabled, current_iteration_attempted, current_iteration_accepted, and current_iteration_reason.
• initial_mismatch, final_mismatch, and iterations.
• Candidate voltage diagnostics: candidate_voltage_magnitude_min, candidate_voltage_magnitude_max, candidate_voltage_low_count, candidate_voltage_high_count, candidate_voltage_worst_low_bus, candidate_voltage_worst_high_bus, and their corresponding values.
• Candidate angle diagnostics: candidate_max_angle_step_deg and maximum_angle_step_deg.
• Rejection diagnostics: guard_violations, rejection_stage, rejected_at_iteration, and original_start_values_restored.
• Restored voltage ranges after rejection: restored_voltage_magnitude_min and restored_voltage_magnitude_max.

Important interpretations:

current_iteration_accepted: true
  The pre-solve result was used as Newton-Raphson start values.

current_iteration_accepted: false and original_start_values_restored: true
  The candidate was rejected and Newton-Raphson started from the original start values.

current_iteration_reason: voltage_magnitude_guard
  At least one candidate voltage was outside vm_min_pu/vm_max_pu.

current_iteration_reason: angle_step_guard
  The candidate changed an angle beyond max_angle_step_deg.

current_iteration_reason: not_improved
  The candidate did not improve the mismatch enough.

Other implementation reasons include disabled, skipped_small_case, max_iter, tolerance_reached, invalid_voltage, singular_current_update, and invalid_mismatch.

Q-limit interaction

For the active-set path, the guarded current-iteration pre-solve is attempted before the Newton-Raphson solve when enabled. For classical MATPOWER-style Q-limit outer-loop modes, it is applied only to the first inner solve; later inner solves in the same outer loop start without repeating current iteration. Current iteration does not directly change Q-limit switching decisions.

Limitations

• Experimental diagnostic start-value helper.
• Can be rejected by voltage, angle-step, finite-value, singular-update, or mismatch-improvement guards.
• Can reduce the initial mismatch without guaranteeing Newton-Raphson convergence.
• May not help cases whose main issue is model/convention mismatch, wrong branch, or an invalid MATPOWER import convention.
• Does not replace MATPOWER auto-profile, DC start, or start projection.

Merit-function line search options

power_flow.merit enables an optional Armijo sufficient-decrease acceptance criterion inside the existing autodamp backtracking loop of the rectangular Newton-Raphson solver. It is an alternative, opt-in acceptance test — not a replacement for Newton-Raphson and not a replacement for autodamp. Disabled by default (enabled: false), which leaves today's max-mismatch autodamp behavior byte-for-byte unchanged. See Merit-Function Line Search in the solver documentation for the theoretical background.

power_flow:
  autodamp: true
  merit:
    enabled: false
    armijo_c1: 1.0e-4
    scale_p: 1.0
    scale_q: 1.0
    scale_v: 1.0
    fallback_max_mismatch: true

Recommended usage

power_flow:
  autodamp: true
  merit:
    enabled: true
    armijo_c1: 1.0e-4
    fallback_max_mismatch: true

Enable power_flow.merit.enabled together with power_flow.autodamp on cases where the historical ∞-norm autodamp criterion is suspected to accept a step that reduces the worst-bus mismatch while increasing overall residual energy. Leave scale_p/scale_q/scale_v at 1.0 unless P/Q/V residuals are known to differ by orders of magnitude in a particular case.

Diagnostics and interpretation

When a run has an output directory in its performance profile and merit.enabled = true, the solver writes merit_linesearch.log with one line per Newton iteration: f_before, directional_derivative, tested_alphas, accepted_alpha, and accept_reason. The solver status is extended with merit_enabled, merit_used_iterations, merit_fallback_count, merit_active_set_skip_count, merit_initial, and merit_final.

accept_reason values:

armijo
  A backtracking trial satisfied the Armijo sufficient-decrease condition; it was accepted directly.

fallback_max_mismatch
  No trial satisfied Armijo; fallback_max_mismatch=true, and the classic max-mismatch criterion
  found an improving trial, which was accepted instead.

fallback_conservative
  No trial satisfied Armijo (and, if fallback_max_mismatch=true, no trial improved the max
  mismatch either); the most conservative finite trial from the backtracking sweep was accepted.

active_set_skip
  A PV/PQ active-set switch (Q-limit handling) happened during this Newton iteration, so the
  residual vector's entries changed meaning; the merit comparison was skipped for this iteration
  and the classic max-mismatch criterion was used instead.

Limitations

• Opt-in line-search criterion, not a general-purpose nonlinear optimizer; it does not replace Newton-Raphson.
• The merit function f(x) = 1/2 ‖W F(x)‖² can have local minima with F(x) ≠ 0; satisfying Armijo does not by itself guarantee convergence.
• Does not influence which of multiple numerical solution branches (e.g. high-voltage vs. low-voltage) the solver converges to.
• PV/PQ active-set switches make f discontinuous in meaning across the switch; the merit comparison is skipped for that iteration (accept_reason = active_set_skip).
• Does not change candidate start-value ranking (start_mode.measure_candidates), which remains mismatch-based.

Trust-region step control options

power_flow.trust_region enables an optional scaled-Newton trust-region alternative to power_flow.autodamp: it caps the Newton step norm at an adaptive radius and accepts/rejects trials by merit-function decrease rather than by the max-mismatch criterion. Disabled by default (enabled: false). Mutually exclusive with power_flow.autodamp = true — both mechanisms control the Newton step length; enabling both is a configuration error. See Trust-Region Step Control in the solver documentation for the theoretical background.

power_flow:
  autodamp: false
  trust_region:
    enabled: false
    initial_radius: 1.0
    min_radius: 1.0e-4
    max_radius: 10.0
    eta_accept: 0.1
    shrink_factor: 0.5
    expand_factor: 2.0
    expand_threshold: 0.75
    step_mode: scaled

Diagnostics and interpretation

When a run has an output directory in its performance profile and trust_region.enabled = true, the solver writes trust_region.log with one line per Newton iteration: radius_before, rho, tested_radii (the shrink sequence tried this iteration), rejected_steps, accepted, radius_after, collapsed, and accept_reason. The solver status is extended with trust_region_enabled, tr_step_count, tr_rejected_steps, tr_min_radius, tr_max_radius (the observed radius range across the run, not the configured bounds), tr_final_radius, tr_collapsed, and the dogleg-branch counters tr_dogleg_newton_count, tr_dogleg_interp_count, tr_dogleg_cauchy_count, tr_active_set_skip_count (all 0 in scaled mode).

accept_reason values: scaled (the scaled step mode's only reason); dogleg_newton/dogleg_interp/dogleg_cauchy (which point on the dogleg path was accepted, dogleg mode only); active_set_skip (a PV/PQ switch happened this iteration, dogleg mode only — the comparison was skipped and a single scaled-style trial was accepted unconditionally); none (a collapse entry, no step accepted).

tr_collapsed: false
  The trust region never dropped below min_radius; every Newton iteration eventually accepted a step.

tr_collapsed: true
  The radius fell below min_radius without an accepted step in some iteration; the run reports
  reason = :trust_region_collapsed. Lower min_radius, raise initial_radius, or fall back to
  autodamp for this case.

tr_rejected_steps > 0
  At least one trial was rejected (rho < eta_accept) and the radius was shrunk before an
  eventual accept (or collapse). A high count relative to tr_step_count suggests the model
  is a poor local predictor for this case; consider a different start profile.

Step-control mode combinations (autodamp / merit / trust-region)

power_flow.autodamp, power_flow.merit.enabled, and power_flow.trust_region.enabled jointly select how the Newton step length is chosen. Only some combinations are valid; PowerFlowConfig enforces the rules below at load time (ArgumentError) regardless of whether the values came from YAML, an API config_overrides argument, or the Web UI:

• power_flow.merit.enabled = true requires power_flow.autodamp = true (merit is an alternative acceptance test inside the autodamp backtracking loop, not a standalone step-control mode).
• power_flow.trust_region.enabled = true requires power_flow.autodamp = false (trust-region is a separate step-control mode that replaces autodamp's backtracking, not a companion to it).
• Because of the two rules above, merit.enabled = true and trust_region.enabled = true can never both hold at once — enabling one always implies the exact opposite value of autodamp required by the other.

The Web UI mirrors these rules client-side: the Autodamping & merit-function line search box and the Trust-region step control box are mutually exclusive — enabling one automatically unchecks and disables the other (and its sub-fields), and the merit toggle itself is disabled/unchecked whenever autodamping is off. This is a convenience only; the authoritative check is the PowerFlowConfig validation shown above, which still applies to YAML files and direct API calls.

power_flow.trust_region.step_mode (scaled/dogleg) is orthogonal to this matrix: it only takes effect on rows where trust_region.enabled = true, and does not change which autodamp/merit/trust_region.enabled combinations are valid. In the Web UI it is disabled/hidden together with the rest of the Trust-region box's sub-fields whenever the box itself is disabled or hidden (trust-region off, or the APSLF solver is selected).

Q-limit options and guard

Safe configuration refresh

Use refresh_sparlectra_config_file(path; write=false) to check an existing user YAML against the current template without modifying it. The refresh helper preserves existing user-provided values, adds missing keys from src/configuration.yaml.example, reports duplicate keys, and can normalize known deprecated aliases when normalize_deprecated=true.

Writing is explicit: pass write=true to update the file. By default a timestamped .bak-YYYYmmdd-HHMMSS backup is created before writing, and duplicate keys prevent automatic writes. This refresh mechanism is a maintenance tool only; normal configuration loading still accepts supported Q-limit enforcement legacy aliases, and Sparlectra never silently rewrites user YAML during startup.