These notes record deterministic compatibility transformations applied while loading older BMOPF documents. They describe what changed; they do not certify that the migrated model preserves every intended scientific meaning.
| Code | Sev | Trigger & rationale |
|---|
E.DOM.VMIN_NEGATIVE | E | A negative per-phase entry in v_min — magnitudes are nonnegative by definition. (v_min is a per-phase array, phase-to-ground.) |
E.DOM.VMAX_NONPOSITIVE | E | A per-phase v_max entry ≤ 0 — forces zero voltage; almost certainly a unit/typo error. |
E.DOM.VNMAX_NEGATIVE | E | Negative vn_max (the optional, maximum-only neutral-to-ground cap). |
E.DOM.NEGATIVE_VALUE | E | Negative value in an inherently nonnegative field (length, diagonal resistance). |
W.DOM.LOAD_PF_LOW | W | Load power factor below 0.70 — plausible but unusual for aggregated demand; often a P/Q unit mix-up. |
W.DOM.GEN_COST_NEGATIVE | W | Negative generation cost — the optimizer will dispatch it to its bound; verify it is intended (e.g. must-run subsidy). |
W.DOM.GEN_COST_HIGH | W | Cost above 10 $/kWh — outside the package's default plausibility threshold; check units and whether an extreme scarcity/subsidy scenario is intentional. |
E.DOM.GEN_SMAX_NONPOSITIVE | E | Generator s_max (optional per-phase apparent-power rating) has a non-positive entry — the apparent-power circle is empty, so no operating point exists. |
E.DOM.GEN_IMAX_NONPOSITIVE | E | Generator i_max (optional per-phase current limit) has a non-positive entry — the current circle is empty, so no operating point exists. |
W.DOM.COST_PHASE_NONUNIFORM | W | A dispatchable element (generator or voltage_source) has a per-phase cost vector whose entries differ across phases. Costs are normally a single $/kWh price applied symmetrically; a non-uniform vector is more often a data-entry slip than an intended per-phase price signal. Scalar costs are uniform by definition and never flag. |
W.DOM.LC_ZERO_R | W | Near-zero or negative self-resistance on any linecode diagonal — a superconducting conductor, usually a placeholder. |
E.DOM.XFMR_VREF_INVALID | E | A transformer has v_nom_from ≤ 0 or v_nom_to ≤ 0. The turns ratio N = v_ref_from / v_ref_to is undefined or infinite; the OPF cannot be built. Usually caused by a missing field defaulting to zero or a unit error (kV entered as 0.0). |
W.DOM.XFMR_RATIO_OOB | W | Direction-agnostic transformer step ratio max(r, 1/r) above 1000:1. Calibrated so standard distribution step-downs (e.g. 11 kV/433 V ≈ 25:1) do not flag. |
W.DOM.XFMR_REVERSED | W | An isolating two-bus transformer (single_phase/center_tap/wye_delta/delta_wye) has its bus_from/bus_to terminals wired toward the source: bus_to is strictly closer (in hops) to a voltage source than bus_from. Orientation is measured by multi-source BFS over lines, closed switches and transformers; bus_from should be the source-side terminal. Almost always swapped bus_* (and usually v_nom_*) fields. Endpoints that are equidistant (a loop/mesh) or unreachable from any source are skipped, so the check is safe on non-radial parts. Requires at least one voltage_source. |
W.DOM.XFMR_STEP_UP | W | An isolating two-bus transformer boosts voltage away from the source: its upstream-side v_nom is strictly below its downstream-side v_nom (upstream/downstream determined by the same source-distance BFS as W.DOM.XFMR_REVERSED, so it is correct even when the terminals are reversed). Distribution step transformers normally step down toward the load; this is usually swapped v_nom_from/v_nom_to, or a genuine boost transformer if intended. Regulators/autotransformers and n_winding are excluded. |
I.DOM.XFMR_IDEAL | I | An isolating power transformer (single_phase/center_tap/wye_delta/delta_wye/n_winding) has zero leakage reactance (total series X ≤ xfmr_z_min_ohm, default 1e-6 Ω) — modeled as an ideal transformer with no series voltage drop. The IVR OPF represents the series impedance as a coefficient in the winding voltage-drop equation, not an inverted admittance, so zero impedance collapses cleanly to the exact voltage-ratio constraint V_fr = N·V_to and is well-posed, not degenerate. Informational because %Z was most likely omitted: supply realistic leakage (x ≈ 4–10 % on the rating base) if regulation across the winding matters. A lossless unit (R≈0 with finite X) is normal here and is not flagged. Regulators/autotransformers are excluded. |
W.DOM.XFMR_LOW_IMPEDANCE | W | A two-winding transformer has a tiny non-zero series impedance — ` |
W.DOM.XFMR_X_NONINDUCTIVE | W | A measurable transformer short-circuit reactance is negative. For n_winding this is a pairwise x_sc["i_j"] entry; for two-bus subtypes it is the total series reactance x_series_from + x_series_to (the individual legs are a fictitious star/T split and may be negative — only their sum is measurable). A real short-circuit test is inductive by construction, so a negative value is almost always a sign flip or an X↔B (reactance/susceptance) confusion in the source data. The transformer analogue of W.PROV.X_NONINDUCTIVE. |
W.DOM.XFMR_X_NOT_PSD | W | An n_winding transformer's short-circuit reactance matrix imag(ZB) has a negative eigenvalue — the pairwise x_sc values are mutually inconsistent and cannot arise from any passive coupled-coil model (energy argument). Distinct from a negative diagonal ZB / star-branch entry, which is physical for n ≥ 3 and not flagged; only the matrix-level PSD property is invariant. For n = 3 this is the realisability triangle inequality X₁₂·X₁₃ ≥ ¼(X₁₂+X₁₃−X₂₃)². The transformer analogue of W.PROV.X_NOT_PSD. |
W.DOM.ZERO_LIMIT | W | An i_max/s_max entry exactly 0. Read literally this forces zero flow; in source tools 0 usually means "no limit" — classic semantic abuse. Drop the field instead. |
W.DOM.POWER_LIMIT_NEUTRAL | W | A line/switch sets a positive s_max on its neutral conductor. A ground-referenced apparent-power limit is degenerate there: the neutral-to-ground voltage is ≈ 0, so S = V∘I* ≈ 0 and the cap never binds even as the neutral current overheats the conductor. Rate the neutral with i_max (a current limit) instead. See current vs. apparent-power limits. |
W.DOM.ZERO_LENGTH | W | A zero-length line — degenerate impedance; the spec's lossless switch object is the right model for such sections (ref. 2). |
W.DOM.ANGLE_UNITS | W | A source v_angle entry with magnitude > 2π — angles are radians in the data model; this is almost certainly degrees. |
W.DOM.SOURCE_V_NEAR_BOUND | W | A voltage source's fixed v_magnitude sits within source_v_margin_frac (default 5 %) of the v_max − v_min band from either bound, on its own bus or a same-voltage-base neighbour (reachable via lines/switches; transformers are not crossed). The source pins that voltage as a hard equality, so little headroom remains and the OPF risks infeasibility. The stricter sibling W.PRE.SOURCE_VOLTAGE_OOB fires when the setpoint is already outside the bounds; this one warns before it crosses. |
W.DOM.SHUNT_ON_GROUNDED | W | A shunt connects to a terminal whose voltage is pinned to 0 V — either declared in the bus's perfectly_grounded_terminals or the neutral of a voltage-source bus (pinned to system ground). The shunt then draws I = G·V = 0 current and is completely inert. Usually a redundant element, or a sign that impedance grounding was intended where a hard V=0 ground was actually declared. |
I.DOM.NEGATIVE_LOAD | I | Loads with negative p_nom — embedded generation hiding as negative load; skews adequacy statistics and dodges the generator model. See object identity. |
I.DOM.NEGATIVE_GENERATION | I | A generator whose entire active range is p_max ≤ 0 (only ever absorbs) — a consumer modelled as a generator (the mirror of I.DOM.NEGATIVE_LOAD); model it as a load. |
I.DOM.GEN_LIKELY_IBR | I | A generator sits on an LV bus (≤ 1 kV). Distribution-connected DERs are overwhelmingly inverter-interfaced; the ibr object models them faithfully (capability curve, no inertia, current limit, volt-var/volt-watt) where a synchronous-generator object does not. |
W.DOM.LINE_LOW_IMPEDANCE | W | A line whose absolute series impedance ‖Z‖F (linecode ‖(R+jX)‖F × length, or the inline total matrices directly) is below 10⁻⁴ Ω. Near-zero impedance makes the KVL constraint nearly rank-deficient; model the section as a switch instead. |
W.DOM.LINE_IMPEDANCE_SPREAD | W | The worst adjacent-line ‖Z‖_F ratio (two lines sharing an interior bus, excluding voltage-source, transformer, and switch buses) exceeds 10⁵. At this contrast the NLP Jacobian loses roughly 5 decimal digits of precision; consider per-unit scaling or network reformulation. |
I.DOM.LINE_IMPEDANCE_SPREAD | I | Same as above but ratio is between 10³ and 10⁵ — common at MV/LV boundaries and usually benign, but worth reviewing if solvers struggle to converge. The result dict key max_adjacent_impedance_ratio always carries the worst observed value. |
E.DOM.INV_P_BOUNDS | E | IBR p_min > p_max — the active-power box is empty; infeasible by construction. |
E.DOM.INV_Q_BOUNDS | E | IBR q_min > q_max — the reactive-power box is empty. |
E.DOM.INV_SMAX_NONPOSITIVE | E | IBR s_max has a non-positive entry — the apparent-power circle is empty, so no operating point exists. |
E.DOM.IBR_IMAX_NONPOSITIVE | E | IBR i_max (optional per-phase current limit) has a non-positive entry — the current circle is empty, so no operating point exists. |
W.DOM.INV_BOUND_EXCEEDS_SMAX | W | An IBR P or Q box-bound magnitude exceeds s_max — that box bound can never bind because the apparent-power circle dominates; usually a units or sizing mistake. |
W.DOM.INV_PV_ABSORBS | W | A prime_mover=PV IBR has p_min < 0, i.e. it is allowed to absorb real power — physically implausible for PV; usually a sign error. |
W.DOM.DROOP_BREAKPOINT_OUTSIDE_BAND | W | An IBR's Volt-var/Volt-watt droop has breakpoint voltages outside the bus's [v_min, v_max] band — the droop may never engage within the feasible operating range, so the control is effectively inert. |
| Code | Sev | Trigger & rationale |
|---|
E.DOM.WIRE_GMR_EXCEEDS_RADIUS | E | gmr > radius — physically impossible: GMR ≤ radius for any current distribution inside the conductor (= e^(−μᵣ/4)·radius = 0.7788·radius for a solid round conductor; lower for stranded/ACSR). |
E.DOM.WIRE_CABLE_LAYERS | E | Cable layer radii do not nest: core ≥ insulation outer radius, t_insulation ≥ d_insulation/2, concentric-neutral strand circle inside the insulation, or d_shield outside d_cable / inside d_insulation. The construction is unbuildable. |
W.DOM.WIRE_GMR_RATIO | W | gmr/radius < 0.2 — real conductors span ~0.35 (ACSR 6/1, steel core carries little flux) to 0.826 (61-strand, Kersting tables); usually a units or transcription slip. |
W.DOM.WIRE_RAC_BELOW_RDC | W | r_ac < r_dc — skin and proximity effects can only increase resistance at any f > 0. |
W.DOM.WIRE_IMPLIED_RESISTIVITY | W | Implied resistivity ρ = r_dc·π·radius² outside [8·10⁻⁹, 3·10⁻⁷] Ω·m — the metallic range (annealed Cu 1.724·10⁻⁸ per IEC 60228 … steel ~1.4·10⁻⁷, widened for stranding/fill and temperature). The unit-error catcher: an Ω/km value entered in the Ω/m field lands three decades outside. |
W.DOM.WIRE_EPS_R_RANGE | W | Insulation eps_r outside [1.5, 10] — XLPE 2.3, EPR ~3, PVC 3–8; IEC 60287-1-1. |
I.DOM.WIRE_CURRENT_DENSITY | I | i_max implies a current density outside [0.5, 10] A/mm² — typical continuous ratings are 1–6 A/mm². |
E.DOM.GEOM_CONDUCTOR_OVERLAP | E | Two conductors' circles overlap (centre distance < sum of radii) — physically impossible cross-section. |
W.DOM.GEOM_CLEARANCE | W | An overhead conductor sits below 4 m (under distribution statutory clearances) or above 100 m — usually a feet-as-metres slip. |
W.DOM.GEOM_EARTH_RESISTIVITY | W | earth_resistivity outside [1, 10⁴] Ω·m — practical soils span ~10–1000 Ω·m. |
W.DOM.GEOM_CARSON_VALIDITY | W | The Carson series parameter k = √(ωμ₀/ρ)·S exceeds 0.25 for some conductor pair. The truncated series used by modified_carson/full_carson is accurate only for k ≪ 1 — which holds at distribution spacings and 50/60 Hz (Kersting & Green 2011 report < 1 % error) but degrades for very wide spacings, low earth resistivity, or high frequency. Consider earth_model = "deri". |
W.DOM.GEOM_BURIED_EARTH_MODEL | W | Buried conductors combined with full_carson (evaluated at the surface — the rigorous buried theory is Pollaczek 1926 / Saad et al. 1996; negligible at power frequency since burial depth ≪ earth skin depth, but the approximation is made explicit), or with deri when burial depth exceeds 10 % of the complex-depth magnitude p = √(ρ/jωμ₀) (Deri et al. 1981 assume |y| ≪ |p|). |
W.DOM.WIRE_SKIN_FREQUENCY | W | The geometry's frequency exceeds a wire's critical skin frequency fcrit = ρc/(π r² μ₀) — above it, constant r_ac and GMR-based internal inductance degrade (Jensen et al. 2001; Urquhart & Thomson 2015 quantify error growth with frequency). The guard that keeps this fundamental-frequency library honest. |
W.DOM.FREQUENCY_MISMATCH | W | meta.frequency is set and some line_geometry.frequency or linecode derivation.frequency differs. Frequencies are never rescaled (no OpenDSS-style base-frequency scaling exists in BMOPF) — recompile or fix the data. |
W.DOM.MIXED_FREQUENCY | W | No meta.frequency, but geometry/derivation frequencies within one network disagree — impedances computed at different frequencies must not share a network. |
W.DOM.LINE_IMPLIED_PER_LENGTH | W | A line with inline ABSOLUTE matrices also carries a descriptive length, and Z_self/length falls outside the plausible distribution per-metre range [10⁻⁶, 10⁻²] Ω/m — likely per-metre data mislabeled as section totals (or vice versa). Inline line matrices are totals and are never scaled by length. |
Every line and linecode stores a two-sided nominal-π: a series impedance with a shunt admittance half-block at the from-end (G_from/B_from) and the to-end (G_to/B_to). Which blocks are populated, and whether the two ends are equal, determines the model topology. The taxonomy makes the modelling assumption auditable and flags the parameterisations that are suspicious in distribution networks.
When a 3-wire LV network is detected, the structure of each linecode's R and X blocks is compared against three known impedance-transformation signatures from Geth, Heidari & Koirala (ACM e-Energy 2022, doi:10.1145/3538637.3538844):
| Code | Sev | Trigger & rationale |
|---|
E.INT.UNKNOWN_BUS | E | A component references a bus id that does not exist. |
E.INT.UNKNOWN_LINECODE | E | A line references a linecode that does not exist (distinct from unused linecodes). |
E.INT.UNKNOWN_WIRE_DATA | E | A line_geometry conductor references a wire_data id that does not exist. |
E.INT.UNKNOWN_LINE_GEOMETRY | E | A linecode's line_geometry back-reference points at a geometry that does not exist. |
E.INT.LINE_IMPEDANCE_SOURCE | E | A line has both a linecode reference and inline absolute R_series_/X_series_ matrices (ambiguous), or neither (no impedance). A line carries exactly one impedance source; units are unambiguous by location — linecode matrices are Ω/m and scale with length, inline line matrices are section totals in Ω and never scale. |
E.INT.LINE_DIM_MISMATCH | E | A line's terminal_map_from/terminal_map_to length does not equal its impedance matrix dimension (from the referenced linecode, the compiled geometry, or its inline matrices). Matrix row k is the impedance seen by terminal-map entry k, so the counts must match exactly: an n-conductor linecode/geometry belongs on an n-terminal line. This is an error, not a warning — some tools (e.g. OpenDSS) silently map/truncate to the shorter length, which drops conductors and their mutual coupling, or misaligns matrix rows with terminal roles (e.g. applying the phase-c row to a neutral terminal), and solves to a plausible-but-wrong answer. solve_opf/solve_pf likewise refuse rather than truncate. |
E.INT.UNKNOWN_TERMINAL | E | A terminal-map entry is not a terminal of the referenced bus — typos, or attempts to connect nodal elements directly to ground (forbidden by spec Table 10). |
E.INT.UNKNOWN_CONTROL_PROFILE | E | An IBR references a control_profile id that does not exist in the network's control_profile table. |
E.INT.VOLTAGE_AGGREGATION_INVALID | E | An IBR's voltage_aggregation is neither PER_PHASE nor AVERAGE — the engine cannot resolve which voltage the droop/limits reference. |
E.INT.CONTROL_PROFILE_CONFLICT | E | A control_profile declares both power_factor and a Volt-var/Volt-watt droop. These are mutually exclusive reactive-control modes; only one may be active. |
E.INT.VOLT_VAR_SHAPE | E | A volt_var droop does not have exactly 4 breakpoints and 2 q_limits — the piecewise curve is malformed and cannot be stamped. |
E.INT.VOLT_VAR_BREAKPOINTS | E | A volt_var droop's voltage breakpoints are not strictly increasing — the piecewise-linear curve is non-monotone and ill-defined. |
W.INT.VOLT_VAR_QLIMITS | W | A volt_var droop's q_limits are not in the expected [absorb ≤ 0, inject ≥ 0] order — usually a sign or ordering slip, though the curve still builds. |
E.INT.VOLT_WATT_SHAPE | E | A volt_watt droop does not have exactly 2 breakpoints and 2 p_limits — the curtailment curve is malformed and cannot be stamped. |
E.INT.VOLT_WATT_BREAKPOINTS | E | A volt_watt droop's voltage breakpoints are not strictly increasing — the curtailment curve is non-monotone and ill-defined. |
E.INT.DROOP_UNSUPPORTED | E | A Volt-var/Volt-watt droop uses an option the engine does not yet implement — a voltage_reference other than PN_PER_PHASE, or a q_unit/p_unit/q_ref/p_ref outside the supported set. |
W.INT.DIM_MISMATCH | W | Per-component vector-length mismatches that are recoverable/ambiguous rather than corrupting: generator/IBR per-phase p_*/q_*/cost/filter vectors vs phase count, i_max length vs conductor count, load setpoint length vs configuration, source vm/va vs map length. (The line-impedance-matrix-vs-terminal-count case is the stricter E.INT.LINE_DIM_MISMATCH.) |
W.INT.IMAX_NO_NEUTRAL | W | A star generator/IBR with ≥2 phases rates only its phase conductors (i_max length = phases); add a trailing entry for the neutral conductor, which can carry more current than the phases under unbalance compensation. |
W.INT.PADDED_MATRIX | W | All-zero row/column pairs in linecode impedances — padded conductors demonstrably wreck NLP performance (22 → 590 Ipopt iterations in (ref. 2) Table 3); shrink the matrix and use terminal maps. |
E.INT.NO_VOLTAGE_REFERENCE | E | A galvanic island (transformer windings are separations) with no source, perfect grounding, or grounding shunt — voltages there are defined only up to a shift (the IEEE-123 "bus 610" rank deficiency (ref. 2)). A shunt counts only if its admittance has nonzero row sums, so a pure delta capacitor bank correctly does not anchor an island. |
W.INT.WYE_WITHOUT_NEUTRAL | W | A wye-configured load/generator at a bus with no identifiable neutral — implies an undeclared ground return; in 3-wire sections only delta connections are expected. |
W.INT.FLOATING_LOAD_TERMINAL | W | A load or generator references a phase terminal that no branch (line, switch, or transformer winding) uses on the same bus. The voltage at that terminal is decoupled from the rest of the network — KCL is trivially satisfied there and the power balance constraint is degenerate. Common cause: a 3-phase load connected to a 2-wire section, or a terminal number typo. Terminals at voltage-source buses and neutral terminals are excluded (sources pin voltages; neutrals are often grounded implicitly). |
W.INT.UNUSED_BUS_TERMINAL | W | A bus declares a terminal in terminal_names that is not referenced by any component at that bus (no branch end, load, generator, shunt, or voltage source uses it). The terminal adds a free voltage variable with no KCL constraint — pure numeric overhead. Almost always a conversion artifact or a missing connection. Voltage-source buses are excluded (the source pins every declared terminal regardless). |
W.INT.LOW_IMPEDANCE_LINE | W | Lines whose total series impedance is below 10⁻³× the network median — they degrade conditioning; the spec's lossless switch object is the intended model (ref. 2). |
I.INT.UNIFORM_GEN_COST | I | Groups of generators with identical cost vectors — any dispatch split among them is optimal (degeneracy); diversify costs for benchmark use. |
Rules the JSON Schema cannot express.
| Code | Sev | Trigger & rationale |
|---|
W.SPEC.N_SOURCES | W | Voltage-source count ≠ 1 (spec Eq. 17 requires exactly one in this version). |
W.SPEC.BAD_CONFIG | W | A configuration string outside SINGLE_PHASE/WYE/DELTA. |
W.SPEC.CONFIG_ARITY | W | Terminal-map arity inconsistent with the configuration (SINGLE_PHASE = 2, WYE = 4, DELTA = 3). |
E.SPEC.DUPLICATE_TERMINAL | E | A component's terminal_map (or terminal_map_from/terminal_map_to for lines/switches) contains the same terminal label more than once — a degenerate connection that collapses two distinct conductors onto one. |
I.SPEC.LOAD_PHASE_TO_PHASE | I | A SINGLE_PHASE load/generator whose two terminals are both phase conductors (neither is the bus neutral) — a phase-to-phase (delta-connected) single-phase element. Valid per spec; flagged as context because the modelling is distinct from the more common phase-to-neutral case. |
E.SPEC.WYE_MISSING_NEUTRAL | E | A WYE load/generator whose last terminal is not the neutral of its bus — the return path is not the neutral conductor, which violates the spec's WYE connection semantics. |
E.SPEC.WYE_DUPLICATE_PHASE | E | A WYE load/generator has duplicate phase terminals in the non-neutral slots. |
E.SPEC.DELTA_HAS_NEUTRAL | E | A DELTA load/generator includes the bus neutral in its terminal map — delta elements must be phase-to-phase only. |
E.SPEC.DELTA_DUPLICATE_PHASE | E | A DELTA load/generator has duplicate phase terminals. |
W.SPEC.CAP_QRATED_LENGTH | W | A capacitor's q_rated length is inconsistent with its configuration (SINGLE_PHASE → 1, WYE → #phases, DELTA → #pairs). |
E.SPEC.CAP_VRATED | E | A capacitor has non-positive v_nom — the susceptance B = q_rated/v_nom² is undefined. |
E.SPEC.CAP_NEGATIVE_Q | E | A capacitor has negative q_rated entries. A capacitor bank has non-negative susceptance (Q = B·V², B ≥ 0); a negative value is an inductor/reactor and must be modelled as a shunt with negative B, not a capacitor. |
W.SPEC.CAP_WYE_NO_NEUTRAL | W | A WYE capacitor has no resolvable neutral terminal in its terminal_map. Each phase is stamped against the neutral, so without one the bank assembles an all-zero susceptance and is silently ignored by the OPF. Name the return terminal n, or use SINGLE_PHASE/DELTA. |
W.SPEC.XFMR_TMAP_ARITY | W | Transformer terminal-map lengths off the per-subtype spec values — also the deliberate tripwire for unconverted wye-wye units. |
W.SPEC.INV_TOPOLOGY | W | An IBR topology outside the spec-allowed set (FOUR_LEG/THREE_LEG/SINGLE_PHASE). |
W.SPEC.INV_TMAP_ARITY | W | An IBR's terminal_map length does not match the arity its topology requires. |
W.SPEC.INV_PRIME_MOVER | W | An IBR prime_mover is outside the spec-allowed set (PV, BATTERY, GENERIC, STATCOM, DSTATCOM). |
W.SPEC.TERMINAL_TYPES | W | The source file used non-string terminal identifiers; they were coerced at parse (aliases or verbatim — the finding says which). |
I.SPEC.MATRIX_TRIANGULAR | I | Impedance matrices stored upper-triangular; the spec defines full row-first storage. Read fine; normalise before publishing. |
| Code | Sev | Trigger & rationale |
|---|
E.SOL.INFEASIBLE | E | Solver reports INFEASIBLE with no primal candidate. A time limit or local failure without a candidate is reported separately, not as a proof of infeasibility. |
W.SOL.NO_CANDIDATE | W | No primal candidate is available to profile. Termination alone does not establish network infeasibility; inspect result count and primal status. |
I.SOL.CONTROLLER_COMPLIANCE | I | Separate exact Volt-watt cap compliance and declared modeled smooth-cap feasibility in SI, with output, caps, excesses, smoothing width/mode, and approximation error. Missing or unsupported modeled-curve evidence is indeterminate; exact-cap violations retain their original errors. This does not authenticate the supplied model evidence. |
W.SOL.INCOMPLETE_RESULT | W | Declared result data are missing. The profile is indeterminate; omitted terms must not be interpreted as zero or as checks passed. Structured detail lists missing paths. |
E.SOL.PHASOR_INCONSISTENT | E | Supplied vm differs from hypot(vr, vi) beyond max(0.2% of the computed magnitude, 1 μV). All voltage-dependent checks use the rectangular phasor, without mutating the supplied result. |
E.SOL.REFERENCE_VIOLATION | E | Rectangular bus voltage disagrees with an explicit perfect ground or supported ideal WYE/SINGLE_PHASE source reference beyond max(0.2% of reference magnitude, 1 μV). This checks references, not full network equations. |
W.SOL.LIMIT_UNASSESSED | W | A declared limit cannot be assessed: a sequence limit outside the complete three-phase domain, or a line limit with incomplete terminal maps, unsupported angle bounds, or undefined endpoint angle. Structured detail identifies the reason; profiling reports indeterminate coverage. |
W.SOL.VUF_UNDEFINED | W | A declared voltage-unbalance ratio cannot be assessed because the positive-sequence magnitude is at most 1 μV. The bus-limit contract returns indeterminate rather than inventing a ratio. |
E.SOL.NAN_IN_RESULT | E | One or more numeric fields in the result dict contain NaN or Inf. Indicates a solver failure or extraction bug even when the termination status appears feasible. |
E.SOL.VOLT_VIOLATION | E | A bus terminal voltage magnitude (vm, vpn, vpp, sequence component, or vuf ratio) lies outside its declared bound. |
W.SOL.VOLT_ACTIVE | W | A voltage magnitude is within 1 % of its bound — the constraint is near-active (binding at the tolerance level). |
E.SOL.ANGLE_VIOLATION | E | A line conductor's signed theta_from - theta_to angle lies outside its declared window, or a bus phase pair's centered angle difference θⱼ − θₖ − (va_nom[j] − va_nom[k]) lies outside the bus's va_diff_min/va_diff_max. Recomputed from the primal solution via atan2 per terminal, independent of the constraint's own bilinear expression. |
W.SOL.ANGLE_ACTIVE | W | A signed line angle or centered bus phase-pair angle difference is near a va_diff bound (near-active). |
E.SOL.THERMAL_VIOLATION | E | A thermal/loading limit is exceeded in the solved result: a line conductor current at either endpoint (including pi-shunts), or a switch conductor current, over i_max or its ground-referenced apparent power |S|=v·cm over s_max (element or linecode); a transformer per-winding current over i_max_from/i_max_to; or a transformer winding coil apparent power |S| over its nameplate cap (s_max, the per-winding share of s_rating; recorded in the result so no coil-voltage reconstruction is needed). |
W.SOL.THERMAL_ACTIVE | W | The same current or apparent-power quantity is within 1 % of its limit — the thermal limit is near-active. |
E.SOL.GEN_VIOLATION | E | A generator's solved operating point (per terminal) violates a declared limit: pg/qg outside p_min/p_max/q_min/q_max, the optional s_max apparent-power circle, or the optional i_max current-magnitude circle. |
W.SOL.GEN_ACTIVE | W | Generator dispatch is within 1 % of a bound — the bound is near-active. |
E.SOL.IBR_VIOLATION | E | An IBR's solved operating point (per phase) violates a declared limit: pg outside p_min/p_max, the s_max apparent-power circle, or the optional i_max current-magnitude circle. |
W.SOL.IBR_ACTIVE | W | An IBR dispatch is within 1 % of a P bound — the bound is near-active. |
W.SOL.IBR_PF_DEVIATION | W | A constant-power-factor IBR's solved operating point deviates from its commanded PF beyond tolerance — the PF-coupling constraint residual is non-trivial. |
W.SOL.LOAD_RESIDUAL | W | For a constant_power load, solved pd/qd differs from p_nom/q_nom by more than 1 W / 1 var — the bilinear constant-power constraint has a non-trivial residual; the solver may not have converged tightly. Not emitted for voltage-dependent models (where pd ≠ p_nom is expected). |
W.SOL.LOAD_MODEL_RESIDUAL | W | For a voltage-dependent load, the realised pd/qd is inconsistent with what the load model predicts at the solved terminal voltage by more than 1 W / 1 var. Indicates the load model constraint was not satisfied — a solver convergence or result extraction issue. |
I.SOL.LOAD_VD_SUMMARY | I | Aggregate realised vs nominal P/Q across all voltage-dependent sub-loads. Quantifies the total demand shift due to voltage sensitivity at the solved operating point. |
W.SOL.POWER_BALANCE | W | Network-wide active power balance error (Σpg − Σpd − Σp_loss) exceeds 1 % of total load — a significant mismatch that may indicate a lossy model, a missing component, or a result extraction issue. |
I.SOL.BINDING_SUMMARY | I | Summary count of violated and near-active bounds across all categories (voltage, thermal, generator). Always emitted for feasible solutions. |
I.SOL.LOSS_FRACTION | I | Line losses exceed 20 % of total generation — unusually high; may indicate a high-impedance feeder, a model issue, or an extreme operating point. |
W.SOL.NEG_LOSS | W | A line or transformer dissipates negative active power (p_loss < 0) beyond numerical noise — non-physical for a passive branch, which cannot generate active power. Tolerance is throughput-relative (p_loss < −max(1 W, 1e-4·|S_through|)). Signals a non-converged / ill-conditioned solution, a sign error, or a negative-resistance input. Reactive loss is excluded, as line charging / capacitive shunts make q_loss legitimately negative. |
I.SOL.NEUTRAL_SHIFT | I | Maximum neutral terminal voltage magnitude across all buses, with the bus identifier. Non-zero neutral shift indicates load unbalance or grounding impedance. |
W.SOL.INIT_LEVEL_MISMATCH | W | One or more terminals have vm_init / vm_solved outside [0.1, 10] — the initialisation used the wrong voltage level (e.g. source voltage applied to an LV bus via flat warm-start). Solver may still converge but local-minimum risk is elevated. Only emitted when result["initialisation"] is present. |
W.SOL.INIT_LARGE_ERROR | W | One or more phase terminals have an initialisation error exceeding 20 % of the solved voltage magnitude — the start point was a poor approximation of the solution. |
I.SOL.INIT_NEUTRAL_NONZERO | I | One or more neutral terminals were initialised with non-zero voltage. Neutral start values should be zero; non-zero values indicate an initialisation inconsistency. |
| Code | Sev | Trigger & rationale |
|---|
E.INT.UNKNOWN_DC_BUS | E | An ibr.dc_bus, dc_branch endpoint, dc_load/dc_source.dc_bus, or dc_grounding.dc_bus references a dc_bus id that does not exist. |
E.INT.UNKNOWN_DC_TERMINAL | E | A DC terminal-map entry (converter DC port, branch from/to, grounding, load/source) names a terminal not in the target dc_bus.terminal_names. |
E.INT.NO_DC_VOLTAGE_REFERENCE | E | A connected DC island (dcbuses joined by dcbranches) has no dc_grounding (perfect or resistive) — the signed DC voltages float (rank-deficient). The DC analog of E.INT.NO_VOLTAGE_REFERENCE. |
W.INT.DC_FED_AC_ISLAND | W | A converter feeds an AC bus whose AC island has no AC voltage reference (source/grounding) and no grid-forming converter — the bus is energised only through the MVDC link (a dangling converter, not embedded in a referenced AC system). Intentional DC-fed feeders should mark a converter grid_forming. |
E.INT.DC_NO_VOLTAGE_CONTROL | E | A connected DC island has no converter on DC-voltage control (dc_control = "V" or "droop") — the DC operating voltage is underdetermined. The DC analog of needing an AC slack; designate a master/droop converter (master–slave or droop, per MTDC practice). |
E.DOM.DC_POLE_ROLE_REQUIRED | E | A dc_bus carries a line-to-neutral or line-to-line voltage bound but lacks the pole role(s) needed to orient it (POSITIVE/NEGATIVE, and a return for L-N). The roles are the sign tag that keeps the bound linear; without them it cannot be applied. |
W.DOM.DC_DROOP_BOUNDS | W | A dc_control="droop" converter's droop conflicts with its own capability: either dc_p_ref lies outside the net active-power box [Σp_min, Σp_max] (else ±Σsmax), or the converter also runs a `powerfactor` profile whose forced reactive power shrinks the s_max-circle active headroom below the droop's saturation. The droop equality then fights the P/Q/S limits and the OPF can turn infeasible. |
E.SPEC.DC_BUS_ARITY | E | A dc_bus does not have 1 (monopole/earth return), 2 (pole+return), or 3 (bipole) terminals. |
E.SPEC.DC_BRANCH_ARITY | E | A dc_branch's terminal_map_from and terminal_map_to differ in length (conductor count must match end to end). |
E.SPEC.DC_BRANCH_R_DIM | E | A dc_branch's per-conductor r array length does not equal its conductor count. |
E.SPEC.DC_PORT_MISSING_MAP | E | An IBR references a dc_bus but has no dc_terminal_map. |
E.SPEC.DC_PORT_ARITY | E | An IBR's dc_terminal_map spans more terminals than its dc_bus has wires. |
E.SPEC.DUPLICATE_DC_TERMINAL | E | A DC terminal map (branch or converter port) lists the same terminal twice. |
E.DOM.DC_R_NEGATIVE | E | A dc_branch.r (or dc_grounding.r) has a negative entry — resistances are nonnegative. |
E.DOM.DC_GROUNDING_R_NEGATIVE | E | A dc_grounding.r is negative. |
E.DOM.DC_VBOUND_INVALID | E | Within a bound family (v_dc, vdc_ln, vdc_ll) a minimum exceeds its maximum. |
E.DOM.DC_LL_BOUND_NO_POLE | E | A line-to-line bound is declared on a dc_bus with fewer than 3 wires (no positive+negative pole). |
E.DOM.DC_LN_BOUND_NO_NEUTRAL | E | A line-to-neutral bound is declared on a dc_bus with no return/neutral conductor (fewer than 2 wires). |
E.DOM.DC_RATING_NONPOSITIVE | E | A dc_branch.i_max/p_max is non-positive. |
W.DOM.DC_VBOUND_INCONSISTENT | W | The line-to-ground / line-to-neutral / line-to-line bound families cannot hold simultaneously given the topology + grounding (e.g. vdc_ll_max < 2 × the line-to-ground floor on a midpoint-grounded symmetric bipole). |
W.DOM.DC_POLE_SIGN | W | A terminal's bound sign contradicts its declared pole role (a POSITIVE pole with v_dc_max ≤ 0, or a NEGATIVE pole with v_dc_min ≥ 0). |
W.DOM.DC_MULTIPOINT_GROUNDING | W | A connected DC island has more than one grounding point — this closes an earth loop and permits circulating earth-return current (often deliberate for bipoles; verify). |
W.DOM.DC_BUS_NO_CONVERTER | W | A dc_bus has no converter (IBR) attached — an islanded DC node. |
W.RED.DC_BRANCH_SELF_LOOP | W | A dc_branch connects a dc_bus to itself — it carries no transfer. |
I.RED.DC_PARALLEL_BRANCHES | I | Two dc_branches connect the same unordered dc_bus pair. |
W.RED.DC_REDUNDANT_GROUNDING | W | A dc_grounding earths a terminal already in the dcbus's `perfectlygrounded_terminals`. |
E.SOL.DC_VOLT_VIOLATION | E | Post-solve: a signed DC node voltage lies outside its [v_dc_min, v_dc_max] band. |
E.SOL.DC_THERMAL_VIOLATION | E | Post-solve: a DC branch conductor current exceeds its i_max. |
| Code | Sev | Trigger & rationale |
|---|
E.CONTRACT.PARALLEL_TERMINAL_RELATION_MISMATCH | E | The declared scalar aggregate line's admittance differs from the sum of the explicitly mapped source-member admittances. The target therefore fails even the unconstrained terminal-current relation. |
W.CONTRACT.PARALLEL_MEMBER_LIMIT_LOSS | W | The aggregate preserves the summed scalar terminal admittance but its current rating defines an inner restriction or outer relaxation of the source member-current-limit region. Detail includes PSK-000001, the classification, exact voltage-drop bounds, and a concrete current witness. |
I.CONTRACT.NOT_APPLICABLE | I | A declared executable contract is outside its implemented domain, for example because the initial parallel-member check received a multiconductor or shunted line. No preservation conclusion is drawn. |
W.CONTRACT.INDETERMINATE | W | Required source, target, mapping, impedance, or rating evidence is missing or unresolved. No preservation conclusion is drawn; detail names the missing evidence and recommended follow-up. |
E.CONTRACT.NEUTRAL_IDENTITY_LOSS | E | A mapped target bus has no identifiable explicit neutral terminal. Omitting it does not establish that its voltage, current, limits, or grounding relation are represented by the mathematical reference. |
E.CONTRACT.NEUTRAL_CONTINUITY_MISMATCH | E | The target changes whether mapped bus neutrals are connected through neutral-bearing lines, closed switches, or single-phase autotransformers. A matching simple bus graph is not sufficient. |
E.CONTRACT.GROUND_REFERENCE_RELATION_MISMATCH | E | The target changes a mapped neutral's declared perfect-ground, scalar finite-grounding-shunt, or voltage-source-reference relation. Those declarations are not interchangeable. |
I.CONTRACT.NEUTRAL_GROUND_NOT_APPLICABLE | I | The neutral/ground/reference check is outside its implemented domain, for example because the source lacks explicit neutrals or a grounding shunt couples multiple terminals. No preservation conclusion is drawn. |
W.CONTRACT.NEUTRAL_GROUND_INDETERMINATE | W | A mapped bus or scalar grounding relation is missing or unresolved. No preservation conclusion is drawn; detail names the missing evidence and recommended follow-up. |
E.CONTRACT.CLAIMED_FEASIBLE_SOLUTION_INVALID | E | A result labelled LOCALLY_SOLVED, OPTIMAL, or ALMOST_LOCALLY_SOLVED contains non-finite values or violates a declared bus voltage or angle limit when independently recomputed by profile_solution. The contract finding retains the underlying E.SOL.* evidence. |
I.CONTRACT.SOLUTION_STATUS_NOT_APPLICABLE | I | The solver did not claim a feasible result, or the network has no declared bus terminals. The initial claimed-solution contract therefore makes no validity conclusion. |
W.CONTRACT.SOLUTION_VALIDATION_INDETERMINATE | W | Termination status or required vr/vi/vm data for a declared bus terminal is missing. No validation conclusion is drawn; detail identifies the missing evidence. |
E.CONTRACT.LOAD_VOLTAGE_BASE_MISMATCH | E | Scientific contract load_voltage_base_consistency found that a voltage-dependent load's v_nom lies outside the declared ratio band for its source-propagated connection-coordinate base. |
I.CONTRACT.LOAD_VOLTAGE_BASE_NOT_APPLICABLE | I | The initial contract has no unique voltage-dependent WYE or DELTA load to check. |
W.CONTRACT.LOAD_VOLTAGE_BASE_INDETERMINATE | W | A selected load, numeric v_nom, or source-reachable bus voltage base is unavailable, so connection-coordinate consistency cannot be decided. |
E.CONTRACT.TRANSFORMER_TAP_DOMAIN_LOSS | E | The mapped target transformer has a different continuous tap interval from the adjustable source: an inner restriction, outer extension, shifted overlap, or disjoint decision domain. Detail includes PSK-000005, both intervals, the classification, and a tap witness admitted by only one domain. |
I.CONTRACT.TRANSFORMER_TAP_NOT_APPLICABLE | I | The source is not an adjustable continuous tap transformer in the implemented domain, the subtype is unsupported or changes, or mapped non-tap declarations differ. No domain-preservation conclusion is drawn. |
W.CONTRACT.TRANSFORMER_TAP_INDETERMINATE | W | A mapped transformer, complete numeric tap interval, or admissible start is missing or invalid. No domain-preservation conclusion is drawn. |
E.CONTRACT.TRANSFORMER_WINDING_INCIDENCE_MISMATCH | E | The target changes a mapped transformer winding side, stored orientation, or ordered terminal-to-coil incidence. A bare bus_from/bus_to swap is not a complete typed transformer reversal. |
E.CONTRACT.TRANSFORMER_WINDING_BASE_RATIO_MISMATCH | E | The target changes a mapped v_nom_from/v_nom_to winding reference or the resulting fixed effective coil ratio under the subtype's connection convention. |
I.CONTRACT.TRANSFORMER_WINDING_NOT_APPLICABLE | I | The initial winding-convention contract does not cover the subtype, adjustable tap, non-bijective mapping, or subtype-changing reversal. No preservation conclusion is drawn. |
W.CONTRACT.TRANSFORMER_WINDING_INDETERMINATE | W | A mapped transformer, bus, terminal map, positive winding reference, fixed tap, or constructible incidence relation is missing. No preservation conclusion is drawn. |
E.CONTRACT.DECISION_MANIFEST_EVIDENCE_GAP | E | A manifest claiming exact decision equivalence omits a required admissible-domain, terminal, observation, constraint, decision-variable, objective, or recovery disposition, or lacks the evidence reference or justification required by that disposition. Terminal evidence alone is insufficient. |
E.CONTRACT.DECISION_MANIFEST_UNRESOLVED_OBLIGATION | E | A manifest claiming exact decision equivalence explicitly marks a required dimension as unassessed or not_preserved, contradicting the unqualified exactness claim. |
I.CONTRACT.DECISION_MANIFEST_NOT_APPLICABLE | I | The manifest does not claim exact decision equivalence. A narrower terminal, inner, outer, or approximate claim lies outside this completeness gate and is not mislabeled as a failure. |
W.CONTRACT.DECISION_MANIFEST_INDETERMINATE | W | The manifest schema, identity, claim, dimension object, or disposition is missing, malformed, or unsupported. No declaration-completeness conclusion is drawn. |
E.CONTRACT.KRON_BOUNDARY_RELATION_MISMATCH | E | The target series impedance differs from the source Schur-complement boundary relation in the declared phase coordinate order. |
E.CONTRACT.KRON_GROUNDING_PRECONDITION | E | The eliminated source neutral is not perfectly grounded at every source line endpoint, so the three-wire Kron target is not exact for the declared network boundary. |
I.CONTRACT.KRON_NOT_APPLICABLE | I | The initial Kron contract does not cover the supplied conductor count, terminal order, endpoint mapping, line shunts, or self-loop shape. No reduction conclusion is drawn. |
W.CONTRACT.KRON_INDETERMINATE | W | A mapped line, bus, conductor order, impedance matrix, or endpoint declaration is missing or unresolved, so the Kron boundary cannot be decided. |
W.CONTRACT.KRON_RECOVERY_INDETERMINATE | W | The required eliminated-terminal recovery map is missing, malformed, or names a different terminal, so internal recovery obligations cannot be decided. |
E.CONTRACT.SEQUENCE_SYMMETRY_MISMATCH | E | A source series or shunt factor is not circulant in the declared phase order and can mix positive, negative, and zero sequence components. |
E.CONTRACT.SEQUENCE_DOMAIN_MISMATCH | E | The declared boundary, grounding, device, decision, or observation domain is not closed under the positive-sequence restriction. |
E.CONTRACT.SEQUENCE_RELATION_MISMATCH | E | The scalar target relation differs from the source positive-sequence eigenvalue in the declared convention. |
I.CONTRACT.SEQUENCE_NOT_APPLICABLE | I | The initial positive-sequence contract does not cover the supplied conductor count, terminal order, factor shape, or unsupported shunt structure. |
W.CONTRACT.SEQUENCE_INDETERMINATE | W | A source or target factor, terminal map, or required collapse-domain declaration is missing or unresolved. |
E.CONTRACT.STATE_UPDATE_PROVENANCE_LOSS | E | The target freezes or omits update provenance for a source equivalent that varies over a non-singleton state domain. |
E.CONTRACT.STATE_DOMAIN_MISMATCH | E | The target state domain differs from the source domain, so the declared equivalent does not cover the same state range. |
E.CONTRACT.STATE_BASE_ALIGNMENT_MISMATCH | E | The target calibration state differs from the source base state. |
I.CONTRACT.STATE_EQUIVALENT_NOT_APPLICABLE | I | The initial state-dependent-equivalent contract does not cover the supplied domain declaration. |
W.CONTRACT.STATE_EQUIVALENT_INDETERMINATE | W | A required state parameter, domain, base state, or update declaration is missing or malformed. |
E.CONTRACT.REFERENCE_LOSS | E | A target island loses a voltage reference present in the source island. |
E.CONTRACT.SINGULARITY_CHANGE | E | A target island becomes rank-deficient relative to a full-rank source island. |
I.CONTRACT.REFERENCE_SINGULARITY_NOT_APPLICABLE | I | No connected-island reference evidence was supplied, so this initial validation bundle is not applicable. |
W.CONTRACT.REFERENCE_SINGULARITY_INDETERMINATE | W | Reference-analysis island records or their mapping are missing or malformed. |
E.CONTRACT.TERMINAL_ORDER_MISMATCH | E | Target endpoint terminal maps do not follow the declared permutation. |
E.CONTRACT.PERMUTATION_RELATION_MISMATCH | E | The target series primitive is not the source primitive conjugated by the declared permutation. |
I.CONTRACT.PERMUTATION_NOT_APPLICABLE | I | The explicit permutation contract does not apply because a bijection, line, or compatible matrix dimensions are unavailable. |
W.CONTRACT.PERMUTATION_INDETERMINATE | W | A required source or target line primitive or terminal-map record is missing or malformed. |
E.CONTRACT.FEASIBILITY_RESIDUAL_VIOLATION | E | An independently computed equation, KCL, power-balance, or recovery residual exceeds its declared tolerance. |
E.CONTRACT.FEASIBILITY_DEVICE_LIMIT_VIOLATION | E | Independent device-limit validation reports one or more violations. |
I.CONTRACT.FEASIBILITY_NOT_APPLICABLE | I | No solved/feasible solver status was supplied for the residual-witness contract. |
W.CONTRACT.FEASIBILITY_INDETERMINATE | W | A solved result lacks finite, independently computed residual or device-limit witness fields. |
E.CONTRACT.UNIT_SYSTEM_MISMATCH | E | Target serialization declares a different unit system. |
E.CONTRACT.BASE_MAP_MISMATCH | E | Target serialization does not preserve the declared unit/base map. |
E.CONTRACT.SERIALIZED_PAYLOAD_MISMATCH | E | Target serialization has a different canonical semantic payload hash. |
W.CONTRACT.UNIT_BASE_SERIALIZATION_INDETERMINATE | W | Required unit/base or canonical semantic-hash metadata is missing or malformed. |