CDPSM_to_GLM¶

public class CDPSM_to_GLM¶

This class converts CIM (IEC 61968) RDF to GridLAB-D format

The general pattern is to retrieve iterators on the different types of objects (e.g. ACLineSegment) through simple SPARQL queries. Usually these iterators include just the mrID, or the mrID and name. Then Jena RDF model and resource functions are used to pull other properties from iterated objects, writing GridLAB-D input along the way. A future version will rely more heavily on SPARQL queries to do the selection and filtering, as the preferred pattern for developers working with CIM. In existing code, the EnergySource most closely follows this new preferred pattern.

Invoke as a console-mode program

Author:	Tom McDermott

Fields¶

baseURI¶

static final String baseURI¶: identifies gridlabd

mapNodes¶

static HashMap<String, GldNode> mapNodes¶: to look up nodes by name

mapSpacings¶

static HashMap<String, SpacingCount> mapSpacings¶: to look up line spacings by name

neg120¶

static final Complex neg120¶: Rotates a phasor -120 degrees by multiplication

nsCIM¶

static final String nsCIM¶: namespace for CIM; should match the CIM version used to generate the RDF

nsRDF¶

static final String nsRDF¶: namespace for RDF

pos120¶

static final Complex pos120¶: Rotates a phasor +120 degrees by multiplication

ptBaseNomV¶

Property ptBaseNomV¶

ptEqBaseV¶

Property ptEqBaseV¶

ptEquip¶

Property ptEquip¶

ptLevBaseV¶

Property ptLevBaseV¶

Methods¶

AccumulateLoads¶

static boolean AccumulateLoads(GldNode nd, String phs, double pL, double qL, double Pv, double Qv, double Pz, double Pi, double Pp, double Qz, double Qi, double Qp)¶

Distributes a total load (pL+jqL) among the phases (phs) present on GridLAB-D node (nd)

Parameters:

nd – GridLAB-D node to receive the total load
phs – phases actually present at the node
pL – total real power
qL – total reactive power
Pv – real power voltage exponent from a CIM LoadResponseCharacteristic
Qv – reactive power voltage exponent from a CIM LoadResponseCharacteristic
Pz – real power constant-impedance percentage from a CIM LoadResponseCharacteristic
Qz – reactive power constant-impedance percentage from a CIM LoadResponseCharacteristic
Pi – real power constant-current percentage from a CIM LoadResponseCharacteristic
Qi – reactive power constant-current percentage from a CIM LoadResponseCharacteristic
Pp – real power constant-power percentage from a CIM LoadResponseCharacteristic
Qp – reactive power constant-power percentage from a CIM LoadResponseCharacteristic

Returns:

always true

Bus_ShuntPhases¶

static String Bus_ShuntPhases(String phs, String conn)¶

appends N or D for GridLAB-D loads and capacitors, based on wye or delta connection

Parameters:	phs – from CIM PhaseCode conn – contains w for wye connection and d for delta connection
Returns:	phs with N or D possibly appended

CFormat¶

static String CFormat(Complex c)¶

Parameters:	c – complex number
Returns:	formatted string for GridLAB-D input files with ‘j’ at the end

Count_Phases¶

static int Count_Phases(String phs)¶

from the phase string, determine how many are present, but ignore D, N and S

Parameters:	phs – the parsed CIM PhaseCode
Returns:	(1..3)

FindBaseVoltage¶

static double FindBaseVoltage(Resource res, Property ptEquip, Property ptEqBaseV, Property ptLevBaseV, Property ptBaseNomV)¶

Returns the nominal voltage for conduction equipment, from either its own or container’s base voltage. For example, capacitors and transformer ends have their own base voltage, but line segments don’t.

Parameters:

res – an RDF resource corresponding to a ConductingEquipment instance; we need to find its base voltage
ptEquip – an RDF property corresponding to the EquipmentContainer association
ptEqBaseV – an RDF property corresponding to a possible BaseVoltage association on the equipment itself
ptLevBaseV – an RDF property corresponding to the EquipmentContainer’s BaseVoltage association
ptBaseNomV – an RDF property corresponding to the nominalVoltage attribute of a CIM BaseVoltage

Returns:

the nominal voltage as found from the equipment or its container, or 1.0 if not found

FindConductorAmps¶

static String FindConductorAmps(Model mdl, Resource res, Property ptDataSheet, Property ptAmps)¶

needs to return the current rating for a line segment ‘res’ that has associated WireInfo at ‘ptDataSheet’, which in turn has the current rating at ptAmps

TODO - this is not implemented; emitted syntax is for OpenDSS and the function call (below, in main) needs review

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file res – an RDF resource corresponding to a CIM ACLineSegment ptDataSheet – an RDF property corresponding to CIM AssetDatasheet attribute ptAmps – an RDF property corresponding to CIM ratedCurrent attribute
Returns:	unusable OpenDSS input

FirstPhase¶

static String FirstPhase(String phs)¶

Parameters:	phs – a parsed CIM PhaseCode
Returns:	the first phase found as A, B, or C

GLDCapMode¶

static String GLDCapMode(String s)¶

translate the capacitor control mode from CIM to GridLAB-D

Parameters:	s – CIM regulating control mode enum
Returns:	MANUAL, CURRENT, VOLT, VAR

GLD_ID¶

static String GLD_ID(String arg)¶

parse the GridLAB-D name from a CIM name, based on # position

Parameters:	arg – the CIM IdentifiedObject.name attribute, not the mrID
Returns:	the compatible name for GridLAB-D

GLD_Name¶

static String GLD_Name(String arg, boolean bus)¶

convert a CIM name to GridLAB-D name, replacing unallowed characters and prefixing for a bus/node

Parameters:	arg – the root bus or component name, aka CIM name bus – to flag whether nd_ should be prepended
Returns:	the compatible name for GridLAB-D

GetACLineParameters¶

static String GetACLineParameters(Model mdl, String name, Resource r, double len, double freq, String phs, PrintWriter out)¶

for a standalone ACLineSegment with sequence parameters, find GridLAB-D formatted and normalized phase impedance matrix

TODO - this is always three-phase, so we don’t need all 7 variations from GetSequenceLineConfigurations

Parameters:

mdl – an RDF model (set of statements) read from the CIM imput file
name – the root name of the line segment and its line_configuration
r – an RDF resource corresponding to a CIM ACLineSegment
len – the length of the ACLineSegment in feet
freq – frequency in Hz for converting susceptance to capacitance
phs – phasing for the written line_configuration (one of 7 variations) that needs to be referenced
out – the PrintWriter instance opened from the main program, passed here so that we can share code in GetSequenceLineConfigurations

Returns:

the name of the written line_configuration

GetBusName¶

static String GetBusName(Model mdl, String eq_id, int seq)¶

finds the bus (ConnectivityNode) name for conducting equipment

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file* eq_id – the CIM mrID of the conducting equipment seq – equals 1 to use the first terminal found, or 2 to use the second terminal found
Returns:	the GridLAB-D compatible bus name, or x if not found. As Terminals no longer have sequence numbers, the ordering of seq is unpredictable, so if there are two we can get bus 1 - bus 2 or bus 2 - bus 1

GetBusPositionString¶

static String GetBusPositionString(Model mdl, String id)¶

for a bus (ConnectivityNode), search for X,Y geo coordinates based on connected Terminals and equipment

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file id – name of the bus to search from
Returns:	X,Y coordinates in comma-separated value (CSV) format

GetCableData¶

static String GetCableData(Model mdl, Resource res)¶

needs to return underground_line_conductor data in GridLAB-D format

TODO - this is not implemented; the emitted syntax is actually for OpenDSS

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file res – an RDF resource corresponding to a CIM CableInfo (not a leaf/concrete class)
Returns:	unusable OpenDSS input

GetCapControlData¶

static String GetCapControlData(Model mdl, Resource rCap, Resource ctl)¶

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file rCap – an RDF resource corresponding to a CIM LinearShuntCompensator (aka capacitor) ctl – an RDF resource corresponding to the CIM RegulatingControl that was found attached to the LinearShuntCompensator
Returns:	the embedded capacitor control data for a GridLAB-D capacitor object

GetEquipmentType¶

static String GetEquipmentType(Resource r)¶

find the type of monitored equipment for controlled capacitors, usually a line or the capacitor itself

Parameters:	r – an RDF resource, will have a CIM mrID, should be a LinearShuntCompensator, ACLineSegment, EnergyConsumer or PowerTransformer
Returns:	cap, line, xf if supported in GridLAB-D; NULL or ##UNKNOWN## if unsupported

GetGldTransformerConnection¶

static String GetGldTransformerConnection(String[] wye, int nwdg)¶

Map CIM connectionKind to GridLAB-D winding connections. TODO: some of the returnable types aren’t actually supported in GridLAB-D

Parameters:	wye – array of CIM connectionKind attributes per winding nwdg – number of transformer windings, also the size of wye
Returns:	the GridLAB-D winding connection. This may be something not supported in GridLAB-D, which should be treated as a feature request

GetImpedanceMatrix¶

static String GetImpedanceMatrix(Model mdl, String name, Property ptCount, Resource r, boolean bWantSec)¶

Convert CIM PerLengthPhaseImpedance to GridLAB-D line_configuration

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file name – root name of the line_configuration(s), should be the CIM name r – an RDF resource, will have a CIM mrID, should be PerLengthPhaseImpedance ptCount – an RDF property for the PerLengthPhaseImpedance.conductorCount bWantSec – flags the inclusion of triplex, true except for debugging
Returns:	the GridLAB-D formatted impedance matrix for a line configuration. We have to write 3 of these in the case of 1-phase or 2-phase matrices. If (by name) it appears to be triplex and bWantSec is false, nothing will be returned.

GetLineSpacing¶

static String GetLineSpacing(Model mdl, Resource rLine)¶

needs to return the line_spacing and wire/cncable/tscable assignments for this rLine in GridLAB-D format

TODO - this is not implemented, the emitted syntax is actually for OpenDSS

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file rLine – an RDF resource corresponding to a CIM ACLineSegment that should have an associated AssetInfo
Returns:	unusable OpenDSS input

GetMatIdx¶

static int GetMatIdx(int n, int row, int col)¶

converts the [row,col] of nxn matrix into the sequence number for CIM PerLengthPhaseImpedanceData (only valid for the lower triangle) *

Parameters:	n – 2x2 matrix order row – first index of the element col – second index
Returns:	sequence number

GetPowerTransformerData¶

static String GetPowerTransformerData(Model mdl, Resource rXf)¶

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file rXf – an RDF resource corresponding to CIM PowerTransformer; it should have mesh impedance data
Returns:	transformer and transformer_configuration objects in GridLAB-D format

GetPowerTransformerTanks¶

static String GetPowerTransformerTanks(Model mdl, Resource rXf, ResIterator itTank, boolean bWantSec)¶

writes a PowerTransformer in GridLAB-D format, in the case where individual tranformer tanks that are connected together in a bank. GridLAB-D supports only 2-winding banks with same phasing on both sides, or single-phase, center-tapped secondary transformers.

Parameters:

mdl – an RDF model (set of statements) read from the CIM imput file
rXf – an RDF resource corresponding to a CIM PowerTransformer that uses tank modeling
itTank – a Jena iterator on the tanks associated with rXf, known to be non-empty before this function is called
bWantSec – usually true, in order to include single-phase, center-tapped secondary transformers, which would come to this function

Returns:

transformer object in GridLAB-D format; the transformer_configuration comes from calling GetXfmrCode

GetPropValue¶

static String GetPropValue(Model mdl, String uri, String prop)¶

unprotected lookup of uri.prop value, to be deprecated in favor of SafeProperty

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file uri – an RDF resource, currently only an EquipmentContainer is used, and it should always exist prop – currently only IdentifiedObject.name is used, and it should always exist
Returns:	the name of the CIM object

GetRegulatorData¶

static String GetRegulatorData(Model mdl, Resource rXf, String name, String xfGroup, String bus1, String bus2, String phs)¶

Connects a regulator in GridLAB-D format between bus1 and bus2; should be called from GetPowerTransformerTanks. In CIM, a regulator consists of a transformer plus the ratio tap changer, so if such is found, should call GetRegulatorData instead of just writing the transformer data in GetPowerTransformerTanks. Any impedance in the regulating transformer will be lost in the GridLAB-D model. Should be called from PowerTransformers that have RatioTapChangers attached, so we know that lookup will succeed

TODO: implement regulators for tank transformers

Parameters:

mdl – an RDF model (set of statements) read from the CIM imput file
rXf – an RDF resource corresponding to a CIM PowerTransformer that has a RatioTapChanger associated
name – the name of the PowerTransformer (already looked up before calling this function)
xfGroup – the PowerTransformer’s IEC vector group (already looked up before calling this function)
bus1 – first bus (ConnectivityNode) on the regulator (already looked up before calling this function)
bus2 – second bus (ConnectivityNode) on the regulator (already looked up before calling this function)
phs – phases that contain A, B and/or C (already looked up before calling this function)

Returns:

regulator and regulator_configuration objects in GridLAB-D format

GetSequenceLineConfigurations¶

static String GetSequenceLineConfigurations(String name, double sqR1, double sqX1, double sqC1, double sqR0, double sqX0, double sqC0)¶

For balanced sequence impedance, return a symmetric phase impedance matrix for GridLAB-D. We have to write 7 variations to support all combinations of 3, 2 or 1 phases used.

Parameters:	name – is the root name for these 7 variations sqR1 – positive sequence resistance in ohms/mile sqX1 – positive sequence reactance in ohms/mile sqC1 – positive sequence capacitance in nF/mile sqR0 – zero sequence resistance in ohms/mile sqX0 – zero sequence reactance in ohms/mile sqC0 – zero sequence capacitance in nF/mile
Returns:	text for 7 line_configuration objects

GetWdgConnection¶

static String GetWdgConnection(Resource r, Property p, String def)¶

parse the CIM WindingConnection enumeration

Parameters:	r – an RDF resource, will have a CIM mrID, should be a transformerEnd p – an RDF property, will be a CIM attribute, should be connectionKind def – default value if property is not found, such as Y
Returns:	D, Y, Z, Yn, Zn, A or I

GetWireData¶

static String GetWireData(Model mdl, Resource res)¶

needs to return overhead_line_conductor data in GridLAB-D format; res is the CIM OverheadWireInfo instance

TODO - this is not implemented; the emitted syntax is actually for OpenDSS

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file res – an RDF resource corresponding to CIM OverheadWireInfo
Returns:	unusable OpenDSS input

GetXfmrCode¶

static String GetXfmrCode(Model mdl, String id, double smult, double vmult, boolean bWantSec)¶

Translates a single TransformerTankInfo into GridLAB-D format. These transformers are described with short-circuit and open-circuit tests, which sometimes use non-SI units like percent and kW, as they appear on transformer test reports.

TODO: smult and vmult may be removed, as they should always be 1 for valid CIM XML

Parameters:

mdl – an RDF model (set of statements) read from the CIM imput file
id – CIM mRID corresponding to a CIM TransformerTankInfo
smult – scaling factor for converting winding ratings to volt-amperes (should be 1)
vmult – scaling factor for converting winding ratings to volts (should be 1)
bWantSec – usually true to include single-phase, center-tapped secondary tranformers, which come to this function

Returns:

transformer_configuration object in GridLAB-D format

GldPrefixedNodeName¶

static String GldPrefixedNodeName(String arg)¶

prefix all bus names with nd_ for GridLAB-D, so they “should” be unique

Parameters:	arg – the root bus name, aka CIM name
Returns:	nd_arg

MergePhases¶

static String MergePhases(String phs1, String phs2)¶: accumulate phases without duplication

Phase_Kind_String¶

static String Phase_Kind_String(String arg)¶

parses a single phase from CIM SinglePhaseKind

Parameters:	arg – CIM SinglePhaseKind enum
Returns:	A, B, C, N, s1 or s2

Phase_String¶

static String Phase_String(String arg)¶

parses the phase string from CIM phaseCode

Parameters:	arg – CIM PhaseCode enum
Returns:	some combination of A, B, C, N, s1, s2, s12

SafeBoolean¶

static boolean SafeBoolean(Resource r, Property p, boolean def)¶

look up Jena boolean value

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	boolean value, or default if not found

SafeDouble¶

static double SafeDouble(Resource r, Property p, double def)¶

look up Jena double value

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	double value, or default if not found

SafeInt¶

static int SafeInt(Resource r, Property p, int def)¶

look up Jena integer value

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	integer value, or default if not found

SafePhasesX¶

static String SafePhasesX(Resource r, Property p)¶

look up Jena phase property

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute
Returns:	phases in string format, or ABCN if not found

SafeProperty¶

static String SafeProperty(Resource r, Property p, String def)¶

look up Jena string property

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	the property (or default value) as a string

SafeRegulatingMode¶

static String SafeRegulatingMode(Resource r, Property p, String def)¶

parse the CIM regulating control mode enum

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	voltage, timeScheduled, reactivePower, temperature, powerFactor, currentFlow, userDefined

SafeResName¶

static String SafeResName(Resource r, Property p)¶

for components (not buses) returns the CIM name from r.p attribute if it exists, or the r.mrID if not, in GridLAB-D format

Parameters:	r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute
Returns:	a name compatible with GridLAB-D

SafeResourceLookup¶

static String SafeResourceLookup(Model mdl, Property ptName, Resource r, Property p, String def)¶

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file ptName – should be the IdentifiedObject.Name property of the resource we are looking for r – an RDF resource, will have a CIM mrID p – an RDF property, will be a CIM attribute def – default value if property is not found
Returns:	the GridLAB-D formatted name of a resource referenced by r.p

Shunt_Delta¶

static boolean Shunt_Delta(Resource r, Property p)¶

for loads and capacitors, returns true only if CIM PhaseShuntConnectionKind indicates delta

Parameters:	r – an RDF resource, will have a CIM mrID, should be LinearShuntCompensator or EnergyConsumer p – an RDF property, will be a CIM attribute for phaseConnection
Returns:	true if delta connection

WirePhases¶

static String WirePhases(Model mdl, Resource r, Property p1, Property p2)¶

Returns GridLAB-D formatted phase string by accumulating CIM single phases, if such are found, or assuming ABC if not found. Note that in CIM, secondaries have their own phases s1 and s2. *

Parameters:	mdl – an RDF model (set of statements) read from the CIM imput file r – an RDF resource, will have a CIM mrID, should be something that can have single phases attached p1 – an RDF property, will be a CIM attribute, should associate from a single phase back to r p2 – an RDF property, will be a CIM attribute, should be the single phase instance’s phase attribute
Returns:	concatenation of A, B, C, s1 and/or s2 based on the found individual phases

main¶

public static void main(String[] args)¶

Reads command-line input for the converter

Parameters:	args – will be CDPSM_to_GLM [options] input.xml output_root
Throws:	java.io.FileNotFoundException – if the CIM RDF input file is not found

Options:

-l={0..1} load scaling factor, defaults to 1

-t={y|n} triplex; y/n to include or ignore secondaries. Defaults to yes. Use no for debugging only, as all secondary load will be ignored.

-e={u|i} encoding; UTF-8 or ISO-8859-1. No default, so this should be specified. Choose ‘u’ if the CIM file came frome OpenDSS.

-f={50|60} system frequency; defaults to 60

-v={1|0.001} multiplier that converts CIM voltage to V for GridLAB-D; defaults to 1

-s={1000|1|0.001} multiplier that converts CIM p,q,s to VA for GridLAB-D; defaults to 1

-q={y|n} are unique names used? If yes, they are used as unique GridLAB-D names. If no, the CIM mrID is de-mangled to create a unique GridLAB-D name, but this option is only implemented for ACLineSegments as written to some earlier GIS profiles.

-n={schedule_name} root filename for scheduled ZIPloads (defaults to none)

-z={0..1} constant Z portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)

-i={0..1} constant I portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)

-p={0..1} constant P portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)

Example: java CDPSM_to_GLM -l=1 -e=u -i=1 ieee8500.xml ieee8500

Assuming Jena and Commons-Math are in Java’s classpath, this will produce two output files:

ieee8500_base.glm with GridLAB-D components for a constant-current model at peak load. This file includes an adjustable source voltage and manual capacitor/tap changer states. It should be invoked from a separate GridLAB-D file that sets up the clock, solver, recorders, etc. For example, these two GridLAB-D input lines set up 1.05 per-unit source voltage on a 115-kV system:
- #define VSOURCE=69715.065 // 66395.3 * 1.05
- #include “ieee8500_base.glm”
If there were capacitor/tap changer controls in the CIM input file, that data was written to ieee8500_base.glm as comments, which can be recovered through manual edits.
ieee8500_busxy.glm with bus geographic coordinates, used in GridAPPS-D but not GridLAB-D

Cautions: this converter does not yet implement all variations in the CIM for unbalanced power flow.

AssetInfo links to WireSpacing, OverheadWireInfo, ConcentricNeutralCableInfo and TapeShieldCableInfo
PerLengthSequenceImpedance has not been tested
Capacitor power factor control mode - not in GridLAB-D
Capacitor user-defined control mode - not in GridLAB-D
Capacitor controlled by load (EnergyConsumer) - need to name loads
Line ratings for PerLengthImpedance
Dielectric constant (epsR) for cables - not in CIM
Soil resistivity (rho) for line impedance - not in CIM
Multi-winding transformers other than centertap secondary-not in GridLAB-D
Unbalanced transformer banks - not in GridLAB-D
Autotransformers have not been tested
schedule_name implemented for secondary loads only, primary loads to be done
Fuse not implemented
Breaker not implemented
Jumper not implemented
Disconnector not implemented

Throws:	java.io.UnsupportedEncodingException – if the UTF encoding flag is wrong

See also: CDPSM_to_GLM