power_grid_model_io

cli

converters

Abstract converter class

class power_grid_model_io.converters.base_converter.BaseConverter(source: Optional[BaseDataStore[T]] = None, destination: Optional[BaseDataStore[T]] = None)

Abstract converter class

Methods

convert(data[, extra_info])	Convert input/update/(a)sym_output data and optionally extra info.
load_asym_output_data([data])	Load asymmetric output data
load_input_data([data])	Load input data and extra info
load_sym_output_data([data])	Load symmetric output data
load_update_data([data])	Load update data
save(data[, extra_info, destination])	Save input/update/(a)sym_output data and optionally extra info.

__init__(source: Optional[BaseDataStore[T]] = None, destination: Optional[BaseDataStore[T]] = None)

Initialize a logger

load_input_data(data: Optional[T] = None) → Tuple[Dict[str, ndarray], Dict[int, Dict[str, Union[str, float, int, Tuple[float, float, float], List[ExtraInfoType], Dict[str, ExtraInfoType]]]]]

Load input data and extra info

Note: You shouldn’t have to overwrite this method. Check _parse_data() instead.

Args:

data: Optional[T]: (Default value = None)

Returns:

load_update_data(data: Optional[T] = None) → Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]]

Load update data

Note: You shouldn’t have to overwrite this method. Check _parse_data() instead.

Args:

data: Optional[T]: (Default value = None)

Returns:

load_sym_output_data(data: Optional[T] = None) → Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]]

Load symmetric output data

Note: You shouldn’t have to overwrite this method. Check _parse_data() instead.

Args:

data: Optional[T]: (Default value = None)

Returns:

load_asym_output_data(data: Optional[T] = None) → Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]]

Load asymmetric output data

Note: You shouldn’t have to overwrite this method. Check _parse_data() instead.

Args:

data: Optional[T]: (Default value = None)

Returns:

convert(data: Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]], extra_info: Optional[Dict[int, Dict[str, Union[str, float, int, Tuple[float, float, float], List[ExtraInfoType], Dict[str, ExtraInfoType]]]]] = None) → T

Convert input/update/(a)sym_output data and optionally extra info.

Note: You shouldn’t have to overwrite this method. Check _serialize_data() instead.

Args:

data: Dataset: extra_info: Optional[ExtraInfoLookup]: (Default value = None)

Returns:

save(data: Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]], extra_info: Optional[Dict[int, Dict[str, Union[str, float, int, Tuple[float, float, float], List[ExtraInfoType], Dict[str, ExtraInfoType]]]]] = None, destination: Optional[BaseDataStore[T]] = None) → None

Save input/update/(a)sym_output data and optionally extra info.

Note: You shouldn’t have to overwrite this method. Check _serialize_data() instead.

Args:

data: Dataset: extra_info: Optional[ExtraInfoLookup]: (Default value = None) destination: Optional[BaseDataStore[T]]: (Default value = None)

Returns:

Tabular Data Converter: Load data from multiple tables and use a mapping file to convert the data to PGM

class power_grid_model_io.converters.tabular_converter.TabularConverter(mapping_file: Optional[Path] = None, source: Optional[BaseDataStore[TabularData]] = None, destination: Optional[BaseDataStore[TabularData]] = None)

Tabular Data Converter: Load data from multiple tables and use a mapping file to convert the data to PGM

Methods

convert(data[, extra_info])	Convert input/update/(a)sym_output data and optionally extra info.
get_id(table, key[, name])	Get a the numerical ID previously associated with the supplied name / key combination Args: table: Table name (e.g. "Nodes") key: Component identifier (e.g. {"name": "node1"} or {"number": 1, "sub_number": 2}) name: Optional component name (e.g. "internal_node") Returns: The associated id.
load_asym_output_data([data])	Load asymmetric output data
load_input_data([data])	Load input data and extra info
load_sym_output_data([data])	Load symmetric output data
load_update_data([data])	Load update data
lookup_id(pgm_id)	Retrieve the original name / key combination of a pgm object Args: pgm_id: a unique numerical ID Returns: The original name / key combination
save(data[, extra_info, destination])	Save input/update/(a)sym_output data and optionally extra info.
set_mapping_file(mapping_file)	Read, parse and interpret a mapping file. This includes:

__init__(mapping_file: Optional[Path] = None, source: Optional[BaseDataStore[TabularData]] = None, destination: Optional[BaseDataStore[TabularData]] = None)

Prepare some member variables and optionally load a mapping file

Args:

mapping_file: A yaml file containing the mapping.

set_mapping_file(mapping_file: Path) → None

Read, parse and interpret a mapping file. This includes:

• the table to table mapping (‘grid’)

• the unit conversions (‘units’)

• the value substitutions (‘substitutions’) (e.g. enums or other one-on-one value mapping)

Args:

mapping_file: Path:

Returns:

get_id(table: str, key: Mapping[str, int], name: Optional[str] = None) → int

Get a the numerical ID previously associated with the supplied name / key combination Args:

table: Table name (e.g. “Nodes”) key: Component identifier (e.g. {“name”: “node1”} or {“number”: 1, “sub_number”: 2}) name: Optional component name (e.g. “internal_node”)

Returns: The associated id

lookup_id(pgm_id: int) → Dict[str, Union[str, Dict[str, int]]]

Retrieve the original name / key combination of a pgm object Args:

pgm_id: a unique numerical ID

Returns: The original name / key combination

Vision Excel Converter: Load data from a Vision Excel export file and use a mapping file to convert the data to PGM

class power_grid_model_io.converters.vision_excel_converter.VisionExcelConverter(source_file: Optional[Union[Path, str]] = None, language: str = 'en')

Vision Excel Converter: Load data from a Vision Excel export file and use a mapping file to convert the data to PGM

Methods

convert(data[, extra_info])	Convert input/update/(a)sym_output data and optionally extra info.
get_appliance_id(table, node_number, sub_number)	Get the automatically assigned id of an appliance (source, load, etc.)
get_branch_id(table, number)	Get the automatically assigned id of a branch (line, transformer, etc.)
get_id(table, key[, name])	Get a the numerical ID previously associated with the supplied name / key combination Args: table: Table name (e.g. "Nodes") key: Component identifier (e.g. {"name": "node1"} or {"number": 1, "sub_number": 2}) name: Optional component name (e.g. "internal_node") Returns: The associated id.
get_node_id(number)	Get the automatically assigned id of a node
get_virtual_id(table, obj_name, node_number, ...)	Get the automatically assigned id of a vitual object (e.g.
load_asym_output_data([data])	Load asymmetric output data
load_input_data([data])	Load input data and extra info
load_sym_output_data([data])	Load symmetric output data
load_update_data([data])	Load update data
lookup_id(pgm_id)	Retrieve the original name / key combination of a pgm object Args: pgm_id: a unique numerical ID Returns: The original name / key combination
save(data[, extra_info, destination])	Save input/update/(a)sym_output data and optionally extra info.
set_mapping_file(mapping_file)	Read, parse and interpret a mapping file. This includes:

__init__(source_file: Optional[Union[Path, str]] = None, language: str = 'en')

Prepare some member variables and optionally load a mapping file

Args:

mapping_file: A yaml file containing the mapping.

get_node_id(number: int) → int

Get the automatically assigned id of a node

get_branch_id(table: str, number: int) → int

Get the automatically assigned id of a branch (line, transformer, etc.)

get_appliance_id(table: str, node_number: int, sub_number: int) → int

Get the automatically assigned id of an appliance (source, load, etc.)

get_virtual_id(table: str, obj_name: str, node_number: int, sub_number: int) → int

Get the automatically assigned id of a vitual object (e.g. the internal node of a ‘TansformerLoad’)

Power Grid Model ‘Converter’: Load and store power grid model data in the native PGM JSON format.

class power_grid_model_io.converters.pgm_json_converter.PgmJsonConverter(source_file: Optional[Union[Path, str]] = None, destination_file: Optional[Union[Path, str]] = None)

A ‘converter’ class to load and store power grid model data in the native PGM JSON format. The methods are simmilar to the utils in power_grid_model, with the addition of storing and loading ‘extra info’. Extra info is the set of attributes that don’t match the power grid model’s internal structure, but are important to keep close to the data. The most common example is the original object ID, if the original IDs are not numeric, or not unique over all components.

Args:

Returns:

Methods

convert(data[, extra_info])	Convert input/update/(a)sym_output data and optionally extra info.
load_asym_output_data([data])	Load asymmetric output data
load_input_data([data])	Load input data and extra info
load_sym_output_data([data])	Load symmetric output data
load_update_data([data])	Load update data
save(data[, extra_info, destination])	Save input/update/(a)sym_output data and optionally extra info.

__init__(source_file: Optional[Union[Path, str]] = None, destination_file: Optional[Union[Path, str]] = None)

Initialize a logger

data_stores

Abstract data store class

class power_grid_model_io.data_stores.base_data_store.BaseDataStore

Abstract data store class

Methods

load()	The method that loads the data from one or more sources and returns it in the specified format.
save(data)	The method that saves the data to one or more destinations.

__init__()

Initialize a logger

abstract load() → T

The method that loads the data from one or more sources and returns it in the specified format. Note that the load() method does not receive a reference to the data source(s); i.e. the data source(s) should be set in the constructor, or in a separate member method.

Returns: Loaded data of type <T>

abstract save(data: T) → None

The method that saves the data to one or more destinations. Note that the save() method does not receive a reference to the data destination(s); i.e. the data destination(s) should be set in the constructor, or in a separate member method.

Args:

data: Tha data to store shoul dbe of type <T>

Excel File Store

class power_grid_model_io.data_stores.excel_file_store.ExcelFileStore(file_path: Optional[Path] = None, **extra_paths: Path)

Excel File Store

The first row of each sheet is expected to contain the column names, unless specified differently by an extension of this class. Columns with duplicate names (on the same sheet) are either removed (if they contain exactly the same values) or renamed.

Methods

files()	The files as supplied in the constructor.
load()	Load one or more Excel file as tabular data.
save(data)	Store tabular data as one or more Excel file.

__init__(file_path: Optional[Path] = None, **extra_paths: Path)

Initialize a logger

files() → Dict[str, Path]

The files as supplied in the constructor. Note that the file names are read-only.

Returns: A copy of the file paths as set in the constructor.

load() → TabularData

Load one or more Excel file as tabular data.

Returns: The contents of all the Excel file supplied in the constructor. The tables of the main file will have no prefix, while the tables of all the extra files will be prefixed with the name of the key word argument as supplied in the constructor.

save(data: TabularData) → None

Store tabular data as one or more Excel file.

Args:

data: Tha data to store. The keys of the tables will be the names of the spread sheets in the excel files. Table names with a prefix corresponding to the name of the key word argument as supplied in the constructor will be stored in the associated files.

The json file store

class power_grid_model_io.data_stores.json_file_store.JsonFileStore(file_path: Path)

The json file store expects each json file to be eiter a single dictionary, or a list of dictonaries.

Methods

load()	Loads a JSON file, validates the structure and returns it in a native python data format
save(data)	Saves the native python data format as a JSON file
set_compact(compact)	In compact mode, each object will be output on a single line.
set_indent(indent)	Change the number of spaces used for each indent level (affects output only)

__init__(file_path: Path)

Initialize a logger

set_indent(indent: Optional[int]) → None

Change the number of spaces used for each indent level (affects output only)

Args:

indent: Number of spaces for each indent level. None = all json on a single line.

set_compact(compact: bool) → None

In compact mode, each object will be output on a single line. Note that the JsonFileStore is not very general; it assumes that data is either a dictionary of this format:

{

“category_0”:

[

{“attribute_0”: …, “attribute_1”: …, …}, {“attribute_0”: …, “attribute_1”: …, …},

],

“category_1”:

[

{“attribute_0”: …, “attribute_1”: …, …}, {“attribute_0”: …, “attribute_1”: …, …},

],

…

}

or a list of those dictionaries.

Args:

compact: Boolean defining if the output should be stored compact or not

load() → Union[Dict[str, List[Dict[str, Any]]], List[Dict[str, List[Dict[str, Any]]]]]

Loads a JSON file, validates the structure and returns it in a native python data format

Returns: StructuredData

save(data: Union[Dict[str, List[Dict[str, Any]]], List[Dict[str, List[Dict[str, Any]]]]]) → None

Saves the native python data format as a JSON file

Args:

data: StructuredData

Vision Excel file store

class power_grid_model_io.data_stores.vision_excel_file_store.VisionExcelFileStore(file_path: Path)

Vision Excel file store

In Vision files, the second row contains information about the unit of measure. Therefore, row 1 (which is row 2 in Excel) is added to the header_rows in the constructor.

Methods

files()	The files as supplied in the constructor.
load()	Load one or more Excel file as tabular data.
save(data)	Store tabular data as one or more Excel file.

__init__(file_path: Path)

Args:

file_path: The main Vision Excel export file

data_types

The TabularData class is a wrapper around Dict[str, Union[pd.DataFrame, np.ndarray]], which supports unit conversions and value substitutions

class power_grid_model_io.data_types.tabular_data.TabularData(**tables: Union[DataFrame, ndarray])

The TabularData class is a wrapper around Dict[str, Union[pd.DataFrame, np.ndarray]], which supports unit conversions and value substitutions

Methods

get_column(table_name, column_name)	Select a column from a table, while applying unit conversions and value substitutions
items()	Mimic the dictionary .items() function
keys()	Mimic the dictionary .keys() function
set_substitutions(substitution)	Define value substitutions
set_unit_multipliers(units)	Define unit multipliers.

__init__(**tables: Union[DataFrame, ndarray])

Tabular data can either be a collection of pandas DataFrames and/or numpy structured arrays. The key word arguments will define the keys of the data.

tabular_data = TabularData(foo=foo_data) tabular_data[“foo”] –> foo_data

Args:

**tables: A collection of pandas DataFrames and/or numpy structured arrays

set_unit_multipliers(units: UnitMapping) → None

Define unit multipliers.

Args:

units: A UnitMapping object defining all the units and their conversions (e.g. 1 MW = 1_000_000 W)

set_substitutions(substitution: ValueMapping) → None

Define value substitutions

Args:

substitution: A ValueMapping defining all value substitutions (e.g. “yes” -> 1)

get_column(table_name: str, column_name: str) → Series

Select a column from a table, while applying unit conversions and value substitutions

Args:

table_name: The name of the table as supplied in the constructor column_name: The name of the column or “index” to get the index

Returns:

The required column, with unit conversions and value substitutions applied

keys() → Iterable[str]

Mimic the dictionary .keys() function

Returns: An iterator over all table names as supplied in the constructor.

items() → Iterable[Tuple[str, Union[DataFrame, ndarray]]]

Mimic the dictionary .items() function

Returns: An iterator over the table names and the raw table data

functions

These functions can be used in the mapping files to apply functions to tabular data

power_grid_model_io.functions._functions.has_value(value: Any) → bool

Return True if the value is not None, NaN or empty string.

power_grid_model_io.functions._functions.value_or_default(value: Optional[T], default: T) → T

Return the value, or a default value if no value was supplied.

power_grid_model_io.functions._functions.value_or_zero(value: Optional[float]) → float

Return the value, or a zero value if no value was supplied.

power_grid_model_io.functions._functions.complex_inverse_real_part(real: float, imag: float) → float

Return the real part of the inverse of a complex number

power_grid_model_io.functions._functions.complex_inverse_imaginary_part(real: float, imag: float) → float

Return the imaginary part of the inverse of a complex number

power_grid_model_io.functions._functions.get_winding(winding: str, neutral_grounding: bool = True) → WindingType

Return the winding type as an enum value, based on the string representation

power_grid_model_io.functions._functions.degrees_to_clock(degrees: float) → int

Return the clock

power_grid_model_io.functions._functions.is_greater_than(left_side, right_side) → bool

Return true if the first argument is greater than the second

These functions can be used in the mapping files to apply functions to vision data

power_grid_model_io.functions.phase_to_phase.relative_no_load_current(i_0: float, p_0: float, s_nom: float, u_nom: float) → float

Calculate the relative no load current.

power_grid_model_io.functions.phase_to_phase.reactive_power(p: float, cos_phi: float) → float

Calculate the reactive power, based on p, cosine phi.

power_grid_model_io.functions.phase_to_phase.power_wind_speed(p_nom: float, wind_speed: float, cut_in_wind_speed: float = 3.0, nominal_wind_speed: float = 14.0, cutting_out_wind_speed: float = 25.0, cut_out_wind_speed: float = 30.0) → float

Estimate p_ref based on p_nom and wind_speed.

See section “Wind turbine” in https://phasetophase.nl/pdf/VisionEN.pdf

power_grid_model_io.functions.phase_to_phase.get_winding_from(conn_str: str, neutral_grounding: bool = True) → WindingType

Get the winding type, based on a textual encoding of the conn_str

power_grid_model_io.functions.phase_to_phase.get_winding_to(conn_str: str, neutral_grounding: bool = True) → WindingType

Get the winding type, based on a textual encoding of the conn_str

power_grid_model_io.functions.phase_to_phase.get_clock(conn_str: str) → int

Extract the clock part of the conn_str

power_grid_model_io.functions.phase_to_phase.reactive_power_to_susceptance(q: float, u_nom: float) → float

Calculate susceptance, b1 from reactive power Q with nominal voltage

mappings

Tabular data mapping helper class

class power_grid_model_io.mappings.tabular_mapping.TabularMapping(mapping: Dict[str, Dict[str, Union[Dict[str, Union[int, float, str, Dict, List]], List[Dict[str, Union[int, float, str, Dict, List]]]]]])

Tabular data mapping helper class

Methods

instances(table)	Return instance definitions (as a generator)
tables()	Return the names of the tables (as a generator)

__init__(mapping: Dict[str, Dict[str, Union[Dict[str, Union[int, float, str, Dict, List]], List[Dict[str, Union[int, float, str, Dict, List]]]]]])

tables() → Generator[str, None, None]

Return the names of the tables (as a generator)

Yields:

table_name

instances(table: str) → Generator[Tuple[str, Dict[str, Union[int, float, str, Dict, List]]], None, None]

Return instance definitions (as a generator)

Yields:

component_name, instance_attribute_mapping

Unit mapping helper class

class power_grid_model_io.mappings.unit_mapping.UnitMapping(mapping: Optional[Dict[str, Optional[Dict[str, float]]]] = None)

Unit mapping helper class. The input data is expected to be of the form: {

“A” : None, “W”: {

“kW”: 1000.0, “MW”: 1000000.0

}

}

Methods

get_unit_multiplier(unit)	Find the correct unit multiplier and the corresponding SI unit
set_mapping(mapping)	Creates an internal mapping lookup table based on input data of the form: mapping = { "A" : None, "W": { "kW": 1000.0, "MW": 1000000.0 } }

__init__(mapping: Optional[Dict[str, Optional[Dict[str, float]]]] = None)

set_mapping(mapping: Dict[str, Optional[Dict[str, float]]])

Creates an internal mapping lookup table based on input data of the form: mapping = {

“A” : None, “W”: {

“kW”: 1000.0, “MW”: 1000000.0

}

}

get_unit_multiplier(unit: str) → Tuple[float, str]

Find the correct unit multiplier and the corresponding SI unit

Value substitution helper class

class power_grid_model_io.mappings.value_mapping.ValueMapping(mapping: Optional[Dict[str, Dict[Union[int, float, str, bool], Union[int, float, str, bool]]]] = None)

Value substitution helper class

Methods

get_substitutions(attr[, table])

Find the substitutions for a given attribute.

__init__(mapping: Optional[Dict[str, Dict[Union[int, float, str, bool], Union[int, float, str, bool]]]] = None)

get_substitutions(attr: str, table: Optional[str] = None) → Dict[Union[int, float, str, bool], Union[int, float, str, bool]]

Find the substitutions for a given attribute.

utils

Automatic ID generator class

class power_grid_model_io.utils.auto_id.AutoID

Automatic ID generator class

1. Usage without items:

   auto_id = AutoID() a = auto_id() # a = 0 b = auto_id() # b = 1 c = auto_id() # c = 2 item = auto_id[2] # item = 2

2. Usage with hashable items:

   auto_id = AutoID() a = auto_id(item=”Alpha”) # a = 0 b = auto_id(item=”Bravo”) # b = 1 c = auto_id(item=”Alpha”) # c = 0 (because key “Alpha” already existed) item = auto_id[1] # item = “Bravo”

3. Usage with non-hashable items:

   auto_id = AutoID() a = auto_id(item={“name”: “Alpha”}, key=”Alpha”) # a = 0 b = auto_id(item={“name”: “Bravo”}, key=”Bravo”) # b = 1 c = auto_id(item={“name”: “Alpha”}, key=”Alpha”) # c = 0 (because key “Alpha” already existed) item = auto_id[1] # item = {“name”: “Alpha”}

Note: clashing keys will update the item:

auto_id = AutoID() a = auto_id(item={“name”: “Alpha”}, key=”Alpha”) # a = 0 b = auto_id(item={“name”: “Bravo”}, key=”Bravo”) # b = 1 c = auto_id(item={“name”: “Charly”}, key=”Alpha”) # c = 0 (because key “Alpha” already existed) item = auto_id[0] # item = {“name”: “Charly”}

Methods

__call__([item, key])

Generate a new unique numerical id for the item, or retrieve the previously generated id.

__init__() → None

Module utilities, expecially useful for loading optional dependencies

power_grid_model_io.utils.modules.get_function(fn_name: str) → Callable

Get a function pointer by name