2. User Manual

Software package

As shown in the figure below, IMTB software package includes:

• PSCAD library (.pslx)
• Packaged version with an executable file (.exe) or script version with multiple Python scripts (.py with dependence on installed Python modules)
• A template user input file for multi-scenario tests (.xlsx)

(a)

(b)

Figure 1 IMTB software package. (a)Packaged version; (b) Script version.

Simulation environment

To use IMTB, preparation of the simulation environment is needed. It includes preparing the EMT simulation environment and Python environment if the user wants to use the script version.

EMT simulation environment:

• EMT tool: PSCAD 5.0.2 and above

Note

• PSCAD 5.0.0 or PSCAD 5.0.1 can work, but bugs were found with the snapshot function. If users want to use IMTB in PSCAD 5.0.0 or PSCAD 5.0.1, please always NOT use the snapshot function.
• The IMTB is NOT applicable for PSCAD version lower than 5.0.0.

• EMT compiler preparation for GUI working properly can be done based on the following instruction:

The GUI uses an MHI function to look for installed compilers on the machine you use it, but this PSCAD list could be an outdated version, so you can take steps below by changing the list yourself, as shown in figure below.

1. Open environment medic from PSCAD (sometimes called Fortran Medic)
2. In the medic navigate: Actions -> Generate installed products list
3. Restart PSCAD and IMTB

Figure 2. Fortran complier drop down instruction

Python environment:

• Packaged version (.exe): IMTB can be run directly with an executable file without in-stalling Python modules
• Script version (.py): the following required Python modules are needed to be installed
  • Python: 3.9+ (the developer tests the tool using this Python version and above)
  • PySimpleGUI==4.60.5 (this version is free of charge. In case that PySimpleGUI cannot be installed with the older version, you can apply FreeSimpleGUI, then update the corresponding import script in "IMTB_gui.py" by using import FreeSimpleGUI as sg)
  • xml
  • mhi-pscad
  • mhi-psout
  • numpy
  • pandas
  • Plotly
  • Tqdm
  • openpyxl

Note

Please be aware that there can be python module dependencies based on the selected Python version and the programming environment. If any issue arises in the Python environment preparation, please check the Python module dependence and reinstall with compatible versions of python modules of different libraries. For the user’s reference, the tool developer’s Python environment is provided below.

• Python==3.9.19
• PySimpleGUI==4.60.5
• xml (not version specific, but need to be installed)
• mhi-pscad==2.9.5
• mhi-psout==1.0.4
• numpy==1.26.4
• pandas==2.2.2
• Plotly==5.22.0
• Tqdm=4.49.0
• Openpyxl==3.1.5

Model setup

Before running IMTB, the user needs to configure model setup in PSCAD project to enable the IMTB execution.

Check snapshot and data saving functions before start

Important

Note that this is the step before using IMTB. It is recommended for users to check beforehand, as it ensures that your PSCAD model to be tested have the correct snapshot and data saving functions to enable IMTB execution.

1. Check your PSCAD model with snapshot function and data saving correctly

• It must support to run from a saved snapshot to enable this function in IMTB.
  • Some user-defined or black-box PSCAD models support snapshot but need time to settle even after starting from snapshot. In this case, user need to add this additional time to “Settling time” pa-rameter in the frequency scan settings.
  • If model does not provide snapshot functionality, disable this in IMTB GUI and add the startup time to the Settling time parameter.
• For PSCAD project models originally developed in a version lower than V5.0.2, after checking running from snapshot, save the project in PSCAD V5.0.2. This is to ensure automation library can execute correctly with no compatibility issues.
• Check if the data can be saved in “Advanced (*.psout)” mode.

Note

Note that there are bugs found with PSCAD V5.0.0 or V5.0.1 to save "psout" files from snapshot. Therefore, if the user wants to use IMTB with PSCAD V5.0.0 or V5.0.1, please disable the snapshot function and consider sufficient time in “Settling time”.

2. Configure your model correctly, and get an understanding what is the time needed for snapshot (to let the model run into stationary behavior, from which the scan can be executed)

Figure 3. Check snapshot and "psout" saving functions.

Configure IMTB

1. Create PSCAD workspace in the same folder of the project file
2. Save the IMTB PSCAD library in the workspace folder and load it into the workspace, as shown in Figure 4(a). All libraries shall be above any project case in the sequence.
3. Add IMTB tool into PSCAD project and define parameters of the tool, as shown Figure 4(b). Do NOT add with dependencies (just copy paste the object from library to your model case). The IMTB toolbox definition shall still be in the IMTB library.
4. Create a simulation set with the project(s) to simulate with IMTB, as shown in Figure 4(a). It can include more than one project case, if necessary.
5. If any changes in control pannels (reference values, SCR etc.) need to be done, set those as default values. Explanation: after PSCAD restarts, all values will be set to default.
6. If multiple scenario test function is to be applied, save the scenario EXCEL file in the workspace folder, and configure the parameter mappings in the EXCEL file and the PSCAD project, as shown in Figure 5.

Important

The naming of variables defined in the EXCEL file shall be unique in all PSCAD project files!

7. Save workspace and project, and then close PSCAD.

(a)

(b)

Figure 4. Configure IMTB in a workspace file. (a) Configure workspace and simulation set; (b) Configure IMTB component and its parameters.

(a)

(b)

Figure 5. Configure parameter mapping for multiple scenario test. (a) Parameter definition in EXCEL file; (b) Parameter definition in PSCAD project.

Frequency scan procedures and simulation setup

The frequency scan starts with the GUI setting as shown in Figure 6. It includes simulation settings in the left column and the frequency scan settings in the right column.

Figure 6. GUI setting of the IMTB.

Simulation settings

• Workspace – Browse workspace, then the associated PSCAD version, license type and Fortran information shall be automatically loaded. Changes can be made if needed. Check all the parameters for errors (e.g. fortran extension has some automation, but can be faulty depending on the machine setup). If any previous settings are still in the same folder, the GUI will try to load them.
• Max. parallel simulations –This is the number of cores to be used for paralleled simulations in perturbation injections, each core will run a single-tone perturbation injection. The number needs to be no larger than the maximum core number minus 1. It can be set to 1 for no parallel simulations.
• Simulation name – Define simulation name (a folder will be created accordingly for this scan data)
• Simulation set – Select PSCAD simulation set, the dropdown menu will contain all simulation sets that are linked to chosen workspace
• Simulation settings – Define some simulation settings, e.g. fundamental frequency, solution timestep etc. Plot timestep can be automatically updated based on frequency scan settings. Plot timestep will affect the maximum frequency of the scan.
• Snapshot function – IMTB offers a way to use the snapshot function for the simulation model to settle in a chosen operating point and start scan from this point on. In this way it is not needed to simulate the startup period for each scanned frequency. It also allows to start from previously created snapshot. Be aware that the simulation settings and the model needs to be same as in the model used to create the snapshot. It is only advised to use snapshots created by IMTB only.

Warning

Snapshot function works in IMTB only for PSCAD v5.0.2 and (probably) higher. For lower versions please disable this function and add the startup time of the simulation model as the “settling time” parameter.

• Multi-scenario function – Enable multi-scenario function if this function is chosen and browse the scenario EXCEL file.

Frequency scan settings

• Terminal type – “AC” or “DC” PoC
• Injection type – “series” or “shunt” injection, where “series” applies controlled voltage sources in series as perturbations and “shunt” applies controlled current sources in parallel as perturbations
• Immittance type – “SISO” or “MIMO”, which defines the scan implemented in SISO immittance or MIMO immittance / transfer function
• Injection components – e.g. “pos” or “neg” for AC SISO scan, “posneg” or “dq” for AC MIMO scan, “ab” or “cb” for DC SISO scan, etc.
• Injection amplitude – user defined (0.01-0.05 p.u. as recommended range to start with)
• Frequency range – “custom”, “complete(log)” or “complete(truelog)”.
  • With “custom”, user can select “linear” or “log” or “truelog” frequency sweep type and the related parameters. Only single type of frequency sweep will be applied
  • With “complete(log)” or “complete(truelog)”, user can apply some combined fre-quency ranges with different frequency sweep types. The user only needs to define what is the stop frequency. By default, linear scale is chosen in lower frequency range, and log or truelog scale is chosen in higher frequency range.
  • User may check the frequency array by clicking “see injection frequency array” to understand the applied frequency range after the setting is configured.
• Frequency sweep type – “linear” or “log” or “truelog”, when choosing “custom” frequency range.
  • “log” scans for defined number of steps between each logarithmical step (eg from 1 to 2 or from 60 to 70).
  • In “truelog” user can define the number of points to be scanned in the de-fined range. Those will be rounded to nearest integer value. This means that the real number of points will be lower as it is setup to.
• Start/stop frequency – user defined when relevant
• Frequency step – user defined, only valid when choosing “linear” sweep type
• Points between log – user defined, only valid when choosing “log” sweep type
• Number of points – user defined, only valid when choosing “truelog” sweep type
• Settling time – the time window needed for perturbation injection to settle to steady state
• Injection time – the time window needed for perturbation injection to perform discrete Fourier transformation
• Plot impedances – enabled means that the frequency scan results will be plotted on Bode diagrams
• Plot harmonics – by default disabled. It can be enabled for steady-state harmonic analysis if needed to help with analysis.
• Calculate NET – can be enabled if the network side frequency scan is also expected
• Clear RAW data – by default enabled. It will clean the time-domain raw simulation data from EMT simulation after the frequency scan is done.

Execution

After the GUI settings are done, execute “START”, the tool will automatically open PSCAD to run the simulation, record time-domain raw data, calculate impedance(s) and plot impedance(s). There are also quick information buttons “(i)” for most parameters. User may check the relevant information regarding the relevant parameters.

Results

After the frequency scan is completed, the data will be archived in the folder named “IMTB_data” in the workspace folder, and the folder structure is organized as follows.

• Workspace folder
  • IMTB_data
    • TimeStamp_SimulationName
      • "settings.csv" – the setting information of the scan
      • Impedance data saved in “.csv” and “.xlsx” files
      • Impedance plots saved in “.html” files
      • (Optionally) Plot of the harmonics in “.html” file

(a)

(b)

Figure 7. Result folder structure. (a) Simulation folders under “IMTB_data”; (b) Setting and output files under each simulation folder.