• • • • • •

PyDSS

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

Documentation: https://natlabrockies.github.io/PyDSS/

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 (PV, storage, motor stall, fault, transformer, thermostat, and more).
• 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 running Monte Carlo simulations with profile management.
• Extension Architecture — Plugin system for custom controllers, post-processing scripts, and report types.

Installation

Install in a conda virtual environment (recommended):

conda create -n pydss python=3.11
conda activate pydss
pip install NREL-pydss

Quick Start

# Create a project with two scenarios
pydss create-project --project=my-project --scenarios="scenario1,scenario2" --path=./projects

# Copy your OpenDSS files into projects/my-project/DSSfiles/
# Set dss_file in projects/my-project/simulation.toml

# Run all scenarios
pydss run ./projects/my-project

Python API

from pydss.pydss_project import PyDssProject

# Run a project
PyDssProject.run_project("./projects/my-project")

# Access results
from pydss.pydss_results import PyDssResults
results = PyDssResults("./projects/my-project")
scenario = results.scenarios[0]
df = scenario.get_dataframe("Lines", "Currents", "Line.pvl_112")

CLI Commands

Command	Description
pydss create-project	Create a new project with scenarios
pydss run	Run all scenarios in a project
pydss export	Convert HDF5 results to CSV
pydss controllers	Manage the controller registry
pydss edit-scenario	Modify scenario configuration
pydss reports	Generate analysis reports

Run pydss --help for full usage details.

License

BSD 3-Clause. See LICENSE for details.