Quick Start

In this quick start a simple 10kV network as below is calculated. A line connects two nodes. One node has a source. The other node has a symmetric load.

node_1 ---line_3--- node_2
 |                    |
source_5            sym_load_4

The library uses a graph data model to represent the physical components and their attributes, see Graph Data Model.

Before we start working on the network, we need first import the main model class as well as some helper functions for enumerations and meta data.

from power_grid_model import AttributeType, ComponentType, DatasetType, initialize_array, LoadGenType, PowerGridModel
from power_grid_model.utils import self_test

A basic self_test function is provided to check if the installation was successful and there are no build errors, segmentation violations, undefined symbols, etc. The function should be imported and called by a user by running following commands:

self_test()

Input Data

The library uses dictionaries of numpy structured arrays as the main (input and output) data exchange format between Python interface and C++ core. Detailed design of data interface can be found in Native Data Interface.

The helper function power_grid_model.initialize_array can be used to easily generate an array of the correct format.

# node
node = initialize_array(DatasetType.input, ComponentType.node, 2)
node[AttributeType.id] = [1, 2]
node[AttributeType.u_rated] = [10.5e3, 10.5e3]

The code above generates a node input array with two nodes, and assigns the attributes of the nodes to the array. A dictionary of such arrays is used for input_data and update_data. This row based format is the most common way to start, but the same dataset can also use a columnar format where each component maps to a dictionary of attribute arrays. Columnar data can be useful when a component has many optional attributes, for example in large batch calculations. See Dataset Terminology and Native Data Interface for details.

# line
line = initialize_array(DatasetType.input, ComponentType.line, 1)
line[AttributeType.id] = [3]
line[AttributeType.from_node] = [1]
line[AttributeType.to_node] = [2]
line[AttributeType.from_status] = [1]
line[AttributeType.to_status] = [1]
line[AttributeType.r1] = [0.25]
line[AttributeType.x1] = [0.2]
line[AttributeType.c1] = [10e-6]
line[AttributeType.tan1] = [0.0]
line[AttributeType.i_n] = [1000]
# load
sym_load = initialize_array(DatasetType.input, ComponentType.sym_load, 1)
sym_load[AttributeType.id] = [4]
sym_load[AttributeType.node] = [2]
sym_load[AttributeType.status] = [1]
sym_load[AttributeType.type] = [LoadGenType.const_power]
sym_load[AttributeType.p_specified] = [2e6]
sym_load[AttributeType.q_specified] = [0.5e6]
# source
source = initialize_array(DatasetType.input, ComponentType.source, 1)
source[AttributeType.id] = [5]
source[AttributeType.node] = [1]
source[AttributeType.status] = [1]
source[AttributeType.u_ref] = [1.0]
# all
input_data = {
    ComponentType.node: node,
    ComponentType.line: line,
    ComponentType.sym_load: sym_load,
    ComponentType.source: source
}

Another example of how to create components can be found in Input data.

Note

The keys of the dictonary of arrays are unique and should match with the respective type name of the component. See, e.g., that type name of node is ComponentType.node.

Instantiate Model

We can instantiate the model by calling the constructor of power_grid_model.PowerGridModel:

model = PowerGridModel(input_data, system_frequency=50.0)

Power Flow Calculation

To run calculations, use the object methods power_grid_model.PowerGridModel.calculate_power_flow or power_grid_model.PowerGridModel.calculate_state_estimation functions. Refer Calculations for more details on the many optional arguments.

result = model.calculate_power_flow()

Both input and output data are dictionaries of structured numpy arrays. We can use pandas to convert them to data frames and print them.

import pandas as pd

print('Node Input')
print(pd.DataFrame(input_data[ComponentType.node]))
print('Node Result')
print(pd.DataFrame(result[ComponentType.node]))

The result data can then be viewed in tabular forms.

Node Input
   id  u_rated
0   1  10500.0
1   2  10500.0
Node Result
   id  energized      u_pu             u   u_angle             p              q
0   1          1  0.999964  10499.619561 -0.000198  2.009413e+06  162978.063374
1   2          1  0.994801  10445.415523 -0.003096 -2.000000e+06 -500000.000000

Validation

To validate the input_data and update_data for valid values, use power_grid_model.validation.validate_input_data and power_grid_model.validation.validate_batch_data. Refer to Data Validator for more details.

Batch Data

You can calculate a (large) number of scenarios using one command and even in parallel threading. This is what makes Power Grid Model a powerful calculation engine. You need to create a batch update dataset and put it in the update_data argument of calculate_power_flow. Please refer to Power Flow Example for a detailed tutorial about how to execute batch calculations.