ztoolacdc 0.1.48

Frequency domain small-signal analysis toolbox for EMT models

Z-tool

Z-tool is a Python-based implementation for the frequendy-domain stability analysis of modern power systems. The core functionalities are measurement/characterization of EMT models in the frequency domain and small-signal stability assessment. The analysis relies on an existing system model in the EMT simulation software PSCAD and/or input frequency response data.

The following features are currently implemented and validated:

• Voltage perturbation-based admittance scan at several nodes, including converter-based systems and black-box components, via frequency_sweep
• Stability assessment via Generalized Nyquist Criteria applicable to standalone-stable MIMO systems
• Oscillation mode identification via closed-loop eigenvalue decomposition and bus participation factors, EVD
• Passivity assessment and small gain theorem application
• Sensitivity of the Nyquist loci with respect to the components' admittance via loci_sensitivity
• Comprehensive stability analysis computing previous and other metrics via stability_analysis
• Frame conversion functions, e.g. from dq-frame to alpha/beta-frame and to positive/negative sequence

The flowchart below summarizes a common usage of the tool for stability studies, including frequency-domain system identification (frequency_sweep) and several stability analysis functions (stability):

Installation

To use the toolbox, the following pre-requisites are needed.

1. Python 3.7 or higher together with
   • Numpy, Scipy, and Matplotlib (included in common python installations such as Anaconda)
   • PSCAD automation library
2. PSCAD v5 or higher is recommended.
3. Install the Z-tool via cmd py -m pip install ztoolacdc or using the repository files. Similarly, cmd py -m pip install ztoolacdc --upgrade updates the package.

Usage

A generic usage of the package can be summarized in the following steps:

1. Add the Z-tool PSCAD library to your PSCAD project
2. Place the tool's scan blocks at the target buses and name them uniquely
3. Define the resulting connectivity of the scan blocks (only for multi-infeed analyses)
4. Specify the basic simulation settings and frequency range for the study
5. Run the frequency scan and small-signal stability analysis functions

Follow the example(s) described here for more guidance. More details on the approach and implemented functions can be found in the papers below and/or this webinar with the complementary slides. The GUI is currently under development.

Other features

• Transfer function scan via the frequency_sweep_TF function, see the example here
• Change of PSCAD component values for parametric studies, see the example here
• Rational fitting via least-squares optimization with the mode_estimation function, see the example here
• Alternative computation of participation factors, e.g. extended PFs via EVD
• Singular value (sigmas) computation for the sensitivity and complementary sensitivity functions
• Exploit the symmetric properties of the system to reduce the scan time (optional)
• Base conversion for the analysis of systems with different voltage levels
• PSCAD control arguments: disabling unnecessary outputs, clear temporary files, keep PSCAD open, retain certificate, etc.
• Previous snapshots can be re-used to speed-up simulations
• Snapshot simulation plots for a quick look into the initialization run

Citing Z-tool

If you find the Z-tool useful in your work, we kindly request that you cite the following publications, which you can freely access here and here.

@INPROCEEDINGS{Cifuentes2024,
  author={Cifuentes Garcia, Francisco Javier and Roose, Thomas and Sakinci, Özgür Can and Lee, Dongyeong and Dewangan, Lokesh and Avdiaj, Eros and Beerten, Jef},
  booktitle={2024 IEEE PES Innovative Smart Grid Technologies Europe (ISGT EUROPE)}, 
  title={Automated Frequency-Domain Small-Signal Stability Analysis of Electrical Energy Hubs}, 
  year={2024},
  pages={1-6},
  doi={10.1109/ISGTEUROPE62998.2024.10863484}}

@article{Cifuentes2025,
author = {Francisco Javier {Cifuentes Garcia} and Jef Beerten},
title = {Z-Tool: Frequency-domain characterization of EMT models for small-signal stability analysis},
journal = {Electric Power Systems Research},
volume = {252},
pages = {112405},
year = {2026},
doi = {https://doi.org/10.1016/j.epsr.2025.112405}}

Contact Details

For queries about the package or related work please feel free to reach out to Fransciso Javier Cifuentes Garcia. You can find more open-source tools for power systems analysis in the etch website.

License

This is a free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Z-tool is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

Contributors

• Francisco Javier Cifuentes Garcia: Main developer
• Thomas Roose: Initial stability analysis functions
• Jan Kircheis, Eros Avdiaj and Özgür Can Sakinci: Validation and support

Future work

• Scans in split projects
• Switch between current and voltage perturbation
• Computation of stability margin