Power Grid Model

power-grid-model is a library for steady-state distribution power system analysis, hosted by the Linux Foundation Energy (see also the LF Energy landing page). It is distributed for Python and C. The core of the library is written in C++. Currently, it supports both symmetric and asymmetric calculations for the following calculation types:

• Power Flow

• State Estimation

• Short Circuit

Ecosystem & Extensions

Enhance your workflow or convert your network data using these official and community repositories:

• Extended Python Interface (PGM-DS): For a high-level, extended Python interface to the model, refer to the power-grid-model-ds repository.

• Data Conversions (Official): For converting various standard data formats to the Power Grid Model, refer to the official power-grid-model-io repository.

• CGMES Conversions (Community): For ENTSO-E CIM/CGMES datasets, you can use the third-party CGMES2PGM Converter to generate PGM input data. For dataset uploading and state estimation workflows, refer to the accompanying CGMES2PGM Suite.

Note

Do you wish to be updated on the latest news and releases? Subscribe to the Power Grid Model mailing list by sending an (empty) email to: powergridmodel+subscribe@lists.lfenergy.org

Install from PyPI

You can directly install the package from PyPI.

pip install power-grid-model

Install from Conda

If you are using conda, you can directly install the package from conda-forge channel.

conda install -c conda-forge power-grid-model

Installation via Homebrew

If you are using the C API with brew, you can install the C API (and experimental C++ wrapper) directly:

brew install powergridmodel/pgm/power-grid-model

If you are interested in having this package in homebrew-core, please consider contributing the formula, in conformance to their documentation.

Build and install from Source

To install the library from source, refer to the Build Guide.

Citations

If you are using Power Grid Model in your research work, please consider citing our library using the references in Citation.

Contents

Detailed contents of the documentation are structured as follows.

• Power Grid Model
• Quick Start
  • Input Data
  • Instantiate Model
  • Power Flow Calculation
  • Validation
  • Batch Data

User Manual

• Component Type Hierarchy and Graph Data Model
  • Symmetry of Components and Calculation
  • Reference Direction
• Dataset Terminology
  • Buffer Type
  • Buffer Representation
  • Component Dataset Independency
  • Component Data Uniformity
  • Serialization Representation
  • Data structures
  • Terminologies related to data structures
  • Attributes of Components
• Components
  • Base
  • Node
  • Edge
  • Branch
  • Branch3
  • Appliance
  • Sensor
  • Fault
  • Regulator
  • Other components
• Calculations
  • Calculation types
  • Batch Calculations
• Grid Component Modeling
  • Ideal transformer
  • Grounding transformer
  • Phase-shifting transformer
  • Choke coil
  • Cable
  • Ideal source
• Guidelines for performance enhancement
  • Scalability
  • Data validity
  • Data format
  • Batch calculations
  • Parallel computing
  • Matrix prefactorization
• Data Validator
  • Validation Errors
  • Validation functions
• Model validation
  • Minimal test cases in pandapower
  • Distribution network case
  • Transmission network case
  • Vision validation case
  • Short Circuit Calculation cases
  • Other library validation
  • Test case creation
• Serialization
  • Serialization format
  • Known limitations

API Reference

• power_grid_model (Python API)
  • PowerGridModel
  • initialize_array()
  • attribute_dtype()
  • attribute_empty_value()
  • power_grid_meta_data
  • enum
  • data types
  • error types
  • typing
  • validation
  • logging
  • utils
• power_grid_model_c (C API)
  • Main Header
  • Basics
  • Handle
  • Meta Data
  • Buffer
  • Dataset
  • Options
  • Model
  • Logger
  • Serialization
  • Dataset Definitions

Examples

• Power Flow Example
  • Example Network
  • Input Dataset
  • Validation (optional)
  • Construction
  • One-time Power Flow Calculation
  • Update Model
  • Batch Calculation
  • Error Handling
  • Power flow calculations with automatic tap changing
• Serialization example
  • Load dependencies
  • Load a dataset from a JSON file
  • Run power flow calculation on the loaded input data
  • Serialize the output dataset
  • Msgpack serialization
  • Selective deserialization and dataset format
• State Estimation Example
  • Example Network
  • Input Dataset
  • Validation (optional)
  • Construction
  • One-time State Estimation Calculation
  • Observability
  • Batch calculation
• Short Circuit Example
  • Example Network
  • Input Dataset
  • Validation (optional)
  • Construction
  • One-time Short circuit Calculation
  • Batch Calculations
• Multi-dimensional batch calculation example
  • Why are multi-dimensional batch calculations relevant?
  • Example Network
  • Input data and model construction
  • Batch Calculation
• Validation Examples
  • Batch datasets
• Make Test Dataset
  • Structure of Validation Datasets
  • Helper Functions to Import and Export
  • Import and Export Batch Update/Result Dataset
  • Detailed configuration with the params.json
• Asymmetric Calculation Example
  • Example Network
  • Power Flow Calculation
  • Batch Asymmetric Power Flow Calculation
  • Asymmetric State Estimation
• Transformer Example
  • Transformer (Two-winding Transformer)
  • Three-Winding Transformer
  • Power flow calculations with automatic tap changing
• Generic Branch Examples
  • Generic Branch Representation of a Three-winding Transformer
  • Generic Branch Representation for Line, Transformer and PST
  • Using the Generic Branch with CIM/CGMES Data
• Asym Line Example
  • Asym Line
• Logging Example
  • Example Network
  • Imports
  • Build the Input Dataset
  • Text Logger
  • Benchmark Logger
  • Multiple Simultaneous Loggers
  • Accumulation and Clearing Content
  • Reuse Across Runs
  • Python Logging Integration
  • Batch Calculations
  • Usage notes

Algorithms

• Power Flow Algorithm Details
  • Nodal Equations
  • Newton-Raphson power flow
  • Iterative current power flow
  • Linear power flow
  • Linear current power flow
• Automatic Tap Changing Algorithm Details
  • Control logic for power flow with automatic tap changing
  • Initialization and exploitation of regulated transformers
  • Search methods used for tap changing optimization
  • Regulatable voltage range outside u_band
  • Error type MaxIterationReached
• Short Circuit Algorithm Details
  • Short Circuit Equations
  • IEC 60909 short circuit calculation
  • Prefault voltages
• State Estimation Algorithm Details
  • Weighted Least Squares Formulation
  • State Estimation Measurement Aggregation
  • State Estimate Sensor Transformations
  • Iterative linear state estimation
  • Newton-Raphson state estimation
• LU Solver
  • Background
  • Implementation
• Dense and selective matrix inverses
  • Dense inverse
  • Selective inverse

Advanced documentation

• Native Data Interface
  • Structured Array
  • Columnar data format
  • Creating Dataset
  • Basic Data Types
  • Meta-data Helper Module
• Build Guide
  • Build Requirements
  • Build Python Package
  • Build CMake Project
  • Example Setup for Ubuntu 26.04 (in WSL or physical/virtual machine)
  • Example Setup for Windows 11
  • Example Setup for macOS (Tahoe)
  • Package tests
  • Visual Studio Code Support
  • Documentation
• Development Container Setup Guide
  • Prerequisites
  • Container Engine
  • IDE/Editor
• Use Power Grid Model through C API
  • Finding and linking the package
  • Opaque struct/pointer
  • Handle
  • Logging
  • Calculation options
  • Buffers and attributes
  • Dataset views
  • Known limitations
• High-level design
  • Layers of abstraction
  • Existing library interfaces
  • Creating a custom library or interface
• Design of the Power Grid Model core
  • Calculation logic and data flow
  • Detailed Power Grid Model core design
• Design of the Python Wrapper Package
  • Class Graph Diagram
  • Package Graph Diagram
• Advanced terminology
  • Conventions
  • Programming terminology

Contribution

• Code of Conduct
  • Our Pledge
  • Our Standards
  • Our Responsibilities
  • Scope
  • Conflict Resolution
  • Attribution
• How to Contribute
  • Ways of contributing
  • Filing bugs and change requests
  • Community Guidelines
  • Style Guide
  • pre-commit hooks
  • REUSE Compliance
  • Git branching
  • Commit signature verification
  • Signing the Developer Certificate of Origin (DCO)
  • Automated workflow review process
  • Code reviews
  • Pull Request Process
  • AI‑Assisted Contributions
  • Contribution Workflow
  • Attribution
• Folder Structure of the Repository
• Project Governance
  • Technical Steering Committee
  • Maintainers
  • Contributors
  • PyPI project management

Release and Support

• Release strategy
  • Actively supported Python versions
• Get in Contact
  • How to ask for help, suggest a feature, or give recommendations.
  • Professional Support
  • How to report a bug
  • How to report a security vulnerability
  • Contributing a fix
• Community
  • Companies using Power Grid Model
  • Integration of Power Grid Model in other open-source tooling:
• Security Policy
  • Supported Versions
  • Reporting a Vulnerability
  • Third-Party Software and Development Tools
  • Verifying releases
• Citations