Graph Data Model

To represent the physical grid components, and the calculation results, this library uses a graph data model. In this document, the graph data model is presented with the list of all components types, and their relevant input/output attributes.

Enumerations

Some attributes of components are enumerations. The enumerations are implemented using 8-bit signed integer, as explained in Native Data Interface.

The table below for a list of enumerations. They are all defined in the module power_grid_model.enum. The underlying type of enumeration is int8_t.

enum type name in Python	possible values	usage
`LoadGenType`	`const_power = 0` `const_impedance = 1` `const_current = 2`	load/generation types
`WindingType`	`wye = 0` `wye_n = 1` `delta = 2` `zigzag = 3` `zigzag_n = 4`	transformer winding type
`BranchSide`	`from_side = 0` `to_side = 1` `side_1 = 2` `side_2 = 3` `side_3 = 4`	the side of a branch
`MeasuredTerminalType`	`branch_from = 0`, measuring the from-terminal between a branch and a node `branch_to = 1`, measuring the to-terminal between a branch 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	type of flow (e.g. power) measurement
`CalculationMethod`	`linear = 0` `newton_raphson = 1` `iterative_linear = 2` `iterative_current = 3` `linear_current = 4`	method of calculation

Component Type Hierarchy and Graph Data Model

The components types are organized in an inheritance-like hierarchy. A sub-type has all the attributes from its parent type. The hierarchy of the component types is shown below.

base ──┬─────────────────────────────────────────────── node
       │
       ├── branch ──────────────────────────────────┬── line
       │                                            ├── link
       │                                            └── transformer
       |
       |── branch3 ──────────────────────────────────── three_winding_transformer
       │
       ├── appliance ──┬─────────────────────────────── source
       │               │
       │               ├─────────────────────────────── shunt
       │               │
       │               └── generic_load_gen ────────┬── sym_load
       │                                            ├── sym_gen
       │                                            ├── asym_load
       │                                            └── asym_gen
       │
       └── sensor ─────┬── generic_voltage_sensor ──┬── sym_voltage_sensor
                       │                            └── asym_voltage_sensor
                       │
                       └── generic_power_sensor ────┬── sym_power_sensor
                                                    └── asym_power_sensor

NOTE: the type names in the hierarchy are exactly the same as the component type names in the power_grid_model.power_grid_meta_data, see Native Data Interface

This library uses a graph data model with three generic component types: node, branch, branch3 and appliance. A node is similar to a vertex in the graph, a branch is similar to an edge in the graph and a branch3 connects threee nodes together. An appliance is a component which is connected (coupled) to a node, it is seen as a user of this node.

The figure below shows a simple example:

node_1 ---line_3 (branch)--- node_2 --------------three_winding_transformer_8 (branch3)------ node_6
 |                             |                                 |
source_5 (appliance)       sym_load_4 (appliance)             node_7

There are four nodes (points/vertices) in the graph of this simple grid.
The node_1 and node_2 are connected by line_3 which is a branch (edge).
The node_2, node_6, and node_7 are connected by three_winding_transformer_8 which is a branch3.
There are two appliances in the grid. The source_5 is coupled to node_1 and the sym_load_4 is coupled to node_2.

Symmetry of Components and Calculation

It should be emphasized that the symmetry of components and calculation are two independent concepts in the model. For example, a power grid model can consist of both sym_load and asym_load. They are symmetric or asymmetric load components. On the other hand, the same model can execute symmetric or asymmetric calculations.

In case of symmetric calculation, the asym_load will be treated as a symmetric load by averaging the specified power through three phases.
In case of asymmetric calculation, the sym_load will be treated as an asymmetric load by dividing the total specified power equally into three phases.

Attributes of Components

The attributes of components are listed in the tables in the sections below. The column names of the tables are as follows:

name: name of the attribute. It is exactly the same as the attribute name in power_grid_model.power_grid_meta_data.
data type: data type of the attribute. It is either a type from the table in Native Data Interface. Or it can be an enumeration as above defined. There is two special data types RealValueInput and RealValueOutput.
- RealValueInput is used for some input attributes. It is a double for a symmetric class (e.g. sym_load) and double[3] an asymmetric class (e.g. asym_load). It is explained in detail in the corresponding types.
- RealValueOutput is used for many output attributes. It is a double in symmetric calculation and double[3] for asymmetric calculation.
- As noted above, these two special types are independent.
unit: unit of the attribute, if it is applicable. As a general rule, only standard SI units without any prefix are used.
description: description of the attribute.
required: if the attribute is required. If not, then it is optional. Note if you choose not to specify an optional attribute, it should have the null value as defined in Native Data Interface.
input: if the attribute is part of an input dataset.
update: if the attribute can be mutated by the update call PowerGridModel.update on an existing instance, only applicable when this attribute is part of an input dataset.
output: if the attribute is part of an output dataset.
valid values: if applicable, an indication which values are valid for the input data

Validation

For performance reasons, the input/update data is not automatically validated. There are validation functions available in the power_grid_model.validation module:

# Manual validation
#   validate_input_data() assumes that you won't be using update data in your calculation.
#   validate_batch_data() validates input_data in combination with batch/update data.
validate_input_data(input_data, calculation_type, symmetric) -> List[ValidationError]
validate_batch_data(input_data, update_data, calculation_type, symmetric) -> Dict[int, List[ValidationError]]

# Assertions
#   assert_valid_input_data() and assert_valid_batch_data() raise a ValidationException,
#   containing the list/dict of errors, when the data is invalid.
assert_valid_input_data(input_data, calculation_type, symmetric)
raises
ValidationException
assert_valid_batch_data(input_data, calculation_type, update_data, symmetric)
raises
ValidationException

# Utilities
#   errors_to_string() converts a set of errors to a human readable (multi-line) string representation
errors_to_string(errors, name, details)

Have a look at the Jupyter Notebook "Validation Examples" for more information on how to apply these functions.

Component Types

Base

type name: base

The base type for all power grid components.

name	data type	unit	description	required	input	update	output
`id`	`int32_t`	-	ID of a component, the id should be unique along all components, i.e. you cannot have a node with `id` 5 and a line with `id` 5.	✔	✔	❌ (id needs to be specified in the update query, but cannot be changed)	✔
`energized`	`int8_t`	-	Indicates if a component is energized, i.e. connected to a source		❌	❌	✔

Node

type name: node

node is a point in the grid. Physically a node can be a busbar, a joint, or other similar component.

name	data type	unit	description	required	input	update	output	valid values
`u_rated`	`double`	volt (V)	rated line-line voltage	✔	✔	❌	❌	`> 0`
`u_pu`	`RealValueOutput`	-	per-unit voltage magnitude		❌	❌	✔
`u_angle`	`RealValueOutput`	rad	voltage angle		❌	❌	✔
`u`	`RealValueOutput`	volt (V)	voltage magnitude, line-line for symmetric calculation, line-neutral for asymmetric calculation		❌	❌	✔

Branch

type name: branch

branch is the abstract base type for the component which connects two different nodes. For each branch two switches are always defined at from- and to-side of the branch. In reality such switches may not exist. For example, a cable usually permanently connects two joints. In this case, the attribute from_status and to_status is always 1.

name	data type	unit	description	required	input	update	output	valid values
`from_node`	`int32_t`	-	ID of node at from-side	✔	✔	❌	❌	a valid node id
`to_node`	`int32_t`	-	ID of node at to-side	✔	✔	❌	❌	a valid node id
`from_status`	`int8_t`	-	connection status at from-side	✔	✔	✔	❌	`0` or `1`
`to_status`	`int8_t`	-	connection status at to-side	✔	✔	✔	❌	`0` or `1`
`p_from`	`RealValueOutput`	watt (W)	active power flowing into the branch at from-side		❌	❌	✔
`q_from`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power flowing into the branch at from-side		❌	❌	✔
`i_from`	`RealValueOutput`	ampere (A)	current at from-side		❌	❌	✔
`s_from`	`RealValueOutput`	volt-ampere (VA)	apparent power flowing at from-side		❌	❌	✔
`p_to`	`RealValueOutput`	watt (W)	active power flowing into the branch at to-side		❌	❌	✔
`q_to`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power flowing into the branch at to-side		❌	❌	✔
`i_to`	`RealValueOutput`	ampere (A)	current at to-side		❌	❌	✔
`s_to`	`RealValueOutput`	volt-ampere (VA)	apparent power flowing at to-side		❌	❌	✔
`loading`	`double`	-	relative loading of the line, `1.0` meaning 100% loaded.		❌	❌	✔

Line

type name: 'line'

line is a branch with specified serial impedance and shunt admittance. A cable is also modeled as line. A line can only connect two nodes with the same rated voltage.

name	data type	unit	description	required	input	update	output	valid values
`r1`	`double`	ohm (Ω)	positive-sequence serial resistance	✔	✔	❌	❌	`r1` and `x1` cannot be both zero
`x1`	`double`	ohm (Ω)	positive-sequence serial reactance	✔	✔	❌	❌	`r1` and `x1` cannot be both zero
`c1`	`double`	farad (F)	positive-sequence shunt capacitance	✔	✔	❌	❌
`tan1`	`double`	-	positive-sequence shunt loss factor (tan𝛿)	✔	✔	❌	❌
`r0`	`double`	ohm (Ω)	zero-sequence serial resistance	✨ only for asymmetric calculations	✔	❌	❌	`r0` and `x0` cannot be both zero
`x0`	`double`	ohm (Ω)	zero-sequence serial reactance	✨ only for asymmetric calculations	✔	❌	❌	`r0` and `x0` cannot be both zero
`c0`	`double`	farad (F)	zero-sequence shunt capacitance	✨ only for asymmetric calculations	✔	❌	❌
`tan0`	`double`	-	zero-sequence shunt loss factor (tan𝛿)	✨ only for asymmetric calculations	✔	❌	❌
`i_n`	`double`	ampere (A)	rated current	✔	✔	❌	❌	`> 0`

Link

type name: link

link usually represents a short internal cable/connection between two busbars inside a substation. It has a very high admittance (small impedance) which is set to a fixed per-unit value (equivalent to 10e6 siemens for 10kV network). There is no additional attribute for link.

Transformer

transformer connects two nodes with possibly different voltage levels.

Note: it can happen that tap_min > tap_max. In this case the winding voltage is decreased if the tap position is increased.

name	data type	unit	description	required	input	update	output	valid values
`u1`	`double`	volt (V)	rated voltage at from-side	✔	✔	❌	❌	`> 0`
`u2`	`double`	volt (V)	rated voltage at to-side	✔	✔	❌	❌	`> 0`
`sn`	`double`	volt-ampere (VA)	rated power	✔	✔	❌	❌	`> 0`
`uk`	`double`	-	relative short circuit voltage, `0.1` means 10%	✔	✔	❌	❌	`>= pk / sn` and `> 0` and `< 1`
`pk`	`double`	watt (W)	short circuit (copper) loss	✔	✔	❌	❌	`>= 0`
`i0`	`double`	-	relative no-load current	✔	✔	❌	❌	`>= p0 / sn` and `< 1`
`p0`	`double`	watt (W)	no-load (iron) loss	✔	✔	❌	❌	`>= 0`
`winding_from`	`WindingType`	-	from-side winding type	✔	✔	❌	❌
`winding_to`	`WindingType`	-	to-side winding type	✔	✔	❌	❌
`clock`	`int8_t`	-	clock number of phase shift. Even number is not possible if one side is Y(N) winding and the other side is not Y(N) winding. Odd number is not possible, if both sides are Y(N) winding or both sides are not Y(N) winding.	✔	✔	❌	❌	`>= 0` and `<= 12`
`tap_side`	`BranchSide`	-	side of tap changer	✔	✔	❌	❌
`tap_pos`	`int8_t`	-	current position of tap changer	✔	✔	✔	❌	`(tap_min <= tap_pos <= tap_max)` or `(tap_min >= tap_pos >= tap_max)`
`tap_min`	`int8_t`	-	position of tap changer at minimum voltage	✔	✔	❌	❌
`tap_max`	`int8_t`	-	position of tap changer at maximum voltage	✔	✔	❌	❌
`tap_nom`	`int8_t`	-	nominal position of tap changer	❌ default zero	✔	❌	❌	`(tap_min <= tap_nom <= tap_max)` or `(tap_min >= tap_nom >= tap_max)`
`tap_size`	`double`	volt (V)	size of each tap of the tap changer	✔	✔	❌	❌	`>= 0`
`uk_min`	`double`	-	relative short circuit voltage at minimum tap	❌ default same as `uk`	✔	❌	❌	`>= pk_min / sn` and `> 0` and `< 1`
`uk_max`	`double`	-	relative short circuit voltage at maximum tap	❌ default same as `uk`	✔	❌	❌	`>= pk_max / sn` and `> 0` and `< 1`
`pk_min`	`double`	watt (W)	short circuit (copper) loss at minimum tap	❌ default same as `pk`	✔	❌	❌	`>= 0`
`pk_max`	`double`	watt (W)	short circuit (copper) loss at maximum tap	❌ default same as `pk`	✔	❌	❌	`>= 0`
`r_grounding_from`	`double`	ohm (Ω)	grounding resistance at from-side, if relevant	❌ default zero	✔	❌	❌
`x_grounding_from`	`double`	ohm (Ω)	grounding reactance at from-side, if relevant	❌ default zero	✔	❌	❌
`r_grounding_to`	`double`	ohm (Ω)	grounding resistance at to-side, if relevant	❌ default zero	✔	❌	❌
`x_grounding_to`	`double`	ohm (Ω)	grounding reactance at to-side, if relevant	❌ default zero	✔	❌	❌

Branch3

type name: branch3

branch3 is the abstract base type for the component which connects three different nodes. For each branch3 three switches are always defined at side 1, 2, or 3 of the branch. In reality such switches may not exist.

name	data type	unit	description	required	input	update	output	valid values
`node_1`	`int32_t`	-	ID of node at side 1	✔	✔	❌	❌	a valid node id
`node_2`	`int32_t`	-	ID of node at side 2	✔	✔	❌	❌	a valid node id
`node_3`	`int32_t`	-	ID of node at side 3	✔	✔	❌	❌	a valid node id
`status_1`	`int8_t`	-	connection status at side 1	✔	✔	✔	❌	`0` or `1`
`status_2`	`int8_t`	-	connection status at side 2	✔	✔	✔	❌	`0` or `1`
`status_3`	`int8_t`	-	connection status at side 3	✔	✔	✔	❌	`0` or `1`
`p_1`	`RealValueOutput`	watt (W)	active power flowing into the branch at side 1	✔	❌	❌	✔
`q_1`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power flowing into the branch at side 1	✔	❌	❌	✔
`i_1`	`RealValueOutput`	ampere (A)	current at side 1	✔	❌	❌	✔
`s_1`	`RealValueOutput`	volt-ampere (VA)	apparent power flowing at side 1	✔	❌	❌	✔
`p_2`	`RealValueOutput`	watt (W)	active power flowing into the branch at side 2	✔	❌	❌	✔
`q_2`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power flowing into the branch at side 2	✔	❌	❌	✔
`i_2`	`RealValueOutput`	ampere (A)	current at side 2	✔	❌	❌	✔
`s_2`	`RealValueOutput`	volt-ampere (VA)	apparent power flowing at side 2	✔	❌	❌	✔
`p_3`	`RealValueOutput`	watt (W)	active power flowing into the branch at side 3	✔	❌	❌	✔
`q_3`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power flowing into the branch at side 3	✔	❌	❌	✔
`i_3`	`RealValueOutput`	ampere (A)	current at side 3	✔	❌	❌	✔
`s_3`	`RealValueOutput`	volt-ampere (VA)	apparent power flowing at side 3	✔	❌	❌	✔
`loading`	`double`	-	relative loading of the branch, `1.0` meaning 100% loaded.	✔	❌	❌	✔

Three-Winding Transformer

three_winding_transformer connects three nodes with possibly different voltage levels.

Note: it can happen that tap_min > tap_max. In this case the winding voltage is decreased if the tap position is increased.

name	data type	unit	description	required	input	update	output	valid values
`u1`	`double`	volt (V)	rated voltage at side 1	✔	✔	❌	❌	`> 0`
`u2`	`double`	volt (V)	rated voltage at side 2	✔	✔	❌	❌	`> 0`
`u3`	`double`	volt (V)	rated voltage at side 3	✔	✔	❌	❌	`> 0`
`sn_1`	`double`	volt-ampere (VA)	rated power at side 1	✔	✔	❌	❌	`> 0`
`sn_2`	`double`	volt-ampere (VA)	rated power at side 2	✔	✔	❌	❌	`> 0`
`sn_3`	`double`	volt-ampere (VA)	rated power at side 3	✔	✔	❌	❌	`> 0`
`uk_12`	`double`	-	relative short circuit voltage across side 1-2, `0.1` means 10%	✔	✔	❌	❌	`>= pk_12 / min(sn_1, sn_2)` and `> 0` and `< 1`
`uk_13`	`double`	-	relative short circuit voltage across side 1-3, `0.1` means 10%	✔	✔	❌	❌	`>= pk_13 / min(sn_1, sn_3)` and `> 0` and `< 1`
`uk_23`	`double`	-	relative short circuit voltage across side 2-3, `0.1` means 10%	✔	✔	❌	❌	`>= pk_23 / min(sn_2, sn_3)` and `> 0` and `< 1`
`pk_12`	`double`	watt (W)	short circuit (copper) loss across side 1-2	✔	✔	❌	❌	`>= 0`
`pk_13`	`double`	watt (W)	short circuit (copper) loss across side 1-3	✔	✔	❌	❌	`>= 0`
`pk_23`	`double`	watt (W)	short circuit (copper) loss across side 2-3	✔	✔	❌	❌	`>= 0`
`i0`	`double`	-	relative no-load current with respect to side 1	✔	✔	❌	❌	`>= p0 / sn` and `< 1`
`p0`	`double`	watt (W)	no-load (iron) loss	✔	✔	❌	❌	`>= 0`
`winding_1`	`WindingType`	-	side 1 winding type	✔	✔	❌	❌
`winding_2`	`WindingType`	-	side 2 winding type	✔	✔	❌	❌
`winding_3`	`WindingType`	-	side 3 winding type	✔	✔	❌	❌
`clock_12`	`int8_t`	-	clock number of phase shift across side 1-2, odd number is only allowed for Dy(n) or Y(N)d configuration.	✔	✔	❌	❌	`>= 0` and `<= 12`
`clock_13`	`int8_t`	-	clock number of phase shift across side 1-3, odd number is only allowed for Dy(n) or Y(N)d configuration.	✔	✔	❌	❌	`>= 0` and `<= 12`
`tap_side`	`BranchSide`	-	side of tap changer	✔	✔	❌	❌	`side_1` or `side_2` or `side_3`
`tap_pos`	`int8_t`	-	current position of tap changer	✔	✔	✔	❌	`(tap_min <= tap_pos <= tap_max)` or `(tap_min >= tap_pos >= tap_max)`
`tap_min`	`int8_t`	-	position of tap changer at minimum voltage	✔	✔	❌	❌
`tap_max`	`int8_t`	-	position of tap changer at maximum voltage	✔	✔	❌	❌
`tap_nom`	`int8_t`	-	nominal position of tap changer	❌ default zero	✔	❌	❌	`(tap_min <= tap_nom <= tap_max)` or `(tap_min >= tap_nom >= tap_max)`
`tap_size`	`double`	volt (V)	size of each tap of the tap changer	✔	✔	❌	❌	`> 0`
`uk_12_min`	`double`	-	relative short circuit voltage at minimum tap, across side 1-2	❌ default same as `uk_12`	✔	❌	❌	`>= pk_12_min / min(sn_1, sn_2)` and `> 0` and `< 1`
`uk_12_max`	`double`	-	relative short circuit voltage at maximum tap, across side 1-2	❌ default same as `uk_12`	✔	❌	❌	`>= pk_12_max / min(sn_1, sn_2)` and `> 0` and `< 1`
`pk_12_min`	`double`	watt (W)	short circuit (copper) loss at minimum tap, across side 1-2	❌ default same as `pk_12`	✔	❌	❌	`>= 0`
`pk_12_max`	`double`	watt (W)	short circuit (copper) loss at maximum tap, across side 1-2	❌ default same as `pk_12`	✔	❌	❌	`>= 0`
`uk_13_min`	`double`	-	relative short circuit voltage at minimum tap, across side 1-3	❌ default same as `uk_13`	✔	❌	❌	`>= pk_13_min / min(sn_1, sn_3)` and `> 0` and `< 1`
`uk_13_max`	`double`	-	relative short circuit voltage at maximum tap, across side 1-3	❌ default same as `uk_13`	✔	❌	❌	`>= pk_13_max / min(sn_1, sn_3)` and `> 0` and `< 1`
`pk_13_min`	`double`	watt (W)	short circuit (copper) loss at minimum tap, across side 1-3	❌ default same as `pk_13`	✔	❌	❌	`>= 0`
`pk_13_max`	`double`	watt (W)	short circuit (copper) loss at maximum tap, across side 1-3	❌ default same as `pk_13`	✔	❌	❌	`>= 0`
`uk_23_min`	`double`	-	relative short circuit voltage at minimum tap, across side 2-3	❌ default same as `uk_23`	✔	❌	❌	`>= pk_23_min / min(sn_2, sn_3)` and `> 0` and `< 1`
`uk_23_max`	`double`	-	relative short circuit voltage at maximum tap, across side 2-3	❌ default same as `uk_23`	✔	❌	❌	`>= pk_23_max / min(sn_2, sn_3)` and `> 0` and `< 1`
`pk_23_min`	`double`	watt (W)	short circuit (copper) loss at minimum tap, across side 2-3	❌ default same as `pk_23`	✔	❌	❌	`>= 0`
`pk_23_max`	`double`	watt (W)	short circuit (copper) loss at maximum tap, across side 2-3	❌ default same as `pk_23`	✔	❌	❌	`>= 0`
`r_grounding_1`	`double`	ohm (Ω)	grounding resistance at side 1, if relevant	❌ default zero	✔	❌	❌
`x_grounding_1`	`double`	ohm (Ω)	grounding reactance at side 1, if relevant	❌ default zero	✔	❌	❌
`r_grounding_2`	`double`	ohm (Ω)	grounding resistance at side 2, if relevant	❌ default zero	✔	❌	❌
`x_grounding_2`	`double`	ohm (Ω)	grounding reactance at side 2, if relevant	❌ default zero	✔	❌	❌
`r_grounding_3`	`double`	ohm (Ω)	grounding resistance at side 3, if relevant	❌ default zero	✔	❌	❌
`x_grounding_3`	`double`	ohm (Ω)	grounding reactance at side 3, if relevant	❌ default zero	✔	❌	❌

Appliance

type name: appliance

appliance is an abstract user which is coupled to a node. For each appliance a switch is defined between the appliance and the node.

The sign of active/reactive power of the appliance depends on the reference direction.

For load reference direction, positive active power means the power flows from the node to the appliance.
For generator reference direction, positive active power means the power flows from the appliance to the node.

name	data type	unit	description	required	input	update	output	valid values
`node`	`int32_t`	-	ID of the coupled node	✔	✔	❌	❌	a valid node id
`status`	`int8_t`	-	connection status to the node	✔	✔	✔	❌	`0` or `1`
`p`	`RealValueOutput`	watt (W)	active power		❌	❌	✔
`q`	`RealValueOutput`	volt-ampere-reactive (var)	reactive power		❌	❌	✔
`i`	`RealValueOutput`	ampere (A)	current		❌	❌	✔
`s`	`RealValueOutput`	volt-ampere (VA)	apparent power		❌	❌	✔
`pf`	`RealValueOutput`	-	power factor		❌	❌	✔

Source

type name: source
reference direction: generator

source is representing the external network with a Thévenin's equivalence. It has an infinite voltage source with an internal impedance. The impedance is specified by convention as short circuit power.

name	data type	unit	description	required	input	update	output	valid values
`u_ref`	`double`	-	reference voltage in per-unit	✨ only for power flow	✔	✔	❌	`> 0`
`u_ref_angle`	`double`	rad	reference voltage angle	❌ default 0.0	✔	✔	❌
`sk`	`double`	volt-ampere (VA)	short circuit power	❌ default 1e10	✔	❌	❌	`> 0`
`rx_ratio`	`double`	-	R to X ratio	❌ default 0.1	✔	❌	❌	`>= 0`
`z01_ratio`	`double`	-	zero sequence to positive sequence impedance ratio	❌ default 1.0	✔	❌	❌	`> 0`

Generic Load and Generator

type name: generic_load_gen

generic_load_gen is an abstract load/generation which contains only the type of the load/generation with response to voltage.

name	data type	unit	description	required	input	update	output
`type`	`LoadGenType`	-	type of load/generator with response to voltage	✔	✔	❌	❌

Load/Generator Concrete Types

There are four concrete types of load/generator. They share similar attributes: specified active/reactive power. However, the reference direction and meaning of RealValueInput is different, as shown in the table below.

type name	reference direction	meaning of `RealValueInput`
`sym_load`	load	`double`
`sym_gen`	generator	`double`
`asym_load`	load	`double[3]`
`asym_gen`	generator	`double[3]`

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output
`p_specified`	`RealValueInput`	watt (W)	specified active power	✨ only for power flow	✔	✔	❌
`q_specified`	`RealValueInput`	volt-ampere-reactive (var)	specified reactive power	✨ only for power flow	✔	✔	❌

Shunt

type name: shunt
reference direction: load

shunt is an appliance with a fixed admittance (impedance). It behaves similar to a load/generator with type const_impedance.

name	data type	unit	description	required	input	update	output
`g1`	`double`	siemens (S)	positive-sequence shunt conductance	✔	✔	❌	❌
`b1`	`double`	siemens (S)	positive-sequence shunt susceptance	✔	✔	❌	❌
`g0`	`double`	siemens (S)	zero-sequence shunt conductance	✨ only for asymmetric calculation	✔	❌	❌
`b0`	`double`	siemens (S)	zero-sequence shunt susceptance	✨ only for asymmetric calculation	✔	❌	❌

Sensor

type name: sensor

sensor is an abstract type for all the sensor types. A sensor does not have any physical meaning. Rather, it provides measurement data for the state estimation algorithm. The state estimator uses the data to evaluate the state of the grid with the highest probability.

name	data type	unit	description	required	input	update	output	valid values
`measured_object`	`int32_t`	-	id of the measured object	✔	✔	❌	❌	a valid object id

Generic Voltage Sensor

type name: generic_voltage_sensor

generic_voltage_sensor is an abstract class for symmetric and asymmetric voltage sensor. It measures the magnitude and (optionally) the angle of the voltage of a node.

name	data type	unit	description	required	input	update	output	valid values
`u_sigma`	`double`	volt (V)	standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3.	✨ only for state estimation	✔	✔	❌	`> 0`

Voltage Sensor Concrete Types

There are two concrete types of voltage sensor. They share similar attributes: the meaning of RealValueInput is different, as shown in the table below. In a sym_voltage_sensor the measured voltage is a line-to-line voltage. In a asym_voltage_sensor the measured voltage is a 3-phase line-to-ground voltage.

type name	meaning of `RealValueInput`
`sym_voltage_sensor`	`double`
`asym_voltage_sensor`	`double[3]`

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output	valid values
`u_measured`	`RealValueInput`	volt (V)	measured voltage magnitude	✨ only for state estimation	✔	✔	❌	`> 0`
`u_angle_measured`	`RealValueInput`	rad	measured voltage angle (only possible with phasor measurement units)	❌	✔	✔	❌
`u_residual`	`RealValueOutput`	volt (V)	residual value between measured voltage magnitude and calculated voltage magnitude		❌	❌	✔
`u_angle_residual`	`RealValueOutput`	rad	residual value between measured voltage angle and calculated voltage angle (only possible with phasor measurement units)		❌	❌	✔

Generic Power Sensor

type name: generic_power_sensor

power_sensor is an abstract class for symmetric and asymmetric power sensor. It measures the active/reactive power flow of a terminal. The terminal is either connecting an appliance and a node, or connecting the from/to end of a branch and a node. In case of a terminal between an appliance and a node, the power reference direction in the measurement data is the same as the reference direction of the appliance. For example, if a power_sensor is measuring a source, a positive p_measured indicates that the active power flows from the source to the node.

name	data type	unit	description	required	input	update	output	valid values
`measured_terminal_type`	`MeasuredTerminalType`	-	indicate if it measures an `appliance` or a `branch`	✔	✔	❌	❌	the terminal type should match the `measured_object`
`power_sigma`	`double`	volt-ampere (VA)	standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3.	✨ only for state estimation	✔	✔	❌	`> 0`

Power Sensor Concrete Types

There are two concrete types of power sensor. They share similar attributes: the meaning of RealValueInput is different, as shown in the table below.

type name	meaning of `RealValueInput`
`sym_power_sensor`	`double`
`asym_power_sensor`	`double[3]`

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output
`p_measured`	`RealValueInput`	watt (W)	measured active power	✨ only for state estimation	✔	✔	❌
`q_measured`	`RealValueInput`	volt-ampere-reactive (var)	measured reactive power	✨ only for state estimation	✔	✔	❌
`p_residual`	`RealValueOutput`	watt (W)	residual value between measured active power and calculated active power		❌	❌	✔
`q_residual`	`RealValueOutput`	volt-ampere-reactive (var)	residual value between measured reactive power and calculated reactive power		❌	❌	✔

Selection of calculation method

There are four power-flow algorithms and one state estimation algorithm available in power-grid-model. Some methods use a prefactorization feature which is also described in this section.

Power-flow algorithms

Following are guidelines to be considered while selecting a power-flow CalculationMethod for your application:

Iterative methods

These should be selected when exact solution is required within specified error_tolerance.

CalculationMethod.newton_raphson: Traditional Newton-Raphson method.
CalculationMethod.iterative_current: Newton-Raphson would be more robust in achieving convergence and require less iterations. However, Iterative current can be faster most times because it uses matrix prefactorization.

Linear methods

Linear approximation methods are many times faster than the iterative methods. Can be used where approximate solutions are acceptable. Both methods have equal computation time for a single powerflow calculation.

CalculationMethod.linear: It will be more accurate when most of the load/generation types are of constant impedance.
CalculationMethod.linear_current: It will be more accurate when most of the load/generation types are constant power or constant current. Batch calculations will be faster because matrix prefacorization is possible.

State Estimation algorithms

Following are guidelines to be considered while selecting a state estimation CalculationMethod for your application:

CalculationMethod.iterative_linear: It is an iterative method which converges to a true solution. Matrix prefactorization is possible.

Matrix Prefactorization

Every iteration of power-flow or state estimation has a step of solving large number of sparse linear equations i.e. AX=b in matrix form. Computation wise this is a very expensive step. One major component of this step is factorization of the A matrix. In certain calculation methods, this A matrix and its factorization remains unchanged over iterations and batches (only specific cases) which makes it possible reuse the factorization, skip this step and improve performance.

Note: Prefactorization over batches is possible when switching status or specified power values of load/generation or source reference voltage is modified. It is not possible when topology or grid parameters are modified, i.e. in switching of branches, shunt, sources or change in transformer tap positions.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

graph-data-model.md

graph-data-model.md

Graph Data Model

Enumerations

Component Type Hierarchy and Graph Data Model

Symmetry of Components and Calculation

Attributes of Components

Validation

Component Types

Base

Node

Branch

Line

Link

Transformer

Branch3

Three-Winding Transformer

Appliance

Source

Generic Load and Generator

Load/Generator Concrete Types

Shunt

Sensor

Generic Voltage Sensor

Voltage Sensor Concrete Types

Generic Power Sensor

Power Sensor Concrete Types

Selection of calculation method

Power-flow algorithms

Iterative methods

Linear methods

State Estimation algorithms

Matrix Prefactorization

Files

graph-data-model.md

Latest commit

History

graph-data-model.md

File metadata and controls

Graph Data Model

Enumerations

Component Type Hierarchy and Graph Data Model

Symmetry of Components and Calculation

Attributes of Components

Validation

Component Types

Base

Node

Branch

Line

Link

Transformer

Branch3

Three-Winding Transformer

Appliance

Source

Generic Load and Generator

Load/Generator Concrete Types

Shunt

Sensor

Generic Voltage Sensor

Voltage Sensor Concrete Types

Generic Power Sensor

Power Sensor Concrete Types

Selection of calculation method

Power-flow algorithms

Iterative methods

Linear methods

State Estimation algorithms

Matrix Prefactorization