3. Quickstart Guide PSCAD
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.
- Please note: The package "scipy" required for the plotter tool is not compatible with Python 3.7.2. Since it is not required to run the PSCAD MTB, it can be omitted from installation in this regard.
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:
- Install Python 3.7.x (with x > 2)
- Install requirements from PSCAD requirements.txt into the Python 3.7.x installation (or a virtual environment). This can be done by executing,
python -m pip install -r requirements.txt
- 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 -m pip install --target C:\Users\<USERNAME>\AppData\Roaming\Python\Python37\site-packages -r requirements.txt
- 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-packagesorC:\Users\<user-name>\AppData\Roaming\Python\Python37\site-packages
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.x, 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.
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.
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.
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 (from the build folder, i.e. <workspace name>.ifxxx) after ALL 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,
- Volley the number of simulations to be run in parallel (up to a maximum of 64, license dependent) -- see PSCAD help website
-
Tracing when Falsethe simulation runs as a "blind" background process. No data is sent to the PSCAD graphs until the run is completely finished. True, every parallel worker tries to send live data back to the GUI simultaneously.
- This can be useful for debugging, but it can also significantly slow down the simulation.
- It is recommended to set this to False (also the fallback value) for large simulations or when running multiple simulations in parallel.
-
State animation when True, as the simulation runs, the PSCAD GUI constantly updates the schematic to show the current state of the power system. When False, the schematic remains static.
- This can be useful for debugging, but it can also significantly slow down the simulation.
- It is recommended to set this to False (also the fallback value) for large simulations or when running multiple simulations in parallel.
-
Only in use channels when False, the simulation engine calculates and prepares every single signal and component state in the entire project, just in case you want to look at it later. When True, the engine only processes and buffers data for signals that are explicitly connected to an Output Channel or a Plot.
- It is recommended to set this to True (also the fallback value) for large simulations or when running multiple simulations in parallel.
-
Disable all unused PGBs when True, all Plot/Graph Blocks (PGBs) or Output Channels, that are NOT specifically listed in the Plotter's figureSetup.csv file, except for signals starting with MTB\<signal_name>.
- It is recommended to set this to True (also the fallback value) for large simulations, as this reduces not only the size of the .psout files, but also and the possibility of a PSCAD Out of Memory (OoM) error when running a lot of test cases.
- For more information on this feature, please have a look at the PSCAD Out of Memory (OoM) error section
-
Fortran version specifies the Fortran version, see Fortran versions, to be used, when running execute_pscad.py from the command line, 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)
- Workspace specifies the PSCAD workspace file to be used when running execute_pscad.py from the command line
Note
Tracing = False is equal to Disable Tracing, while Tracing = True, is equal to Enable Tracing (All)
With Tracing = False, the Progress and Time will not be displayed in PSCAD's status bar, i.e.
Tip
But to quote from the PSCAD help website, "It is recommended that unless absolutely necessary, that the Tracing option should remain set to Disable Tracing, as the additional processing necessary to send simulation data back to display in graphs, is normally detrimental to the overall speed of the PMR simulation."
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.
- Add the MTB.pslx project into the workspace. Do this by right-clicking on the Projects folder, click 'Add Existing Project...'.
- Add the interface.f file. Do this by right-clicking the Resources folder, click 'Add' -> 'Source Code (*.f, *.for, *.f90, *.c, *.cpp)'.
- Add the execute_pscad.py file. Do this by right-clicking the Resources folder, click 'Add' -> 'Script\Apps (*.py, *.exe, *.bat)'.
- 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)'.
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.
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:
- mtb_Pmode = 0: FSM and LFSM disabled
- mtb_Pmode = 1: LFSM enabled, FSM disabled
- mtb_Pmode = 2: FSM enabled, LFSM disabled
- mtb_Pmode = 3: FSM and LFSM enabled
-
Qmode signal is an integer output determining the reactive power mode. The modes are:
- mtb_Qmode = 0: Reactive power mode (Q)
- mtb_Qmode = 1: Voltage mode (Qu)
- 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.
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.
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.
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.
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.
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.
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 can be used to set the upper limit for the solar converter output.
the Pavail signal can sent to inside the solar plant to directly control the solar irradiation in W/m2.
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.
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'.
To run individual cases,
- Right click on the MTB block and select 'Edit Parameters...'
- Change the 'Mode' parameter to Manual
- Select the desired 'Manual rank'. The rank corresponds to the given rank in the testcases.xlsx Excel file
- 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'
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.
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.
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.
Something peculiar happen when we moved from having PSCAD '.out' output files,
project.parameters(PlotType = '1', output_filename = f'{plantSettings.Projectname}.out')
to PSCAD '.psout' output files, see also PSOUT Format (V5+)
project.parameters(PlotType = '2', output_filename = f'{plantSettings.Projectname}.psout')
First of all, PSCAD 5.0.1 gave "PlotType" errors which implied that only PSCAD 5.0.2 could be used, and secondly, for large project with a lot of signals and when running a lot of test cases, a PSCAD Out of memory error sometimes occurs. Usually when the PSCAD server is heavily utilized. We suspect that this is due to a memory leak in PSCAD when working with these binary files, but this is being disputed by MHI...
As a result, we add the feature to writing a caseRankTaskID.csv file to the MTB folder with the mapping the Case rank number to the Task IDs, prior to running the Volley. This allows the '.psout' files in the build folder, usually ending in .ifxx, e.g. .if15_86 for Intel Fortran 15 (32bit) saved with Task ID number, to be renamed with their Case rank number and moved to a different folder location using the recover_psout_files.py script.
Task IDs are assigned based on 'Simulation time'. By confirming which test cases have been completed, a re-run of the MTB can be done with already ran cases removed to save the simulation time on the second run. If this OOM error occurs regularly, two workarounds have been tested to solve the issue.
The first workaround is to use the following batch_execute_pscad.py script to run all the test cases in small batches, e.g.
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, for the example above, will then be stored in six MTB-timestampped folders, e.g.
The second workaround is to set Disable all unused PGBs = True in config.ini to disable all Plot/Graphic Blocks (PGBs) our Output Channels not specifically listed in the Plotter's figureSetup.csv
- With Disable all unused PGBs = True, the following functions from pscad_synchronize_pgbs.py from are called:
- getSignalsFromFigureSetup - to get the signals from figureSetup.csv that needs to be kept
- validateFigureSetupAgainstWorkspace - validate if these signals can be found in the PSCAD Projects,
- synchronizePGBsInProject - Enable all PGBs that are required by figureSetup.csv, and Disables all PGBs not required
- printPGBStatus - to print the status of all PGBs in a Project
The pscad_synchronize_pgbs.py file can also be run as a standalone script inside PSCAD to check which signals
- Will be kept
- Will be disabled
- Are already disabled
- To check the pathname of the signals if validateFigureSetupAgainstWorkspace cannot find the signal specified in figureSetup.csv
e.g. running from PSCAD with the following default settings
will result in the following output, where the signals PPC\Pcontrol\Pref and *PPC\Pcontrol\Pout were included in figureSetup.csv
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]
...
--------------
Enabled : 8
Disabled: 9
...
============================================================
Total enabled : 132
Total disabled: 88
Will keep : 10
Will disable : 123
Project Solbakken DRY RUN: Would disable 123, and enable 1.
============================================================
We did a test on an arbitrary TSO plant, Solbakken
-
With batch_execute_pscad.py,
- Requires converting testcases.xlsx into smaller sets of test cases
- Total size of all the result is 10.3 GB
- But all signals from the plant is available
-
With Disable all unused PGBs = True
- Can use the testcase.xlsx as is
- Size of the result is 4.97 GB
- But only plant signals specifically listed in figureSetup.csv will be available for post processing
