# ⚡ py-dss-toolkit: Advanced Python Tools for OpenDSS Powered by EPRI
[](https://pypi.org/project/py-dss-toolkit/)
[](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/LICENSE)
[](https://github.com/PauloRadatz/py_dss_toolkit/actions)
**`py-dss-toolkit`** is a Python package that builds on the capabilities of the [`py-dss-interface`](https://github.com/PauloRadatz/py_dss_interface) package to provide advanced functionalities for creating Python-OpenDSS solutions more efficiently. By combining the robust connection to OpenDSS provided by `py-dss-interface` with the feature-rich tools of `py-dss-toolkit`, users can streamline their workflows and gain powerful new capabilities for analyzing and manipulating OpenDSS models, simulations, and results.
🔗 For more information about `py-dss-interface`, visit the [GitHub repository](https://github.com/PauloRadatz/py_dss_interface).
🚨 Note: This project was previously known as `py-dss-tools` and the repository was named `py_dss_tools`. It has been renamed to avoid naming conflicts on PyPI.
## 📦 Installation
You can install `py-dss-toolkit` in two ways:
### 👤 User Installation
If you simply want to use the package:
```bash
pip install py-dss-toolkit
```
### 👨💻 Developer Installation
If you want to contribute or explore the source code:
```bash
git clone https://github.com/PauloRadatz/py_dss_toolkit.git
cd py_dss_toolkit
pip install -e .
```
## ✨ Features
- Retrieve, analyze, and visualize OpenDSS model data using with ease.
- Flexible simulation result access via `dss_tools` or structured workflows via `CreateStudy`.
- Visualize circuit topology, voltage profiles, and time-series using DSSView, Plotly, or Matplotlib.
- Extract Simulation results directly into pandas DataFrames.
- Built on top of `py-dss-interface`.
## 🚀 What Can You Do With py-dss-toolkit?
### 🔍 1. Model Exploration and Manipulation
- Access detailed model information via organized pandas DataFrames.
- Modify models efficiently with built-in Pythonic tools.
📘 [Example Notebook](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/models.ipynb)
### 📊 2. Exploring Simulation Results Capabilities
- Retrieve SnapShot power flow results (voltages, currents, powers) via organized pandas DataFrames.
- Extract QSTS simulation data including meters and monitors.
📘 [Snapshot Results](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/snapshot_results.ipynb)
📘 [QSTS Results](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/qsts_results.ipynb)
### 📈 3. Visualize Simulation Results
`py-dss-toolkit` supports multiple methods to visualize:
- Circuit topology
- Voltage profiles
- Time-series results
All three can be visualized using:
- 🖥️ **DSSView.exe** — the native visualization tool for OpenDSS.
- 🔍 **Plotly (interactive)** — browser-based interactive plots.
- 🧾 **Matplotlib (static)** — publication-ready static charts.
📘 [Circuit Interactive View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/circuit_interactive_view.ipynb)
📘 [Voltage Profile DSS View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/voltage_profile_dss_view.ipynb)
📘 [Voltage Profile Interactive View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/voltage_profile_interactive_view.ipynb)
📘 [Voltage Profile Static View](https://github.com/PauloRadatz/py_dss_tools/blob/master/examples/dss_tools/voltage_profile_static_view.ipynb)
## 🛠️ How to Use py-dss-toolkit?
### 🔧 1. Directly with the `dss_tools` Object
This approach is ideal when you want full flexibility to use `py-dss-toolkit` alongside your own custom logic or an existing `py-dss-interface` workflow. It allows you to:
- Inject the active DSS object into `py-dss-toolkit` using `update_dss()`
- Use any feature provided by `py-dss-toolkit` independently of the study type
- Combine different simulation types, preprocessing, and postprocessing in a custom flow
✅ **Pros:**
- Full control and flexibility
- Ideal for experienced users who want to mix tools freely
- Easily integrates into existing scripts
⚠️ **Cons:**
- No study-type validation (e.g., SnapShot vs QSTS restrictions)
- Higher chance of calling functions that don’t match the simulation context
- Slightly steeper learning curve for py-dss-interface beginners
```python
import py_dss_interface
from py_dss_toolkit import dss_tools
dss = py_dss_interface.DSS()
dss.text("compile path/to/model.dss")
dss_tools.update_dss(dss)
dss.text("solve")
dss_tools.interactive_view.voltage_profile()
```
### 🧪 2. Using the `CreateStudy` Class
This approach is best when you want a clear, structured workflow that restricts available features based on the type of study you are performing (e.g., SnapShot, QSTS). It abstracts the setup and ensures that only relevant tools are available, helping avoid mistakes or invalid calls.
✅ **Pros:**
- Easier for beginners to follow and use safely
- Prevents access to results or views that don’t apply to the selected study type
- Provides a cleaner, study-oriented interface
⚠️ **Cons:**
- Less flexible than using `dss_tools` directly
- You are limited to workflows supported by the framework
- More abstraction might make it harder to customize or mix multiple simulations
```python
from py_dss_toolkit import CreateStudy
study = CreateStudy.snapshot("Snapshot Study", dss_file="path/to/model.dss")
study.run()
study.interactive_view.circuit_plot()
```
## 🤝 Community and Support
Contributions and feedback are welcome! Open an issue or start a discussion on the [GitHub Issues Page](https://github.com/PauloRadatz/py_dss_tools/issues).
This project is under active development, and there are many additional features that could be included in the future. If you have ideas or specific needs, feel free to open a feature request, contribute directly, or reach out to me!
## 📚 How to Cite
If you use `py-dss-toolkit` in your academic work, please reference it as follows:
**APA Style:**
Radatz, P. (2025). *py-dss-toolkit: Advanced Python Tools for OpenDSS powered by EPRI* (Version X.X.X) [Computer software]. GitHub. https://github.com/PauloRadatz/py_dss_tools
**BibTeX Entry:**
```bibtex
@software{radatz2025pydsstools,
author = {Paulo Radatz},
title = {py-dss-toolkit: Advanced Python Tools for OpenDSS powered by EPRI},
year = {2025},
version = {X.X.X},
url = {https://github.com/PauloRadatz/py_dss_tools}
}
```
📌 Please replace `X.X.X` with the version of the package you are using.
## 🙏 Acknowledgements
Developed and maintained by [Paulo Radatz](https://www.linkedin.com/in/pauloradatz/), with support from the global OpenDSS community.
Special thanks to the OpenDSS community and all contributors and users who have provided feedback and inspiration. The development of `py-dss-toolkit` builds on the foundation laid by [`py-dss-interface`](https://github.com/PauloRadatz/py_dss_interface).
---
Raw data
{
"_id": null,
"home_page": null,
"name": "py-dss-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "OpenDSS, Python, Power Systems, Distribution Systems, Energy",
"author": null,
"author_email": "Paulo Radatz <paulo.radatz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8b/5b/3c05d06ab19d6f5bfe0e52a79bfdeaa4346c3ad50848b10f90b1ec814ce6/py_dss_toolkit-0.4.0.tar.gz",
"platform": null,
"description": "# \u26a1 py-dss-toolkit: Advanced Python Tools for OpenDSS Powered by EPRI\r\n\r\n[](https://pypi.org/project/py-dss-toolkit/)\r\n[](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/LICENSE)\r\n[](https://github.com/PauloRadatz/py_dss_toolkit/actions)\r\n\r\n**`py-dss-toolkit`** is a Python package that builds on the capabilities of the [`py-dss-interface`](https://github.com/PauloRadatz/py_dss_interface) package to provide advanced functionalities for creating Python-OpenDSS solutions more efficiently. By combining the robust connection to OpenDSS provided by `py-dss-interface` with the feature-rich tools of `py-dss-toolkit`, users can streamline their workflows and gain powerful new capabilities for analyzing and manipulating OpenDSS models, simulations, and results.\r\n\r\n\ud83d\udd17 For more information about `py-dss-interface`, visit the [GitHub repository](https://github.com/PauloRadatz/py_dss_interface).\r\n\r\n\ud83d\udea8 Note: This project was previously known as `py-dss-tools` and the repository was named `py_dss_tools`. It has been renamed to avoid naming conflicts on PyPI.\r\n\r\n\r\n## \ud83d\udce6 Installation\r\n\r\nYou can install `py-dss-toolkit` in two ways:\r\n\r\n### \ud83d\udc64 User Installation\r\n\r\nIf you simply want to use the package:\r\n\r\n```bash\r\npip install py-dss-toolkit\r\n```\r\n\r\n### \ud83d\udc68\u200d\ud83d\udcbb Developer Installation\r\n\r\nIf you want to contribute or explore the source code:\r\n\r\n```bash\r\ngit clone https://github.com/PauloRadatz/py_dss_toolkit.git\r\ncd py_dss_toolkit\r\npip install -e .\r\n```\r\n\r\n## \u2728 Features\r\n\r\n- Retrieve, analyze, and visualize OpenDSS model data using with ease.\r\n- Flexible simulation result access via `dss_tools` or structured workflows via `CreateStudy`.\r\n- Visualize circuit topology, voltage profiles, and time-series using DSSView, Plotly, or Matplotlib.\r\n- Extract Simulation results directly into pandas DataFrames.\r\n- Built on top of `py-dss-interface`.\r\n\r\n## \ud83d\ude80 What Can You Do With py-dss-toolkit?\r\n\r\n### \ud83d\udd0d 1. Model Exploration and Manipulation\r\n\r\n- Access detailed model information via organized pandas DataFrames.\r\n- Modify models efficiently with built-in Pythonic tools.\r\n\r\n\ud83d\udcd8 [Example Notebook](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/models.ipynb)\r\n\r\n### \ud83d\udcca 2. Exploring Simulation Results Capabilities\r\n\r\n- Retrieve SnapShot power flow results (voltages, currents, powers) via organized pandas DataFrames.\r\n- Extract QSTS simulation data including meters and monitors.\r\n\r\n\ud83d\udcd8 [Snapshot Results](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/snapshot_results.ipynb)\r\n\ud83d\udcd8 [QSTS Results](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/qsts_results.ipynb)\r\n\r\n### \ud83d\udcc8 3. Visualize Simulation Results\r\n\r\n`py-dss-toolkit` supports multiple methods to visualize:\r\n- Circuit topology\r\n- Voltage profiles\r\n- Time-series results\r\n\r\nAll three can be visualized using:\r\n- \ud83d\udda5\ufe0f **DSSView.exe** \u2014 the native visualization tool for OpenDSS.\r\n- \ud83d\udd0d **Plotly (interactive)** \u2014 browser-based interactive plots.\r\n- \ud83e\uddfe **Matplotlib (static)** \u2014 publication-ready static charts.\r\n\r\n\ud83d\udcd8 [Circuit Interactive View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/circuit_interactive_view.ipynb)\r\n\ud83d\udcd8 [Voltage Profile DSS View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/voltage_profile_dss_view.ipynb)\r\n\ud83d\udcd8 [Voltage Profile Interactive View](https://github.com/PauloRadatz/py_dss_toolkit/blob/master/examples/dss_tools/voltage_profile_interactive_view.ipynb)\r\n\ud83d\udcd8 [Voltage Profile Static View](https://github.com/PauloRadatz/py_dss_tools/blob/master/examples/dss_tools/voltage_profile_static_view.ipynb)\r\n\r\n## \ud83d\udee0\ufe0f How to Use py-dss-toolkit?\r\n\r\n### \ud83d\udd27 1. Directly with the `dss_tools` Object\r\n\r\nThis approach is ideal when you want full flexibility to use `py-dss-toolkit` alongside your own custom logic or an existing `py-dss-interface` workflow. It allows you to:\r\n\r\n- Inject the active DSS object into `py-dss-toolkit` using `update_dss()`\r\n- Use any feature provided by `py-dss-toolkit` independently of the study type\r\n- Combine different simulation types, preprocessing, and postprocessing in a custom flow\r\n\r\n\u2705 **Pros:**\r\n- Full control and flexibility\r\n- Ideal for experienced users who want to mix tools freely\r\n- Easily integrates into existing scripts\r\n\r\n\u26a0\ufe0f **Cons:**\r\n- No study-type validation (e.g., SnapShot vs QSTS restrictions)\r\n- Higher chance of calling functions that don\u2019t match the simulation context\r\n- Slightly steeper learning curve for py-dss-interface beginners\r\n\r\n```python\r\nimport py_dss_interface\r\nfrom py_dss_toolkit import dss_tools\r\n\r\ndss = py_dss_interface.DSS()\r\ndss.text(\"compile path/to/model.dss\")\r\ndss_tools.update_dss(dss)\r\n\r\ndss.text(\"solve\")\r\n\r\ndss_tools.interactive_view.voltage_profile()\r\n```\r\n\r\n### \ud83e\uddea 2. Using the `CreateStudy` Class\r\n\r\nThis approach is best when you want a clear, structured workflow that restricts available features based on the type of study you are performing (e.g., SnapShot, QSTS). It abstracts the setup and ensures that only relevant tools are available, helping avoid mistakes or invalid calls.\r\n\r\n\u2705 **Pros:**\r\n- Easier for beginners to follow and use safely\r\n- Prevents access to results or views that don\u2019t apply to the selected study type\r\n- Provides a cleaner, study-oriented interface\r\n\r\n\u26a0\ufe0f **Cons:**\r\n- Less flexible than using `dss_tools` directly\r\n- You are limited to workflows supported by the framework\r\n- More abstraction might make it harder to customize or mix multiple simulations\r\n\r\n```python\r\nfrom py_dss_toolkit import CreateStudy\r\n\r\nstudy = CreateStudy.snapshot(\"Snapshot Study\", dss_file=\"path/to/model.dss\")\r\nstudy.run()\r\n\r\nstudy.interactive_view.circuit_plot()\r\n```\r\n\r\n## \ud83e\udd1d Community and Support\r\n\r\nContributions and feedback are welcome! Open an issue or start a discussion on the [GitHub Issues Page](https://github.com/PauloRadatz/py_dss_tools/issues).\r\n\r\nThis project is under active development, and there are many additional features that could be included in the future. If you have ideas or specific needs, feel free to open a feature request, contribute directly, or reach out to me!\r\n\r\n## \ud83d\udcda How to Cite\r\n\r\nIf you use `py-dss-toolkit` in your academic work, please reference it as follows:\r\n\r\n**APA Style:**\r\n\r\nRadatz, P. (2025). *py-dss-toolkit: Advanced Python Tools for OpenDSS powered by EPRI* (Version X.X.X) [Computer software]. GitHub. https://github.com/PauloRadatz/py_dss_tools\r\n\r\n**BibTeX Entry:**\r\n\r\n```bibtex\r\n@software{radatz2025pydsstools,\r\n author = {Paulo Radatz},\r\n title = {py-dss-toolkit: Advanced Python Tools for OpenDSS powered by EPRI},\r\n year = {2025},\r\n version = {X.X.X},\r\n url = {https://github.com/PauloRadatz/py_dss_tools}\r\n}\r\n```\r\n\r\n\ud83d\udccc Please replace `X.X.X` with the version of the package you are using.\r\n\r\n\r\n## \ud83d\ude4f Acknowledgements\r\nDeveloped and maintained by [Paulo Radatz](https://www.linkedin.com/in/pauloradatz/), with support from the global OpenDSS community.\r\n\r\nSpecial thanks to the OpenDSS community and all contributors and users who have provided feedback and inspiration. The development of `py-dss-toolkit` builds on the foundation laid by [`py-dss-interface`](https://github.com/PauloRadatz/py_dss_interface).\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Advanced Python Tools for OpenDSS Powered by EPRI.",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/PauloRadatz/py_dss_toolkit/blob/master/CHANGELOG.rst",
"Issue Tracker": "https://github.com/PauloRadatz/py_dss_toolkit/issues",
"Source": "https://github.com/PauloRadatz/py_dss_toolkit"
},
"split_keywords": [
"opendss",
" python",
" power systems",
" distribution systems",
" energy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0529ba10c0f3a39435cb51ce2b2d1a963a226e3e5bf028f0d9cdf7d31848f0b",
"md5": "8d784b3c433f5b2ef4e75093f41adedd",
"sha256": "2f07245fbefba34934d1850c909bb62a38d5b9c440ab2b10229b7dba77605d05"
},
"downloads": -1,
"filename": "py_dss_toolkit-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d784b3c433f5b2ef4e75093f41adedd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 101296,
"upload_time": "2025-08-20T10:29:23",
"upload_time_iso_8601": "2025-08-20T10:29:23.829403Z",
"url": "https://files.pythonhosted.org/packages/a0/52/9ba10c0f3a39435cb51ce2b2d1a963a226e3e5bf028f0d9cdf7d31848f0b/py_dss_toolkit-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b5b3c05d06ab19d6f5bfe0e52a79bfdeaa4346c3ad50848b10f90b1ec814ce6",
"md5": "6d625c274f49742b012e9c69037cb2c6",
"sha256": "8387c95d57b1001217985d50a8b896e160de9733385f797ba56ac588acdcf1e4"
},
"downloads": -1,
"filename": "py_dss_toolkit-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6d625c274f49742b012e9c69037cb2c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 59894711,
"upload_time": "2025-08-20T10:29:36",
"upload_time_iso_8601": "2025-08-20T10:29:36.076451Z",
"url": "https://files.pythonhosted.org/packages/8b/5b/3c05d06ab19d6f5bfe0e52a79bfdeaa4346c3ad50848b10f90b1ec814ce6/py_dss_toolkit-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 10:29:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PauloRadatz",
"github_project": "py_dss_toolkit",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"appveyor": true,
"tox": true,
"lcname": "py-dss-toolkit"
}
JSON
