Skip to main content

powerio_dist/bmopf/
mod.rs

1//! The BMOPF task force JSON schema
2//! (<https://github.com/distribution-system-opt/dsopt-schema>).
3//!
4//! Everything is explicit SI: volts, watts, vars, ohms, siemens, meters,
5//! radians, string bus ids and terminal names. The schema sets
6//! `additionalProperties: false` on electrical elements and permits free-form
7//! top-level `extras` and `meta.provenance` objects, so the strict emitter
8//! drops what the schema cannot carry and says so per field.
9//!
10//! # One BMOPF
11//!
12//! PowerIO reads and writes one BMOPF: the schema proposed in
13//! [dsopt-schema#2](https://github.com/distribution-system-opt/dsopt-schema/pull/2)
14//! and vendored from its commit [`BMOPF_PROPOSAL_COMMIT`]. It is the Task
15//! Force's schema plus the classes the task force's draft carried (IBR,
16//! control profiles, time series, the DC network, the n-winding and regulator
17//! transformers, typed geometry). Its `$id` is [`BMOPF_SCHEMA_ID`].
18//!
19//! A document names the release it was written against in
20//! `meta.schema_version`, its only version identifier; the writer states the
21//! one the schema's `$id` names, and any patch release of that line reads as
22//! current. A document from an older draft states no release and is
23//! identified by its `meta.$schema`, as those drafts defined it.
24//!
25//! The reader reads every document as the one BMOPF. A document from an
26//! older draft (including the `bmopf-report` drafts and the early draft
27//! PowerIO 0.11 wrote) is read through the legacy paths that accept the
28//! older layouts, and reported once with `READ.BMOPF.SCHEMA_LEGACY`. The
29//! older layouts are: the IBR, control profile, DC, time series, and overflow
30//! transformer tables under `extras`; the transformer `tap` spelling; the
31//! `cost` spelling of `energy_cost_rate`; the bus bounds `v_min`/`v_max` and
32//! `vn_max`; `meta.$schema`; the regulators' `tap_ratio`; `DSTATCOM`,
33//! `VA_FRACTION` and the lowercase enum values; and the `extras.geojson`
34//! geometry layer. A current document that uses those spellings gets the
35//! same single finding, and one stating both bus bound spellings with
36//! different values is `READ.BMOPF.SEMANTIC_INVALID`. A document stating no
37//! version is reported with `READ.BMOPF.SCHEMA_ABSENT`, and one naming no
38//! known release with `READ.BMOPF.SCHEMA_UNKNOWN`; both are read the same way.
39//!
40//! Output always states the current schema, even for an unchanged document
41//! read from an older draft: the retained source bytes are echoed only when
42//! the source itself states a current release and no `meta.$schema`. The
43//! writer never states a value the schema rejects; it drops it and reports
44//! it.
45//!
46//! The phase to ground bounds are `vpg_min`/`vpg_max`, and the neutral to
47//! ground cap is `vng_max`. Geometry goes in the
48//! typed `bus.*.geo` (a GeoJSON Point) and `line.*.geo` (a GeoJSON
49//! LineString) slots, with the coordinate system in `meta.crs` (absent means
50//! OGC:CRS84, longitude then latitude, which the writer leaves implicit); a coordinate
51//! space the schema cannot name is also recorded as `extras.powerio_geo`.
52//! Component locations (`MulticonductorNetwork::component_locations`) travel
53//! as the `geo` Point of the voltage source, load, generator, IBR, shunt,
54//! capacitor, switch or transformer they attach to, in a WGS84 document; a
55//! switch or transformer `geo` LineString reads as the midpoint of its end
56//! positions. `ibr` and `control_profile` are top-level tables, the two-winding
57//! transformer subtypes spell the ratio `tap_ratio`, `tap_ratio_min` and
58//! `tap_ratio_max`, the regulators `voltage_ratio`, `voltage_ratio_min` and
59//! `voltage_ratio_max`, and costs are `energy_cost_rate`. Line and linecode
60//! `s_max` have one entry per conductor.
61//!
62//! The schema's `$id` ([`BMOPF_SCHEMA_ID`]), where the exact schema bytes
63//! were retrieved from ([`bmopf_proposal_url`]), and their digest
64//! ([`BMOPF_PROPOSAL_SHA256`]) are recorded under
65//! `meta.provenance.powerio_bmopf`.
66//!
67//! # What stays under `extras`
68//!
69//! The top-level `capacitor` table is strict, so a capacitor too malformed to
70//! type keeps its raw properties under `extras.capacitor`, and a time series
71//! profile BMOPF's multiplicative semantics cannot represent stays verbatim
72//! under `extras.time_series`; each is reported. A source document's own
73//! `extras` object is stashed on read and re-emitted verbatim, so consumer
74//! keys beside these survive a write and read back.
75//!
76//! # Regulator subtypes
77//!
78//! The first BMOPF draft defined no regulator subtype; the task force's
79//! BMOPFTools toolchain extended it with `single_phase_autotransformer` and
80//! `open_delta_regulator`, and the schema declares both. This emitter
81//! writes them in the top-level `transformer` table.
82//! An OpenDSS transformer a RegControl targets emits as
83//! `transformer.single_phase_autotransformer` when it reads as a series
84//! regulator (one phase, two windings of equal connection, voltage, and
85//! rating on distinct buses), and two identical line to line legs spelling
86//! one open delta connection (ABBC/BCAC/CABA) merge into one
87//! `transformer.open_delta_regulator` object named after the first leg. A
88//! BMOPF document that already carries either subtype re-emits it verbatim.
89//!
90//! # `terminal_conventions` goes stale on a rename
91//!
92//! The emitted `terminal_conventions` block is the source document's own
93//! block re-emitted verbatim, or, absent that, one authored from the terminal
94//! names in the model: `n` and `N` are neutral, and `4` in the complete
95//! `1,2,3,4` convention is neutral; other names are phase labels. Either way the block describes the terminal naming
96//! of the document that carries it and nothing else. A consumer that renames
97//! terminals must delete the block and recompute it from the renamed
98//! terminals; carried across a rename it sorts names no bus has any more, and
99//! nothing else in the document contradicts it.
100
101mod capacitor;
102mod geo;
103mod profile;
104pub(crate) mod read;
105mod write;
106
107pub use profile::{
108    BMOPF_PROPOSAL_COMMIT, BMOPF_PROPOSAL_SHA256, BMOPF_SCHEMA_ID, bmopf_proposal_url,
109};
110pub use write::BmopfEmitOptions;
111pub(crate) use write::emit_bmopf_json_text_with_options;
112
113/// Whether a BMOPF document identifies itself as the schema PowerIO writes:
114/// a current `meta.schema_version` and no earlier `meta.$schema`. A
115/// same-format emission echoes retained source bytes only then; a document
116/// from an older draft, or stating none, is written fresh. Shared with the
117/// facade, which echoes calculation values itself.
118#[doc(hidden)]
119#[must_use]
120pub fn __states_written_version(text: &str) -> bool {
121    #[derive(serde::Deserialize)]
122    struct Document {
123        meta: Option<Meta>,
124    }
125    #[derive(serde::Deserialize)]
126    struct Meta {
127        schema_version: Option<String>,
128        #[serde(rename = "$schema")]
129        schema: Option<serde::de::IgnoredAny>,
130    }
131    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
132    serde_json::from_str::<Document>(text)
133        .ok()
134        .and_then(|document| document.meta)
135        .is_some_and(|meta| {
136            meta.schema.is_none()
137                && meta
138                    .schema_version
139                    .as_deref()
140                    .is_some_and(profile::states_current_release)
141        })
142}
143
144mod validate;