Quick Start Guide

This page provides a short guide to get PyDSS up and running. If you have not already installed PyDSS, please follow the instructions at Installation.

The basic steps are:

  1. Create an empty project

  2. Copy your OpenDSS model files into the project

  3. Customize the simulation settings

  4. Run the simulation

Create an empty project

PyDSS requires a specific directory structure with configuration files that specify how to run a simulation. Run this command to create an empty project:

$ pydss create-project --project=my-project --scenarios="scenario1,scenario2" --path=./pydss-projects

This creates the directory structure described in PyDSS Project Layout.

OpenDSS Models

  1. Copy your OpenDSS model files into ./pydss-projects/my-project/DSSfiles/.

  2. Set the field dss_file in simulation.toml to the OpenDSS entry point filename (e.g., Master.dss).

Customize the simulation settings

The file ./pydss-projects/my-project/simulation.toml is the main configuration file for the project. Key settings include:

  • Simulation type: QSTS (quasi-static time series), Dynamic, Snapshot, or Monte Carlo

  • Start time and duration: When the simulation starts and how long it runs

  • Step resolution: Time step size (in seconds)

  • Export options: What data to collect and in what format (HDF5 or CSV)

Refer to SimulationSettingsModel for the full list of settings.

Each scenario has its own config files for additional customization:

  • ExportLists/ — What data to export

  • pyControllerList/ — Controller configurations

Run the simulation

$ pydss run ./pydss-projects/my-project

Results

  • Exported data: ./pydss-projects/my-project/Exports/<scenario-name>/

  • Reports: ./pydss-projects/my-project/Reports/

  • HDF5 store: ./pydss-projects/my-project/store.h5

Access results programmatically using the Python API:

from pydss.pydss_results import PyDssResults

results = PyDssResults("./pydss-projects/my-project")
scenario = results.scenarios[0]
df = scenario.get_dataframe("Buses", "puVmagAngle", "bus_name")

Refer to the Tutorial for more detailed examples.