Sienna

Sienna#

Provides a scenario handler for the Sienna simulation platform.

This module defines the SiennaScenario class, which provides methods for accessing and processing data from Sienna system json files and simulation h5 files.

class gat.scenariohandlers.sienna.SiennaScenario(simulation_files=None, system_file=None, config=None, pattern='*.h5', solution_data=None, metadata_file=None)#

Class for providing holistic access to Sienna system and simulation data found in JSON and h5 files respectively

Parameters:

  • simulation_files (str | List[str] | None) – List([str, path]) - A path or list of paths to the simulation h5 files produced by a Sienna simulation.

  • system_files – [str, path] - A path or str to the Sienna system JSON file.

  • system_file (str | None)

  • config (ScenarioConfig | None)

  • pattern (str)

  • solution_data (str | List[str] | None)

  • metadata_file (str | None)

Internals Properties#

self.parser:

A SimulationAggregator(parser_class=SiennaSimulationParser) (multi-file) or a single SiennaSimulationParser for one h5 file.

self.system:

A SiennaSystemParser(system_file) for parsing the Sienna system JSON file.

self.config:

A mutable configuration object that tells the handler where to look for certain types of data.

self.unit_base_value:

The Sienna System base unit. Acts as a scaling multiplier for all the timeseries and capacity data. (See Sienna Documentation for more details)

self.unit_system:

Natural or Per-Unit

property area: str | None#

"area").

Type:

Display label for the aggregation column (default

copy(selected_model=None, display_name=None)#

Create a copy of this scenario with independent configuration and parser.

Parameters:#

selected_modelstr, optional

Model to select in the new scenario’s parser. If None, uses current selected_model.

display_namestr, optional

Display name for the new scenario. If None, uses current display_name.

Returns:#

SiennaScenario

New scenario instance with independent configuration and parser

Parameters:

  • selected_model (str | None)

  • display_name (str | None)

Return type:

SiennaScenario

classmethod from_simulation_models(simulation_files, system_file=None, config=None, pattern='*.h5', solution_data=None)#

Create multiple SiennaScenario objects, one for each simulation model in the h5 files.

Parameters:#

simulation_filesstr or list of str

Path to simulation output data or list of paths to h5 files

system_filestr, optional

Path to system data file (Sienna JSON file)

configScenarioConfig, optional

Base configuration object for all scenarios

patternstr, optional

Glob pattern to use when searching for files (default: “*.h5”)

Returns:#

Dict[str, SiennaScenario]

Dictionary mapping simulation model names to scenario objects

Parameters:

  • simulation_files (str | List[str])

  • system_file (str | None)

  • config (ScenarioConfig | None)

  • pattern (str)

  • solution_data (str | List[str] | None)

Return type:

Dict[str, SiennaScenario]

property generator_technology_map: Dict[str, str]#

Creates the generator->technology mapping by parsing the system data using SiennaSystemParser.

For thermal standards technology = prime_mover_type + ext[‘fuel’]

All other components in the self.config.generation_components list use prime_mover_type only.

Returns:

Dictionary of generator by id as keys and technology type as values.

get_area_interchange()#

Parses the Area Interchange data found across multiple files using the SiennaSystemAggregator.get_dataset(“FlowActivePowerVariable__AreaInterchange”).

dataset lookup value can be overridden with SiennaScenario.config.interchange_path

Returns:

Timeseries dataframe of flow across interchanges of the default Areas in the underlying Sienna system.

get_area_unserved()#

Not Implemented.

get_availability()#

Sienna Dataset: ActivePowerTimeSeriesParameter__RenewableDispatch

Returns:

Timeseries dataframe of RenewableDispatch Availability.

Return type:

DataFrame

get_gen_area_map(area_column=None)#

Creates the generator->area relationship using the SiennaSystemParser.get_bus_area_relation() and component->node relationships.

Returns:

Dictionary of Generator Name -> Geographic Area.

Return type:

dict | None

get_generation()#

Parses and Aggregates the generation data across multiple simulation files.

Uses the internal SiennaSimulation Aggregator and reads all datasets that start with “ActivePowerVariable*”.

Combines all the datasets and returns a dataframe scaled by unit_base_value

Returns:

Timeseries Dataframe of generation by generator id/name.

Return type:

DataFrame

get_generation_capacity()#

Combines the base_power*rating of values of Sienna components found in self.config.generation_components

Returns:

A dataframe of aggregated generation capacity by Simplified Technogogy across each area.

get_line_flow()#

Parses and Aggregates the Line Flow data across multiple files by using the SiennaSystemAggregator.get_dataset(“FlowActivePowerVariable__Line”)

Values are scaled by unit_base_value

Returns:

Timeseries dataframe of line flow scaled by unit base value.

Return type:

DataFrame

get_line_rating_map()#

Parses the line capacity by reading the SiennaSystemParser.get_component_data(“Line”) and scaling the rating by unit_base_value

Returns:

Dictionary of Line Id -> Line Capacity

Return type:

dict | None

get_load()#

Sienna Dataset: ActivePowerTimeSeriesParameter__StandardLoad

Returns:

Timeseries Dataframe of the Standard Load dataset.

Return type:

DataFrame | None

get_load_area_map(area_column=None)#

Creates the load bus->area relationship using the internal SiennaSystemParser

  1. Creates the load->node relationship using SiennaSystemParser.get_component_bus_relation for the PowerLoad component.

  2. Creats the node->area relationship using the SiennaSystemParser.get_bus_area_relation()

Returns:

Dictionary of Load bus name -> geographic area.

Return type:

dict | None

get_production_cost()#

Combines the cost expressions and and ActivePower Variables found in the self.config.cost_paths dand self.config.generation_paths to get the Production cost.

Returns:

Timeseries DataFrame of production cost by generator.

get_raw_dataset(key)#

Return an h5 dataset as an unscaled DataFrame.

key may be a short alias (matched against the parser’s list_datasets()) or a full h5 path. Returns the values exactly as stored on disk — no base_power scaling applied. Use the high-level get_* methods (get_generation, get_load, etc.) if you want scaled MW values.

Parameters:

key (str)

Return type:

DataFrame | None

get_storage_charging()#

Sienna Dataset: ActivePowerInVariable%

Creates the storage charging dataframe by finding any dataset with ActivePowerInVariable* pattern. Includes a combination of Battery Charging or Pump Load.

Values are scaled by unit_base_value

Returns:

Timeseries Dataframe of charging load.

Return type:

DataFrame

get_system_dispatch(include_load=True, include_use=False, include_charging=True, **kwargs)#

Gets the dispatch data for the entire system, optionally including load, use, and charging information.

Parameters:

  • include_load – Boolean indicating whether to include load in the dispatch data.

  • include_use – Boolean indicating whether to include use (e.g., unserved energy) in the dispatch data.

  • include_charging – Boolean indicating whether to include charging data in the dispatch data.

  • kwargs – Additional keyword arguments to be passed to the parent class’s get_system_dispatch method.

Returns:

DataFrame containing the dispatch data for the entire system.

get_system_unserved()#

Gets the system-wide unserved energy balance for a copper plate Sienna model.

Sums the total energy balance across the system for each timestep. Only returns the negative balances as absolute values, otherwise 0.

Return type:

Series

get_unserved()#

Not Implemented

to_multiscenario()#

Create a MultiScenario from all simulation models in this scenario’s h5 files.

Returns:#

MultiScenario

MultiScenario object with scenarios for each simulation model

Return type:

MultiScenario