Overview

The following tutorials illustrate the functionality of powfacpy. You can use the PowerFactory project under *tests_input_tests.pfd* to run the commands in the tutorials locally. You can follow the link to Github on the right to download the tutorials in .qmd format (quarto). If you prefer jupyter notebook format, you can convert them with quarto convert <tutorial_name.qmd> (assuming quarto is installed).

1 Getting started

Start here with the getting started tutorial. This tutorial gives an overview of the interaction with the PowerFactory database using powfacpy. The methods introduced in this tutorial serve as a basis to do more complex things and to write more readable code using less lines of code.

2 Dynamic Simulation, Plotting and Data Export

The tutorial shows how to conveniently simulate and plot with a syntax similar to matplotlib. It is also depicted how to export data to pandas and csv formats and use external plotting libraries such as matplotlib.

3 Dynamic Model Validation

This tutorial illustartes the dynamic simulation of a unit model (e.g. a wind turbine) for test scenarios with varying grid voltage behaviour at the point of connection. Such tests are required for example if you want to debug a dynamic model and its controllers, validate a dynamic model according to a reference (e.g. another softare) or test the bahaviour for grid code requirements.

4 Dynamic Model Documentation

The dynamic model documentation tutorial demonstrates how to generate HTML documentation for dynamic models in PowerFactory, specifically composite models (ElmComp) and their DSL models (ElmDsl). Such documentation is useful for project reports, or for sharing model details in an accessible format with collaborators who do not have access to PowerFactory.

5 Importing Modelica Models (experimental)

The Modelica models tutorial shows how to create and compile a PowerFactory Modelica model type (TypMdl) from a .mo file or a ModelicaModelSpec with powfacpy.applications.modelica, without entering the declarations and equations through the GUI. The running example is a stepwise under-frequency / RoCoF load-shedding controller.

6 Isolated Testing of Dynamic Model Blocks (DSL/Modelica)

The dynamic model block testing tutorial exercises a DSL block definition (BlkDef) or a compiled Modelica model type (TypMdl) in isolation, independently of any grid or network it will eventually be connected to. It shows both isolated testers: BlockDefinitionFrameTest / ModelicaModelFrameTest (model placed in the shipped BlockDefinitionTesting composite frame, inputs fed by an lapprox DSL - true ramps and arbitrary piecewise-linear profiles) and, for a Modelica model directly with no frame at all, ModelicaModelTest (inputs driven by parameter events - step changes only).

7 Static Calculations (Load Flow etc.)

The static calculations in this tutorial like power flow (or load flow as it’s called in PowerFactory) or short circuit analysis are not the main focus of powfacpy. However, powfacpy provides a convenient interface to perform these calculations and to access the results.

8 Study Cases

The study cases tutorial illustrates how to automatically create study cases for parameter studies.

9 Parameter Studies

This tutorial shows how to perform parameter studies in a concise and structured way and to generate targeted parameter modifications with minimal code, built on the backend-agnostic parstudy package (powfacpy[parstudy]) - powfacpy.applications.parameter_studies only adds pf_parameter (sweep an attribute across a list of PF objects) and apply_gradient (spread it unevenly across them instead). Compared to the ‘Study Cases’ tutorial, parstudy mutates the model in place and restores it after each run rather than materializing a persistent study case per combination - a better fit for large or exploratory sweeps (grids, Latin hypercube, Sobol sampling) where the sweep strategy, statistics and plots matter more than having a browsable, reusable set of PF cases.

11 Network Matrices and Pandapower Interface

This tutorial demonstrates how to export network matrices such as admittance or Jacobian matrix using the Pandapower interface as an intermediate step.

12 Topology and Groupings

The tutorial on topology and groupings focuses on the grouping of network elements into boundaries, zones and areas.

13 The Global DIgSILENT Library

The global DIgSILENT library tutorial shows how to navigate the built-in library by the folder names shown in the GUI (which differ from the coded names the Python API expects), using DigsilentLibrary.

14 Dynamic Model Templates

The dynamic model templates tutorial covers powfacpy.template_models: Python interfaces to library templates that read information hidden in the controllers (e.g. the inertia of a grid-forming converter), LibraryTemplateIndex to detect which global-library template each controller in the active project’s grid was built from, and TemplateMatcher which combines the two.

15 Subsystems

The Subsystems tutorial covers similar topics as the topology and groupings tutorial on zones, areas and boundaries. However, the SubSystem and SubSystemContainer clases of powfacpy go beyond the functionality and add further analysis for coherent network areas and their interactions (e.g. power exchange, connectivity, frequency stability / inertia, etc.).

16 CGMES Model Exchange

In the cgmes model exchange tutorial you can learn how to get started with the application.model_exchange tool to export, import or update grid models using CGMES.

17 Database Interface

The database interface tutorial illustrates the Database interface class of powfacpy, which provides methods to export and import larger chunks of data from the PowerFactory database (objects and their attributes, results variables, dynamic model parameters). Unlike exporting to formats such as CGMES, the Database class preserves a structure that stays close to the native PowerFactory database layout.

18 A Word on Performance

This tutorial evaluates the performance characteristics of the Python API of PowerFactory. The powfacpy wrapper is benchmarked against the native API. Moreover, the performance improvements achieved through the caching mechanisms provided by powfacpy are demonstrated.