repository·main·Indexed 42 days ago
https://github.com/powergridmodel/power-grid-modelA high-performance Python/C++ library for steady-state distribution power system analysis. It supports Power Flow, State Estimation, and Short Circuit calculations via C++ cores with Python and C interfaces.
power-grid-model is a high-performance library designed for steady-state distribution power system analysis. It provides interfaces for both Python and C, with its core implementation written in C++.
Supported calculations include:
For data conversion utilities, see the power-grid-model-io repository. For an extended Python interface, see the power-grid-model-ds repository.
The power-grid-model is a library for steady-state distribution power system analysis, hosted by the Linux Foundation Energy. It is written in C++ and provides interfaces for both Python and C.
Supported calculation types (both symmetric and asymmetric):
power-grid-model format.The repository is organized into several distinct components based on the language and interface used. Use this guide to locate specific parts of the codebase:
power_grid_model_c/power_grid_model/include/power_grid_model.power_grid_model_c/power_grid_model_c.src/power_grid_model.src/power_grid_model/validation.power_grid_model_c_example.tests folder contains several sub-directories:cpp_unit_tests: Unit tests for the C++ core.cpp_integration_tests: Integration tests for the C++ core.cpp_validation_tests: Validation test cases for the C++ core.c_api_tests: Tests for the C API communication layer.benchmark_cpp: C++ benchmark test case generator.package_tests: A CMake project to verify the C API package installation.unit: Python code tests.tests/data folder contains validation test cases for components and algorithms, as well as sample network types. These are validated against hand calculations or popular power system analysis software.The repository provides three distinct ways to build and use the library:
power-grid-model package available on PyPI that uses a C++ extension as its calculation core..dll, .so, or .dylib) with a stable pure C API/ABI.If you only intend to develop the Python side, use the provided development container to set up the environment automatically.
The LU solver in the power grid model is a hybrid system designed to handle large-scale power system equations efficiently. It consists of two primary components:
LUFullPiv algorithm.The solver uses an in-place decomposition approach and supports pivot perturbation to improve numerical stability.
The power grid model uses a modified backward error calculation to prevent rounding errors in single rows from causing iterative refinement to fail. The calculation uses a denominator cap determined by a parameter $\epsilon$.
To ensure numerical stability, $\epsilon$ should be chosen to be small, but large enough to suppress numerical instabilities.
Mathematical Formula:
$$ \begin{aligned} D_{\text{max}} &= \max_i\left{ \left(\left|\mathbf{M}\right|\cdot\left|\boldsymbol{x}\right| + \left|\boldsymbol{b}\right|\right)_i \right} \ \text{backward_error} &= \max_i \left{ \frac{|\boldsymbol{r}|i}{ \max\left{ \left(\left|\mathbf{M}\right|\cdot\left|\boldsymbol{x}\right| + \left|\boldsymbol{b}\right|\right)i, \epsilon{\text{backward_error}} D{\text{max}} \right} \right} \end{aligned} $$
appliance is an abstract user component that is coupled to a node. Every appliance includes a switch between itself and the node to control connectivity. The direction of power flow for an appliance is determined by its specific type (e.g., source is a generator, shunt is a load).When multiple sensors measure the same physical quantity (e.g., multiple voltage sensors on a single bus), power-grid-model can merge these into a single virtual measurement using a Kalman filter approach.
The aggregated measurement $z$ is calculated as:
$$z = \dfrac{\sum_{k=1}^{N_{sensor}} z_k \sigma_k^{-2}}{\sum_{k=1}^{N_{sensor}} \sigma_k^{-2}}$$
Where $z_k$ and $\sigma_k$ are the measured value and standard deviation of the $k$-th individual sensor.
To avoid breaking changes when new calculation parameters are added, the C API uses an opaque PGM_Options object instead of passing individual arguments to PGM_calculate.
Workflow:
PGM_create_options.PGM_set_* functions.PGM_Options pointer to PGM_calculate.The model uses two special data types for handling real-valued numerical data, which vary depending on whether the calculation is symmetric or asymmetric:
RealValueInput: Used for input attributes.sym_load): A double.asym_load): A double[3] (array of 3 doubles).RealValueOutput: Used for output attributes.double.double[3].The power-grid-model calculation core is written in C++. To exchange data between Python and the C++ core, the library uses a dictionary of NumPy structured arrays.
In this format:
ComponentType (e.g., node, transformer).struct definitions used by the core.For development, use CMake presets to enable all tests, warnings, examples, and benchmarks. These presets use the Ninja generator.
Available targets in a developer build include:
power_grid_model_c: The stable pure C API/ABI dynamic library.tests/cpp_unit_tests_*: C++ core unit tests using doctest.tests/cpp_validation_tests: Validation tests using doctest.tests/native_api_tests: C API tests using doctest.tests/benchmark_cpp: C++ performance benchmarks.power_grid_model_c_example: An example C program.To see available presets, use cmake --list-presets.