CIM Issues #6202
Modeling guide is missing instructions for data type names in attribute names
CIM Modeling Guide
Description
In a previous version of CIM, the UML was cleaned up to change all properties like "ratedkV" and "ratedVoltage" to be renamed to "ratedU" based on the policy that the data type abbreviations should be used instead of data type names or units of measurement.
However, this naming rule is missing in section "5.5 Attribute Rules" in the CIM Modeling Guide v1.1 (2021-02-13).
Decision
Reviewed on 12-Jun-2023 in Oslo:
Reviewed and universally agreed that this should be added to the CIM Modelling Guide document. It should be spelled out explicitly in the guide which values this should adhere to and what the required value should be. The below is what was decided should be added as a rule to the section:
Active Power (p)
Reactive Power (q)
Apparent Power (s)
Resistance (r)
Reactance (x)
Conductance (g)
Susceptance (b)
Power Factor (pf)
Participation Factor (participationFactor)
IMPORTANT: the rule should state that camel case is to be used. So an attribute would be just "x" and not "X" but ratedX if using camel case.
While there is agreement on the attributes with units listed above, the universal use of (U) for voltage needs further exploration.(e.g. voltage should voltage be using "U" e.g. not ratedkV or ratedVotage, but rather ratedU). It would be good to identify the voltage attributes to see if there are obvious attributes that should be cleaned up.
Additionally, the rule should include:
When expressing sequencing specifically for Reactance (x), Resistance (r), Susceptance (b) and Conductance (g) the following abbreviations are to be applied:
positive -> expressed as shown above as x, r, b, g
zero sequence -> express as x0, r0, b0, g0
negative sequence -> express as x2, r2, b2, g2
NOTE: As part of this task the UML should be updated so that wherever the existing model expresses or abbreviates "Participation Factor" today as PF it should be changed to fully spell the attribute out (i.e. participationFactor). This will remove any ambiguity that will exist. Also we have 2 instances in the UML today where we have negative sequencing expressed as RN and XN and should be changed to r2 and x2 (this would be a breaking change). Given that CIM18 has a lot of breaking changes it is recommended this goes in at the same time (before September 2023).
Question remains as to who to assign the modeling guide updates to.
Modeling should be done by respective modeling managers where applicable.
11-Oct-2023:
We have reviewed and updated the comments above today to clarify further.
26-Oct-2023 Joint WG Hybrid meetings in Minneapolis:
Final decisions were made today after discussion. We have committed to the following:
* The CIM Modelling Guidelines document must be updated with a new rule for this.
* We have decide NOT to change existing attributes so as to minimize breaking changes.
* Instead, starting as of the CIM18 release, any new attributes created that fit into the types specified in this Issue (and correspondingly outlined in the new modelling rule) will be required to conform to the new naming rules.
Release Notes
Section 5.5 in the online CIM Modeling Guide has been updated with new rule Rule059.
For details refer to:
https://cim-mg.ucaiug.io/section5-cim-uml-modeling-rules-and-recommendations/#55-attribute-rules
The corresponding GitHub issue for the change can be found here:
Updated by Martin Miller about 2 years ago
- Subject changed from Modeling guide is missing instructions for value types in names to Modeling guide is missing instructions for data type names in attribute names
Updated by Todd Viegut over 1 year ago
- Status changed from Open to Review
- Solution Version set to CIM18
- Breaking Change set to Yes
- Breaking Change Description set to Change to attribut names
- Requestor set to Martin Miller
- Decision updated (diff)
Updated by Todd Viegut about 1 year ago
- Release Notes updated (diff)
10-Oct-2023:
Do we rename activePower to P or P to activePower. This is not clear from the directives given in the Decision section. Our current understanding is that this should be in the "abbreviated form" (e.g. p, x, ratedU and NOT activePower, reactance, ratedVoltage respectively). We want this double confirmed before we apply abbreviations through the model (and introduce breaking changes).
Updated by Chavdar Ivanov about 1 year ago
Overview for Base package
Attributes to be changed (clear following the instructions)
Core package
BaseVoltage.nominalVoltage => BaseVoltage.nominalU
VoltageLevel.highVoltageLimit => VoltageLevel.highUlimit or should we do highLimitU
VoltageLevel.lowVoltageLimit => VoltageLevel.lowUlimit or should we do lowLimitU
Wires package
EnergySource.activePower => EnergySource.p
EnergySource.reactivePower => EnergySource.q
EnergySource.nominalVoltage => EnergySource.nominalU
EnergySource.voltageAngle => EnergySource.angleU
EnergySource.voltageMagnitude => EnergySource.magnitudeU
ReactiveCapabilityCurve.referenceVoltage => ReactiveCapabilityCurve.referenceU
RotatingMachine.ratedPowerFactor => RotatingMachine.ratedPF
SeriesCompensator.varistorRatedCurrent => SeriesCompensator.varistorRatedI
SeriesCompensator.varistorVoltageThreshold => SeriesCompensator.varistorThresholdU
ShuntCompensator.voltageSensitivity => ShuntCompensator.sensitivityU
StaticVarCompensator.voltageSetPoint => StaticVarCompensator.setPointU
Switch.ratedCurrent => Switch.ratedI
SwitchPhase.ratedCurrent => SwitchPhase.ratedI
SynchronousMachine.voltageRegulationRange => SynchronousMachine.regulationRangeU
TapChangerControl.maxLimitVoltage => TapChangerControl.maxLimitU
TapChangerControl.minLimitVoltage => TapChangerControl.minLimitU
LoadModel package
LoadResponseCharacteristic.pConstantCurrent => LoadResponseCharacteristic.pConstantI
LoadResponseCharacteristic.pConstantImpedance => LoadResponseCharacteristic.pConstantZ
LoadResponseCharacteristic.pConstantPower => LoadResponseCharacteristic.pConstantP
LoadResponseCharacteristic.pFrequencyExponent => LoadResponseCharacteristic.pExponentF
LoadResponseCharacteristic.pVoltageExponent => LoadResponseCharacteristic.pExponentU
LoadResponseCharacteristic.qConstantCurrent => LoadResponseCharacteristic.qConstantI
LoadResponseCharacteristic.qConstantImpedance => LoadResponseCharacteristic.qConstantZ
LoadResponseCharacteristic.qConstantPower => LoadResponseCharacteristic.qConstantP
LoadResponseCharacteristic.qFrequencyExponent => LoadResponseCharacteristic.qExponentF
LoadResponseCharacteristic.qVoltageExponent => LoadResponseCharacteristic.qExponentU
DC package
- DCGround.inductance => DCGround.l
- DCLineSegment.capacitance => DCLineSegment.c
- DCLineSegment.inductance => DCLineSegment.l
- DCLineSegment.resistance => DCLineSegment.r
- DCSeriesDevice.inductance => DCSeriesDevice.l
- DCSeriesDevice.resistance => DCSeriesDevice.r
- DCShunt.capacitance => DCShunt.c
- DCShunt.resistance => DCShunt.r
- PerLengthDCLineParameter.capacitance => PerLengthDCLineParameter.c
- PerLengthDCLineParameter.inductance => PerLengthDCLineParameter.l
- PerLengthDCLineParameter.resistance => PerLengthDCLineParameter.r
- VsCapabilityCurve.referenceVoltage => VsCapabilityCurve.referenceU
- VsConverter.maxValveCurrent => VVsConverter.maxValveI
OperationalLimits package
BranchGroup.maximumActivePower =>BranchGroup.maxP
BranchGroup.minimumActivePower =>BranchGroup.minP
BranchGroup.maximumReactivePower =>BranchGroup.maxQ
BranchGroup.minimumReactivePower =>BranchGroup.minQ
BranchGroup.minitorActivePower =>BranchGroup.monitorP
BranchGroup.minitorReactivePower =>BranchGroup.monitorQ
Questions on attributes:
Core package
BaseFrequency.frequency - does not make sense to do BaseFrequency.f what about BaseFrequency.value
BasePower.basePower - does not make sense to do BasePower.baseP what about BasePower.value
Wires package
- we have AsynchronousMachine.nominalFrequency and .nominalSpeed = do we leave it like this?
- ExternalNetworkInjection.voltageFactor - do we leave it like this or we do uf?
- ExternalNetworkInjection.maxInitialSymShCCurrent and minInitialSymShCCurrent - Do we change to minIk and maxIk
- FrecuencyConverter.frequency - .f or keep it?
- PetercenCoil.offsetCurrent and .positionCurrent - keep it or do .offsetI and positionI
- PowerTransformer.beforeShCircuitHighestOperatingCurrent => PowerTransformer.ib or keep it
- PowerTransformer.beforeShCircuitHighestOperatingVoltage => PowerTransformer.ub or keep it
- PowerTransformer.beforeShortCircuitAnglePf => PowerTransformer.phib or keep it
- PowerTransformer.highSideMinOperatingU => PowerTransformer.uQmin or keep it
Generation package
there are some in the GenerationTrainingSimulation, should we do these too
Updated by Chavdar Ivanov about 1 year ago
TF13 Call 18 Oct 2023
The proposal is to apply this only for the new attributes, i.e. revert the decision. The details of the new approach will need to be recorded in the modelling guide. Preference is to abbreviate only single terms
We have reviewed and updated as follows.
The attribute rule to be added to section 5.5 of the CIM Modelling Guide Document is as follows:
1. For the properties listed below, the attribute name must use the symbol, in lower camel case, instead of the name or unit of measurement.
Active Power (p)
Reactive Power (q)
Apparent Power (s)
Resistance (r)
Reactance (x)
Conductance (g)
Susceptance (b)
Power Factor (pf)
Voltage (u)
Current (i)
Frequency (f)
Inductance (l)
Capacitance (c)
Impedance (z)
Admittance (y)
2. For the properties mentioned in item 1, the symbol is appended with "2" for negative-sequence and "0" for zero-sequence properties.
3. Where properties mentioned in item 1 are used in a compound term (i.e. simple term), e.g. maximum voltage, nominal apparent power, natural impedance, the value name is written in full. The attribute name as a whole complies to Rule 049.
In the specific cases of BaseFrequency.frequency and BasePower.basePower, the new attribute names would be BaseFrequency.value and BasePower.value.