A few usage examples are provided here to help you getting familiar with the package functions and frequency-domain analysis methods. The most simple case consists os a single AC-bus analysis in 2L_VSC. The example in parametric sweep runs several frequency scans at different operating conditions and shows how to interpolate the results to other scenarios. Additionally, the hybrid AC/DC network examined in this paper is provided in the Energy_hub folder. Lastly, the transfer function example illustrates how to use Z-tool to extract the transfer function between any two given signals. If you are a new user, it is recommended to follow aforementioned examples after reading the introduction below.
To use the tool, the following pre-requisites are needed
-
Python 3.7 or higher together with
- Numpy, Scipy, and Matplotlib
- PSCAD automation library
Check the end of the page for instructions on how to install the previous packages.
-
PSCAD v5 or higher is recommeded.
-
Install the Z-tool via cmd
py -m pip install ztoolacdc
The general tool usage can be summarized in the following steps:
- Add the Z-tool PSCAD library to your PSCAD project.
If you are using the tool for the first time in a given project, then add the PSCAD library to your workspace and move it before your project files. Note that if you open an existing PSCAD project from a different PC, like those in the 2L_VSC and Energy_hub examples, the library will appear grayed-out as it points to a different location. After you install the package, the library file Z_tool.pslx is in the Scan folder within the package's installation directory: use the cmd py -m pip show ztoolacdc to find this folder in your computer. Therefore, in the PSCAD project simply unload the grayed-out library by right-cliking on it and selecting Unload, then add the library file Z_tool.pslx within the Z-tool installation path in your PC (Scan folder at the directory retrieved by cmd py -m pip show ztoolacdc), move it up before your project files and save the changes.
- Place the tool's analysis blocks at the target buses and name them uniquely.
Copy the scan blocks from the Z-tool PSCAD library and paste them in series at the desired buses. The location of the scan blocks determines the partition points where the subsystems are to be decoupled. It is necessary to give them a name so the results can be related to actual system nodes; the given name will apear on top of the scan block after introduced. In addition, the base frequency and steady-state voltage magnitude can be specified, although it is not mandatory.
- Define the connectivity of the scan blocks: for single-bus analysis this step is not needed.
If there is more than one scan block, then the topology information needs to be provided so as to scan the system as efficiently as possible, and later study its stability. Only the blocks specified in the topology file are considered for the scan and subsequent analysis while the others are ignored (by-passed). Each scan block has two series-connection points, shown in the canvas by the numbers 1 and 2. The topology is specified via a binary 2N×2N symmetric matrix where N is the number of scan blocks involved:
- A one in the diagonal entries indicates no further connection to other blocks
- Off-diagonal ones indicate interconnection between the blocks at their corresponding sides, which can be 1 or 2
- Zeros indicate no interconnection between the blocks at their corresponding sides
The scan routine decouples the network at these points so each side, i.e. 1 or 2, connects to a different subsystem. When several blocks are interconnected via electrical components they define a subsystem. The sides are labed as X-1 and X-2 in the topology file, where X corresponds to the user-defined PSCAD block name. For instance, the HVDC cable network of the point-to-point example is defined from the MMC1_DC block side 1 to the MMC2_DC block side 1. This is specified in the topology file as a 1 in the row MMC2_DC-1 and column MMC1_DC-1 (and vice-versa as this matrix is symmetric). The other side of each DC scan block connects to a MMC which is also connected to an AC scan block at its AC-side. The special case of AC/DC converters is recognized by the package as these are always key components when studying system dynamics. This table can just be pasted into a text file which path is an argument to the frequency sweep and stability analysis functions. To verify that the system topology is specified correctly, set visualize_network=True in the frequency_sweep function returns a simplified single-line diagram (SLD) pdf file with ending _network_visualization.pdf to make sure the interconnections have been correctly defined.
The corresponding SLD file generated when calling frequency_sweep is shown below: the lines represent admittances between two or more scan blocks defined as the analysis points, e.g. the HVDC cable between MMC1_DC and MMC2_DC, while the red dots point at subsystems which are only at one side of the specified analysis points, e.g. the Thevenin equivalent at the left side of the MMC1_AC block.
- Specify the basic simulation settings and frequency range for the study
The next step is to introduce the scan parameters in the corresponding python script.
The parameters, which are self-descriptive, are provided to the frequency_sweep function which performs the frequency-domain characterization. You can read about the function's documentation by typing help(name_of_the_function) in a python terminal after importing the function, or at the end of the corresponding python file.
""" Simple script template for the frequency sweep and frequency-domain analysis of an EMT model"""
from ztoolacdc.frequency_sweep import frequency_sweep
from ztoolacdc.stability import stability_analysis
from os import getcwd
pscad_folder = getcwd() # Absolute location of the PSCAD workspace (getcwd can be used when the script is in the same folder)
results_folder = pscad_folder + r'\Results' # Location of the folder to store the results
topology = pscad_folder + r'\topology.txt' # Absolute path of topology file
workspace_name = "P2P_study" # Name of the PSCAD workspace (.pswx file)
project_name = "P2P" # Name of the PSCAD project (.pscx file)
fortran_ext= '.gf81' # Fortran compiler extension, e.g. '.gf46' or '.gf81'
output_files = 'example' # Desired name for the output files
perturbations = 8 * 65 # Number of scanned frequencies: ideally a multiple of the possible multi-core simulations number
multi_freq_scan = True # True = 8-tone sinusoidal perturbation, False = single-tone perturbations
f_base = 1 # Base frequency in Hz (determines the frequency resolution)
f_min = 1 # Minimum frequency in Hz
f_max = 3000 # Maximum frequency in Hz
start_fft = 1 # [s] Time for the system to reach steady-state after every perturbation
fft_periods = 1 # Number of periods used in the FFT for the lowest frequency
dt_injections = 1 # [s] Time after the decoupling to reach steady-state (optional, it can be set to zero)
t_snap = 5 # [s] Time for the cold-start of the model after which an snapshot is taken
t_sim = start_fft + fft_periods/f_base # [s] Simulation time during under sinusoidal perturbations
t_step = 20 # [us] Simulation timestep
v_perturb_mag = 0.002 # Voltage perturbation magnitude in per unit with respect to the steady-state value
frequency_sweep(t_snap=t_snap, t_sim=t_sim, t_step=t_step, v_perturb_mag=v_perturb_mag, start_fft=start_fft, multi_freq_scan=multi_freq_scan,
f_points=perturbations, f_base=f_base, f_max=f_max, f_min=f_min, visualize_network=True, fft_periods=fft_periods,
topology=topology, working_dir=pscad_folder, fortran_ext=fortran_ext, dt_injections=dt_injections,
workspace_name=workspace_name, project_name=project_name, results_folder=results_folder, output_files=output_files)
stability_analysis(topology=topology, results_folder=results_folder, file_root=output_files)
After running the script, the status of the scan process can be seen in real time. In addition, the main analysis outcomes are displayed on the screen for quick reference, e.g. stability conclusion and dominant oscillatory mode. You can customize the stability analysis by the arguments provided to the stability_analysis function.
When the process is finished, we can access the results in the specificed results folder. The admittances are ploted in .pdf and saved as .txt tab-separated files. You can read these matrices into by calling the read_admittance function.
If the stability_analysis function is called, then the results also include detailed system stability properties, such as the application of the Nyquist criterion to determine system stability, the eigenvalue decomposition of the closed-loop impedance matrix to reveal the system oscillatory modes and participating buses for the dominant modes, as well as the computation of the passivity index of the different system matrices. If only the stability of the system is of interest the calculation of the other metrics can be disabled by setting their corresponding argument to False, e.g. when run_passivity=False, run_EVD=False the function does not calculate the passivity index and the bus PFs, respectively. Furthermore, additional result logging can be disabled if desired, e.g. make_plot=False and save_results=False.
We recommend reading these openly available papers and checking the webinar slides and recording to better understand the package's functioning principles. You can find four step-by-step examples in the following subfolders: 2L_VSC, Parametric_sweep, Energy_hub and the Transfer_function. Feel free to reach out to Fransciso Javier Cifuentes Garcia in case of questions!
After installing Python or using an exsiting Python version >3.7, you can add the necessary packages with the use of pip following the steps below.
To install the packages you need to open a comand window and call pip through python followed by the package we want to instal.
Firstly, it can be verified that the python version called with py is the intended one by typing py --version
Then, the installation syntax looks like this: py -m pip install NAMEofTHEpackage.
- The Z-tool package can be installed via
py -m pip install ztoolacdcand updated withpy -m pip install ztoolacdc --upgrade - Numpy, Scipy and Matplotlib. Numpy and Scipy packages contain the mathematical functions to handle the numerical data, such as rFFT, inverse matrix computations and EVD. Matplotlib is used to plot the results.
- PSCAD automation library. It is automatically downloaded to your computer after installing PSCAD v5. It should be located in a directory similar to C:\Users\Public\Documents\Manitoba Hydro International\Python\Packages. Here there should be a file named mhi_pscad-2.2.1-py3-none-any.whl or similar. Use the same cmd + pip commands as before, but first go to the folder where the package is located using cmd commands. More information on the PSCAD automation library can be found here.
