power_grid_model
- class power_grid_model.PowerGridModel(*_args, **_kwargs)
Bases:
object
Main class for Power Grid Model
- Attributes:
all_component_count
Get count of number of elements per component type.
batch_error
Get the batch error object, if present
Methods
calculate_power_flow
(*[, symmetric, ...])Calculate power flow once with the current model attributes.
calculate_state_estimation
(*[, symmetric, ...])Calculate state estimation once with the current model attributes.
copy
()Copy the current model
get_indexer
(component_type, ids)Get array of indexers given array of ids for component type
update
(*, update_data)Update the model with changes. Args: update_data: update data dictionary key: component type name value: 1D numpy structured array for this component update Returns: None.
- 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.
- Args:
- 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. Args:
- 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
- Args:
component_type: type of component ids: array of ids
- Returns:
array of inderxers, 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
- Args:
- symmetric:
True: three-phase symmetric calculation, even for asymmetric loads/generations False: three-phase asymmetric calculation
- error_tolerance:
error tolerance for voltage in p.u., only applicable when iterative=True
- max_iterations:
maximum number of iterations, only applicable when iterative=True
- calculation_method: an enumeration or string
newton_raphson: use Newton-Raphson iterative method (default) linear: use linear method
- update_data:
None: calculate power flow once with the current model attributes A dictionary for batch calculation with batch update
key: component type name to be updated in batch value:
- a 2D numpy structured array for homogeneous update batch
Dimension 0: each batch Dimension 1: each updated element per batch for this component type
or a dictionary containing two keys, for inhomogeneous update batch
- indptr: a 1D integer numpy array with length n_batch + 1
given batch number k, the update array for this batch is data[indptr[k]:indptr[k + 1]] This is the concept of compressed sparse structure https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html
data: 1D numpy structured array in flat
- threading:
only applicable for batch calculation < 0 sequential = 0 parallel, use number of hardware threads > 0 specify number of parallel threads
- output_component_types: 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: if the program continues (instead of throwing error) if some scenarios fails
- 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
- Error handling:
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
- Args:
- symmetric:
True: three-phase symmetric calculation, even for asymmetric loads/generations False: three-phase asymmetric calculation
- error_tolerance:
error tolerance for voltage in p.u., only applicable when iterative=True
- max_iterations:
maximum number of iterations, only applicable when iterative=True
- calculation_method: an enumeration
iterative_linear: use iterative linear method
- update_data:
None: calculate state estimation once with the current model attributes A dictionary for batch calculation with batch update
key: component type name to be updated in batch value:
- a 2D numpy structured array for homogeneous update batch
Dimension 0: each batch Dimension 1: each updated element per batch for this component type
or a dictionary containing two keys, for inhomogeneous update batch
- indptr: a 1D integer numpy array with length n_batch + 1
given batch number k, the update array for this batch is data[indptr[k]:indptr[k + 1]] This is the concept of compressed sparse structure https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html
data: 1D numpy structured array in flat
- threading:
only applicable for batch calculation < 0 sequential = 0 parallel, use number of hardware threads > 0 specify number of parallel threads
- output_component_types: 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: if the program continues (instead of throwing error) if some scenarios fails
- 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
- Error handling:
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
- Args:
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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- 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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- 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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- 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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- 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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- power_flow = 0
- state_estimation = 1
- class power_grid_model.enum.CalculationMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnum
Calculation Methods
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- linear = 0
- newton_raphson = 1
- iterative_linear = 2
- iterative_current = 3
- linear_current = 4
- 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
- Attributes:
denominator
the denominator of a rational number in lowest terms
imag
the imaginary part of a complex number
numerator
the numerator of a rational number in lowest terms
real
the real part of a complex number
Methods
as_integer_ratio
(/)Return integer ratio.
bit_count
(/)Number of ones in the binary representation of the absolute value of self.
bit_length
(/)Number of bits necessary to represent self in binary.
conjugate
Returns self, the complex conjugate of any int.
from_bytes
(/, bytes[, byteorder, signed])Return the integer represented by the given array of bytes.
to_bytes
(/[, length, byteorder, signed])Return an array of bytes representing an integer.
- 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
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:
Is the data structure correct? (checking data types and numpy array shapes)
Are all required values provided? (checking NaNs)
Are all ID’s unique? (checking object identifiers across all components)
Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)
- Args:
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 or ValueError if the data structure is invalid.
- Returns:
None if the data is valid, or a list containing all validation errors.
- 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]]]
Ihe input dataset is validated:
Is the data structure correct? (checking data types and numpy array shapes)
Are all input data ID’s unique? (checking object identifiers across all components)
- For each batch the update data is validated:
Is the update data structure correct? (checking data types and numpy array shapes)
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:
Are all required values provided? (checking NaNs)
Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)
- Args:
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 or ValueError if the data structure is invalid.
- Returns:
None if the data is valid, or a dictionary containing all validation errors, where the key is the batch number (0-indexed).
- 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:
Is the data structure correct? (checking data types and numpy array shapes)
Are all required values provided? (checking NaNs)
Are all ID’s unique? (checking object identifiers across all components)
Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)
- Args:
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 or 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)
Ihe input dataset is validated:
Is the data structure correct? (checking data types and numpy array shapes)
Are all input data ID’s unique? (checking object identifiers across all components)
- For each batch the update data is validated:
Is the update data structure correct? (checking data types and numpy array shapes)
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:
Are all required values provided? (checking NaNs)
Are the supplied values valid? (checking limits and other logic as described in “Graph Data Model”)
- Args:
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 or 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. Args:
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
- Attributes:
- component
component_str
A string representation of the component to which this error applies
- field
field_str
A string representation of the field to which this error applies
- ids
Methods
get_context
([id_lookup])Returns a dictionary that supplies (human readable) information about this error.
- 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.
- Args:
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 Args:
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 Args:
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