Class: RegulatorRecord

Step voltage regulator data record for DistOPF. Tap positions are integer step counts (positive = raise, negative = lower).

Note: the id field is a synthetic identifier not present in the CSV. The reader constructs it as "{fb}" (for example, "1_2")._

URI: distopf:RegulatorRecord

 classDiagram
    class RegulatorRecord
    click RegulatorRecord href "../RegulatorRecord/"
      RegulatorRecord : fb

      RegulatorRecord : from_name

      RegulatorRecord : id

      RegulatorRecord : phases

      RegulatorRecord : tap_a

      RegulatorRecord : tap_b

      RegulatorRecord : tap_c

      RegulatorRecord : tb

      RegulatorRecord : to_name

Slots

Name	Cardinality and Range	Description	Inheritance
id	1 String	Synthetic identifier constructed as "{fb}_{tb}" (for example, "1_2")	direct
fb	1 Integer	From-bus integer index	direct
tb	1 Integer	To-bus integer index	direct
from_name	0..1 String	From-bus name label (the ConnectivityNode name)	direct
to_name	0..1 String	To-bus name label (the ConnectivityNode name)	direct
phases	0..1 String	Regulated phases (abc, a, b, c, ab, ac, bc)	direct
tap_a	0..1 Float	Phase A tap position, in steps (0	direct
tap_b	0..1 Float	Phase B tap position, in steps (0	direct
tap_c	0..1 Float	Phase C tap position, in steps (0	direct

Usages

used by	used in	type	used
DistopfModel	regulator_records	range	RegulatorRecord

Comments

• DistOPF RegulatorRecord maps to a CIM RatioTapChanger attached to a PowerTransformerEnd, on the PowerTransformer identified by the fb/tb bus pair. Import creates one RatioTapChanger per record, using tap_a as the tap position for all phases. Export groups the tap changers found on a transformer's from/to bus pair back into one record with per-phase tap positions.

Identifier and Mapping Information

Schema Source

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

Mappings

Mapping Type	Mapped Value
self	distopf:RegulatorRecord
native	distopf:RegulatorRecord
exact	cim:RatioTapChanger

LinkML Source

Direct

name: RegulatorRecord
description: 'Step voltage regulator data record for DistOPF. Tap positions are integer
  step counts (positive = raise, negative = lower).

  Note: the `id` field is a synthetic identifier not present in the CSV. The reader
  constructs it as "{fb}_{tb}" (for example, "1_2").'
comments:
- DistOPF RegulatorRecord maps to a CIM RatioTapChanger attached to a PowerTransformerEnd,
  on the PowerTransformer identified by the fb/tb bus pair. Import creates one RatioTapChanger
  per record, using tap_a as the tap position for all phases. Export groups the tap
  changers found on a transformer's from/to bus pair back into one record with per-phase
  tap positions.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:RatioTapChanger
attributes:
  id:
    name: id
    description: Synthetic identifier constructed as "{fb}_{tb}" (for example, "1_2").
      Not present in the CSV; generated by the reader.
    comments:
    - 'DistOPF-only: a synthetic key built from fb/tb, not a CIM identity. The CIM
      RatioTapChanger is identified by its own mRID and named "reg_{fb}_{tb}" on import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    identifier: true
    domain_of:
    - BusRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: true
  fb:
    name: fb
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: From-bus integer index.
    comments:
    - 'Structural mapping via traversal: the transformer is found by searching PowerTransformer
      objects whose Terminals connect the ConnectivityNodes at bus indices fb and
      tb. Import: fb identifies the PowerTransformerEnd (endNumber 1) whose terminal
      the tap changer attaches near. Export: fb = the bus index of the first sorted
      PowerTransformerEnd''s ConnectivityNode.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    related_mappings:
    - cim:PowerTransformerEnd.Terminal
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: integer
    required: true
  tb:
    name: tb
    annotations:
      order:
        tag: order
        value: 2
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: To-bus integer index.
    comments:
    - 'Same traversal as fb (see the fb comment). Import: tb identifies the PowerTransformerEnd
      (endNumber 2) that the RatioTapChanger is actually attached to. Export: tb =
      the bus index of the second sorted PowerTransformerEnd''s ConnectivityNode.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    related_mappings:
    - cim:PowerTransformerEnd.Terminal
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: integer
    required: true
  from_name:
    name: from_name
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: From-bus name label (the ConnectivityNode name).
    comments:
    - 'Not used on import (the transformer is located by fb/tb bus index, not by name).
      Export: from_name = the from-side ConnectivityNode''s name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("")
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: string
    required: false
  to_name:
    name: to_name
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: To-bus name label (the ConnectivityNode name).
    comments:
    - 'Not used on import (the transformer is located by fb/tb bus index, not by name).
      Export: to_name = the to-side ConnectivityNode''s name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("")
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: string
    required: false
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Regulated phases (abc, a, b, c, ab, ac, bc).
    todos:
    - Export always writes phases="abc" regardless of which single phase (if any)
      the source RatioTapChanger actually controls.
    comments:
    - 'Not used on import. Export: always written as "abc"; the exporter currently
      reports the record''s overall phase coverage rather than deriving it from which
      of tap_a/tap_b/tap_c are non-neutral.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("abc")
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  tap_a:
    name: tap_a
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase A tap position, in steps (0.0 = neutral).
    comments:
    - 'Import: RatioTapChanger.step = tap_a directly (tap_a is used as the single
      representative tap position for the transformer end, regardless of phase; neutralStep
      is fixed at 0). Export: tap_a = step − neutralStep when the tap changer''s phase
      resolves to A (via TransformerEnd.phases, or by convention from the RatioTapChanger''s
      name); if no phase can be determined, the same tap position is written to tap_a,
      tap_b, and tap_c.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    close_mappings:
    - cim:RatioTapChanger.step
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - RegulatorRecord
    range: float
    required: false
  tap_b:
    name: tap_b
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase B tap position, in steps (0.0 = neutral).
    todos:
    - Import does not read tap_b — a per-phase RatioTapChanger for phase B is never
      created from this field.
    comments:
    - 'Not used on import (only tap_a is read; see the tap_a comment). Export: tap_b
      = step − neutralStep when the tap changer''s phase resolves to B, following
      the same logic as tap_a.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - RegulatorRecord
    range: float
    required: false
  tap_c:
    name: tap_c
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ''
    description: Phase C tap position, in steps (0.0 = neutral).
    todos:
    - Import does not read tap_c — a per-phase RatioTapChanger for phase C is never
      created from this field.
    comments:
    - 'Not used on import (only tap_a is read; see the tap_a comment). Export: tap_c
      = step − neutralStep when the tap changer''s phase resolves to C, following
      the same logic as tap_a.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    rank: 1000
    ifabsent: float(0.0)
    domain_of:
    - RegulatorRecord
    range: float
    required: false

Induced

name: RegulatorRecord
description: 'Step voltage regulator data record for DistOPF. Tap positions are integer
  step counts (positive = raise, negative = lower).

  Note: the `id` field is a synthetic identifier not present in the CSV. The reader
  constructs it as "{fb}_{tb}" (for example, "1_2").'
comments:
- DistOPF RegulatorRecord maps to a CIM RatioTapChanger attached to a PowerTransformerEnd,
  on the PowerTransformer identified by the fb/tb bus pair. Import creates one RatioTapChanger
  per record, using tap_a as the tap position for all phases. Export groups the tap
  changers found on a transformer's from/to bus pair back into one record with per-phase
  tap positions.
from_schema: https://gridappsd.org/cimhub/distopf
exact_mappings:
- cim:RatioTapChanger
attributes:
  id:
    name: id
    description: Synthetic identifier constructed as "{fb}_{tb}" (for example, "1_2").
      Not present in the CSV; generated by the reader.
    comments:
    - 'DistOPF-only: a synthetic key built from fb/tb, not a CIM identity. The CIM
      RatioTapChanger is identified by its own mRID and named "reg_{fb}_{tb}" on import.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    identifier: true
    owner: RegulatorRecord
    domain_of:
    - BusRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: true
  fb:
    name: fb
    annotations:
      order:
        tag: order
        value: 1
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: From-bus integer index.
    comments:
    - 'Structural mapping via traversal: the transformer is found by searching PowerTransformer
      objects whose Terminals connect the ConnectivityNodes at bus indices fb and
      tb. Import: fb identifies the PowerTransformerEnd (endNumber 1) whose terminal
      the tap changer attaches near. Export: fb = the bus index of the first sorted
      PowerTransformerEnd''s ConnectivityNode.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    related_mappings:
    - cim:PowerTransformerEnd.Terminal
    owner: RegulatorRecord
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: integer
    required: true
  tb:
    name: tb
    annotations:
      order:
        tag: order
        value: 2
      value_type:
        tag: value_type
        value: int
      separator:
        tag: separator
        value: ','
    description: To-bus integer index.
    comments:
    - 'Same traversal as fb (see the fb comment). Import: tb identifies the PowerTransformerEnd
      (endNumber 2) that the RatioTapChanger is actually attached to. Export: tb =
      the bus index of the second sorted PowerTransformerEnd''s ConnectivityNode.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    related_mappings:
    - cim:PowerTransformerEnd.Terminal
    owner: RegulatorRecord
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: integer
    required: true
  from_name:
    name: from_name
    annotations:
      order:
        tag: order
        value: 3
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: From-bus name label (the ConnectivityNode name).
    comments:
    - 'Not used on import (the transformer is located by fb/tb bus index, not by name).
      Export: from_name = the from-side ConnectivityNode''s name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("")
    owner: RegulatorRecord
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: string
    required: false
  to_name:
    name: to_name
    annotations:
      order:
        tag: order
        value: 4
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: To-bus name label (the ConnectivityNode name).
    comments:
    - 'Not used on import (the transformer is located by fb/tb bus index, not by name).
      Export: to_name = the to-side ConnectivityNode''s name.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("")
    owner: RegulatorRecord
    domain_of:
    - BranchRecord
    - RegulatorRecord
    range: string
    required: false
  phases:
    name: phases
    annotations:
      order:
        tag: order
        value: 5
      value_type:
        tag: value_type
        value: string
      quote:
        tag: quote
        value: false
      separator:
        tag: separator
        value: ','
    description: Regulated phases (abc, a, b, c, ab, ac, bc).
    todos:
    - Export always writes phases="abc" regardless of which single phase (if any)
      the source RatioTapChanger actually controls.
    comments:
    - 'Not used on import. Export: always written as "abc"; the exporter currently
      reports the record''s overall phase coverage rather than deriving it from which
      of tap_a/tap_b/tap_c are non-neutral.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    ifabsent: string("abc")
    owner: RegulatorRecord
    domain_of:
    - BusRecord
    - BranchRecord
    - GeneratorRecord
    - CapacitorRecord
    - BatteryRecord
    - RegulatorRecord
    range: string
    required: false
  tap_a:
    name: tap_a
    annotations:
      order:
        tag: order
        value: 6
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase A tap position, in steps (0.0 = neutral).
    comments:
    - 'Import: RatioTapChanger.step = tap_a directly (tap_a is used as the single
      representative tap position for the transformer end, regardless of phase; neutralStep
      is fixed at 0). Export: tap_a = step − neutralStep when the tap changer''s phase
      resolves to A (via TransformerEnd.phases, or by convention from the RatioTapChanger''s
      name); if no phase can be determined, the same tap position is written to tap_a,
      tap_b, and tap_c.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    close_mappings:
    - cim:RatioTapChanger.step
    rank: 1000
    ifabsent: float(0.0)
    owner: RegulatorRecord
    domain_of:
    - RegulatorRecord
    range: float
    required: false
  tap_b:
    name: tap_b
    annotations:
      order:
        tag: order
        value: 7
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ','
    description: Phase B tap position, in steps (0.0 = neutral).
    todos:
    - Import does not read tap_b — a per-phase RatioTapChanger for phase B is never
      created from this field.
    comments:
    - 'Not used on import (only tap_a is read; see the tap_a comment). Export: tap_b
      = step − neutralStep when the tap changer''s phase resolves to B, following
      the same logic as tap_a.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    rank: 1000
    ifabsent: float(0.0)
    owner: RegulatorRecord
    domain_of:
    - RegulatorRecord
    range: float
    required: false
  tap_c:
    name: tap_c
    annotations:
      order:
        tag: order
        value: 8
      value_type:
        tag: value_type
        value: float
      precision:
        tag: precision
        value: 6
      separator:
        tag: separator
        value: ''
    description: Phase C tap position, in steps (0.0 = neutral).
    todos:
    - Import does not read tap_c — a per-phase RatioTapChanger for phase C is never
      created from this field.
    comments:
    - 'Not used on import (only tap_a is read; see the tap_a comment). Export: tap_c
      = step − neutralStep when the tap changer''s phase resolves to C, following
      the same logic as tap_a.'
    from_schema: https://gridappsd.org/cimhub/distopf/classes/regulator
    rank: 1000
    ifabsent: float(0.0)
    owner: RegulatorRecord
    domain_of:
    - RegulatorRecord
    range: float
    required: false