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, axis_height: 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
- 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
- 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”
- 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