Sienna

Sienna stores system level data in a JSON file and timeseries data in h5 files that can be in various locations.

Timeseries data is often stored with the headers in a separate location than the data. Timestamps are built by viewing attributes of either UC or emulation_model.

H5 dataset example:

dataset -> “ActivePowerTimeSeriesParameter__StandardLoad”

headers -> “ActivePowerTimeSeriesParameter__StandardLoad__columns”

SiennaSimulationParser: Parses singular h5 files. Lists available datasets and returns formatted timeseries dataframes based on desired dataset key or h5 path.

For multi-file aggregation, use the generic SimulationAggregator parameterized with parser_class=SiennaSimulationParser (parallel loading enabled by default). The previous SiennaSimulationAggregator was removed in Phase 10.

SiennaSystemParser: Parses the Sienna System JSON file. Lists available datasets by component and returns formatted dataframes based on component type desired.

class gat.datahelpers.sienna.SiennaH5Parser(simulation_store_path)

Sienna H5 Parser

Low-level reader for a Sienna simulation h5 file. Renamed from SiennaSimulationParser in Phase 10 to disambiguate from the v1 gat.simulations.sienna.SiennaSimulationParser (which subclasses BaseSimulationParser). The legacy name still resolves via a module-level __getattr__ deprecation alias at the bottom of this file.

Reads data from a given Sienna Simulation h5 file.

Creates timestamps based on attribute data and automatically attaches columns.

Used as a core class for aggregating across multiple h5 files via gat.simulations.SimulationAggregator(parser_class=…).

Internal Properties:

self.file_path:

The path to the h5 file used to initialize the object.

self.sim_attr:

Attributes under the /simulation path. Used for creating the timestamps.

self.uc_attr:

Attributes for the /simulation/decision_model/UC path.

self.em_attr:

Attributes for the /simulation/emulation_model path. Also used in creating the timestamps.

get_attributes(key)

reads the attribute metadata of a given certain key.

Parameters:

key – The dataset name to read.

Return type:

dict | None

get_dataset(key)

creates the dataframe based on dataset alias or h5 path.

Parameters:

key – Creates a dataframe based on a key found in self.list_datasets() or a full h5 path. (e.g. ActivePowerTimeSeriesParameter__RenewableDispatch)

Return type:

DataFrame | None

get_decision_model_base_power(model_name='UC')

Read base_power from a decision model’s h5 group attrs.

This is the authoritative source of the simulation-side scale factor; sys.json’s units_settings.base_value can disagree if a simulation was run with a different per-unit base than the system was serialized with.

Parameters:

model_name (str)

Return type:

float | None

get_raw_dataset(key)

Return an h5 dataset as an unscaled DataFrame.

Accepts either a short alias (matched against list_datasets()) or a full h5 path (e.g. /simulation/decision_models/UC/variables/ActivePowerVariable__ThermalStandard). No base_power scaling is applied — values are exactly what’s on disk. Use the high-level get_* methods on SiennaScenario if you want scaled (MW) values.

Parameters:

key (str)

Return type:

DataFrame | None

list_datasets()

Returns:

A dictionary of the dataset names and corresponding h5 paths. Ignores the additional “__columns” datasets

Return type:

dict

property timestamps: DatetimeIndex

The timestamps for the emulation model of the simulation file

class gat.datahelpers.sienna.SiennaModelConfig(*, base_power, horizon_count, interval_ms, num_executions, resolution_ms, system_uuid, name=None)

Parameters:

• base_power (int)

• horizon_count (int)

• interval_ms (int)

• num_executions (int)

• resolution_ms (int)

• system_uuid (str)

• name (str | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class gat.datahelpers.sienna.SiennaSimulationConfig

This class holds the attributes for a given set of Simulation attributes This class is responsible for generating the timestamps of decision and emulation models

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class gat.datahelpers.sienna.SiennaSystemParser(system_file_path)

Sienna System Parser

Reads data from a given Sienna JSON file

param system_file_path:

Path to the Sienna System JSON file

Internal Properties:

self.system_data:

The python object representation of the given JSON file.

get_bus_area_relation(key_value=None, area_column='area')

Get the area relationship for buses.

Parameters:

• key_value (str | None) – Column name in ACBus to use as lookup key

• area_column (str | None) – Column name containing area information

Returns:

Dictionary mapping bus identifiers to area names

Return type:

dict | None

get_component(component_type, expand_ext=True)

Get component data for a given component type.

Parameters:

• component_type (str) – Component type name (must be in list_components())

• expand_ext (bool) – If True, expand ‘ext’ field into separate columns

Returns:

DataFrame with component data indexed by UUID, or None if not found

Return type:

DataFrame | None

get_component_bus_relation(component_type, index_column='name', value_col='bus')

Get the bus relationship for components of a given type.

Parameters:

• component_type – Component type name

• index_column – Column to use as the key in the returned dict

• value_col – Column to use as the value in the returned dict

Returns:

Dictionary mapping component names to bus UUIDs

Return type:

dict | None

get_component_data(component_type, expand_ext=True)

Deprecated: Use get_component() instead.

Return type:

DataFrame | None

list_component_types()

Deprecated: Use list_components() instead.

Return type:

set | None

list_components()

List all unique component types in the system.

Returns:

Set of component type names (e.g., ‘ThermalStandard’, ‘ACBus’, ‘Line’)

Return type:

set | None