# 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)):
## Installation
To use the toolbox, 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))
2. PSCAD v5 or higher is recommended.
3. Install the Z-tool via cmd `py -m pip install ztoolacdc` or using the package files.
## 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 analysis blocks at the target buses and name them uniquely
3. Define the resulting connectivity of the scan blocks
4. Specify the basic simulation settings and frequency range for your study
5. Run the frequency scan and small-signal stability analysis functions
Follow the example(s) described [here](Examples/README.md) for more details. We recommend reading this [paper](https://ieeexplore.ieee.org/document/10863484) and checking the webinar [slides](Doc/Z%20tool%20webinar%20slides%2013-02-2025.pdf) and recording to better understand the package's functioning principles. 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 which you can access [here](https://lirias.kuleuven.be/4201452&lang=en):
```bibtex
@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}}
```
## 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). You can find more open-source tools for power systems analysis in the [etch website](https://etch.be/en/research/open-source-tools).
## 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 --->
Raw data
{
"_id": null,
"home_page": null,
"name": "ztoolacdc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "stability, frequency, admittance, impedance, scan, PSCAD",
"author": null,
"author_email": "Francisco Javier Cifuentes Garcia <franciscojavier.cifuentesgarcia@kuleuven.be>",
"download_url": "https://files.pythonhosted.org/packages/a4/02/7eacb4cc0276f796959e55a055c70a82814ec78e172f4e8d654bbc6e6721/ztoolacdc-0.1.25.tar.gz",
"platform": null,
"description": "# Z-tool\r\nZ-tool is a Python-based implementation for the frequendy-domain analysis of modern power systems.\r\nThe core functionalities are admittance characterization and small-signal stability assessment.\r\nThe analysis relies on an existing system model in the EMT simulation software [PSCAD]([url](https://www.pscad.com/)).\r\n\r\nThe following features are currently implemented and validated:\r\n- [x] Voltage perturbation-based admittance scan at several nodes, including MMC-based systems and black-box components\r\n- [x] Stability assessment via Generalized Nyquist Criteria applicable to standalone-stable MIMO systems\r\n- [x] Oscillation mode identification via eigenvalue decomposition (EVD) and bus participation factors\r\n- [x] Passivity assessment and Singular Value Decomposition functions\r\n\r\nThe 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)):\r\n\r\n\r\n\r\n\r\n## Installation\r\nTo use the toolbox, the following pre-requisites are needed.\r\n1. Python 3.7 or higher together with\r\n * [Numpy](https://numpy.org/), [Scipy](https://scipy.org/), and [Matplotlib](https://matplotlib.org/) (included in common python installations such as Anaconda)\r\n * [PSCAD automation library]([url](https://www.pscad.com/webhelp-v5-al/index.html))\r\n2. PSCAD v5 or higher is recommended.\r\n3. Install the Z-tool via cmd `py -m pip install ztoolacdc` or using the package files.\r\n\r\n## Usage\r\nA generic usage of the package can be summarized in the following steps:\r\n1. Add the Z-tool PSCAD library to your PSCAD project\r\n2. Place the tool's analysis blocks at the target buses and name them uniquely\r\n3. Define the resulting connectivity of the scan blocks\r\n4. Specify the basic simulation settings and frequency range for your study\r\n5. Run the frequency scan and small-signal stability analysis functions\r\n\r\nFollow the example(s) described [here](Examples/README.md) for more details. We recommend reading this [paper](https://ieeexplore.ieee.org/document/10863484) and checking the webinar [slides](Doc/Z%20tool%20webinar%20slides%2013-02-2025.pdf) and recording to better understand the package's functioning principles. The GUI is currently under development.\r\n\r\n## Citing Z-tool\r\nIf you find the Z-tool useful in your work, we kindly request that you cite the following publications which you can access [here](https://lirias.kuleuven.be/4201452&lang=en):\r\n\r\n```bibtex\r\n@INPROCEEDINGS{Cifuentes2024,\r\n author={Cifuentes Garcia, Francisco Javier and Roose, Thomas and Sakinci, \u00d6zg\u00fcr Can and Lee, Dongyeong and Dewangan, Lokesh and Avdiaj, Eros and Beerten, Jef},\r\n booktitle={2024 IEEE PES Innovative Smart Grid Technologies Europe (ISGT EUROPE)}, \r\n title={Automated Frequency-Domain Small-Signal Stability Analysis of Electrical Energy Hubs}, \r\n year={2024},\r\n pages={1-6},\r\n doi={10.1109/ISGTEUROPE62998.2024.10863484}}\r\n\r\n```\r\n\r\n## Contact Details\r\nFor 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). You can find more open-source tools for power systems analysis in the [etch website](https://etch.be/en/research/open-source-tools).\r\n\r\n## License\r\nThis 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.\r\n\r\n## Contributors\r\n* Fransciso Javier Cifuentes Garcia: Main developer\r\n* Thomas Roose: Initial stability analysis functions\r\n* Eros Avdiaj and \u00d6zg\u00fcr Can Sakinci: Validation and support\r\n\r\n## Future work\r\n- [x] Exploit the symmetric properties of the admittance matrix for AC (and DC) systems to reduce the scans (less simulation time)\r\n- [x] Allow a previous snapshot to be re-used\r\n- [ ] Snapshot simulation plot\r\n- [ ] Support for non-topology specification: inefficient but easier to use\r\n- [ ] Option to clear the temporary PSCAD files\r\n- [ ] Allow for different computation of the PFs, e.g. admittance PFs\r\n- [ ] Switch between current and voltage perturbation\r\n- [ ] Computation of stability margins: phase, gain and vector margins\r\n<!--- - [ ] 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?) --->\r\n<!--- - [ ] Transformation to positive and negative sequence representation \r\n- [ ] Frequency scan and stability analysis optimization based on the passivity properties of the converters --->\r\n",
"bugtrack_url": null,
"license": "GNU GPL v3",
"summary": "Frequency domain analysis toolbox for EMT models",
"version": "0.1.25",
"project_urls": {
"Documentation": "https://www.esat.kuleuven.be/electa/ztool",
"Homepage": "https://www.esat.kuleuven.be/electa/ztool"
},
"split_keywords": [
"stability",
" frequency",
" admittance",
" impedance",
" scan",
" pscad"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8c8cca8a711c8a94fecbbc65d2b6c77483046b88c5b527286dee72130ccceae6",
"md5": "798646233d476197bd497f93eea5ea86",
"sha256": "554c20dd825ec4226b95639c73099ade3b1bc772f9ebd0c8f3810ef828084b81"
},
"downloads": -1,
"filename": "ztoolacdc-0.1.25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "798646233d476197bd497f93eea5ea86",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 154916,
"upload_time": "2025-02-24T10:09:57",
"upload_time_iso_8601": "2025-02-24T10:09:57.886815Z",
"url": "https://files.pythonhosted.org/packages/8c/8c/ca8a711c8a94fecbbc65d2b6c77483046b88c5b527286dee72130ccceae6/ztoolacdc-0.1.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a4027eacb4cc0276f796959e55a055c70a82814ec78e172f4e8d654bbc6e6721",
"md5": "16004999b2b1e9b7eb7b6237fe13138b",
"sha256": "db3142e3bd7acad631dafaf674ac9bbecc86827d08bba29203d8fec2f5092249"
},
"downloads": -1,
"filename": "ztoolacdc-0.1.25.tar.gz",
"has_sig": false,
"md5_digest": "16004999b2b1e9b7eb7b6237fe13138b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 148549,
"upload_time": "2025-02-24T10:10:00",
"upload_time_iso_8601": "2025-02-24T10:10:00.068971Z",
"url": "https://files.pythonhosted.org/packages/a4/02/7eacb4cc0276f796959e55a055c70a82814ec78e172f4e8d654bbc6e6721/ztoolacdc-0.1.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-24 10:10:00",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ztoolacdc"
}
JSON