Class: BusRecord

Bus data record for DistOPF three-phase distribution OPF.

URI: distopf:BusRecord

 classDiagram
    class BusRecord
    click BusRecord href "../BusRecord/"
      BusRecord : bus_type

      BusRecord : cvr_p

      BusRecord : cvr_q

      BusRecord : has_cap

      BusRecord : has_gen

      BusRecord : has_load

      BusRecord : id

      BusRecord : latitude

      BusRecord : load_shape

      BusRecord : longitude

      BusRecord : name

      BusRecord : phases

      BusRecord : pl_a

      BusRecord : pl_b

      BusRecord : pl_c

      BusRecord : ql_a

      BusRecord : ql_b

      BusRecord : ql_c

      BusRecord : s_base

      BusRecord : v_a

      BusRecord : v_b

      BusRecord : v_c

      BusRecord : v_ln_base

      BusRecord : v_max

      BusRecord : v_min

Slots

Name	Cardinality and Range	Description	Inheritance
id	1 Integer	Bus integer index (one-based row number)	direct
name	0..1 String	Bus name label (matches the original feeder bus number)	direct
pl_a	0..1 Float	Phase A active load in per-unit (base s_base)	direct
ql_a	0..1 Float	Phase A reactive load in per-unit (base s_base)	direct
pl_b	0..1 Float	Phase B active load in per-unit (base s_base)	direct
ql_b	0..1 Float	Phase B reactive load in per-unit (base s_base)	direct
pl_c	0..1 Float	Phase C active load in per-unit (base s_base)	direct
ql_c	0..1 Float	Phase C reactive load in per-unit (base s_base)	direct
bus_type	0..1 String	Bus type (SWING = slack bus, PQ = load bus)	direct
v_a	0..1 Float	Phase A initial voltage magnitude in per-unit (base v_ln_base)	direct
v_b	0..1 Float	Phase B initial voltage magnitude in per-unit (base v_ln_base)	direct
v_c	0..1 Float	Phase C initial voltage magnitude in per-unit (base v_ln_base)	direct
v_ln_base	0..1 Float	Line-to-neutral base voltage, in volts	direct
s_base	0..1 Float	Apparent power base, in volt-amperes	direct
v_min	0..1 Float	Minimum voltage magnitude limit, in per-unit	direct
v_max	0..1 Float	Maximum voltage magnitude limit, in per-unit	direct
cvr_p	0..1 Float	Conservation Voltage Reduction (CVR) active power coefficient	direct
cvr_q	0..1 Float	Conservation Voltage Reduction (CVR) reactive power coefficient	direct
phases	0..1 String	Active phases at this bus (abc, a, b, c, ab, ac, bc)	direct
has_gen	0..1 Boolean	True if a generator is connected at this bus	direct
has_load	0..1 Boolean	True if a load is connected at this bus	direct
has_cap	0..1 Boolean	True if a capacitor is connected at this bus	direct
latitude	0..1 Float	Geographic latitude, in degrees	direct
longitude	0..1 Float	Geographic longitude, in degrees	direct
load_shape	0..1 String	Name of the load-shape profile applied to this bus	direct

Usages

used by	used in	type	used
DistopfModel	bus_records	range	BusRecord

Comments

• DistOPF BusRecord maps primarily to a CIM ConnectivityNode, with an associated BaseVoltage/VoltageLevel/Substation created (or reused) for the bus's base voltage, and an optional EnergyConsumer when the bus carries load. Import creates all of these from a single record. Export starts from the ConnectivityNode and traverses its Terminals to recover load, generation, and capacitor presence.

Identifier and Mapping Information

Schema Source

• from schema: https://gridappsd.org/cimhub/distopf

Mappings

Mapping Type	Mapped Value
self	distopf:BusRecord
native	distopf:BusRecord
exact	cim:ConnectivityNode

LinkML Source

Direct

name: BusRecord
description: Bus data record for DistOPF three-phase distribution OPF.
comments:
- DistOPF BusRecord maps primarily to a CIM ConnectivityNode, with an associated BaseVoltage/VoltageLevel/Substation
  created (or reused) for the bus's base voltage, and an optional EnergyConsumer when
  the bus carries load. Import creates all of these from a single record. Export starts
  from the ConnectivityNode and traverses its Terminals to recover load, generation,
  and capacitor presence.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:ConnectivityNode
attributes:
  id:
    name: id
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Bus integer index (one-based row number).
    comments:
    - 'DistOPF-only: a row index used to key this record and resolved by branch/generator/capacitor/battery
      records via fb/tb. Not stored on the CIM ConnectivityNode, which is identified
      by its own mRID. Export assigns fresh 1-based indices to ConnectivityNodes in
      traversal order, so round-tripped indices are not guaranteed to match the original
      import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    identifier: true
    domain_of:
    - BusRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: integer
    required: true
  name:
    name: name
    annotations:
      order:
        tag: order
        value: 2
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Bus name label (matches the original feeder bus number).
    comments:
    - 'Direct name mapping in both directions: name ↔ ConnectivityNode.name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    exact_mappings:
    - cim:IdentifiedObject.name
    rank: 1000
    ifabsent: string("")
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    range: string
    required: false
  pl_a:
    name: pl_a
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase A active load in per-unit (base s_base).
    comments:
    - 'Import: pl_a, pl_b, and pl_c are summed and converted to a single EnergyConsumer.p
      = (pl_a + pl_b + pl_c) × s_base (per-unit to watts); there is no per-phase EnergyConsumerPhase
      created, so the load is not split back out per phase on the CIM side. Export:
      pl_a = EnergyConsumerPhase(phase=A).p / s_base when per-phase children exist
      on the connected EnergyConsumer; otherwise the total EnergyConsumer.p / s_base
      is written to pl_a alone (pl_b and pl_c are left at zero).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:EnergyConsumerPhase.p
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_a:
    name: ql_a
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase A reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_a (reactive power): see the pl_a comment for
      the full EnergyConsumer.q derivation.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:EnergyConsumerPhase.q
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  pl_b:
    name: pl_b
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase B active load in per-unit (base s_base).
    comments:
    - 'Import: included in the pl_a+pl_b+pl_c sum written to EnergyConsumer.p (see
      the pl_a comment). Export: pl_b = EnergyConsumerPhase(phase=B).p / s_base when
      per-phase children exist; otherwise left at zero (the fallback total goes to
      pl_a only).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_b:
    name: ql_b
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase B reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_b (reactive power): see the pl_b and pl_a
      comments.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  pl_c:
    name: pl_c
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase C active load in per-unit (base s_base).
    comments:
    - 'Import: included in the pl_a+pl_b+pl_c sum written to EnergyConsumer.p (see
      the pl_a comment). Export: pl_c = EnergyConsumerPhase(phase=C).p / s_base when
      per-phase children exist; otherwise left at zero (the fallback total goes to
      pl_a only).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_c:
    name: ql_c
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase C reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_c (reactive power): see the pl_c and pl_a
      comments.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  bus_type:
    name: bus_type
    annotations:
      order:
        tag: order
        value: 9
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Bus type (SWING = slack bus, PQ = load bus).
    comments:
    - 'Not used on import (the bus/slack designation is not derived from this field).
      Export: bus_type = "SWING" when the ConnectivityNode has a Terminal connected
      to an EnergySource, otherwise "PQ" — i.e. the swing bus is detected structurally,
      not read from a dedicated CIM attribute.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergySource.Terminals
    rank: 1000
    ifabsent: string("PQ")
    domain_of:
    - BusRecord
    range: string
    required: false
  v_a:
    name: v_a
    annotations:
      order:
        tag: order
        value: 10
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase A initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_b:
    name: v_b
    annotations:
      order:
        tag: order
        value: 11
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase B initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_c:
    name: v_c
    annotations:
      order:
        tag: order
        value: 12
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase C initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_ln_base:
    name: v_ln_base
    annotations:
      order:
        tag: order
        value: 13
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 10
      separator:
        tag: separator
        value: ','
    description: Line-to-neutral base voltage, in volts.
    todos:
    - 'Import and export disagree on whether BaseVoltage.nominalVoltage is line-to-neutral
      or line-to-line: import stores v_ln_base unconverted, but export divides by
      √3 assuming a line-to-line value. This asymmetry breaks round-tripping and should
      be reconciled.'
    comments:
    - 'Import: BaseVoltage.nominalVoltage = v_ln_base directly (both are line-to-neutral
      volts; the importer does not apply a √3 factor). Export: v_ln_base = nominalVoltage
      / √3, resolved by traversing ConnectivityNode → Terminal → ConductingEquipment
      → BaseVoltage (or, for a transformer terminal, PowerTransformerEnd.ratedU /
      √3) — i.e. export treats the stored CIM value as phase-phase and converts to
      phase-neutral, which is the opposite convention from import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:BaseVoltage.nominalVoltage
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    - BranchRecord
    range: float
    required: false
    unit:
      ucum_code: V
  s_base:
    name: s_base
    annotations:
      order:
        tag: order
        value: 14
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 1
      separator:
        tag: separator
        value: ','
    description: Apparent power base, in volt-amperes.
    todos:
    - Export hard-codes s_base = 1e6 (_S_BASE) rather than resolving a per-bus base
      voltage/power combination.
    comments:
    - DistOPF-only scaling constant used to convert the per-unit load fields (pl_*/ql_*)
      to and from CIM's SI-unit power values; not itself stored on the CIM object.
      Both import and export currently use a fixed 1e6 VA (1 MVA) base regardless
      of this field's value.
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1000000.0)
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    range: float
    required: false
    unit:
      ucum_code: VA
  v_min:
    name: v_min
    annotations:
      order:
        tag: order
        value: 15
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Minimum voltage magnitude limit, in per-unit.
    todos:
    - No CIM equivalent for a per-bus minimum voltage limit; the closest CIM concept
      (an OperationalLimit on a VoltageLimit) is not wired up.
    comments:
    - 'DistOPF-only (N/A): OPF voltage constraint lower bound; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.95)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_max:
    name: v_max
    annotations:
      order:
        tag: order
        value: 16
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum voltage magnitude limit, in per-unit.
    todos:
    - No CIM equivalent for a per-bus maximum voltage limit; the closest CIM concept
      (an OperationalLimit on a VoltageLimit) is not wired up.
    comments:
    - 'DistOPF-only (N/A): OPF voltage constraint upper bound; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.05)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  cvr_p:
    name: cvr_p
    annotations:
      order:
        tag: order
        value: 17
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Conservation Voltage Reduction (CVR) active power coefficient.
    todos:
    - No CIM equivalent for a per-bus CVR active-power coefficient (the closest concept,
      EnergyConsumer.pVoltageExponent, is not wired up); would need a converter to
      roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF voltage-dependent load coefficient; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
  cvr_q:
    name: cvr_q
    annotations:
      order:
        tag: order
        value: 18
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Conservation Voltage Reduction (CVR) reactive power coefficient.
    todos:
    - No CIM equivalent for a per-bus CVR reactive-power coefficient (the closest
      concept, EnergyConsumer.qVoltageExponent, is not wired up); would need a converter
      to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF voltage-dependent load coefficient; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 19
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Active phases at this bus (abc, a, b, c, ab, ac, bc).
    comments:
    - 'Not used on import. Export: derived from the set of phases with an EnergyConsumerPhase
      child on a connected EnergyConsumer; defaults to "abc" when no per-phase children
      are present (even if the load is genuinely single-phase — see the pl_a family
      of comments).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergyConsumerPhase.phase
    rank: 1000
    ifabsent: string("abc")
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  has_gen:
    name: has_gen
    annotations:
      order:
        tag: order
        value: 20
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a generator is connected at this bus.
    comments:
    - 'Not used on import (generator equipment is created separately by the GeneratorRecord
      converter and linked by ConnectivityNode). Export: has_gen = True if any Terminal
      on this ConnectivityNode connects to a SynchronousMachine or PowerElectronicsConnection.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:SynchronousMachine
    - cim:PowerElectronicsConnection
    rank: 1000
    ifabsent: 'false'
    domain_of:
    - BusRecord
    range: boolean
    required: false
  has_load:
    name: has_load
    annotations:
      order:
        tag: order
        value: 21
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a load is connected at this bus.
    comments:
    - 'Import: has_load gates whether an EnergyConsumer is created for this bus at
      all. Export: has_load = True if any Terminal on this ConnectivityNode connects
      to an EnergyConsumer.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergyConsumer
    rank: 1000
    ifabsent: 'false'
    domain_of:
    - BusRecord
    range: boolean
    required: false
  has_cap:
    name: has_cap
    annotations:
      order:
        tag: order
        value: 22
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a capacitor is connected at this bus.
    comments:
    - 'Not used on import (capacitor equipment is created separately by the CapacitorRecord
      converter and linked by ConnectivityNode). Export: has_cap = True if any Terminal
      on this ConnectivityNode connects to a LinearShuntCompensator.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:LinearShuntCompensator
    rank: 1000
    ifabsent: 'false'
    domain_of:
    - BusRecord
    range: boolean
    required: false
  latitude:
    name: latitude
    annotations:
      order:
        tag: order
        value: 23
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 4
      separator:
        tag: separator
        value: ','
    description: Geographic latitude, in degrees.
    todos:
    - No CIM equivalent wired up. CIM's PositionPoint (via Location) could carry this,
      but ConnectivityNode does not currently traverse to one.
    comments:
    - 'DistOPF-only (N/A): geographic coordinate; not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: deg
  longitude:
    name: longitude
    annotations:
      order:
        tag: order
        value: 24
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 4
      separator:
        tag: separator
        value: ','
    description: Geographic longitude, in degrees.
    todos:
    - No CIM equivalent wired up. CIM's PositionPoint (via Location) could carry this,
      but ConnectivityNode does not currently traverse to one.
    comments:
    - 'DistOPF-only (N/A): geographic coordinate; not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: deg
  load_shape:
    name: load_shape
    annotations:
      order:
        tag: order
        value: 25
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ''
    description: Name of the load-shape profile applied to this bus.
    todos:
    - No CIM equivalent is wired up; implementing this depends on the ScheduleRecord
      → RegularIntervalSchedule converter described in case/schedule.yaml's class-level
      todo.
    comments:
    - 'DistOPF-only: names a row in the separate ScheduleRecord table (see case/schedule.yaml),
      which itself has no CIM converter yet. Not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:RegularIntervalSchedule
    rank: 1000
    ifabsent: string("default")
    domain_of:
    - BusRecord
    range: string
    required: false

Induced

name: BusRecord
description: Bus data record for DistOPF three-phase distribution OPF.
comments:
- DistOPF BusRecord maps primarily to a CIM ConnectivityNode, with an associated BaseVoltage/VoltageLevel/Substation
  created (or reused) for the bus's base voltage, and an optional EnergyConsumer when
  the bus carries load. Import creates all of these from a single record. Export starts
  from the ConnectivityNode and traverses its Terminals to recover load, generation,
  and capacitor presence.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:ConnectivityNode
attributes:
  id:
    name: id
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Bus integer index (one-based row number).
    comments:
    - 'DistOPF-only: a row index used to key this record and resolved by branch/generator/capacitor/battery
      records via fb/tb. Not stored on the CIM ConnectivityNode, which is identified
      by its own mRID. Export assigns fresh 1-based indices to ConnectivityNodes in
      traversal order, so round-tripped indices are not guaranteed to match the original
      import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    identifier: true
    owner: BusRecord
    domain_of:
    - BusRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: integer
    required: true
  name:
    name: name
    annotations:
      order:
        tag: order
        value: 2
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Bus name label (matches the original feeder bus number).
    comments:
    - 'Direct name mapping in both directions: name ↔ ConnectivityNode.name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    exact_mappings:
    - cim:IdentifiedObject.name
    rank: 1000
    ifabsent: string("")
    owner: BusRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    range: string
    required: false
  pl_a:
    name: pl_a
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase A active load in per-unit (base s_base).
    comments:
    - 'Import: pl_a, pl_b, and pl_c are summed and converted to a single EnergyConsumer.p
      = (pl_a + pl_b + pl_c) × s_base (per-unit to watts); there is no per-phase EnergyConsumerPhase
      created, so the load is not split back out per phase on the CIM side. Export:
      pl_a = EnergyConsumerPhase(phase=A).p / s_base when per-phase children exist
      on the connected EnergyConsumer; otherwise the total EnergyConsumer.p / s_base
      is written to pl_a alone (pl_b and pl_c are left at zero).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:EnergyConsumerPhase.p
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_a:
    name: ql_a
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase A reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_a (reactive power): see the pl_a comment for
      the full EnergyConsumer.q derivation.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:EnergyConsumerPhase.q
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  pl_b:
    name: pl_b
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase B active load in per-unit (base s_base).
    comments:
    - 'Import: included in the pl_a+pl_b+pl_c sum written to EnergyConsumer.p (see
      the pl_a comment). Export: pl_b = EnergyConsumerPhase(phase=B).p / s_base when
      per-phase children exist; otherwise left at zero (the fallback total goes to
      pl_a only).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_b:
    name: ql_b
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase B reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_b (reactive power): see the pl_b and pl_a
      comments.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  pl_c:
    name: pl_c
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase C active load in per-unit (base s_base).
    comments:
    - 'Import: included in the pl_a+pl_b+pl_c sum written to EnergyConsumer.p (see
      the pl_a comment). Export: pl_c = EnergyConsumerPhase(phase=C).p / s_base when
      per-phase children exist; otherwise left at zero (the fallback total goes to
      pl_a only).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  ql_c:
    name: ql_c
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 16
      separator:
        tag: separator
        value: ','
    description: Phase C reactive load in per-unit (base s_base).
    comments:
    - 'Same import/export formula as pl_c (reactive power): see the pl_c and pl_a
      comments.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  bus_type:
    name: bus_type
    annotations:
      order:
        tag: order
        value: 9
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Bus type (SWING = slack bus, PQ = load bus).
    comments:
    - 'Not used on import (the bus/slack designation is not derived from this field).
      Export: bus_type = "SWING" when the ConnectivityNode has a Terminal connected
      to an EnergySource, otherwise "PQ" — i.e. the swing bus is detected structurally,
      not read from a dedicated CIM attribute.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergySource.Terminals
    rank: 1000
    ifabsent: string("PQ")
    owner: BusRecord
    domain_of:
    - BusRecord
    range: string
    required: false
  v_a:
    name: v_a
    annotations:
      order:
        tag: order
        value: 10
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase A initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_b:
    name: v_b
    annotations:
      order:
        tag: order
        value: 11
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase B initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_c:
    name: v_c
    annotations:
      order:
        tag: order
        value: 12
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase C initial voltage magnitude in per-unit (base v_ln_base).
    todos:
    - No CIM equivalent for a per-phase OPF initial voltage guess on ConnectivityNode;
      would need a CIM extension (or a SvVoltage state-variable link) to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF initial-guess/flat-start voltage; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_ln_base:
    name: v_ln_base
    annotations:
      order:
        tag: order
        value: 13
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 10
      separator:
        tag: separator
        value: ','
    description: Line-to-neutral base voltage, in volts.
    todos:
    - 'Import and export disagree on whether BaseVoltage.nominalVoltage is line-to-neutral
      or line-to-line: import stores v_ln_base unconverted, but export divides by
      √3 assuming a line-to-line value. This asymmetry breaks round-tripping and should
      be reconciled.'
    comments:
    - 'Import: BaseVoltage.nominalVoltage = v_ln_base directly (both are line-to-neutral
      volts; the importer does not apply a √3 factor). Export: v_ln_base = nominalVoltage
      / √3, resolved by traversing ConnectivityNode → Terminal → ConductingEquipment
      → BaseVoltage (or, for a transformer terminal, PowerTransformerEnd.ratedU /
      √3) — i.e. export treats the stored CIM value as phase-phase and converts to
      phase-neutral, which is the opposite convention from import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    close_mappings:
    - cim:BaseVoltage.nominalVoltage
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    - BranchRecord
    range: float
    required: false
    unit:
      ucum_code: V
  s_base:
    name: s_base
    annotations:
      order:
        tag: order
        value: 14
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 1
      separator:
        tag: separator
        value: ','
    description: Apparent power base, in volt-amperes.
    todos:
    - Export hard-codes s_base = 1e6 (_S_BASE) rather than resolving a per-bus base
      voltage/power combination.
    comments:
    - DistOPF-only scaling constant used to convert the per-unit load fields (pl_*/ql_*)
      to and from CIM's SI-unit power values; not itself stored on the CIM object.
      Both import and export currently use a fixed 1e6 VA (1 MVA) base regardless
      of this field's value.
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1000000.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    range: float
    required: false
    unit:
      ucum_code: VA
  v_min:
    name: v_min
    annotations:
      order:
        tag: order
        value: 15
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Minimum voltage magnitude limit, in per-unit.
    todos:
    - No CIM equivalent for a per-bus minimum voltage limit; the closest CIM concept
      (an OperationalLimit on a VoltageLimit) is not wired up.
    comments:
    - 'DistOPF-only (N/A): OPF voltage constraint lower bound; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.95)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  v_max:
    name: v_max
    annotations:
      order:
        tag: order
        value: 16
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum voltage magnitude limit, in per-unit.
    todos:
    - No CIM equivalent for a per-bus maximum voltage limit; the closest CIM concept
      (an OperationalLimit on a VoltageLimit) is not wired up.
    comments:
    - 'DistOPF-only (N/A): OPF voltage constraint upper bound; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(1.05)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  cvr_p:
    name: cvr_p
    annotations:
      order:
        tag: order
        value: 17
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Conservation Voltage Reduction (CVR) active power coefficient.
    todos:
    - No CIM equivalent for a per-bus CVR active-power coefficient (the closest concept,
      EnergyConsumer.pVoltageExponent, is not wired up); would need a converter to
      roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF voltage-dependent load coefficient; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
  cvr_q:
    name: cvr_q
    annotations:
      order:
        tag: order
        value: 18
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Conservation Voltage Reduction (CVR) reactive power coefficient.
    todos:
    - No CIM equivalent for a per-bus CVR reactive-power coefficient (the closest
      concept, EnergyConsumer.qVoltageExponent, is not wired up); would need a converter
      to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF voltage-dependent load coefficient; not read or written
      by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 19
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Active phases at this bus (abc, a, b, c, ab, ac, bc).
    comments:
    - 'Not used on import. Export: derived from the set of phases with an EnergyConsumerPhase
      child on a connected EnergyConsumer; defaults to "abc" when no per-phase children
      are present (even if the load is genuinely single-phase — see the pl_a family
      of comments).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergyConsumerPhase.phase
    rank: 1000
    ifabsent: string("abc")
    owner: BusRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  has_gen:
    name: has_gen
    annotations:
      order:
        tag: order
        value: 20
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a generator is connected at this bus.
    comments:
    - 'Not used on import (generator equipment is created separately by the GeneratorRecord
      converter and linked by ConnectivityNode). Export: has_gen = True if any Terminal
      on this ConnectivityNode connects to a SynchronousMachine or PowerElectronicsConnection.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:SynchronousMachine
    - cim:PowerElectronicsConnection
    rank: 1000
    ifabsent: 'false'
    owner: BusRecord
    domain_of:
    - BusRecord
    range: boolean
    required: false
  has_load:
    name: has_load
    annotations:
      order:
        tag: order
        value: 21
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a load is connected at this bus.
    comments:
    - 'Import: has_load gates whether an EnergyConsumer is created for this bus at
      all. Export: has_load = True if any Terminal on this ConnectivityNode connects
      to an EnergyConsumer.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:EnergyConsumer
    rank: 1000
    ifabsent: 'false'
    owner: BusRecord
    domain_of:
    - BusRecord
    range: boolean
    required: false
  has_cap:
    name: has_cap
    annotations:
      order:
        tag: order
        value: 22
      value_type:
        tag: value_type
        value: bool
      separator:
        tag: separator
        value: ','
    description: True if a capacitor is connected at this bus.
    comments:
    - 'Not used on import (capacitor equipment is created separately by the CapacitorRecord
      converter and linked by ConnectivityNode). Export: has_cap = True if any Terminal
      on this ConnectivityNode connects to a LinearShuntCompensator.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:LinearShuntCompensator
    rank: 1000
    ifabsent: 'false'
    owner: BusRecord
    domain_of:
    - BusRecord
    range: boolean
    required: false
  latitude:
    name: latitude
    annotations:
      order:
        tag: order
        value: 23
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 4
      separator:
        tag: separator
        value: ','
    description: Geographic latitude, in degrees.
    todos:
    - No CIM equivalent wired up. CIM's PositionPoint (via Location) could carry this,
      but ConnectivityNode does not currently traverse to one.
    comments:
    - 'DistOPF-only (N/A): geographic coordinate; not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: deg
  longitude:
    name: longitude
    annotations:
      order:
        tag: order
        value: 24
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 4
      separator:
        tag: separator
        value: ','
    description: Geographic longitude, in degrees.
    todos:
    - No CIM equivalent wired up. CIM's PositionPoint (via Location) could carry this,
      but ConnectivityNode does not currently traverse to one.
    comments:
    - 'DistOPF-only (N/A): geographic coordinate; not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    rank: 1000
    ifabsent: float(0.0)
    owner: BusRecord
    domain_of:
    - BusRecord
    range: float
    required: false
    unit:
      ucum_code: deg
  load_shape:
    name: load_shape
    annotations:
      order:
        tag: order
        value: 25
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ''
    description: Name of the load-shape profile applied to this bus.
    todos:
    - No CIM equivalent is wired up; implementing this depends on the ScheduleRecord
      → RegularIntervalSchedule converter described in case/schedule.yaml's class-level
      todo.
    comments:
    - 'DistOPF-only: names a row in the separate ScheduleRecord table (see case/schedule.yaml),
      which itself has no CIM converter yet. Not read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/bus
    related_mappings:
    - cim:RegularIntervalSchedule
    rank: 1000
    ifabsent: string("default")
    owner: BusRecord
    domain_of:
    - BusRecord
    range: string
    required: false