powergridmodel

Power Grid Model

Overview

power-grid-model is a high-performance C++ library with a Python interface for steady-state distribution power system analysis. It operates on numpy structured arrays via a dictionary-based data model and supports symmetric (single-phase equivalent) and asymmetric (full three-phase) calculations.

Version: v1.13.134 Language: Python (C++ core) License: Mozilla Public License 2.0 (MPL-2.0) Repo: https://github.com/PowerGridModel/power-grid-model

Quick Start

from power_grid_model import PowerGridModel, LoadGenType, initialize_array

# Build component arrays
node = initialize_array('input', 'node', 2)
node['id'] = [1, 2]; node['u_rated'] = [10.5e3, 10.5e3]

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]

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 = initialize_array('input', 'source', 1)
source['id'] = [5]; source['node'] = [1]; source['status'] = [1]; source['u_ref'] = [1.0]

input_data = {'node': node, 'line': line, 'sym_load': sym_load, 'source': source}

model = PowerGridModel(input_data, system_frequency=50.0)
result = model.calculate_power_flow()
# result['node'] contains: id, energized, u_pu, u_angle, u, p, q

Core Concepts

• Input format: dict[str, np.ndarray] — structured arrays created via initialize_array(data_type, component_type, shape). Dataset types: input, update, sym_output, asym_output, sc_output.
• Symmetric vs asymmetric: symmetric=True (default) solves a balanced single-phase equivalent; symmetric=False solves the full three-phase abc system and requires zero-sequence parameters.
• Batch calculations: Pass update_data (2-D dense array or sparse CSR dict) to run many scenarios in one call. Pass list[BatchDataset] for Cartesian product dimensions (time-series x contingency).
• All IDs must be globally unique across all component types in the same scenario.
• NaN as sentinel: Unset optional fields carry NaN/int-min sentinel values from initialize_array; do not leave required fields as NaN.