assetra.unit

class assetra.units.EnergyUnit(id: int, nameplate_capacity: float)

Abstract base class for all energy units.

Energy units are the fundamental building blocks of energy systems in the assetra model. This base class defines an interface which allows the assetra model to save/load pre-existing energy systems from files and run probabilistic simulations with unique energy unit types.

Parameters:

• id (int) – Unique identifying number, used to ensure energy units are not added more than once to an energy system

• nameplate_capacity (float) – Nameplate capacity of the energy unit in units of power (to be kept consistend between units). For some units defining the nameplate capacity may not make physical sense, e.g. demand units, in which case the nameplate capacity should be set to zero.

abstractmethod static to_unit_dataset(units: list[EnergyUnit]) → Dataset

Convert a list of energy units of the derived class type into an xarray dataset.

For different energy units, different dataset dimensions and coordinates may be appropriate.

Parameters:

units (list[EnergyUnit]) – List of of energy units of the derived class type

Returns:

Dataset storing sufficient information to (1) fully

reconstruct the list of energy units from which it is created and (2) generate hourly capacity time series with the EnergyUnit.get_probabilistic_capacity_matrix function

Return type:

xr.Dataset

abstractmethod static from_unit_dataset(unit_dataset: Dataset) → list[EnergyUnit]

Convert a unit dataset to a list of energy units of the derived energy unit type.

This is the inverse to the derived EnergyUnit.to_unit_dataset function

Parameters:

unit_dataset (xr.Dataset) – Unit dataset with structure and content defined in the derived EnergyUnit.to_unit_dataset function

Returns:

List of energy units of the derived class type

Return type:

list[EnergyUnit]

abstractmethod static get_probabilistic_capacity_matrix(unit_dataset: Dataset, net_hourly_capacity_matrix: DataArray) → DataArray

Return probabilistic hourly capacity matrix for a fleet of energy units of the derived energy unit type.

Take the unit dataset and create a matrix representing the total hourly capacity of all energy units for some number of monte carlo trials. The hours and number of trials should match the net hourly capacity matrix.

Parameters:

• unit_dataset (xr.Dataset) – Unit dataset for the derived energy unit type, e.g. generated with the derived EnergyUnit.to_unit_dataset function

• net_hourly_capacity_matrix (xr.DataArray) – Probabilistic net hourly capacity matrix with dimensions (trials, time) and shape (# of trials, # of hours)

Returns:

Combined hourly capacity for all units in the unit

dataset for a determined number of Monte Carlo trials. The dimensions and coordinates of this matrix should match the net hourly capacity matrix

Return type:

xr.DataArray

class assetra.units.StaticUnit(id: int, nameplate_capacity: float, hourly_capacity: DataArray)

Derived energy unit class.

A static energy unit is neither stochastic nor responsive. A single hourly capacity profile is used in all probabilistic capacity trials. For example, a historical demand profile be fully accounted for in all trials of a probabilistic simulation.

Parameters:

• id (int) – Unique identifying number

• nameplate_capacity (float) – Nameplate capacity of the energy unit in units of power

• hourly_capacity (xr.DataArray) – Hourly capacity contained in DataArray with dimension (time) and datetime coordinates.

static to_unit_dataset(units: list[StaticUnit]) → Dataset

Convert a list of static energy units into an xarray dataset

Parameters:

units (list[StaticUnit]) – List of of static energy units

Returns:

Dataset with dimensions (energy_unit, time) and

variables (nameplate_capacity[energy_unit], hourly_capacity[energy_unit, time]). Coordinates for the energy_unit and time dimensions are energy unit IDs and hourly datetime indices, respectively.

Return type:

xr.Dataset

static from_unit_dataset(unit_dataset: Dataset) → list[StaticUnit]

Convert a static unit dataset to a list of static energy units.

This is the inverse StaticUnit.to_unit_dataset function

Parameters:

unit_dataset (xr.Dataset) – Unit dataset with structure and content defined in the derived StaticUnit.to_unit_dataset function

Returns:

List of static energy units

Return type:

list[StaticUnit]

static get_probabilistic_capacity_matrix(unit_dataset: Dataset, net_hourly_capacity_matrix: DataArray) → DataArray

Return probabilistic hourly capacity matrix for a static unit dataset.

For static units, combine hourly capacity profiles for all energy units in the unit dataset and broadcast the result across all trials

Parameters:

• unit_dataset (xr.Dataset) – Static unit dataset, as generated by StaticUnit.to_unit_dataset function

• net_hourly_capacity_matrix (xr.DataArray) – Probabilistic net hourly capacity matrix with dimensions (trials, time) and shape (# of trials, # of hours)

Returns:

Combined hourly capacity for all units in the unit

dataset with the same dimensions and shape as net hourly capacity matrix

Return type:

xr.DataArray

class assetra.units.StochasticUnit(id: int, nameplate_capacity: float, hourly_capacity: DataArray, hourly_forced_outage_rate: DataArray)

Derived energy unit class.

A stochastic energy unit uses time-varying forced outage rates to sample indepenedent outages throughout the simulation period. Stochastic units are non-responsive, meaning that while hourly capacity profiles vary between trials in a probabilistic simulation, the profiles do not depend on system conditions and only need to be sampled once

Parameters:

• id (int) – Unique identifying number

• nameplate_capacity (float) – Nameplate capacity of the energy unit in units of power

• hourly_capacity (xr.DataArray) – Hourly capacity contained in DataArray with dimension (time) and datetime coordinates

• hourly_forced_outage_rate (xr.DataArray) – Hourly forced outage rate as decimal percents (e.g. 5% -> 0.05) contained in DataArray with dimension (time) and datetime coordinates. Should be a parallel matrix to hourly_capacity

static to_unit_dataset(units: list[StochasticUnit])

Convert a list of stochastic energy units into an xarray dataset

Parameters:

units (list[StochasticUnit]) – List of of stochastic energy units

Returns:

Dataset with dimensions (energy_unit, time) and

variables (nameplate_capacity[energy_unit], hourly_capacity[energy_unit, time]), hourly_forced_outage_rate[energy_unit, time]. Coordinates for the energy_unit and time dimensions are energy unit IDs and hourly datetime indices, respectively.

Return type:

xr.Dataset

static from_unit_dataset(unit_dataset: Dataset) → list[StochasticUnit]

Convert a stochastic unit dataset to a list of stochastic energy units.

This is the inverse to StochasticUnit.to_unit_dataset function

Parameters:

unit_dataset (xr.Dataset) – Unit dataset with structure and content defined in the derived StochasticUnit.to_unit_dataset function

Returns:

List of stochastic units

Return type:

list[StochasticUnit]

static get_probabilistic_capacity_matrix(unit_dataset: Dataset, net_hourly_capacity_matrix: DataArray) → DataArray

Return probabilistic hourly capacity matrix for a stochastic unit dataset.

For stochastic units, sample hourly independent outages in for units in all trials. Outages are sampled hourly for every unit and trial. Random numbers are drawn from the range 0 to 1, and where samples are less than the hourly forced outage rate, the effective capacity of that energy unit in that hour and trial is set to 0. The probabilistic capacity matrix is the aggregation of sampled capacities across energy units

Parameters:

• unit_dataset (xr.Dataset) – Static unit dataset, as generated by StaticUnit.to_unit_dataset function

• net_hourly_capacity_matrix (xr.DataArray) – Probabilistic net hourly capacity matrix with dimensions (trials, time) and shape (# of trials, # of hours)

Returns:

Combined hourly capacity for all units in the unit

dataset with the same dimensions and shape as net hourly capacity matrix

Return type:

xr.DataArray

class assetra.units.StorageUnit(id: int, nameplate_capacity: float, charge_rate: float, discharge_rate: float, charge_capacity: float, roundtrip_efficiency: float)

Derived energy unit class.

A storage unit is a state-dependent, responsive energy unit. The available capacity of a storage unit depends on its state of charge and on the needs of the system. As opposed to static and stochastic units, which require hourly time series, storage unit operation is characterized by a handful of scalar parameters

Parameters:

• id (int) – Unique identifying number

• nameplate_capacity (float) – Nameplate capacity in units of power. For storage, typically the discharge rate

• charge_rate (float) – Charge rate in units of power

• discharge_rate (float) – Discharge rate in units of power

• charge_capacity (float) – Maximum charge capacity in units of energy

• roundtrip_efficiency (float) – Roundtrip efficiency as decimal percent

static to_unit_dataset(units: list[StorageUnit]) → Dataset

Convert a list of storage units into an xarray dataset

Parameters:

units (list[StorageUnit]) – List of of storage energy units

Returns:

Dataset with dimensions (energy_unit) and

variables (nameplate_capacity[energy_unit], charge_rate[energy_unit], discharge_rate[energy_unit], charge_capacity[energy_unit], roundtrip_efficiency[energy_unit] hourly_forced_outage_rate[energy_unit, time]). Coordinates for the energy_unit dimension are energy unit IDs

Return type:

xr.Dataset

static from_unit_dataset(unit_dataset: Dataset) → list[StorageUnit]

Convert a storage unit dataset to a list of storage units.

This is the inverse StorageUnit.to_unit_dataset function

Parameters:

unit_dataset (xr.Dataset) – Unit dataset with structure and content defined in the derived StorageUnit.to_unit_dataset function

Returns:

List of storage units

Return type:

list[StorageUnit]

static get_probabilistic_capacity_matrix(unit_dataset: Dataset, net_hourly_capacity_matrix: DataArray) → DataArray

Return probabilistic hourly capacity matrix for a storage unit dataset.

For storage units, it is necessary to dispatch units every hour and iteration sequentially. The dispatch policy implemented in StorageUnit._get_hourly_capacity is a greedy policy to minimize expected unserved energy. Units are dispatched according to the order they appear in the unit dataset

Parameters:

• unit_dataset (xr.Dataset) – Storage unit dataset, as generated by StorageUnit.to_unit_dataset function

• net_hourly_capacity_matrix (xr.DataArray) – Probabilistic net hourly capacity matrix with dimensions (trials, time) and shape (# of trials, # of hours)

Returns:

Combined hourly capacity for all units in the unit

dataset with the same dimensions and shape as net hourly capacity matrix

Return type:

xr.DataArray

class assetra.units.DemandUnit(id: int, hourly_demand: DataArray)

Derived energy unit class, providing a more meaningful interface for demand. Internally, demand is treated as a static unit with negative capacity and a nameplate rating of zero.

This interface converts positive hourly demand into negative hourly capacity

Parameters:

• id (int) – Unique identifying number

• hourly_demand (xr.DataArray) – Hourly demand contained in DataArray with dimension (time) and datetime coordinates.

class assetra.units.HydroUnit(id, nameplate_capacity, monthly_expected_generation, hourly_forced_outage_rate=None)

Derived energy unit class.

A hydro unit represents a hydropower generator that allocates its monthly expected generation by dispatching proportionally to unmet demand in each hour, subject to its nameplate capacity and (optionally) forced outages.

Parameters:

• id (int) – Unique identifying number.

• nameplate_capacity (float) – Nameplate capacity of the hydro unit in units of power.

• monthly_expected_generation (xr.DataArray) – Expected monthly generation, in units of energy, as a DataArray with dimension (month).

• hourly_forced_outage_rate (xr.DataArray, optional) – Hourly forced outage rate as decimal percents, as a DataArray with dimension (time) and datetime coordinates. Defaults to None.

static to_unit_dataset(units: list[HydroUnit]) → Dataset

Convert a list of hydro units into an xarray dataset.

Parameters:

units (list[HydroUnit]) – List of hydro units.

Returns:

Dataset storing sufficient information to reconstruct the list of hydro units,

including nameplate capacity, monthly expected generation, and, if present, hourly forced outage rates.

Return type:

xr.Dataset

static from_unit_dataset(unit_dataset: Dataset) → list[HydroUnit]

Convert a hydro unit dataset to a list of hydro units.

This is the inverse to HydroUnit.to_unit_dataset function.

Parameters:

unit_dataset (xr.Dataset) – Unit dataset with structure defined in HydroUnit.to_unit_dataset.

Returns:

List of hydro units.

Return type:

list[HydroUnit]

static get_probabilistic_capacity_matrix(unit_dataset: Dataset, net_hourly_capacity_matrix: DataArray) → DataArray

Return probabilistic hourly capacity matrix for a hydro unit dataset.

For each hydro unit, simulate hourly capacity allocation in each trial, optionally accounting for forced outages if an hourly outage rate is present.

Parameters:

• unit_dataset (xr.Dataset) – Hydro unit dataset, as generated by HydroUnit.to_unit_dataset.

• net_hourly_capacity_matrix (xr.DataArray) – Probabilistic net hourly capacity matrix with dimensions (trial, time) and shape (#trials, #hours).

Returns:

Combined hourly capacity for all units in the unit dataset, with the same

dimensions and shape as net_hourly_capacity_matrix.

Return type:

xr.DataArray