PyDSS¶

About PyDSS¶

PyDSS is a Python wrapper for OpenDSS that extends its organizational, analytical, and co-simulation capabilities. It is built on top of OpenDSSDirect.py.

Key Features¶

Custom Control Algorithms — Define Python-based controllers for any circuit element, executed at each simulation time step. 13 built-in controllers are included.
HELICS Co-simulation — Integrate with external simulators via the HELICS framework for cyber-physical co-simulation studies.
Scenario Management — Run multiple scenarios on a shared OpenDSS model with independent controllers, exports, and post-processing.
Flexible Data Export — Export results to HDF5 or CSV with per-element filtering, regex-based selection, moving averages, and group aggregation.
Automated Reports — Generate reports for voltage metrics, thermal metrics, PV clipping/curtailment, capacitor switching, tap changes, and feeder losses.
Monte Carlo Studies — Built-in support for Monte Carlo simulations with profile management.
Extension Architecture — Plugin system for custom controllers, post-processing scripts, and report types.

Installation¶

Recommendation: Install PyDSS in a conda virtual environment.

$ conda create -n pydss python=3.11
$ conda activate pydss

Install the latest release from PyPI:

$ pip install NREL-pydss

Or install from source for development:

$ git clone https://github.com/NatLabRockies/PyDSS
$ cd PyDSS
$ pip install -e ".[dev]"

Verify the installation:

$ pydss --help

Note

PyDSS requires Python 3.9 or later. Python 3.11 is recommended.

Running PyDSS¶

Refer to the Quick Start Guide for basic instructions on how to configure PyDSS to run a simulation with an existing OpenDSS model.

Refer to Tutorial for in-depth instructions on customizing a PyDSS project, including data export options, controllers, and programmatic result access.

Additional Documentation¶

License¶

See the LICENSE file for details.

Contact¶

Questions? Please send an email to aadil.latif@nrel.gov or aadil.latif@gmail.com