3. Quickstart PSCAD Guide

3. Quickstart PSCAD Guide

3.1 System Requirements

The MTB execute_pscad.py script is used to execute MTB test cases for a PSCAD plant model. It supports two execution modes:

Mode	Python environment	Typical use
Run from within PSCAD	PSCAD embedded Python 3.7.2	Automation tasks that may run slightly faster inside PSCAD
Run from the command line	External Python, for example Python 3.13	Automated execution and batch runs

The required Python packages are listed in requirements.txt in the main MTB folder.

3.1.1 Running from within PSCAD

When running execute_pscad.py from within PSCAD, PSCAD 5.0.2 uses its embedded Python 3.7.2 environment. This is not an interactive execution workflow; it is mainly useful because some PSCAD automation calls may run slightly faster when executed inside PSCAD.

External packages cannot always be installed directly into PSCAD's embedded Python environment. A practical workaround is:

1. Install Python 3.7.x.
2. Install the MTB requirements into that Python 3.7.x installation or virtual environment:

<PATH-TO-PYTHON37> -m pip install -r requirements.txt

A typical Python path is:

C:\Program Files\Python37\python.exe

If normal installation is blocked by permissions, install to the user's roaming Python folder:

<PATH-TO-PYTHON37> python -m pip install --target C:\Users\<USERNAME>\AppData\Roaming\Python\Python37\site-packages -r requirements.txt

The MTB usually finds the Python path automatically, but an additional path can be added with the Python path setting in config.ini, for example:

C:\Program Files\Python37\Lib\site-packages
C:\Users\<USERNAME>\AppData\Roaming\Python\Python37\site-packages

3.1.2 Running from the command line

When running execute_pscad.py from the command line, or through batch_execute_pscad.py, the script uses the active external Python installation.

Install the MTB requirements for that Python installation:

python -m pip install -r requirements.txt

There are two command-line scenarios:

Scenario	Behaviour
PSCAD is already running	execute_pscad.py searches for a Pscad.exe process owned by the current Windows user and connects to one of its listening ports.
PSCAD is not already running	execute_pscad.py launches PSCAD 5.0.2, acquires a certificate license that meets the configured Volley, loads the configured workspace, and sets the configured Fortran compiler.

Important

Command-line execution that launches PSCAD requires certificate licensing. If no existing PSCAD instance is found, the script uses the first available certificate that meets the Volley requirement in config.ini.

3.1.3 Example workspace

An example setup is available in setup_examples, including SimpleSolarFarm.pscx and MTB_Setup_Example.pswx. The example demonstrates the MTB setup only; it is not representative of a compliant plant model.

3.2 Preparation

3.2.1 Create an MTB installation folder

Create an MTB subfolder in the PSCAD workspace folder, where the .pswx file is usually located, and copy or extract the MTB files into that folder.

3.2.2 Edit the Settings sheet

Fill in the model-specific information in the Settings sheet in testcases.xlsx. The workbook guide is described in 1. Quickstart Testcases Workbook Guide.

Important MTB 2.x settings include:

• Default P available: associated with mtb_s_pavail_pu, the Pavail event type, and Pavail0.
• Default Q(U) droop: associated with mtb_s_qudroop, the QUdroop event type, and QUdroop0.
• Main Transformer Grounded: associated with mtb_s_mtrfrgnd and MtrfrGnd0.

3.2.3 Edit config.ini

Edit config.ini if required.

The PSCAD execution script reads the following settings:

Section	Setting	Default / fallback	Used for
[General]	Casesheet path	testcases.xlsx	Path to thetestcases.xlsx file used for PSCAD execution.
[General]	Export folder	export	Folder where.psout result files are moved after execution.
[Python]	Python path	blank	Optional path appended tosys.path, often used for PSCAD embedded Python package access.
[PSCAD]	Volley	16 in code, 8 in the default config	Number of parallel PSCAD simulation tasks.
[PSCAD]	Tracing	False	Sets PSCAD simulation-set affinity type.False disables tracing; True enables tracing for all workers.
[PSCAD]	State animation	False	Enables or disables schematic animation during simulation.
[PSCAD]	Only in use channels	True	Only processes channels explicitly connected to output channels or plots.
[PSCAD]	Disable all unused PGBs	True	Synchronizes Plotter Group Blocks withplotter/figureSetup.csv and disables unused PGBs.
[PSCAD]	Use legacy Unit measurement signal naming	True	Uses the legacy<Unit_name>\<alias>_<signal_name> naming style for Unit Measurement signals.
[PSCAD]	Fortran version	no fallback	Required when the script launches PSCAD from the command line. Ignored when connecting to an existing PSCAD instance.
[PSCAD]	Workspace	no fallback	Workspace loaded when the script launches PSCAD from the command line. Ignored when connecting to an existing PSCAD instance.

Note

Tracing = False corresponds to Disable Tracing. Tracing = True corresponds to Enable Tracing (All). Tracing is useful for debugging but can significantly slow down large parallel simulations.

Note

The Fortran compiler name shown in the PSCAD GUI may not exactly match the value that must be written in config.ini. When running without an existing PSCAD instance, an empty or invalid Fortran version makes the script print the valid Intel compiler names available on the machine.

It may also be necessary to run the PSCAD Environment Medic and update the Fortran compiler list by selecting Generate installed product list, especially after a PSCAD server update.

Important

Energinet's simulation model requirements currently specify that PSCAD models should use Intel Fortran 12 or 15.

3.3 MTB Setup in PSCAD

3.3.1 Import the MTB into the PSCAD workspace

Open a workspace with all required models, libraries, ETRAN libraries, and resources. In the example workspace, the model under test is SimpleSolarFarm in MTB_Setup_Example.pswx.

Add the following resources:

1. MTB.pslx, added as an existing project.
2. interface.f, added as source code.
3. execute_pscad.py, added as a script/app resource.
4. Optional pscad_update_ums.py, used for Unit Measurement signal naming.
5. Optional pscad_synchronize_pgbs.py, used to inspect or synchronize Plotter Group Blocks.

All resources can also be added in one go by right-clicking the Resources folder and selecting Add -> Other (.).

3.3.2 Connect the MTB block to the PoC

1. Disconnect and disable the power grid from the PoC in the model. Keep any PoC measurements that are already present.

2. Copy the MTB block from the MTB project.

3. Paste the MTB block into the plant model and connect it to the PoC.

4. Adjust the orientation of the MTB block if required.

3.3.3 Connect MTB controls to the PPC

3.3.3.1 MTB output signals

Right-click the MTB block, select Edit Parameters..., and open Signal outputs to view the output signals.

The main output signals are:

Signal	Purpose
Pref	Active power reference in pu usingPn from the Settings sheet.
Pavail	Available active power limit in pu.
Qref	Shared reactive power, voltage, or power factor reference depending on Q mode.
Qref_Q	Reactive power reference when Q mode is active.
Qref_Qu	Voltage reference when Q(U) mode is active.
Qref_Qpf	Power factor reference when PF mode is active.
Qref mode 3-6	Custom Q-mode outputs.
Q(U) droop	Q(U) droop value in percent.
Pmode	Active power mode: 0 = FSM/LFSM disabled, 1 = LFSM, 2 = FSM, 3 = FSM + LFSM.
Qmode	Reactive power mode: 0 = Q, 1 = Q(U), 2 = PF.
Main Transformer Ground	Main transformer grounding signal.
mtb_SIPS_g	Integer SIPS signal for generation facilities.
mtb_SIPS_d	Integer SIPS signal for demand facilities.
Custom signal 1-10	Custom signal outputs driven bySignal 1, Signal 2, etc. events in testcases.xlsx.

3.3.3.2 Convert input signals to the PPC

Pref and Qref_Q

If the PPC expects active and reactive power inputs in MW and Mvar, scale the pu references by the plant rating. In the example plant, rated at 10 MW, mtb_Pref and mtb_Qref_Q are multiplied by 10.

Qref_Qu

If the PPC uses a different voltage base than the MTB, scale the Qref_Qu signal accordingly. For example, converting from 152 kV to 161.9 kV gives a factor of 152 / 161.9 = 0.9388.

Pmode and Qmode

If the PPC expects different integer values for P modes or Q modes, use an X-Y table to map MTB output values to PPC input values.

Example Qmode mapping:

Qmode	MTB output	Output tap 1	Output tap 2	Output tap 3
Q	0	4	0	0
U	1	5	1	0
PF	2	3	0	1

3.3.3.3 Connect signals to the PPC

The exact signal routing is model-specific. In the example, P, Q, Q(U), and PF references are connected on the main canvas, while Qmode and Pmode are connected inside the PPC block.

System protection (SIPS) signals

For some plants, a System Integrity Protection Scheme (SIPS) interface is required. MTB supports this through mtb_SIPS_g for generation facilities and mtb_SIPS_d for demand facilities.

The MTB includes an MTB SIPS Integer to Binary Decoder block that decodes mtb_SIPS_x into SIPS_x_step_y binary signals. The default setup provides five SIPS steps.

The MTB provides a generic decoder instance and two preconfigured instances with the same signal names used in the plotter figureSetup.csv for generation (RfG) and demand (DCC) cases.

Available power signals

Some MTB cases test changes in available power for solar and wind power plants. From MTB 2.0, a dedicated mtb_Pavail signal is provided in pu and can be used to set the upper active power limit.

A Wireless Radio Link can also be used to send the Pavail signal inside the solar plant and directly control irradiation in W/m².

3.3.4 Connect additional MTB measurements (optional)

The MTB block measures at PoC. Additional measurement points can be added with the Unit measurement block from the MTB project.

Copy and paste the block into the model and connect it to the point of interest. Use Paste Special -> Paste Transfer when pasting the block.

Set the voltage base and apparent power base by editing the block parameters. The Unit alias parameter controls the legacy signal-name prefix.

If Use legacy Unit measurement signal naming = True, Unit Measurement signals are named with both the Unit Measurement block name and alias. If it is False, the alias is ignored because .psout signal paths already include the Unit Measurement block instance name.

Important

If Disable all unused PGBs = True, update the plotter figureSetup.csv so any required Unit Measurement signals are listed. Otherwise those PGBs can be disabled before simulation.

3.4 Script Execution

3.4.1 Running all selected cases (Volley mode)

The MTB can run selected cases in parallel. The usable volley count depends on the CPU and the available PSCAD license. The default config.ini sets Volley = 8.

To run the simulation from PSCAD, right-click execute_pscad.py and select Run.

Progress can be followed under Simulation Sets -> MTB -> . The PSCAD task number does not necessarily match the case rank from testcases.xlsx, because MTB orders tasks to reduce total simulation time. The script prints the Rank, Task ID, and Case name in the PSCAD Script Output window, and also writes caseRankTaskID.csv for OOM recovery.

3.4.2 Running individual cases (Manual mode)

To run a single rank:

1. Right-click the MTB block and select Edit Parameters....
2. Change Mode to Manual.
3. Select the desired Manual rank from testcases.xlsx.
4. Run execute_pscad.py.

The .psout file for the selected case is saved in a timestamped MTB subfolder inside the configured export folder.

3.5 Script Execution Finished

When the script finishes, result files are available in the configured export folder, by default export. The MTB creates .psout files that can be plotted with plotter.py and compared with PowerFactory results. See 4. Quickstart Plotter Guide.

3.6 Troubleshooting

3.6.1 Wrong compiler

Running PSCAD with the wrong compiler can produce errors like these:

To change compiler in PSCAD, go to File -> Application Options -> Dependencies and select the required Intel Fortran compiler.

3.6.2 UnicodeDecodeError

If the PSCAD project name or folder path contains Danish letters such as æ, ø, or å, execute_pscad.py may fail with a UnicodeDecodeError. Rename the project or folder path to use ASCII characters.

3.6.3 PSCAD Out of Memory (OOM) error

Large PSCAD projects with many signals and many test cases can run into PSCAD out-of-memory errors when generating .psout files.

Before running the volley, execute_pscad.py writes caseRankTaskID.csv with the mapping between case rank, PSCAD task ID, and case name. If PSCAD crashes, this mapping can be used with recover_psout_files.py to rename recovered .psout files from task IDs back to case ranks.

Two workarounds are commonly used when OOM errors occur regularly.

3.6.3.1 Batch execution with smaller test case sets

Use batch_execute_pscad.py to run several smaller testcases.xlsx files in sequence:

test_case_paths = ['testcases1.xlsx', # e.g. RfG Ranks: 1..44
                   'testcases2.xlsx', # e.g. RfG Ranks: 45..88
                   'testcases3.xlsx', # e.g. RfG Ranks: 89..132
                   'testcases4.xlsx', # e.g. RfG Ranks: 133..176
                   'testcases5.xlsx', # e.g. Custom Ranks: 3001..3044
                   'testcases6.xlsx'] # e.g. Custom Ranks: 3045..3087

The output is stored in separate timestamped MTB folders.

3.6.3.2 Disable unused PGBs

Set Disable all unused PGBs = True in config.ini to disable Plotter Group Blocks that are not needed for plotting. execute_pscad.py then calls functions from pscad_synchronize_pgbs.py:

Function	Purpose
getSignalsFromFigureSetup	Reads EMT signals fromfigureSetup.csv.
validateFigureSetupAgainstWorkspace	Verifies that requested signals exist in the PSCAD workspace.
synchronizePGBsInProject	Enables required PGBs and disables PGBs that are not required.

The script can also be run from within PSCAD to inspect which signals will be kept or disabled before applying synchronization.

Example output:

Success: All signals in figureSetup.csv were located in the workspace.

============================================================
Project: Solbakken
============================================================

Main\PPC\Pcontrol
======================
  Pref [KEEP]
  Pmeas [already disabled]
  Perror [WILL DISABLE]
  Pi [already disabled]
  Pp [already disabled]
  Ppi [WILL DISABLE]
  Pout [KEEP]

============================================================
Total enabled : 132
Total disabled: 88
Will keep     : 10
Will disable  : 123

Project Solbakken DRY RUN: Would disable 123, and enable 1.
============================================================

3.6.3.3 Comparing the two OOM workarounds

A test on a TSO plant showed the following trade-off:

Workaround	Advantage	Trade-off
batch_execute_pscad.py	All plant signals remain available	Requires splittingtestcases.xlsx; total result size was 10.3 GB in the test
Disable all unused PGBs = True	Can usetestcases.xlsx as-is; result size was 4.97 GB in the test	Only plant signals listed infigureSetup.csv are available for post-processing