power_grid_model

class power_grid_model.PowerGridModel(*_args, **_kwargs)

Bases: object

Main class for Power Grid Model

property batch_error: Optional[PowerGridBatchError]

Get the batch error object, if present

Returns:

Batch error object, or None

property all_component_count: Dict[str, int]

Get count of number of elements per component type. If the count for a component type is zero, it will not be in the returned dictionary.

Returns:

A dictionary with

  • key: Component type name

  • value: Integer count of elements of this type

copy() → PowerGridModel

Copy the current model

Returns:

A copy of PowerGridModel

__init__(input_data: Dict[str, ndarray], system_frequency: float = 50.0)

Initialize the model from an input data set.

Parameters:

  • input_data –

    Input data dictionary

    • key: Component type name

    • value: 1D numpy structured array for this component input

  • system_frequency – Frequency of the power system, default 50 Hz

update(*, update_data: Dict[str, ndarray])

Update the model with changes.

Parameters:

update_data –

Update data dictionary

  • key: Component type name

  • value: 1D numpy structured array for this component update

Returns:

None

get_indexer(component_type: str, ids: ndarray)

Get array of indexers given array of ids for component type

Parameters:

  • component_type – Type of component

  • ids – Array of ids

Returns:

Array of indexers, same shape as input array ids

calculate_power_flow(*, symmetric: bool = True, error_tolerance: float = 1e-08, max_iterations: int = 20, calculation_method: Union[CalculationMethod, str] = CalculationMethod.newton_raphson, update_data: Optional[Dict[str, Union[ndarray, Dict[str, ndarray]]]] = None, threading: int = -1, output_component_types: Optional[Union[Set[str], List[str]]] = None, continue_on_batch_error: bool = False) → Dict[str, ndarray]

Calculate power flow once with the current model attributes. Or calculate in batch with the given update dataset in batch.

Parameters:

  • symmetric (bool, optional) –

    Whether to perform a three-phase symmetric calculation.

    • True: Three-phase symmetric calculation, even for asymmetric loads/generations (Default).

    • False: Three-phase asymmetric calculation.

  • error_tolerance (float, optional) – Error tolerance for voltage in p.u., applicable only when the calculation method is iterative.

  • max_iterations (int, optional) – Maximum number of iterations, applicable only when the calculation method is iterative.

  • calculation_method (an enumeration or string) –

    The calculation method to use.

    • newton_raphson: Use Newton-Raphson iterative method (default).

    • linear: Use linear method.

  • update_data (dict, optional) –

    None: Calculate power flow once with the current model attributes. Or a dictionary for batch calculation with batch update.

    • key: Component type name to be updated in batch.

    • value:

      • For homogeneous update batch (a 2D numpy structured array):

        • Dimension 0: Each batch.

        • Dimension 1: Each updated element per batch for this component type.

      • For inhomogeneous update batch (a dictionary containing two keys):

  • threading (int, optional) –

    Applicable only for batch calculation.

    • < 0: Sequential

    • = 0: Parallel, use number of hardware threads

    • > 0: Specify number of parallel threads

  • output_component_types ({set, list}, optional) – List or set of component types you want to be present in the output dict. By default, all component types will be in the output.

  • continue_on_batch_error (bool, optional) – If the program continues (instead of throwing error) if some scenarios fail.

Returns:

Dictionary of results of all components.

  • key: Component type name to be updated in batch.

  • value:

    • For single calculation: 1D numpy structured array for the results of this component type.

    • For batch calculation: 2D numpy structured array for the results of this component type.

      • Dimension 0: Each batch.

      • Dimension 1: The result of each element for this component type.

Raises:

Exception – In case an error in the core occurs, an exception will be thrown.

calculate_state_estimation(*, symmetric: bool = True, error_tolerance: float = 1e-08, max_iterations: int = 20, calculation_method: Union[CalculationMethod, str] = CalculationMethod.iterative_linear, update_data: Optional[Dict[str, Union[ndarray, Dict[str, ndarray]]]] = None, threading: int = -1, output_component_types: Optional[Union[Set[str], List[str]]] = None, continue_on_batch_error: bool = False) → Dict[str, ndarray]

Calculate state estimation once with the current model attributes. Or calculate in batch with the given update dataset in batch.

Parameters:

  • symmetric (bool, optional) –

    Whether to perform a three-phase symmetric calculation.

    • True: Three-phase symmetric calculation, even for asymmetric loads/generations (Default).

    • False: Three-phase asymmetric calculation.

  • error_tolerance (float, optional) – error tolerance for voltage in p.u., only applicable when the calculation method is iterative.

  • max_iterations (int, optional) – Maximum number of iterations, applicable only when the calculation method is iterative.

  • calculation_method (an enumeration) – Use iterative linear method.

  • update_data (dict, optional) –

    None: Calculate state estimation once with the current model attributes. Or a dictionary for batch calculation with batch update.

    • key: Component type name to be updated in batch.

    • value:

      • For homogeneous update batch (a 2D numpy structured array):

        • Dimension 0: Each batch.

        • Dimension 1: Each updated element per batch for this component type.

      • For inhomogeneous update batch (a dictionary containing two keys):

  • threading (int, optional) –

    Applicable only for batch calculation.

    • < 0: Sequential

    • = 0: Parallel, use number of hardware threads

    • > 0: Specify number of parallel threads

  • output_component_types ({set, list}, optional) – List or set of component types you want to be present in the output dict. By default, all component types will be in the output.

  • continue_on_batch_error (bool, optional) – If the program continues (instead of throwing error) if some scenarios fail.

Returns:

Dictionary of results of all components.

  • key: Component type name to be updated in batch.

  • value:

    • For single calculation: 1D numpy structured array for the results of this component type.

    • For batch calculation: 2D numpy structured array for the results of this component type.

      • Dimension 0: Each batch.

      • Dimension 1: The result of each element for this component type.

Raises:

Exception – In case an error in the core occurs, an exception will be thrown.

calculate_short_circuit(*, calculation_method: Union[CalculationMethod, str] = CalculationMethod.iec60909, update_data: Optional[Dict[str, Union[ndarray, Dict[str, ndarray]]]] = None, threading: int = -1, output_component_types: Optional[Union[Set[str], List[str]]] = None, continue_on_batch_error: bool = False) → Dict[str, ndarray]

Calculate a short circuit once with the current model attributes. Or calculate in batch with the given update dataset in batch

Parameters:

  • calculation_method (an enumeration) – Use the iec60909 standard.

  • update_data –

    None: calculate a short circuit once with the current model attributes. Or a dictionary for batch calculation with batch update

    • key: Component type name to be updated in batch

    • value:

      • For homogeneous update batch (a 2D numpy structured array):

        • Dimension 0: each batch

        • Dimension 1: each updated element per batch for this component type

      • For inhomogeneous update batch (a dictionary containing two keys):

  • threading (int, optional) –

    Applicable only for batch calculation.

    • < 0: Sequential

    • = 0: Parallel, use number of hardware threads

    • > 0: Specify number of parallel threads

  • output_component_types ({set, list}, optional) – List or set of component types you want to be present in the output dict. By default, all component types will be in the output.

  • continue_on_batch_error (bool, optional) – If the program continues (instead of throwing error) if some scenarios fail.

Returns:

Dictionary of results of all components.

  • key: Component type name to be updated in batch.

  • value:

    • For single calculation: 1D numpy structured array for the results of this component type.

    • For batch calculation: 2D numpy structured array for the results of this component type.

      • Dimension 0: Each batch.

      • Dimension 1: The result of each element for this component type.

Raises:

Exception – In case an error in the core occurs, an exception will be thrown.

power_grid_model.initialize_array(data_type: str, component_type: str, shape: Union[tuple, int], empty: bool = False)

Initializes an array for use in Power Grid Model calculations

Parameters:

  • data_type – input, update, sym_output, or asym_output

  • component_type – one component type, e.g. node

  • shape – shape of initialization integer, it is a 1-dimensional array tuple, it is an N-dimensional (tuple.shape) array

  • empty – if leave the memory block un-initialized

Returns:

np structured array with all entries as null value

enum

Common Enumerations

Note: these enumeration match the C++ arithmetic core, so don’t change the values unless you change them in C++ as well

class power_grid_model.enum.LoadGenType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Load and Generator Types

const_power = 0
const_impedance = 1
const_current = 2
class power_grid_model.enum.WindingType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Transformer Winding Types

wye = 0
wye_n = 1
delta = 2
zigzag = 3
zigzag_n = 4
class power_grid_model.enum.BranchSide(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Branch Sides

from_side = 0
to_side = 1
class power_grid_model.enum.Branch3Side(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Branch3 Sides

side_1 = 0
side_2 = 1
side_3 = 2
class power_grid_model.enum.CalculationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Calculation Types

power_flow = 0
state_estimation = 1
short_circuit = 2
class power_grid_model.enum.CalculationMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Calculation Methods

linear = 0
newton_raphson = 1
iterative_linear = 2
iterative_current = 3
linear_current = 4
iec60909 = 5
class power_grid_model.enum.MeasuredTerminalType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

The type of asset measured by a (power) sensor

branch_from = 0

Measuring the from-terminal between a branch (except link) and a node

branch_to = 1

Measuring the to-terminal between a branch (except link) and a node

source = 2

Measuring the terminal between a source and a node

shunt = 3

Measuring the terminal between a shunt and a node

load = 4

Measuring the terminal between a load and a node

generator = 5

Measuring the terminal between a generator and a node

branch3_1 = 6

Measuring the terminal-1 between a branch3 and a node

branch3_2 = 7

Measuring the terminal-2 between a branch3 and a node

branch3_3 = 8

Measuring the terminal-3 between a branch3 and a node

node = 9

Measuring the total power injection into a node

class power_grid_model.enum.FaultType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

The type of fault represented by a fault component

three_phase = 0
single_phase_to_ground = 1
two_phase = 2
two_phase_to_ground = 3
nan = -128

Unspecified fault type. Needs to be overloaded at the latest in the update_data

class power_grid_model.enum.FaultPhase(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

The faulty phase(s) affected by the provided fault type

abc = 0

All phases are faulty in a three-phase fault

a = 1

The first phase is faulty in a single-phase-to-ground fault

b = 2

The second phase is faulty in a single-phase-to-ground fault

c = 3

The third phase is faulty in a single-phase-to-ground fault

ab = 4

The first and second phase are faulty in a two-phase or two-phase-to-ground fault

ac = 5

The first and third phase are faulty in a two-phase or two-phase-to-ground fault

bc = 6

The second and third phase are faulty in a two-phase or two-phase-to-ground fault

default_value = -1

Use the default fault phase. Depends on the fault_type.

nan = -128

Unspecified fault phase. Needs to be overloaded at the latest in the update_data

validation

power_grid_model.validation.validate_input_data(input_data: Dict[str, ndarray], calculation_type: Optional[CalculationType] = None, symmetric: bool = True) → Optional[List[ValidationError]]

Validates the entire input dataset:

  1. Is the data structure correct? (checking data types and numpy array shapes)

  2. Are all required values provided? (checking NaNs)

  3. Are all ID’s unique? (checking object identifiers across all components)

  4. Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)

Parameters:

  • input_data – A power-grid-model input dataset

  • calculation_type – Supply a calculation method, to allow missing values for unused fields

  • symmetric – A boolean to state whether input data will be used for a symmetric or asymmetric calculation

Returns:

None if the data is valid, or a list containing all validation errors.

Raises:

Error – KeyError | TypeError | ValueError: if the data structure is invalid.

power_grid_model.validation.validate_batch_data(input_data: Dict[str, ndarray], update_data: Dict[str, Union[ndarray, Dict[str, ndarray]]], calculation_type: Optional[CalculationType] = None, symmetric: bool = True) → Optional[Dict[int, List[ValidationError]]]

The input dataset is validated:

  1. Is the data structure correct? (checking data types and numpy array shapes)

  2. Are all input data ID’s unique? (checking object identifiers across all components)

For each batch the update data is validated:

  1. Is the update data structure correct? (checking data types and numpy array shapes)

  2. Are all update ID’s valid? (checking object identifiers across update and input data)

Then (for each batch independently) the input dataset is updated with the batch’s update data and validated:

  1. Are all required values provided? (checking NaNs)

  2. Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)

Parameters:

  • input_data – A power-grid-model input dataset

  • update_data – A power-grid-model update dataset (one or more batches)

  • calculation_type – Supply a calculation method, to allow missing values for unused fields

  • symmetric – A boolean to state whether input data will be used for a symmetric or asymmetric calculation

Returns:

None if the data is valid, or a dictionary containing all validation errors, where the key is the batch number (0-indexed).

Raises:

Error – KeyError | TypeError | ValueError: if the data structure is invalid.

power_grid_model.validation.assert_valid_input_data(input_data: Dict[str, ndarray], calculation_type: Optional[CalculationType] = None, symmetric: bool = True)

Validates the entire input dataset:

  1. Is the data structure correct? (checking data types and numpy array shapes)

  2. Are all required values provided? (checking NaNs)

  3. Are all ID’s unique? (checking object identifiers across all components)

  4. Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)

Parameters:

  • input_data – A power-grid-model input dataset

  • calculation_type – Supply a calculation method, to allow missing values for unused fields

  • symmetric – A boolean to state whether input data will be used for a symmetric or asymmetric calculation

Raises:

  • KeyError | TypeError | ValueError – if the data structure is invalid.

  • ValidationException – if the contents are invalid.

power_grid_model.validation.assert_valid_batch_data(input_data: Dict[str, ndarray], update_data: Dict[str, Union[ndarray, Dict[str, ndarray]]], calculation_type: Optional[CalculationType] = None, symmetric: bool = True)

The input dataset is validated:

  1. Is the data structure correct? (checking data types and numpy array shapes)

  2. Are all input data ID’s unique? (checking object identifiers across all components)

For each batch the update data is validated:

  1. Is the update data structure correct? (checking data types and numpy array shapes)

  2. Are all update ID’s valid? (checking object identifiers across update and input data)

Then (for each batch independently) the input dataset is updated with the batch’s update data and validated:

  1. Are all required values provided? (checking NaNs)

  2. Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)

Parameters:

  • input_data – a power-grid-model input dataset

  • update_data – a power-grid-model update dataset (one or more batches)

  • calculation_type – Supply a calculation method, to allow missing values for unused fields

  • symmetric – A boolean to state whether input data will be used for a symmetric or asymmetric calculation

Raises:

  • KeyError | TypeError | ValueError – if the data structure is invalid.

  • ValidationException – if the contents are invalid.

power_grid_model.validation.errors_to_string(errors: Optional[Union[List[ValidationError], Dict[int, List[ValidationError]]]], name: str = 'the data', details: bool = False, id_lookup: Optional[Union[List[str], Dict[int, str]]] = None) → str

Convert a set of errors (list or dict) to a human readable string representation.

Parameters:

  • errors – The error objects. List for input_data only, dict for batch data.

  • name – Human understandable name of the dataset, e.g. input_data, or update_data.

  • details – Display object ids and error specific information.

  • id_lookup – A list or dict (int->str) containing textual object ids

Returns:

A human readable string representation of a set of errors.

errors

class power_grid_model.validation.errors.ValidationError

The Validation Error is an abstract base class which should be extended by all validation errors. It supplies three public member variables: component, field and ids; storing information about the origin of the validation error. Error classes can extend the public members. For example:

NotBetweenError(ValidationError):

component = ‘vehicle’ field = ‘direction’ id = [3, 14, 15, 92, 65, 35] ref_value = (-3.1416, 3.1416)

For convenience, a human readable representation of the error is supplied using the str() function. I.e. print(str(error)) will print a human readable error message like:

Field direction is not between -3.1416 and 3.1416 for 6 vehicles

component: Optional[Union[str, List[str]]] = None

The component, or components, to which the error applies.

field: Optional[Union[str, List[str], List[Tuple[str, str]]]] = None

The field, or fields, to which the error applies. A field can also be a tuple (component, field) when multiple components are being addressed.

ids: Optional[Union[List[int], List[Tuple[str, int]]]] = None

The object identifiers to which the error applies. A field object identifier can also be a tuple (component, id) when multiple components are being addressed.

property component_str: str

A string representation of the component to which this error applies

property field_str: str

A string representation of the field to which this error applies

get_context(id_lookup: Optional[Union[List[str], Dict[int, str]]] = None) → Dict[str, Any]

Returns a dictionary that supplies (human readable) information about this error. Each member variable is included in the dictionary. If a function {field_name}_str() exists, the value is overwritten by that function.

Parameters:

id_lookup – A list or dict (int->str) containing textual object ids

utils

power_grid_model.utils.import_json_data(json_file: Path, data_type: str, ignore_extra: bool = False) → Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]]

import json data

Parameters:

  • json_file – path to the json file

  • data_type – type of data: input, update, sym_output, or asym_output

  • ignore_extra – Allow (and ignore) extra attributes in the json file

Returns:

A single or batch dataset for power-grid-model

power_grid_model.utils.export_json_data(json_file: Path, data: Union[Dict[str, ndarray], Dict[str, Union[ndarray, Dict[str, ndarray]]]], indent: Optional[int] = 2, compact: bool = False)

export json data

Parameters:

  • json_file – path to json file

  • data – a single or batch dataset for power-grid-model

  • indent – indent of the file, default 2

  • compact – write components on a single line

Returns:

Save to file