Metadata-Version: 2.2
Name: ztoolacdc
Version: 0.1.1
Summary: Frequency domain analysis toolbox for EMT models
Author-email: Francisco Javier Cifuentes Garcia <franciscojavier.cifuentesgarcia@kuleuven.be>
License: GNU GPL v3
Project-URL: Homepage, https://www.esat.kuleuven.be/electa/ztool
Project-URL: Documentation, https://www.esat.kuleuven.be/electa/ztool
Keywords: stability,frequency,admittance,impedance,scan,PSCAD
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=2.0.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: scipy>=1.8
Requires-Dist: mhi-pscad>=2.9.0

# Z-tool
Z-tool is a Python-based implementation for the frequendy-domain analysis of modern power systems.
The core functionalities are admittance characterization and small-signal stability assessment.
The analysis relies on an existing system model in the EMT simulation software [PSCAD]([url](https://www.pscad.com/)).

The following features are currently implemented and validated:
- [x] Voltage perturbation-based admittance scan at several nodes, including MMC-based systems and black-box components
- [x] Stability assessment via Generalized Nyquist Criteria applicable to standalone-stable MIMO systems
- [x] Oscillation mode identification via eigenvalue decomposition (EVD) and bus participation factors
- [x] Passivity assessment and Singular Value Decomposition functions

The flowchart below summarizes a common usage of the tool for stability studies, including frequency-domain system identification ([frequency_sweep](Source/ztoolacdc/frequency_sweep.py)) and several stability analysis functions ([stability_analysis](Source/ztoolacdc/stability.py)):

![Tool flowchart](Doc/flowchart.png)
![Tool summary](Doc/Ztool_summary.png)

## Installation
To use the tool, the following pre-requisites are needed.
1. Python 3.7 or higher together with
   * [Numpy](https://numpy.org/), [Scipy](https://scipy.org/), and [Matplotlib](https://matplotlib.org/) (included in common python installations such as Anaconda)
   * [PSCAD automation library]([url](https://www.pscad.com/webhelp-v5-al/index.html))
   
   See the examples [here](Examples) for more information on how to install the previous in a MS Windows operating system.

2. PSCAD v5 or higher

3. Install the Z-tool via cmd `py -m pip install ztoolacdc` or using the package files.

## Usage
Follow the example(s) described [here](https://gitlab.kuleuven.be/electa/Z-Tool/Z-tool/-/tree/main/Examples). The GUI is currently under development.

## Citing Z-tool
If you find the Z-tool useful in your work, we kindly request that you cite the following publications:
[paper ISGT 2024](https://lirias.kuleuven.be/4201452&lang=en):

```bibtex
@ARTICLE{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},
title = {Automated Frequency-Domain Small-Signal Stability Analysis of Electrical Energy Hubs},
journal = {IEEE PES Innovative Smart Grid Technologies Europe (ISGT Europe) 2024},
publisher = {IEEE},
pages={1-6},
year = {2024}}
```

## Contact Details
For queries about the package or related work please feel free to reach out to [Fransciso Javier Cifuentes Garcia](https://www.kuleuven.be/wieiswie/en/person/00144512)

## 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
* Fransciso Javier Cifuentes Garcia: Main developer
* Thomas Roose: Initial stability analysis functions
* Eros Avdiaj and Özgür Can Sakinci: Validation and support

## Future work
- [x] Exploit the symmetric properties of the admittance matrix for AC (and DC) systems to reduce the scans (less simulation time)
- [x] Allow a previous snapshot to be re-used
- [ ] Snapshot simulation plot
- [ ] Support for non-topology specification: inefficient but easier to use
- [ ] Option to clear the temporary PSCAD files
- [ ] Allow for different computation of the PFs, e.g. admittance PFs
- [ ] Switch between current and voltage perturbation
- [ ] Computation of stability margins: phase, gain and vector margins
<!--- - [ ] Minimum simulation time before starting FFT (does it need to be at least as long as the period of the perturbation or could it be smaller?) --->
<!--- - [ ] Transformation to positive and negative sequence representation 
- [ ] Frequency scan and stability analysis optimization based on the passivity properties of the converters --->
## 
