Power Grid Model

power-grid-model is a Python library for steady-state distribution power system analysis. The core of the library is written in C++. Currently, it supports the following calculations:

• Symmetric and asymmetric power flow calculation with Newton-Raphson method and linear method
• Symmetric and asymmetric state estimation with iterative linear method

Installation

Runtime Dependencies

The only Python runtime dependency is numpy. It will be automatically installed as the requirements. Moreover, the library optionally depends on Intel Math Kernel Library (mkl), for its PARDISO sparse solver. It is recommended to install mkl because it gives huge performance boosts.

The easiest way to install mkl is using pip or conda:

pip install mkl

or

conda install -c conda-forge mkl

You need to add the path to the mkl runtime file libmkl_rt.so or mkl_rt.dll the environment variable LD_LIBRARY_PATH in Linux or Path in Windows (conda does this automatically in the environment). If the library can find mkl runtime, it uses it as the sparse solver. It is recommended to set the environment variable MKL_THREADING_LAYER to SEQUENTIAL, as multi-threading is handled in a higher level. If the library cannot find mkl runtime, it will fall back to an internally built-in (and much slower) Eigen SparseLU solver.

Install from Pre-built Binary Package

The power-grid-model python package is pre-built for Windows, Linux, and macOS (both Intel and Arm-based), for Python version 3.8, 3.9, and 3.10. You can directly install the package from PyPI.

pip install power-grid-model

Build and install from Source

To install the library from source, refer to the Build Guide.

Quick Start

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

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.

Firstly, import the main model class as well as some helper functions for enumerations and meta data.

from power_grid_model import LoadGenType
from power_grid_model import PowerGridModel
from power_grid_model import initialize_array

Input Data

The library uses dictionary of numpy structured arrays as the main (input and output) data exchange format between Python and C++ core. The documentation Native Data Interface explains the detailed design of this interface.

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

# node
node = initialize_array('input', 'node', 2)
node['id'] = [1, 2]
node['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. Similarly, we can create input arrays for line, load, and generation.

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

Instantiate Model

We can instantiate the model by calling the constructor of PowerGridModel

model = PowerGridModel(input_data, system_frequency=50.0)

Power Flow Calculation

To calculate power flow, call the method calculate_power_flow. This method has many optional arguments, see Python API Reference for a detailed explanation.

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.

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

You can print the data in tables.

Node Input
   id  u_rated
0   1  10500.0
1   2  10500.0
Node Result
   id  energized      u_pu             u   u_angle
0   1          1  0.999964  10499.619561 -0.000198
1   2          1  0.994801  10445.415523 -0.003096

Examples

Please refer to Examples for more detailed examples for power flow and state estimation.

License

This project is licensed under the Mozilla Public License, version 2.0 - see LICENSE for details.

Licenses third-party libraries

This project includes third-party libraries, which are licensed under their own respective Open-Source licenses. SPDX-License-Identifier headers are used to show which license is applicable. The concerning license files can be found in the LICENSES directory.

Intel Math Kernel Library License

The power-grid-model does not bundle or redistribute any MKL runtime library. It only detects if MKL library is installed in the target system. If so, it will use the library to accelerate the calculation. The user is responsible to acquire a suitable MKL license.

Contributing

Please read CODE_OF_CONDUCT and CONTRIBUTING for details on the process for submitting pull requests to us.

Contact

Please read SUPPORT for how to connect and get into contact with the Power Gird Model project.