Power Grid Model

Common errors

• IDWrongType: Wrong type for object with id X

  cause 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.
  fix Ensure 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.

  cause Underlying data issues were not caught by the C++ core's exceptions or were silently handled, leading to erroneous internal states or calculations.
  fix Implement 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.

Warnings

• gotcha The 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.
  Fix: Always 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.
• gotcha Skipping 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.
  Fix: As 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.
• deprecated The 'node injection power sensor' is being deprecated.
  Fix: Check release notes for alternatives or updated sensor types if your workflow relies on this specific sensor functionality.

Install

• pip install power-grid-model Install from PyPI

Imports

• PowerGridModel

  from power_grid_model import PowerGridModel

• initialize_array
  wrong:

  from power_grid_model.utils import initialize_array

  correct:

  from power_grid_model 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

Quickstart

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")