{"id":9192,"library":"power-grid-model","title":"Power Grid Model","description":"Power Grid Model is a Python/C++ library designed for high-performance steady-state distribution power system analysis. It provides functionalities for Power Flow, State Estimation, and Short Circuit calculations, with its core implemented in C++ for efficiency. The library is actively developed, with frequent releases providing new features and improvements.","status":"active","version":"1.13.54","language":"en","source_language":"en","source_url":"https://github.com/PowerGridModel/power-grid-model","tags":["power systems","electrical engineering","simulation","power flow","state estimation","short circuit","numpy"],"install":[{"cmd":"pip install power-grid-model","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required Python version.","package":"python","version":">=3.12","optional":false},{"reason":"Used for structured arrays, the primary data exchange format with the C++ core.","package":"numpy","optional":false}],"imports":[{"symbol":"PowerGridModel","correct":"from power_grid_model import PowerGridModel"},{"note":"The `initialize_array` function is directly available from the top-level `power_grid_model` package, not a submodule like `utils`.","wrong":"from power_grid_model.utils import initialize_array","symbol":"initialize_array","correct":"from power_grid_model import initialize_array"},{"symbol":"AttributeType","correct":"from power_grid_model import AttributeType"},{"symbol":"ComponentType","correct":"from power_grid_model import ComponentType"},{"symbol":"DatasetType","correct":"from power_grid_model import DatasetType"}],"quickstart":{"code":"import numpy as np\nfrom power_grid_model import PowerGridModel, initialize_array, ComponentType, AttributeType, DatasetType\n\n# 1. Define input data using structured NumPy arrays\n# Node data\nnode_data = initialize_array(DatasetType.input, ComponentType.node, 2)\nnode_data[AttributeType.id] = [1, 2]\nnode_data[AttributeType.u_rated] = [10.5e3, 10.5e3] # 10.5 kV rated voltage\n\n# Line data\nline_data = initialize_array(DatasetType.input, ComponentType.line, 1)\nline_data[AttributeType.id] = [3]\nline_data[AttributeType.from_node] = [1]\nline_data[AttributeType.to_node] = [2]\nline_data[AttributeType.r1] = [0.1] # Resistance\nline_data[AttributeType.x1] = [0.2] # Reactance\n\n# Symmetric load data for node 2\nsym_load_data = initialize_array(DatasetType.input, ComponentType.sym_load, 1)\nsym_load_data[AttributeType.id] = [4]\nsym_load_data[AttributeType.node] = [2]\nsym_load_data[AttributeType.p_const] = [1e5] # 100 kW constant power\nsym_load_data[AttributeType.q_const] = [5e4] # 50 kVAr constant reactive power\n\n# Source data for node 1\nsource_data = initialize_array(DatasetType.input, ComponentType.source, 1)\nsource_data[AttributeType.id] = [5]\nsource_data[AttributeType.node] = [1]\nsource_data[AttributeType.u_ref] = [1.0] # 1.0 p.u. voltage reference\nsource_data[AttributeType.u_rated] = [10.5e3]\n\ninput_data = {\n    ComponentType.node: node_data,\n    ComponentType.line: line_data,\n    ComponentType.sym_load: sym_load_data,\n    ComponentType.source: source_data\n}\n\n# 2. Create the power grid model instance\nmodel = PowerGridModel(system_frequency=50.0, input_data=input_data)\n\n# 3. Perform a power flow calculation\noutput_data = model.calculate_power_flow()\n\n# 4. Access results (example: node voltages)\nnode_output = output_data[ComponentType.node]\nprint(\"Node Voltage Results:\")\nfor node_id, voltage in zip(node_output[AttributeType.id], node_output[AttributeType.u]):\n    print(f\"Node {node_id}: {voltage:.2f} V\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Check release notes for alternatives or updated sensor types if your workflow relies on this specific sensor functionality.","message":"The 'node injection power sensor' is being deprecated.","severity":"deprecated","affected_versions":"Potentially upcoming versions, observe changelogs for removal."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"IDWrongType: Wrong type for object with id X"},{"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.","cause":"Underlying data issues were not caught by the C++ core's exceptions or were silently handled, leading to erroneous internal states or calculations.","error":"Model initialization or calculation fails without a clear error message from the core library, or produces unexpected results."}]}