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 See also:
CDPSM_to_GLM.main
, CIM User Group, CIM Profile and Queries for Feeder Modeling in GridLAB-D, GridLAB-D
Fields¶
mapSpacings¶
-
static HashMap<String, SpacingCount>
mapSpacings
¶ to look up line spacings by name
nsCIM¶
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¶
CFormat¶
Count_Phases¶
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¶
GLDCapMode¶
GLD_ID¶
GLD_Name¶
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¶
MergePhases¶
Phase_Kind_String¶
Phase_String¶
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¶
SafeProperty¶
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