Finding-code reference
The complete catalog of finding codes, grouped by family. Codes are stable identifiers — filter on f.code, never on message text. Severity prefix: E. error, W. warning, I. info (see Analysis & reports for the severity semantics).
For deterministic offline lookup, use explain_finding(code) or bin/bmopf explain-finding CODE --pretty. The checked machine-readable export is generated/finding-registry.json, generated from this page. A catalog entry explains the stable code class; a Finding instance's component, message, and detail describe one observation. Neither should be treated as an inferred root cause or an automatically safe repair.
The EXPORT. family comes from explicit to_dss admission. The CONTRACT. codes at the end come from the explicit source-versus-target scientific contracts, which must be invoked directly with a source, a target, and a mapping. And a case imported through from_dss carries findings this package did not author: PowerIO's conversion diagnostics, kept under their own codes (EMIT., READ., PARSE., LOWER., …, one namespace per pipeline stage) and cataloged by powerio rather than here. They report what the OpenDSS import could not carry into BMOPF, not the quality of what arrived, and the leading namespace is what tells them apart from the codes below. See Ingest warnings.
EXPORT — explicit conversion admission
These Findings are emitted by to_dss, including on refusal, rather than by analyze. See OpenDSS export.
| Code | Sev | Trigger & rationale |
|---|---|---|
W.EXPORT.DSS_RATING_UNVERIFIED | W | DSS re-import changes component/terminal correspondence or declared bounds/ratings, fails, or lies outside the static AC domain. Evidence reports indeterminate, changed source/target declarations when available, PowerIO version, unassessed dimensions and powerio#762. Default export refuses; explicit allow_unverified_ratings=true permits power-flow verification and retains the warning. It makes no OPF preservation claim. |
COMP — completeness
| Code | Sev | Trigger & rationale |
|---|---|---|
E.COMP.MISSING_REQUIRED | E | A component lacks a field the data model marks required (incl. the seven transformer required fields per subtype). The case cannot be instantiated as an OPF without it. |
SCHEMA — unknown fields & metadata validation
| Code | Sev | Trigger & rationale |
|---|---|---|
I.SCHEMA.UNKNOWN_FIELDS | I | Fields present that the data model does not define (underscore-prefixed extension keys are exempt). Cataloged rather than rejected: they are either converter passthrough or schema-evolution candidates — but a spec-conformant consumer will ignore them, so nothing essential should live there. |
E.SCHEMA.REQUIRED | E | JSON Schema validation: a required field is missing at the reported path. |
E.SCHEMA.TYPE | E | JSON Schema validation: a field has the wrong JSON type (e.g. string where a number is expected) at the reported path. |
E.SCHEMA.ENUM | E | JSON Schema validation: a value is not among the allowed enumerated values. |
E.SCHEMA.RANGE | E | JSON Schema validation: a numeric value violates a minimum/maximum (or exclusive-bound) range constraint. |
I.SCHEMA.OTHER | I | JSON Schema validation: a schema violation not covered by the specific codes above (catch-all, carrying the raw reason and path). |
I.SCHEMA.VERSION_UNKNOWN | I | The declared spec version has no bundled JSON Schema document, so structural schema validation was skipped for this case. |
W.SCHEMA.META_SCHEMA_URI | W | meta.$schema is present but does not look like an https:// URI. The field is intended to point to the versioned BMOPF JSON Schema document. |
W.SCHEMA.META_DATE_FORMAT | W | meta.created or meta.modified is not a recognizable ISO 8601 datetime string (expected YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). |
I.SCHEMA.META_LICENSE_URI | I | meta.license is a long string that does not look like a URI. Short SPDX identifiers (e.g. CC-BY-4.0) are fine; longer values should be a https:// URI pointing to the license text. |
W.SCHEMA.META_ORCID_FORMAT | W | An entry in meta.authors has an orcid field that does not match the standard ORCID format XXXX-XXXX-XXXX-XXXX. |
W.SCHEMA.META_SOURCE_URL | W | A url field in meta.sources is present but does not look like an https:// URI. |
MIGRATE — input migration notes
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 |
|---|---|---|
W.MIGRATE.XFMR_SERIES_FIELDS | W | Legacy lumped transformer r_series/x_series fields were assigned to the wye winding and zeroed on the delta winding. The transformation follows the legacy convention but should be checked against the source model. |
W.MIGRATE.FIELD_RENAMES | W | One or more legacy component fields were renamed to their current schema names, including voltage, winding-configuration, or IBR voltage-aggregation fields. |
W.MIGRATE.XFMR_EXTRAS_FOLD | W | Transformer fields temporarily relocated under extras.transformer by schema 0.1.0 were folded back onto their transformer record. |
W.MIGRATE.NWINDING_NOMINAL_TAP | W | An exact unit n-winding winding tap_ratio, with no competing tap bounds or control declaration, was normalized to the implicit nominal ratio. The original value and winding index remain in migration evidence; this does not enable non-unit taps or tap optimization. |
W.MIGRATE.TOP_LEVEL_EXTRAS_FOLD | W | Component tables temporarily relocated under top-level extras by schema 0.1.0 were folded back onto the network record. |
W.MIGRATE.LOAD_MODEL_CASE | W | Uppercase legacy/upstream load-model enum values were lowercased to the values used by this package and its bundled schema. |
CONN — connectivity & topology
| Code | Sev | Trigger & rationale |
|---|---|---|
E.CONN.DISCONNECTED | E | More than one connected component (over lines, closed switches and transformers). Buses without a path to a source have no defined operating point. |
E.CONN.SELF_LOOP | E | A line, switch, or transformer has identical bus_from and bus_to — a zero-length branch that creates a degenerate KVL constraint and is almost always a wiring error. |
W.CONN.MESHED | W | Physical branch count exceeds the spanning-forest count — cycles exist. Counted over branch elements, so electrically parallel lines are correctly detected as meshes. Structured detail separates simple cycles, parallel excess, and transformer-mediated cycles and gives bounded closing-branch witnesses. Not an error (the spec supports meshes) but radial-only methods will fail. Radiality is assessed over phase-carrying branches: a line or closed switch that maps only neutral- or earth-role terminals at both ends (for example, a neutral bond beside a service transformer) closes no phase-conductor cycle. Such cycles are counted in neutral_only_cycle_rank (result and detail) and do not raise this warning. |
W.CONN.DANGLING | W | Degree-1 buses with no load, generator or shunt attached — dead ends that contribute variables and constraints but no physics; often conversion artifacts (e.g. switch far-ends). |
GEO — declared geographic coordinates
See the spatial diagnostics guide for illustrated interpretation and the separate S.* candidate / R.* review catalog. Coincident buses, shared routes and zero transformer extent alone emit no Finding.
These checks require a network-level WGS84 declaration. An absent or different CRS leaves geodesic comparisons unassessed; field names alone do not establish a geographic frame. The component's structured detail records the measured values, threshold, and CRS evidence.
| Code | Sev | Trigger & rationale |
|---|---|---|
W.GEO.WGS84_RANGE | W | A finite bus coordinate is outside the longitude ±180° or latitude ±90° range despite an explicit network WGS84 declaration. This suggests a coordinate or CRS metadata error. |
W.GEO.LINE_SHORTER_THAN_CHORD | W | A line's physical length (meta.physical_length_m, or declared length when no physical/regularization metadata prevents that interpretation) is more than max(5 m, 10% of chord) shorter than the geodesic distance between its explicitly declared WGS84 bus coordinates. An explicitly regularized electrical length without physical length, or invalid explicit physical metadata, makes this check indeterminate. Structured evidence preserves both lengths and the comparison basis; inspect coordinates, units, and length provenance. |
W.GEO.ROUTE_ENDPOINT_GAP | W | A declared WGS84 route polyline's endpoints differ from the connected bus positions by more than max(20 m, 10% of chord), with reversed route direction allowed. Inspect the bus reference, route provenance, and snapping assumptions. |
VOLT — voltage levels
| Code | Sev | Trigger & rationale |
|---|---|---|
E.VOLT.LEVEL_MISMATCH | E | BFS voltage propagation reaches a bus with two inconsistent nominal voltages (beyond 5 %). The network's transformer ratios and topology contradict each other. Lines and closed switches that map only neutral- or earth-role terminals at both ends (for example, a primary-to-secondary neutral bond beside a service transformer) carry no phase conductor and do not propagate a level. |
E.VOLT.LINE_CROSSING | E | A line (not a transformer) connects buses assigned to different voltage levels. Only transformers may cross levels; this is almost always a wiring error in the data. A neutral-only line (neutral- or earth-role terminals at both ends) carries no phase voltage and is not a crossing. |
W.VOLT.UNASSIGNED | W | Buses unreachable from any voltage source during propagation — likely islanded; their nominal voltage is unknown. A bus whose terminals are all neutral/earth-role and which is reached only through neutral-only branches (for example, a grounding-electrode bus) has no phase level; it is listed in neutral_only_buses instead. A bus with phase terminals that is reached only through neutral-only branches still raises this warning, although connectivity counts it as connected: it has no phase supply. |
W.VOLT.XFMR_RATIO | W | A transformer's v_nom turns ratio disagrees (>10 %) with the voltage ratio of the levels it actually connects — ratio and placement are inconsistent. |
DIV — diversity & symmetry
These Findings describe repetition and balance in declared parameters. Network location, connection and other constraints determine whether any optimization symmetry follows; repeated values alone do not establish degeneracy.
| Code | Sev | Trigger & rationale |
|---|---|---|
W.DIV.LOAD_SYMMETRIC | W | Retained threshold: at least three assessed loads and fewer distinct ordered P/Q tuples than n_total ÷ 2. n_duplicates = n_total - n_distinct counts excess repetitions, not one identical group. Detail includes group/member counts and bounded examples. Review unexpected allocation patterns; repetition does not prove duplicate customers, interchangeable injections or solver degeneracy. |
I.DIV.LOAD_CV_LOW | I | Load p_nom coefficient of variation < 0.05 across ≥3 loads — essentially uniform loading. |
I.DIV.LOAD_PF_DSS_DEFAULT | I | Load power factor mean is within 1 % of 0.88 with CV < 0.05 — strongly suggests reactive power was never explicitly set and the OpenDSS default PF was inherited throughout. Compare with I.PROV.DSS_DEFAULT_PF, which detects the exact 0.88 value per load; this finding detects the statistical signature across all loads. |
I.DIV.LOAD_IMBALANCE | I | A multi-phase load with >20 % spread between its phase setpoints — noteworthy unbalance (often intended; this is context, not criticism). |
I.DIV.LOAD_PHASE_BALANCED | I | Aggregate active load is balanced within 2% across the observed phase labels in a galvanic zone. Spatial loading, impedances, connections and grounding remain unassessed; this does not establish single-phase-equivalent applicability. |
I.DIV.LOAD_UNIFORM_MODEL | I | Across ≥3 loads, every load uses the same load model. When that model is constant_power (the default), no load exercises voltage dependence (ZIP/exponential) — the case does not test voltage-dependent load behavior. Observational coverage signal, not a defect. |
I.DIV.LOAD_UNIFORM_CONFIG | I | Across ≥3 loads, every load shares the same configuration (e.g. all WYE) — no connection diversity. Observational; uniform connection is common and often legitimate. |
I.DIV.LINE_SYMMETRIC | I | ≥80 % of the lines sharing a linecode have lengths within ±10 % of the median — electrically near-identical sections. |
I.DIV.BUS_UNIFORM_VMIN | I | Every bus that has v_min has the same value — no spatial differentiation of the lower voltage envelope. Phase-to-ground bounds only; vpn_*/vpp_* bounds are not compared. |
I.DIV.BUS_UNIFORM_VMAX | I | Same for v_max. |
OPS — operational loading
| Code | Sev | Trigger & rationale |
|---|---|---|
W.OPS.IMPORT_DEPENDENT | W | Local generation capacity below 5 % of total load — the case is a pure import feeder; with only a slack source the dispatch problem is loss minimization at best. |
W.OPS.XFMR_OVERLOADED | W | Estimated downstream apparent load exceeds 90 % of a transformer's rating at nominal setpoints and removing that transformer separates its from and to bus sets. A parallel path makes the load sum an upper bound and suppresses this warning; a neutral-only branch, such as a neutral bond beside the transformer, is not a parallel path. On an applicable radial component this is a nominal-demand/nameplate review screen; it does not establish that a winding cap exists or that a solved limit is violated. Inspect load/rating bases and subtype-specific limits (see methodology). |
W.OPS.LINE_UNCONSTRAINED | W | Lines without any thermal limit (i_max/s_max on the line or its linecode) — the OPF will have no flow constraints there. |
W.OPS.XFMR_UNCONSTRAINED | W | An n_winding winding has no finite supported i_max or s_max cap. Fields may be absent or explicitly unbounded (Inf); zero is a real restriction. Unlike two-winding subtypes, an n-winding s_rating is only a nameplate. Why it matters: no thermal cap is imposed on that winding, so a solution may rely on unavailable capacity. Check: review the declared states and add finite per-winding caps from the datasheet when appropriate. Alternative: unlimited loading may be intentional. Evidence retains field paths, absent/unbounded counts, and malformed/unsupported coverage; direct neutral-current caps remain unassessed. |
I.OPS.UNLOADED_PHASE | I | A phase terminal is present on buses in a galvanic zone (connected via lines and closed switches; transformers and neutral-only branches are boundaries) but no load connects to it anywhere in that zone. Reported per zone and per terminal. Common in partial-phase feeders; worth reviewing before interpreting unbalance results. |
I.OPS.FEEDER_LONG | I | The farthest bus is further by declared line length from the nearest supply boundary than the configured threshold. Likely meaning: a genuinely long rural/SWER feeder, meter values interpreted as kilometers upstream, or a duplicated km-to-m conversion. Why it matters: length errors scale per-length linecode impedances and can distort voltages and losses; inline absolute section matrices do not scale with length. Check: spot-check lengths against maps and inspect per-km/per-m impedance units separately. Alternative: an equivalent electrical length. impedance_basis_counts records the declared sources. boundary_reach_m is compared; legacy reach_m remains anchor extent. Missing/conflicting boundary or length evidence leaves the comparison unassessed; several boundaries need an explicit multi_boundary policy. This is not a voltage-drop calculation. |
I.OPS.FEEDER_SHORT | I | The farthest bus is closer by declared line length to the nearest supply boundary than the configured threshold. Likely meaning: a stub/service drop, the OpenDSS default length=1, or kilometer values copied into meter fields. Why it matters: too-short lengths shrink per-length linecode impedances and may hide voltage drops and losses; inline absolute matrices stay unchanged. Check: inspect lengths and their impedance source. Alternative: a genuinely compact site. impedance_basis_counts records the sources. Several boundaries need an explicit multi_boundary policy; invalid, missing or regularized lengths leave the comparison unassessed. |
PRE — infeasibility pre-flight
| Code | Sev | Trigger & rationale |
|---|---|---|
W.PRE.XFMR_COIL_HEADROOM | W | A supported radial, single-source, single-phase-bank nominal-demand estimate exceeds one coil’s nameplate VA share. Signed nominal P/Q are summed by explicit terminal mapping, without losses or voltage/coupling effects. Negative headroom is a screening warning, not an infeasibility certificate. |
I.PRE.XFMR_COIL_UNASSESSED | I | Nominal per-coil transformer headroom is outside the declared domain or lacks required finite data/mapping. Structured status, reason and component context explain why no allocation was estimated. |
E.PRE.VBOUND_CONFLICT | E | A bus voltage bound pair with lower > upper (checked elementwise for all four flavors: v, vpn, vpp, vpos). The feasible set is empty before the solver starts. |
E.PRE.PBOUND_CONFLICT | E | Generator p_min > p_max — infeasible by construction. |
E.PRE.QBOUND_CONFLICT | E | Generator q_min > q_max — same. |
I.PRE.NO_VOLT_BOUNDS | I | Buses with no voltage-magnitude bound of any kind (v_min/v_max, vpn_min/vpn_max, vpp_min/vpp_max or vpos_min/vpos_max) — voltages are unconstrained there (spec semantics for absent optional bounds). This is a coverage screen: a vpp_* bound leaves the common-mode (neutral-shift) component free, and a vpos_* bound alone does not bound each phase magnitude under unbalance, but both still count as declared coverage. Unbalance and neutral-shift limits (vneg_max, vzero_max, vuf_max, vn_max) do not bound the phase voltage magnitude and do not count. |
I.PRE.SINGLE_SOURCE | I | Exactly one voltage source. The spec requires this in the current version; operationally it is still a single point of failure worth knowing about. |
W.PRE.SOURCE_VOLTAGE_OOB | W | A voltage source setpoint (v_magnitude) falls outside the bus's declared v_min/v_max. The source pins that voltage as a hard equality in the OPF, so the bound is trivially violated before the solver starts — a guaranteed infeasibility. Common cause: v_magnitude set in kV while bounds are in V, or an augmented bound tighter than the actual supply voltage. |
W.PRE.SOURCE_BUS_GENERATOR | W | A generator without p_max/q_max sits at a voltage-source bus. The voltage source is itself the network's current slack, so two unbounded current injections share one fixed-voltage bus — the dispatch split is degenerate (non-unique). Remove the generator and express its role as flow bounds/cost on the voltage source instead. |
I.PRE.SOURCE_BUS_GENERATOR | I | A bounded generator sits at a voltage-source bus. Well-posed (the generator is bounded, the source takes the remainder), but if its bounds/cost are meant to limit or price grid import, set them on the voltage source (p_min/p_max/q_min/q_max/cost) instead. |
DOM — domain plausibility
| 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 bus_to strictly closer (in hops) to a voltage source than bus_from and no alternate path joins its endpoints when the transformer is removed (neutral-only branches are not alternate paths). On that graph bridge, bus_from should be the source-side terminal; inspect swapped bus_* and v_nom_* fields. Equal-distance, unreachable, and non-bridge cases are unassessed. 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 (using source-distance BFS). The transformer must be a graph bridge; alternate paths make the direction ambiguous. Distribution step transformers normally step down toward the load; inspect swapped v_nom_from/v_nom_to or a genuine boost transformer. 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 realizability 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 neighbor (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 modeled 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. |
Wire / geometry realizability and model-assumption validity
Physical-realizability and validity-domain checks for the wire_data / line_geometry libraries. E-class conditions also hard-error in compile_linecode; W-class assumption checks are additionally emitted as compile-time warnings. References: Carson (1926) BSTJ 5(4); Pollaczek (1926); Deri, Tevan, Semlyen & Castanheira (1981); Saad, Gaba & Giroux (1996); Kersting & Green (2011); Kersting, Distribution System Modeling and Analysis; Jensen et al. (2001); Urquhart & Thomson (2015); IEC 60228 / IEC 60287.
| 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 (center 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-meters 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-meter range [10⁻⁶, 10⁻²] Ω/m — likely per-meter data mislabeled as section totals (or vice versa). Inline line matrices are totals and are never scaled by length. |
LOAD — load model validation & analysis
Emitted by domain_rules_check (coefficient plausibility, DOM pass) and load_model_analysis (load_models pass).
Validation (domain rules)
| Code | Sev | Trigger & rationale |
|---|---|---|
E.LOAD.VNOM_MISSING | E | A voltage-dependent load (model ≠ constant_power) has no v_nom field. The reference voltage is required to evaluate any voltage-dependent power expression; the OPF cannot be constructed without it. |
E.LOAD.VNOM_ARITY | E | v_nom is an array whose length is neither 1 nor the number of sub-loads. Each entry must broadcast to exactly one sub-load. |
E.LOAD.VNOM_NONPOSITIVE | E | One or more v_nom entries are ≤ 0. Voltages are strictly positive; a non-positive value is unphysical and would produce division by zero in the OPF. |
E.LOAD.ZIP_ARITY | E | A ZIP coefficient array (alpha_z/i/p or beta_z/i/p) has length that is neither 1 nor the number of sub-loads. |
E.LOAD.EXP_ARITY | E | gamma_p or gamma_q has length that is neither 1 nor the number of sub-loads. |
W.LOAD.ZIP_SUM | W | For a ZIP load, the active ($\alpha^Z + \alpha^I + \alpha^P$) or reactive ($\beta^Z + \beta^I + \beta^P$) coefficients do not sum to 1. At nominal voltage the load will not consume its nominal power; usually a data entry error. |
W.LOAD.GAMMA_NEGATIVE | W | An exponential exponent $\gamma < 0$ — power increases as voltage falls. Physically possible for some device classes but extremely unusual in distribution-network demand models; almost always a sign error. |
W.LOAD.MODEL_MIXED | W | A zip load carries gamma_p/gamma_q fields, or an exponential load carries ZIP coefficient fields. The extra fields are ignored; this finding flags the likely copy-paste error. |
W.LOAD.VNOM_MISMATCH | W | A load's v_nom differs from the BFS-inferred bus nominal voltage by more than 25 %. For WYE loads v_nom is compared against the inferred phase-to-neutral voltage; for DELTA loads against phase-to-neutral × √3 (line-to-line). A large deviation means the power setpoint and voltage sensitivity are referenced to the wrong operating point — a common OpenDSS conversion error where the load kV field is left at a default or is set to the wrong voltage level. |
I.LOAD.GAMMA_RANGE | I | An exponential exponent $\gamma \notin (0, 2)$ — outside the range typical of distribution loads (motors ≈ 0.08, constant-impedance = 2). Still valid; flagged as context. |
I.LOAD.MODEL_FIELDS_IGNORED | I | A constant_power, constant_current, or constant_impedance load carries ZIP or exponential coefficient fields. These fields are redundant for named degenerate models and will be ignored by the OPF. |
Analysis (load model pass)
| Code | Sev | Trigger & rationale |
|---|---|---|
I.LOAD.EXP_ZIP_EQUIVALENT | I | One or more exponential loads have all exponents in $\{0, 1, 2\}$. These can be represented losslessly as zip (or the named constant_power/constant_current/constant_impedance models), keeping the OPF quadratic. The loads detail key lists the affected load IDs. |
W.LOAD.NL_NO_VMIN | W | One or more voltage-dependent loads sit on buses without any lower voltage magnitude bound (v_min, vpn_min, or vpp_min). The OPF squared-voltage variable $W$ will rely on the default floor bound ($0.5\,V^{\text{nom}}$) rather than an engineering limit. For loads with $\gamma < 2$ or $\alpha^I/\alpha^Z \neq 0$ the power expression grows unboundedly as voltage falls; an explicit lower bound is strongly recommended. |
RED — redundancy
| Code | Sev | Trigger & rationale |
|---|---|---|
W.RED.ZERO_LOADS | W | Loads with p_nom = q_nom = 0 — electrically inert objects that still create variables/constraints. |
W.RED.DUAL_THERMAL_LIMIT | W | An element (line/switch/generator/IBR) declares both a current limit (i_max) and an apparent-power limit (s_max). Both are enforced natively. The pair is not mathematically redundant — because ` |
W.REDUND.ZERO_LOAD | W | The structural-repair pass (fix_case) analogue of W.RED.ZERO_LOADS: a load with p_nom = q_nom = 0 on all phases is flagged as electrically inert during the fix workflow. |
I.RED.LOAD_SPARSE_PHASES | I | WYE loads where at least one phase has p≈0 and q≈0 while another is active. Each dead phase still generates a current variable and two bilinear constraints in the OPF; splitting into per-phase SINGLE_PHASE loads eliminates them. SINGLE_PHASE and DELTA loads are excluded (no clean per-phase equivalent). |
I.RED.LOAD_MERGEABLE | I | Groups of loads on the same bus sharing the same configuration and terminal_map (WYE/SINGLEPHASE keys are phase-order-insensitive; DELTA keys are normalized to the smallest cyclic rotation). Each group can be collapsed into one load with summed `pnom/qnom. Loads withtimeseries` references are excluded (merging profiles is non-trivial). |
I.RED.ZERO_SHUNTS | I | Shunts whose every G/B matrix entry is zero — same. |
I.RED.MERGEABLE_LINES | I | Chains of series lines whose interior buses have line-degree 2 and no other attachment (loads, generators, shunts, switches, transformers all counted as blockers). Merging removes superfluous buses that slow solvers (ref. 2). |
I.RED.PARALLEL_LINES | I | Parallel line records grouped by bus pair, with ordered terminal-map and normalized declaration classes, multiplicity, member/excess counts and bounded witnesses. Matching declarations are inspection candidates, not verified duplicate assets. No deletion or aggregation follows. n_identical_group_excess counts sum(m-1) only over wholly matching groups; whole-network cycle excess has a different scope. |
I.RED.UNUSED_LINECODES | I | Linecodes never referenced by a line — a cable library shipped with the case; harmless, but distinguishes library data from network data. |
I.RED.DUPLICATE_LINECODES | I | Groups of linecodes with identical R/X_series_1_1 fingerprints (codes lacking impedance data are excluded — absence is not evidence of duplication). |
PROV — provenance & conventions
The largest family; full derivations in the methodology notes.
| Code | Sev | Trigger & rationale |
|---|---|---|
W.PROV.POWERIO_UNCODED | W | A PowerIO conversion diagnostic arrived without a stable code. BMOPFTools retained it under this explicit fallback rather than silently dropping it or inventing a conversion-stage identity. |
Impedance matrix structure
| Code | Sev | Trigger & rationale |
|---|---|---|
E.PROV.NONRECIPROCAL | E | An impedance/admittance block (linecode R/X/G/B, inline line R/X/G/B, or bus-shunt G/B) is not symmetric — reciprocity is violated; passive RLC networks cannot do that. Catches, e.g., delta-bank admittances built from the incidence matrix instead of Y·(M∆)ᵀM∆. Reported with component_type = :line for inline absolute line matrices. |
E.PROV.NONPASSIVE | E | The R block has a negative eigenvalue — the line would generate power. PSD of R is invariant under Kron reduction (Schur complements of accretive matrices stay accretive), so this is always an error. Applies to linecodes and inline line matrices alike. |
W.PROV.X_NONINDUCTIVE | W | Non-positive series self-reactance — series compensation does not exist inside linecodes; almost always a sign flip or X/B confusion. |
W.PROV.X_NOT_PSD | W | The X block has a negative eigenvalue — the implied inductance matrix is not realizable (energy argument; also Kron-invariant via sectorial Schur closure). |
I.PROV.NEGATIVE_MUTUAL_R | I | Negative off-diagonal resistance. Carson's earth-return term makes mutual R positive for geometry-derived matrices; a negative entry signals processed/fitted provenance. |
E.PROV.NEGATIVE_G | E | A conductance block (line shunt or bus shunt) that is not PSD / has negative diagonals — an active element. |
W.PROV.B_SIGN | W | A susceptance block that is not PSD or has negative diagonals — not a physical capacitance matrix. |
I.PROV.B_OFFDIAG | I | Positive mutual susceptance with PSD intact — deviates from the Maxwell sign pattern. Clean electrostatic pipelines (including grounded-screen elimination and bundling) preserve the pattern, so this marks fitted/averaged provenance rather than an error. |
I.PROV.SHUNT_LIKELY_CAPACITOR | I | A shunt is purely capacitive — no conductance (G ≈ 0) and a strictly positive diagonal susceptance (B = ωC > 0; a reactor would be negative). It looks like a fixed capacitor bank carried as a generic admittance. Consider modeling it as a first-class capacitor (nameplate q_rated/v_nom); the fix recipe can convert phase-to-ground banks automatically with FixRecipe(apply_shunt_to_capacitor = true). See object identity. |
I.PROV.SHUNT_LIKELY_REACTOR | I | A shunt is purely inductive — no conductance (G ≈ 0) and a strictly negative diagonal susceptance (B = −1/ωL < 0). It looks like a shunt reactor, a distinct asset from a capacitor or a generic shunt; keep its identity explicit and verify the sign convention. |
W.PROV.LINE_BRIDGES_VOLTAGE_LEVELS | W | A line's two endpoint buses are assigned different nominal voltage levels (ratio beyond 5 %). A line cannot change voltage level — this is a transformer elided into the per-unit line model (the textbook "the transformer vanishes in per-unit"), or a data error. Model it as a transformer. Neutral-only lines, such as neutral bonds across a transformer, are excluded. |
W.PROV.GEOMETRY_MISMATCH | W | A linecode carrying a line_geometry back-reference no longer matches a re-derivation from that geometry (beyond 10⁻⁶ relative). The stored matrices are stale or hand-edited — recompile with compile_linecode(net, id; force=true) or drop the back-reference. The geometry analogue of the transformer Yprim cross-check. |
W.PROV.GEOMETRY_UNCOMPILABLE | W | A linecode references a line_geometry that fails to compile (broken wire data, invalid earth model, missing frequency, …) — the provenance link cannot be verified. |
Line model topology
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 modeling assumption auditable and flags the parameterizations that are suspicious in distribution networks.
| Topology | Meaning | Expected in distribution? |
|---|---|---|
| series | No shunt on either end — pure series Z. | Yes — the default for LV / short-cable feeders, where line charging is negligible. |
| symmetric π | Shunt on both ends with Y_from ≈ Y_to. | Yes — the canonical nominal-π; a uniform reciprocal line splits its charging equally. Expected once charging matters (longer MV/HV overhead, underground cable). |
| asymmetric π | Shunt on both ends but Y_from ≠ Y_to. | Suspicious — a uniform line is symmetric; unequal halves usually mean a reduction artifact or data error. |
| Γ (gamma) | Shunt on exactly one end. | Review — a valid deliberate lumping of charging at one terminal, but it breaks the physical from/to symmetry. |
| Code | Sev | Trigger & rationale |
|---|---|---|
I.PROV.LINE_MODEL_UNIFORM | I | Every line-model definition (linecode or inline line) uses a single topology — series-only, symmetric-π, etc. The network is internally consistent; the message states which model and whether it is the expected one. |
I.PROV.LINE_MODEL_MIXED | I | The case study mixes topologies (e.g. some branches series-only, others π). Legitimate when short spurs are modeled as series and long trunks as π, but flagged so the mix can be reviewed for consistency — especially any asymmetric-π or Γ members. Replaces the former I.PROV.NO_PI_SHUNT / I.PROV.PARTIAL_PI_SHUNT. |
W.PROV.ASYMMETRIC_PI | W | A line/linecode has shunts on both ends but the from-side and to-side admittances differ. A uniform reciprocal line splits its charging equally; unequal halves indicate a network-reduction artifact or a data error. |
I.PROV.GAMMA_SECTION | I | A line/linecode carries shunt admittance on exactly one end (a Γ-section). Valid as a deliberate lumping of charging at one terminal, but it breaks the from/to symmetry of a physical line — confirm it is intended. |
I.PROV.SHUNT_CONDUCTANCE | I | A line/linecode π-shunt carries non-zero conductance (G_from/G_to) — dielectric loss / leakage is modeled. Unusual in distribution, where the line shunt is normally purely capacitive; confirm it is not an X/B or units confusion. |
Parameterization provenance
| Code | Sev | Trigger & rationale |
|---|---|---|
I.PROV.SEQ_DERIVED | I | Equal self and equal mutual entries in the inspected three-conductor phase block; implied Z₁/Z₀ are reported for that block. Likely meaning: sequence values (r1,x1,r0,x0), transposition or physical symmetry. A larger matrix can be materialized from sequence input (including OpenDSS nphases=4), or combine a sequence-built phase block with separately supplied neutral parameters. Conductor count alone does not select an origin. Why it matters: omitted phase-pair asymmetry can matter to a study, while retained neutral coupling can still create unbalance. Check: source parameters, conductor count, coupling and grounding. Converter-generated source equivalents are not flagged. |
I.PROV.DECOUPLED_PHASES | I | Negligible mutual series coupling in the inspected phase block (relative coupling below 10⁻⁶), whether or not self entries are uniform. Likely meaning: independently supplied phase impedances. For nearly uniform self terms, Z₀ ≈ Z₁; unequal diagonal terms can still couple the sequence networks. Check: phase versus sequence coordinates, return paths and retained conductor coupling. Alternatives: negligible physical coupling or a prior reduction whose Schur correction cancels mutual entries. Diagonal structure alone does not exclude Kron history; the per-phase hint takes priority and the transformation candidate remains unknown. Converter-generated source equivalents are not flagged. |
I.PROV.LINE_SWITCH_LIKE | I | A line has near-zero series impedance and may be better represented by the spec's lossless switch object. |
Bound & limit completeness
| Code | Sev | Trigger & rationale |
|---|---|---|
E.PROV.INCONSISTENT_BOUNDS | E | A bus has a voltage-bound pair with min > max — the feasible set is empty (the provenance-pass counterpart of the pre-flight E.PRE.VBOUND_CONFLICT). |
I.PROV.OVERLAPPING_VOLTAGE_BOUNDS | I | A bus has several voltage-bound types active at once (e.g. both v and vpn) — overlapping envelopes; confirm they are meant to co-apply. |
W.PROV.REDUNDANT_VOLTAGE_BOUNDS | W | A bus declares both phase-to-ground (v_min/v_max) and phase-to-neutral (vpn_*) bounds that encode the same limit — redundant duplication. |
W.PROV.INAPPLICABLE_VOLTAGE_BOUNDS | W | A bus carries voltage bounds that cannot be enforced for its terminal structure and will be ignored by the OPF (e.g. a phase-to-neutral bound on a bus with no neutral). |
W.PROV.I_MAX_INCOMPLETE | W | One or more lines have fewer i_max entries than conductors — the thermal limit is only partially specified; the unspecified conductors are left unconstrained. |
W.PROV.I_MAX_INCOMPLETE_SWITCH | W | Same as above for switches. |
W.PROV.I_MAX_INCOMPLETE_XFMR | W | Same for transformers (i_max_from/i_max_to shorter than the winding conductor count). |
W.PROV.I_MAX_ABSENT | W | One or more lines have no i_max on their linecode (or no linecode) — the series current is left entirely unconstrained in the OPF, so no thermal limit is enforced on the branch at all (distinct from I_MAX_INCOMPLETE, which is a partial limit). |
W.PROV.I_MAX_ABSENT_SWITCH | W | Same for closed switches with no i_max. Open switches are excluded — their current is fixed to zero regardless. |
Zone phase topology
Emitted by the :connectivity pass after classifying each galvanic zone. Informational tags, not defects.
| Code | Sev | Trigger & rationale |
|---|---|---|
I.PROV.SPLIT_PHASE_ZONE | I | A galvanic zone is fed by a center_tap transformer — a split-phase section (NA 120-0-120, AU 230-0-230 downstream of SWER). The two legs are anti-phase about the center-tap neutral; the OPF warm-start initializes them 180° apart accordingly. |
I.PROV.SWER_ZONE | I | A galvanic zone is single-wire (one phase conductor across all its buses) and transformer-isolated — a Single-Wire-Earth-Return section. Distinguished from a single-phase lateral, which shares its three-phase feeder's zone. |
Voltage-source sequence & supply consistency
Classify each polyphase voltage source's stored v_angle and check it against the phase counts of the buses it galvanically supplies. Phase count and separation are fixed inside a galvanic zone — only a transformer (Scott-T, center-tap, delta-wye) changes them. Phase conductors and source phase angles are identified with the case's resolved terminal roles (terminal_conventions, or the naming convention when none is declared): neutral- and earth-role labels, such as a declared neutral "4", are not phases.
| Code | Sev | Trigger & rationale |
|---|---|---|
W.PROV.SOURCE_ZERO_SEQUENCE | W | A voltage source's per-phase angles are all equal (zero-sequence / co-phasal) — not a valid positive-sequence supply. A degenerate input that also predicts convergence failure (cf. PSCC-2026 Table VI); fix the angles and use positive-sequence initialization. |
W.PROV.SOURCE_NEGATIVE_SEQUENCE | W | A source's rotation is reversed relative to its a→b→c phase labels — a likely phase-labeling error. Match voltage initialization to the intended rotation. |
W.PROV.SOURCE_INCOHERENT_ROTATION | W | A source's per-phase separations are not a consistent ±120°, 90°, or 180° set — malformed angle data. (Valid positive-sequence 120°, split-phase 180°, and two-phase 90° supplies are not flagged.) |
W.PROV.PHASE_COUNT_EXCEEDS_SUPPLY | W | A bus declares more phase conductors than its galvanic feed (voltage source or feeding-transformer secondary) supplies — e.g. a 3-phase bus downstream of a single-phase or split-phase (180°) source within one zone. Phase count cannot increase without a transformer. |
W.PROV.PHASE_ARRANGEMENT_MISMATCH | W | A zone contains a 3-phase bus and enough conductors, but its source's angle arrangement is zero/quadrature/anti-phase/incoherent rather than a 120° rotation — it cannot establish a rotating 3-phase field; a true 3-phase supply or a phase-converting transformer (e.g. Scott-T) is required. |
Grounding & reduction conventions
| Code | Sev | Trigger & rationale |
|---|---|---|
I.PROV.KRON_LIKELY | I | An LV level has no neutral carried by represented branches. Likely meaning: prior neutral elimination, including Kron reduction, in a network that may physically be four-wire. Why it matters: the usual Kron model assumes zero neutral voltage at line endpoints and cannot predict actual neutral rise if that assumption is inappropriate. Dissipation can remain in the reduced impedance; separate neutral quantities need source blocks or a recovery map. Check: original conductor/grounding data and the quantities needed for the study. Alternative: a genuine three-wire network or another equivalent. |
I.PROV.KRON_REDUCIBLE | I | A 4-wire network whose every neutral is perfectly grounded — Kron reduction would be exact, so the explicit neutrals are numerically redundant. |
Impedance transformation type (3-wire LV only)
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 |
|---|---|---|
I.PROV.IMPEDANCE_TRANSFORM_KR | I | A finite three-wire matrix with phase coupling matches neither PN/MPN pattern: a weak matrix-only hint of Kron reduction. LV use without a represented neutral strengthens it; positively known MV/HV-only or unused cases receive context-specific guidance. Missing or mixed voltage/map evidence remains unassessed and retains conditional neutral-related implications. Diagonal cases use the per-phase simplification hint with origin unresolved; Schur corrections can cancel original mutuals. Why it matters: a zero-neutral-voltage approximation cannot show actual neutral rise, while dissipation remains represented under the exact boundary relation. Separate attribution needs source blocks or a recovery map. Check: original conductors and grounding. Alternatives: native three-wire construction or other equivalents. Converter source equivalents are not flagged. |
I.PROV.IMPEDANCE_TRANSFORM_PN | I | Uniform R with mutual/self near one half and varying X suggest a phase-to-neutral equivalent: neutral resistance may have been folded into phase impedances. Why it matters: the phase-to-neutral transformation is exact with no conductor-to-earth shunts, no device injection into earth and one grounding point per continuous neutral section. It also applies to unequal conductors; similar resistances explain the fingerprint, not accuracy. Multiple earth-return paths can break these assumptions, and grounding impedance alone does not determine error. Source data can support neutral recovery. Check: source four-wire impedances and earth-current assumptions. Alternative: another parameterization sharing the pattern. |
I.PROV.IMPEDANCE_TRANSFORM_MPN | I | Uniform R and X with R mutual/self near one half suggest a modified phase-to-neutral equivalent with reactance symmetrization. Why it matters: review the PN assumptions about earth shunts, device earth injection and single-point grounding; grounding impedance alone does not determine error. Reactance symmetrization adds an approximation that removes phase-pair reactance asymmetry. Check: source impedances, geometry and the asymmetry needed for the study. Alternative: a symmetric physical or authored equivalent sharing the pattern. |
W.PROV.IMPLICIT_GROUNDING | W | Neutral terminals are referenced by components but no branch carries a neutral conductor, and some referenced neutrals lack represented grounding. The intended return/grounding convention is indeterminate; no every-bus ground constraint or Kron history is inferred. |
E.PROV.FLOATING_NEUTRAL | E | A neutral section (continuity graph over lines/closed switches) with no path to ground and loads/generators using it — the zero-sequence path is undefined; 4-wire analysis is ill-posed. |
W.PROV.FLOATING_NEUTRAL | W | Same, but unused — latent rather than active. |
I.PROV.WYE_NEUTRAL_UNGROUNDED | I | A three-phase wye winding brings out its star-point neutral at a bus that has no local grounding (no perfect ground and no grounding impedance). The wye star point is the natural earthing point; its zero-sequence potential is then set only by what the neutral conductor reaches elsewhere. Single-phase transformers (phase-to-neutral / phase-to-phase) are exempt. |
OpenDSS default fingerprints
Values matching documented OpenDSS defaults indicate the source .dss files likely omitted the field (see methodology for the table).
| Code | Sev | Trigger & rationale |
|---|---|---|
W.PROV.DSS_DEFAULT_Z | W | Recovered Z₁/Z₀ match the default line constants (r1=0.058, x1=0.1206, r0=0.1784, x0=0.4047 Ω/kft) — a fictitious 60 Hz overhead line in your data. |
W.PROV.DSS_DEFAULT_SOURCE_Z | W | Source Thévenin Z₁ matches MVAsc3=2000 with X1R1=4 — the fault level was never specified; arguably the most consequential default of all. |
I.PROV.DSS_DEFAULT_AMPS | I | i_max exactly 400 A (the normamps default; 600 A is excluded as a common genuine rating). |
I.PROV.DSS_DEFAULT_XFMR | I | Transformer per-unit impedance equal to xhl = 7 % / %r = 0.2 per winding. |
I.PROV.DSS_DEFAULT_PF | I | Loads at power factor exactly 0.88 — reactive demand defaulted. |
I.PROV.DSS_DEFAULT_KV | I | Components sitting exactly at 115 kV or 12.47 kV — US defaults, glaring outside US test feeders. |
I.PROV.DSS_DEFAULT_LENGTH | I | A minority of lines with length exactly 1.0 among varied lengths. (Universal 1.0 is detected as a deliberate length-normalized convention and reported in the convention statement instead.) |
Control devices
| Code | Sev | Trigger & rationale |
|---|---|---|
W.PROV.REGULATOR_PATTERN | W | A transformer that looks like a voltage-regulator/autotransformer encoding: either both windings on one bus (the explicit EPRI autotransformer form) or a near-1:1 wye unit with same-level endpoints / very low impedance / non-unity tap. The data model has no regulator object — a control device has been frozen into a fixed branch. |
INT — structural integrity
Motivated by the benchmark-pitfall catalog of (ref. 2).
| Code | Sev | Trigger & rationale |
|---|---|---|
E.INT.UNKNOWN_BUS | E | A component references a bus id that does not exist. Branch and transformer evidence identifies the endpoint or original winding index. |
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 | An AC terminal-map entry or perfectly_grounded_terminals reference is not a terminal of its bus. Evidence identifies the field; branch/winding evidence also identifies endpoint, original winding index and invalid map positions. This includes typos and 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.CONSTANT_PF_INVALID | E | A declared constant power_factor.pf is missing, nonnumeric, Boolean, nonfinite, zero or outside −1…1. Native model construction rejects it instead of silently dropping the control or failing in trigonometry. |
E.INT.MINIMUM_PF_INVALID | E | A versioned package minimum-PF request has invalid values, unknown IBRs, ambiguous mappings, unsupported directions/scope or unsupported control combinations. Structured reason codes explain the rejected request; no constraint is silently omitted. |
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 | An indexed field has an incompatible shape for its device topology: powers/capabilities/costs, current limits, load setpoints, source reference prefixes, or bus phase/pair bounds. Device evidence identifies roles, map positions, indexing domain, allowed lengths and observed shape; see device parameter indexing. No universal conductor-count rule applies. The line-matrix case remains the stricter E.INT.LINE_DIM_MISMATCH. |
W.INT.DEVICE_INDEXING_UNASSESSED | W | Device/bus indexing is indeterminate because roles or references are unresolved, the map is malformed, earth-conductor behavior is unsupported, or a phase-to-neutral bound lacks its reference. Evidence carries status="indeterminate" and a reason; no expected count is guessed. Declaration and reference defects retain their existing Finding owners. |
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. |
CONV — terminal-role conventions
Checks on the case-wide terminal_conventions block that classifies terminal labels into phase/neutral/earth roles (see Terminal-role conventions).
| Code | Sev | Trigger & rationale |
|---|---|---|
W.CONV.TERMINAL_ROLES_INFERRED | W | The case declares no terminal_conventions block, so phase/neutral/earth roles were inferred from the naming convention (a terminal n/N is neutral, all others phase). Declare the block to make the classification explicit and self-documenting; it is written for you on the next write_bmopf. |
E.CONV.ROLE_OVERLAP | E | A terminal label appears in more than one of the phase/neutral/earth role lists. Each label must have a single role. |
W.CONV.TERMINAL_UNCLASSIFIED | W | An existing AC bus terminal is in none of the declared role lists. Legacy consumers treat it as a phase; the Finding includes bus declarations and resolved component/winding/grounding usage paths together. Unknown bus/terminal references retain their integrity owner and do not add a role warning. |
W.CONV.MULTIPLE_NEUTRALS | W | A single bus carries more than one terminal classified as neutral — a bus is expected to have at most one neutral conductor. |
E.CONV.DECLARATION_INVALID | E | An explicit terminal_conventions block is not an object, or a role list is not an array of strings. Role classification is indeterminate; invalid declarations are not replaced by inferred roles. Evidence identifies the declaration path and expected shape. |
E.CONV.BUS_ROLE_CONFLICT | E | With explicit case-wide roles, a bus's in-memory neutral_terminal metadata is malformed, names a nonexistent bus terminal, or disagrees with those roles. Evidence identifies the metadata path, matching role declarations, and expected neutral labels. Validation leaves the metadata unchanged; role overlap keeps its separate owner. |
I.CONV.UNUSED_LABEL | I | A role label is declared but unused anywhere in the inventoried AC bus terminals, component maps, grounding references, or neutral metadata. This is informational hygiene, distinct from an unwired spare bus conductor. The Finding is suppressed when supported usage cannot be completely inventoried. |
TMAP — terminal-map conventions
Checks on how component terminal_maps reference bus terminals.
| Code | Sev | Trigger & rationale |
|---|---|---|
E.TMAP.PHASE_TO_NEUTRAL | E | A nodal device has all-neutral/repeated-neutral misuse or a DELTA/THREELEG device includes neutral; a line/switch position connects phase to neutral, or a branch repeats an all-neutral endpoint. Position comparisons require equal-length, distinct, resolved phase/neutral maps; different phase labels are valid. Reversed single-phase pairs and role-resolved WYE/FOURLEG neutral permutations are accepted, as are symmetric metallic N-only lines and switches. |
E.TMAP.DEVICE_ROLES | E | A supported nodal device includes an explicit earth conductor outside its model, or a FOUR_LEG IBR lacks its identified neutral return. Structured map/role evidence describes the unsupported connection; this does not introduce an earth-conductor model. |
I.TMAP.CROSS_PHASE_LINE | I | A line or switch has different from/to terminal maps — the conductors are cross-connected between phases across the branch. Valid (e.g. an intentional phase swap) but flagged as context. |
I.TMAP.PERMUTED_ORDER | I | A component's terminal_map is a permutation of the bus's nodal terminal order — non-canonical ordering; verify the swap is deliberate rather than a data-entry slip. |
SPEC — TF-spec conformance
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 outside SINGLE_PHASE/WYE/DELTA for a load/generator/capacitor, or outside SINGLE_PHASE/WYE for native voltage-source references. |
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 modeling is distinct from the more common phase-to-neutral case. |
E.SPEC.WYE_MISSING_NEUTRAL | E | A WYE load/generator omits the identified neutral of its bus. The neutral may appear anywhere in the map; phase-indexed fields follow map order with neutral removed. |
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 modeled 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 map lengths differ from the subtype data-model arity, a winding list has fewer than two entries, or an n-winding WYE lacks explicit neutral / DELTA lacks two terminals. Native boundary arities may retain this warning. See connection-map rules. |
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; normalize before publishing. |
SOL — solution profiling
Produced by profile_solution when checking an OPF result dict against its network. See SolutionReport and render_solution.
| 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. Apparent-power checks use max(1e-6 × abs(s_max), 1e-6 VA) tolerance, recorded with the excess in structured evidence. |
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. Apparent-power checks use max(1e-6 × abs(s_max), 1e-6 VA) tolerance, recorded with the excess in structured evidence. |
W.SOL.IBR_ACTIVE | W | An IBR dispatch is within 1 % of a P bound — the bound is near-active. |
E.SOL.IBR_Q_VIOLATION | E | An IBR's supplied qg violates a declared q_min or q_max, including under constant-PF or supported Volt-var control. Bounds index the modeled phase or pair according to topology. Evidence records the output index, terminal, topology, value and bounds in var. Uses the existing power-bound tolerance (1 var absolute floor). |
W.SOL.IBR_Q_ACTIVE | W | An IBR's supplied qg is within 1 % of a declared reactive-power bound without violating it at the power-bound tolerance. Evidence records output identity, value and bounds in var. |
E.SOL.IBR_MINIMUM_PF | E | Supplied per-coil P/Q violates the declared generation minimum-PF envelope, including negative P or reactive-only operation at P=0. Uses dispatched P, a bounded-coefficient residual and an explicit VA tolerance; does not authenticate the solver or case provenance. |
I.SOL.IBR_MINIMUM_PF_UNASSESSED | I | Minimum-PF compliance cannot be assessed because no candidate is available, dispatch is absent/nonfinite, or the policy is invalid. Missing data are never treated as zero or a passing check. |
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 realized 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 realized 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 initialization 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 initialization 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 initialized with non-zero voltage. Neutral start values should be zero; non-zero values indicate an initialization inconsistency. |
DER — distributed-energy-resource augmentation
| Code | Sev | Trigger & rationale |
|---|---|---|
W.DER.NO_CANDIDATES | W | The selected DER placement strategy produced no placements because no candidate load buses passed its filters. |
I.DER.PLACED | I | DER augmentation placed one or more generators; the Finding records the strategy, count, total active-power capacity, and generation/load ratio. |
W.DER.OVERSUPPLY | W | Added DER active-power capacity exceeds 150% of total load, so the resulting OPF may be trivially over-supplied. |
IBR — inverter-based-resource augmentation
| Code | Sev | Trigger & rationale |
|---|---|---|
W.IBR.NO_CANDIDATES | W | The selected IBR placement strategy produced no placements because no candidate load buses passed its filters. |
I.IBR.PLACED | I | IBR augmentation placed one or more devices; the Finding records the strategy, count, total apparent-power rating, and rating/load ratio. |
W.IBR.OVERSUPPLY | W | Added IBR apparent-power rating exceeds 150% of total load, so the resulting OPF may be trivially over-supplied. |
BENCH — benchmark readiness
| Code | Sev | Trigger & rationale |
|---|---|---|
I.BENCH.AUGMENTATION | I | The case is not yet a non-trivial OPF benchmark; the message lists the concrete augmentation steps: no costed generation (degenerate objective), slack-only generation (trivial dispatch), absent voltage bounds, absent vpn/vpos bounds (which also aid solver robustness (ref. 3)), missing thermal limits. The absent-voltage-bounds step is suggested only when no bus has a voltage-magnitude bound of any kind (v_*, vpn_*, vpp_* or vpos_*). |
W.BENCH.GEN_NO_DOF | W | One or more generators have p_min ≈ p_max on every phase — fixed output, not dispatchable. These generators consume variables and constraints but cannot move in the optimal solution, and may mask the true binding constraints. |
W.BENCH.GEN_ZERO_COST | W | Dispatchable generators have zero direct cost. This is a screening signal: network losses, upstream cost and constraints can still determine dispatch. Do not add arbitrary costs solely to silence it. |
W.BENCH.GEN_DEGENERATE_COST | W | Dispatchable generators on the same bus or one hop apart share a representative cost coefficient. Check control interchangeability; equal costs alone do not establish primal non-uniqueness. |
I.BENCH.LOAD_ZERO_PNOM | I | One or more loads have p_nom = 0 on all phases — they impose no real power demand and are electrically inert. These loads may indicate missing data or placeholder entries that should be populated before benchmark use. |
DC — MVDC/LVDC network
Checks for the DC side: dc_bus nodes (signed line-to-ground voltage, no angle), dc_branch lines, dc_grounding earth-return points, and dc_load/dc_source. A converter station / back-to-back SOP / MVDC tie is several IBRs sharing a dc_bus (see semantic_modeling.md and the conventions for DC terminal/pole/return recognition).
| 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 energized 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. |
CONTRACT — executable scientific contracts
These findings do not come from analyze. They are produced only by the explicit source-versus-target scientific contracts, which need a source, a target, and an explicit mapping — a reduced target cannot reveal source information that has already been discarded. Ordinary single-case analysis never emits them.
| 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 the scientific reference, 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 labeled 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 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. |
Connection-map structure and supported winding roles
| Code | Severity | Meaning |
|---|---|---|
E.INT.CONNECTION_SHAPE | E | A branch/transformer component or winding is not an object, a winding list is not an array, a bus identifier is missing/non-string, or an endpoint map is not a nonempty string array. Raw traversal preserves the original winding index and never converts numeric winding fields. |
E.INT.SWITCH_DIM_MISMATCH | E | Switch endpoint maps have unequal lengths. Each position denotes one through conductor; no truncation or inferred mapping is allowed. Evidence includes both endpoints. |
E.TMAP.WINDING_ROLES | E | A transformer winding map violates the represented subtype's phase/neutral or positional rule, or coupled winding coil counts differ. This does not impose line continuity across independent windings. Evidence identifies the rule, side/winding and resolved roles; see coverage table. |
W.TMAP.CONNECTION_UNASSESSED | W | Branch/winding role comparison is indeterminate because role declarations are malformed, roles are ambiguous/unclassified, bus neutrals are multiple, or earth conductors are outside this supported domain. References and structural errors retain their integrity owners. No role count is guessed. |