Install & Compatibility
Where this runs
tested against v1.10.41 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.369s · 96.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.3s · import 0.380s · 90MB
97MB installed
● package 97MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PowerGridModel
✓ from power_grid_model import PowerGridModel
initialize_array
✓ from power_grid_model import initialize_array
✗ from power_grid_model.utils import initialize_array
The `initialize_array` function is directly available from the top-level `power_grid_model` package, not a submodule like `utils`.
AttributeType
✓ from power_grid_model import AttributeType
ComponentType
✓ from power_grid_model import ComponentType
DatasetType
✓ from power_grid_model import DatasetType
This quickstart demonstrates how to set up a simple two-node, one-line network with a source and a symmetric load, create a `PowerGridModel` instance, perform a power flow calculation, and retrieve the results. Data is provided as dictionaries of NumPy structured arrays, which is the native data interface for the C++ core.
import numpy as np
from power_grid_model import PowerGridModel, initialize_array, ComponentType, AttributeType, DatasetType
# 1. Define input data using structured NumPy arrays
# Node data
node_data = initialize_array(DatasetType.input, ComponentType.node, 2)
node_data[AttributeType.id] = [1, 2]
node_data[AttributeType.u_rated] = [10.5e3, 10.5e3] # 10.5 kV rated voltage
# Line data
line_data = initialize_array(DatasetType.input, ComponentType.line, 1)
line_data[AttributeType.id] = [3]
line_data[AttributeType.from_node] = [1]
line_data[AttributeType.to_node] = [2]
line_data[AttributeType.r1] = [0.1] # Resistance
line_data[AttributeType.x1] = [0.2] # Reactance
# Symmetric load data for node 2
sym_load_data = initialize_array(DatasetType.input, ComponentType.sym_load, 1)
sym_load_data[AttributeType.id] = [4]
sym_load_data[AttributeType.node] = [2]
sym_load_data[AttributeType.p_const] = [1e5] # 100 kW constant power
sym_load_data[AttributeType.q_const] = [5e4] # 50 kVAr constant reactive power
# Source data for node 1
source_data = initialize_array(DatasetType.input, ComponentType.source, 1)
source_data[AttributeType.id] = [5]
source_data[AttributeType.node] = [1]
source_data[AttributeType.u_ref] = [1.0] # 1.0 p.u. voltage reference
source_data[AttributeType.u_rated] = [10.5e3]
input_data = {
ComponentType.node: node_data,
ComponentType.line: line_data,
ComponentType.sym_load: sym_load_data,
ComponentType.source: source_data
}
# 2. Create the power grid model instance
model = PowerGridModel(system_frequency=50.0, input_data=input_data)
# 3. Perform a power flow calculation
output_data = model.calculate_power_flow()
# 4. Access results (example: node voltages)
node_output = output_data[ComponentType.node]
print("Node Voltage Results:")
for node_id, voltage in zip(node_output[AttributeType.id], node_output[AttributeType.u]):
print(f"Node {node_id}: {voltage:.2f} V")
Debug
Known issues
gotchaThe C++ core's exceptions may not always be clear. It is highly recommended to validate input data using `power_grid_model.validation.validate_input_data()` or `assert_valid_input_data()` before constructing a `PowerGridModel` instance to catch errors early.fixAlways run `from power_grid_model.validation import validate_input_data` and call `validate_input_data(input_data, calculation_type, symmetric)` on your data before model instantiation or calculation. Use `assert_valid_input_data` for a more assertive check that raises an exception on invalid data.
affects: All
gotchaSkipping data validation can lead to silently incorrect results. Not all data errors in the input will necessarily raise an exception from the C++ core; some may just yield invalid calculation outcomes without an explicit warning.fixAs per the prior warning, utilize the validation module consistently. If using large datasets, validate smaller, representative slices as the validator itself is not performance-optimized.
affects: All
deprecatedThe 'node injection power sensor' is being deprecated.fixCheck release notes for alternatives or updated sensor types if your workflow relies on this specific sensor functionality.
affects: Potentially upcoming versions, observe changelogs for removal.
Errors
Common errors & fixes
IDWrongType: Wrong type for object with id X
Input data attributes (e.g., node IDs, voltage ratings, impedances) are provided with an incorrect or incompatible NumPy data type for a specific component or attribute.
fixEnsure that the `dtype` of the NumPy array used for each attribute matches the expected type for that attribute (e.g., integers for IDs, float64 for most numerical values). The `initialize_array` helper function correctly sets these types, so prefer using it. If manually creating arrays, verify `dtype` carefully.
Model initialization or calculation fails without a clear error message from the core library, or produces unexpected results.
Underlying data issues were not caught by the C++ core's exceptions or were silently handled, leading to erroneous internal states or calculations.
fixImplement robust input data validation using `power_grid_model.validation.assert_valid_input_data()` or `validate_input_data()` prior to calling `PowerGridModel()` or calculation methods. This will provide more descriptive Python-level validation errors.
Upgrade
Version history
1.13.95latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
numpyrequiredUsed for structured arrays, the primary data exchange format with the C++ core.