7. Quickstart Python Utility Scripts

7. Quickstart Python Utility Scripts

The utility_scripts folder contains helper scripts for model checking, project cleanup, data extraction, PSCAD/PowerFactory comparison, and recovery of PSCAD result files. These scripts are not part of the normal MTB execution workflow, but they are useful when preparing models, checking consistency between PowerFactory and PSCAD, or troubleshooting simulation output.

Most scripts are intended for one of three execution contexts:

Script type	Run from	Typical purpose
PowerFactory scripts	Inside DIgSILENT PowerFactory as a Python/ComPython script	Extract data or run model checks
PSCAD scripts	From a Python environment withmhi.pscad, or inside the PSCAD scripting environment	Inspect or clean PSCAD projects
Standalone command-line scripts	From PowerShell or a terminal	Inspect.psout files or recover output files

7.1 Script overview

Script	Wrapper / related file	Main use	Execution context
check_powerfactory_model.py	Check PowerFactory Model.pfd	Checks that a PowerFactory model can run balanced/unbalanced load flow, calculate initial conditions, and run RMS simulations	PowerFactory
get_component_data_from_powerfactory.py	Get Component Data.pfd	Exports cable and transformer data from PowerFactory to Excel	PowerFactory
get_dsl_checksums_from_powerfactory.py	Get DSL Checksums.pfd	Exports checksums for encrypted DSL model types	PowerFactory
get_relay_data_from_powerfactory.py	Get Relay Data.pfd	Exports relay and protection settings from PowerFactory to Excel	PowerFactory
compare_component_data_with_pscad.py	Uses the workbook fromGet Component Data.pfd	Compares PowerFactory cable/transformer data with the corresponding PSCAD component parameters	PSCAD / Python withmhi.pscad
clean_project_definitions.py		Removes unused component definitions from a PSCAD project	PSCAD / Python withmhi.pscad
list_psout_signals.py		Lists available signals in a PSCAD.psout file	Command line
recover_psout_files.py		Recovers and renames.psout files after a PSCAD out-of-memory crash	Command line

7.2 PowerFactory model check

check_powerfactory_model.py is used to verify that the active PowerFactory project can run the basic study steps required by the MTB workflow. The script is delivered with the PowerFactory wrapper Check PowerFactory Model.pfd.

The script performs the following checks:

1. Compiles all relevant dynamic model types. This is not yet an Energinet requirement.
2. Checks that state variable derivatives are less than the tolerance for the initial conditions.
3. Calculates a balanced load flow and flat run.
4. Calculates an unbalanced load flow and flat run.
5. Checks fixed time step runs.
6. Checks variable time step runs.

The script expects to be run inside PowerFactory and uses attributes from the current PowerFactory script object:

Attribute	Purpose
MaximumError	Tolerance used when checking state variable derivatives
ModelTypes	Dynamic model types to compile
ForceRebuild	Whether model types should be force rebuilt
DisplayCompilerMessages	Compiler message output level

7.3 Export component data from PowerFactory

get_component_data_from_powerfactory.py exports selected network component data from PowerFactory to an Excel workbook. The script is delivered with the PowerFactory wrapper Get Component Data.pfd.

This is the first step in the PowerFactory/PSCAD component comparison workflow. It reads cable and transformer data from the RMS model, calculates equivalent parameters in PSCAD format, and writes the results to an Excel workbook.

The exported workbook contains:

Sheet	Content
PowerFactory Cable Data	Cable names, number of parallel lines, length, positive- and zero-sequence impedance/admittance data, and PSCAD-equivalent values
PowerFactory ElmTr2 Data	Two-winding transformer names, type, vector group, ratings, voltages, short-circuit data, losses, and calculated PSCAD-equivalent values
PowerFactory ElmTr3 Data	Three-winding transformer data, if any three-winding transformers exist in the project

The script is run from PowerFactory and expects the current script object to define:

Attribute	Purpose
excel_output_path	Full path to the Excel file to create

This exported workbook is used as input to compare_component_data_with_pscad.py.

7.4 Export DSL checksums from PowerFactory

get_dsl_checksums_from_powerfactory.py exports checksums for encrypted DSL model types in the PowerFactory project. The script is delivered with the PowerFactory wrapper Get DSL Checksums.pfd.

It scans all BlkDef objects and records model types containing the encrypted model marker:

001! Encrypted model; Editing not possible.

The output Excel workbook contains one sheet:

Sheet	Content
DSL Encryption Data	DSL model type name and checksum

The script is run from PowerFactory and expects the current script object to define:

Attribute	Purpose
excel_output_path	Full path to the Excel file to create

7.5 Export relay data from PowerFactory

get_relay_data_from_powerfactory.py exports relay and protection setting information from PowerFactory to Excel. The script is delivered with the PowerFactory wrapper Get Relay Data.pfd.

The output workbook makes it easier to compare the PowerFactory protection settings with the corresponding protection settings in PSCAD.

It scans ElmRelay objects and creates:

Sheet	Content
Relay Data	Overview of relays, application type, out-of-service status, and relevant relay slots
One sheet per relay	Detailed protection functions, IEC symbol, ANSI number, out-of-service status, relay type, tripping direction, characteristic, threshold value, and time value

The script filters out common auxiliary slots such as voltage transformers, current transformers, measurement blocks, PLLs, logic blocks, clocks, and filters.

The script is run from PowerFactory and expects the current script object to define:

Attribute	Purpose
excel_output_path	Full path to the Excel file to create

7.6 Compare PowerFactory and PSCAD component data

compare_component_data_with_pscad.py compares cable and transformer data exported from PowerFactory with the corresponding components in a PSCAD project.

The script reads the Excel workbook created by get_component_data_from_powerfactory.py, then opens the configured PSCAD project and extracts cable and transformer data from matching EMT model components. It writes the PSCAD values to the same workbook and adds comparative sheets showing whether the PSCAD values match the equivalent values calculated from PowerFactory.

At the top of the script, configure:

pscad_project_name = 'Solbakken'
excel_path = r'E:\Users\<username>\Solbakken_PowerFactory_Component_Data.xlsx'
SET_PARAMS = False

Setting	Purpose
pscad_project_name	Name of the PSCAD project to inspect
excel_path	Path to the PowerFactory component data workbook
SET_PARAMS	IfTrue, PSCAD cable and transformer parameters are overwritten with values derived from PowerFactory. Keep this False unless parameter synchronization is intended.

The script supports comparison of:

Component type	Notes
Cables	Compares length and positive-/zero-sequence series and shunt values
Two-winding transformers	Supportsdb_xfmr_3p2w and xfmr-3p2w PSCAD component definitions
Three-winding transformers	Supportsxfmr-3p3w2 if three-winding transformer data exists in the Excel workbook

The script appends comparative sheets to the same Excel workbook:

Sheet	Content
Comparative Cable Data	PowerFactory values, PSCAD values, and percentage differences
Comparative ElmTr2 Data	PowerFactory two-winding transformer values, PSCAD values, and percentage differences
Comparative ElmTr3 Data	PowerFactory three-winding transformer values, PSCAD values, and percentage differences, if applicable

7.7 Clean unused PSCAD project definitions

clean_project_definitions.py deletes unused component definitions from a PSCAD project.

At the top of the script, configure the PSCAD project name:

project = pscad.project("Solbakken")

The script repeatedly:

1. Finds definitions with zero instances.
2. Deletes them.
3. Saves the project.
4. Repeats until no unused definitions remain.

Use this script with care. It modifies and saves the PSCAD project.

7.8 List signals in a .psout file

list_psout_signals.py lists and organizes signals from a PSCAD .psout file. It is useful when configuring figureSetup.csv or troubleshooting missing signal names.

Example:

python utility_scripts/list_psout_signals.py "export\MTB_Example\Solbakken_1.psout"

Include generic multimeter signals:

python utility_scripts/list_psout_signals.py "export\MTB_Example\Solbakken_1.psout" --multimeters

Arguments:

Argument	Required	Purpose
path	Yes	Path to the.psout file
-m, --multimeters	No	Include generic multimeter signals. By default, non-MTB multimeter signals are hidden.

The output is grouped into:

Group	Meaning
MAIN CANVAS SIGNALS	Signals found directly on the PSCAD main canvas
SUB-MODULE SIGNALS	Signals found inside submodules

7.9 Recover .psout files after a PSCAD OOM crash

recover_psout_files.py recovers .psout files from the PSCAD build folder after a crash, such as an out-of-memory crash during batch execution.

The script uses the caseRankTaskID.csv mapping generated by the MTB PSCAD execution workflow to rename task-ID-based .psout files back to case-rank-based filenames.

Example:

python utility_scripts/recover_psout_files.py `
  --buildPath "C:\Path\To\PSCAD\Build\Folder" `
  --exportPath "..\export" `
  --csvPath "..\caseRankTaskID.csv" `
  --projectName "Solbakken"

Arguments:

Argument	Required	Default	Purpose
-b, --buildPath	Yes		Path to the.psout files that should be recovered
-e, --exportPath	No	..\export	Root export folder where recovered files are moved
-n, --projectName	No		Optional project-name filter. If supplied, only matching.psout files are recovered
-c, --csvPath	No	..\caseRankTaskID.csv	CSV file mapping PSCAD task IDs to MTB case ranks

Recovered files are moved to a timestamped folder named like:

OOM_YYYYMMDDHHMMSS

Inside that folder, files are renamed to the normal MTB result naming pattern:

<ProjectName>_<CaseRank>.psout

7.10 Notes and cautions

• The PowerFactory scripts must be run in a PowerFactory environment where the powerfactory Python module is available.
• The PSCAD scripts require mhi.pscad and, for .psout inspection, mhi.psout.
• Some scripts contain project-specific defaults such as Solbakken or local Excel paths. Review these values before running the scripts on another project.
• compare_component_data_with_pscad.py can modify PSCAD component parameters when SET_PARAMS = True.
• clean_project_definitions.py modifies and saves the PSCAD project.
• Always keep a backup or use version control before running scripts that modify PowerFactory or PSCAD projects.