API and Web UI Service Reference

SparlectraApiArtifact

Metadata for one file produced or discovered by run_sparlectra_api. Artifact paths are absolute so callers do not need to know Sparlectra's internal file naming or working-directory conventions.

SparlectraApiResult

Stable, non-interactive result returned by run_sparlectra_api. Each result has a unique run_id and a schema_version for transport consumers. The raw_result field contains the underlying SparlectraRunResult for a completed solver invocation and is nothing for input or configuration errors. Use the serialization helpers for transport-safe representations that omit raw_result by default.

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.

collect_sparlectra_api_artifacts(output_dir) -> Vector{SparlectraApiArtifact}

Discover files beneath an API run directory and return deterministic artifact metadata. This is the only filename-discovery contract needed by GUI clients.

run_sparlectra_api(; casefile, config_file, output_dir, config_overrides=Dict(),
                    performance_timing=:off, run_diagnostics=false,
                    detailed_result_csv=false,
                    detailed_result_csv_format="technical",
                    detailed_result_csv_semicolon=false) -> SparlectraApiResult

Run one MATPOWER power-flow case through a stable, non-interactive API contract. The function validates GUI overrides, writes effective_config.yaml, delegates the numerical work to run_sparlectra, captures textual output in run.log, writes result.json, discovers all generated files, and returns structured status and artifact metadata. The input configuration template is never modified. performance_timing may be :off, :compact, or :full and writes a single-run performance.log; run_diagnostics=true captures existing PowerFlow diagnostic printers in diagnose.log; and detailed_result_csv=true writes Excel-friendly bus-voltage and branch-flow CSV artifacts. Optional detailed_result_csv_format accepts technical, excel_de, or excel_us. The legacy detailed_result_csv_semicolon=true maps to excel_de when the explicit format is omitted. Artifact generation does not change PowerFlow run success.

run_fixed_reference_self_check(; casefile, config_file=DEFAULT_SPARLECTRA_CONFIG_PATH,
                                output_dir, config_overrides=Dict(), case_format=:auto) -> SparlectraApiResult

Evaluate the Newton-Raphson mismatch at a case's own stored operating point, without letting any start-value machinery adjust it. Where a normal run answers "does this case converge with the configured start/step-control settings?", the self-check answers a narrower, model-focused question: is the case's own recorded operating point already close to power balance under Sparlectra's imported network model? A large residual here points at the imported network model (branch parameters, shifted angles, a wrong per-unit convention) rather than at the solver's start guess or step control.

Supported inputs:

• MATPOWER (case_format = :matpower/:auto): evaluates at the case's stored VM/VA columns.
• CGMES (case_format = :cgmes): evaluates at the delivery's SvVoltage state, which the importer writes into the bus objects at creation time. Buses without a usable SvVoltage keep the importer's 1.0 pu / 0° fallback; their count is reported in self_check.log and per bus in the has_sv column of self_check_residuals.csv — a large no-SV share weakens the interpretation of the residual.

Arguments

• casefile: case path (MATPOWER file or CGMES delivery), forwarded to run_sparlectra_api.
• config_file: base configuration; the self-check settings are merged on top of it (see "How" below), so any other settings in config_file (e.g. import conventions) still apply.
• output_dir: forwarded to run_sparlectra_api; all normal run artifacts (including diagnose.log) are written here, plus self_check.log and self_check_residuals.csv.
• config_overrides: optional further GUI_EDITABLE_CONFIG_KEYS overrides, applied on top of the self-check settings (e.g. to adjust power_flow.tol for the reported mismatch classification).

How

Forces power_flow.max_iter = 1, power_flow.qlimits.enabled = false, and every start-value machine off (start_mode.flatstart = false, start_mode.start_projection = false, start_mode.dc_seed_unconditional = false, start_current_iteration.enabled = false, apslf_start.enabled = false), then runs through run_sparlectra_api with diagnostics enabled. The imported bus voltages therefore reach the solver verbatim; the only remaining adjustment is the solver pinning the slack magnitude to its regulating setpoint (noted in self_check.log).

Returns

A SparlectraApiResult. success reflects whether the run completed, not whether the residual is small — read self_check.log's start_state_residual_inf (the max |P|/|Q| residual at the unmodified start state) or raw_result.final_mismatch (after the single corrective step) for that. self_check_residuals.csv holds the full per-bus residual export for attribution.

get_powerflow_result(run_id::AbstractString) -> Dict{String,Any}

Return serialized metadata for a registered local PowerFlow service run.

If the run ID is unknown, return a structured service failure dictionary instead of throwing, so Web UI callers can render a stable error response.

start_powerflow_run(request::AbstractDict; case_directory=nothing) -> Dict{String,Any}

Start one local PowerFlow service run above run_sparlectra_api. The request must provide casefile, config_file, and output_root; optional config_overrides are forwarded to the programmatic API. A unique run ID is chosen before execution, and all generated files are written beneath output_root/run_id. Completed API runs, including failed runs with a result.json, are registered in memory and in the persistent run index. Public service failures are returned as structured dictionaries.

When case_directory is provided by a trusted caller, bare .m case names are resolved there through ensure_casefile and remain the executed source. Generated Julia cache files in that directory are hidden from the Web UI service path: explicit .jl requests resolve to a matching .m source when present and are rejected otherwise.

delete_all_powerflow_runs(; output_root::AbstractString) -> Dict{String,Any}

Delete all safely registered PowerFlow run directories beneath output_root. Entries that cannot be validated or removed remain indexed and are reported in failed_runs; deletion never follows an indexed path outside the output root.

delete_powerflow_run(run_id::AbstractString; output_root::AbstractString) -> Dict{String,Any}

Delete one registered PowerFlow run beneath output_root. The run ID must be a safe index entry whose directory is exactly <output_root>/<run_id>; arbitrary paths and unregistered directories are never removed.

list_powerflow_runs(output_root::AbstractString) -> Vector{Dict{String,Any}}

List runs from the persistent index for a future run-history UI. Each entry has an available flag; missing directories, missing result.json files, and unsafe indexed paths are described by a structured reason instead of raising.

load_powerflow_run_index(output_root::AbstractString) -> Dict{String,Any}

Load the persistent PowerFlow run index beneath output_root. A missing or unreadable index returns an empty transport-safe index. Invalid top-level content is reported through reason and message without throwing.

refresh_powerflow_run_registry!(output_root::AbstractString) -> Dict{String,Any}

Reload valid PowerFlow service runs from the persistent index under output_root into the in-process registry. Runs that were active when the Web UI stopped are marked as stale aborted results before registration, while invalid or missing entries are reported in unavailable_runs.

list_powerflow_artifacts(run_id::AbstractString)

Return transport-safe metadata for artifacts currently available for a registered local PowerFlow service run. Unknown run IDs are returned as a structured service failure dictionary.

resolve_powerflow_artifact(run_id::AbstractString, artifact_name::AbstractString)

Resolve an artifact by its metadata name, never by an arbitrary filesystem path. Absolute paths, traversal components, Windows-style paths, missing files, and artifacts escaping the selected run directory are returned as structured failures.

Convert artifact metadata to a transport-safe dictionary.

to_dict(result::SparlectraApiResult; include_raw_result=false) -> Dict{String,Any}

Convert an API result to a transport-safe dictionary. raw_result is omitted by default because the solved network is not a stable JSON/YAML transport type.

Serialize an API result as JSON without an additional JSON package.

Convert an API result to a transport-safe NamedTuple.

Serialize an API result as YAML without an additional YAML package.