Remote and shared voltage control

.github/workflows/validate-schemas.yml

@@ -71,12 +71,16 @@ jobs:
       - name: Check infrastore field parity
         run: python scripts/check_infrastore_parity.py
 
+      # The remote voltage control fields land in PowerSystems on mb/remote-control, which
+      # pins the model packages generated from these schemas, so the parity gate reads
+      # that branch while both are open.
+      # TODO after mb/remote-control merges to PowerSystems psy6: set `ref` back to psy6.
       # TODO after psy6 merges to PowerSystems main: drop `ref`
-      - name: Checkout PowerSystems (psy6) for parity gate
+      - name: Checkout PowerSystems (mb/remote-control) for parity gate
         uses: actions/checkout@v4
         with:
           repository: Sienna-Platform/PowerSystems.jl
-          ref: psy6
+          ref: mb/remote-control
           path: PowerSystems.jl
           fetch-depth: 1
 

Core/SystemDocument.json

@@ -77,6 +77,14 @@
         "$ref": "../Operations/Associations/TradingHubAssociation.json"
       }
     },
+    "voltage_control_associations": {
+      "description": "Links a voltage control group (VoltageDroopControl or ReactivePowerSharing) to one member device with its relative reactive power weight and, for a two-terminal member, the converter terminal. One row per (control, member). Optional, defaulting to empty, like `trading_hub_associations`: documents written before it exist and omit it.",
+      "default": [],
+      "type": "array",
+      "items": {
+        "$ref": "../Operations/Associations/VoltageControlAssociation.json"
+      }
+    },
     "time_series_associations": {
       "description": "Time series metadata rows, one per (series, owner) association. Each row names the store holding its values in its own `address`; `time_series_storage_file` remains the document-level sidecar name.",
       "type": "array",

Core/units.json

@@ -16,6 +16,7 @@
     {"name": "Impedance", "dimension": {"M": 1, "L": 2, "T": -3, "I": -2}, "default_unit": "ohm", "ucum": "Ohm", "description": "Impedance"},
     {"name": "Conductance", "dimension": {"M": -1, "L": -2, "T": 3, "I": 2}, "default_unit": "S", "ucum": "S", "description": "Conductance"},
     {"name": "Susceptance", "dimension": {"M": -1, "L": -2, "T": 3, "I": 2}, "default_unit": "S", "ucum": "S", "description": "Susceptance"},
+    {"name": "Admittance", "dimension": {"M": -1, "L": -2, "T": 3, "I": 2}, "default_unit": "S", "ucum": "S", "description": "Admittance (complex conductance + j susceptance)"},
     {"name": "Angle", "dimension": {}, "default_unit": "rad", "ucum": "rad", "description": "Angle (allowed units rad and deg)"},
     {"name": "Frequency", "dimension": {"T": -1}, "default_unit": "Hz", "ucum": "Hz", "description": "Frequency"},
     {"name": "PowerPerFrequency", "dimension": {"M": 1, "L": 2, "T": -2}, "default_unit": "MW/Hz", "ucum": "MW/Hz", "description": "Active power response per unit of frequency deviation (regulation / droop participation)"},
@@ -68,6 +69,7 @@
     {"quantity_kind": "Impedance", "unit": "ohm", "to_default": 1.0},
     {"quantity_kind": "Conductance", "unit": "S", "to_default": 1.0},
     {"quantity_kind": "Susceptance", "unit": "S", "to_default": 1.0},
+    {"quantity_kind": "Admittance", "unit": "S", "to_default": 1.0},
     {"quantity_kind": "Angle", "unit": "rad", "to_default": 1.0},
     {"quantity_kind": "Angle", "unit": "deg", "to_default": 0.017453292519943295},
     {"quantity_kind": "FractionPerTime", "unit": "1/min", "to_default": 1.0},
@@ -106,7 +108,9 @@
     {"quantity_kind": "Mass", "unit": "ston", "to_default": 0.90718474},
     {"quantity_kind": "Resistance", "unit": "pu", "to_default": null},
     {"quantity_kind": "Reactance", "unit": "pu", "to_default": null},
+    {"quantity_kind": "Impedance", "unit": "pu", "to_default": null},
     {"quantity_kind": "Susceptance", "unit": "pu", "to_default": null},
+    {"quantity_kind": "Admittance", "unit": "pu", "to_default": null},
     {"quantity_kind": "Conductance", "unit": "pu", "to_default": null},
     {"quantity_kind": "ActivePower", "unit": "pu", "to_default": null},
     {"quantity_kind": "ReactivePower", "unit": "pu", "to_default": null},

Dynamics/DynamicGeneratorComponent/PSS/PSS2C.json

@@ -152,7 +152,7 @@
     },
     "hysteresis_binary_logic": {
       "description": "Hysteresis memory variable",
-      "default": "1.0",
+      "default": 1,
       "type": "integer"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/DEGOV.json

@@ -40,7 +40,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/DEGOV1.json

@@ -61,7 +61,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/GasTG.json

@@ -45,7 +45,7 @@
     },
     "P_ref": {
       "description": "Reference load set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/GeneralGovModel.json

@@ -136,7 +136,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/HydroTurbineGov.json

@@ -52,7 +52,7 @@
     },
     "P_ref": {
       "description": "Reference load set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/IEEETurbineGov1.json

@@ -84,7 +84,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/PIDGOV.json

@@ -78,7 +78,7 @@
     },
     "P_ref": {
       "description": "Reference load set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/TGFixed.json

@@ -12,7 +12,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/TGSimple.json

@@ -16,7 +16,7 @@
     },
     "P_ref": {
       "description": "Reference power set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Dynamics/DynamicGeneratorComponent/TurbineGov/WPIDHY.json

@@ -74,7 +74,7 @@
     },
     "P_ref": {
       "description": "Reference load set-point",
-      "default": "1.0",
+      "default": 1.0,
       "type": "number"
     }
   },

Operations/Associations/VoltageControlAssociation.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "VoltageControlAssociation",
+  "description": "Links a voltage control group (a VoltageDroopControl or a ReactivePowerSharing attribute) to one member device and records the member's relative reactive power weight. One row per (control, member). `entity_id` names a device that regulates voltage to a setpoint; `terminal` picks the converter for a two-terminal member (a TwoTerminalVSCLine) and is null for every other member. A device, or a two-terminal line's converter, belongs to at most one group of either kind. PSS/E RMPCT imports as weight = RMPCT / 100, so the PSS/E default of 100 is the default weight of 1.0.",
+  "type": "object",
+  "properties": {
+    "control_id": {
+      "description": "ID of the VoltageDroopControl or ReactivePowerSharing attribute the member belongs to.",
+      "type": "integer"
+    },
+    "entity_id": {
+      "description": "ID of the member device.",
+      "type": "integer"
+    },
+    "weight": {
+      "description": "Positive relative weight of this member. Its share of the reactive power required at the regulated bus is weight divided by the sum of the weights of the members in service. Units: 1.",
+      "default": 1.0,
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "x-unit": "1",
+      "x-quantity": "Dimensionless"
+    },
+    "terminal": {
+      "description": "Converter of a two-terminal member this row refers to; required for a TwoTerminalVSCLine member and UNDEFINED for every other member.",
+      "default": "UNDEFINED",
+      "$ref": "../../Operations/common.json#/$defs/VoltageControlTerminal"
+    }
+  },
+  "required": [
+    "control_id",
+    "entity_id"
+  ]
+}

Operations/Branch/ThreeWindingTransformer.json

@@ -124,7 +124,7 @@
         "COMPONENT_MVAR": "MVAr",
         "COMPONENT_BASE": "pu"
       },
-      "x-quantity": "Susceptance"
+      "x-quantity": "Admittance"
     },
     "shunt_location": {
       "description": "Placement of `magnetizing_shunt` in the equivalent star model.",

Operations/Branch/TransformerCircuit.json

@@ -59,10 +59,40 @@
       "default": "UNDEFINED",
       "$ref": "../../Operations/common.json#/$defs/TransformerControlObjective"
     },
-    "regulated_bus_number": {
-      "description": "Controlled bus number (PSS/E CONT; sign = regulation side).",
-      "default": 0,
-      "type": "integer"
+    "regulated_bus_id": {
+      "description": "ID of the bus whose voltage this circuit's tap changer regulates (PSS/E CONT). Set exactly when `control_objective` is `VOLTAGE` or `VOLTAGE_DISABLED`, null otherwise.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "regulated_bus_side": {
+      "description": "Side of the controlling winding on which the regulated bus lies, replacing the sign of PSS/E CONT. Set only when the regulated bus is not one of the transformer's own terminal buses; when it is, the side follows from the connections and this must be UNDEFINED.",
+      "default": "UNDEFINED",
+      "$ref": "../../Operations/common.json#/$defs/TransformerRegulatedBusSide"
+    },
+    "load_drop_compensation_r": {
+      "description": "Resistive part of the load drop compensation impedance for voltage control (PSS/E CR): the regulated voltage is compensated by `load_drop_compensation_r + j load_drop_compensation_x` times the circuit current. Zero means no compensation. Units: per parameter_units — NATURAL_UNITS: ohm, COMPONENT_BASE: pu .",
+      "default": 0.0,
+      "type": "number",
+      "x-unit-discriminator": "parameter_units",
+      "x-units": {
+        "NATURAL_UNITS": "ohm",
+        "COMPONENT_BASE": "pu"
+      },
+      "x-quantity": "Resistance"
+    },
+    "load_drop_compensation_x": {
+      "description": "Reactive part of the load drop compensation impedance for voltage control (PSS/E CX). Zero means no compensation. Units: per parameter_units — NATURAL_UNITS: ohm, COMPONENT_BASE: pu .",
+      "default": 0.0,
+      "type": "number",
+      "x-unit-discriminator": "parameter_units",
+      "x-units": {
+        "NATURAL_UNITS": "ohm",
+        "COMPONENT_BASE": "pu"
+      },
+      "x-quantity": "Reactance"
     },
     "control_limits": {
       "description": "Control band (PSS/E RMA/RMI), per `control_objective`. Units: per control_objective — UNDEFINED: 1, VOLTAGE_DISABLED: 1, REACTIVE_POWER_FLOW_DISABLED: 1, ACTIVE_POWER_FLOW_DISABLED: rad, CONTROL_OF_DC_LINE_DISABLED: 1, ASYMMETRIC_ACTIVE_POWER_FLOW_DISABLED: rad, FIXED: 1, VOLTAGE: 1, REACTIVE_POWER_FLOW: 1, ACTIVE_POWER_FLOW: rad, CONTROL_OF_DC_LINE: 1, ASYMMETRIC_ACTIVE_POWER_FLOW: rad .",

Operations/Branch/TwoTerminalLCCLine.json

@@ -269,6 +269,38 @@
       },
       "x-quantity": "Reactance"
     },
+    "rectifier_commutating_bus_id": {
+      "description": "ID of the bus whose voltage angle the rectifier firing angle is measured against (PSS/E ICR). Null means the rectifier's own bus. Must be null for a capacitor-commutated line.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "inverter_commutating_bus_id": {
+      "description": "ID of the bus whose voltage angle the inverter extinction angle is measured against (PSS/E ICI). Null means the inverter's own bus. Must be null for a capacitor-commutated line.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "rectifier_tap_transformer_id": {
+      "description": "ID of the TwoWindingTransformer whose tap this line adjusts on the rectifier side (PSS/E IFR, ITR, IDR). Null means the line's own rectifier tap fields describe the tap. The referenced circuit's `control_objective` must be `CONTROL_OF_DC_LINE`. Must be null for a capacitor-commutated line.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "inverter_tap_transformer_id": {
+      "description": "ID of the TwoWindingTransformer whose tap this line adjusts on the inverter side (PSS/E IFI, ITI, IDI). Null means the line's own inverter tap fields describe the tap. The referenced circuit's `control_objective` must be `CONTROL_OF_DC_LINE`. Must be null for a capacitor-commutated line.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
     "active_power_limits_from": {
       "description": "Minimum and maximum active power flows to the FROM node. Units: per power_units — NATURAL_UNITS: MW, COMPONENT_BASE: pu .",
       "default": {

Operations/Branch/TwoTerminalVSCLine.json

@@ -393,36 +393,22 @@
       "type": "number",
       "x-unit": "kV"
     },
-    "remote_bus_control_from": {
-      "description": "Number of the AC bus whose voltage the `from` converter regulates when `ac_control_from` is `AC_VOLTAGE`; null regulates its own terminal bus.",
+    "remote_regulated_bus_id_from": {
+      "description": "ID of the AC bus whose voltage the `from` converter regulates when `ac_control_from` is `AC_VOLTAGE` and that bus is not its own terminal bus. Null means the `from` terminal bus; a value equal to that bus is invalid.",
       "default": null,
       "type": [
         "integer",
         "null"
       ]
     },
-    "remote_bus_control_to": {
-      "description": "Number of the AC bus whose voltage the `to` converter regulates when `ac_control_to` is `AC_VOLTAGE`; null regulates its own terminal bus.",
+    "remote_regulated_bus_id_to": {
+      "description": "ID of the AC bus whose voltage the `to` converter regulates when `ac_control_to` is `AC_VOLTAGE` and that bus is not its own terminal bus. Null means the `to` terminal bus; a value equal to that bus is invalid.",
       "default": null,
       "type": [
         "integer",
         "null"
       ]
     },
-    "rmpct_from": {
-      "description": "Percent of the total Mvar required to hold the voltage at the bus regulated by the `from` converter that is contributed by this converter. Units: 1.",
-      "default": 100.0,
-      "type": "number",
-      "x-unit": "1",
-      "x-quantity": "Fraction"
-    },
-    "rmpct_to": {
-      "description": "Percent of the total Mvar required to hold the voltage at the bus regulated by the `to` converter that is contributed by this converter. Units: 1.",
-      "default": 100.0,
-      "type": "number",
-      "x-unit": "1",
-      "x-quantity": "Fraction"
-    },
     "base_power": {
       "description": "System base power for per-unitization of this component's per-unit fields, recorded per component in lieu of a system-level table. Units: MVA.",
       "type": "number",

Operations/Branch/TwoWindingTransformer.json

@@ -32,7 +32,7 @@
         "COMPONENT_MVAR": "MVAr",
         "COMPONENT_BASE": "pu"
       },
-      "x-quantity": "Susceptance"
+      "x-quantity": "Admittance"
     },
     "shunt_location": {
       "description": "Placement of `magnetizing_shunt` on the two sides of the circuit arc.",

Operations/StaticInjection/EnergyReservoirStorage.json

@@ -18,6 +18,30 @@
       "description": "ID of the bus that this component is connected to.",
       "type": "integer"
     },
+    "remote_regulated_bus_id": {
+      "description": "ID of the bus whose voltage this unit regulates when that bus is not its own (PSS/E IREG). Null means the unit regulates the bus it is connected to; a value equal to that bus is invalid, so local regulation has exactly one representation. An available voltage droop controller the unit belongs to overrides this target.",
+      "default": null,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "voltage_setpoint_units": {
+      "description": "Unit basis for voltage_setpoint. COMPONENT_BASE (per-unit on the base voltage of the bus the unit regulates) is PSS/E RAW native (VS).",
+      "default": "COMPONENT_BASE",
+      "$ref": "../../Operations/common.json#/$defs/VoltageUnitBasis"
+    },
+    "voltage_setpoint": {
+      "description": "Voltage magnitude the unit holds at the bus it regulates while its bus type marks it as voltage regulating (PSS/E VS). Ignored while the unit belongs to an available voltage droop controller. Units: per voltage_setpoint_units — NATURAL_UNITS: kV, COMPONENT_BASE: pu .",
+      "default": 1.0,
+      "type": "number",
+      "x-unit-discriminator": "voltage_setpoint_units",
+      "x-units": {
+        "NATURAL_UNITS": "kV",
+        "COMPONENT_BASE": "pu"
+      },
+      "x-quantity": "Voltage"
+    },
     "prime_mover_type": {
       "description": "Prime mover technology according to EIA 923.",
       "$ref": "../../Core/common.json#/$defs/PrimeMovers"