2. Quickstart PowerFactory Guide

2. Quickstart PowerFactory Guide

2.1 System Requirements

The MTB execute_pf.py script executes RMS test cases in DIgSILENT PowerFactory. The current version is developed for PowerFactory 2025 SP4 with Python 3.11.

Install the MTB Python dependencies from the main MTB folder:

python -m pip install -r requirements.txt

Note

An example PowerFactory setup is available in setup_examples/MTB_Setup_Example.pfd. The example demonstrates the MTB setup only; it is not representative of a compliant plant model.

Important

The PowerFactory example was tested by an external third party with these changes to the default values in testcases.xlsx: Pn = 17.00 MW, Uc = 50.00 kV, and Un = 50.00 kV.

2.2 Preparation

2.2.1 Create an MTB installation folder

Extract or copy the MTB files into a common folder on the PC.

2.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.

2.2.3 Edit config.ini

Edit config.ini if required.

The PowerFactory execution script reads the following settings:

Section	Setting	Default / fallback	Used for
[General]	Casesheet path	testcases.xlsx	Path to thetestcases.xlsx file used for PowerFactory execution.
[General]	Export folder	export	Folder where PowerFactory CSV result files are exported.
[Python]	Python path	no fallback	Additional path appended tosys.path, typically used to make the PowerFactory Python module available.
[PowerFactory]	Parallel	True	Enables PowerFactory task automation parallel execution.
[PowerFactory]	QDSL copy grid	blank	Optional workaround grid whereinitializer_qdsl is copied if QDSL execution fails from the MTB grid. Leave blank to disable.
[PowerFactory]	create_case_folder	False	CreatesMTB_<Casegroup> subfolders for generated study cases and variations when True.

2.3 Model Setup in PowerFactory

2.3.1 Import the MTB into the project

Right-click the Network Data folder in the PowerFactory model and import MTB.pfd from the MTB folder. The project must be inactive to import using this method.

Important

The MTB grid naming must remain MTB.

Activate the MTB grid and replace the external grid with MTB. Remember to deactivate the existing external grid and any linked dynamic controls used for the external grid by marking them as Out of Service.

Connect the cubicle formerly used for the external grid at PoC to meas.ElmSind, Terminal j. Copy the cubicle from the busbar used by the external grid and paste it to meas.ElmSind.

2.3.2 Connect the MTB to the plant controller

There are two main ways to connect the MTB to the model's Power Plant Controller (PPC):

1. Connect references through the execute.ComPython script, where reference signals and model parameters are linked through script input parameters and external objects.
2. Assign the PPC P-control and Q-control block types to the MTB frame slots and connect MTB signals graphically through the MTB composite frame.

Note

The execute.ComPython script also contains relevant execution parameters. Only_setup can be used to set up one selected case without running all cases, and Post_run_backup creates a project version after the MTB run.

2.3.2.1 MTB connection through execute.ComPython

1. Open execute.ComPython and add the active and reactive PPC controller signal names to the relevant rows in the input parameter table.
2. Add the PPM and PPC controller block instances responsible for active and reactive power reference control. Depending on the plant model, this can be one or several blocks.

For the example shown above:

• Pmax is the attribute of the PPM control block that controls maximum available active power.
• Psp_ppu is the attribute of the active power control block that controls the active power reference in pu.
• Qsp_qpu is the attribute of the reactive power control block for Q control mode.
• QUsp_upu is the attribute of the reactive power control block for Q(U) voltage reference control.
• QPFsp_pf is the attribute of the reactive power control block for PF control mode.
• QUslope is the attribute of the reactive power control block for Q(U) droop in percent.

Important

When using predefined case sets from testcases.xlsx, the SIPS event interface can only be set up through the MTB frame. This requires the plant SIPS interface to be available as signals. Alternatively, custom signals can be used.

Important

Some PPCs use a reactive power base equal to 0.33 times the active power base, in accordance with Danish grid-code requirements. In those cases, the MTB reactive power reference must be scaled by approximately 3.03.

2.3.2.2 MTB connection through the MTB frame

1. Open the MTB composite frame type, for example by right-clicking it and selecting Mark in Graphic. Scroll to the User blocks area and insert the PPC active and reactive power control block types.

Important

This setup method requires the plant references to be modeled as signals, not only as internal parameters in the PPC P-control and Q-control blocks.

2. Select the DSL model type for the MTB slot by editing the slot and selecting the relevant type from the project library.

Note

DSL instances are coloured green, whereas DSL library types are coloured red.

3. Repeat this setup for the PPM active power controller and the PPC active and reactive power controllers.

4. Wire the MTB reference signals Pref, Qref, Uref, and PF to the corresponding PPC controller inputs. If possible, also wire Pavail and Q(U)droop as signals.

Important

If Pavail or Q(U)droop are parameters rather than signals, initialize them through initializer_script.ComDpl or through execute.ComPython parameter subscriptions.

5. The mtb_sips_decoder_g and mtb_sips_decoder_d blocks provide the binary interface between the mtb_s_sips_g and mtb_s_sips_d signals and the plant's System Integrity Protection Scheme (SIPS) interface.

2.3.3 Configure the MTB composite model

Add the ElmDsl model instances for the PPM P-control, PPC P-control, and PPC Q-control at the bottom of Net Elements in the MTB composite model MTB.ElmComp.

2.3.3.1 Edit initializer_script.ComDpl

The initializer_script.ComDpl script is used to configure initial model parameters and objects for each test case. It is executed for each generated study case when execute_pf.py runs.

Typical initialization tasks include:

• Initial available power, Pavail0.
• Active power control mode.
• Reactive power control mode.
• Initial Q(U) droop value, QUdroop0.
• Initial main transformer grounding state, MtrfrGnd0.

Add the PPM P-control block, PPC P-control block, PPC Q-control block, and main transformer object to the External Objects table as required.

If the test cases include limited available power, assign the relevant plant parameter, for example Irradiance or Pmax, to Pavail0.

The default MTB P control modes are:

Value	Mode
0	No power-frequency relation, constant power
1	Limited Frequency Sensitivity Mode (LFSM)
2	Frequency Sensitivity Mode (FSM)
3	LFSM + FSM

The default MTB Q control modes are:

Value	Mode
0	Q reference mode
1	Q(U) mode
2	PF / cosphi mode

If the plant uses other integer values for Pmode or Qmode, use initializer_script.ComDpl to map the MTB values to the plant-specific control parameters.

If the test cases include changes to Q(U) droop or main transformer grounding, connect the relevant objects and uncomment or adapt the corresponding code in initializer_script.ComDpl.

2.3.4 Connect the inverter to the MTB

This can be done with the MTB built-in Station and Power Frequency controllers, or with the initializer_qdsl.ElmQdsl initializer.

2.3.4.1 Station and Power Frequency controller setup

1. Open the Station controller under the MTB folder and add the inverter ElmGenstat to the Machines column.

2. Open the Power Frequency controller and add the inverter on the Load Flow tab.

2.3.4.2 QDSL initializer setup

1. Put initializer_qdsl.ElmQdsl in service. The QDSL script is located in the MTB composite frame folder and is out of service by default.

2. Choose a QDSL type from the MTB library that fits the plant model and fill in the data that is not set by script. By default, mtb_init_example_4 is selected and recommended.

3. Select the load-flow tab of the QDSL block and connect the relevant network elements, for example the plant inverter.

2.3.5 Configure execute.ComPython

Edit execute.ComPython and select execute_pf.py in the script tab. The full file path must be defined in Script file.

Note

If there are issues during plot setup or result export with parallel execution, go to Tools -> User Settings -> Parallel Computing -> Advanced and enable Transfer complete project to all processes.

When execute.ComPython is executed, execute_pf.py:

1. Creates a pre-run project version named PRE_MTB_<timestamp>.
2. Resets project units and consolidates the active study case.
3. Reads plant settings and cases from testcases.xlsx.
4. Creates PowerFactory study cases and variations for all RMS-enabled cases.
5. Applies case-specific MTB signals and events.
6. Executes initial conditions, RMS simulation, and CSV export through ComTasks.
7. Sets up standard PowerFactory plots for PowerFactory 2024 and newer.
8. Optionally creates a post-run project version when Post_run_backup > 0.

Note

When executing the script, active variations are consolidated, meaning changes recorded in the active variations are applied to the Network Data folder.

2.4 Script Execution Finished

When execution is finished, the PowerFactory output window should show that the Python script executed successfully.

The study cases enabled for RMS execution in testcases.xlsx should be visible in the project overview. If create_case_folder = True, generated study cases and variations are placed under MTB_<Casegroup> folders.

Simulation results are exported as CSV files to a timestamped subfolder inside the configured Export folder.

The exported .csv files can be plotted with the MTB plotter and compared with PSCAD results.

2.5 Add Additional Measurements to Result Files

Additional PowerFactory signals or parameters can be recorded through the execute.ComPython input parameters and external objects.

For each measurement object:

1. Add the object to the Meas_obj_<n> external object row.
2. Set Meas_obj_<n>_signals to a semicolon-separated list of PowerFactory result variables to record.
3. Set Meas_obj_<n>_alias to the alias used in the exported result file.

execute_pf.py scans Meas_obj_1 through Meas_obj_99 and adds the requested variables to the result file.

2.6 Custom Signal Setup

The MTB can control additional plant-specific signals or parameters in the PPC or other DSL models. Custom signals can be configured through execute.ComPython parameter subscriptions or through the MTB frame.

2.6.1 Custom signal setup through execute.ComPython

Use the custom signal input rows in execute.ComPython to subscribe plant parameters to MTB custom signals.

1. Enter the plant attribute to control and the required scaling. MTB custom signals are normally in pu.
2. Connect the object that owns the attribute in the external objects pane.

Internally, execute_pf.py supports custom subscribers for Custom1 through Custom10, connected to mtb_s_1 through mtb_s_10.

2.6.2 Custom signal setup through the MTB frame

From the MTB frame graphic:

1. Copy existing slots from the User Blocks section and place them by the custom signal slots, or insert new blocks/signals from the drawing tools. The MTB frame type's graphical freeze mode must be unlocked.
2. Connect the MTB custom signals to the desired signal inputs in the plant control blocks.

2.7 Troubleshooting

• Make sure the P-control and Q-control blocks used for MTB setup are from the PPC, not from the inverter, unless the model intentionally uses inverter-level control.
• If PowerFactory parallel execution fails during plot setup or result export, enable Transfer complete project to all processes under Tools -> User Settings -> Parallel Computing -> Advanced.
• If QDSL initialization fails because the QDSL controller is not in the same grid as the calculation-relevant static generators, configure QDSL copy grid in config.ini or leave it blank to disable the workaround.