External Solver Interface

Sparlectra provides a solver-agnostic interface that allows external power-flow solvers (e.g. research prototypes, new implementations, or custom Newton variants) to consume a canonical network model and return results in a consistent form.

The goal is clean separation:

• Sparlectra builds and owns the network model
• External solvers operate purely on exported data
• Results can be compared against Sparlectra’s internal Newton–Raphson solver

Canonical Data Structures

PFModel

PFModel represents a compressed, solver-independent power-flow model.

PFModel(
  Ybus::AbstractMatrix{ComplexF64},
  baseMVA::Float64,
  busIdx_net::Vector{Int},
  busType::Vector{Symbol},   # :Slack | :PV | :PQ
  slack_idx::Int,
  Vset::Vector{Float64},
  Sspec::Vector{ComplexF64},
  V0::Vector{ComplexF64},
  qmin_pu::Vector{Float64},
  qmax_pu::Vector{Float64},
)

Important notes:

• Only active buses are included (isolated buses are removed).
• Bus ordering matches the internal BusData ordering used by createYBUS.
• V0 provides a canonical initial state (flat-start or case-based).
• Reactive power limits are optional and may be ignored by external solvers.

A model is constructed using:

model = buildPfModel(net; flatstart=net.flatstart)

For difficult starts, the canonical model builder can apply the same start projection used by the internal rectangular solver:

model = buildPfModel(net;
    flatstart = true,
    start_projection = true,
    start_projection_try_dc_start = true,
    start_projection_try_blend_scan = true,
    start_projection_blend_lambdas = [0.25, 0.5, 0.75],
    start_projection_dc_angle_limit_deg = 60.0,
)

External solvers receive the projected start in model.V0. runpf_external! forwards the same keyword arguments to buildPfModel.

PFSolution

External solvers must return a PFSolution:

PFSolution(
  V::Vector{ComplexF64},   # PF ordering
  converged::Bool,
  iters::Int,
  residual_inf::Float64,
  meta::Any,
)

The voltage vector V must use PF ordering (i.e. the same ordering as model.busIdx_net).

External Solver Contract

External solvers implement the following interface:

abstract type AbstractExternalSolver end

solvePf(solver::AbstractExternalSolver, model::PFModel; kwargs...) -> PFSolution

Sparlectra itself does not impose any numerical method. Only the data contract must be respected.

Running an External Solver

For convenience, Sparlectra provides:

runpf_external!(
  net,
  solver;
  tol=1e-8,
  flatstart=net.flatstart,
  include_limits=false,
  show_model=false,
  show_solution=false,
)

This function:

1. Builds a PFModel from net
2. Calls the external solver
3. Evaluates a canonical mismatch norm
4. Writes the solution back into net

Output Control

The external solver interface is silent by default.

Optional helpers are provided for inspection and debugging:

showPfModel(model; verbose=false)
showPfSolution(solution)

These functions intentionally do not overload Base.show to avoid global display side effects.

Example: Exporting a Reference Solution

See:

examples/export_solution.jl

This example:

• Runs Sparlectra’s internal Newton–Raphson solver
• Exports PFModel and PFSolution
• Optionally executes an external solver path
• Compares voltage magnitude and angle deviations

It is intended as a reference and regression test for external solvers.