Output Files

Output Files#

Hercules generates HDF5 output files containing simulation data for analysis and visualization. This page describes the file format, available utilities for reading the data, and how the emulator generates these files.

File Format#

Hercules outputs simulation data in HDF5 (Hierarchical Data Format 5) format.

File Structure#

The HDF5 file contains the following structure:

hercules_output.h5
├── data/
│   ├── time                    # Simulation time points (seconds)
│   ├── step                    # Simulation step numbers
│   ├── plant_power             # Total plant power output
│   ├── plant_locally_generated_power  # Locally generated power
│   ├── components/
│   │   ├── wind_farm.power                   # Wind farm power output
│   │   ├── wind_farm.wind_speed_mean_background # Farm-average background wind speed
│   │   ├── wind_farm.wind_speed_mean_withwakes   # Farm-average with-wakes wind speed
│   │   ├── wind_farm.wind_direction_mean     # Farm-average wind direction
│   │   ├── wind_farm.turbine_powers.000      # Turbine 0 power (if logged)
│   │   ├── wind_farm.turbine_powers.001      # Turbine 1 power (if logged)
│   │   ├── solar_farm.power                  # Solar farm power output
│   │   ├── solar_farm.dni                    # Direct normal irradiance (if logged)
│   │   ├── solar_farm.poa                    # Plane-of-array irradiance (if logged)
│   │   ├── battery.power                     # Battery power (if present)
│   │   ├── battery.soc                       # Battery state of charge (if logged)
│   │   └── ...                               # Other component outputs
│   └── external_signals/
│       └── ...                 # Other external signals
└── metadata/
    ├── h_dict                  # Simulation configuration (JSON string)
    ├── dt_sim                  # Simulation time step (seconds)
    ├── dt_log                  # Logging time step (seconds)
    ├── log_every_n             # Logging stride value
    ├── starttime               # Simulation start time (always 0.0 seconds)
    ├── endtime                 # Simulation end time (duration in seconds)
    ├── start_clock_time        # Simulation start wall clock time
    ├── end_clock_time          # Simulation end wall clock time
    ├── total_time_wall         # Total wall clock time for simulation
    ├── starttime_utc           # Simulation start UTC time (Unix timestamp)
    └── ...                     # Other metadata attributes

Reading Output Files#

Hercules provides several utilities in the utilities module for reading and analyzing output files:

Basic Reading#

from hercules.utilities import read_hercules_hdf5

# Read entire file
df = read_hercules_hdf5("outputs/hercules_output.h5")
print(df.head())

Subset Reading#

For large datasets, you can read only specific columns or time ranges:

from hercules.utilities import read_hercules_hdf5_subset

# Read specific columns
df_subset = read_hercules_hdf5_subset(
    "outputs/hercules_output.h5",
    columns=["wind_farm.power", "wind_farm.wind_speed_mean_background", "solar_farm.power"]
)

# Read specific time range (seconds)
df_time_range = read_hercules_hdf5_subset(
    "outputs/hercules_output.h5",
    time_range=(3600, 7200)  # 1-2 hours into simulation
)

# Combine both filters
df_filtered = read_hercules_hdf5_subset(
    "outputs/hercules_output.h5",
    columns=["plant.power"],
    time_range=(0, 3600)
)

Metadata Access#

from hercules.utilities import get_hercules_metadata

# Get simulation metadata
metadata = get_hercules_metadata("outputs/hercules_output.h5")
print(f"Simulation configuration: {metadata['h_dict']}")
print(f"Start time: {metadata.get('starttime_utc')}")

Convenience Class#

For easier access to both data and metadata, you can use the HerculesOutput convenience class:

from hercules import HerculesOutput

# Initialize with filename
ho = HerculesOutput("outputs/hercules_output.h5")

# Access metadata with dot notation
print(f"Simulation time step: {ho.dt_sim}")
print(f"Logging time step: {ho.dt_log}")
print(f"Simulation configuration: {ho.h_dict}")

# Access full data
data = ho.df
print(data.head())

# Get subset of data
subset = ho.get_subset(
    columns=["wind_farm.power", "solar_farm.power"],
    time_range=(3600, 7200)
)

The HerculesOutput class provides a convenient interface while still allowing direct access to the underlying utility functions if needed.

Time UTC Reconstruction#

The read_hercules_hdf5() function automatically reconstructs UTC timestamps for each simulation step using the stored starttime_utc metadata:

from hercules.utilities import read_hercules_hdf5

# Read data with reconstructed time_utc
df = read_hercules_hdf5("outputs/hercules_output.h5")
if "time_utc" in df.columns:
    print(f"UTC timestamps available: {df['time_utc'].head()}")

The reconstruction formula is:

time_utc = starttime_utc + timedelta(seconds=time)

Backward Compatibility#

Hercules maintains backward compatibility with output files created before the timing model changes (prior to version 2.0). Old output files may contain:

  • zero_time_utc instead of starttime_utc

  • Different metadata field names

The HerculesOutput class and reading utilities automatically handle both old and new formats, so you can read any Hercules output file regardless of when it was created.
Contents