OpenDSS Analysis Tool

A modular Python tool for running SMART-DS dataset using OpenDSS.

File Structure

├── main.py                 # Main execution script
├── config.py              # Configuration settings
├── dss_checks.py          # OpenDSS system checking functions
├── data_processing.py     # Data processing utilities
├── file_readers.py        # File reading functions
├── plotting_utils.py      # Plotting and visualization
├── output_utils.py        # Output and file saving utilities
├── timeseries_analysis.py # Timeseries analysis for voltage estimation
├── requirements.txt       # Python dependencies
└── README.md             # This file

Installation

1. Install required packages:

pip install -r requirements.txt

2. Ensure OpenDSS is installed and accessible via opendssdirect.py

Data format

This is based on the Smart-DS dataset developed by NREL, the formatting is expected as follows:

year/region/substation/scenarios/feeders/

Usage

python main.py <dataset> <region> <year> <scenario> <run_all> <delete_folders>

Parameters:

• dataset: Dataset name/path
• region: Region to analyze
• year: Year or 'peak' for peak analysis
• scenario: Scenario name (e.g., 'base_timeseries', 'base_peak')
• run_all: 'timeseries' to run full timeseries analysis, or other value for peak only
• delete_folders: 'Delete' to clean up intermediate folders, or other value to keep

Examples:

Peak analysis:

python main.py Region Substation year base_peak normal keep

Timeseries analysis:

python main.py Region Substation year base_timeseries timeseries keep
python main.py SFO P4U 2018 base_timeseries timeseries Delete

Configuration

Edit config.py to adjust:

• Voltage violation thresholds (upper/lower bounds)
• Loading thresholds for transformers and lines
• Plotting settings
• Output file names
• Progress reporting intervals

Key Features

System Checks

• Voltage Violations: Detects over/under voltage conditions
• Equipment Overloads: Identifies overloaded transformers and lines
• Blown Fuses: Checks for blown protective devices

Timeseries Analysis

• Collects voltage data across all buses for every timestep
• Saves load and PV generation data as features
• Creates datasets suitable for voltage estimation models
• Exports data in CSV format with metadata

Visualization

• Voltage histograms and percentile plots
• Daily load curve plotting
• System summary statistics

Output Files

The tool generates various output files including:

• peak_under_voltages.csv - Undervoltage violations
• peak_over_voltages.csv - Overvoltage violations
• peak_transformer_overloads.csv - Transformer overloads
• peak_line_overloads.csv - Line overloads
• blown_fuses.csv - Blown fuses
• Summary_data.csv - System summary statistics
• voltage_estimation_data/ - Complete timeseries dataset for ML

Voltage Estimation Dataset

When running with timeseries mode, the tool creates a comprehensive dataset for voltage estimation including:

• voltage_pu_all_buses.csv - Target voltage values (per-unit) for all buses
• load_kw_all_buses.csv - Active power loads as features
• load_kvar_all_buses.csv - Reactive power loads as features
• pv_irradiance_all_systems.csv - PV system data (if applicable)
• system_summary.csv - System-level metrics
• dataset_metadata.json - Dataset description and structure

This dataset can be used to train machine learning models for voltage estimation and prediction.

Notes

• The tool processes data sequentially (multiprocessing has been disabled)
• Progress is reported every 1000 timesteps during timeseries analysis
• All intermediate calculations and violations are logged to console
• The tool is designed to handle missing or corrupted data in a graceful way (ask for forgiveness not permission)

Dependencies

See requirements.txt for the complete list of Python packages required.