Power Grid Model

power-grid-model is a library for steady-state distribution power system analysis. 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

For conversions from various data format to the power-grid-model, refer to the power-grid-model-io repository. For an extended python interface to the the power-grid-model, refer to the power-grid-model-ds repository.

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
  • Data structures
  • Terminologies related to data structures
  • Attributes of Components
• Components
  • Base
  • Node
  • Branch
  • Branch3
  • Appliance
  • Sensor
  • Fault
  • Regulator
• Calculations
  • Calculation types
  • Batch Calculations
• Guidelines for performance enhancement
  • 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

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
  • utils
• power_grid_model_c (C API)
  • Main Header
  • Basics
  • Handle
  • Meta Data
  • Buffer
  • Dataset
  • Options
  • Model
  • 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
• 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

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
• 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

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 24.04 (in WSL or physical/virtual machine)
  • Example Setup for Windows 11
  • Example Setup for macOS (Tahoe)
  • Package tests
  • Visual Studio Code Support
  • Documentation
• Use Power Grid Model through C API
  • Finding and linking the package
  • Opaque struct/pointer
  • Handle
  • Calculation options
  • Buffers and attributes
  • Dataset views
• 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
  • 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
  • Signing the Developer Certificate of Origin (DCO)
  • Code reviews
  • Pull Request Process
  • 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
• Getting Help
  • How to ask for help, suggest a feature, or give recommendations.
  • 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
• Citations