ODM XML Schema Specification

Introduction

The Open Model for Exchanging Power System Simulation Data (ODM) schema is formally defined in this document. The ODM Schema is based on XM Schema standard published by W3C. Eclipse, an open-source free IDE, is used to create and edit the schema. The schema and its associated Java API library are hosted at the InterPSS Project on Github, open and freely accessible.

Please Note: The ODM Schema is still under development. Therefore the information presented here might be not 100% accurate. We intend to make regular updates to make it as currently as possible.

ODM Schema File Location

ODM Schema currently is hosted at InterPSS Github Code repository and the ODMSchema.xsd is the main schema file.

Naming Convention

There is two main XML data structures used in ODM, in addition to standard data types defined in XML schema.

    • Complex Type : <...>XmlType, is for defining complex data structure with different types of attributes and elements, for example, PSSNetworkXmlType. Complex type always ends "XmlType".
    • Simple Type : <...>EnumType of String is for defining enumeration of simple tokens, for example, LFGenCodeEnumType has [Swing, PV, PQ]. Simple type of string always ends with "EnumType".
    • Unit Type : <...>UnitType is special simple type for defining unit. for example, ApparentPowerUnitType has [Mva, Kva ...].

Name Space

The ODM Schema target namespace is "http://www.ieee.org/odm/Schema/2008". All types defined in the ODM Schema are "qualified" with a namespace prefix pss.

<schema xmlns="http://www.w3.org/2001/XMLSchema"

targetNamespace="http://www.ieee.org/odm/Schema/2008"

xmlns:pss="http://www.ieee.org/odm/Schema/2008"

elementFormDefault="qualified">

...

<element name="PSSStudyCase" type="pss:StudyCaseXmlType"></element>

...

</schema>

Please see Namespaces in XML for more in depth discussion about namespace.

Version Number

The Schema root element type StudyCaseXmlType has a attribute schemaVersion for indicating schema version number.

PU System

Actual units, such as KV, MVA, and PU could be used in the ODM Model. All PU values in the model are based on the base case base Kva and bus base voltage, unless otherwise specified.

Extension

ODM is designed to be extended. The extension folder is for ODM extension by any interested party. Currently, it has a folder containing extension by InterPSS. The following namespace has been introduced in InterPSS extension.

xmlns:ipss="http://www.interpss.org/Schema/odm/2008"

Schema Root Element

The ODM schema root element PSSStudyCase is of type StudyCaseXmlType.

<schema xmlns="http://www.w3.org/2001/XMLSchema" ...>

<element name="PSSStudyCase" type="pss:StudyCaseXmlType"></element>

...

</shema>

The StudyCaseXmlType has the following elements:

    • schemaVersion - version number
    • originalFormat - [ IEEE-CDF | PSS-E | UCTE-DEF | InterPSS| PSAT | Custom ] original data format.
    • adapterProviderName - optional, data transformation adapter provider name
    • adapterProviderVersion - optional, data transformation adapter provider version
    • analysisCategory - [ Loadflow | ShortCircuit | TransientStability ] analysis type category. This could be expended to include more types in the future schema version
    • networkCategory - [ Transmission |Distribution ] network type category.
    • baseCase - element of type PSSNetworkXmlType for describing a power network as the base case.
    • modificationList - optional, a list of modification to the base case
    • scemarioList - optional, a list of scenarios, built on the base case.

Base Record

The information are organized in the Schema using the record concept.

    • name - Optional, element name
    • desc - Optional, element description
    • isoCode - Optional, element ISO code
    • offLine - Optional, element actual off-line status
    • normalOffLineStatus - Optional, normal element off-line status
    • number - Optional, element number
    • area - Area number. It is optional and should be a non-zero number.
    • zone - Zone number. It is optional and should be a non-zero number.
    • ownerList - Optional, owner list of the element
    • nvPairList - Optional, name value pair for those elements not defined in the schema
    • extension - Optional, extension point. One can add an element of Any type (any schema type) to extend the schema.

ID Record

A ID record has an id of Type xsd:ID, which guarantees its uniqueness in an ODM xml file. It is the parent of all searchable records, such BusRecord, BranchRecord.

Base Case

The base case element is of type PSSNetworkXmlType. It is intend to describe a power network for simulation purpose. Currently, it our focus is on Loadflow study information. The structure has been designed in such a way that it could be extended to include more simulation information, such as short circuit, transient stability.

    • baseKva - Base kva for the PU system.
    • baseKvaUnit - [ KVA | MVA ] base kav unit
    • busList - network bus record list
    • branchList - network branch record list
    • loseZoneList - lose zone list per IEEE CDF. It may be extended to cover other formats
    • interchangeList - interchange list per IEEE CDF. It may be extended to cover other formats
    • tieLineList - tie line list per IEEE CDF. It may be extended to cover other formats

Bus Record

Bus record has a unique id and a set of attributes inherited from the BaseRecordXmlType. It also holds bus related simulation data. Now it only covers Loadflow study information. It will be extended to cover other simulation concepts, such as short circuit.

    • baseVoltage - Bus base voltage
    • baseVoltageUnit - [ VOLT | KV] Bus base voltage unit
    • loadflowBusData - Bus loadflow data

Bus Loadflow Data

By analysis different data formats, we believe the above bus model captured all possible permutations of a local bus model for loadflow analysis purpose. Bus generation Q some times is used to control voltage of a remote bus.

Bus Loadflow data is described by the LoadflowBusDataXmlType.

    • voltage - Bus voltage
    • angle - Bus angle
    • genData - Bus generation data, see more description below
    • loadData - Bus load data, see more description below
    • shuntY - Bus shunt Y
    • powerInjection - power injection into the network, for store Loadflow results

Generation Loadflow Data

    • code - [ PQ, PV, SWING ]
    • gen - generation, p, q plus a unit [ PU | KVA | MVA ]
    • qGenLimit - generator reactive power limit, used for PV bus
    • vGenLimit - generator voltage limit
    • desiredRemoteVoltage - describing desired remote bus voltage when the generator Q is used to control the remote bus voltage.

Load Data

    • code - [ CONST_P, CONST_I, CONST_Z ] constant power, constant current or constant z load.
    • load - load, p, q plus a unit

Remote Voltage Adjustment

Some times, generator Q is used to control voltage of a remote bus, for example, the high-voltage side of generator output transformer.

    • desiredVoltage - desired voltage at the remote bus.
    • remoteBus - reference to the remote bus

Branch Record

Branch record has an unique id, an id reference to a from bus record, an id reference to a to bus record, a circuit id, and a set of attributes inherited from the BaseRecordXmlType. The tereiayBus is optional, which could be used to define a 3-winding transformer. It also holds branch related simulation data. Now it only covers Loadflow study information. It will be extended to cover other simulation concepts, such as short circuit.

Loadflow Branch Data

Branch Loadflow data is described by the LoadflowBranchDataXmlType.

    • code - [ Line | Transformer | PhaseShiftXformer ] branch code, currently support line, transformer, phase-shifting transformer. More types will be added in the future.
    • lineData - Transmission line data, see more below
    • xformerData - Transformer data, see more below
    • phaseShiftXfrData - Phase shifting transformer data, see more below
    • ratingLimit - Branch MVar and current rating limits, see more below

Loadflow Line Data

By analysis different data formats, we believe the above line model captured all possible permutations of a local transmission model for loadflow analysis purpose.

    • z - line impedance, r, x, plus a unit [ PU | OHM ]
    • totalShuntY - total line charging shunt Y, g, b, plus a unit [ PU | MHO | MICROMHO ]
    • fromShuntY - extra shunt Y at the from bus end of the line
    • toShuntY - extra shunt Y at the to bus end of the line

Loadflow Transformer Data

By analysis different data formats, we believe the above transformer model captured all possible permutations of a local transformer or a logical phase-shift transformer model for loadflow analysis purpose. Adjustment could be applied to transformer tap to adjust bus voltage or Mvar flow, or to phase-shifting transformer angle to adjust Mw flow.

Transformer Data

    • z - transformer impedance, r, x, plus a unit [ PU | Ohm ].
    • ratingData - transformer rating data. Voltage unit should be VOLT or KV and the same for both side.
    • fromTurnRatio - PU based on the transformer rated voltage
    • toTurnRatio - PU based on the transformer rated voltage
    • fromShuntY - From side shunt Y, g, b, plus a unit [ PU | Mho | MicroMho ].
    • toShuntY - To side shunt Y, g, b, plus a unit [ PU | Mho | MicroMho ].
    • tapAdjustment - transformer tap adjustment info, see more below.

In the transformer data schema definition, only transformer impedance z are required elements. The fromTurnRation and toTurnRatio should be set to 1.0 if not defined. The other optional elements should be set to zero if not specified.

Please Note: When transformer Z and Y are specified in actual value, in Ohm or Mho, the side where the value is measured need to be specified. ODM assumes that the value is measured at the high voltage side.

Transformer Tap Adjustment

    • adjustmentType - [ Voltage | MvarFlow ] tap adjustment type, voltage adjustment or mvar flow adjustment
    • tapLimit - tap limit
    • tapLimitUnit - [ PU | PERCENT ] tap limit unit
    • tapAdjStepSize - tap adjustment step size. If 0.0 or not defined, assume continuous adjustment
    • tapAdjOnFromSide - Turn ratio at from side or to side could be adjusted.
    • voltageAdjData - voltage adjustment data, see more below
    • mvarFlowAdjData - mvar flow adjustment data, see more below.

Transformer Tap Adjustment for Bus Voltage

    • mode - [ ValueAdjustment | RangeAdjustment ] adjustment could be based on a desired value or desired range.
    • desiredValue - desiredValue for desired bus voltage for the ValueAdjustment
    • desiredRange - desiredRange for desired bus voltage range for the RangeAdjustment
    • desiredVoltageUnit - desired voltage unit [ PU | Volt | KV ]
    • adjVoltageBus - adjustment voltage
    • adjBusLocation - [ TerminalBus | NearFromBus | NearToBus | FromBus | ToBus ] adjustment bus location

Transformer Tap Adjustment for MVar Flow

    • mode - [ ValueAdjustment | RangeAdjustment ] adjustment could be based on a desired value or desired range.
    • desiredValue - desiredValue for desired mvar flow for the ValueAdjustment
    • desiredRange - desiredRange for desired mvar flow range for the RangeAdjustment
    • desiredMvarFlowUnit - desired mvar unit [ PU | KVAR | MVAR ]
    • mvarMeasuredOnFromSide - describing mvar measuring location, from bus side or to bus side

Loadflow PhaseShift Transformer Data

PhaseShift transformer inherits from transformer. In addition it has the following fields

    • fromAngle - from bus side angle
    • toAngle - to bus side angle
    • angleAdjustment - phase shifting angle adjustment to control MW flow.

Phase Angle Adjustment

    • mode - [ ValueAdjustment | RangeAdjustment ] adjustment could be based on a desired value or desired range.
    • desiredValue - desiredValue for desired MW flow for the ValueAdjustment
    • desiredRange - desiredRange for desired MW flow range for the RangeAdjustment
    • angleDegLimit - phase shifting angle limit in degrees
    • desiredPowerUnit - [ PU | KW | MW ] desired MW flow unit
    • desiredMeasuredOnFromSide - desired MW flow measured on from bus or to bus side

Branch Rating Limit

Three mva rating limits and a current rating limit could be defined

    • mvaRating1 - branch mva rating limit
    • mvaRating2 - branch mva rating limit
    • mvaRating3 - branch mva rating limit
    • currentRating - branch current rating limit
    • mvaRatingUnit - [ PU | KVA | MVA ] branch mva rating limit unit
    • currentRatingUnit - [ PU | Amp | KA ] current rating limit unit

Modification

A list of modifications could be defined in a StudyCase, as shown in the following figure:

The modification element is of type ModifyRecordXmlType, which is abstract. In actual application, it needs to be replaced with a concrete Xml type, for example, the NetModificationXmlType, in the following figure:

Contingency

In contingency analysis, there is a need to define a list of contingencies which might be applied to the base case. Here we present one possible ways to define contingencies.

    • A contingency could be described as a set of branch offline status changes;
    • A modification of type NetModificaitonXmlType could be defined to represent a contingency;
    • A StudyCase XML file could contain a list of modifications for contingency analysis

Study Scenario

A studyScenario could be defined in a StudyCase, as shown in the following figure: