3. Quickstart Guide PSCAD

System Requirements

Developed with PSCAD release 5.0.2 (2023/04/26) with Python 3.7.2 (embedded), and using Python 3.13 as an external client, dependent on Python packages as specified in requirements.txt

Running from within PSCAD

When running execute_pscad.py from within PSCAD, e.g.

PSCAD uses the embedded PSCAD Python environment 3.7.2 into which external Python packages cannot be installed and imported in the standard way.

The easiest way around this is the following procedure:

1. Install Python 3.7.2
2. Install requirements from PSCAD requirements.txt into the Python 3.7.2 installation (or a virtual environment). This can be done by executing,

python -m pip install -r requirements.txt

3. Depending on the permissions, one may need to execute the following command to install the requirements in the user's "Roaming" folder, e.g.

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

4. The MTB usually is able to find the Python path, but it can also be manually added to config.ini if required so that it points to the python 3.7.2 installations site-packages folder, e.g. C:\Program Files\Python37\Lib\site-packages or C:\Users\<user-name>\AppData\Roaming\Python\Python37\site-packages

Running from the command line

When running execute_pscad.py from the command line,

the script will use the default Python installation, e.g. Python 3.13.5 for the example above.

The MTB Python package requirements requirements.txt should also be for this default Python installation, by executing,

python -m pip install -r requirements.txt

Unlike for Python 3.7.2, this should almost always install the Python packages in the correct location.

Important

Currently, running execute_pscad.py from the command line only works with certificate licensing. When the script is run, it will first look for a listening port. If none is found, or it cannot initialize, it will look for a certificate. It will use the first certificate that meets the Volley setting in config.ini. See section 3.1.3

---

Note

An example setup of the MTB can be found in the folder setup_examples named SimpleSolarFarm.pscx with the workspace setup in MTB_Setup_Example.pswx. This is purely an example to showcase the setup of the MTB and the model used is not in any way representative of a compliant model or plant.

3.1 Preparation

3.1.1 Create an MTB 'installation' folder

Create an MTB subfolder in the PSCAD workspace folder (where the .pswx file is usually located), and extract or copy all MTB files and to this newly created subfolder, e.g.

3.1.2 Edit the 'Settings' sheet

Fill in the model-specific information in the 'Settings' sheet in the testcases.xlsx file. The Excel guide can be found here Quickstart Guide Excel

Note

The following are new for MTB 2.0:

• Default P available associated with the signal mtb_s_pavail_pu, the Event Type Pavail, and the initial power available at t=0, Pavail0

• Default Q(U) droop associated with the signal mtb_s_qudroop, the Event Type QUdroop, and the initial Q(U) droop setting at t=0, QUdroop0. This previously was a constant V droop associated with the constant mtb_c_vdroop

• Main Transformer Grounded is associated with the signal mtb_s_mtrfrgnd and initial main transformer grounding configuration, MtrfrGnd0. No event is associated with this signal.

3.1.3 Edit the configuration file

Edit the config.ini file if required.

• Under the [General] section,

  • Casesheet path specifies the file path of the testcases.xlsx sheet to be used
  • Export folder specifies the location where the PSCAD .psout, output files will be moved to after the PSCAD simulations are done

• Under the [Python] section,

  • Python path specifies any additional paths to be added to the Python path, see System Requirements

• Under the [PSCAD] section,

  • Fortran version specifies the Fortran version, see Fortran versions, to be used, e.g.

    • Intel 12.1.371
    • Intel 15.0.148
    • Intel 15.0.148 (64-bit)
    • Intel 19.2.49496
    • Intel 19.2.49496 (64-bit)

    If none is specified, the manual selected version saved with the Workspace file, will be used

  • Volley the number of simulations to be run in parallel (up to a maximum of 64, license dependent) -- see PSCAD help website

  • Workspace specifies the PSCAD workspace file to be used when executing execute_pscad.py as an external client from the command line

3.2 Model Setup in PSCAD

3.2.1 Importing the MTB into the PSCAD workspace

Open a workspace with all the models and libraries required for running simulations, including ETRAN libraries and any resources. In this example, the model under test is called 'SimpleSolarFarm' and forms part of the MTB_Setup_Example.pswx workspace.

1. Add the MTB.pslx project into the workspace. Do this by right-clicking on the Projects folder, click 'Add Existing Project...'.
2. Add the interface.f file. Do this by right-clicking the Resources folder, click 'Add' -> 'Source Code (*.f, *.for, *.f90, *.c, *.cpp)'.
3. Add the execute_pscad.py file. Do this by right-clicking the Resources folder, click 'Add' -> 'Script\Apps (*.py, *.exe, *.bat)'.
4. Add the optional Unit Measurement signal renaming script, pscad_update_ums.py file. Do this by right-clicking the Resources folder, click 'Add' -> 'Script\Apps (*.py, *.exe, *.bat)'.

3.2.2 Connection of MTB block to POC

Disconnect and disable the power grid from the POC in the model. Make sure to keep any measurements present at POC (Shown below in the red dotted box.). Otherwise, the model might not work properly.

Then copy the test bench from the MTB project into the model. Do this by right-clicking the MTB block and clicking 'Copy'. Then go to the model, right-click, and click 'Paste'. The last step is to connect the MTB block to the POC.

3.2.3 Connection of MTB controls to the Power Plant Controller (PPC)

3.2.3.1 MTB output signals

You can see the different signals the MTB outputs by right-clicking on the MTB block and selecting 'Edit Parameters...'. Then go to 'Signal outputs'

The different output signals are summarized below:

• Pref signal is the active power reference. It is given in per unit with a base value determined by the 'Pn' value in the 'Settings' sheet in the testcases.xlsx excel document.

• P available signal is the limited power available for a given test case, due to reduced irradiance or lower wind speed, etc.

• Qref signal is the reactive power reference for both reactive power control (Q), voltage control (Qu), and power factor control (Qpf) mode. It changes its value based on the Q mode selected at the given time. It is given in per unit when in Q or Qu mode. In Q mode the base value is the 'Pn' value in the 'Settings' sheet. In Qu mode, the base value is the 'Un' value in the 'Settings' sheet. In Qpf mode the value is the desired power factor which can be from -1 to 1.

• Qref Q mode signal is the reactive power reference when in reactive power control mode. It is given in per units with a base value determined by the 'Pn' value in the 'Settings' sheet.

• Qref Qu modesignal is the reactive power reference when in voltage control mode. It is given in per units with a base value determined by the 'Un' value in the 'Settings' sheet.

• Qref Qpf mode signal is the power factor reference when in power factor mode. The reference can take any value between -1 and 1.

• Qref mode 3-6 are outputs that can be used to create custom Q modes

• Q(U) droop signal is the Q(U) droop value in % when in Q(U) mode

• Pmode signal is an integer output determining the active power mode. The modes are:

  1. mtb_Pmode = 0: FSM and LFSM disabled
  2. mtb_Pmode = 1: LFSM enabled, FSM disabled
  3. mtb_Pmode = 2: FSM enabled, LFSM disabled
  4. mtb_Pmode = 3: FSM and LFSM enabled

• Qmode signal is an integer output determining the reactive power mode. The modes are:

  1. mtb_Qmode = 0: Reactive power mode (Q)
  2. mtb_Qmode = 1: Voltage mode (Qu)
  3. mtb_Qmode = 2: Power factor mode (Qpf)

• Main Transformer Ground signal is a signal that can be used to ground the main transformer

• Custom signal 1-10 can be used to create custom signal outputs. In the testcases.xlsx excel document they are used just like the other output signals by inserting an event. Their type names are 'Signal 1', 'Signal 2', and so on. They can be used to for example to implement System Protection (SIPS) control etc.

3.2.3.2 Conversion of input signals to the PPC.

Pref and Qref_Q

In this given example the PPC takes its active and reactive power inputs in MW and Mvar. Therefore simple calculations have to be done. In the MTB project, conversion blocks are given as templates. The example plant is rated at 10 MW. The 'mtb_Pref' and 'mtb_Qref_Q' signals are therefore multiplied by 10.

Qref_Qu

The nominal voltage level 'Un' is determined by the POC. If the plant in normal operation is run at a different voltage, a conversion has to be made to the 'Qref Qu mode' signal. For example, if a plant is connected to the 150 kV level the nominal voltage is 152 kV. It might be desirable to run the plant at a higher voltage of 161.9 kV and therefore the base value in the PPC is set to 161.9 kV. If the plant is run in Qu mode the MTB sends a reference in pu based on the nominal voltage of 152 kV. A conversion factor of 152/161.9 = 0.9388 is therefore inserted to convert between the base values.

Pmode and Qmode

If the PPC takes different integer values for the P modes or Q modes than the MTB provides, X-Y tables can be used for the conversion. In this given example the PPC P modes match the MTB outputs, but the Q modes do not. The PPC takes the Qmode inputs, reactive power mode = 3, voltage mode = 1, and power factor mode = 2. It is therefore necessary to route the numbers 0->3, 1->1, 2->2. This is done with the X-Y table found in the MTB project. To set it up insert it into the model and double-click on the block. Click on the '...' button in the data table row. Change the table to match your desired output.

3.2.3.3 Connection of signals to the PPC

Standard signals

This step is different for every model. In this example, the P, Q, Qu, and Qpf references are connected in the main canvas. The Qmode and Pmode parameters are connected inside the PPC block.

Insert the used adapters and make the necessary connections.

System protection (or SIPS) signals

For some plants system protection is a requirement. In the MTB this functionality is tested with custom signals 1 and 3. 'Signal 3' is used to enable system protection and 'Signal 1' gives the reference in per unit with a base value given by 'Pn'. In the MTB project, two adapters are given to help with the implementation. In this example, the system protection setpoint is given in percent.

To set up system protection, insert the adapters into the main canvas and connect the signals. In this example, the signals are found in the PPC.

Available power signals

Some MTB cases test changes in available power for solar and wind power plants. Custom signal 2 used to be used for this purpose, but from MTB 2.0, a dedicated signal is provided, mtb_Pavail. The value is in pu and is usually "connected" inside the inverter model as a parameter.

If the inverter model requires a percentage value, the signal can easily be scaled as follows,

3.2.4 Connection of additional MTB measurements (Optional)

The MTB block takes measurements at POC. It is possible to add additional measurement points in the model. This measured data will be exported alongside the POC measurements. The block required to do this is called 'Unit measurement' and can be found in the MTB project.

Copy and paste the block into the model and connect it to the point of interest. When pasting in the block use 'Paste Special' -> 'Paste Transfer' to avoid any issues. In this example, the unit measurement block is placed at the inverter terminals.

To set up the measurement block the voltage base and apparent power base have to be set. This is done by right-clicking on the block and selecting 'Edit Parameters...'. Now specify the apparent power base and voltage base. The units are in MVA and kV. In this specific example, the Sbase is 10 MVA and the Vbase is 33 kV. The 'Unit alias' parameter specifies the prefix of the output values names.

3.3 Script Execution

3.3.1 Running all selected cases (Volley mode)

The model is now set up and can be run. An example of a finished model can be seen below.

The MTB will run the cases in parallel. The amount of usable cores depends on both the computer processor and the PSCAD license available. The MTB is by default set to run with a volley count of 8. This means that 8 cases are run simultaneously. To change the volley count change the 'Volley' parameter in the config.ini file.

To run the simulation, right-click on the 'execute_pscad.py' script and press 'Run'.

You can follow along to see the progress by going to the workspace and selecting 'Simulations Sets' -> 'MTB' -> '?Model name?'. Click on a simulation task to view the preliminary results. A lot of different plots are available inside the MTB block. Double-click on the MTB block to access them. The numbering of the simulation tasks does not match the rank of the cases specified in the testcases.xlsx file. This is because the test bench intelligently chooses which cases to run in parallel based on case simulation time. This ensures that the overall simulation time is minimized. To see which simulation task corresponds to which simulation case go to the 'Script Output' tab at the bottom of PSCAD. Here the 'execute_pscad.py' script outputs the 'Rank' (given by testcases.xlsx) and the 'Task ID' (corresponding simulation task in PSCAD) alongside the 'Casename'.

3.3.2 Running individual cases (Manual mode)

To run individual cases,

1. Right click on the MTB block and select 'Edit Parameters...'

2. Change the 'Mode' parameter to Manual

3. Select the desired 'Manual rank'. The rank corresponds to the given rank in the testcases.xlsx Excel file

4. To run the individual case click on 'Run' in the 'execute_pscad.py' file under 'Resources'

The '.psout' file for this case will be saved in an MTB Date-Time subfolder, e.g. MTB_28012026121723, inside the 'export folder'

3.4 Script Execution Finished

Once the script has finished and the simulation runs are complete the output files can be accessed. They are found in the specified path from the config.ini file, by default 'export'. The MTB creates a set of '.psout'-files that can be used with the plotter.py to plot the results and optionally compare it with results from PowerFactory. See the Quickstart Guide Plotter.

3.5 Troubleshooting

3.5.1 Wrong compiler

Running PSCAD with the wrong compiler might lead to errors looking like this

Or this

To change the compiler go to File -> Application Options -> Dependencies. We use the Intel fortran compilers.

3.5.2 UnicodeDecodeError

If the PSCAD project name or the name of the folder the project is stored in contains the letters "æ/ø/å", the execute_pscad.py script will give the following error. To fix this, change the file or folder name.

3.5.3 PSCAD Out of memory (OOM) Error

'''' project.parameters(PlotType = '1', output_filename = f'{plantSettings.Projectname}.out') '''' '''' project.parameters(PlotType = '2', output_filename = f'{plantSettings.Projectname}.psout') ''''