API Reference

First import emthub.api as emthub, then invoke a function like emthub.print_cim_summaries([filename_roots])

api

Functions intended for public access.

Example

To show print CIM summaries interface:

import emthub.api as emthub
emthub.print_cim_summaries(['XfmrSat','IEEE39','IEEE118','WECC240','SMIBDLL'])

Public Functions:

add_ibr_plant:: Add an IBR plant with attributes and a DLL interface.
adhoc_sparql_dict:: Load the result of a user-written SPARQL query into a Python dictionary.
build_bus_lists:: Order the buses (connectivity nodes) sequentially.
build_system_graph:: Auto-layout a diagram of the CIM network, returning a networkx graph.
create_atp:: Write an ATP netlist from CIM loaded into a Python dictionary.
create_cim_rdf:: Create RDF in TTL/XML formats from results of load_psse_rawfile.
create_cim_sql:: Create SQL db from results of load_psse_rawfile.
create_matpower:: Write a MATPOWER netlist from CIM loaded into a Python dictionary.
extract_case:: Copy example files for one case into the current directory.
get_dll_interface:: Returns a Python dictionary of the interface to an IEEE/Cigre DLL.
get_swingbus_id:: Find the CIM ConnectivityNode ID by matching the Name/Number from the original raw file.
list_cases:: List the names and descriptions of examples provided with the package.
load_detailed_model_types:: Load the library of detailed dynamic models with parameter descriptors.
list_dict_table:: Print the fields and attributes of a Python dictionary loaded from SPARQL.
load_dynamics_defaults:: Load example default settings for dynamics into a Python dictionary.
load_dynamics_mapping:: Load a dictionary of CIM classes and attributes corresponding to dyr file contents.
load_emt_dict:: Load an RDF graph into Python dictionary using packaged SPARQL queries.
load_ic_dict:: Load an RDF graph into Python dictionary from standalone power flow solution file.
load_psse_dyrfile:: Load contents of a PSSE dyrfile into a Pandas dataframe.
load_psse_meta:: Load PSSE rawfile metadata into a Python dictionary.
load_psse_rawfile:: Load contents of a PSSE rawfile into a Python dictionary.
load_system_graph:: Load the networkx layout (graph) from a JSON file.
match_dyr_generators:: Collect dyrfile models from Pandas dataframe into a Python dictionary by generator name/id.
plot_system_graph:: Plot the transmission system topology from a networkx layout (graph).
print_cim_summaries:: Print class names and counts found in list of Turtle files.
print_psse_table:: Print a named dictionary loaded from section of a PSSE rawfile.
print_solution_summary:: Prints a summary of solved MATPOWER case to console.
read_matpower_casefile:: Read a MATPOWER m file into Python dictionary.
run_matpower_and_wait:: Runs MATPOWER from command line on Windows, Mac, or Linux.
save_system_graph:: Save the networkx layout (graph) to a JSON file.
summarize_casefile:: Report the table sizes, total load, and total generation in a loaded MATPOWER case file.
summarize_graph:: Count the class instances by namespace in an RDF graph.
summarize_psse_dyrfile:: Enumerate contents of a loaded PSSE dyrfile dataframe.
write_atp_dll_interface:: Netlists an ATP module that calls an IEEE/Cigre DLL.
write_cim_rdf:: Serialize the (possibly modified) return value from create_cim_rdf.
write_most_table_indices:: Writes some array column indices not included in the base MATPOWER set.
CASES:: Configuration data for five examples that come with this package.

buslists

Helper functions that navigate sequential bus numbers and CIM ConnectivityNode IDs.

emthub.buslists.build_bus_lists(d)

Order the buses (connectivity nodes) sequentially.

Creates two efficient dictionaries to access buses by their sequential number, or by ConnectivityNode ID.

Parameters:

d (dict) – The dictionary of CIM query results for a network.

Returns:

ordered_buses (dict) – The EMTBus dictionary, re-ordered by bus number.
bus_numbers (dict) – Reverse lookup the ConnectivityNode ID by bus number.

emthub.buslists.get_swingbus_id(ordered_buses, swingbus)

Find the CIM ConnectivityNode ID by matching the Name/Number from the original raw file.

The swing bus is used in MATPOWER or another power flow, and the Thevenin equivalent source in some EMT models.

Parameters:

ordered_buses (dict) – a dictionary of EMTBus sorted by bus number
swingbus (str) – the swing bus number, as a string name

Returns:

cnid (str) – the ConnectivityNode ID corresponding to the swing bus.

cim_examples

emthub.cim_examples.CASES: A list containing example case configurations as dictionaries.

[
  {
    "id": "6477751A-0472-4FD6-B3C3-3AD4945CBE56",
    "name": "IEEE39",
    "desc": "39 buses, 9 machines, 1 IBR",
    "legend_loc": "lower right",
    "wind_units": [],
    "solar_units": [
      "30_1"
    ],
    "hydro_units": [],
    "nuclear_units": [],
    "swingbus": "31",
    "load": 1.0,
    "UseXfmrSaturation": false,
    "UseMATPOWER": true
  },
  {
    "id": "1783D2A8-1204-4781-A0B4-7A73A2FA6038",
    "name": "IEEE118",
    "desc": "193 buses, 56 machines, 19 IBR",
    "legend_loc": "best",
    "wind_units": [
      "132_W",
      "136_W",
      "138_W",
      "168_W",
      "180_W"
    ],
    "solar_units": [
      "126_S",
      "128_S",
      "130_S",
      "140_S",
      "149_S",
      "151_S",
      "159_S",
      "165_S",
      "175_S",
      "179_S",
      "183_S",
      "185_S",
      "188_S",
      "191_S"
    ],
    "hydro_units": [],
    "nuclear_units": [],
    "swingbus": "131",
    "load": 0.6748,
    "UseXfmrSaturation": false,
    "UseMATPOWER": true
  },
  {
    "id": "2540AF5C-4F83-4C0F-9577-DEE8CC73BBB3",
    "name": "WECC240",
    "desc": "333 buses, 105 machines, 35 IBR",
    "legend_loc": "best",
    "wind_units": [
      "10322_S",
      "10342_W",
      "13332_S",
      "21301_G",
      "2332_S",
      "2431_S",
      "2434_S",
      "24382_RG",
      "24386_SW",
      "2439_S"
    ],
    "solar_units": [
      "2533_S",
      "2631_S",
      "32343_NW",
      "34331_S",
      "38351_NG",
      "3932_S",
      "3933_CG",
      "39331_NB",
      "40311_H",
      "40312_S",
      "4035_C",
      "40392_W",
      "41312_W",
      "42321_H",
      "5032_C",
      "50324_W",
      "61322_H",
      "61324_W",
      "62351_H",
      "63331_W",
      "64333_W",
      "6533_C",
      "65331_G",
      "70312_P",
      "70321_G"
    ],
    "hydro_units": [
      "12321_H",
      "13311_H",
      "21302_H",
      "2637_H",
      "2638_H",
      "40352_H",
      "40391_H",
      "41311_H",
      "41321_H",
      "42312_H",
      "50311_H",
      "63352_H",
      "65332_H",
      "70322_H",
      "8033_H",
      "80341_H"
    ],
    "nuclear_units": [
      "14311_N",
      "41322_N"
    ],
    "swingbus": "3831",
    "old_swingbus": "2438",
    "load": 1.02,
    "UseXfmrSaturation": false,
    "UseMATPOWER": true
  },
  {
    "id": "93EA6BF1-A569-4190-9590-98A62780489E",
    "name": "XfmrSat",
    "desc": "5 buses, load rejection with transformer saturation",
    "legend_loc": "best",
    "wind_units": [],
    "solar_units": [],
    "hydro_units": [],
    "nuclear_units": [],
    "swingbus": "1",
    "load": 1.0,
    "emergency_ratings": true,
    "UseXfmrSaturation": true,
    "UseMATPOWER": true
  },
  {
    "id": "62CB0930-211D-4762-B5C1-27BF73EAC7C4",
    "name": "SMIBDLL",
    "desc": "12 buses in a test harness, 1 IBR in a DLL",
    "legend_loc": "best",
    "wind_units": [],
    "solar_units": [
      "1_1"
    ],
    "hydro_units": [],
    "nuclear_units": [],
    "swingbus": "5",
    "load": 1.0,
    "UseXfmrSaturation": true,
    "UseMATPOWER": false,
    "ExtraFiles": [
      "create_smib_dll.py",
      "gfm_gfl_ibr2.dll",
      "gfm_gfl_ibr2.dll32"
    ]
  }
]

cim_sparql

Functions that read CIM into Python dictionaries using SPARQL queries.

emthub.cim_sparql.adhoc_sparql_dict(g, q, key_field)

Load the result of a user-written SPARQL query into a Python dictionary.

Use this function to run SPARQL that has been constructed at runtime. It is used to work with IBR and conventional generating plants that are not rooted in raw files, i.e., the plant data is constructed at runtime.

Parameters:

g (Graph) – an RDF graph constructed in memory, or loaded from XML or TTL file
q (str) – the SPARQL query text
key_field (str) – the field to index query results on, usually a CIM mRID

Returns:

dict (dict) – dictionary results from SPARQL, corresponding to a single un-named table.

emthub.cim_sparql.list_dict_table(dict, tag=None)

Print the fields and attributes of a Python dictionary loaded from SPARQL.

Use this function to explore the structure, size, and contents of a table loaded from SPARQL.

Parameters:

dict (dict) – result from load_emt_dict, load_ic_dict, or adhoc_sparql_dict
tag (str) – should be a loaded table name, ‘Adhoc Query’. If it includes * then the table is multi-keyed.

emthub.cim_sparql.load_emt_dict(g, sysid, bTiming=False)

Load an RDF graph into Python dictionary using packaged SPARQL queries.

This function works on a graph that might contain several transmission system datasets, differentiated by sysid. The correct sysid must be supplied, even if the graph contains data for only one transmission system, because sysid filters all queries.

Parameters:

g (Graph) – an RDF graph loaded from XML or TTL file
sysid (str) – the ID of the transmission system’s EquipmentContainer
bTiming (bool) – print the execution time of each packaged query

Returns:

dict (dict) – dictionary of EMT tables loaded from SPARQL.

emthub.cim_sparql.load_ic_dict(g, bPrint=False)

Load an RDF graph into Python dictionary from standalone power flow solution file.

This function only runs the EMTBusVoltageIC and EMTBranchFlowIC queries on data that usually comes from a power flow solver.

The EMTXfmrFlowIC no longer works in a standalone power flow solution file. To obtain this filtering, merge the power flow solution and network model into a single CIM RDF file, and then use EMTXfmrFlow.

Parameters:

g (Graph) – an RDF graph loaded from XML or TTL file
bPrint (bool) – print the total query time

Returns:

dict (dict) – dictionary of EMT tables loaded from SPARQL.

emthub.cim_sparql.summarize_graph(g)

Count the class instances by namespace in an RDF graph.

Use this function for a printed summary of the graph size.

Parameters:: g (Graph) – the RDF Graph obtained from construction in memory, or loaded from a file.

cim_summary

Summarizes the class counts in Turtle files

emthub.cim_summary.graph_summary_dict(root, classes_found)

Create a dictionary of class names and counts found in an RDF graph.

The Turtle file must exist in the current directory. This is a local version of emthub.summarize_graph that keeps a running list of classes found in repeated invocations. It also returns the counts in a dictionary, rather than printing to console.

Parameters:

root (str) – the basename of a Turtle file in the current directory.
classes_found (set) – adds each class (str) found to a set of classes found in many files.

Returns:

d – a dictionary of class names and their instance counts found in g.

emthub.cim_summary.print_cim_summaries(root_list)

Prints a summary of class names and counts found in list of Turtle files.

Only the list XfmrSat, IEEE39, IEEE118, WECC240, and SMIBDLL is supported. The Turtle files must already exist in the current directory.

Parameters:: root_list (str) – list of Turtle or base file names.

cim_support

Helper functions that read rawfile and dyrfile data into Python dictionaries. These dictionaries are then used to create RDF CIM data.

emthub.cim_support.load_detailed_model_types()

Load the library of detailed dynamic models with parameter descriptors.

The data comes from a JSON file included in the package named detailed_model_types.json.

Returns:

detailed_models (dict) – dictionary of detailed models, keyed first on model kind, which is
like a namespace for each supported file extension, and second on model name.

emthub.cim_support.load_dynamics_defaults()

Load example default settings for dynamics into a Python dictionary.

The data comes from a JSON file included in the package named dynamics_defaults.json.

Returns:: dyn_settings (dict) – dictionary of default values, keyed on model type and then attribute.

emthub.cim_support.load_dynamics_mapping(bReverseLookup=True)

Load a dictionary of CIM classes and attributes corresponding to dyr file contents.

The data comes from a JSON file included in the package named dyr_mapping.json. Use this function to translate dyrfile contents to the CIM classes and attributes. A reverse lookup option keys on CIM classes, to create missing dyrfile data from a CIM model based only on a rawfile.

Parameters:: bReverseLookup (bool) – key on the CIM class instead of the dyr model name
Returns:: attmap (dict) – dictionary keyed on a dyr model name, with CIM class and attributes.

emthub.cim_support.load_psse_dyrfile(case)

Load contents of a PSSE dyrfile into a Pandas dataframe.

The PSSE DYR file does not conform to CSV standards:

A line beginning with / or // is a comment to be ignored

Rows span lines. Each row ends with a single /

Field delimiters are comma (,) or any number of blanks

Each row generally begins with bus number (int), model name (str), and ID (str) but the ID is not always quoted

So, it is loaded into a Pandas data structure that offers more robust parsing, and flexible sizing, than standard Python arrays and CSV parsers.

Parameters:: case (dict) – an example chosen from emthub.cim_examples.CASES
Returns:: dyr (DataFrame) – the dynamics input data.

emthub.cim_support.load_psse_meta()

Load PSSE rawfile metadata into a Python dictionary.

The data comes from a JSON file included in the package named psseraw.json. It currently supports versions 33, 34, and 35. This function does not have to called separately from load_psse_rawfile.

Returns:: meta (dict) – schema of tables found in supported rawfile versions.

emthub.cim_support.load_psse_rawfile(fname, bPrint=False)

Load contents of a PSSE rawfile into a Python dictionary.

Versions 33, 34, and 35 are supported. The corresponding dynamics data should be read using load_psse_dyrfile, which does not have versions.

Parameters:

fname (str) – name of the PSSE rawfile to read.
bPrint (bool) – for debugging, print the contents of each rawfile row as it’s parsed.

Returns:

tables (dict) – dictionary of table data, following the schema from load_psse_meta.
kvbases (dict) – dictionary of voltage (kV) bases found in the system data, keyed on a constructed name for CIM BaseVoltage instances.
bus_kvbases (dict) – dictionary of voltage (kV) bases for each bus in the system.
baseMVA (float) – the system MVA base.

emthub.cim_support.match_dyr_generators(df, bPrint=False)

Collect dyrfile models from Pandas dataframe into a Python dictionary by generator name/id.

A conventional generator may have several dynamics models, e.g., the machine itself, excitation system, governor, power system stabilizer, etc. An IBR may also have several dynamic models associated with it, e.g., plant controller, regulator, converter controller, wind dynamics, etc. So, the return dictionary is keyed on generator, than one or more model types. The model types are taken from column 2 of each dyr file entry.

Parameters:

df (DataFrame) – the return value from load_psse_dyrfile
bPrint (bool) – print the dynamic model types and data found for each generator

Returns:

d (dict) – a dictionary of dynamic models, keyed on generator ID and then model type

emthub.cim_support.print_psse_table(tables, table_name)

Print a named dictionary loaded from section of a PSSE rawfile.

Use this function to verify the data imported from load_psse_rawfile. Also reveals the column names in each table.

Parameters:

tables (dict) – returned from load_psse_rawfile
table_name (str) – name of the table to print. Should be one of ‘BUS’, ‘LOAD’, ‘FIXED SHUNT’, ‘SWITCHED SHUNT’, ‘GENERATOR’, ‘BRANCH’, ‘SYSTEM SWITCHING DEVICE’, ‘TRANSFORMER’

emthub.cim_support.summarize_psse_dyrfile(dyr, case, bDetails=False)

Enumerate contents of a loaded PSSE dyrfile dataframe.

Use this for checking the numbers and sizes of dynamic models read. Each model of the same type should have the same size. Names of the parameters are not available from dyr files, so not available in this function.

Parameters:

dyr (DataFrame) – return value from load_psse_dyrfile
case (dict) – an example chosen from emthub.cim_examples.CASES
bDetails (bool) – print dyr using built-in Pandas formatting

Returns:

models (dict) – a dictionary of the dynamic models found, with sizes and instance counts

create_atp

Helper functions that netlist an Alternative Transients Program (ATP) model from CIM data. ATP requires a no-cost license to use, but not all parties are allowed to license ATP. The code in this module, and the output from this module’s code, are covered by the Apache 2.0 license. So, this module may be useful as an example for developers implementing the CIM-to-EMT netlisting function for other EMT simulators.

emthub.create_atp.create_atp(d, icd, fpath, case)

Write an ATP netlist from CIM loaded into a Python dictionary.

Writes a file ending in _net.atp, which references support files for machines, IBR, controls, and other components. An ATP user license is required for the support files, and to run a simulation on the _net.atp file. Also writes an atpmap file that maps CIM bus (ConnectivityNode) names to ATP bus numbers.

Parameters:

d (dict) – loaded from rdflib
icd (dict) – power flow solution for initial conditions
fpath (str) – relative path for ATP netlist files
case (dict) – an example chosen from emthub.cim_examples.CASES

emthub.create_atp.reset_globals(case)

Reset counters and limits for the next ATP netlist export.

It’s not necessary to call this function from outside the create_atp function.

Parameters:: case (dict) – an example chosen from emthub.cim_examples.CASES

create_mpow

Helper functions that write a MATPOWER model from CIM data. These power flow models can be used to help initialize EMT simulations.

emthub.create_mpow.create_matpower(d, sys_name, fp, swingbus, scale=1.0)

Write a MATPOWER netlist from CIM loaded into a Python dictionary.

MATPOWER only supports constant PQ loads. Constant impedance loads are netlisted as bus shunts, i.e., constant admittance. Constant current loads are handled as constant PQ loads.

Parameters:

d (dict) – dictionary of CIM data from load_emt_dict
sys_name (str) – the root name of the transmission system, typically from CASES[i][‘name’]. This name is used as the MATLAB/Octave function name to load the MATPOWER case.
fp (file) – an open file handle to the MATPOWER m file to be written
swingbus (str) – the swing bus number, as a string to look up the CIM ConnectivityNode ID
scale (float) – scaling factor on the nominal loads

create_rdf

Helper functions that write CIM RDF.

emthub.create_rdf.add_ibr_plant(case, plant, g, CIM, EMT)

Add an IBR plant with attributes and a DLL interface.

Call this function after create_cim_rdf, with a supplemental plant dictionary to configure an IBR plant. Call the function once for each IBR plant to be added. After adding all IBR plants, call write_cim_rdf to serialize the full CIM dataset.

The plant dictionary keys are as follows, referencing components by name rather than mRID.

generator, the name of the main PowerElectronicsConnection.

rpa_bus, the bus number of the facility point of common coupling, or reference point of applicability.

inv_bus, the bus number of generator. It will be moved to make room for the AC filter.

container_name, of the singleton CIM EquipmentContainer of all network and facility model components.

kv_base, for the AC side of the PowerElectronicsConnection, the system base, not necessarily the equipment’s rated voltage.

dll_path, the name of the DLL to be interfaced. It must be in a callable location.

components, an array of other plant components (not including the GeneratingUnit that is associated with the generator). Each array item is a two-element array in the form [CIMClassName, name of the component]. This function adds internal componeents for the AC filter and DC bus.

attributes, an array of IBRPlant attributes. Each array is a three-element array in the form [AttributeName, value, CIM Unit Class].

ac_filter, a dictionary of AC-side filter parameters used to create a sub-network in CIM to represent the filter. Each array is a two-element array in the form [value, CIM Unit Class].

dc_bus, a dictionary of DC bus parameters used to create a sub-network in CIM to represent the DC side of the PowerElectronicsConnection. Each array is a two-element array in the form [value, CIM Unit Class].

An example, from create_smib_dll.py, follows:

plant = {'generator': '1_1',
         'rpa_bus': '4',
         'inv_bus': '1',
         'container_name': 'SMIBDLL',
         'kv_base': 0.6,
         'dll_path': './gfm_gfl_ibr2.dll',
         'components': [
           ['ACLineSegment', '2_3_1'],
           ['PowerTransformer', '2_1_0_1'],
           ['PowerTransformer', '4_3_0_1']
           ],
         'attributes': [
           ['switchingFrequency', 3060.0, 'Frequency']
           ],
         'ac_filter' : {
            'acFilterCapacitance': [0.0015, 'Capacitance'],
            'acFilterLbridge': [0.0001, 'Inductance'],
            'acFilterLgrid': [0.0, 'Inductance'],
            'acFilterRbridge': [0.00075, 'Resistance'],
            'acFilterRgrid': [0.0, 'Resistance'],
            'acFilterKind': ['Yn', 'PhaseShuntConnectionKind']
           },
         'dc_bus' : {
            'dcLinkCapacitance': [0.1, 'Capacitance'],
            'dcLinkVoltage': [1200.0, 'Voltage']
           }
         }

Warning

This function is hard-wired for an AC-side tee filter and DC-side link capacitance. No zero-impedance branches are currently allowed.

Parameters:

case (dict) – an example chosen from emthub.cim_examples.CASES
plant (dict) – defines the IBR plant’s generator, other components, attributes, and DLL
g (Graph) – the RDF graph from rawfile and dyrfile data, from create_cim_rdf
CIM (Namespace) – an RDF namespace for the core CIM, from create_cim_rdf
EMT (Namespace) – an RDF namespace for the EMT extensions, from create_cim_rdf

Returns:

g (Graph) – modified RDF graph with an IBR plant model
CIM (Namespace) – an RDF namespace for the core CIM, same as input
EMT (Namespace) – an RDF namespace for the EMT extensions, same as input

emthub.create_rdf.create_cim_rdf(tables, kvbases, bus_kvbases, baseMVA, case, bSerialize=True, bWantGraph=False)

Create RDF in TTL/XML formats from results of load_psse_rawfile.

This function calls load_psse_dyrfile internally, as configured in the case argument. It also creates basic IBR plant and conventional generating plant data, for plants that can be interpreted from the generator (PowerElectronicsConverter or SynchronousMachine) and a generator step-up (GSU) transformer that is directly connected to the generator. When the rawfile data, the dyrfile data, and the simple plants define the entire network, the RDF data should be written by specifying bSerialize=True.

If a more complicated IBR plant will be part of the model, use bSerialize=False and bWantGraph=True. This allows for additional processing IBR plant attributes and a DLL interface before calling write_cim_rdf.

Parameters:

tables (dict) – data tables, returned from load_psse_rawfile
kvbases (dict) – bus kV bases found in the system, returned from load_psse_rawfile
bus_kvbases (dict) – kV bases for each bus, returned from load_psse_rawfile
baseMVA (float) – system MVA base, returned from load_psse_rawfile
case (dict) – an example chosen from emthub.cim_examples.CASES
bSerialize (bool) – call write_cim_rdf on the graph produced
bWantGraph (bool) – return the RDF graph and namespaces for additional processing

Returns:

g (Graph) – an RDF graph built from rawfile and dyrfile data
CIM (Namespace) – an RDF namespace for the core CIM
EMT (Namespace) – an RDF namespace for the EMT extensions

emthub.create_rdf.write_cim_rdf(case, g, CIM, EMT)

Serialize the (possibly modified) return value from create_cim_rdf.

Writes both TTL and XML. The RDF serializer also supports json-ld, which could be implemented in a single line of code.

Parameters:

case (dict) – an example chosen from emthub.cim_examples.CASES
g (Graph) – the RDF graph from create_cim_rdf, possibly modified with add_ibr_plant
CIM (Namespace) – an RDF namespace for the core CIM, from create_cim_rdf
EMT (Namespace) – an RDF namespace for the EMT extensions, from create_cim_rdf

create_sql

Functions that insert CIM data into a SQL database. Not Fully Implemented

emthub.create_sql.create_cim_sql(tables, kvbases, bus_kvbases, baseMVA, case)

Create SQL db from results of load_psse_rawfile.

TODO: Not fully implemented.

Parameters:

tables (dict) – dictionary of tables from load_psse_rawfile
kvbases (dict) – dictionary of system-wide voltage bases found in load_psse_rawfile
bus_kvbases (dict) – dictionary of bus voltage bases found in load_psse_rawfile
baseMVA (float) – the base MVA from the rawfile, usually 100, found in load_psse_rawfile

dll_config

Functions to query an IEEE/Cigre DLL through its API.

emthub.dll_config.get_dll_interface(dll_name, bPrint=True)

Returns a Python dictionary of the interface to an IEEE/Cigre DLL.

Use this function to extract the DLL parameters, input ports, output ports, and version information. Some of that will be added to CIM data.

Parameters:

dll_name (str) – path to the DLL that will be called through its API
bPrint (bool) – write a summary of DLL parameters and signals to the console

Returns:

d (dict) – dictionary of the DLL parameters, signals, and other metadata.

emthub.dll_config.write_atp_dll_interface(dll_fullname, atp_path, parm_vals, bus, type_90_sources, type_91_sources, ap)

Netlists an ATP module that calls an IEEE/Cigre DLL.

This function calls the DLL through its API to obtain its full metadata. It writes an include file, with .mod extension, to be called by the main ATP netlist. It then appends a call to this include file in the main ATP netlist.

Parameters:

dll_fullname (str) – filename of the DLL in an executable location.
atp_path (str) – path where the ATP main netlist and include files are being written.
parm_vals (list) – array of DLL parameters that came from CIM data. Only floating-point values are supported in ATP.
bus (str) – the root ATP bus name where this DLL is connected. ATP only allows 5 characters in this name.
type_90_sources (dict) – kind and phase of voltage inputs, keyed on the ATP/TACS bus name
type_91_sources (dict) – kind and phase of current inputs, keyed on the ATP/TACS bus name of a measuring switch.
ap (file) – handle of the file that has been opened for the main ATP netlist.

mpow_utilities

Functions that run MATPOWER from the console, and read MATPOWER/MOST cases/results into Python. Also defines some needed constants for zero-based array indices corresponding to MATPOWER’s one-based array indices. See Appendix B, Data File Format, in the MATPOWER manual for more information. For example, PG is the column index in the generator table for real power output; it’s 2 for MATPOWER and 1 for Python.

Some internal functions were developed to support the i2x project’s work on BPS hosting capacity; these functions are not used for EMT initialization.

emthub.mpow_utilities.print_solution_summary(fname, details=False)

Prints a summary of solved MATPOWER case to console.

Use this to check for convergence, solution time, and presence of overloads or bus voltage violations. Does not include branch and bus details.

Parameters:

filename (str) – name of a solution summary file created in the script passed to run_matpower_and_wait
details (bool) – include the total load, generation, loss and voltage summary.

emthub.mpow_utilities.read_matpower_casefile(fname, asNumpy=True)

Read a MATPOWER m file into Python dictionary.

Parses the gen, branch, bus, bus_name, gencost, gentype, and genfuel tables.

Parameters:

fname (str) – name of the MATPOWER m file to read
asNumpy (bool) – request the data in Numpy rather than Python arrays

Returns:

d (dict) – a dictionary of the MATPOWER case input.

emthub.mpow_utilities.run_matpower_and_wait(fscript, quiet=False)

Runs MATPOWER from command line on Windows, Mac, or Linux.

Octave and MATPOWER must be installed. On Windows, Octave should be installed in the default location.

Parameters:

fscript (str) – the name of a MATPOWER m-file to run.
quiet (bool) – request a progress notification to the console.

emthub.mpow_utilities.summarize_casefile(d, label)

Report the table sizes, total load, and total generation in a loaded MATPOWER case file.

The total load includes constant PQ only. Constant Z loads are represented as bus shunts, and do not appear in this summary. Constant I loads are not supported in MATPOWER.

Parameters:

d (dict) – return value from read_matpower_casefile
label (str) – annotation for the summary, typically Input or Solved

emthub.mpow_utilities.write_most_table_indices(fp)

Writes some array column indices not included in the base MATPOWER set.

MOST is the optimal power flow bundled with MATPOWER. Some of its indices are used in generator cost and fuel modeling (used to distinguish IBR), and in the i2x hosting capacity work. For EMT, these indices are used to apply edits, taken from emthub.cim_examples.CASES, on the base network model.

Parameters:: fp (file) – a handle to an open MATPOWER m file

plot_utils

Plotting and graph topology support functions. Use these to add missing DiagramLayout data to the CIM model. The sequence of steps for this is:

Call create_cim_rdf using the rawfile and dyrfile data. It won’t have DiagramLayout data in the serialized CIM RDF (unless the function finds an old JSON file from previously completing step 2).
Call build_system_graph, using a dictionary obtained from the RDF data saved in step 1. This writes a JSON file with the layout.
Call plot_system_graph to visually check the layout, including colors and labels.
Call create_cim_rdf a second time. Now it will find the JSON file from step 2, and include DiagramLayout data in the serialized CIM RDF.

emthub.plot_utils.build_system_graph(d)

Auto-layout a diagram of the CIM network, returning a networkx graph.

This function assigns colors to buses (graph nodes) depending on the presence of load, wind, solar, or conventional generation. It assigns colors and weights to the mult-terminal components (graph edges) depending on the type of component and voltage class. ACLineSegments are weighed by an estimated physical length. Then the networkx package’s kamada_kawai_layout option is used to create a plausible layout of the buses.

Parameters:: d (dict) – CIM data from load_emt_dict
Returns:: G (networkx.Graph) – the node/edge system layout.

emthub.plot_utils.load_system_graph(fname)

Load the networkx layout (graph) from a JSON file.

Narrative.

Parameters:: fname (str) – name of the JSON file containing networkx Graph data
Returns:: G (networkx.Graph) – the node/edge system layout.

emthub.plot_utils.plot_system_graph(G, sys_name, plot_labels, loc)

Plot the transmission system topology from a networkx layout (graph).

Uses matplotlib to make the plot from G. Optionally, use a button on the plot GUI to save it in the current working directory.

Parameters:

G (networkx.Graph) – the node/edge system layout.
sys_name (str) – root name from the title, typically from CASES[i][‘name’]
plot_labels (bool) – plot node (bus) labels. Only recommended with a small number of nodes.
loc (str) – location of the legend for matplotlib, typically from CASES[i][‘legend_loc’]. The examples use ‘best’, the default, or specify ‘lower right’.

emthub.plot_utils.save_system_graph(G, fname)

Save the networkx layout (graph) to a JSON file.

Call this after build_system_graph.

Parameters:

G (networkx.Graph) – the node/edge system layout.
fname (str) – name of the JSON file to save G in

Example Scripts for Users

These are distributed in the examples subdirectory, and obtainable by emthub-extract-case #. The command-line documentation follows.

emthub.examples.atp.main()

Runs or post-processes ATP from an existing netlist.

Command-line Arguments:: index (int): case number from 0 to 4 option (str): either run to execute ATP, convert to convert PL4 to COMTRADE and then HDF5, plot to plot HDF5 on screen, or png to plot HDF5 to a file.

emthub.examples.bps_make_mpow.main()

Creates a netlist for MATPOWER from CIM RDF (TTL file).

Command-line Arguments:: index (int): case number from 0 to 4

emthub.examples.cim_summary.main(): Tabulates the CIM classes and instance counts found in 5 example files.

emthub.examples.cim_to_atp.main()

Creates a netlist for ATP from CIM RDF (TTL file).

Command-line Arguments:: index (int): case number from 0 to 4

emthub.examples.create_smib_dll.main(): Creates the ATP netlist and a DLL interface for the SMIBDLL example (case 4). The rawfile tables are hard-coded.

emthub.examples.ic_to_rdf.main()

Converts initial conditions from MATPOWER to CIM RDF (TTL file).

Command-line Arguments:: index (int): case number from 0 to 4

emthub.examples.mpow.main()

Runs MATPOWER from a previously generated netlist.

Command-line Arguments:: index (int): case number from 0 to 4

emthub.examples.plot_bps.main()

Plot a system graphical layout. Data comes from a SystemName_Network.json file.

Command-line Arguments:: index (int): case number from 0 to 4

emthub.examples.raw_to_rdf.main()

Creates CIM RDF from rawfile and dyrfile data. Three output formats are produced, namely TTL, XML, and JSON.

Command-line Arguments:: index (int): case number from 0 to 3. Case 4 uses create_smib_dll.py instead.

emthub.examples.test_cim_sparql.main()

Use this for printing the results of a SPARQL query loaded into a Python dictionary. Edit the script to print the dictionaries of interest.

Command-line Arguments:: index (int): case number from 0 to 4