MATPOWER format

Sparlectra can read power-flow test cases in the MATPOWER case format. A MATPOWER case is usually a .m file that defines or returns a MATLAB/Octave structure named mpc. In the current case format, this structure contains baseMVA, bus, gen, branch and optionally gencost.[^matpower-data-format]

For a normal power-flow run in Sparlectra, the most relevant parts are baseMVA, bus, gen and branch. The optional gencost table is mainly relevant for optimal power flow and is usually not needed for a plain load-flow calculation.[^matpower-caseformat]

Minimal structure

A typical case file has this shape:

function mpc = case_example
mpc.version = '2';
mpc.baseMVA = 100;

mpc.bus = [
    % bus_i type Pd Qd Gs Bs area Vm Va baseKV zone Vmax Vmin
      1     3   0  0  0  0  1    1  0  110    1    1.1  0.9;
      2     1  50 30  0  0  1    1  0  110    1    1.1  0.9;
];

mpc.gen = [
    % bus Pg Qg Qmax Qmin Vg mBase status Pmax Pmin
      1   80 0  100  -100 1.0 100   1      100  0;
];

mpc.branch = [
    % fbus tbus r     x      b      rateA rateB rateC ratio angle status angmin angmax
      1    2    0.02  0.06   0.03   100   100   100   0     0     1      -360   360;
];

The exact number and meaning of columns is fixed by MATPOWER. The official MATPOWER documentation is the authoritative reference for the complete column lists.[^matpower-data-format]

baseMVA

baseMVA is the common power base of the case. MATPOWER uses it for per-unit quantities. Typical examples use values such as 100, but the correct value depends on the case data.

bus: network nodes

mpc.bus describes the electrical buses. Each row is one bus. The most important columns for users are:

A PQ bus normally represents a load bus. A PV bus usually has generation with a specified active power and voltage magnitude. The reference bus supplies the angular reference for the island.

gen: generators and voltage setpoints

mpc.gen describes generators or equivalent injections. Each row is one generator connected to a bus.

Important columns are:

For load-flow studies, PG, VG, QMAX and QMIN are usually the values users inspect first.

branch: lines and transformers

mpc.branch describes network connections. Each row is one line, cable, transformer or equivalent branch.

Important columns are:

In MATPOWER, lines and transformers are represented in the same branch matrix. A non-zero tap ratio or phase shift indicates transformer behavior.

Sparlectra result columns and write_solution

Standard MATPOWER solvers write a solved case back into the same input matrices: mpc.bus VM/VA are overwritten in place, and mpc.gen PG/QG are overwritten in place. mpc.branch is different — a solved MATPOWER case gains genuine additional columns 14–17 (PF, QF, PT, QT; an OPF run additionally adds columns 18–21 for the OPF-specific results). These are not a Sparlectra extension; they are the standard MATPOWER solved-case branch layout.

writeMatpowerCasefile controls this through the write_solution argument (config key matpower_export.write_solution, default true): when enabled, mpc.branch gains columns 14–17 (PF, QF, PT, QT, MATPOWER sign convention: flow into the branch at the respective end), sourced from the existing branch-flow report path without exporter-side flow recomputation, and VM/VA reflect the current solved node state. A mpc.sparlectra.solution_written = 1 marker documents that columns 8/9 and 14–17 represent a solution. Sparlectra does not write OPF columns 18–21 or mpc.gencost. See writeMatpowerCasefile and the "Writing the solved state" section of the import guide for the full option reference and the model-only (write_solution = false) behavior.

gencost: optional cost data

mpc.gencost contains generator cost data for optimal power-flow studies. It can be present in many public MATPOWER cases, but it is usually not needed for a plain power-flow run.

Practical checks before importing a case

Before running a case in Sparlectra, check the following points:

1. The file should define or return mpc.
2. mpc.version should normally be '2'.
3. Bus numbers in branch and gen must exist in mpc.bus.
4. At least one in-service reference bus is required per connected island.
5. Decimal values must use a decimal point, not a decimal comma.
6. Inactive generators or branches should have status 0.
7. Per-unit branch impedances must be consistent with baseMVA and the voltage base of the case.

What Sparlectra uses

For a standard Web UI power-flow run, Sparlectra primarily uses the topology and electrical data from bus, gen and branch. The result page and log files then report whether the numerical power flow converged, how many iterations were needed and what final mismatch remained.

When Q-limit handling is enabled, the generator reactive power limits from QMAX and QMIN become important. If a generator cannot maintain its voltage setpoint within those limits, the solver may have to treat the bus differently depending on the selected configuration.

Sparlectra-specific optional metadata and import options

The standard MATPOWER case concepts are mpc.bus, mpc.gen, mpc.branch and, when present, mpc.gencost. The official MATPOWER documentation remains authoritative for those standard tables and their columns.

Sparlectra can also read a small set of optional metadata fields when a conversion or validation workflow provides them. These fields are Sparlectra-recognized extensions, not required MATPOWER fields. If they are absent, standard MATPOWER imports still work. If they are present but the corresponding apply_* import options remain false, Sparlectra keeps conservative/default naming and branch-classification behavior.

Names and source metadata are useful for CSV exports, FOR001/FOR002 validation, outage mapping, diagnostics and support workflows.

Sparlectra transformer-loss extension

Sparlectra supports transformer conductance natively on PowerTransformerWinding.g, which flows through getTrafoRXBG/getTrafoRXBG_pu into Branch.g_pu. Standard MATPOWER has no branch-local field equivalent to that active no-load conductance, so Sparlectra preserves roundtrip metadata under mpc.sparlectra when such data exists. The block is versioned with mpc.sparlectra.format_version = 1 and stores mpc.sparlectra.transformer_losses entries with the MATPOWER branch row, original FOR/DTF identifier, terminal bus names, raw R/X/G/B values where available, converted per-unit values, tap/phase-shift data, source marker, and the allocation convention.

Sparlectra applies FOR/DTF transformer conductance as part of the native transformer PI branch model (Branch.g_pu) rather than as synthetic terminal bus shunts. Exported .m files include an explicit SPARLECTRA EXTENSION WARNING comment because plain MATPOWER ignores the proprietary metadata and may therefore compute different transformer active losses. When Sparlectra reimports one of these files it restores the branch conductance metadata without adding terminal bus-shunt approximations.

Sparlectra MATPOWER import options overview

The options below are the most common import-convention controls users may need when a case was converted from another tool or carries optional metadata. See the full MATPOWER import configuration reference for allowed values, defaults and interactions.

For example, a case-conversion or validation workflow might use:

matpower_import:
  auto_profile: recommend
  pv_voltage_source: gen_vg
  compare_voltage_reference: imported_setpoint
  ratio: normal
  shift_unit: deg
  shift_sign: 1.0
  bus_shunt_model: admittance
  apply_bus_names: true
  apply_branch_names: true
  apply_branch_kind: true
  import_for001_contingencies: true
  matpower_dcline_mode: pf_injections

This is an example configuration, not a requirement for every case.

MATPOWER mpc.dcline

Sparlectra recognizes mpc.dcline tables. The default matpower_import.matpower_dcline_mode: pf_injections is the default and imports active rows as fixed terminal injections. reject_active remains an explicit fail-fast mode. Empty and inactive-only tables are tolerated.

For ordinary power-flow compatibility studies, opt in to matpower_import.matpower_dcline_mode: pf_injections. This imports active rows with a MATPOWER toggle_dcline-compatible PF approximation: each DC line is represented by from/to generator-like terminal injections, from-side PG = -PF, to-side received power from PF - (LOSS0 + LOSS1 * PF) when loss columns are available (or input PT otherwise), row QF/QT, voltage setpoints VF/VT, and terminal Q limits where present. Terminal buses with voltage setpoints become voltage-controlled where appropriate, while existing reference buses stay reference buses and isolated buses are not activated. API/Web UI runs with imported active DC lines include matpower_dcline.csv as a compact diagnostic artifact.

This option is a toggle_dcline-compatible PF approximation, not a full HVDC converter model. OPF-style behavior, converter controls, dclinecost, and detailed DC-grid modeling are not provided by Sparlectra yet.

The Web UI exposes selected MATPOWER import convention controls in the form and writes the effective configuration as a run artifact. It does not rewrite the user YAML automatically. With auto_profile = recommend, Sparlectra logs recommendations without changing the active configuration; with auto_profile = apply, it applies only safe convention recommendations. Use the result artifacts and logs to reproduce the final effective settings for a run.

Full reference

This page is intentionally short. For the complete MATPOWER format, use the official MATPOWER documentation:

• MATPOWER Manual, Appendix “Data File Format”: https://matpower.app/manual/matpower/DataFileFormat.html
• MATPOWER caseformat reference: https://matpower.org/documentation/ref-manual/legacy/functions/caseformat.html
• MATPOWER named column constants: https://matpower.org/docs/ref/matpower6.0/define_constants.html

[^matpower-data-format]: MATPOWER Manual, “Data File Format”. It describes version 2 case files as an mpc structure with baseMVA, bus, branch, gen and optional gencost; it also defines the bus, generator, branch and cost columns. https://matpower.app/manual/matpower/DataFileFormat.html [^matpower-caseformat]: MATPOWER caseformat reference. It defines a MATPOWER case file as an M-file or MAT-file that returns or defines an mpc case structure and documents version 2, optional fields and solver-added result columns. https://matpower.org/documentation/ref-manual/legacy/functions/caseformat.html