Class: BatteryRecord

Battery energy storage system (BESS) data record for DistOPF. Power ratings are in per-unit (base s_base). Energy capacity is in per-unit hours (s_base × hour). State-of-charge fields are fractions (0.0-1.0).

URI: distopf:BatteryRecord

 classDiagram
    class BatteryRecord
    click BatteryRecord href "../BatteryRecord/"
      BatteryRecord : annual_cycle_limit

      BatteryRecord : charge_efficiency

      BatteryRecord : control_variable

      BatteryRecord : discharge_efficiency

      BatteryRecord : energy_capacity

      BatteryRecord : id

      BatteryRecord : max_soc

      BatteryRecord : min_soc

      BatteryRecord : name

      BatteryRecord : phases

      BatteryRecord : s_max

      BatteryRecord : start_soc

Slots

Name	Cardinality and Range	Description	Inheritance
id	1 Integer	Battery integer index (one-based row number)	direct
name	0..1 String	Battery name label (matches the name of the bus where the battery connects)	direct
s_max	0..1 Float	Maximum apparent power rating in per-unit (base s_base)	direct
phases	0..1 String	Active phases for this battery (abc, a, b, c, ab, ac, bc)	direct
energy_capacity	0..1 Float	Total energy capacity in per-unit hours (s_base × hour)	direct
min_soc	0..1 Float	Minimum state of charge, as a fraction (0	direct
max_soc	0..1 Float	Maximum state of charge, as a fraction (0	direct
start_soc	0..1 Float	Initial state of charge, as a fraction (0	direct
charge_efficiency	0..1 Float	Charging efficiency, as a fraction (0	direct
discharge_efficiency	0..1 Float	Discharging efficiency, as a fraction (0	direct
annual_cycle_limit	0..1 Integer	Annual charge/discharge cycle limit, in cycles per year	direct
control_variable	0..1 String	OPF control variable (P = active power, Q = reactive power, PQ = both, empty ...	direct

Usages

used by	used in	type	used
DistopfModel	battery_records	range	BatteryRecord

Comments

• DistOPF BatteryRecord maps to a CIM BatteryUnit connected through a PowerElectronicsConnection. Import creates both objects from a single record; export reads the BatteryUnit and its PowerElectronicsConnection back into one record.

Identifier and Mapping Information

Schema Source

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

Mappings

Mapping Type	Mapped Value
self	distopf:BatteryRecord
native	distopf:BatteryRecord
exact	cim:BatteryUnit

LinkML Source

Direct

name: BatteryRecord
description: Battery energy storage system (BESS) data record for DistOPF. Power ratings
  are in per-unit (base s_base). Energy capacity is in per-unit hours (s_base × hour).
  State-of-charge fields are fractions (0.0-1.0).
comments:
- DistOPF BatteryRecord maps to a CIM BatteryUnit connected through a PowerElectronicsConnection.
  Import creates both objects from a single record; export reads the BatteryUnit and
  its PowerElectronicsConnection back into one record.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:BatteryUnit
attributes:
  id:
    name: id
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Battery integer index (one-based row number).
    comments:
    - 'DistOPF-only: a row index used to key this record, not a CIM identity. On import
      the battery''s ConnectivityNode is looked up by name (falling back to this index
      against the bus table); the CIM objects are identified by their own mRID.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    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: Battery name label (matches the name of the bus where the battery
      connects).
    comments:
    - 'Import: BatteryUnit.name = PowerElectronicsConnection.name = name, and the
      same string is used to look up the connected ConnectivityNode by name. Export:
      name = the connected ConnectivityNode''s name (falls back to BatteryUnit.name
      if the PowerElectronicsConnection has no resolvable terminal node).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:IdentifiedObject.name
    ifabsent: string("")
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    range: string
    required: false
  s_max:
    name: s_max
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum apparent power rating in per-unit (base s_base).
    comments:
    - 'Import: PowerElectronicsConnection.ratedS = s_max × s_base (per-unit to volt-amperes).
      Export: s_max = ratedS / s_base.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:PowerElectronicsConnection.ratedS
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Active phases for this battery (abc, a, b, c, ab, ac, bc).
    todos:
    - Export does not inspect PowerElectronicsConnectionPhase children, so a single-phase
      or split-phase battery always exports as "abc".
    comments:
    - 'Not used on import (the importer always creates a single three-phase connection
      with no PowerElectronicsConnectionPhase children). Export: always written as
      "abc"; per-phase battery connections are not yet detected.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    ifabsent: string("abc")
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  energy_capacity:
    name: energy_capacity
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Total energy capacity in per-unit hours (s_base × hour). For example,
      1.2 with s_base = 1 MVA is 1.2 MWh.
    todos:
    - BatteryUnit.ratedE is populated with cim.ActivePower (watts), which is dimensionally
      a power unit, not energy (watt-hours); the watt-hour value is correct numerically
      but the CIMUnit type should be an energy unit once one exists in the profile.
    comments:
    - 'Import: BatteryUnit.ratedE = energy_capacity × s_base (per-unit hours to watt-hours,
      since s_base is in VA). Export: energy_capacity = ratedE / s_base.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    close_mappings:
    - cim:BatteryUnit.ratedE
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
    unit:
      ucum_code: pu.h
  min_soc:
    name: min_soc
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Minimum state of charge, as a fraction (0.0-1.0).
    todos:
    - No CIM equivalent for a minimum state-of-charge limit on BatteryUnit; requires
      a CIM extension to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF state-of-charge bound; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
  max_soc:
    name: max_soc
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum state of charge, as a fraction (0.0-1.0).
    todos:
    - No CIM equivalent for a maximum state-of-charge limit on BatteryUnit; requires
      a CIM extension to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF state-of-charge bound; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
  start_soc:
    name: start_soc
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Initial state of charge, as a fraction (0.0-1.0).
    comments:
    - 'Import: BatteryUnit.storedE = energy_capacity × s_base × start_soc. Export:
      start_soc = storedE / ratedE (falls back to 0.5 if ratedE is zero or unset).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    close_mappings:
    - cim:BatteryUnit.storedE
    rank: 1000
    ifabsent: float(0.5)
    domain_of:
    - BatteryRecord
    range: float
    required: false
  charge_efficiency:
    name: charge_efficiency
    annotations:
      order:
        tag: order
        value: 9
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Charging efficiency, as a fraction (0.0-1.0).
    comments:
    - 'Direct fraction mapping in both directions, with no unit conversion: charge_efficiency
      ↔ BatteryUnit.chargingEfficiency.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:BatteryUnit.chargingEfficiency
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
  discharge_efficiency:
    name: discharge_efficiency
    annotations:
      order:
        tag: order
        value: 10
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Discharging efficiency, as a fraction (0.0-1.0).
    comments:
    - 'Direct fraction mapping in both directions, with no unit conversion: discharge_efficiency
      ↔ BatteryUnit.dischargingEfficiency.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:BatteryUnit.dischargingEfficiency
    rank: 1000
    ifabsent: float(1.0)
    domain_of:
    - BatteryRecord
    range: float
    required: false
  annual_cycle_limit:
    name: annual_cycle_limit
    annotations:
      order:
        tag: order
        value: 11
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Annual charge/discharge cycle limit, in cycles per year.
    todos:
    - No CIM equivalent for an annual cycle limit on BatteryUnit; requires a CIM extension
      to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF cycling constraint; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: int(365)
    domain_of:
    - BatteryRecord
    range: integer
    required: false
  control_variable:
    name: control_variable
    annotations:
      order:
        tag: order
        value: 12
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ''
    description: OPF control variable (P = active power, Q = reactive power, PQ =
      both, empty = fixed).
    comments:
    - 'DistOPF-only (N/A): OPF solver hint for which setpoints are dispatchable; not
      read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    ifabsent: string("P")
    domain_of:
    - GeneratorRecord
    - BatteryRecord
    range: string
    required: false

Induced

name: BatteryRecord
description: Battery energy storage system (BESS) data record for DistOPF. Power ratings
  are in per-unit (base s_base). Energy capacity is in per-unit hours (s_base × hour).
  State-of-charge fields are fractions (0.0-1.0).
comments:
- DistOPF BatteryRecord maps to a CIM BatteryUnit connected through a PowerElectronicsConnection.
  Import creates both objects from a single record; export reads the BatteryUnit and
  its PowerElectronicsConnection back into one record.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:BatteryUnit
attributes:
  id:
    name: id
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Battery integer index (one-based row number).
    comments:
    - 'DistOPF-only: a row index used to key this record, not a CIM identity. On import
      the battery''s ConnectivityNode is looked up by name (falling back to this index
      against the bus table); the CIM objects are identified by their own mRID.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    identifier: true
    owner: BatteryRecord
    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: Battery name label (matches the name of the bus where the battery
      connects).
    comments:
    - 'Import: BatteryUnit.name = PowerElectronicsConnection.name = name, and the
      same string is used to look up the connected ConnectivityNode by name. Export:
      name = the connected ConnectivityNode''s name (falls back to BatteryUnit.name
      if the PowerElectronicsConnection has no resolvable terminal node).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:IdentifiedObject.name
    ifabsent: string("")
    owner: BatteryRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    range: string
    required: false
  s_max:
    name: s_max
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum apparent power rating in per-unit (base s_base).
    comments:
    - 'Import: PowerElectronicsConnection.ratedS = s_max × s_base (per-unit to volt-amperes).
      Export: s_max = ratedS / s_base.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:PowerElectronicsConnection.ratedS
    rank: 1000
    ifabsent: float(0.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
    unit:
      ucum_code: pu
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Active phases for this battery (abc, a, b, c, ab, ac, bc).
    todos:
    - Export does not inspect PowerElectronicsConnectionPhase children, so a single-phase
      or split-phase battery always exports as "abc".
    comments:
    - 'Not used on import (the importer always creates a single three-phase connection
      with no PowerElectronicsConnectionPhase children). Export: always written as
      "abc"; per-phase battery connections are not yet detected.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    ifabsent: string("abc")
    owner: BatteryRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  energy_capacity:
    name: energy_capacity
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Total energy capacity in per-unit hours (s_base × hour). For example,
      1.2 with s_base = 1 MVA is 1.2 MWh.
    todos:
    - BatteryUnit.ratedE is populated with cim.ActivePower (watts), which is dimensionally
      a power unit, not energy (watt-hours); the watt-hour value is correct numerically
      but the CIMUnit type should be an energy unit once one exists in the profile.
    comments:
    - 'Import: BatteryUnit.ratedE = energy_capacity × s_base (per-unit hours to watt-hours,
      since s_base is in VA). Export: energy_capacity = ratedE / s_base.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    close_mappings:
    - cim:BatteryUnit.ratedE
    rank: 1000
    ifabsent: float(0.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
    unit:
      ucum_code: pu.h
  min_soc:
    name: min_soc
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Minimum state of charge, as a fraction (0.0-1.0).
    todos:
    - No CIM equivalent for a minimum state-of-charge limit on BatteryUnit; requires
      a CIM extension to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF state-of-charge bound; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: float(0.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
  max_soc:
    name: max_soc
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Maximum state of charge, as a fraction (0.0-1.0).
    todos:
    - No CIM equivalent for a maximum state-of-charge limit on BatteryUnit; requires
      a CIM extension to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF state-of-charge bound; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: float(1.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
  start_soc:
    name: start_soc
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Initial state of charge, as a fraction (0.0-1.0).
    comments:
    - 'Import: BatteryUnit.storedE = energy_capacity × s_base × start_soc. Export:
      start_soc = storedE / ratedE (falls back to 0.5 if ratedE is zero or unset).'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    close_mappings:
    - cim:BatteryUnit.storedE
    rank: 1000
    ifabsent: float(0.5)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
  charge_efficiency:
    name: charge_efficiency
    annotations:
      order:
        tag: order
        value: 9
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Charging efficiency, as a fraction (0.0-1.0).
    comments:
    - 'Direct fraction mapping in both directions, with no unit conversion: charge_efficiency
      ↔ BatteryUnit.chargingEfficiency.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:BatteryUnit.chargingEfficiency
    rank: 1000
    ifabsent: float(1.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
  discharge_efficiency:
    name: discharge_efficiency
    annotations:
      order:
        tag: order
        value: 10
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Discharging efficiency, as a fraction (0.0-1.0).
    comments:
    - 'Direct fraction mapping in both directions, with no unit conversion: discharge_efficiency
      ↔ BatteryUnit.dischargingEfficiency.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    exact_mappings:
    - cim:BatteryUnit.dischargingEfficiency
    rank: 1000
    ifabsent: float(1.0)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: float
    required: false
  annual_cycle_limit:
    name: annual_cycle_limit
    annotations:
      order:
        tag: order
        value: 11
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: Annual charge/discharge cycle limit, in cycles per year.
    todos:
    - No CIM equivalent for an annual cycle limit on BatteryUnit; requires a CIM extension
      to roundtrip.
    comments:
    - 'DistOPF-only (N/A): OPF cycling constraint; not read or written by the CIM
      converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    rank: 1000
    ifabsent: int(365)
    owner: BatteryRecord
    domain_of:
    - BatteryRecord
    range: integer
    required: false
  control_variable:
    name: control_variable
    annotations:
      order:
        tag: order
        value: 12
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ''
    description: OPF control variable (P = active power, Q = reactive power, PQ =
      both, empty = fixed).
    comments:
    - 'DistOPF-only (N/A): OPF solver hint for which setpoints are dispatchable; not
      read or written by the CIM converters.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/battery
    ifabsent: string("P")
    owner: BatteryRecord
    domain_of:
    - GeneratorRecord
    - BatteryRecord
    range: string
    required: false