py-dss-interface

🐍 py-dss-interface: Python Control for OpenDSS Powered by EPRI

PyPI License AppVeyor

py-dss-interface is a Python package endorsed by EPRI to control OpenDSS Powered by EPRI using the Python programming language. This tool is actively used across multiple EPRI research projects and by many utilities and consultants. It also serves as the foundation for the automated testing process of OpenDSS itself.

🚀 What Can You Do With `py-dss-interface`?

Use the full power of Python to control and automate your OpenDSS workflows:

⚙️ Automate repetitive OpenDSS tasks.
🧠 Manipulate circuit, element, and bus properties with Python logic.
📊 Extract simulation results and generate custom reports.
🧮 Implement advanced analysis and algorithms using Python.

🔄 Why Use `py-dss-interface` Instead of the COM Interface?

Compared to the COM interface, py-dss-interface provides a modern, Pythonic experience:

💡 Code Completion: Works seamlessly with IDEs like PyCharm for better developer productivity.
📦 No OpenDSS Installation Required (Windows): No need to install OpenDSS since py-dss-interface comes bundled with a tested version of OpenDSS. However, you may also use a different OpenDSS version if desired. Please note that compatibility is only guaranteed for the bundled version.
🔄 Supports Multiple DSS Objects: Interact with multiple OpenDSS objects at the same time.
🌐 Multi-Platform: Supports both Windows and now Linux (via local OpenDSS C++ build).
⚡ Better Performance: Some examples comparing performance will be provided later.
🔐 Version Control Friendly (Windows): Avoid breaking your Python code when updating the OpenDSS version on your computer.

💻 Platform Support

✅ Windows

pip install py-dss-interface

🐧 Linux (OpenDSS C++ Build Required)

To use py-dss-interface on Linux, you’ll need to build the OpenDSS C++ engine locally:

Clone this repository:

git clone https://github.com/PauloRadatz/py_dss_interface.git
cd py_dss_interface

Run the setup script:

cd py_dss_interface
bash OpenDSSLinuxCPPForRepo.sh

Install the package:
```
pip install -e .
```
Or if you don’t need editable mode:
```
pip install .
```

📌 Note: You will need tools for building C++ code on your system (e.g., g++, cmake, etc.) to compile the OpenDSS engine locally.

📦 Quickstart Example

import py_dss_interface

dss = py_dss_interface.DSS()
dss.text("compile path/to/circuit.dss")
dss.text("solve")
print(dss.circuit.total_power)

📖 Documentation

📖 Full documentation available at: 👉 https://py-dss-interface.readthedocs.io/en/latest/

🎓 Learn More

📘 Comprehensive Online Course

The best way to master py-dss-interface is through the official course:

👉 Try the first modules for free

📺 YouTube Playlists

🧩 Tools Built on py-dss-interface

📈 OpenDER_Interface: EPRI’s tool for Distributed Energy Resource simulation and control, powered by py-dss-interface. More on OpenDER: GitHub
📊 2023 Hosting Capacity Webinar: Examples shown using this package.
🔧 py-dss-tools: A new package built on top of py-dss-interface, coming soon to PyPI.

📂 Where to Find Examples

📁 OpenDSS Repository
📁 Local Installation: After installing OpenDSS in your Windows computer, navigate to: C:\\Program Files\\OpenDSS\\Examples\\Python\\py-dss-interface

🤝 Community and Support

💬 Open an Issue on GitHub for bugs or feature requests.
🙌 Contributions welcome! Please open a pull request with clear descriptions.
💻 Questions? Join discussions in the OpenDSS user forums or comment on relevant YouTube videos.

📚 How to Cite

If you use py-dss-interface in your academic work, please reference it as follows:

APA Style:

Radatz, P. (2025). py-dss-interface: A Python package that interfaces with OpenDSS powered by EPRI (Version X.X.X) [Computer software]. GitHub. https://github.com/PauloRadatz/py_dss_interface

BibTeX Entry:

@software{radatz2024bdgd2opendss,
  author = {Paulo Radatz},
  title = {py-dss-interface: A Python package that interfaces with OpenDSS powered by EPRI},
  year = {2025},
  version = {X.X.X},
  url = {https://github.com/PauloRadatz/py_dss_interface}
}

📌 Please replace X.X.X with the version of the package you are using.

🙏 Acknowledgements

Developed and maintained by Paulo Radatz, with support from EPRI and the global OpenDSS community.

Special thanks to Ênio Viana and Rodolfo Pilar Londero for their contributions to the first version of this tool.