Metadata-Version: 2.4
Name: NREL-pydss
Version: 3.1.10
Summary: A high-level python interface for OpenDSS
Project-URL: Homepage, https://github.com/NatLabRockies/PyDSS
Project-URL: Documentation, https://natlabrockies.github.io/PyDSS/
Author-email: Aadil Latif <Aadil.Latif@nrel.gov>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: click~=8.1.8
Requires-Dist: h5py~=3.13.0
Requires-Dist: helics~=3.6.1
Requires-Dist: loguru~=0.7.3
Requires-Dist: networkx~=3.4.2
Requires-Dist: numpy~=2.2.4
Requires-Dist: opendssdirect-py==0.8.4
Requires-Dist: pandas~=2.2.3
Requires-Dist: pvder~=0.6.0
Requires-Dist: pydantic<3,>=2
Requires-Dist: pymongo~=4.11.3
Requires-Dist: requests~=2.32.3
Requires-Dist: scikit-learn~=1.6.1
Requires-Dist: scipy~=1.15.2
Requires-Dist: shapely~=2.0.7
Requires-Dist: tables~=3.10.1
Requires-Dist: terminaltables~=3.1.10
Requires-Dist: toml~=0.10.2
Provides-Extra: dev
Requires-Dist: autodoc-pydantic~=2.0.1; extra == 'dev'
Requires-Dist: enum-tools[sphinx]~=0.12.0; extra == 'dev'
Requires-Dist: furo~=2024.8.6; extra == 'dev'
Requires-Dist: mock~=5.2.0; extra == 'dev'
Requires-Dist: pytest-cov~=7.1.0; extra == 'dev'
Requires-Dist: pytest~=9.1.0; extra == 'dev'
Requires-Dist: setuptools~=75.8.0; extra == 'dev'
Requires-Dist: sphinx-click~=6.0.0; extra == 'dev'
Requires-Dist: sphinx-enum-extend~=0.1.3; extra == 'dev'
Requires-Dist: sphinx-rtd-theme~=3.1.0; extra == 'dev'
Requires-Dist: sphinxcontrib-openapi~=0.8.4; extra == 'dev'
Requires-Dist: sphinxcontrib-redoc~=1.6.0; extra == 'dev'
Requires-Dist: sphinx~=7.4.7; extra == 'dev'
Provides-Extra: server
Requires-Dist: aiohttp-swagger3~=0.8.0; extra == 'server'
Requires-Dist: aiohttp~=3.9.0; extra == 'server'
Description-Content-Type: text/markdown

﻿[![Pytest](https://github.com/NatLabRockies/PyDSS/actions/workflows/pull_request_tests.yml/badge.svg)](https://github.com/NatLabRockies/PyDSS/actions/workflows/pull_request_tests.yml) • [![Upload to PyPi](https://github.com/NatLabRockies/PyDSS/actions/workflows/python-publish.yml/badge.svg)](https://github.com/NatLabRockies/PyDSS/actions/workflows/python-publish.yml) • [![deploy-docs](https://github.com/NatLabRockies/PyDSS/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/NatLabRockies/PyDSS/actions/workflows/gh-pages.yml) • ![PyPI - Downloads](https://img.shields.io/pypi/dm/NREL-pydss) • [![GitHub issues](https://img.shields.io/github/issues/NatLabRockies/PyDSS)](https://github.com/NatLabRockies/PyDSS/issues) • [![License](https://img.shields.io/github/license/NatLabRockies/PyDSS)](https://github.com/NatLabRockies/PyDSS/blob/master/LICENSE) • [![PyPI Downloads](https://static.pepy.tech/personalized-badge/nrel-pydss?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/nrel-pydss)

# PyDSS

**PyDSS** is a high-level Python interface for [OpenDSS](https://www.epri.com/pages/sa/opendss) that extends its organizational, analytical, and co-simulation capabilities. It is built on top of [OpenDSSDirect.py](https://pypi.org/project/OpenDSSDirect.py/).

**Documentation:** [https://natlabrockies.github.io/PyDSS/](https://natlabrockies.github.io/PyDSS/index.html)

## 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](https://github.com/GMLC-TDC/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):

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

## Quick Start

```bash
# 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

```python
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](LICENSE) for details.

