Reports#

This page describes how to generate PyDSS reports from exported simulation data.

The following reports can be enabled in the project’s simulation.toml Reports section.

  • Capacitor State Change Counts (EXPERIMENTAL): Reports the state changes per Capacitor.

  • Feeder Losses: Reports the feeder losses.

  • PV Clipping (EXPERIMENTAL): Reports PV Clipping for the simulation.

  • PV Curtailment (EXPERIMENTAL): Reports PV Curtailment at every time point in the simulation.

  • RegControl Tap Number Change Counts (EXPERIMENTAL): Reports the tap number changes per RegControl.

  • Thermal Metrics: Reports thermal metrics.

  • Voltage Metrics: Reports voltage metrics.

The Reports section contains global settings that may apply to any report. Each report may contain its own specific settings.

Global settings#

Format#

Used to control export format for dataframes: .csv or .h5. In either case you can use PyDSS to convert the file back to a dataframe.

from PyDSS.utils.dataframe_utils import read_dataframe

df = read_dataframe("path/to/filename")

Granularity#

Controls how often and how much data is collected. This applies to elements of given type, such as PVSystems. Suppose there are 10 PVSystems in the circuit and 35,040 time points in the simulation. Each value stored is a float that consumes 8 bytes.

  • per_element_per_time_point: Collect data for every element at every time point.

    Storage required: 100 elements * 35040 floats * 8 bytes = 27 MiB

  • per_element_total: Keep a running sum for each element. Report the total for each element.

    Storage required: 100 elements * 1 float * 8 bytes = 800 bytes

  • all_elements_per_time_point: Sum all elements for a given type at every time point.

    Storage required: 1 * 35040 floats * 8 bytes = 273 KiB

  • all_elements_total: Keep a running sum across all elements for a given type.

    Storage required: 1 element * 1 number = 8 bytes

Export Parameters#

Each report configures its own export parameters. PyDSS will serialize the export parameters used in a simulation to <project-path>/Exports/<scenario-name>/ExportsActual.toml.

This can be useful for debugging purposes when you develop your own reports.

Output Data#

PyDSS stores generated reports in <project-path>/Reports.

Adding New Reports#

Here’s how to create a new report in PyDSS.

  1. Create a new class in a Python file in PyDSS/reports. The class must inherit from ReportBase.

  2. Implement the required methods:

    • generate: Generates the report files. This should create the files in <project-path>/Reports.

    • get_required_exports: Defines the export parameters at runtime. Refer to Pre-filtering Export Data.

Examples#

Refer to the simulation settings in tests/data/pv_reports_project/simulation.toml for an example configuration that enables these reports.