Skip to content

README.md

Latest commit

 

History

History
207 lines (134 loc) · 7.35 KB

README.md

File metadata and controls

207 lines (134 loc) · 7.35 KB

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

PyPI Platform License AppVeyor PyPI Downloads

py-dss-interface is a Python package to control OpenDSS Powered by EPRI — the official EPRI-maintained distribution of OpenDSS — using the Python programming language. It is designed to work with OpenDSS Powered by EPRI only. This tool is actively used across multiple EPRI research projects and by utilities and consultants, and it also serves as a foundation for automated testing workflows for OpenDSS.

🚀 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: No need to install OpenDSS since py-dss-interface comes bundled with a tested version of OpenDSS (Windows and Linux). 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 Linux (pre-built wheels available; build from source if needed).
  • ⚡ Better Performance: Some examples comparing performance will be provided later.
  • 🔐 Version Control Friendly: Avoid breaking your Python code when updating the OpenDSS version on your computer.

💻 Platform Support

✅ Windows

pip install py-dss-interface

🐧 Linux

Pre-built wheels are available for x86_64 and ARM64. Start with pip install:

pip install py-dss-interface

If pip install doesn't work for your environment, you can build from source as described below.

🔧 Build from source (fallback)

To use py-dss-interface on Linux, you'll need to build the OpenDSS C++ engine locally using OpenDSSLinuxCPPForRepo.sh.

  1. Clone the repository

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

  2. Build the OpenDSS C++ engine

    bash py_dss_interface/OpenDSSLinuxCPPForRepo.sh

    📌 Note: You'll need tools for building C++ code (e.g., g++, cmake, etc.).

  3. Install the package

    pip install path/to/py_dss_interface

📦 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)

🧪 Running Tests

The project includes a comprehensive test suite using pytest. Tests can be run individually or together depending on your platform and backend.

Basic Test Execution

# Run all tests
pytest tests/

Test Execution Modes

Automatic Individual Execution (Default)

On Linux or when using the C++ backend on Windows, tests automatically run individually in separate subprocesses to prevent memory leak issues. This is handled automatically by the test framework.

Running All Tests Together

To run all tests together (faster execution, but may have memory issues if there are leaks), use the --run-together flag:

# Run all tests together (even on Linux/C++)
pytest tests/ --run-together

Note: Use --run-together when you want to test memory management fixes or need faster test execution. Individual execution is recommended for normal testing to prevent memory leaks.

Test Summary

When tests run individually, a detailed summary is displayed at the end showing:

  • Total tests executed
  • Passed/Failed/Error counts
  • List of failed tests (if any)
  • Execution time

📖 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

📂 Where to Find Examples

  • 📁 OpenDSS Repository
  • 📁 Local Installation: After installing OpenDSS on 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. (2026). py-dss-interface: A Python package that interfaces with OpenDSS powered by EPRI (Version 2.3.0) [Computer software]. GitHub. https://github.com/PauloRadatz/py_dss_interface

BibTeX Entry:

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

🙏 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.