Chapter 9: Transforming Data to CIM

Example: CIM to PSS/E

An example of how MDT can be used is taking a real-world example of translating CIM RDF XML data into PSS/E RAW⁴² format⁴³ and looks at the high-level process involved in creating a CIM to PSS/E transform using MDT. PSS/E RAW is a space/comma delimited ASCII file format for bus-branch, balanced network data and, unlike the CIM, is not derived from an overall UML model (or if it is, the UML is not publicly available). As such, to create a CIM to PSS/E converter using MDT a number of steps are involved:

1. The PSS/E data structure must be derived to create a PSS/E meta-model
2. A parser for PSS/E RAW files must be written to create the format-agnostic data objects
3. A transform between the CIM classes and the PSS/E meta-model elements
4. A CIM to RDF XML serialization interface must be written to create the CIM RDF XML from the CIM data objects.

It is assumed that the CIM meta-model will be the UML (or a subset of the UML from the appropriate profile group).

Defining the PSS/E Meta-Model

Defining the PSS/E meta-model involves a reverse engineering of the format to determine the elements, attribute and associations. While some formats may provide a mechanism to automatically determine this meta-data (that is, extracting a database schema) with PSS/E the definition is primarily a manual task based on the comments and meta-data within the instance files (and if available, any documentation). With PSS/E there are a number of complex elements including: Bus, Branch, Transformer, Load, Generator and Shunt, as well as containment elements Area and Zone and the Owner element.

Unlike CIM there is no explicit inheritance so the direct mirror of the file format is to have a non-hierarchical class structure. Often during the creation of a meta-model, however, patterns emerge between classes (that is, multiple classes have a single association to a Bus or contain a name or ID attribute) and so a class hierarchy may be introduced to make the meta-model more elegant and remove duplication.

Associations in PSS/E are defined as index references to other classes (that is, a Load has a Bus index 1001 which corresponds to a Bus entry with ID 1001). In the meta-model these are instead defined as associations so that when the data is read into the format-agnostic objects the index references are resolved and become direct, in-memory associations (that is, pointers).

Parsing/Writing PSS/E RAW

The parsing of the files into memory is a case of identifying the format of the files then writing software that will read this format, creating the appropriate in-memory data object instances for each element from the processed data. Since PSS/E is an ASCII format a parser can be written in most programming languages.

The processing is generally a two-step process, creating all the objects and their attributes then resolving all the index references (since some elements refer to elements that are at the end of the file). Processing even large network models in this format can be accomplished very quickly.

Writing PSS/E data involves the processing of the in-memory data objects and serializing them to a file in the correct order and format. When the structure is derived from the file format serialization can be a relatively straightforward process; looping through each element and outputting the attributes in order.

More complex serialization rules are required to deal with associations (that is, knowing the correct index attribute to refer to) or dealing with fixed enumerations where the meta-model has human-readable names such as OutOfService or InService where the file is expecting the enumeration value of 0 or 1.

Transforming CIM to PSS/E

With the PSS/E meta-model defined and the CIM meta-model taken from the UML the transform is written against these meta-models. In some cases, there is simple one-to-one mapping, but in others more complex logic is required. Some examples of the transformation logic are shown below in QVTO (with well documented code to explain what is happening).

CIM EnergyConsumer to PSS/E Load

A relatively straightforward one-to-one mapping is that of the CIM’s EnergyConsumer to PSS/E Load as shown below.

Mapping CIM::IEC61970::Wires::EnergyConsumer:: getLoad() : PSSE::Load {
  -- Set the Bus to be the first (and only)
    -- Terminal’s Topological Node mapped to a PSSE:Bus
    result.Bus := self.Terminals->first().TopologicalNode.map getBus();
    result.id := self.name;
  
    var p : Real := 0.0;
    var q : Real := 0.0;
  
    -- If the EnergyConsumer’s Terminal has an SvPowerFlow associated
    -- with it then we use the values from it, otherwise we use the fixed
    -- real and reactive power values for the load
    if (self.Terminals->first().SvPowerFlow <> null) then{
       p := self.Terminals->first().SvPowerFlow.p;
       q := self.Terminals->first().SvPowerFlow.q;
    }else{
       if (self.isSet(“pfixed”)) then{ p := self.pfixed;}endif;
       if (self.isSet(“qfixed”)) then{ q := self.qfixed;}endif;
    }endif;
  
    -- If a LoadResponse is set then this load will have Constant, Current
    -- and Impedance components. The PSS/E values are thus set based on the
    -- total real/reactive power multiplied by the component
    -- (which should add to 1.0)
    if (self.LoadResponse <> null) then{
       if (not self.LoadResponse.exponentModel) then{
           Pmva := p * self.LoadResponse.pConstantPower;
           Qmva := q * self.LoadResponse.qConstantPower;
           Pcurrent := p * self.LoadResponse.pConstantCurrent;
           Qcurrent := q * self.LoadResponse.qConstantCurrent;
           Padmittance := p * self.LoadResponse.pConstantImpedance;
           Qadmittance := q * self.LoadResponse.qConstantImpedance;     
       }else{
           -- PSS/E cannot deal with the exponent model so set all as MVA 
           Pmva := p;
           Qmva := q;
     }endif;
    }else{
       -- If no LoadResponse is present then only the constant power is set
       Pmva := p;
       Qmva := q;   
    }endif;
  
  
  -- The PSS/E Area is mapped to the SubGeographicalRegion and the Zone to
    -- the GeographicalRegion
    result.Area := self.getSubGeographicalRegion().map getArea();
    result.Zone := self.getGeographicalRegion().map getZone();
  
    -- For Load’s with an OperatingShare the Owner becomes its OperatingParticipant
    -- ignoring any but the first as PSS/E supports only a single owner
    result.Owner := self.OperatingShare->first().
                      OperatingParticipant.map getOwner();
  
    -- The isConnected() helper function checks if the Terminal is connected
    -- and so sets the status  oolean accordingly
    status := self.isConnected();
}

As can be seen in this example, a number of other mapping functions are called to convert TopologicalNode to Bus and GeograpicalRegion to Zone amongst others. The association paths can be followed with a simple syntax so that the EnergyConsumer’s (self in this code as it is the source of the mapping) LoadResponseCharacteristic can be accessed via its LoadReponse association with the simple syntax self.LoadReponse with the internal LoadResponseCharacteristic attributes then accessed by appending them as self.LoadResponse.pConstantCurrent or self.LoadReponse.exponentModel.

SynchronousMachine to Generator

The mapping of generation is more complex as it as the CIM’s SynchronousMachine class may not be behaving as a generator so there are some initial conditions placed. This mapping is also a one-to-many as it may produce a PSS/E Generator and multiple PSS/E Owner Share elements.

Mapping CIM::IEC61970::Wires::SynchronousMachine:: getGen() : PSSE::Generator
    -- Only SynchronousMachines operating as a Generator with a GeneratingUnit
    -- or as a condenser without a GeneratingUnit are mapped to the PSS/E Generator
    when {
       (self.GeneratingUnit <> null and self.operatingMode = 
            CIM::IEC61970::Wires::SynchronousMachineOperatingMode::generator) or
       (self.GeneratingUnit = null and self.operatingMode = 
            CIM::IEC61970::Wires::SynchronousMachineOperatingMode::condenser)}{
  
    -- The Generator’s Bus is mapped to the SynchronousMachine’s Terminal’s
    -- TopologicalNode
    result.Bus := self.Terminals->first().TopologicalNode.map getBus();
    -- The PSS/E ID is mapped to the name 
    result.id := self.name;
  
  
-- If the SynchronousMachine has a RegulatingControl that controls Voltage
    -- The the regulating bus for the Generator must be set to the
    -- Bus the RegulatingControl is controlling (obtained via the TopologicalNode
    -- of the Terminal it is associated to) and the setpoint set to the
    -- RegulatingControl’s regulated set-point
    if (self.RegulatingControl <> null and self.RegulatingControl.mode = 
          CIM::IEC61970::Wires::RegulatingControlModeKind::voltage) then{
       var cBus := self.RegulatingControl.Terminal.TopologicalNode.map getBus();
       result.VregulatedSetpoint := self.RegulatingControl.targetValue/cBus.baseKV;
       if (cBus <> null and cBus <> result.Bus) then{
           result.Regulating := cBus;
       }endif;
    }endif;
  
    -- If a generator the Pgen, max and min values are taken from the GeneratingUnit
    if (self.GeneratingUnit <> null) then{
       Pgen := self.GeneratingUnit.nominalP;
       Pmax := self.GeneratingUnit.maxOperatingP;
       Pmin := self.GeneratingUnit.minOperatingP;
    }endif;
  
    -- If the ratedS is set that is taken as the base power for per-unit conversion
    -- otherwise the system base is used
    var mBase := sBase;
    if (self.isSet(“ratedS”)) then{ mBase := self.ratedS;}endif;
    MVAbase := mBase;
    -- The reactive power gen, max and min are taken from the SynchronousMachine
    Qgen := self.baseQ;
    Qmax := self.maxQ;
    Qmin := self.minQ;
    Rmachine := zToPerUnit(self.r, result.Bus.baseKV, mBase);
    Xmachine := zToPerUnit(self.x, result.Bus.baseKV, mBase);
  
    -- If the Terminal has an SvPowerFlow this is taken as being the actual
    -- power output of the machine. The values are multiplied by -1 as CIM’s
    -- representation of powerflow has a Load as positive and a Source as negative
    -- (in terms of direction of flow into or from the bus)
    if (self.Terminals->first().SvPowerFlow <> null) then{
       Pgen := self.Terminals->first().SvPowerFlow.p * -1;
       Qgen := self.Terminals->first().SvPowerFlow.q * -1;
    }endif;
  
    -- A PSS/E OwnerShare is created for each OperatingParticipant in the CIM.
    -- As such this mapping produces not only a PSS/E Generator but potentially
    -- multiple PSS/E OwnerShare elements
    self.OperatingShare->forEach(op){
       var share := object PSSE::OwnerShare{};
       share.Owner := op.OperatingParticipant.map getOwner();
       share.fraction := op.percentage/100;
       result.Owners := share;
    };
  
    -- The isConnected() helper function checks if the Terminal is connected
    -- and so sets the status  oolean accordingly
    result.status := self.isConnected();
}

This and the EnergyConsumer-Load mapping show that the mapping of the actual electrical parameters (load, generation) often form the minority of the transformation code. Dealing with the differences in structure can account for the majority of the effort and it is here that the code is both easier to write and maintain when it is written against the structure rather than trying to map CIM XML directly to PSS/E RAW in a single function.

Footnotes

⁴² PSS/E is a power system analysis tool from Siemens PTI that is widely used in the power industry. The PSS/E RAW format is its native file format.

⁴³ A.W. McMorran, G.W. Ault, I.M. Elders, C.E.T. Foote, G.M. Burt, J.R. McDonald, “Translating CIM XML Power System Data to a Proprietary Format for System Simulation”, IEEE Transactions on Power Systems, February 2004, Volume 19, Number 1, pp. 229-235.