Model Schema

generation_models.generation_models.

class StorageCoupling(*values)

Enum class for selecting coupling bus for hybrid systems

ac = 'ac': indicates the BESS and generator are coupled at the medium voltage AC bus

dc = 'dc': indicates the BESS and generator are coupled together at the DC inputs of the generator inverter

hv_ac = 'hv_ac': indicates the BESS and generator are coupled at the high voltage AC bus, e.g. the outlet of the GSU/substation

class SingleAxisTracking(*, tracking_type: Literal['SAT'] = 'SAT', rotation_limit: float = 45.0, backtrack: bool = True)

N-S oriented single axis tracker model

tracking_type: t.Literal['SAT']: Used by the API for model-type discrimination, can be ignored

rotation_limit: float

The limit of rotation angle for a single axis tracker. Assumed to be symmetric around 0° (tracker horizontal)

Unit: degrees
Example: 45 for range of +45° to -45°

backtrack: bool

Backtracking eliminates shading between rows of single-axis-tracking arrays (within the rotation_limit) by altering the rotation angle of the tracker.

Format as a Boolean
Example: True to enable backtracking

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class FixedTilt(*, tracking_type: Literal['FT'] = 'FT', tilt: float)

Fixed tilt array model

tracking_type: t.Literal['FT']: Used by the API for model-type discrimination, can be ignored

tilt: float

The angle of orientation for a fixed tilt array relative to horizontal, with positive angles tilting the array towards the azimuth and negative angles tilting it away.

Unit: degrees
Example: 30 for 30°

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ScalarUtilization(*, actual: float, lower: float, upper: float)

The quantity of an Ancillary Services capacity award that is dispatched by the grid operator.

Most operators require sufficient State of Charge to meet AS obligations throughout the day, however the amount that a system gets dispatched is unknown in advance. To account for this, we allow you to model a range of uncertainty using the following parameters and ensure State of Charge feasibility over an entire horizon. Please contact us with further questions on this concept (more detailed explanations coming soon).

The ScalarUtilization class applies a single uncertainty range for the entire simulation. This is useful for scenarios where more detailed utilization information isn’t available or accurate. For example, applying historical utilization averages to a forecast simulation. To be able to apply utilization ranges as a time series, use TimeSeriesUtilization

actual: float

The modeled dispatched capacity for the base case analysis.

Units: fraction of capacity award for the specific service
Example values: 0.20 (20%) for regulation markets, 0.05 (5%) for reserves markets

lower: float

The lower bound dispatched capacity.

Units: fraction of capacity award for the specific service
Example values: 0.0 indicating no operations

upper: float

The upper bound dispatched capacity.

Units: fraction of capacity award for the specific service
Example values: 1.0 (100%) indicating that sufficient state of charge needs to be reserved to meet full capacity award.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TimeSeriesUtilization(*, actual: List[float], lower: List[float], upper: List[float])

The quantity of an Ancillary Services capacity award that is dispatched by the grid operator.

The TimeSeriesUtilization class applies a unique utilization scenario to each reserve market time interval. This is useful for scenarios with corresponding price and utilization, or when you want to be able to vary the utilization over time.

For more information on utilization generally, see the ScalarUtilization docs

actual: t.List[float]

The modeled dispatched capacity for the base case analysis.

Units: fraction of capacity award for the specific service
Example values: 0.20 (20%) for regulation markets, 0.05 (5%) for reserves markets

lower: t.List[float]

The lower bound dispatched capacity.

Units: fraction of capacity award for the specific service
Example values: 0.0 indicating no operations

upper: t.List[float]

The upper bound dispatched capacity.

Units: fraction of capacity award for the specific service
Example values: 1.0 (100%) indicating that sufficient state of charge needs to be reserved to meet full capacity award.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class BaseReserveMarket(*, price: List[float], deployment_price: List[float] | None = None, offer_cap: float | List[float], obligation: List[float] | None = None)

price: t.List[float]

The capacity prices for this specific service. Used in dispatch co-optimization. Assumed to be hourly. The list length must be equivalent to the hourly sum of all battery terms.

Units: $/MW
Values length: if the project is a 1-year project, the list must be 8760-values long

deployment_price: t.Optional[t.List[float]]

The deployment/utilization prices for this specific service. This is the price paid for actual deployment (called/utilized energy), separate from the capacity price. If specified, deployment revenue replaces RTM settlement for the deployed portion. Unlike price, this follows real-time market granularity (typically 5-minute intervals), not hourly. The list length must match the RTM price length.

Units: $/MWh
Values length: must match RTM price length (e.g., 288 values for a 24-hour day with 5-minute intervals)

offer_cap: t.Union[float, t.List[float]]

The maximum storage capacity that can be bid for this specific service in each interval. Specific offer values will be allocated by the dispatch optimization algorithm. Can be a single float (applied to all intervals) or a time series list (assumed to be hourly). If a list, the length must match the price length.

Units: kW
Maximum value: 200% of nameplate power

obligation: t.Optional[t.List[float]]

Time series of already-cleared reserve market obligations. If provided, reserve markets participation is treated as a constraint on real-time market participation, instead of reserve market participation being co-optimized.

Assumed to be hourly
Must have same length as price
Positive-only values
Units: kW

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ReserveMarket(*, price: List[float], deployment_price: List[float] | None = None, offer_cap: float | List[float], obligation: List[float] | None = None, utilization: ScalarUtilization | TimeSeriesUtilization, duration_requirement: float = 0.0)

General class for different types of Ancillary Services.

This will be a dictionary item in either the up or down field of ReserveMarkets depending on the service.

utilization: t.Union[ScalarUtilization, TimeSeriesUtilization]: Sub-model to account for utilization uncertainty. See ScalarUtilization. If using TimeSeriesUtilization, must be same length as price.

duration_requirement: float

The duration for which a reserve offer must be sustainable, given a BESS’s SOE. For example, for a duration_requirement of 1 hour, a 10MW / 2hr battery with a current SOE of 5MWh would only be allowed to offer 5MW to the reg-up market, as this is the output it could sustain for 1 hour. This only applies to “up” markets.

Units: hours
Default: 0 hours
Recommended values: - ERCOT reg-up: 1 hour - ERCOT reserves (RRS): 1 hour

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

price

The capacity prices for this specific service. Used in dispatch co-optimization. Assumed to be hourly. The list length must be equivalent to the hourly sum of all battery terms.

Units: $/MW
Values length: if the project is a 1-year project, the list must be 8760-values long

deployment_price

The deployment/utilization prices for this specific service. This is the price paid for actual deployment (called/utilized energy), separate from the capacity price. If specified, deployment revenue replaces RTM settlement for the deployed portion. Unlike price, this follows real-time market granularity (typically 5-minute intervals), not hourly. The list length must match the RTM price length.

Units: $/MWh
Values length: must match RTM price length (e.g., 288 values for a 24-hour day with 5-minute intervals)

offer_cap

The maximum storage capacity that can be bid for this specific service in each interval. Specific offer values will be allocated by the dispatch optimization algorithm. Can be a single float (applied to all intervals) or a time series list (assumed to be hourly). If a list, the length must match the price length.

Units: kW
Maximum value: 200% of nameplate power

obligation

Time series of already-cleared reserve market obligations. If provided, reserve markets participation is treated as a constraint on real-time market participation, instead of reserve market participation being co-optimized.

Assumed to be hourly
Must have same length as price
Positive-only values
Units: kW

class SymmetricReserveMarket(*, price: List[float], deployment_price: List[float] | None = None, offer_cap: float | List[float], obligation: List[float] | None = None, up_utilization: ScalarUtilization | TimeSeriesUtilization, down_utilization: ScalarUtilization | TimeSeriesUtilization, up_duration_requirement: float = 0.0, down_duration_requirement: float = 0.0)

Convenience interface that immediately gets broken up into two ReserveMarkets constrained to be symmetric.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

price

The capacity prices for this specific service. Used in dispatch co-optimization. Assumed to be hourly. The list length must be equivalent to the hourly sum of all battery terms.

Units: $/MW
Values length: if the project is a 1-year project, the list must be 8760-values long

deployment_price

The deployment/utilization prices for this specific service. This is the price paid for actual deployment (called/utilized energy), separate from the capacity price. If specified, deployment revenue replaces RTM settlement for the deployed portion. Unlike price, this follows real-time market granularity (typically 5-minute intervals), not hourly. The list length must match the RTM price length.

Units: $/MWh
Values length: must match RTM price length (e.g., 288 values for a 24-hour day with 5-minute intervals)

offer_cap

The maximum storage capacity that can be bid for this specific service in each interval. Specific offer values will be allocated by the dispatch optimization algorithm. Can be a single float (applied to all intervals) or a time series list (assumed to be hourly). If a list, the length must match the price length.

Units: kW
Maximum value: 200% of nameplate power

obligation

Time series of already-cleared reserve market obligations. If provided, reserve markets participation is treated as a constraint on real-time market participation, instead of reserve market participation being co-optimized.

Assumed to be hourly
Must have same length as price
Positive-only values
Units: kW

class ReserveMarkets(*, up: Dict[str, ReserveMarket] = {}, down: Dict[str, ReserveMarket] = {}, symmetric: Dict[str, SymmetricReserveMarket] = {})

Container for holding ancillary/reserve market inputs

up: t.Dict[str, ReserveMarket]

dictionary of reserve markets, where each key is the market name and the corresponding value is the ReserveMarket object.

For example:

{
    'reg_up': ReserveMarket(...),
    'rrs': ReserveMarket(...)
}

down: t.Dict[str, ReserveMarket]: dictionary of reserve markets, where each key is the market name and the corresponding value is the ReserveMarket object. See up for example

symmetric: t.Dict[str, SymmetricReserveMarket]

dictionary of symmetric reserve markets, where each key is the market name and the corresponding value is the: SymmetricReserveMarket object.

For example:

{
    'reg': SymmetricReserveMarket(...),
}

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DARTPrices(*, rtm: Annotated[list[float], Len(min_length=1, max_length=None)], dam: Annotated[list[float], Len(min_length=1, max_length=None)], imbalance: Annotated[list[float], Len(min_length=1, max_length=None)] | None = None)

Energy prices used for the energy arbitrage application.

rtm: conlist(float, min_length=1)

Real-time market prices. Prices correspond to the time interval given by PVStorageModel.time_interval_mins or StandaloneStorageModel.time_interval_mins. The list length must match the sum of all battery terms when given in the chosen time interval.

For example: if the project has 2 batteries, each with a 1-year term, and the chosen interval is 15min, the list must be (2 battery years) * (8760*4 intervals per year) = 70080 values long

dam: conlist(float, min_length=1)

Hourly Day-Ahead prices. The list length must match the hourly sum of all battery terms.

For example: if the project is a 1-year, hourly project, the list must be 8760-values long

imbalance: t.Optional[conlist(float, min_length=1)]: Imbalance market or payment prices. Intended for modeling e.g. ERCOT’s Real Time On-line Reserve Price Adder (RTORPA). Prices correspond to the time interval given by PVStorageModel.time_interval_mins or StandaloneStorageModel.time_interval_mins and list length must match rtm

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SolarResourceTimeSeries(*, year: List[int], month: List[int], day: List[int], hour: List[int], minute: List[int], tdew: List[float], df: List[float], dn: List[float], gh: List[float], pres: List[float], tdry: List[float], wdir: List[float], wspd: List[float], alb: List[float] | None = None, snow: List[float] | None = None)

Irradiance and environmental time series data

The interval for all time series is assumed to match PVGenerationModel.time_interval_mins.
All time-series must be the same length.
For sub-hourly data, the timestamp represented by the year, month, day, hour and minute attributes represents the beginning of the time interval, as well as the time to be used for sun position calculations. For hourly data, the beginning of the time interval is given by hour. minute indicates the point within the interval to be used for determining sun position.
The irradiance and weather values represent average values across the interval. Timestamps are assumed to be in local standard time and should not consider Daylight Savings Time or include leap days. To model a leap day (e.g. for a back-cast with aligned price and irradiance data), repeat timestamps for 2/28.
Typical Year (TY) solar resource data represents the “typical” resource in a location such that the data can be tiled across all the years of a project’s lifetime. Data is assumed to be typical if it spans 8760 hours and project_term and project_term_units equate to a whole number of years. TY data should: - represent one full year of data (8760 hours) - not contain any leap days - start with the 0th hour of January 1st.

year: t.List[int]

Year value of the interval-beginning timestamp

4 digit integer.

month: t.List[int]

Month value of interval-beginning timestamp

Possible values: 1-12.

day: t.List[int]

Day value of interval-beginning timestamp

Possible values: 1-31

hour: t.List[int]

Hour value of interval-beginning timestamp

Possible values: 0-23

minute: t.List[int]

Minute values of interval-beginning timestamp, or for hourly simulations, the minute associated with desired sun position

Possible values: 0-59
For hourly simulations, in almost all cases, this should be 30 for all intervals (the midpoint of the hour)

tdew: t.List[float]

Dew point temperature

Units: °C

df: t.List[float]

Diffuse Horizontal Irradiance

Units: W/m²

dn: t.List[float]

Direct Normal Irradiance

Units: W/m²

gh: t.List[float]

Global Horizontal Irradiance

Units: W/m²

pres: t.List[float]

Ambient pressure

Units: milibar

tdry: t.List[float]

Ambient Temperature (dry bulb)

Units: °C

wdir: t.List[float]

Wind direction

Units: degrees east of north, with a wind from the north having a value of 0.0

wspd: t.List[float]

Wind speed

Units: meter per second

alb: t.Optional[t.List[float]]

Surface albedo

Units: ratio of reflected GHI
Default value is 0.2

snow: t.Optional[t.List[float]]

Snow depth

Units: centimeters

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SolarResource(*, latitude: float, longitude: float, time_zone_offset: float, elevation: float, data: SolarResourceTimeSeries, monthly_albedo: List[float] | None = None)

Sub-model for full specification of solar resource inputs

latitude: float

Geographic coordinate for the North-South position of the resource in decimal degrees

Example: 38.0 for 38.0°N

longitude: float

Geographic coordinate for the East-West position of the resource in decimal degrees

Example: -80.0 for 80.0°W

time_zone_offset: float

The UTC offset for the amount of time subtracted from or added to the UTC timezone. This is used in conjuction with the local-standard timestamps contained in data

Example: -8.0 for UTC-8:00 (Pacific Standard Time)

elevation: float

Height above (or below) sea level.

Units: meters
Example: 358.0 for 358 meters above sea level

data: SolarResourceTimeSeries: Solar resource time series data, see SolarResourceTimeSeries for gotchas (e.g. Typical Year constraints)

monthly_albedo: t.Optional[t.List[float]]

Surface albedo is the fraction of the Global Horizontal Irradiance that reflects, more detail here. If provided, this value overrides the hourly albedo value in SolarResourceTimeSeries.

Units: ratio
Format as a 12 element list of floats
Example: [0.2] * 12 for 12 months of 0.2 albedo
Default value is 0.2

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PSMRegion(*values)

Region / satellite system to query for irradiance data.

NorthAmerica = 'North America': Irradiance data from the GOES satellite system

AsiaPacific = 'Asia/Pacific': Irradiance data from the Himawari satellite system

EuropeAfricaAsia = 'Europe/Africa/Asia': Irradiance data from the Meteosat Prime Meridian satellite system

class SolarResourceLocation(*, latitude: float, longitude: float, region: PSMRegion = PSMRegion.NorthAmerica)

Location inputs class for pulling PSM solar resource data from the NSRDB

latitude: float

Geographic coordinate for the North-South position of the resource in decimal degrees

Example: 38.0 for 38.0°N

longitude: float

Geographic coordinate for the East-West position of the resource in decimal degrees

Example: -80.0 for 80.0°W

region: PSMRegion: regional data set to be queried

model_config = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class FileComponent(*, path: str)

Equipment inputs class for using inverter/pv module files that have already been uploaded to Tyba, e.g. via the Webapp

path: str: Path in Tyba database to uploaded file. Please contact Tyba for assistance in determining the correct file path

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PVModuleCEC(*, bifacial: bool, a_c: float, n_s: float, i_sc_ref: float, v_oc_ref: float, i_mp_ref: float, v_mp_ref: float, alpha_sc: float, beta_oc: float, t_noct: float, a_ref: float, i_l_ref: float, i_o_ref: float, r_s: float, r_sh_ref: float, adjust: float, gamma_r: float, bifacial_transmission_factor: float, bifaciality: float, bifacial_ground_clearance_height: float)

Inputs for modeling PV module/array performance using the CEC module model, which is an extension of the Desoto 5-parameter model. More information on how the model is implemented in NREL SAM (and by extension Tyba) can be found in Section 10.4 of the SAM Photovoltaic Model Technical Reference Update.

bifacial: bool: Whether or not the module is bifacial

a_c: float

Module area

Units: m²
Example value: 2.17 m²

n_s: float

Number of cells

Example value: 72

i_sc_ref: float

Short circuit current at STC

Units: Adc
Example value: 11.3 Adc

v_oc_ref: float

Open circuit voltage at STC

Units: Vdc
Example value: 48.6 Vdc

i_mp_ref: float

Max power current at STC

Units: Adc
Example value: 10.8 Adc

v_mp_ref: float

Max power voltage at STC

Units: Vdc
Example value: 40.1Vdc

alpha_sc: float

Temperature coefficient of short circuit current

Denormalize the CEC Data-sheet $\\alpha$ value as follows:
- $\\alpha = {\\alpha_{CEC}}*{I_{sc}/100}$
Units: A/K
Example value: 0.00461 A/K

beta_oc: float

Temperature coefficient of open circuit voltage

Denormalize the CEC Data-sheet $\\beta$ value as follows:
- $\\beta = {\\beta_{CEC}}*{V_{oc}/100}$
Units: V/K
Example value: -0.1406 V/K

t_noct: float

Nominal operating cell temperature

Units: °C
Example value: 44.0°C

a_ref: float

Ideality factor at STC

Units: V
Example value: 1.81 V

i_l_ref: float

Light current at STC

Units: A
Example value: 11.47 A

i_o_ref: float

Diode saturation current at STC

Units: A
Example value: 2.63e-11 A

r_s: float

Reference series resistance

Units: $\\Omega$
Example value: 0.27$\\Omega$

r_sh_ref: float

Reference shunt resistance

Units: $\\Omega$
Example value: 453.56$\\Omega$

adjust: float

Temperature coefficient adjustment factor

Format as a float that represents the percentage
Example value: 7.64 for 7.64%

gamma_r: float

Temperature coefficient of maximum power

Units: %/°C
Example value: -0.36%/°CC

bifacial_transmission_factor: float

Fraction of irradiance incident on the front surface of the array that passes through and strikes the ground (and thus contributes to backside irradiance). Such transmission can be due to e.g. gaps between modules, module/cell borders for glass-glass modules etc. Sometimes estimated as the ratio of the area light can pass through to the total bounding area of the array frontside collector surface

Ignored if bifacial is False
Format as a float that represents the decimal value
Example value: 0.2 for 20%

bifaciality: float

Rear-side to front-side efficiency ratio.

Ignored if bifacial is False
Format as a float that represents the decimal value
Example value: 0.68 for 68%

bifacial_ground_clearance_height: float

Height from the ground to the bottom of the PV array. For tracking systems, this is the height at a zero-degree tilt

Ignored if bifacial is False
Units: m
Example value: 0 m

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class MermoudModuleTech(*values)

Enum class for selecting module technology input to PVModuleMermoudLejeune.tech

SiMono = 'mtSiMono': Monocrystalline Silicon

SiPoly = 'mtSiPoly': Polycrystalline Silicon

CdTe = 'mtCdTe': Thin-film Cadmium-Telluride

CIS = 'mtCIS': Copper Indium Gallium Selenide

uCSi_aSiH = 'mtuCSi_aSiH': Amorphous Silicon

class PVModuleMermoudLejeune(*, bifacial: bool, bifacial_transmission_factor: float, bifaciality: float, bifacial_ground_clearance_height: float, tech: MermoudModuleTech, iam_c_cs_iam_value: List[float] | None = None, iam_c_cs_inc_angle: List[float] | None = None, i_mp_ref: float, i_sc_ref: float, length: float, n_diodes: int, n_parallel: int, n_series: int, r_s: float, r_sh_0: float, r_sh_exp: float, r_sh_ref: float, s_ref: float, t_c_fa_alpha: float, t_ref: float, v_mp_ref: float, v_oc_ref: float, width: float, alpha_sc: float, beta_oc: float, mu_n: float, n_0: float, custom_d2_mu_tau: float | None = None)

Inputs for modeling PV module/array performance using the Mermoud-Legeune (aka PVsyst) model. Instances can be generated from PAN files using tyba_client.io.pv_module_from_pan()

bifacial: bool: Whether or not the module is bifacial

bifacial_transmission_factor: float

Fraction of irradiance incident on the front surface of the array that passes through and strikes the ground (and thus contributes to backside irradiance). Such transmission can be due to e.g. gaps between modules, module/cell borders for glass-glass modules etc. Sometimes estimated as the ratio of the area light can pass through to the total bounding area of the array frontside collector surface

Ignored if bifacial is False
Format as a float that represents the decimal value
Example value: 0.2 for 20%

bifaciality: float

Rear-side to front-side efficiency ratio.

Ignored if bifacial is False
Format as a float that represents the decimal value
Example value: 0.68 for 68%

bifacial_ground_clearance_height: float

Height from the ground to the bottom of the PV array. For tracking systems, this is the height at a zero-degree tilt

Ignored if bifacial is False
Units: m
Example value: 0 m

tech: MermoudModuleTech: Input for selecting module technology, which determines $E_g$ and $\\frac{d^2}{\\mu_{\\tau, eff}}$ used in the single diode equation. Values are chosen based on recommendations in the PVSyst User Guide. Note that a custom value for $\\frac{d^2}{\\mu_{\\tau, eff}}$ can also be provided with the custom_d2_mu_tau input.

iam_c_cs_iam_value: t.Optional[t.List[float]]

Incident angle modifier factors

Corresponds to iam_c_cs_inc_angle
Units: unitless
Example values: [1.0, 1.0, 0.95, 0.85, 0.6, 0.2, 0.]

iam_c_cs_inc_angle: t.Optional[t.List[float]]

Incident angle modifier angles

Corresponds to iam_c_cs_iam_value
Units: degrees
Example values: [0, 15, 30, 45, 60, 75, 90]

i_mp_ref: float

Max power current at reference conditions (set by s_ref and t_ref)

Units: Adc
Example value: 10.8 Adc

i_sc_ref: float

Short circuit current at reference conditions (set by s_ref and t_ref)

Units: Adc
Example value: 11.3 Adc

length: float

Long dimension of solar module

Units: m
Example value: 1.956m

n_diodes: int

Number of diodes in solar cell

Units: quantity
Example value: 3

n_parallel: int

Number of cells in parallel

Units: quantity
Example value: 1

n_series: int

Number of cells in series

Units: quantity
Example value: 72

r_s: float

Reference series resistance

Units: $\\Omega$
Example value: 0.27

r_sh_0: float

Shunt resistance in 0 irradiance

Units: $\\Omega$
Example value: 2500

r_sh_exp: float

Shunt resistance exponential factor

Units: $\\Omega$
Example value: 5.5

r_sh_ref: float

Shunt resistance at reference conditions (set by s_ref and t_ref)

Units: $\\Omega$
Example value: 600

s_ref: float

Reference irradiance. In almost all cases this should be 1000 W/m² corresponding to STC

Units: W/m²
Example value: 1000

t_c_fa_alpha: float

Faiman thermal model absorptivity. Referred to as “Alpha” in the PVsyst User Guide.

Units: unitless
Example value: 0.90

t_ref: float

Reference temperature. In almost all cases this should be 25°C corresponding to STC

Units: °C
Example value: 25.0

v_mp_ref: float

Max power voltage at reference conditions (set by s_ref and t_ref)

Units: Vdc
Example value: 40.1Vdc

v_oc_ref: float

Open circuit voltage at reference conditions (set by s_ref and t_ref)

Units: Vdc
Example value: 48.6Vdc

width: float

Short dimension of solar module

Units: m
Example value: 0.992 m

alpha_sc: float

Temperature coefficient of short circuit current

Units: A/K
Example value: 0.00461 A/K

beta_oc: float

Temperature coefficient of open circuit voltage

Units: V/K
Example value: -0.1406 V/K

mu_n: float

Temperature coefficient of diode non-ideality factor

Units: 1/K
Example value: -0.0007 1/K

n_0: float

Diode non-ideality factor

Units: 1/K
Example value: 0.967

custom_d2_mu_tau: t.Optional[float]

Custom recombination loss coefficient. If not set, the value of $\\frac{d^2}{\\mu_{\\tau, eff}}$ is chosen based on tech

Units: V
Example value: 1.4 V

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class Inverter(*, mppt_low: float, mppt_high: float, paco: float, vdco: float, pnt: float, includes_xfmr: bool = False, pso: float, pdco: float, c0: float, c1: float, c2: float, c3: float, vdcmax: float)

Inputs for modeling inverter performance using the Sandia Inverter Model.

pso: float

Power use during operation

Units: Wdc
Example value: 6429 Wdc

pdco: float

Maximum DC power

Units: Wdc
Example value: 4272031 Wdc

c0: float

First Sandia Coefficients

Units: 1/Wac
Example value: 2.84059e-9 1/Wac

c1: float

Second Sandia Coefficient

Units: 1/Vdc
Example values: 1.1e-5

c2: float

Third Sandia Coefficient

Units: 1/Vdc
Example values: 0.001713

c3: float

Fourth Sandia Coefficient

Units: 1/Vdc
Example values: 0.001056

vdcmax: float

Maximum DC Voltage

Units: Vdc
Example value: 1200 Vdc

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mppt_low

Minimum MPPT DC Voltage

Units: Vdc
Example value: 1003 Vdc

mppt_high

Maximum MPPT DC Voltage

Units: Vdc
Example value: 1200 Vdc

paco

Maximum AC power

Units: Wac
Example value: 4198240 Wac

vdco

Nominal DC Voltage

Units: Vdc
Example value: 1062 Vdc

pnt

Standby/Nighttime power use

Units: Wac
Example value: 1259.47 Wac

includes_xfmr: Indicate whether inverter model includes a medium voltage transformer. If set to True, then ACLosses.mv_transformer should be None or MV transformer losses will be double counted.

class ONDTemperatureDerateCurve(*, ambient_temp: List[float], max_ac_power: List[float])

Temperature derate inputs for use with ONDInverter. Maximum AC power is assumed to vary linearly between the points, as explained in the PVSyst User Guide.

ambient_temp: t.List[float]

Temperatures in the derate curve, corresponding to max_ac_power

Units: °C
Example values: [25.0, 50.0, 60.0]

max_ac_power: t.List[float]

Maximum AC output values in the derate curve, corresponding to ambient_temp

Units: W
Example values: [14000, 12000, 10000]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ONDEfficiencyCurve(*, dc_power: List[float], ac_power: List[float])

Efficiency curve inputs for use with ONDInverter

dc_power: t.List[float]

List of input DC power values. First value must equal to ONDInverter.dc_turn_on

Units: W
Examples values: [0.0, 200.0, 300.0, 600.0, 1000.0]

ac_power: t.List[float]

List of output AC power values corresponding to the values in dc_power

Units: W
Example values: [0.0, 199.0, 298.0, 596.0, 1090.0]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ONDInverter(*, mppt_low: float, mppt_high: float, paco: float, vdco: float, pnt: float, includes_xfmr: bool = False, temp_derate_curve: ONDTemperatureDerateCurve, nominal_voltages: List[float], power_curves: List[ONDEfficiencyCurve], dc_turn_on: float, aux_loss: float | None = None, aux_loss_threshold: float | None = None)

Inputs for modeling inverter performance using the PVSyst/OND model. Instances can be generated from OND files using tyba_client.io.inverter_from_ond().

temp_derate_curve: ONDTemperatureDerateCurve: Curve of maximum AC power vs ambient temperature

nominal_voltages: t.List[float]

DC voltage values that correspond to the curves provided in power_curves. Must have 3 voltages.

Units: Vdc
Example values: [900.0, 1200.0, 1500.0]

power_curves: t.List[ONDEfficiencyCurve]: DC vs AC power curves that correspond to the dc voltages in nominal_voltages. Must have 3 curves. First DC power value in each curve must equal to dc_turn_on

dc_turn_on: float

Minimum DC power value that must be provided for AC power to be produced by inverter.

Units: W
Example value: 100.0

aux_loss: t.Optional[float]

Additional losses applied after efficiency and clipping when AC power is above aux_loss_threshold. This can be used to represent e.g. fan losses. However, some manufacturers include the “Aux_Loss” value in the OND file for reporting purposes even though the aux loss effect is represented in the power_curves. In this case, aux_loss should be None. Consult with your inverter manufacturer for clarification.

Units: W
Example value: 100.0

aux_loss_threshold: t.Optional[float]

DC power threshold above which the loss in aux_loss gets applied.

Units: W
Example value: 200.0

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mppt_low

Minimum MPPT DC Voltage

Units: Vdc
Example value: 1003 Vdc

mppt_high

Maximum MPPT DC Voltage

Units: Vdc
Example value: 1200 Vdc

paco

Maximum AC power

Units: Wac
Example value: 4198240 Wac

vdco

Nominal DC Voltage

Units: Vdc
Example value: 1062 Vdc

pnt

Standby/Nighttime power use

Units: Wac
Example value: 1259.47 Wac

includes_xfmr: Indicate whether inverter model includes a medium voltage transformer. If set to True, then ACLosses.mv_transformer should be None or MV transformer losses will be double counted.

class Layout(*, orientation: str | None = None, vertical: int | None = None, horizontal: int | None = None, aspect_ratio: float | None = None)

Inputs related to the configuration of PV modules within their racking

orientation: t.Optional[str]

The orientation of the PV modules within their racking.

Possible values: “portrait” (length is vertical) or “landscape” (width is vertical)
Default is “portrait”

vertical: t.Optional[int]

The number of modules along the vertical axis (side) of the racking table.

Default value is 2

horizontal: t.Optional[int]

The number of modules along the horizontal axis (bottom) of the racking table per sub-array.

Default value is 48

aspect_ratio: t.Optional[float]

The ratio of the module length to module width.

Default value is 1.7

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class Transformer(*, rating: float | None = None, load_loss: float, no_load_loss: float)

Inputs for modeling transformers (both high (HV) and medium voltage (MV))

rating: t.Optional[float]

The transformer’s rated power capacity. If set to None, the rated power capacity will be either: the total nominal AC inverter capacity (if inverters are modeled), or the poi_limit

Units: kW
Example value: 100000.0

load_loss: float

The transformer’s load-dependent loss factor (coil losses) when operating at the rated capacity

Units: unitless
Recommended values:
- HV transformer/GSU = 0.007
- MV transformer = 0.009

no_load_loss: float

The transformer’s constant loss factor (core losses)

Units: unitless
Recommended values:
- HV transformer/GSU = 0.002
- MV transformer = 0.001

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ACLosses(*, ac_wiring: float = 0.01, transmission: float = 0.0, poi_adjustment: float = 0.0, transformer_load: Annotated[float | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, transformer_no_load: Annotated[float | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, hv_transformer: Transformer | None = Transformer(rating=None, load_loss=0.007, no_load_loss=0.002), mv_transformer: Transformer | None = None)

Inputs related to system losses that occur downstream of the solar/BESS inverters

ac_wiring: float

Losses from MV AC wiring resistance between the inverter/MV transformer and the point of interconnection (or HV transformer if applicable).

Units: fraction

transmission: float

Losses from HV AC wiring resistance, i.e. gen-tie wiring losses.

Units: fraction

poi_adjustment: float

Adjust AC power at POI to account for additional arbitrary losses. Intended to apply a constant haircut to model system availability, but can be used for other purposes as well.

Negative values can be used to represent power gains
Units: fraction
Given intended use of modeling availability, not applied during BESS optimization (if applicable) or to market offers and awards

transformer_load: Annotated[float | None, get_deprecator('transformer_load is deprecated and will be removed in the future. Use hv_transformer instead.')]

Deprecated. Please use hv_transformer.

The high-voltage transformer’s load-dependent loss factor (coil losses)

transformer_no_load: Annotated[float | None, get_deprecator('transformer_no_load is deprecated and will be removed in the future. Use hv_transformer instead.')]

Deprecated. Please use hv_transformer.

The high-voltage transformer’s constant loss factor (core losses)

hv_transformer: t.Optional[Transformer]: Inputs for modeling a HV transformer/GSU. Setting to None assumes the system interconnection voltage is such that a GSU is not needed. For parameter recommendations, see Transformer

mv_transformer: t.Optional[Transformer]: Inputs for modeling a MV transformer. If the inverter model given in the inverter attribute of PVGenerationModel, DCExternalGenerationModel or DownstreamSystem includes MV transformer effects, then this should be set to None to avoid double-counting losses. Otherwise, a Transformer object should be provided to ensure transformer losses are accounted for. For parameter recommendations, see Transformer

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

BoundedLossFactor

float that must be between 0 and 1 inclusive

alias of Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1.0)])]

class DCLosses(*, dc_optimizer: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, enable_snow_model: bool = False, dc_wiring: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.02, soiling: ~typing.Annotated[list[~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=-1.0), Le(le=1.0)])]], ~annotated_types.Len(min_length=12, max_length=12)] = <factory>, diodes_connections: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.005, mismatch: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.01, nameplate: ~typing.Annotated[float, ~annotated_types.Ge(ge=-0.05), ~annotated_types.Le(le=1.0)] = 0.0, rear_irradiance: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, mppt_error: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0), ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = 0.0, tracking_error: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, lid: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, dc_array_adjustment: float = 0.0)

Inputs related to PV array losses that occur upstream of the solar inverters. For use (via Losses) with PVGenerationModel

dc_optimizer: BoundedLossFactor

Losses from power equipment within the array, including DC optimizers and DC-DC converters.

Units: fraction
Min value: 0.0
Max value: 1.0

enable_snow_model: bool: Indicates whether NREL SAM’s snow loss model should be activated. If True, snow in SolarResource.data must be provided.

dc_wiring: BoundedLossFactor

Losses from DC wiring resistance within the array.

Units: fraction
Min value: 0.0
Max value: 1.0

soiling: conlist(Annotated[float, Field(ge=-1.0, le=1.0)], min_length=12, max_length=12)

Monthly reduction in irradiance occurring from dust, dirt, or other substances on the surface of the module. If enable_snow_model is False, this input should also be used to account for any snow losses. Similarly, this input can be used to approximate a combination of soiling and other effects (e.g. spectral) as a series of monthly gains and losses.

Units: fraction
Format as a list of 12 floats representing the decimal value of loss
Min monthly value: -1.0 (100% gain)
Max monthly value: 1.0 (100% loss)

diodes_connections: BoundedLossFactor

Losses from voltage drops of diodes and electrical connections.

Units: fraction
Min value: 0.0
Max value: 1.0

mismatch: BoundedLossFactor

Losses due to differences in the max power point of individual modules, as well as differences between strings. These differences can be due to manufacturing variation as well as varied shading across the array. Should include the net effect of backside mismatch for bifacial modules.

Units: fraction
Min value: 0.0
Max value: 1.0

nameplate: Annotated[float, Field(ge=-0.05, le=1.0)]

Deviations between the nameplate rating provided by a manufacturer and actual/tested performance. This input could be used to represent positive binning tolerance or the situation where you need to model a PV module with a different wattage than the one you have model parameters for.

Units: fraction
Positive values represent a loss, negative values represent a gain
Min value: -0.05 (5% gain)
Max value: 1.0 (100% loss)
Example: A module with 405W nameplate power and +5% binning tolerance could be represented by a 400W module model and $nameplate = 1 - (405/400)(1 + 0.05/2) = -0.0378$

rear_irradiance: BoundedLossFactor

Losses associated with irradiance on the back surface of bifacial modules. Should be 0.0 for monofacial modules. This would include the effects of rearside rack-shading, soiling, etc. but mismatch should be accounted for in the mismatch input

Units: fraction
Min value: 0.0
Max value: 1.0

mppt_error: Annotated[BoundedLossFactor, get_deprecator('mppt_error is deprecated and will be removed in the future. Use tracking_error instead.')]: Deprecated (as well as misnamed). Use tracking_error instead

tracking_error: BoundedLossFactor

Losses due to tracking system error in single-axis tracking systems. Should be 0.0 for fixed tilt systems.

Units: fraction
Min value: 0.0
Max value: 1.0

lid: BoundedLossFactor

Losses due to Light- and elevated Temperature-Induced Degradation.

Units: fraction
Min value: 0.0
Max value: 1.0

dc_array_adjustment: float

Adjust DC power at inverter input to account for additional arbitrary losses or gains.

Negative values can be used to represent power gains
Units: fraction

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class Losses(*, dc_optimizer: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, enable_snow_model: bool = False, dc_wiring: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.02, soiling: ~typing.Annotated[list[~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=-1.0), Le(le=1.0)])]], ~annotated_types.Len(min_length=12, max_length=12)] = <factory>, diodes_connections: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.005, mismatch: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.01, nameplate: ~typing.Annotated[float, ~annotated_types.Ge(ge=-0.05), ~annotated_types.Le(le=1.0)] = 0.0, rear_irradiance: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, mppt_error: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0), ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = 0.0, tracking_error: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, lid: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, dc_array_adjustment: float = 0.0, ac_wiring: float = 0.01, transmission: float = 0.0, poi_adjustment: float = 0.0, transformer_load: ~typing.Annotated[float | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, transformer_no_load: ~typing.Annotated[float | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, hv_transformer: ~generation_models.generation_models.Transformer | None = Transformer(rating=None, load_loss=0.007, no_load_loss=0.002), mv_transformer: ~generation_models.generation_models.Transformer | None = None)

Container class that combines ACLosses and DCLosses for use with PVGenerationModel

model_config = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ac_wiring

Losses from MV AC wiring resistance between the inverter/MV transformer and the point of interconnection (or HV transformer if applicable).

Units: fraction

transmission

Losses from HV AC wiring resistance, i.e. gen-tie wiring losses.

Units: fraction

poi_adjustment

Adjust AC power at POI to account for additional arbitrary losses. Intended to apply a constant haircut to model system availability, but can be used for other purposes as well.

Negative values can be used to represent power gains
Units: fraction
Given intended use of modeling availability, not applied during BESS optimization (if applicable) or to market offers and awards

transformer_load

Deprecated. Please use hv_transformer.

The high-voltage transformer’s load-dependent loss factor (coil losses)

transformer_no_load

Deprecated. Please use hv_transformer.

The high-voltage transformer’s constant loss factor (core losses)

hv_transformer: Inputs for modeling a HV transformer/GSU. Setting to None assumes the system interconnection voltage is such that a GSU is not needed. For parameter recommendations, see Transformer

mv_transformer: Inputs for modeling a MV transformer. If the inverter model given in the inverter attribute of PVGenerationModel, DCExternalGenerationModel or DownstreamSystem includes MV transformer effects, then this should be set to None to avoid double-counting losses. Otherwise, a Transformer object should be provided to ensure transformer losses are accounted for. For parameter recommendations, see Transformer

dc_optimizer

Losses from power equipment within the array, including DC optimizers and DC-DC converters.

Units: fraction
Min value: 0.0
Max value: 1.0

enable_snow_model: Indicates whether NREL SAM’s snow loss model should be activated. If True, snow in SolarResource.data must be provided.

dc_wiring

Losses from DC wiring resistance within the array.

Units: fraction
Min value: 0.0
Max value: 1.0

soiling

Monthly reduction in irradiance occurring from dust, dirt, or other substances on the surface of the module. If enable_snow_model is False, this input should also be used to account for any snow losses. Similarly, this input can be used to approximate a combination of soiling and other effects (e.g. spectral) as a series of monthly gains and losses.

Units: fraction
Format as a list of 12 floats representing the decimal value of loss
Min monthly value: -1.0 (100% gain)
Max monthly value: 1.0 (100% loss)

diodes_connections

Losses from voltage drops of diodes and electrical connections.

Units: fraction
Min value: 0.0
Max value: 1.0

mismatch

Losses due to differences in the max power point of individual modules, as well as differences between strings. These differences can be due to manufacturing variation as well as varied shading across the array. Should include the net effect of backside mismatch for bifacial modules.

Units: fraction
Min value: 0.0
Max value: 1.0

nameplate

Deviations between the nameplate rating provided by a manufacturer and actual/tested performance. This input could be used to represent positive binning tolerance or the situation where you need to model a PV module with a different wattage than the one you have model parameters for.

Units: fraction
Positive values represent a loss, negative values represent a gain
Min value: -0.05 (5% gain)
Max value: 1.0 (100% loss)
Example: A module with 405W nameplate power and +5% binning tolerance could be represented by a 400W module model and $nameplate = 1 - (405/400)(1 + 0.05/2) = -0.0378$

rear_irradiance

Losses associated with irradiance on the back surface of bifacial modules. Should be 0.0 for monofacial modules. This would include the effects of rearside rack-shading, soiling, etc. but mismatch should be accounted for in the mismatch input

Units: fraction
Min value: 0.0
Max value: 1.0

mppt_error: Deprecated (as well as misnamed). Use tracking_error instead

tracking_error

Losses due to tracking system error in single-axis tracking systems. Should be 0.0 for fixed tilt systems.

Units: fraction
Min value: 0.0
Max value: 1.0

lid

Losses due to Light- and elevated Temperature-Induced Degradation.

Units: fraction
Min value: 0.0
Max value: 1.0

dc_array_adjustment

Adjust DC power at inverter input to account for additional arbitrary losses or gains.

Negative values can be used to represent power gains
Units: fraction

class DCProductionProfile(*, power: List[float], voltage: List[float], ambient_temp: List[float] | None = None)

Time series inputs associated with a DC generation source (e.g. PV array). For use with DCExternalGenerationModel

power: t.List[float]

The net power at all DC-DC busbars for DC-Coupled systems, or all inverter MPP inputs for solar-only systems. This power will be divided by the number of inverters determined based on DCExternalGenerationModel.inverter and the system AC capacity before being passed through the inverter model in DCExternalGenerationModel.inverter

Should not consider any inverter clipping effects on DC power (since this clipping could be captured by a DC-coupled BESS and will be modeled in the inverter model anyways)
Assumed to include any aging/degradation effects
In PVSyst, this field is EArrayMPP (not EArray), though PVsyst does not consider degradation
Units: kW
Example: For a nameplate 100MWdc array at STC for 3 hours, the input would be [100000, 100000, 100000].

voltage: t.List[float]

The voltage at the DC-DC busbar for DC-Coupled systems or inverter MPP input for solar-only systems. Unlike power, total array voltage is not the sum of inverter DC voltages, so these values will not be divided before being passed into the inverter model.

In PVSyst, this field is Uarray
Units: V
Example: For a nominal 1500Vdc system, the max values should be somewhere near but below 1500V.

ambient_temp: t.Optional[t.List[float]]

Hourly ambient temperature. Used for inverter efficiency and HVAC model (when used).

Units: - Units: °C
Example values: [25.0, 35.0, 45.0]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class BoundedSignal(*, min: List[float], actual: List[float], max: List[float])

Container for any time series data associated with a signal that can have a range of values. For use with e.g. ACProductionProfile.power

min: t.List[float]: Time series of the lower bound of possible values the signal could take. For example, for PV array power, this might be a time series of P90 production.

actual: t.List[float]: Time series of the expected signal values. For example, for PV array power, this might be a time series of P50 production.

max: t.List[float]: Time series of the upper bound of possible values the signal could take. For example, for PV array power, this might be a time series of P05 production.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ACProductionProfile(*, power: List[float] | BoundedSignal, ambient_temp: List[float] | None = None)

Time series inputs associated with an MV AC generation source (e.g. PV MV output, wind turbines etc.). For use with ACExternalGenerationModel

power: t.Union[t.List[float], BoundedSignal]

The power at the MV AC bus (i.e. where a MV BESS system would tie-in). Can either be a time series of power values or a BoundedSignal instance for modeling uncertain PV (or other) generation.

In PVSyst, this field is EOutInv if inverter modeling takes into account MV transformer losses. If not, use E_Grid with all models downstream of the mv transformer turned off or set to zero
Units: kW

ambient_temp: t.Optional[t.List[float]]

Hourly ambient temperature. Used for HVAC model if applicable.

Units: - Units: °C
Example values: [25.0, 35.0, 45.0]

model_config = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class BaseSystemDesign(*, dc_capacity: float, ac_capacity: float, poi_limit: float)

Base class for system design objects

dc_capacity: float

The total nameplate DC capacity of all the modules in a system.

Units: kWdc
Example: 1000.0 for a 1000 kWdc system

ac_capacity: float

The total nameplate AC capacity of all the inverters in a system.

Units: kWac
Example: 1000.0 for a 1,000 kWac system

poi_limit: float

The maximum injection capacity at the point of interconnection (usually defined by an interconnection agreement).

Units: kWac
Example: 1000.0 for a system with 1MW in interconnection capacity

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PVSystemDesign(*, dc_capacity: float, ac_capacity: float, poi_limit: float, modules_per_string: int | None = None, strings_in_parallel: int | None = None, tracking: ~typing.Annotated[~generation_models.generation_models.FixedTilt | ~generation_models.generation_models.SingleAxisTracking, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.create_optionally_discriminant_union.<locals>.allow_missing_discriminator, json_schema_input_type=PydanticUndefined)], azimuth: float | None = None, gcr: float)

Inputs for PV wiring and array configuration. A submodel for PVGenerationModel.system_design

modules_per_string: t.Optional[int]: The number of modules connected in series for a single string. Generally Dependent on inverter and module selection. If not provided, a string size that keeps voltage within the inverter MPPT range is selected as part of the simulation.

strings_in_parallel: t.Optional[int]: The number of module strings connected in parallel to form an array. Generally dependent on dc_capacity and module selection. If not provided, Tyba will make an assumption as part of the simulation.

tracking: TrackingTypes: A sub-model to represent the PV racking design. Can be either FixedTilt or SingleAxisTracking

azimuth: t.Optional[float]

Orientation of the array towards the sun. Note that for fixed tilt systems, this means the direction in which the modules are tilted, whereas for single-axis tracking systems this means the direction of the axis of clock-wise rotation

Units: degrees east of north, with due north having a value of 0.0
Default value is 180° (due south) for the northern hemisphere and 0° (due north) for the southern hemisphere
Fixed Tilt Example: A northern hemisphere system with an azimuth of 190° would have all of its modules titled to face 10° west of due south
Single Axis Tracking Example: In the northern hemisphere, an azimuth of 180° (the default), would have the system tilted towards due east in the morning and due west in the evening. An azimuth of 190° would have the modules facing slightly south of east in the morning and slightly north of west in the evening

gcr: float

The ratio of total module area to total land area. This is a measure of inter-row spacing, where a low ratio means the rows are more spread out and a higher ratio means the rows are tightly packed. Note that the tilt in fixed tilt systems is not to be taken into account (not a projected area in the numerator).

Example: 0.33

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

dc_capacity

The total nameplate DC capacity of all the modules in a system.

Units: kWdc
Example: 1000.0 for a 1000 kWdc system

ac_capacity

The total nameplate AC capacity of all the inverters in a system.

Units: kWac
Example: 1000.0 for a 1,000 kWac system

poi_limit

The maximum injection capacity at the point of interconnection (usually defined by an interconnection agreement).

Units: kWac
Example: 1000.0 for a system with 1MW in interconnection capacity

class TermUnits(*values)

Enum for indicating project term units

hours = 'hours': Project term value is in units of hours

days = 'days': Project term value is in units of days

years = 'years': Project term value is in units of years

class Bus(*values)

Enum class for selecting coupling bus for hybrid systems

DC = 'DC': indicates the BESS and generator are coupled together at the DC inputs of the generator inverter

MV = 'MV': indicates the BESS and generator are coupled at the medium voltage AC bus

HV = 'HV': indicates the BESS and generator are coupled at the high voltage AC bus, e.g. the outlet of the GSU/substation

class DownstreamSystem(*, losses: ACLosses, system_design: BaseSystemDesign, model_losses_from: Bus, inverter: Inverter | ONDInverter | str | FileComponent | None = None)

Submodel for detailed treatment of losses in standalone storage systems that aren’t already considered as part of charge_efficiency and discharge_efficiency

losses: ACLosses: Submodel for post-inverter losses to be considered. Note that, depending on the coupling bus specified by model_losses_from, some of the attributes of ACLosses will be ignored. For example, if the coupling bus is specified as high voltage, ac_wiring and mv_transformer will be ignored, since they are upstream of the coupling bus.

system_design: BaseSystemDesign: Submodel that defines system size for reporting, inverter sizing, and POI limiting

model_losses_from: Bus: Indicates the coupling bus downstream of which detailed loss modeling should occur. All losses/effects upstream of this bus are assumed to be rolled into BatteryParams.charge_efficiency and BatteryParams.discharge_efficiency

inverter: t.Optional[InverterTypes]

Inputs for inverter submodel. Required if model_losses_from is “DC”, otherwise ignored. Can take multiple argument types:

An Inverter or ONDInverter object for full specification of the inverter model. In particular, use this type (along with tyba_client.io.inverter_from_ond()) if you are trying to model an inverter from a local OND file
A string of the exact inverter name in Tyba’s default inverter inventory (as shown in the web application)
A FileComponent object that specifies the exact path of an OND file that was previously uploaded to Tyba via the web application

model_config = {'protected_namespaces': ()}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ACExternalGenerationModel(*, project_term: int = 1, project_term_units: TermUnits = 'years', project_type: Literal['generation'] = 'generation', time_interval_mins: int = 60, losses: ACLosses = ACLosses(ac_wiring=0.01, transmission=0.0, poi_adjustment=0.0, transformer_load=None, transformer_no_load=None, hv_transformer=Transformer(rating=None, load_loss=0.007, no_load_loss=0.002), mv_transformer=None), production_override: ACProductionProfile, system_design: BaseSystemDesign, generation_type: Literal['ExternalAC'] = 'ExternalAC')

Inputs for specifying an MV AC generation source, e.g. PV MV power from a non-Tyba source, wind power, etc. Intended to be passed into PVStorageModel.pv_inputs for hybrid simulations but can also be used as a simulation class for generation-only simulations. When used for a generation-only simulation, GenerationModelResults is the results schema

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

system_design: Submodel that defines system size for reporting, inverter sizing, and POI limiting

project_type: Used by the API for model-type discrimination, can be ignored

time_interval_mins

Time interval that corresponds to time series in solar_resource or production_override, whichever is applicable.

Units: minutes

project_term

Integer value with units given by project_term_units that defines the project term (timespan) to be simulated.

For typical-year hybrid and solar-only simulations, the year-long time series in solar_resource will be tiled to match project_term. As such, the project term must represent a number of whole years
For all other hybrid and solar-only simulations, the project term must match the timespan represented by time_interval_mins and the length of the corresponding solar resource or power time series
For standalone storage simulations, the project term must match the timespan represented by time_interval_mins and the corresponding price time series

project_term_units: Units to be applied to project_term to define the term (timespan) to be simulated. See project_term for constraints

generation_type: t.Literal['ExternalAC']: Used by the API for model-type discrimination, can be ignored

losses: ACLosses: Submodel for system losses. ACLosses.mv_transformer must be None since the production_override is assumed to be at medium voltage already.

production_override: ACProductionProfile: Submodel for time series related to generator power. Assumed to be power at the MV AC bus

class DCExternalGenerationModel(*, project_term: int = 1, project_term_units: TermUnits = 'years', project_type: Literal['generation'] = 'generation', time_interval_mins: int = 60, losses: Losses = Losses(dc_optimizer=0.0, enable_snow_model=False, dc_wiring=0.02, soiling=[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], diodes_connections=0.005, mismatch=0.01, nameplate=0.0, rear_irradiance=0.0, mppt_error=0.0, tracking_error=0.0, lid=0.0, dc_array_adjustment=0.0, ac_wiring=0.01, transmission=0.0, poi_adjustment=0.0, transformer_load=None, transformer_no_load=None, hv_transformer=Transformer(rating=None, load_loss=0.007, no_load_loss=0.002), mv_transformer=None), production_override: DCProductionProfile, system_design: BaseSystemDesign, generation_type: Literal['ExternalDC'] = 'ExternalDC', inverter: Inverter | ONDInverter | str | FileComponent)

Inputs for specifying a DC generation source, e.g. PV array power from a non-Tyba source. Intended to be passed into PVStorageModel.pv_inputs for hybrid simulations but can also be used as a simulation class for generation-only simulations. When used for a generation-only simulation, GenerationModelResults is the results schema

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

system_design: Submodel that defines system size for reporting, inverter sizing, and POI limiting

project_type: Used by the API for model-type discrimination, can be ignored

time_interval_mins

Time interval that corresponds to time series in solar_resource or production_override, whichever is applicable.

Units: minutes

project_term

Integer value with units given by project_term_units that defines the project term (timespan) to be simulated.

For typical-year hybrid and solar-only simulations, the year-long time series in solar_resource will be tiled to match project_term. As such, the project term must represent a number of whole years
For all other hybrid and solar-only simulations, the project term must match the timespan represented by time_interval_mins and the length of the corresponding solar resource or power time series
For standalone storage simulations, the project term must match the timespan represented by time_interval_mins and the corresponding price time series

project_term_units: Units to be applied to project_term to define the term (timespan) to be simulated. See project_term for constraints

generation_type: t.Literal['ExternalDC']: Used by the API for model-type discrimination, can be ignored

losses: Losses: Submodel for system losses

production_override: DCProductionProfile

Submodel for time series related to generator power.

Assumed to be at DC bus/inverter MPPT inputs
Assumed to include any aging/degradation effects

inverter: InverterTypes

Inputs for inverter submodel. Can take multiple argument types:

An Inverter or ONDInverter object for full specification of the inverter model. In particular, use this type (along with tyba_client.io.inverter_from_ond()) if you are trying to model an inverter from a local OND file
A string of the exact inverter name in Tyba’s default inverter inventory (as shown in the web application)
A FileComponent object that specifies the exact path of an OND file that was previously uploaded to Tyba via the web application

class ArrayDegradationMode(*values)

Enum for specifying the PV array degradation approach to be used in a PVGenerationModel or PVStorageModel simulation

linear = 'linear'

The degradation applied to each year of PV DC generation will increase linearly. The annual degradation derate is calculated as $1-r_{degrad}*n_{year}$ where $r_{degrad}$ is the degradation rate specified by PVGenerationModel.array_degradation_rate and $n_{year}$ is the count for the year in question.

Example: For a degradation rate of 0.005 (0.5%), the degradation derate applied to all time intervals of year 1 is $1-0.005*1=0.995$

compounding = 'compounding'

The degradation applied to each year of PV DC generation will be compounding. The degradation derate is calculated as $(1-r_{degrad})^{n_{year}}$ where $r_{degrad}$ is the degradation rate specified by PVGenerationModel.array_degradation_rate and $n_{year}$ is the count for the year in question.

Example: For a degradation rate of 0.005 (0.5%), the degradation derate applied to all time intervals of year 2 is $(1-0.005)^2=0.99$

class PVGenerationModel(*, project_term: int = 1, project_term_units: TermUnits = 'years', project_type: Literal['generation'] = 'generation', time_interval_mins: int = 60, generation_type: Literal['PV'] = 'PV', solar_resource: SolarResource | Tuple[float, float] | SolarResourceLocation, inverter: Inverter | ONDInverter | str | FileComponent, pv_module: PVModuleCEC | PVModuleMermoudLejeune | str | FileComponent, layout: Layout = Layout(orientation=None, vertical=None, horizontal=None, aspect_ratio=None), losses: Losses = Losses(dc_optimizer=0.0, enable_snow_model=False, dc_wiring=0.02, soiling=[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], diodes_connections=0.005, mismatch=0.01, nameplate=0.0, rear_irradiance=0.0, mppt_error=0.0, tracking_error=0.0, lid=0.0, dc_array_adjustment=0.0, ac_wiring=0.01, transmission=0.0, poi_adjustment=0.0, transformer_load=None, transformer_no_load=None, hv_transformer=Transformer(rating=None, load_loss=0.007, no_load_loss=0.002), mv_transformer=None), system_design: PVSystemDesign, array_degradation_rate: float = 0.005, array_degradation_mode: ArrayDegradationMode | None = ArrayDegradationMode.linear)

Simulation class for solar-only simulations, or can be passed into PVStorageModel.pv_inputs for hybrid simulations. When used for a solar-only simulation, GenerationModelResults is the results schema

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

project_type: Used by the API for model-type discrimination, can be ignored

time_interval_mins

Time interval that corresponds to time series in solar_resource or production_override, whichever is applicable.

Units: minutes

project_term

Integer value with units given by project_term_units that defines the project term (timespan) to be simulated.

For typical-year hybrid and solar-only simulations, the year-long time series in solar_resource will be tiled to match project_term. As such, the project term must represent a number of whole years
For all other hybrid and solar-only simulations, the project term must match the timespan represented by time_interval_mins and the length of the corresponding solar resource or power time series
For standalone storage simulations, the project term must match the timespan represented by time_interval_mins and the corresponding price time series

project_term_units: Units to be applied to project_term to define the term (timespan) to be simulated. See project_term for constraints

generation_type: t.Literal['PV']: Used by the API for model-type discrimination, can be ignored

solar_resource: t.Union[SolarResource, t.Tuple[float, float], SolarResourceLocation]

Input for irradiance and weather time series and location information. Can take multiple argument types:

A SolarResource object for full specification of solar resource. Must be used if resource does not represent a Typical Year (TY), but can also represent a TY. See SolarResourceTimeSeries for more info.
A SolarResourceLocation object. With this type, Tyba will pull TY solar resource data from the NSRDB and use it in the simulation
A tuple of (latitude, longitude) where the values are in decimal degrees. This argument is equivalent to passing a SolarResourceLocation object with region equal to "North America"

Tiling of solar resource data to match the project_term is only supported for TY data

inverter: InverterTypes

Inputs for inverter submodel. Can take multiple argument types:

An Inverter or ONDInverter object for full specification of the inverter model. In particular, use this type (along with tyba_client.io.inverter_from_ond()) if you are trying to model an inverter from a local OND file
A string of the exact inverter name in Tyba’s default inverter inventory (as shown in the web application)
A FileComponent object that specifies the exact path of an OND file that was previously uploaded to Tyba via the web application

pv_module: PVModuleTypes

Inputs for PV module/array submodel. Can take multiple argument types:

An PVModuleCEC or PVModuleMermoudLejeune object for full specification of the PV module model. In particular, use this type (along with tyba_client.io.pv_module_from_pan()) if you are trying to model a PV module from a local PAN file
A string of the exact PV module name in Tyba’s default module inventory (as shown in the web application)
A FileComponent object that specifies the exact path of a PAN file that was previously uploaded to Tyba via the web application

layout: Layout: Inputs that describe module/racking geometry

losses: Losses: Submodel for both array and AC-side losses

system_design: PVSystemDesign: Inputs for system size and geometry

array_degradation_rate: float: Degradation rate applied annually to pre-inverter array DC power as specified by the array_degradation_mode. Ignored if solar_resource does not represent a Typical Year

array_degradation_mode: t.Optional[ArrayDegradationMode]

Method by which to apply array_degradation_rate to pre-inverter array DC power.

If None, no degradation will be modeled
Only applicable if solar_resource represents a Typical Year, otherwise must be None

class TableCapDegradationModel(*, annual_capacity_derates: List[float])

Submodel for defining BESS energy capacity degradation as a table of values. Intended as a way to bring data in from a guaranteed capacity table included in a BESS purchase order/warranty. Note that although this model applies degradation based on time passing, it can account for both cycle and calendar degradation assuming the guaranteed cap table specifies an annual cycle count and this is similar to the annual cycle counts in the simulation

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

annual_capacity_derates: t.List[float]

List of end-of-year BESS energy capacity derates relative to initial BESS capacity, starting with year 0. At the end of each solver step as defined by StorageSolverOptions.step, the BESS capacity will be reduced based on time passed such that the capacity matches the list derate at the end of each simulation year.

First value in the list must be 1.0 (year 0 has no degradation)
Example: For annual derates [1.0, .9915, 0.9856] and an initial capacity of 100MWh, energy capacity will decrease linearly in a step-wise fashion until it is $100*0.9915=99.15MWh$ at the end of year 1 and $100*0.9856=98.56MWh$ at the end of year 2.
List length must be greater than or equal to BatteryParams.term

class TableEffDegradationModel(*, annual_efficiency_derates: List[float])

Submodel for defining BESS efficiency degradation as a table of values. Intended as a way to bring data in from a BESS purchase order/warranty. Note that although this model applies degradation based on time passing, it can account for both cycle and calendar degradation assuming the PO/warranty specifies an annual cycle count and this is similar to the annual cycle counts in the simulation

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

annual_efficiency_derates: t.List[float]

List of end-of-year BESS efficiency derates relative to initial BESS charge and discharge efficiency, starting with year 0. At the end of each solver step as defined by StorageSolverOptions.step, the BESS efficiency parameters will be reduced based on time passed such that the efficiency matches the list derate at the end of each simulation year.

First value in the list must be 1.0 (year 0 has no degradation)
Example: For annual derates [1.0, .9915, 0.9856] and an initial charge efficiency of 98.5%, efficiency will decrease linearly in a step-wise fashion until it is $.985*0.9915=97.66\\%$ at the end of year 1 and $0.985*0.9856=97.08\\%$ at the end of year 2.
List length must be greater than or equal to BatteryParams.term

class BatteryHVACParams(*, container_temperature: float, cop: float, u_ambient: float, discharge_efficiency_container: float, charge_efficiency_container: float, aux_xfmr_efficiency: float, container_surface_area: float = 20.0, design_energy_per_container: float = 750.0)

Submodel for more detailed estimation of BESS HVAC losses. Requires ambient temperature time series as a simulation input

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

container_temperature: float

Target temperature that BESS container is assumed to be maintained at

Units: °C
Example value: 25°C

cop: float

The HVAC’s coefficient of performance.

Example value: 3.0

u_ambient: float

The heat transfer coefficient between ambient and the container

Units: W/Km²
Example value: 100.0W/Km²

discharge_efficiency_container: float

The portion of the BESS’s discharge efficiency driven by losses within the battery container, i.e., cell, rack and BMS losses.

Must be a greater than discharge_efficiency.
Units: fraction
Example value: 0.98

charge_efficiency_container: float

The portion of the BESS’s charge efficiency driven by losses within the battery container, i.e., cell, rack and BMS losses.

Must be greater than charge_efficiency
Units: fraction
Example value: 0.98

aux_xfmr_efficiency: float

The efficiency of the transformer stepping down from medium voltage to the voltage of the HVAC system.

Units: fraction
Example value: 0.99

container_surface_area: float

Surface area of a single BESS container over which it exchanges heat with the ambient. Generally should consider area in contact with the ground, depending on how u_ambient has been determined

Units: m²
Example value: 20.0

design_energy_per_container: float

Design energy capacity per each BESS container. Used to estimate the number of containers in the BESS, and (along with container_surface_area) the corresponding total surface area available for heat transfer

Units: kWh
Example value: 750.0kWh

class BatteryParams(*, power_capacity: float, energy_capacity: float, charge_efficiency: float | BoundedFloat, discharge_efficiency: float | BoundedFloat, self_discharge_rate: float | None = None, parasitic_soe_loss: float | None = None, degradation_rate: float | None = None, degradation_annual_cycles: float = 261, hvac: BatteryHVACParams | None = None, capacity_degradation_model: TableCapDegradationModel | None = None, efficiency_degradation_model: TableEffDegradationModel | None = None, term: float | None = None)

Inputs for modeling the physical performance of a BESS

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

power_capacity: float

The maximum usable capacity of the battery to draw power to charge. Assumed to be equivalent for charge and discharge. For hybrid simulations, represents maximum power at coupling bus. For standalone storage simulations, represents maximum power at the point of interconnection or at the bus specified in DownstreamSystem.model_losses_from if applicable

Units: kW
Example value: 1000kW

energy_capacity: float

The maximum usable capacity of the battery to store energy.

Units: kWh
Example value: 2000kWh

charge_efficiency: t.Union[float, BoundedFloat]

The percentage of energy stored for every kW of power drawn to charge. For hybrid simulations, should account for all losses up to the coupling bus. For standalone storage simulations, should account for all losses up to the point of interconnection or all losses up to the bus specified in DownstreamSystem.model_losses_from. If hvac is defined, should not account for BESS HVAC load.

Units: fraction
Example value: 0.965

discharge_efficiency: t.Union[float, BoundedFloat]

The percentage of energy discharged for every kW of power drawn to discharge. For hybrid simulations, should account for all losses up to the coupling bus. For standalone storage simulations, should account for all losses up to the point of interconnection or all losses up to the bus specified in DownstreamSystem.model_losses_from. If hvac is defined, should not account for BESS HVAC load.

Units: fraction
Example value: 0.965

self_discharge_rate: t.Optional[float]

Ratio of self-discharge power to SOE, applied when the battery is idle. If a value is provided, self-discharge is calculated like: $self_discharge_rate * SOE$. If None, no self-discharge occurs.

Units: kW/kWh
Example value: 0.01

parasitic_soe_loss: t.Optional[float]

Constant power drain on SOE. This is only an internal SOE loss; it doesn’t add to metered discharge.

Units: kW
Example value: 100kW

degradation_rate: t.Optional[float]

The approximate year over year (YoY) decrease in storage energy capacity due to cycling. Even though it is a YoY value, this specifies a throughput degradation model, meaning the battery degrades this percentage every degradation_annual_cycles cycles. At the end of each solver step as defined by StorageSolverOptions.step, the BESS capacity will be reduced based on the number of cycles that have occurred.

Either this parameter or capacity_degradation_model must be specified. To model no degradation, simply set to 0.0
Units: fraction
Example: for a degradation_rate of 1% and attr:degradation_annual_cycles of 261, a simulation step where 2.5 cycles occur will reduce the BESS capacity by $(0.01/261)*2.5=0.00958\\%$

degradation_annual_cycles: float: Assumed number of annual cycles corresponding to degradation_rate. See degradation_rate for more details

hvac: t.Optional[BatteryHVACParams]

Submodel for more accurately modeling the efficiency of a BESS as a function of temperature.

Requires ambient temperature as a simulation input
If None, HVAC losses should be accounted for in charge_efficiency and discharge_efficiency
HVAC losses are applied at the medium voltage (MV) bus for DC and MV-coupled systems, but at the HV bus for HV-coupled systems

capacity_degradation_model: t.Optional[TableCapDegradationModel]

Specification of the storage energy capacity degradation model. This can be used as an alternative to degradation_rate and degradation_annual_cycles. Currently, only models of type TableCapDegradationModel are supported.

Either this parameter or degradation_rate must be specified. To model no degradation, use degradation_rate and set to 0.0
If specified, must include enough data to cover the battery term

efficiency_degradation_model: t.Optional[TableEffDegradationModel]

Specification of the storage charge and discharge efficiency degradation model. Current, only models of type TableEffDegradationModel are supported. If None, no efficiency degradation is modeled

If specified, must include enough data to cover the battery term

term: t.Optional[float]

The number of years this specific battery will be active.

When multiple batteries are given in MultiStorageInputs.batteries, this parameter is required and used to specify replacement/augmentation
In this case, the total of all battery terms needs to match the timespan of PVStorageModel.energy_prices or StandaloneStorageModel.energy_prices
Only optional if a single battery is specified in MultiStorageInputs.batteries. In this case the term is assumed to be equivalent to the project term

class EnergyStrategy(*values)

Enum for specifying energy market participation strategy

da = 'DA': Make quantity-only bids into the day-ahead market and do not bid into the real-time market. Real-time participation will only cover day-ahead bids, but resource is still exposed to real-time prices if participating in ancillary/reserve markets with non-zero utilization

rt = 'RT': Make quantity-only bids into real-time market and do not bid into the day-ahead market

dart = 'DART': Make quantity-only bids into both the day-ahead and real-time markets

class OpsStrategy(*values)

fixed_energy = 'no_energy': Assume fixed awards in both energy markets. Ancillary services can still be offered.

da_qo_only = 'da_qo_only': Make quantity-only bids into the day-ahead energy and ancillary markets and do not bid into the real-time market. Real-time participation will only cover day-ahead bids, but resource is still exposed to real-time prices if participating in ancillary/reserve markets with non-zero utilization.

rt_qo_only = 'rt_qo_only': Make quantity-only bids into the real-time market and do not bid into the day-ahead market.

dart_qo = 'dart_qo': Make quantity-only bids into both the day-ahead and real-time markets.

dart_pq_qo = 'dart_pq_qo': Price-quantity bid-offers in DAM with quantity-only bid-offers in RTM

rt_redispatch_qo = 'rt_redispatch_qo': Quantity-only RTM bid-offers with DA & ancillaries already awarded.

rt_redispatch_qo_rtcb = 'rt_redispatch_qo_rtcb': Quantity-only RTM bid-offers with DA & ancillaries already awarded. The AS day-ahead obligations are treated as financial obligations only. They are not physically enforced.

class PublicOpsStrategy(*values)

class StorageSolverOptions(*, cycling_cost_adder: float = 0.0, annual_cycle_limit: float | None = None, disable_intra_interval_variation: bool = True, window: int | None = None, step: int | None = None, flexible_solar: bool = False, symmetric_reg: Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, energy_strategy: EnergyStrategy | MarketConfig | PublicOpsStrategy | None = None, dart: Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, uncertain_soe: bool = True, dam_annual_cycle_limit: float | None = None, no_virtual_trades: Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, minimum_dam_coverage_fraction: Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, initial_soe: float | BoundedFloat = 0.0, duration_requirement_on_discharge: bool = True, no_stop_offers: bool = False, solver_config: StrictSolverConfig = StrictSolverConfig(time_limit=8.0, mip_gap_rel_tolerance=0.0, mip_gap_abs_tolerance=0.0, verbose=False, presolve=True), robust_range_initial_soe: bool = False, rtm_bp_tol: float | None = None, rtm_bp_curtailable: bool = True)

Inputs related to BESS market participation and optimization

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

cycling_cost_adder: float

A hurdle rate to add costs in the optimization framework to reduce cycling. This value is often set at around the Variable O&M cost or the expected cost of degradation.

Units: $/MWh
Example value: $15/MWh

annual_cycle_limit: t.Optional[float]

The maximum number of complete cycles per year. A cycle is measured as the throughput equivalent of the energy capacity fully charging and discharging.

Units: N/A
Example value: 250

window: t.Optional[int]

The number of time intervals that the optimization framework has knowledge of with respect to constraints. The optimization is rolling and optimizes for each step with the benefit of foresight into the broader window.

Default value: 24 (for a single day) for hourly runs

step: t.Optional[int]

The number of intervals of a single optimization period.

For example: for the default hourly run, a step of 24 means the optimization sets charge and discharge schedules for a single day.
Default value: 24 (for a single day) for hourly runs

flexible_solar: bool

Whether or not to include solar curtailment in Ancillary Services offers. Only relevant for PVStorageModel simulations

True will allow for solar bids into AS markets
False will not. Ancillary Service participation will come exclusively from the battery in this scenario.

symmetric_reg: Annotated[bool | None, get_deprecator('symmetric_reg is deprecated and will be removed in the future. Use SymmetricReserveMarket instead.')]

Deprecated, specify SymmetricReserveMarket in reserve_markets instead.

Whether or not regulation markets are symmetric. This will depend on the market you are participating in.

If True, ReserveMarkets.up and ReserveMarkets.down must contain "reg_up" and "reg_down" items respectively. Their prices must also be equivalent.

energy_strategy: t.Optional[t.Union[EnergyStrategy, MarketConfig, PublicOpsStrategy]]: Specifies energy market participation strategy

dart: Annotated[bool | None, get_deprecator('dart is deprecated and will be removed in the future. Use energy_strategy instead.')]

Deprecated, use energy_strategy to specify co-optimization

Whether or not to include DA/RT co-optimization in the Energy Markets

Default value: False

minimum_dam_coverage_fraction: Annotated[float, Field(ge=0.0, le=1.0)]

Whether or not virtual trades should be considered during DA/RT co-optimization

Only relevant if energy_strategy is dart
Requires that PVStorageModel.energy_prices/StandaloneStorageModel.energy_prices is type DARTPrices
If False, real-time participation (i.e actual charge and discharge) is not required to cover day-ahead bids. Instead the optimizer assumes day-ahead bids can also be covered by buying energy in the real-time market. With perfect foresight of DA and RT prices, this approach seems highly lucrative, but doesn’t reflect price uncertainty during actual operation and the associated level of market exposure
If True, real-time participation is required to cover day-ahead market bids, but can participate beyond that. May still require real-time energy buys if participating in ancillary/reserve markets with non-zero utilization

initial_soe: t.Union[float, BoundedFloat]

State-of-Energy of BESS at beginning of simulation

Units: kWh

duration_requirement_on_discharge: bool: Whether ReserveMarket.duration_requirement applies to the entire reserve offer, or just the discharge side of the offer. ERCOT currently only constrains the discharge side. This means that if a BESS is offering to reduce the amount it is charging (rather than increasing the amount it is discharging) the offer will not be subject to the duration requirement.

no_stop_offers: bool: Whether or not reserve capacity can be called against a base point in the opposite direction. By default, if the battery is discharging, it can be called via a reg down award to discharge less (aka to “stop”). Setting no_stop_offers=True prevents this, such that battery cannot simultaneously have a discharging base point and a downward reserves award, nor a charging base point with an upward reserves award. This hurts the battery’s ability to profit off of reserve markets, but makes for more conservative RT behavior.

rtm_bp_tol: t.Optional[float]: The tolerance in kW within which the optimizer will keep the RTM base point despite solar uncertainty. This is only applicable when using uncertain solar.

classmethod coerce_virtual_trades(values: dict) → dict: Coerce old no_virtual_trades into new minimum_dam_coverage_fraction

class MultiStorageInputs(*, cycling_cost_adder: float = 0.0, annual_cycle_limit: float | None = None, disable_intra_interval_variation: bool = True, window: int | None = None, step: int | None = None, flexible_solar: bool = False, symmetric_reg: ~typing.Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, energy_strategy: ~generation_models.generation_models.EnergyStrategy | ~generation_models.generation_models.MarketConfig | ~generation_models.generation_models.PublicOpsStrategy | None = None, dart: ~typing.Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, uncertain_soe: bool = True, dam_annual_cycle_limit: float | None = None, no_virtual_trades: ~typing.Annotated[bool | None, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.get_deprecator.<locals>.warn_deprecation_on_instantiation, json_schema_input_type=PydanticUndefined)] = None, minimum_dam_coverage_fraction: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1.0)] = 0.0, initial_soe: float | ~generation_models.generation_models.BoundedFloat = 0.0, duration_requirement_on_discharge: bool = True, no_stop_offers: bool = False, solver_config: ~generation_models.generation_models.StrictSolverConfig = StrictSolverConfig(time_limit=8.0, mip_gap_rel_tolerance=0.0, mip_gap_abs_tolerance=0.0, verbose=False, presolve=True), robust_range_initial_soe: bool = False, rtm_bp_tol: float | None = None, rtm_bp_curtailable: bool = True, batteries: ~typing.List[~generation_models.generation_models.BatteryParams])

Inputs related to BESS design, market participation and optimization

classmethod coerce_virtual_trades(values: dict) → dict: Coerce old no_virtual_trades into new minimum_dam_coverage_fraction

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

cycling_cost_adder

A hurdle rate to add costs in the optimization framework to reduce cycling. This value is often set at around the Variable O&M cost or the expected cost of degradation.

Units: $/MWh
Example value: $15/MWh

annual_cycle_limit

The maximum number of complete cycles per year. A cycle is measured as the throughput equivalent of the energy capacity fully charging and discharging.

Units: N/A
Example value: 250

window

The number of time intervals that the optimization framework has knowledge of with respect to constraints. The optimization is rolling and optimizes for each step with the benefit of foresight into the broader window.

Default value: 24 (for a single day) for hourly runs

step

The number of intervals of a single optimization period.

For example: for the default hourly run, a step of 24 means the optimization sets charge and discharge schedules for a single day.
Default value: 24 (for a single day) for hourly runs

flexible_solar

Whether or not to include solar curtailment in Ancillary Services offers. Only relevant for PVStorageModel simulations

True will allow for solar bids into AS markets
False will not. Ancillary Service participation will come exclusively from the battery in this scenario.

symmetric_reg

Deprecated, specify SymmetricReserveMarket in reserve_markets instead.

Whether or not regulation markets are symmetric. This will depend on the market you are participating in.

If True, ReserveMarkets.up and ReserveMarkets.down must contain "reg_up" and "reg_down" items respectively. Their prices must also be equivalent.

energy_strategy: Specifies energy market participation strategy

dart

Deprecated, use energy_strategy to specify co-optimization

Whether or not to include DA/RT co-optimization in the Energy Markets

Default value: False

minimum_dam_coverage_fraction

Whether or not virtual trades should be considered during DA/RT co-optimization

Only relevant if energy_strategy is dart
Requires that PVStorageModel.energy_prices/StandaloneStorageModel.energy_prices is type DARTPrices
If False, real-time participation (i.e actual charge and discharge) is not required to cover day-ahead bids. Instead the optimizer assumes day-ahead bids can also be covered by buying energy in the real-time market. With perfect foresight of DA and RT prices, this approach seems highly lucrative, but doesn’t reflect price uncertainty during actual operation and the associated level of market exposure
If True, real-time participation is required to cover day-ahead market bids, but can participate beyond that. May still require real-time energy buys if participating in ancillary/reserve markets with non-zero utilization

initial_soe

State-of-Energy of BESS at beginning of simulation

Units: kWh

duration_requirement_on_discharge: Whether ReserveMarket.duration_requirement applies to the entire reserve offer, or just the discharge side of the offer. ERCOT currently only constrains the discharge side. This means that if a BESS is offering to reduce the amount it is charging (rather than increasing the amount it is discharging) the offer will not be subject to the duration requirement.

no_stop_offers: Whether or not reserve capacity can be called against a base point in the opposite direction. By default, if the battery is discharging, it can be called via a reg down award to discharge less (aka to “stop”). Setting no_stop_offers=True prevents this, such that battery cannot simultaneously have a discharging base point and a downward reserves award, nor a charging base point with an upward reserves award. This hurts the battery’s ability to profit off of reserve markets, but makes for more conservative RT behavior.

rtm_bp_tol: The tolerance in kW within which the optimizer will keep the RTM base point despite solar uncertainty. This is only applicable when using uncertain solar.

batteries: t.List[BatteryParams]

List of BatteryParams objects that models replacement/augmentation of the BESS over a project’s life.

Each BatteryParams object is modeled for its term and then the BESS is assumed to be replaced and the SOE is assumed to be reset to initial_soe
To model a single battery over the project lifetime with no augmentation simply provide a list of length 1. In this case. term is ignored and the battery term is assumed to be equivalent to the project term.

class PeakWindow(*, mask: List[bool], price: float)

Inputs that describe peak to be reduced as part of LoadPeakReduction

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mask: t.List[bool]

Time series of boolean values where True indicates that a time intervals should be considered when calculating a peak load that will be valued at price.

List length must match RTM prices

price: float: Price to be applied to the peak load calculated for all the time intervals defined by mask

class LoadPeakReduction(*, load: List[float], max_load: List[float], seasonal_peak_windows: List[PeakWindow] = [], daily_peak_windows: List[PeakWindow] = [])

Submodel for incorporating behind the meter (BTM) peak load/demand charge reduction in the BESS optimization for the purposes of reducing demand charges.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

load: t.List[float]

The BTM load that will be subject to peak reduction as part of BESS optimization

Units: kW
Values should match the RTM price time interval and list length

max_load: t.List[float]

Similar to load but only considered during the determination of load target peaks for the seasonal_peak_windows (as opposed to in the final optimization). An actual operating project will need to define e.g. a monthly target peak at the beginning of the month, when forecast uncertainty for later in the month is high. The difference between max_load and load can be used to reflect this imperfect foresight in the determination of target peaks. E.g. max_load might be a P05 estimate compared to load being a P50.

Units: kW
Ignored unless modeling seasonal_peak_windows
Values should match the RTM price time interval and list length
Note that if both seasonal_peak_windows and daily_peak_windows are considered (such that a one-day simulation window is used) :attr:`max_load` **should be at least 1.1 times load in order to ensure optimal behavior. Please contact Tyba if more detail is needed.

seasonal_peak_windows: t.List[PeakWindow]: List of PeakWindow objects intended to represent demand charges that apply to time spans larger than the simulation window, e.g. monthly demand charges vs a 1-2 day simulation window. For each of these demand charges, prior to the main optimization calculation, a target peak is calculated that represents the maximum reduction that can be achieved for all intervals in the PeakWindow.mask. This target peak is then used in each window of the main optimization calculation. Care should be taken when transforming a tariff into seasonal_peak_windows. For example, consider a “winter on peak” monthly demand charge that applies from 6-10 and 15-19 on weekdays in months 1, 2, 3, 4, 11, and 12. This single charge would be represented by 6 PeakWindow objects, where e.g. the month 1 mask would only have True values matching the tariff schedule in month 1, and False for all time intervals in all other months.

daily_peak_windows: t.List[PeakWindow]

List of PeakWindow objects intended to represent demand charges that apply to time spans equal to the simulation window, e.g. daily demand charges and a 1 day simulation window. Unlike seasonal_peak_windows, target peaks are not calculated and the peak power in each simulation window is minimized. As such, a “winter on peak” daily demand charge that applies from 6-10 and 15-19 on weekdays in months 1, 2, 3, 4, 11, and 12 could be represented by a single PeakWindow object, where each simulation window will consider a “submask” of mask.

Note that peak reduction considers the entire simulation window, so a 2 day simulation window will minimize the peak across both days. As such, to model daily demand charges, make sure to use a one-day simulation window. See max_load for more caveats.

class PVStorageModel(*, energy_prices: ~generation_models.generation_models.DARTPrices | ~typing.List[float] | ~generation_models.generation_models.DARTPriceScenarios, storage_inputs: ~generation_models.generation_models.MultiStorageInputs, reserve_markets: ~generation_models.generation_models.ReserveMarkets | None = None, total_up_offer_cap: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0)] = None, total_down_offer_cap: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0)] = None, time_interval_mins: int = 60, load_peak_reduction: ~generation_models.generation_models.LoadPeakReduction | None = None, dam_award: ~typing.List[float] | None = None, import_limit: ~typing.List[float] | None = None, export_limit: ~typing.List[float] | None = None, project_type: ~typing.Literal['hybrid'] = 'hybrid', storage_coupling: ~generation_models.generation_models.StorageCoupling, pv_inputs: ~typing.Annotated[~generation_models.generation_models.PVGenerationModel | ~generation_models.generation_models.DCExternalGenerationModel | ~generation_models.generation_models.ACExternalGenerationModel, ~pydantic.functional_validators.BeforeValidator(func=~generation_models.generation_models.create_optionally_discriminant_union.<locals>.allow_missing_discriminator, json_schema_input_type=PydanticUndefined)], enable_grid_charge_year: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, solar_revenue_adder: ~typing.List[float] | float | None = None)

Simulation class for hybrid simulations. PVStorageModelResults is the results schema

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

import_limit

Time series of limit values to be applied to import

Power values correspond to the time interval given by time_interval_mins and the list length must match RTM prices
All values should be <= 0
Units: kW
Example values: [-1000.0, -1000.0, 0, 0,]

export_limit

Time series of limit values to be applied to export

Power values correspond to the time interval given by time_interval_mins and the list length must match RTM prices
All values should be >= 0
Units: kW
Example values: [1000.0, 1000.0, 0, 0,]

energy_prices

The energy prices used for storage dispatch optimization. This can either be a single energy price timeseries or two energy price timeseries (i.e corresponding to DA & RT markets):

Single energy market timeseries: Provide a list of prices. Prices correspond to the time interval given by time_interval_mins. The list length must match the sum of all battery terms when given in the chosen time interval. For example: if the project is a 1-year, hourly project, the list should be 8760 values long. A half-year term modeled with a time interval of 15 minutes, requires a list of 17520 energy prices.
Two energy market timeseries: Provide a DARTPrices object

storage_inputs: Submodel for BESS design, market participation and optimization

reserve_markets: A sub-model to handle the specification of reserve market/ancillary market inputs.

total_up_offer_cap

Maximum total capacity that can be offered across all upward reserve/ancillary markets combined.

This constraint applies to the sum of all upward reserve market offers (e.g., regulation up, spinning reserves, non-spinning reserves).

Units: kW

total_down_offer_cap

Maximum total capacity that can be offered across all downward reserve/ancillary markets combined.

This constraint applies to the sum of all downward reserve market offers (e.g., regulation down).

Units: kW

time_interval_mins

The number of minutes per real-time market interval.

Use 60 for an hourly run
Use 5 for a five-minute run

Note: StorageSolverOptions.window and StorageSolverOptions.step values will adjust accordingly

load_peak_reduction: A sub-model to handle the specification of load reduction inputs

project_type: t.Literal['hybrid']: Used by the API for model-type discrimination, can be ignored

storage_coupling: StorageCoupling: Specify the point at which the BESS and generation source are coupled

pv_inputs: GenerationModel: Submodel for PV or external power generation. Can be either a PVGenerationModel, DCExternalGenerationModel, or ACExternalGenerationModel instance

enable_grid_charge_year: Annotated[t.Optional[float], Field(ge=0)]

The time in years after which grid-charging becomes allowed. The default None disallows grid-charging for the entirety of the simulation. This value is 0-indexed, i.e., a value of 5 will enable grid-charging at the start of the 6th year.

Examples: - To allow grid-charging from the beginning of the term, set this to 0. - To disallow grid-charging for the entirety of the term, leave this set to None (the default). - To enable grid-charging after the project has been running for 5 years (at the start of the 6th year), set this to 5. - To enable grid-charging after the project has been running for 6 months, set this value to 0.5.

solar_revenue_adder: t.Optional[t.Union[t.List[float], float]]

Price (or prices) to be assigned as additional revenue earned by solar. Can be used to model Renewable Energy Credit (REC) revenue or Production Tax Credit (PTC) revenue.

Can be either a single price (applied uniformly to all time steps) or a list of prices
If provided as a list, prices correspond to the time interval given by time_interval_mins and the list length must match the sum of all battery terms when given in the chosen time interval.

property project_term: int: Equivalent to e.g. PVGenerationModel.project_term provided in pv_inputs

property project_term_units: TermUnits: Equivalent to PVGenerationModel.project_term_units provided in pv_inputs

class StandaloneStorageModel(*, energy_prices: DARTPrices | List[float] | DARTPriceScenarios, storage_inputs: MultiStorageInputs, reserve_markets: ReserveMarkets | None = None, total_up_offer_cap: Annotated[float | None, Gt(gt=0)] = None, total_down_offer_cap: Annotated[float | None, Gt(gt=0)] = None, time_interval_mins: int = 60, load_peak_reduction: LoadPeakReduction | None = None, dam_award: List[float] | None = None, import_limit: List[float] | None = None, export_limit: List[float] | None = None, project_term: int = 1, project_term_units: TermUnits = 'years', parallel_chunks: int | None = None, project_type: Literal['storage'] = 'storage', downstream_system: DownstreamSystem | None = None, ambient_temp: List[float] | SolarResourceLocation | None = None)

Simulation class for standalone storage simulations. The results schema is StandaloneStorageModelWithDownstreamResults if a downstream system is specified, otherwise the schema is StandaloneStorageModelSimpleResults

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

project_term

Integer value with units given by project_term_units that defines the project term (timespan) to be simulated.

For typical-year hybrid and solar-only simulations, the year-long time series in solar_resource will be tiled to match project_term. As such, the project term must represent a number of whole years
For all other hybrid and solar-only simulations, the project term must match the timespan represented by time_interval_mins and the length of the corresponding solar resource or power time series
For standalone storage simulations, the project term must match the timespan represented by time_interval_mins and the corresponding price time series

project_term_units: Units to be applied to project_term to define the term (timespan) to be simulated. See project_term for constraints

import_limit

Time series of limit values to be applied to import

Power values correspond to the time interval given by time_interval_mins and the list length must match RTM prices
All values should be <= 0
Units: kW
Example values: [-1000.0, -1000.0, 0, 0,]

export_limit

Time series of limit values to be applied to export

Power values correspond to the time interval given by time_interval_mins and the list length must match RTM prices
All values should be >= 0
Units: kW
Example values: [1000.0, 1000.0, 0, 0,]

energy_prices

The energy prices used for storage dispatch optimization. This can either be a single energy price timeseries or two energy price timeseries (i.e corresponding to DA & RT markets):

Single energy market timeseries: Provide a list of prices. Prices correspond to the time interval given by time_interval_mins. The list length must match the sum of all battery terms when given in the chosen time interval. For example: if the project is a 1-year, hourly project, the list should be 8760 values long. A half-year term modeled with a time interval of 15 minutes, requires a list of 17520 energy prices.
Two energy market timeseries: Provide a DARTPrices object

storage_inputs: Submodel for BESS design, market participation and optimization

reserve_markets: A sub-model to handle the specification of reserve market/ancillary market inputs.

total_up_offer_cap

Maximum total capacity that can be offered across all upward reserve/ancillary markets combined.

This constraint applies to the sum of all upward reserve market offers (e.g., regulation up, spinning reserves, non-spinning reserves).

Units: kW

total_down_offer_cap

Maximum total capacity that can be offered across all downward reserve/ancillary markets combined.

This constraint applies to the sum of all downward reserve market offers (e.g., regulation down).

Units: kW

time_interval_mins

The number of minutes per real-time market interval.

Use 60 for an hourly run
Use 5 for a five-minute run

Note: StorageSolverOptions.window and StorageSolverOptions.step values will adjust accordingly

load_peak_reduction: A sub-model to handle the specification of load reduction inputs

parallel_chunks: t.Optional[int]: Number of parallel chunks to use for the simulation

project_type: t.Literal['storage']: Used by the API for model-type discrimination, can be ignored

downstream_system: t.Optional[DownstreamSystem]: Optional submodel for detailed treatment of losses. The point at which detailed losses are considered can be controlled with DownstreamSystem.model_losses_from

ambient_temp: t.Optional[t.Union[t.List[float], SolarResourceLocation]]

Optional ambient temperature data to be used with BatteryParams.hvac. Can take multiple argument types:

A time-series list of ambient temperature with length equivalent to the real-time market time-series in energy_prices
A SolarResourceLocation object. With this type, Tyba will pull TY ambient temperature data from the NSRDB and use it in the simulation. As such, additional requirements are placed on the data in energy_prices and project_term:
- The data in energy_prices must represent a period starting in the 0th hour of January 1st (to align with the pulled ambient temperature data)
- project_term must be equivalent to a number of whole years (so that the ambient temperature data can be tiled to match)
Units: °C

class ResultsFormat(*values)

Desired format in which simulation results will be stored and returned

v0 = 'v0': Default return format, see e.g. GenerationModelResults

v1 = 'v1'

Also known as bus format, similar to v0 but time_series power flow data is formatted as a dict with tuple keys

first key element approximately represents the associated hardware component and the second element indicates the signal name, e.g. (“inverter”, “clipping_loss_kW”) or (“mv_bus”, “power_kW”).
Inspection of returned result is required.

v2 = 'v2': Nested time series format, see e.g. GenerationModelResults

Results Schemas

V0 Results Schema (v0 format)

generation_models.v0_output_schema.

class SolarTimeSeries(*, ideal_tracker_rotation: list | None = None, front_total_poa: list | None = None, rear_total_poa: list | None = None, effective_total_poa: list | None = None, array_dc_snow_loss: list | None = None, array_gross_dc_power: list | None = None, array_dc_power: list | None = None, array_dc_voltage: list | None = None, inverter_mppt_dc_voltage: list | None = None, inverter_mppt_loss: list | None = None, inverter_clipping_loss: list | None = None, inverter_night_tare_loss: list | None = None, inverter_power_consumption_loss: list | None = None, inverter_efficiency: list | None = None, ambient_temp: list | None = None, gross_ac_power: list, mv_transformer_loss: list | None = None, mv_transformer_load_loss: list | None = None, mv_transformer_no_load_loss: list | None = None, mv_ac_power: list, ac_wiring_loss: list, hv_transformer_loss: list | None = None, hv_transformer_load_loss: list | None = None, hv_transformer_no_load_loss: list | None = None, transformer_load_loss: list, transformer_no_load_loss: list, hv_ac_power: list, ac_transmission_loss: list, gen: list, poi_unadjusted: list, system_power: list, positive_system_power: list, negative_system_power: list, curtailed_system_power: list | None = None, net_system_power: list | None = None, net_positive_system_power: list | None = None, sam_design_parameters: dict)

Time series results for PV/Generation-only simulations or for the PV-only sub-simulation of a hybrid simulation

ideal_tracker_rotation: t.Optional[list]

Ideal or “true”-tracking angle for single axis tracking systems.

Units: degrees with horizontal equal to 0°
For backtracking systems this angle will differ from the actual tracker angle
Only generated for PVGenerationModel simulations where PVGenerationModel.system_design.tracking is a SingleAxisTracking instance

front_total_poa: t.Optional[list]

Total plane of array (POA) irradiance that strikes the front face of the PV array after accounting for shading, soiling and incidence angle modifier (IAM) losses

Units: W/m²
Only generated for PVGenerationModel simulations

rear_total_poa: t.Optional[list]

Total plane of array (POA) irradiance that strikes the rear face of the PV array after accounting for rear irradiance losses (as defined by the rear_irradiance input and incidence angle modifier (IAM) losses

Units: W/m²
Only generated for PVGenerationModel simulations where PVGenerationModel.pv_module.bifacial is True

effective_total_poa: t.Optional[list]

Total plane of array (POA) irradiance available to the PV array for conversion to electrical power. Includes front-side and rear-side contributions for bifacial systems but also accounts for the bifaciality factor, such that

$POA_{eff\_total} = POA_{front\_total} + bifaciality * POA_{rear\_total}$

Units: W/m²
Only generated for PVGenerationModel simulations

array_dc_snow_loss: t.Optional[list]

Loss due to build up of snow on solar array. Modeled as a DC power reduction (as opposed to e.g. a reduction in irradiance) and applied just before the conversion to AC power.

Units: kW
Only non-zero if PVGenerationModel.losses.enable_snow_model is True
Only generated for PVGenerationModel simulations

array_gross_dc_power: t.Optional[list]

DC power generated by the PV array after modeling irradiance-to-power conversion and time varying losses (e.g. array_dc_snow_loss), but before modeling constant derate factors (e.g. lid loss)

Units: kW
Only generated for PVGenerationModel simulations

array_dc_power: t.Optional[list]

DC power generated by the PV array (or other generation source) at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (e.g. the combined inverter inputs).

Units: kW
Represents the maximum power point (MPP) power of the array (constrained by the inverter MPP tracking voltage window). It does not represent the reduced DC power that results from inverter clipping. As such, it is equivalent to PVSyst’s EArrayMPP and not EArray
Only generated for PVGenerationModel or DCExternalGenerationModel simulations
For DCExternalGenerationModel simulations this is equivalent to the provided DCExternalGenerationModel.production_override.power

array_dc_voltage: t.Optional[list]

DC voltage generated by the PV array (or other generation source) at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs).

Units: V
Only generated for PVGenerationModel or DCExternalGenerationModel simulations
For DCExternalGenerationModel simulations this is equivalent to the provided DCExternalGenerationModel.production_override.voltage

inverter_mppt_dc_voltage: t.Optional[list]

Deprecated, instead use array_dc_voltage.

Units: V
Only generated for PVGenerationModel simulations

inverter_mppt_loss: t.Optional[list]

Loss due to operating at the edges of the maximum power point (MPP) voltage window, i.e. off of the MPP. Applied just after the irradiance-to-power conversion.

Units: kW
Only generated for PVGenerationModel simulations

inverter_clipping_loss: t.Optional[list]

Loss due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_night_tare_loss: t.Optional[list]

Loss due to inverter standby power draw, applied when the input DC power is below the turn on threshold

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_power_consumption_loss: t.Optional[list]

Loss due to inverter power consumption during operation, applied when the input DC power is above the turn on threshold. Note that depending on the inverter model used, there is a different relationship to inverter_efficiency. For the CEC inverter model (Inverter class), the efficiency includes the consumption loss. For the OND inverter model (ONDInverter class), the consumption loss depends on the aux_loss input and is applied after conversion and clipping.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_efficiency: t.Optional[list]

Inverter conversion (DC to AC) efficiency. Does not include clipping effects, which are returned separately as inverter_clipping_loss.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

ambient_temp: t.Optional[list]

Ambient Temperature. This is provided as a convenience for simulations where Tyba pulls a solar resource dataset based on project location. If ambient temperature was provided as part of a solar resource or external generation dataset, this will be equivalent.

Units: °C

gross_ac_power: list

AC power at the combined inverter outputs. For ACExternalGenerationModel simulations, it is equivalent to mv_ac_power and can be ignored.

Units: kW

mv_transformer_loss: t.Optional[list]

Total loss due to operation of a medium voltage (MV) transformer, the sum of mv_transformer_load_loss and mv_transformer_no_load_loss.

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_transformer_load_loss: t.Optional[list]

Load-dependent loss due to operation of medium voltage (MV) transformer (coil losses). Depends on load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_transformer_no_load_loss: t.Optional[list]

Constant loss due to operation of medium voltage (MV) transformer (core losses). Depends on no_load_loss factor

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_ac_power: list

Total AC power at medium voltage (MV) AC bus, e.g. the panel that collects all of the MV transformer outputs

Units: kW
For ACExternalGenerationModel simulations this is equivalent to the provided ACExternalGenerationModel.production_override.power

ac_wiring_loss: list

Loss due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear. Depends on ac_wiring input.

Units: kW

hv_transformer_loss: t.Optional[list]

Total loss due to operation of high voltage (HV) transformer (i.e. a GSU or substation), the sum of hv_transformer_load_loss and hv_transformer_no_load_loss.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

hv_transformer_load_loss: t.Optional[list]

Load-dependent loss (coil losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

hv_transformer_no_load_loss: t.Optional[list]

Constant loss (core losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on no_load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

transformer_load_loss: list

Deprecated, see hv_transformer_load_loss.

Units: kW
If e.g. PVGenerationModel.losses.hv_transformer is None, will be all zeros.

transformer_no_load_loss: list

Deprecated, see hv_transformer_no_load_loss.

Units: kW
If e.g. PVGenerationModel.losses.hv_transformer is None, will be all zeros.

hv_ac_power: list

Total AC power measured at the switchgear/project boundary. This point is also defined as the high voltage (HV) bus because if a high voltage transformer/GSU/substation is modeled, this corresponds to the HV transformer output.

Units: kW

ac_transmission_loss: list

Loss due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI). Depends on transmission input

Units: kW

gen: list

Power at the point of interconnection (POI), prior to clipping the values to the limit defined by e.g. PVGenerationModel.system_design.poi_limit

Units: kW

poi_unadjusted: list

Power at the point of interconnection (POI), after applying POI clipping but before applying the user-defined poi_adjustment

Units: kW

system_power: list

Power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kW

positive_system_power: list

Positive-only values of system_power time series, where negative values have been set to zero. Useful when trying to quantify AC solar generation or if, for example, power drawn from the grid (inverter standby) is valued at a different price than generated power

Units: kW

negative_system_power: list

Negative-only values of system_power time series, where positive values have been set to zero. Useful if, for example, power drawn from the grid (inverter standby) is valued at a different price than generated power

Units: kW

curtailed_system_power: t.Optional[list]

net_system_power: t.Optional[list]

net_positive_system_power: t.Optional[list]

sam_design_parameters: dict

Dict of raw PySAM inputs. As such, variable names will not correspond to those used in the Tyba model schema, but it can be useful for understanding very specific settings used in the PV simulation. See SAM documentation (link above) for more details.

Only non-empty for PVGenerationModel simulations

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

class SolarWaterfall(*, gh_ann: float | None = None, nominal_poa_ann: float | None = None, shading_lp: float | None = None, soiling_lp: float | None = None, reflection_lp: float | None = None, bifacial_lp: float | None = None, dc_nominal_ann: float | None = None, snow_lp: float | None = None, module_temp_lp: float | None = None, mppt_lp: float | None = None, mismatch_lp: float | None = None, diodes_lp: float | None = None, dc_wiring_lp: float | None = None, tracking_error_lp: float | None = None, mppt_error_lp: float | None = None, nameplate_lp: float | None = None, dc_optimizer_lp: float | None = None, dc_avail_lp: float | None = None, dc_net_ann: float | None = None, inverter_clipping_lp: float | None = None, inverter_consumption_lp: float | None = None, inverter_nightcons_lp: float | None = None, inverter_efficiency_lp: float | None = None, ac_gross_ann: float, mv_transformer_lp: float, ac_wiring_lp: float, hv_transformer_lp: float, transformer_lp: float, transmission_lp: float, poi_clipping_lp: float, ac_availcurtail_lp: float, annual_energy: float)

Loss waterfall results based on the first year (8760 hours) of simulation results. For simulations of less than 1 year, the entire project_term is considered. However, due to limitations of the underlying PySAM model, waterfall items upstream of dc_net_ann will not be generated for simulations less than 1 year long.

gh_ann: t.Optional[float]

Annual Global Horizontal Irradiance. This is based on the solar_resource input and not generated directly by Tyba.

Units: Wh/m²
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

nominal_poa_ann: t.Optional[float]

Annual plane of array (POA) irradiance that strikes the front face of the PV array based solely on transposition, i.e. prior to accounting for shading, soiling and incidence angle modifier (IAM) losses. Does not include rearside irradiance for bifacial systems

Units: Wh/m²
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

shading_lp: t.Optional[float]

Annual fraction of nominal_poa_ann (front side) that is lost due to diffuse and linear beam shading, i.e. not including any DC power loss due to beam shading when true-tracking (the “electrical effect”)

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

soiling_lp: t.Optional[float]

Annual fraction of nominal_poa_ann (front side) that is lost due to soiling.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

reflection_lp: t.Optional[float]

Annual fraction of nominal_poa_ann (front side) that is lost due to reflection/incident angle modifier losses.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

bifacial_lp: t.Optional[float]

Annual fractional gain in plane of array (POA) irradiance due to irradiance that strikes the rear face of the PV array after accounting for rear irradiance losses (as defined by the rear_irradiance input) and incidence angle modifier (IAM) losses. This does not include bifaciality factor (see docs for SolarTimeSeries.rear_total_poa and SolarTimeSeries.effective_total_poa for more details).

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_nominal_ann: t.Optional[float]

Annual DC power generated by the PV array assuming all irradiance is converted to power at the STC/nominal module efficiency

Units: kWh
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

snow_lp: t.Optional[float]

Annual fraction of DC power lost due to buildup of snow on solar array.

Units: kW
Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

module_temp_lp: t.Optional[float]

Annual fraction of DC power that is lost due to operating at non-STC temperature and irradiance. Due to limitations in PySAM, this also includes the fraction of DC power lost due to beam shading when true-tracking (the “electrical effect”)

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mppt_lp: t.Optional[float]

Annual fraction of DC power lost due to operating at the edges of the maximum power point (MPP) voltage window, i.e. off of the MPP.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mismatch_lp: t.Optional[float]

Annual fraction of DC power lost due mismatch, should correspond to the mismatch input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

diodes_lp: t.Optional[float]

Annual fraction of DC power lost due resistance in the diodes and connections of the PV array, should correspond to the diodes_connections input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_wiring_lp: t.Optional[float]

Annual fraction of DC power lost due resistance in the DC wiring of the PV array, should correspond to the dc_wiring input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

tracking_error_lp: t.Optional[float]

Annual fraction of DC power lost due to tracking system error in single-axis tracking PV arrays, should correspond to the tracking_error input.

Units: unitless fraction
Will be null when PVGenerationModel.system_design.tracking is a FixedTilt instance
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mppt_error_lp: t.Optional[float]: Deprecated (as well as misnamed). Equivalent to tracking_error_lp, use that instead.

nameplate_lp: t.Optional[float]

Annual fractional impact to DC power from deviations between the nameplate module rating provided by a manufacturer and actual/tested performance, should correspond to the nameplate input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_optimizer_lp: t.Optional[float]

Annual fractional impact to DC power from dc optimizer operation, should correspond to the dc_optimizer input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_avail_lp: t.Optional[float]

Annual fractional impact of DC power adjustment (which could be used to model e.g. DC availability), should correspond to the dc_array_adjustment input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_net_ann: t.Optional[float]

Annual DC power generated by the project at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (e.g. the combined inverter inputs).

Units: kWh
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance
See the docs for SolarTimeSeries.array_dc_power or SolarStorageTimeSeries.solar_storage_dc_power for more details

inverter_clipping_lp: t.Optional[float]

Annual fraction of AC power lost due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_consumption_lp: t.Optional[float]

Annual fraction of AC power lost due to inverter power consumption during operation. See SolarTimeSeries.inverter_power_consumption_loss for how to interpret depending on inverter model.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_nightcons_lp: t.Optional[float]

Annual fraction of AC power lost due to inverter standby power draw.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_efficiency_lp: t.Optional[float]

Annual fraction of AC power lost due to conversion (DC to AC) efficiency. Does not include consumption or clipping effects, which are returned separately as inverter_consumption_lp and inverter_clipping_lp respectively.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

ac_gross_ann: float

Annual AC power at the combined inverter outputs. For simulations or* PVStorageModel.pv_inputs of type ACExternalGenerationModel this will be the first year sum of ACExternalGenerationModel.production_override.power, and mv_transformer_lp will be zero, e.g. the MV AC generation source is modeled as the output of inverters with integrated MV transformers.

Units: kWh

mv_transformer_lp: float

Annual fraction of AC power lost due to operation of a medium voltage (MV) transformer

Units: unitless fraction

ac_wiring_lp: float

Annual fraction of AC power lost due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear.

Units: unitless fraction

hv_transformer_lp: float

Annual fraction of AC power lost due to operation of a high voltage (HV) transformer (i.e. a GSU or substation)

Units: unitless fraction

transformer_lp: float

Deprecated, see :attr: hv_transformer_lp.

Units: unitless fraction

transmission_lp: float

Annual fraction of AC power lost due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI)

Units: unitless fraction

poi_clipping_lp: float

Annual fraction of AC power lost due to clipping the AC power to the limit defined by e.g. PVGenerationModel.system_design.poi_limit

Units: unitless fraction

ac_availcurtail_lp: float

Annual adjustment of AC power due to the user-defined poi_adjustment

Units: unitless fraction

annual_energy: float

Annual AC power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kWh

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SolarStorageTimeSeries(*, battery_internal_energy: list, battery_internal_energy_max: list, battery_limit: float | list, battery_output: list, excess_power_at_coupling: list, captured_excess_at_coupling: list, solar_storage_dc_voltage: list | None = None, solar_storage_dc_power: list | None = None, solar_storage_power_at_coupling: list, inverter_clipping_loss: list | None = None, inverter_tare_loss: list | None = None, inverter_parasitic_loss: list | None = None, inverter_consumption_loss: list | None = None, inverter_efficiency: list | None = None, solar_storage_gross_ac_power: list | None = None, mv_xfmr_loss: list | None = None, mv_xfmr_load_loss: list | None = None, mv_xfmr_no_load_loss: list | None = None, solar_storage_ac_power: list, solar_storage_mv_ac_power: list | None = None, hvac_loss: list | None = None, ac_wiring_loss: list | None = None, hv_xfmr_loss: list | None = None, hv_xfmr_load_loss: list | None = None, hv_xfmr_no_load_loss: list | None = None, transformer_loss: list | None = None, solar_storage_hv_ac_power: list, transmission_loss: list, solar_storage_gen: list, solar_storage_poi_unadjusted: list, solar_storage_poi: list, positive_solar_storage_poi: list, negative_solar_storage_poi: list)

Power flow-related time series results for hybrid simulations

battery_internal_energy: list

Energy stored in the BESS at the end of each time interval. Corresponds to OptimizerTimeSeries.internal_energy. Note values will be higher than the amount of usable energy in the BESS due to losses between the point of coupling and the internal structure of the cells (the idealized battery “vessel”).

Units: kWh

battery_internal_energy_max: list

Available energy capacity of the BESS. Like battery_internal_energy, values will be larger than the maximum usable capacity of the BESS. For each BESS term the starting value will be energy_capacity divided by discharge_efficiency. The values will decrease based on the specified capacity_degradation_model.

Units: kWh

battery_limit: t.Union[float, list]

Power limit applied at the point of BESS coupling. These values are based on limits and losses that occur between the point of coupling and point of interconnection (POI). For example: The POI limit, export limit, import limit, temperature-dependent inverter capacity, BESS charge and discharge specifications, and component and wiring losses.

Units: kW
In some cases, e.g. when no time-varying limits have been applied, the battery_limit is constant for all time steps and may be returned as a single value, otherwise it will be a time series.

battery_output: list

Power flow to/from the BESS at the point of coupling.

Units: kW
Positive values correspond to BESS discharge, negative values correspond to BESS charge.
Note that the relationship between battery_internal_energy and battery_output is dependent on the current BESS charge and discharge efficiency, which will vary with time if an efficiency_degradation_model has been specified

excess_power_at_coupling: list

Power flowing to the BESS point of coupling from the PV array (or other generation source) that is in excess of the battery_limit. Can be compared to both battery_limit and captured_excess_at_coupling to understand how much the BESS is improving system generation relative to a PV-only system with the same equipment/limits.

Units: kW

captured_excess_at_coupling: list

Excess power flowing to the BESS point of coupling from the PV array (or other generation source) that is used to charge the BESS. Can be compared to both battery_limit and excess_power_at_coupling to understand how much the BESS is improving system generation relative to a PV-only system with the same equipment/limits.

Units: kW

solar_storage_dc_voltage: t.Optional[list]

DC voltage at the DC bus (the point of coupling) for DC-coupled hybrid systems. This will be equivalent to PVStorageModel.solar_only.array_dc_voltage when the PV array (or other generation source) is generating. When the BESS is operating alone it will default to the inverter nominal voltage.

Units: V
Only generated when storage_coupling is dc
DC bus is the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs)

solar_storage_dc_power: t.Optional[list]

Combined DC power of the BESS and PV Array (or other generation source) at the DC bus for DC-coupled hybrid systems.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
Only generated when storage_coupling is dc
DC bus is the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs)

solar_storage_power_at_coupling: list

Combined power (DC or AC) of the BESS and PV Array (or other generation source) at the point of BESS coupling for hybrid systems.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.

inverter_clipping_loss: t.Optional[list]

Loss due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: kW
Only generated when storage_coupling is dc

inverter_tare_loss: t.Optional[list]

Loss due to inverter standby power draw, applied when the input DC power is below the turn on threshold

Units: kW
Only generated when storage_coupling is dc

inverter_parasitic_loss: t.Optional[list]

Duplicate of inverter_tare_loss

Units: kW
Only generated when storage_coupling is dc

inverter_consumption_loss: t.Optional[list]

Loss due to inverter power consumption during operation, applied when the input DC power is above the turn on threshold. Note that depending on the inverter model used, there is a different relationship to inverter_efficiency. For the CEC inverter model (Inverter class), the efficiency includes the consumption loss. For the OND inverter model (ONDInverter class), the consumption loss depends on the aux_loss input and is applied after conversion and clipping.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_efficiency: t.Optional[list]

Inverter conversion (DC to AC) efficiency. Does not include clipping effects, which are returned separately as inverter_clipping_loss.

Units: kW
Only generated when storage_coupling is dc

solar_storage_gross_ac_power: t.Optional[list]

Combined AC power of the BESS and PV Array (or other generation source) at the combined inverter outputs for DC-coupled hybrid systems.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
Only generated when storage_coupling is dc

mv_xfmr_loss: t.Optional[list]

Total loss due to operation of a medium voltage (MV) transformer, the sum of mv_xfmr_load_loss and mv_xfmr_no_load_loss.

Units: kW
Only generated when storage_coupling is dc and e.g. PVStorageModel.pv_inputs.losses.mv_transformer is not None

mv_xfmr_load_loss: t.Optional[list]

Load-dependent loss due to operation of medium voltage (MV) transformer (coil losses). Depends on load_loss factor.

Units: kW
Only generated when storage_coupling is dc and e.g. PVStorageModel.pv_inputs.losses.mv_transformer is not None

mv_xfmr_no_load_loss: t.Optional[list]

Constant loss due to operation of medium voltage (MV) transformer (core losses). Depends on no_load_loss factor

Units: kW
Only generated when storage_coupling is dc and e.g. PVStorageModel.pv_inputs.losses.mv_transformer is not None

solar_storage_ac_power: list

Equivalent to solar_storage_mv_ac_power when storage_coupling is dc or ac, equivalent to solar_storage_hv_ac_power when storage_coupling is hv_ac.

Units: kW

solar_storage_mv_ac_power: t.Optional[list]

Combined AC power of the BESS and PV Array (or other generation source) at medium voltage (MV) AC bus for hybrid systems.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
Only generated when storage_coupling is dc or ac
MV Bus is the panel that collects all of the MV transformer outputs

hvac_loss: t.Optional[list]

Losses due to BESS HVAC operation. Applied at the MV Bus when storage_coupling is dc or ac and at the HV Bus when storage_coupling is hv_ac

Units: kW
Only generated when there is a battery term with hvac as a BatteryHVACParams instance

ac_wiring_loss: t.Optional[list]

Loss due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear. Depends on ac_wiring input.

Units: kW
Only generated when storage_coupling is dc or ac

hv_xfmr_loss: t.Optional[list]

Total loss due to operation of high voltage (HV) transformer (i.e. a GSU or substation), the sum of hv_xfmr_load_loss and hv_xfmr_no_load_loss.

Units: kW
Only generated when storage_coupling is dc or ac and e.g. PVGenerationModel.losses.hv_transformer is not None

hv_xfmr_load_loss: t.Optional[list]

Load-dependent loss (coil losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on load_loss factor.

Units: kW
Only generated when storage_coupling is dc or ac and e.g. PVGenerationModel.losses.hv_transformer is not None

hv_xfmr_no_load_loss: t.Optional[list]

Constant loss (core losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on no_load_loss factor.

Units: kW
Only generated when storage_coupling is dc or ac and e.g. PVGenerationModel.losses.hv_transformer is not None

transformer_loss: t.Optional[list]

Deprecated, see :attr: hv_xfmr_loss.

Units: kW
Only generated when storage_coupling is dc or ac and e.g. PVGenerationModel.losses.hv_transformer is not None

solar_storage_hv_ac_power: list

Combined AC power of the BESS and PV Array (or other generation source) at the switchgear/project boundary. This point is also defined as the high voltage (HV) bus because if a high voltage transformer/GSU/substation is modeled, this corresponds to the HV transformer output.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
HV Bus is the measurement point at the switchgear/project boundary. If a high voltage transformer/GSU/substation is modeled, this corresponds to the HV transformer output

transmission_loss: list

Loss due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI). Depends on transmission input

Units: kW

solar_storage_gen: list

Power at the point of interconnection (POI), prior to clipping the values to the limit defined by e.g. PVGenerationModel.system_design.poi_limit

Units: kW

solar_storage_poi_unadjusted: list

Power at the point of interconnection (POI), after applying POI clipping but before applying the user-defined poi_adjustment

Units: kW

solar_storage_poi: list

Power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kW

positive_solar_storage_poi: list

Positive-only values of solar_storage_poi time series, where negative values have been set to zero.

Units: kW

negative_solar_storage_poi: list

Negative-only values of solar_storage_poi time series, where positive values have been set to zero.

Units: kW

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

class SolarStorageWaterfall(*, gh_ann: float | None = None, nominal_poa_ann: float | None = None, shading_lp: float | None = None, soiling_lp: float | None = None, reflection_lp: float | None = None, bifacial_lp: float | None = None, dc_nominal_ann: float | None = None, snow_lp: float | None = None, module_temp_lp: float | None = None, mppt_lp: float | None = None, mismatch_lp: float | None = None, diodes_lp: float | None = None, dc_wiring_lp: float | None = None, tracking_error_lp: float | None = None, mppt_error_lp: float | None = None, nameplate_lp: float | None = None, dc_optimizer_lp: float | None = None, dc_avail_lp: float | None = None, dc_net_ann: float | None = None, inverter_clipping_lp: float | None = None, inverter_consumption_lp: float | None = None, inverter_nightcons_lp: float | None = None, inverter_efficiency_lp: float | None = None, ac_gross_ann: float, mv_transformer_lp: float, ac_wiring_lp: float, hv_transformer_lp: float, transformer_lp: float, transmission_lp: float, poi_clipping_lp: float, ac_availcurtail_lp: float, annual_energy: float, battery_operation_lp: float, excess_power_at_coupling_lp: float, captured_excess_at_coupling_lp: float, bess_hvac_lp: float | None = None)

Loss waterfall results based on the first year (8760 hours) of simulation results. For simulations of less than 1 year, the entire PVStorageModel.pv_inputs.project_term is considered. However, due to limitations of the underlying PySAM model, waterfall items upstream of dc_net_ann will not be generated for simulations less than 1 year long.

battery_operation_lp: float

Annual fractional energy impact due to operation of the BESS

Units: unitless fraction

excess_power_at_coupling_lp: float

Annual fraction of power flowing to the point of BESS coupling from the PV array (or other generation source) that is in excess of the SolarStorageTimeSeries.battery_limit

Units: unitless fraction

captured_excess_at_coupling_lp: float

Annual fraction of excess power flowing to the point of BESS coupling from the PV array (or other generation source) that is used to charge the BESS.

Units: unitless fraction

bess_hvac_lp: t.Optional[float]

Annual fraction of AC power that is lost to power the BESS HVAC system.

Units: unitless fraction
Only generated when there is a battery term with hvac is a BatteryHVACParams instance

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

gh_ann

Annual Global Horizontal Irradiance. This is based on the solar_resource input and not generated directly by Tyba.

Units: Wh/m²
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

nominal_poa_ann

Annual plane of array (POA) irradiance that strikes the front face of the PV array based solely on transposition, i.e. prior to accounting for shading, soiling and incidence angle modifier (IAM) losses. Does not include rearside irradiance for bifacial systems

Units: Wh/m²
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

shading_lp

Annual fraction of nominal_poa_ann (front side) that is lost due to diffuse and linear beam shading, i.e. not including any DC power loss due to beam shading when true-tracking (the “electrical effect”)

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

soiling_lp

Annual fraction of nominal_poa_ann (front side) that is lost due to soiling.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

reflection_lp

Annual fraction of nominal_poa_ann (front side) that is lost due to reflection/incident angle modifier losses.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

bifacial_lp

Annual fractional gain in plane of array (POA) irradiance due to irradiance that strikes the rear face of the PV array after accounting for rear irradiance losses (as defined by the rear_irradiance input) and incidence angle modifier (IAM) losses. This does not include bifaciality factor (see docs for SolarTimeSeries.rear_total_poa and SolarTimeSeries.effective_total_poa for more details).

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_nominal_ann

Annual DC power generated by the PV array assuming all irradiance is converted to power at the STC/nominal module efficiency

Units: kWh
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

snow_lp

Annual fraction of DC power lost due to buildup of snow on solar array.

Units: kW
Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

module_temp_lp

Annual fraction of DC power that is lost due to operating at non-STC temperature and irradiance. Due to limitations in PySAM, this also includes the fraction of DC power lost due to beam shading when true-tracking (the “electrical effect”)

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mppt_lp

Annual fraction of DC power lost due to operating at the edges of the maximum power point (MPP) voltage window, i.e. off of the MPP.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mismatch_lp

Annual fraction of DC power lost due mismatch, should correspond to the mismatch input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

diodes_lp

Annual fraction of DC power lost due resistance in the diodes and connections of the PV array, should correspond to the diodes_connections input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_wiring_lp

Annual fraction of DC power lost due resistance in the DC wiring of the PV array, should correspond to the dc_wiring input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

tracking_error_lp

Annual fraction of DC power lost due to tracking system error in single-axis tracking PV arrays, should correspond to the tracking_error input.

Units: unitless fraction
Will be null when PVGenerationModel.system_design.tracking is a FixedTilt instance
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

mppt_error_lp: Deprecated (as well as misnamed). Equivalent to tracking_error_lp, use that instead.

nameplate_lp

Annual fractional impact to DC power from deviations between the nameplate module rating provided by a manufacturer and actual/tested performance, should correspond to the nameplate input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_optimizer_lp

Annual fractional impact to DC power from dc optimizer operation, should correspond to the dc_optimizer input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_avail_lp

Annual fractional impact of DC power adjustment (which could be used to model e.g. DC availability), should correspond to the dc_array_adjustment input.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel instance at least 1 year long

dc_net_ann

Annual DC power generated by the project at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (e.g. the combined inverter inputs).

Units: kWh
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance
See the docs for SolarTimeSeries.array_dc_power or SolarStorageTimeSeries.solar_storage_dc_power for more details

inverter_clipping_lp

Annual fraction of AC power lost due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_consumption_lp

Annual fraction of AC power lost due to inverter power consumption during operation. See SolarTimeSeries.inverter_power_consumption_loss for how to interpret depending on inverter model.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_nightcons_lp

Annual fraction of AC power lost due to inverter standby power draw.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

inverter_efficiency_lp

Annual fraction of AC power lost due to conversion (DC to AC) efficiency. Does not include consumption or clipping effects, which are returned separately as inverter_consumption_lp and inverter_clipping_lp respectively.

Units: unitless fraction
Only generated if the simulation or PVStorageModel.pv_inputs is a PVGenerationModel or DCExternalGenerationModel instance

ac_gross_ann

Annual AC power at the combined inverter outputs. For simulations or* PVStorageModel.pv_inputs of type ACExternalGenerationModel this will be the first year sum of ACExternalGenerationModel.production_override.power, and mv_transformer_lp will be zero, e.g. the MV AC generation source is modeled as the output of inverters with integrated MV transformers.

Units: kWh

mv_transformer_lp

Annual fraction of AC power lost due to operation of a medium voltage (MV) transformer

Units: unitless fraction

ac_wiring_lp

Annual fraction of AC power lost due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear.

Units: unitless fraction

hv_transformer_lp

Annual fraction of AC power lost due to operation of a high voltage (HV) transformer (i.e. a GSU or substation)

Units: unitless fraction

transformer_lp

Deprecated, see :attr: hv_transformer_lp.

Units: unitless fraction

transmission_lp

Annual fraction of AC power lost due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI)

Units: unitless fraction

poi_clipping_lp

Annual fraction of AC power lost due to clipping the AC power to the limit defined by e.g. PVGenerationModel.system_design.poi_limit

Units: unitless fraction

ac_availcurtail_lp

Annual adjustment of AC power due to the user-defined poi_adjustment

Units: unitless fraction

annual_energy

Annual AC power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kWh

class OptimizerTimeSeries(*, hvac_loss: list | None = None, import_limit_at_coupling: list | None = None, export_limit_at_coupling: list | None = None, target_load: list | None = None, charge_actual: list, discharge_actual: list, charge: list, discharge: list, charge_hi: list, discharge_hi: list, charge_lo: list, discharge_lo: list, battery_output: list, output: list, total_output: list, internal_energy: list, soe_actual: list, soe_lo: list, soe_hi: list, soe_hb_actual: list, soe_hb_lo: list, soe_hb_hi: list, soe_mean_actual: list, soe_mean_lo: list, soe_mean_hi: list, dam_charge: list | None = None, dam_discharge: list | None = None, dam_solar: list | None = None, dam_base_point: list | None = None, rtm_charge: list | None = None, rtm_discharge: list | None = None, rtm_solar: list | None = None, rtm_base_point: list | None = None, rtm_price: list | None = None, dam_price: list | None = None, imbalance: list | None = None, solar_actual: list | None = None, solar_hi: list | None = None, solar_lo: list | None = None, net_load: list | None = None, RESERVE_MARKET_price: list | None = None, RESERVE_MARKET_offer: list | None = None, RESERVE_MARKET_utilized_max: list | None = None, RESERVE_MARKET_utilized_min: list | None = None, RESERVE_MARKET_utilized_actual: list | None = None, RESERVE_MARKET_realized: list | None = None, RESERVE_MARKET_flex_offer: list | None = None, RESERVE_MARKET_flex_max: list | None = None, RESERVE_MARKET_flex_min: list | None = None, RESERVE_MARKET_flex_actual: list | None = None, RESERVE_MARKET_discharge_offer: list | None = None, RESERVE_MARKET_discharge_max: list | None = None, RESERVE_MARKET_discharge_min: list | None = None, RESERVE_MARKET_discharge_actual: list | None = None, RESERVE_MARKET_stop_charge_offer: list | None = None, RESERVE_MARKET_stop_charge_max: list | None = None, RESERVE_MARKET_stop_charge_min: list | None = None, RESERVE_MARKET_stop_charge_actual: list | None = None, RESERVE_MARKET_charge_offer: list | None = None, RESERVE_MARKET_charge_max: list | None = None, RESERVE_MARKET_charge_min: list | None = None, RESERVE_MARKET_charge_actual: list | None = None, RESERVE_MARKET_stop_discharge_offer: list | None = None, RESERVE_MARKET_stop_discharge_max: list | None = None, RESERVE_MARKET_stop_discharge_min: list | None = None, RESERVE_MARKET_stop_discharge_actual: list | None = None, **extra_data: Any)

Time series results associated with BESS optimization and operation. Note that unless otherwise specified, all time series apply at the BESS modeling boundary. For PVStorageModel simulations the BESS modeling boundary is equivalent to the point of BESS coupling. For StandaloneStorageModel simulations where downstream_system is not None the BESS modeling boundary is specified by model_losses_from. Otherwise, the BESS modeling boundary can be considered the point of interconnection (POI).

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

hvac_loss: t.Optional[list]

Losses due to BESS HVAC operation. Will only be generated as part of StandaloneStorageModelSimpleResults. In that case, will be applied at the BESS modeling boundary. For hybrid or standalone storage with downstream losses see PVStorageModelResults.solar_storage.hvac_loss or StandaloneStorageModelWithDownstreamResults.system.hvac_loss respectively.

Units: kW
Only generated when there is a battery term with hvac as a BatteryHVACParams instance

import_limit_at_coupling: t.Optional[list]

The limit defined by the import limit input (e.g. PVStorageModel.import_limit) but adjusted based on system loses to apply at the BESS modeling boundary.

Units: kW
Using convention that towards the POI/grid is positive, all values will be <= 0

export_limit_at_coupling: t.Optional[list]

The limit defined by the export limit input (e.g. PVStorageModel.export_limit but adjusted based on system loses to apply at the BESS modeling boundary.

Units: kW
Using convention that towards the POI/grid is positive, all values will be >= 0

target_load: t.Optional[list]

The lowest target load that applies for each time interval at the BESS modeling boundary in BTM simulations with monthly/seasonal demand charges. Note that for overlapping demand charges, multiple targets may apply to a given time interval but for simplicity only the lowest is reported here. See seasonal_peak_windows for more details.

Units: kW
Positive values correspond to power flowing from the POI towards the BESS modeling boundary
Only generated when e.g. StandaloneStorageModel.load_peak_reduction is not None and seasonal_peak_windows are given.

charge_actual: list

BESS charging power at the BESS modeling boundary. Represents BESS charging behavior in the base case, where reserve market utilization and PV array (or other generation) power are defined by e.g. ScalarUtilization.actual and solar_actual (if applicable).

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Represents the mean power across the time interval

discharge_actual: list

BESS discharging power at the BESS modeling boundary. Represents BESS discharging behavior in the base case, where reserve market utilization and PV array (or other generation) power are defined by e.g. ScalarUtilization.actual and solar_actual (if applicable).

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Represents the mean power across the time interval

charge: list: Duplicate of charge_actual

discharge: list: Duplicate of discharge_actual

charge_hi: list

The highest BESS charging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

discharge_hi: list

The highest BESS discharging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

charge_lo: list

The lowest BESS charging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

discharge_lo: list

The lowest BESS discharging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

battery_output: list

Power flow to/from the BESS at the BESS modeling boundary. Sum of the charge and discharge time series subject to power flow sign conventions.

Units: kW
Positive values correspond to BESS discharge, negative values correspond to BESS charge.
Note that the relationship between internal_energy and battery_output is dependent on the current BESS charge and discharge efficiency, which will vary with time if an efficiency_degradation_model has been specified

output: list: Duplicate of battery_output

total_output: list

Total power flow at the BESS modeling boundary. For PVStorageModel simulations this is the combined power from the BESS+PV (or other generation source) at the point of BESS coupling. For standalone storage simulations, will be equivalent to battery_output.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.

internal_energy: list: Duplicate of soe_actual

soe_actual: list

Realized energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_actual and discharge_actual are applied at each time interval. As such, will not start with the user-specified initial SOE (since this applies to the beginning of the first time interval). Note values will be higher than the amount of usable energy in the BESS due to all losses between the BESS modeling boundary and the internal structure of the cells (the idealized battery “vessel”).

Units: kWh

soe_lo: list

Lower bound of energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_lo and discharge_hi are applied to a beginning SOE of soe_hb_actual.

Units: kWh

soe_hi: list

Upper bound of energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_hi and discharge_lo are applied to a beginning SOE of soe_hb_actual.

Units: kWh

soe_hb_actual: list

Realized energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_actual in the previous time interval. As such, will start with the user-specified initial SOE (since this applies to the beginning of the first time interval)

Units: kWh

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

soe_hb_lo: list

Lower bound of energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_lo in the previous time interval.

Units: kWh

soe_hb_hi: list

Upper bound of energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_hi in the previous time interval.

Units: kWh

soe_mean_actual: list

Mean value of energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_actual and soe_hb_actual for each time interval.

Units: kWh

soe_mean_lo: list

Mean value of lower-bound energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_lo and soe_hb_lo for each time interval.

Units: kWh

soe_mean_hi: list

Mean value of upper-bound energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_hi and soe_hb_hi for each time interval.

Units: kWh

dam_charge: t.Optional[list]

Day Ahead Market (DAM) award component of charge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Only generated when energy_strategy is da or dart (quantity-only)

dam_discharge: t.Optional[list]

Day Ahead Market (DAM) award component of discharge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Only generated when energy_strategy is da or dart (quantity-only)

dam_solar: t.Optional[list]

Day Ahead Market (DAM) award component of solar_actual at the BESS modeling boundary.

Units: kW
Only generated for attr:~generation_models.generation_models.PVStorageModel sims where energy_strategy is da or dart (quantity-only)

dam_base_point: t.Optional[list]

Total Day Ahead Market (DAM) award at the BESS modeling boundary. Sum of the dam_charge and dam_discharge (and dam_solar for hybrid) time series, subject to power flow sign conventions.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.
Only generated when energy_strategy is da or dart (quantity-only)

rtm_charge: t.Optional[list]

Real Time Market (RTM) award component of charge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_discharge: t.Optional[list]

Real Time Market (RTM) award component of discharge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_solar: t.Optional[list]

Real Time Market (RTM) award component of solar_actual at the BESS modeling boundary.

Units: kW
Only generated for attr:~generation_models.generation_models.PVStorageModel sims where energy_strategy is rt or dart (quantity-only)

rtm_base_point: t.Optional[list]

Total Real Time Market (RTM) award at the BESS modeling boundary. Sum of the rtm_charge and rtm_discharge (and rtm_solar for hybrid) time series, subject to power flow sign conventions.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_price: t.Optional[list]: Real-time market (RTM) prices. Equivalent to the rtm input, but included in the results for convenience.

dam_price: t.Optional[list]: Day Ahead Market (DAM) prices. Equivalent to the dam input, but included in the results for convenience.

imbalance: t.Optional[list]: Imbalance market prices. Equivalent to the imbalance input, but included in the results for convenience.

solar_actual: t.Optional[list]

Realized power from the PV array (or other generation source) at the BESS modeling boundary. Will align with the given generation inputs and specifically ACProductionProfile.power.actual if modeling uncertain solar. Does not include standby losses and can further differ from its generation equivalent due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for PVStorageModel simulations

solar_hi: t.Optional[list]

Upper bound power from the PV array (or other generation source) at the BESS modeling boundary. Relevant when modeling uncertain solar, in which case it will be mostly equivalent to ACProductionProfile.power.max. Otherwise, will be equivalent to solar_actual. Can differ from its input due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for generation_models.generation_models.PVStorageModel simulations

solar_lo: t.Optional[list]

Lower bound power from the PV array (or other generation source) at the BESS modeling boundary. Relevant when modeling uncertain solar, in which case it will be mostly equivalent to ACProductionProfile.power.min. Otherwise, will be equivalent to solar_actual. Can differ from its input due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for generation_models.generation_models.PVStorageModel simulations

net_load: t.Optional[list]

The net load at the BESS modeling boundary in BTM simulations after the BESS and PV array (or other generation source) behavior is accounted for.

Units: kW
Positive values correspond to power flowing from the POI towards the BESS modeling boundary
Only generated when e.g. StandaloneStorageModel.load_peak_reduction is not None

RESERVE_MARKET_price: t.Optional[list]: PLACEHOLDER, not a real output. For each specified reserve market, a _price time series will be generated. Will match the price input but is generated for convenience

RESERVE_MARKET_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, an _offer time series will be generated. This is the power offer made in that market for each time interval (assumed to also be awarded).

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_max: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_min: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_actual time series will be generated. This is the portion of RESERVE_MARKET_offer that is modeled as called and actually impacts BESS state of energy

Units: kW
Average power over the interval

RESERVE_MARKET_realized: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, a _realized time series will be generated. This is a duplicate of RESERVE_MARKET_utilized_actual.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_offer: t.Optional[list]

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_offer time series will be generated for each specified reserve market. This is the portion of the RESERVE_MARKET_offer that will be met with flexible PV array production.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_max: t.Optional[list]

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_max time series will be generated for each specified reserve market. This is the upper-bound portion of RESERVE_MARKET_flex_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_min: t.Optional[list]

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_min time series will be generated for each specified reserve market. This is the lower-bound portion of RESERVE_MARKET_flex_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_actual: t.Optional[list]

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_actual time series will be generated for each specified reserve market. This is the portion of RESERVE_MARKET_flex_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met with BESS discharge.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_max: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_min: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_actual time series will be generated. This is the portion of RESERVE_MARKET_discharge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met by stopping/reducing BESS charging.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_max: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_stop_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_min: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_stop_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_actual time series will be generated. This is the portion of RESERVE_MARKET_stop_charge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met with BESS charge.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_max: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_min: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_actual time series will be generated. This is the portion of RESERVE_MARKET_charge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met by stopping/reducing BESS discharging.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_max: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_stop_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_min: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_stop_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_actual time series will be generated. This is the portion of RESERVE_MARKET_stop_discharge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

class MarketAwardsTimeSeries(*, charge: list, discharge: list, total_output: list, rt_tare: list, dam_charge: list, dam_discharge: list, dam_base_point: list, negative_dam_base_point: list, rtm_charge: list, rtm_discharge: list, rtm_base_point: list, solar_actual: list | None = None, dam_solar: list | None = None, rtm_solar: list | None = None, RESERVE_MARKET_offer: list | None = None, RESERVE_MARKET_realized: list | None = None, RESERVE_MARKET_flex_actual: list | None = None, RESERVE_MARKET_discharge_offer: list | None = None, RESERVE_MARKET_discharge_actual: list | None = None, RESERVE_MARKET_stop_charge_offer: list | None = None, RESERVE_MARKET_stop_charge_actual: list | None = None, RESERVE_MARKET_charge_offer: list | None = None, RESERVE_MARKET_charge_actual: list | None = None, RESERVE_MARKET_stop_discharge_offer: list | None = None, RESERVE_MARKET_stop_discharge_actual: list | None = None, **extra_data: Any)

Time series results intended to represent market awards for use in revenue calculation. Many time series differ from those in OptimizerTimeSeries because they roughly apply at the point of interconnection (POI) as opposed to the BESS modeling boundary, but their purpose is calculating revenue and they should not be treated as physical power components at the POI.

Note also that here the POI corresponds with solar_storage_poi_unadjusted or poi_unadjusted because the poi_adjustment applied downstream is intended to roughly model system availability and thus wouldn’t be considered during BESS operation/optimization

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

charge: list

Equivalent to OptimizerTimeSeries.charge_actual but corrected to represent charge power at the point of interconnection (POI).

Units: kW

discharge: list

Equivalent to OptimizerTimeSeries.discharge_actual but corrected to represent discharge power at the point of interconnection (POI).

Units: kW

total_output: list

Equivalent to solar_storage_poi_unadjusted or poi_unadjusted but with standby losses (such as those generated by inverters or transformers) removed. While these point of interconnection (POI) loads might be settled in the wholesale market they are not treated as part of offers and thus not part of any awards.

Units: kW
All values will be >= 0

rt_tare: list

Net standby losses at the point of interconnection (POI), i.e. the difference between e.g. poi_unadjusted and total_output. These might be charged the real time market (RTM) price or perhaps e.g. some retail energy price.

Units: kW
All values will be <= 0

dam_charge: list

Equivalent to OptimizerTimeSeries.dam_charge but corrected to represent settlement at the point of interconnection (POI).

Units: kW

dam_discharge: list

Equivalent to OptimizerTimeSeries.dam_discharge but corrected to represent settlement at the point of interconnection (POI).

Units: kW

dam_base_point: list

Equivalent to OptimizerTimeSeries.dam_base_point but corrected to represent settlement at the point of interconnection (POI).

Units: kW

negative_dam_base_point: list

Negative of dam_base_point.

Units: kW

rtm_charge: list

Equivalent to OptimizerTimeSeries.rtm_charge but corrected to represent settlement at the point of interconnection (POI).

Units: kW

rtm_discharge: list

Equivalent to OptimizerTimeSeries.rtm_discharge but corrected to represent settlement at the point of interconnection (POI).

Units: kW

rtm_base_point: list

Equivalent to OptimizerTimeSeries.rtm_base_point but corrected to represent settlement at the point of interconnection (POI).

Units: kW

solar_actual: t.Optional[list]

Equivalent to OptimizerTimeSeries.solar_actual but corrected to represent settlement at the point of interconnection (POI).

Units: kW
For hybrid systems, does not always represent the fraction of solar_storage_poi_unadjusted attributable to PV generation (or other generation). It is simply the PV power at the point of BESS coupling derated to represent POI power, inline with how most markets treat hybrid assets. For example, if the PV is charging the BESS and exporting to the grid solar_actual will reflect both flows, not just the exporting flow that actually reaches the POI.

dam_solar: t.Optional[list]

Equivalent to OptimizerTimeSeries.dam_solar but corrected to represent settlement at the point of interconnection (POI).

Units: kW
See solar_actual for hybrid gotchas

rtm_solar: t.Optional[list]

Equivalent to OptimizerTimeSeries.rtm_solar but corrected to represent settlement at the point of interconnection (POI).

Units: kW
See solar_actual for hybrid gotchas

RESERVE_MARKET_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, an _offer time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_offer since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_realized: t.Optional[list]

PLACEHOLDER, not a real output. For each specified reserve market, a _realized time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_realized since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_flex_actual: t.Optional[list]

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_actual time series will be generated for each specified reserve market. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_flex_actual since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_discharge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_offer time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_discharge_offer since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_discharge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_actual time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_discharge_actual since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_stop_charge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_offer time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_stop_charge_offer since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_stop_charge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_actual time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_stop_charge_actual since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_charge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_offer time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_charge_offer since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_charge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_actual time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_charge_actual since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_stop_discharge_offer: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_offer time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_stop_discharge_offer since reserve markets settle at BESS meters.

Units: kW

RESERVE_MARKET_stop_discharge_actual: t.Optional[list]

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_actual time series will be generated. Equivalent to OptimizerTimeSeries.RESERVE_MARKET_stop_discharge_actual since reserve markets settle at BESS meters.

Units: kW

class StandaloneStorageSystemTimeSeries(*, battery_internal_energy: list, battery_internal_energy_max: list, battery_limit: float | list, battery_output: list, dc_power: list | None = None, dc_voltage: list | None = None, inverter_clipping_loss: list | None = None, inverter_tare_loss: list | None = None, inverter_parasitic_loss: list | None = None, inverter_consumption_loss: list | None = None, inverter_efficiency: list | None = None, gross_ac_power: list | None = None, mv_xfmr_loss: list | None = None, mv_xfmr_load_loss: list | None = None, mv_xfmr_no_load_loss: list | None = None, ac_power: list, mv_ac_power: list | None = None, hvac_loss: list | None = None, ac_wiring_loss: list | None = None, hv_xfmr_loss: list | None = None, hv_xfmr_load_loss: list | None = None, hv_xfmr_no_load_loss: list | None = None, transformer_loss: list | None = None, hv_ac_power: list, transmission_loss: list, gen: list, poi_unadjusted: list, poi: list, positive_poi: list, negative_poi: list)

Time series results for standalone storage simulations where downstream_system is not None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

battery_internal_energy: list

Energy stored in the BESS at the end of each time interval. Corresponds to OptimizerTimeSeries.internal_energy. Note values will be higher than the amount of usable energy in the BESS due to losses between the point of coupling and the internal structure of the cells (the idealized battery “vessel”).

Units: kWh

battery_internal_energy_max: list

Available energy capacity of the BESS. Like battery_internal_energy, values will be larger than the maximum usable capacity of the BESS. For each BESS term the starting value will be energy_capacity divided by discharge_efficiency. The values will decrease based on the specified capacity_degradation_model.

Units: kWh

battery_limit: t.Union[float, list]

Power limit applied at the point of BESS coupling. These values are based on limits and losses that occur between the point of coupling and point of interconnection (POI). For example: The POI limit, export limit, import limit, temperature-dependent inverter capacity, BESS charge and discharge specifications, and component and wiring losses.

Units: kW
In some cases, e.g. when no time-varying limits have been applied, the battery_limit is constant for all time steps and may be returned as a single value, otherwise it will be a time series.

battery_output: list

Power flow to/from the BESS at the point of coupling.

Units: kW
Positive values correspond to BESS discharge, negative values correspond to BESS charge.
Note that the relationship between battery_internal_energy and battery_output is dependent on the current BESS charge and discharge efficiency, which will vary with time if an efficiency_degradation_model has been specified

dc_power: t.Optional[list]

DC power at the DC bus.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
Only generated when model_losses_from is DC
DC bus is the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs)

dc_voltage: t.Optional[list]

DC voltage at the DC bus. Will default to the inverter nominal voltage when the BESS is operating.

Units: V
Only generated when model_losses_from is DC
DC bus is the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs)

inverter_clipping_loss: t.Optional[list]

Loss due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: kW
Only generated when model_losses_from is DC

inverter_tare_loss: t.Optional[list]

Loss due to inverter standby power draw, applied when the input DC power is below the turn on threshold

Units: kW
Only generated when model_losses_from is DC

inverter_parasitic_loss: t.Optional[list]

Duplicate of inverter_tare_loss

Units: kW
Only generated when model_losses_from is DC

inverter_consumption_loss: t.Optional[list]

Loss due to inverter power consumption during operation, applied when the input DC power is above the turn on threshold. Note that depending on the inverter model used, there is a different relationship to inverter_efficiency. For the CEC inverter model (Inverter class), the efficiency includes the consumption loss. For the OND inverter model (ONDInverter class), the consumption loss depends on the aux_loss input and is applied after conversion and clipping.

Units: kW
Only generated when model_losses_from is DC

inverter_efficiency: t.Optional[list]

Inverter conversion (DC to AC) efficiency. Does not include clipping effects, which are returned separately as inverter_clipping_loss.

Units: kW
Only generated when model_losses_from is DC

gross_ac_power: t.Optional[list]

AC power at the combined inverter outputs.

Units: kW
Positive values correspond to power flowing towards the POI, negative values correspond to power flowing away from the POI.
Only generated when model_losses_from is DC

mv_xfmr_loss: t.Optional[list]

Total loss due to operation of a medium voltage (MV) transformer, the sum of mv_xfmr_load_loss and mv_xfmr_no_load_loss.

Units: kW
Only generated when model_losses_from is DC and StandaloneStorageModel.downstream_system.losses.mv_transformer is not None

mv_xfmr_load_loss: t.Optional[list]

Load-dependent loss due to operation of medium voltage (MV) transformer (coil losses). Depends on load_loss factor.

Units: kW
Only generated when model_losses_from is DC and StandaloneStorageModel.downstream_system.losses.mv_transformer is not None

mv_xfmr_no_load_loss: t.Optional[list]

Constant loss due to operation of medium voltage (MV) transformer (core losses). Depends on no_load_loss factor

Units: kW
Only generated when model_losses_from is DC and StandaloneStorageModel.downstream_system.losses.mv_transformer is not None

ac_power: list

Equivalent to mv_ac_power when model_losses_from is DC or MV, equivalent to hv_ac_power when model_losses_from is HV.

Units: kW

mv_ac_power: t.Optional[list]

Total AC power at medium voltage (MV) AC bus, e.g. the panel that collects all of the MV transformer outputs

Units: kW

hvac_loss: t.Optional[list]

Losses due to BESS HVAC operation. Applied at the MV Bus when model_losses_from is DC or MV and at the HV Bus when model_losses_from is HV

Units: kW
Only generated when there is a battery term with hvac as a BatteryHVACParams instance

ac_wiring_loss: t.Optional[list]

Loss due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear. Depends on ac_wiring input.

Units: kW
Only generated when model_losses_from is DC or MV

hv_xfmr_loss: t.Optional[list]

Total loss due to operation of high voltage (HV) transformer (i.e. a GSU or substation), the sum of hv_xfmr_load_loss and hv_xfmr_no_load_loss.

Units: kW
Only generated when model_losses_from is DC or MV and hv_transformer is not None

hv_xfmr_load_loss: t.Optional[list]

Load-dependent loss (coil losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on load_loss factor.

Units: kW
Only generated when model_losses_from is DC or MV and hv_transformer is not None

hv_xfmr_no_load_loss: t.Optional[list]

Constant loss (core losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on no_load_loss factor.

Units: kW
Only generated when model_losses_from is DC or MV and hv_transformer is not None

transformer_loss: t.Optional[list]

Deprecated, see :attr: hv_xfmr_loss.

Units: kW
Only generated when model_losses_from is DC or MV and hv_transformer is not None

hv_ac_power: list

Total AC power measured at the switchgear/project boundary. This point is also defined as the high voltage (HV) bus because if a high voltage transformer/GSU/substation is modeled, this corresponds to the HV transformer output.

Units: kW

transmission_loss: list

Loss due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI). Depends on transmission input

Units: kW

gen: list

Power at the point of interconnection (POI), prior to clipping the values to the limit defined by e.g. StandaloneStorageModel.downstream_system.system_design.poi_limit

Units: kW

poi_unadjusted: list

Power at the point of interconnection (POI), after applying POI clipping but before applying the user-defined poi_adjustment

Units: kW

poi: list

Power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kW

positive_poi: list

Positive-only values of poi time series, where negative values have been set to zero.

Units: kW

negative_poi: list

Negative-only values of poi time series, where positive values have been set to zero.

Units: kW

class GenerationModelResults(*, ideal_tracker_rotation: list | None = None, front_total_poa: list | None = None, rear_total_poa: list | None = None, effective_total_poa: list | None = None, array_dc_snow_loss: list | None = None, array_gross_dc_power: list | None = None, array_dc_power: list | None = None, array_dc_voltage: list | None = None, inverter_mppt_dc_voltage: list | None = None, inverter_mppt_loss: list | None = None, inverter_clipping_loss: list | None = None, inverter_night_tare_loss: list | None = None, inverter_power_consumption_loss: list | None = None, inverter_efficiency: list | None = None, ambient_temp: list | None = None, gross_ac_power: list, mv_transformer_loss: list | None = None, mv_transformer_load_loss: list | None = None, mv_transformer_no_load_loss: list | None = None, mv_ac_power: list, ac_wiring_loss: list, hv_transformer_loss: list | None = None, hv_transformer_load_loss: list | None = None, hv_transformer_no_load_loss: list | None = None, transformer_load_loss: list, transformer_no_load_loss: list, hv_ac_power: list, ac_transmission_loss: list, gen: list, poi_unadjusted: list, system_power: list, positive_system_power: list, negative_system_power: list, curtailed_system_power: list | None = None, net_system_power: list | None = None, net_positive_system_power: list | None = None, sam_design_parameters: dict, tyba_api_loss_waterfall: SolarWaterfall, warnings: List[str], coupling: None)

Results schema returned when a PVGenerationModel, ACExternalGenerationModel or DCExternalGenerationModel simulation is run

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

ideal_tracker_rotation

Ideal or “true”-tracking angle for single axis tracking systems.

Units: degrees with horizontal equal to 0°
For backtracking systems this angle will differ from the actual tracker angle
Only generated for PVGenerationModel simulations where PVGenerationModel.system_design.tracking is a SingleAxisTracking instance

front_total_poa

Total plane of array (POA) irradiance that strikes the front face of the PV array after accounting for shading, soiling and incidence angle modifier (IAM) losses

Units: W/m²
Only generated for PVGenerationModel simulations

rear_total_poa

Total plane of array (POA) irradiance that strikes the rear face of the PV array after accounting for rear irradiance losses (as defined by the rear_irradiance input and incidence angle modifier (IAM) losses

Units: W/m²
Only generated for PVGenerationModel simulations where PVGenerationModel.pv_module.bifacial is True

effective_total_poa

Total plane of array (POA) irradiance available to the PV array for conversion to electrical power. Includes front-side and rear-side contributions for bifacial systems but also accounts for the bifaciality factor, such that

$POA_{eff\_total} = POA_{front\_total} + bifaciality * POA_{rear\_total}$

Units: W/m²
Only generated for PVGenerationModel simulations

array_dc_snow_loss

Loss due to build up of snow on solar array. Modeled as a DC power reduction (as opposed to e.g. a reduction in irradiance) and applied just before the conversion to AC power.

Units: kW
Only non-zero if PVGenerationModel.losses.enable_snow_model is True
Only generated for PVGenerationModel simulations

array_gross_dc_power

DC power generated by the PV array after modeling irradiance-to-power conversion and time varying losses (e.g. array_dc_snow_loss), but before modeling constant derate factors (e.g. lid loss)

Units: kW
Only generated for PVGenerationModel simulations

array_dc_power

DC power generated by the PV array (or other generation source) at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (e.g. the combined inverter inputs).

Units: kW
Represents the maximum power point (MPP) power of the array (constrained by the inverter MPP tracking voltage window). It does not represent the reduced DC power that results from inverter clipping. As such, it is equivalent to PVSyst’s EArrayMPP and not EArray
Only generated for PVGenerationModel or DCExternalGenerationModel simulations
For DCExternalGenerationModel simulations this is equivalent to the provided DCExternalGenerationModel.production_override.power

array_dc_voltage

DC voltage generated by the PV array (or other generation source) at the DC bus, i.e. the point in the idealized model flow just before DC-to-AC conversion (.e.g the combined inverter inputs).

Units: V
Only generated for PVGenerationModel or DCExternalGenerationModel simulations
For DCExternalGenerationModel simulations this is equivalent to the provided DCExternalGenerationModel.production_override.voltage

inverter_mppt_dc_voltage

Deprecated, instead use array_dc_voltage.

Units: V
Only generated for PVGenerationModel simulations

inverter_mppt_loss

Loss due to operating at the edges of the maximum power point (MPP) voltage window, i.e. off of the MPP. Applied just after the irradiance-to-power conversion.

Units: kW
Only generated for PVGenerationModel simulations

inverter_clipping_loss

Loss due to inverter power clipping, including clipping that occurs due to a thermal derate of the inverter nameplate power.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_night_tare_loss

Loss due to inverter standby power draw, applied when the input DC power is below the turn on threshold

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_power_consumption_loss

Loss due to inverter power consumption during operation, applied when the input DC power is above the turn on threshold. Note that depending on the inverter model used, there is a different relationship to inverter_efficiency. For the CEC inverter model (Inverter class), the efficiency includes the consumption loss. For the OND inverter model (ONDInverter class), the consumption loss depends on the aux_loss input and is applied after conversion and clipping.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

inverter_efficiency

Inverter conversion (DC to AC) efficiency. Does not include clipping effects, which are returned separately as inverter_clipping_loss.

Units: kW
Only generated for PVGenerationModel or DCExternalGenerationModel simulations

ambient_temp

Ambient Temperature. This is provided as a convenience for simulations where Tyba pulls a solar resource dataset based on project location. If ambient temperature was provided as part of a solar resource or external generation dataset, this will be equivalent.

Units: °C

gross_ac_power

AC power at the combined inverter outputs. For ACExternalGenerationModel simulations, it is equivalent to mv_ac_power and can be ignored.

Units: kW

mv_transformer_loss

Total loss due to operation of a medium voltage (MV) transformer, the sum of mv_transformer_load_loss and mv_transformer_no_load_loss.

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_transformer_load_loss

Load-dependent loss due to operation of medium voltage (MV) transformer (coil losses). Depends on load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_transformer_no_load_loss

Constant loss due to operation of medium voltage (MV) transformer (core losses). Depends on no_load_loss factor

Units: kW
Only generated when e.g. PVGenerationModel.losses.mv_transformer is not None

mv_ac_power

Total AC power at medium voltage (MV) AC bus, e.g. the panel that collects all of the MV transformer outputs

Units: kW
For ACExternalGenerationModel simulations this is equivalent to the provided ACExternalGenerationModel.production_override.power

ac_wiring_loss

Loss due to resistance of medium voltage (MV) AC wiring that connects the MV AC bus, either to a high voltage transformer (if modeled) or the project switchgear. Depends on ac_wiring input.

Units: kW

hv_transformer_loss

Total loss due to operation of high voltage (HV) transformer (i.e. a GSU or substation), the sum of hv_transformer_load_loss and hv_transformer_no_load_loss.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

hv_transformer_load_loss

Load-dependent loss (coil losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

hv_transformer_no_load_loss

Constant loss (core losses) due to operation of high voltage (HV) transformer (i.e. a GSU or substation). Depends on no_load_loss factor.

Units: kW
Only generated when e.g. PVGenerationModel.losses.hv_transformer is not None

transformer_load_loss

Deprecated, see hv_transformer_load_loss.

Units: kW
If e.g. PVGenerationModel.losses.hv_transformer is None, will be all zeros.

transformer_no_load_loss

Deprecated, see hv_transformer_no_load_loss.

Units: kW
If e.g. PVGenerationModel.losses.hv_transformer is None, will be all zeros.

hv_ac_power

Total AC power measured at the switchgear/project boundary. This point is also defined as the high voltage (HV) bus because if a high voltage transformer/GSU/substation is modeled, this corresponds to the HV transformer output.

Units: kW

ac_transmission_loss

Loss due to resistance of high voltage (HV) AC lines that connect the switchgear to the actual point of interconnection (POI). Depends on transmission input

Units: kW

gen

Power at the point of interconnection (POI), prior to clipping the values to the limit defined by e.g. PVGenerationModel.system_design.poi_limit

Units: kW

poi_unadjusted

Power at the point of interconnection (POI), after applying POI clipping but before applying the user-defined poi_adjustment

Units: kW

system_power

Power at the point of interconnection (POI) after accounting for all losses/adjustments

Units: kW

positive_system_power

Positive-only values of system_power time series, where negative values have been set to zero. Useful when trying to quantify AC solar generation or if, for example, power drawn from the grid (inverter standby) is valued at a different price than generated power

Units: kW

negative_system_power

Negative-only values of system_power time series, where positive values have been set to zero. Useful if, for example, power drawn from the grid (inverter standby) is valued at a different price than generated power

Units: kW

curtailed_system_power

net_system_power

net_positive_system_power

sam_design_parameters

Dict of raw PySAM inputs. As such, variable names will not correspond to those used in the Tyba model schema, but it can be useful for understanding very specific settings used in the PV simulation. See SAM documentation (link above) for more details.

Only non-empty for PVGenerationModel simulations

tyba_api_loss_waterfall: SolarWaterfall: Waterfall-style loss data for first year (8760 hours) or results

warnings: t.List[str]: List of warnings generated during simulations. These warnings do not indicate errors in the simulation, but arise when the given inputs may result in inaccurate or unexpected results. For example, a common scenario that will raise a warning is if an inverter has been defined with e.g. includes_xfmr equal to False but no MV transformer has been defined. In this case, the simulation would inaccurately neglect MV transformer losses.

coupling: None: Key used internally. coupling equal to None indicates that the simulation is PV- (or generation) only and does not consider storage.

class PVStorageModelResults(*, solar_only: SolarTimeSeries, solar_storage: SolarStorageTimeSeries, waterfall: SolarStorageWaterfall, optimizer: OptimizerTimeSeries, market_awards: MarketAwardsTimeSeries | None = None, warnings: List[str], coupling: str)

Results schema returned when a PVStorageModel simulation is run

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

solar_only: SolarTimeSeries: Power flow-related time series data for the PV- (or generation) only simulation corresponding to the given generation inputs. Useful for comparing to the results in solar_storage to better understand the value of a hybrid vs PV-only project

solar_storage: SolarStorageTimeSeries: Power flow-related time series results

waterfall: SolarStorageWaterfall: Waterfall-style loss data for first year (8760 hours) or results

optimizer: OptimizerTimeSeries: Time series results associated with BESS optimization and operation

market_awards: t.Optional[MarketAwardsTimeSeries]: Time series results intended to represent market awards for use in revenue calculation

warnings: t.List[str]: List of warnings generated during simulations. See GenerationModelResults.warnings for more information

coupling: str: Key used internally. Reflects the storage_coupling input

class StandaloneStorageModelWithDownstreamResults(*, system: StandaloneStorageSystemTimeSeries, optimizer_outputs: OptimizerTimeSeries, market_awards: MarketAwardsTimeSeries | None = None)

Results schema returned when a StandaloneStorageModel simulation is run with a downstream_system specified

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

system: StandaloneStorageSystemTimeSeries: Power flow-related time series results

optimizer_outputs: OptimizerTimeSeries: Time series results associated with BESS optimization and operation

market_awards: t.Optional[MarketAwardsTimeSeries]: Time series results intended to represent market awards for use in revenue calculation

class StandaloneStorageModelSimpleResults(*, hvac_loss: list | None = None, import_limit_at_coupling: list | None = None, export_limit_at_coupling: list | None = None, target_load: list | None = None, charge_actual: list, discharge_actual: list, charge: list, discharge: list, charge_hi: list, discharge_hi: list, charge_lo: list, discharge_lo: list, battery_output: list, output: list, total_output: list, internal_energy: list, soe_actual: list, soe_lo: list, soe_hi: list, soe_hb_actual: list, soe_hb_lo: list, soe_hb_hi: list, soe_mean_actual: list, soe_mean_lo: list, soe_mean_hi: list, dam_charge: list | None = None, dam_discharge: list | None = None, dam_solar: list | None = None, dam_base_point: list | None = None, rtm_charge: list | None = None, rtm_discharge: list | None = None, rtm_solar: list | None = None, rtm_base_point: list | None = None, rtm_price: list | None = None, dam_price: list | None = None, imbalance: list | None = None, solar_actual: list | None = None, solar_hi: list | None = None, solar_lo: list | None = None, net_load: list | None = None, RESERVE_MARKET_price: list | None = None, RESERVE_MARKET_offer: list | None = None, RESERVE_MARKET_utilized_max: list | None = None, RESERVE_MARKET_utilized_min: list | None = None, RESERVE_MARKET_utilized_actual: list | None = None, RESERVE_MARKET_realized: list | None = None, RESERVE_MARKET_flex_offer: list | None = None, RESERVE_MARKET_flex_max: list | None = None, RESERVE_MARKET_flex_min: list | None = None, RESERVE_MARKET_flex_actual: list | None = None, RESERVE_MARKET_discharge_offer: list | None = None, RESERVE_MARKET_discharge_max: list | None = None, RESERVE_MARKET_discharge_min: list | None = None, RESERVE_MARKET_discharge_actual: list | None = None, RESERVE_MARKET_stop_charge_offer: list | None = None, RESERVE_MARKET_stop_charge_max: list | None = None, RESERVE_MARKET_stop_charge_min: list | None = None, RESERVE_MARKET_stop_charge_actual: list | None = None, RESERVE_MARKET_charge_offer: list | None = None, RESERVE_MARKET_charge_max: list | None = None, RESERVE_MARKET_charge_min: list | None = None, RESERVE_MARKET_charge_actual: list | None = None, RESERVE_MARKET_stop_discharge_offer: list | None = None, RESERVE_MARKET_stop_discharge_max: list | None = None, RESERVE_MARKET_stop_discharge_min: list | None = None, RESERVE_MARKET_stop_discharge_actual: list | None = None, **extra_data: Any)

Results schema returned when a StandaloneStorageModel simulation is run without a downstream_system specified. Note that in this case, all time series apply at the point of interconnection (POI).

model_post_init(_BaseTimeSeries__context: Any) → None: Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

hvac_loss

Losses due to BESS HVAC operation. Will only be generated as part of StandaloneStorageModelSimpleResults. In that case, will be applied at the BESS modeling boundary. For hybrid or standalone storage with downstream losses see PVStorageModelResults.solar_storage.hvac_loss or StandaloneStorageModelWithDownstreamResults.system.hvac_loss respectively.

Units: kW
Only generated when there is a battery term with hvac as a BatteryHVACParams instance

import_limit_at_coupling

The limit defined by the import limit input (e.g. PVStorageModel.import_limit) but adjusted based on system loses to apply at the BESS modeling boundary.

Units: kW
Using convention that towards the POI/grid is positive, all values will be <= 0

export_limit_at_coupling

The limit defined by the export limit input (e.g. PVStorageModel.export_limit but adjusted based on system loses to apply at the BESS modeling boundary.

Units: kW
Using convention that towards the POI/grid is positive, all values will be >= 0

target_load

The lowest target load that applies for each time interval at the BESS modeling boundary in BTM simulations with monthly/seasonal demand charges. Note that for overlapping demand charges, multiple targets may apply to a given time interval but for simplicity only the lowest is reported here. See seasonal_peak_windows for more details.

Units: kW
Positive values correspond to power flowing from the POI towards the BESS modeling boundary
Only generated when e.g. StandaloneStorageModel.load_peak_reduction is not None and seasonal_peak_windows are given.

charge_actual

BESS charging power at the BESS modeling boundary. Represents BESS charging behavior in the base case, where reserve market utilization and PV array (or other generation) power are defined by e.g. ScalarUtilization.actual and solar_actual (if applicable).

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Represents the mean power across the time interval

discharge_actual

BESS discharging power at the BESS modeling boundary. Represents BESS discharging behavior in the base case, where reserve market utilization and PV array (or other generation) power are defined by e.g. ScalarUtilization.actual and solar_actual (if applicable).

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Represents the mean power across the time interval

charge: Duplicate of charge_actual

discharge: Duplicate of discharge_actual

charge_hi

The highest BESS charging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

discharge_hi

The highest BESS discharging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

charge_lo

The lowest BESS charging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

discharge_lo

The lowest BESS discharging power that might result at the BESS modeling boundary due to uncertainty in reserve market utilization and PV array (or other generation) power (if applicable).

Units: kW
All values will be >= 0

battery_output

Power flow to/from the BESS at the BESS modeling boundary. Sum of the charge and discharge time series subject to power flow sign conventions.

Units: kW
Positive values correspond to BESS discharge, negative values correspond to BESS charge.
Note that the relationship between internal_energy and battery_output is dependent on the current BESS charge and discharge efficiency, which will vary with time if an efficiency_degradation_model has been specified

output: Duplicate of battery_output

total_output

Total power flow at the BESS modeling boundary. For PVStorageModel simulations this is the combined power from the BESS+PV (or other generation source) at the point of BESS coupling. For standalone storage simulations, will be equivalent to battery_output.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.

internal_energy: Duplicate of soe_actual

soe_actual

Realized energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_actual and discharge_actual are applied at each time interval. As such, will not start with the user-specified initial SOE (since this applies to the beginning of the first time interval). Note values will be higher than the amount of usable energy in the BESS due to all losses between the BESS modeling boundary and the internal structure of the cells (the idealized battery “vessel”).

Units: kWh

soe_lo

Lower bound of energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_lo and discharge_hi are applied to a beginning SOE of soe_hb_actual.

Units: kWh

soe_hi

Upper bound of energy stored in the BESS (state of energy or SOE) at the end of each time interval. Represents the SOE that results when charge_hi and discharge_lo are applied to a beginning SOE of soe_hb_actual.

Units: kWh

soe_hb_actual

Realized energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_actual in the previous time interval. As such, will start with the user-specified initial SOE (since this applies to the beginning of the first time interval)

Units: kWh

soe_hb_lo

Lower bound of energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_lo in the previous time interval.

Units: kWh

soe_hb_hi

Upper bound of energy stored in the BESS (state of energy or SOE) at the beginning of each time interval. Equivalent to the value of soe_hi in the previous time interval.

Units: kWh

soe_mean_actual

Mean value of energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_actual and soe_hb_actual for each time interval.

Units: kWh

soe_mean_lo

Mean value of lower-bound energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_lo and soe_hb_lo for each time interval.

Units: kWh

soe_mean_hi

Mean value of upper-bound energy stored in the BESS (state of energy or SOE) across each time interval, i.e. the average of soe_hi and soe_hb_hi for each time interval.

Units: kWh

dam_charge

Day Ahead Market (DAM) award component of charge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Only generated when energy_strategy is da or dart (quantity-only)

dam_discharge

Day Ahead Market (DAM) award component of discharge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Only generated when energy_strategy is da or dart (quantity-only)

dam_solar

Day Ahead Market (DAM) award component of solar_actual at the BESS modeling boundary.

Units: kW
Only generated for attr:~generation_models.generation_models.PVStorageModel sims where energy_strategy is da or dart (quantity-only)

dam_base_point

Total Day Ahead Market (DAM) award at the BESS modeling boundary. Sum of the dam_charge and dam_discharge (and dam_solar for hybrid) time series, subject to power flow sign conventions.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.
Only generated when energy_strategy is da or dart (quantity-only)

rtm_charge

Real Time Market (RTM) award component of charge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS discharging or at rest)
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_discharge

Real Time Market (RTM) award component of discharge_actual at the BESS modeling boundary.

Units: kW
All values will be >= 0 (Zero if BESS charging or at rest)
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_solar

Real Time Market (RTM) award component of solar_actual at the BESS modeling boundary.

Units: kW
Only generated for attr:~generation_models.generation_models.PVStorageModel sims where energy_strategy is rt or dart (quantity-only)

rtm_base_point

Total Real Time Market (RTM) award at the BESS modeling boundary. Sum of the rtm_charge and rtm_discharge (and rtm_solar for hybrid) time series, subject to power flow sign conventions.

Units: kW
Positive values correspond to flow towards the POI, negative values correspond to flow away from the POI.
Only generated when energy_strategy is rt or dart (quantity-only)

rtm_price: Real-time market (RTM) prices. Equivalent to the rtm input, but included in the results for convenience.

dam_price: Day Ahead Market (DAM) prices. Equivalent to the dam input, but included in the results for convenience.

imbalance: Imbalance market prices. Equivalent to the imbalance input, but included in the results for convenience.

solar_actual

Realized power from the PV array (or other generation source) at the BESS modeling boundary. Will align with the given generation inputs and specifically ACProductionProfile.power.actual if modeling uncertain solar. Does not include standby losses and can further differ from its generation equivalent due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for PVStorageModel simulations

solar_hi

Upper bound power from the PV array (or other generation source) at the BESS modeling boundary. Relevant when modeling uncertain solar, in which case it will be mostly equivalent to ACProductionProfile.power.max. Otherwise, will be equivalent to solar_actual. Can differ from its input due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for generation_models.generation_models.PVStorageModel simulations

solar_lo

Lower bound power from the PV array (or other generation source) at the BESS modeling boundary. Relevant when modeling uncertain solar, in which case it will be mostly equivalent to ACProductionProfile.power.min. Otherwise, will be equivalent to solar_actual. Can differ from its input due to two factors: (1) economic curtailment that is modeled for energy prices below the negative of the generation_models.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

Units: kWh
Only generated for generation_models.generation_models.PVStorageModel simulations

net_load

The net load at the BESS modeling boundary in BTM simulations after the BESS and PV array (or other generation source) behavior is accounted for.

Units: kW
Positive values correspond to power flowing from the POI towards the BESS modeling boundary
Only generated when e.g. StandaloneStorageModel.load_peak_reduction is not None

RESERVE_MARKET_price: PLACEHOLDER, not a real output. For each specified reserve market, a _price time series will be generated. Will match the price input but is generated for convenience

RESERVE_MARKET_offer

PLACEHOLDER, not a real output. For each specified reserve market, an _offer time series will be generated. This is the power offer made in that market for each time interval (assumed to also be awarded).

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_max

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_min

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_utilized_actual

PLACEHOLDER, not a real output. For each specified reserve market, a _utilized_actual time series will be generated. This is the portion of RESERVE_MARKET_offer that is modeled as called and actually impacts BESS state of energy

Units: kW
Average power over the interval

RESERVE_MARKET_realized

PLACEHOLDER, not a real output. For each specified reserve market, a _realized time series will be generated. This is a duplicate of RESERVE_MARKET_utilized_actual.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_offer

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_offer time series will be generated for each specified reserve market. This is the portion of the RESERVE_MARKET_offer that will be met with flexible PV array production.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_max

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_max time series will be generated for each specified reserve market. This is the upper-bound portion of RESERVE_MARKET_flex_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_min

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_min time series will be generated for each specified reserve market. This is the lower-bound portion of RESERVE_MARKET_flex_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_flex_actual

PLACEHOLDER, not a real output. If flexible_solar is True, a _flex_actual time series will be generated for each specified reserve market. This is the portion of RESERVE_MARKET_flex_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_offer

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met with BESS discharge.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_max

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_min

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_discharge_actual

PLACEHOLDER, not a real output. For each specified up reserve market, a _discharge_actual time series will be generated. This is the portion of RESERVE_MARKET_discharge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_offer

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met by stopping/reducing BESS charging.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_max

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_stop_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_min

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_stop_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_charge_actual

PLACEHOLDER, not a real output. For each specified up reserve market, a _stop_charge_actual time series will be generated. This is the portion of RESERVE_MARKET_stop_charge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_offer

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met with BESS charge.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_max

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_min

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_charge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_charge_actual

PLACEHOLDER, not a real output. For each specified down reserve market, a _charge_actual time series will be generated. This is the portion of RESERVE_MARKET_charge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_offer

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_offer time series will be generated. This is the portion of the RESERVE_MARKET_offer that will be met by stopping/reducing BESS discharging.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_max

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_max time series will be generated. This is the upper-bound portion of RESERVE_MARKET_stop_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_min

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_min time series will be generated. This is the lower-bound portion of RESERVE_MARKET_stop_discharge_offer that could be called and impact BESS state of energy.

Units: kW
Average power over the interval

RESERVE_MARKET_stop_discharge_actual

PLACEHOLDER, not a real output. For each specified down reserve market, a _stop_discharge_actual time series will be generated. This is the portion of RESERVE_MARKET_stop_discharge_offer that is modeled as called and actually impacts BESS state of energy.

Units: kW
Average power over the interval

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

V2 Results Schema (in progress)

generation_models.v2_output_schema.

class BusTimeSeries(*, power: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DCBusTimeSeries(*, power: List[Annotated[float, 'kW', 'unit_types.kW']], voltage: List[Annotated[float, 'V', 'unit_types.V']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class InverterTimeSeries(*, clipping_loss: List[Annotated[float, 'kW', 'unit_types.kW']], efficiency: List[Annotated[float, 'dec', 'unit_types.dec']], tare_loss: List[Annotated[float, 'kW', 'unit_types.kW']], consumption_loss: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TransformerTimeSeries(*, total_loss: List[Annotated[float, 'kW', 'unit_types.kW']], load_loss: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, no_load_loss: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ACWiringTimeSeries(*, loss: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TransmissionTimeSeries(*, loss: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class POITimeSeries(*, power_pre_clip: List[Annotated[float, 'kW', 'unit_types.kW']], power_pre_adjustment: List[Annotated[float, 'kW', 'unit_types.kW']], power: List[Annotated[float, 'kW', 'unit_types.kW']], power_positive: List[Annotated[float, 'kW', 'unit_types.kW']], power_negative: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PVTimeSeries(*, ghi: List[Annotated[float, 'Wm2', 'unit_types.Wm2']], tracker_rotation_angle: List[Annotated[float, 'deg', 'unit_types.deg']] | None = None, front_poa_nominal: List[Annotated[float, 'Wm2', 'unit_types.Wm2']] | None = None, front_poa_shaded: List[Annotated[float, 'Wm2', 'unit_types.Wm2']] | None = None, front_poa_shaded_soiled: List[Annotated[float, 'Wm2', 'unit_types.Wm2']] | None = None, front_poa: List[Annotated[float, 'Wm2', 'unit_types.Wm2']], rear_poa: List[Annotated[float, 'Wm2', 'unit_types.Wm2']], poa_effective: List[Annotated[float, 'Wm2', 'unit_types.Wm2']], poa_effective_power: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, cell_temperature_quasi_steady: List[Annotated[float, 'degC', 'unit_types.degC']] | None = None, cell_temperature: List[Annotated[float, 'degC', 'unit_types.degC']] | None = None, module_efficiency: List[Annotated[float, 'dec', 'unit_types.dec']] | None = None, dc_shading_loss: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, dc_snow_loss: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, mppt_window_loss: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, gross_dc_power: List[Annotated[float, 'kW', 'unit_types.kW']], dc_power_undegraded: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, dc_power: List[Annotated[float, 'kW', 'unit_types.kW']] | None = None, dc_voltage: List[Annotated[float, 'V', 'unit_types.V']] | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class BESSTimeSeries(*, internal_energy: List[Annotated[float, 'kWh', 'unit_types.kWh']], internal_energy_max: List[Annotated[float, 'kWh', 'unit_types.kWh']], limit: List[Annotated[float, 'kW', 'unit_types.kW']], output: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class CoupledBESSTimeSeries(*, internal_energy: List[Annotated[float, 'kWh', 'unit_types.kWh']], internal_energy_max: List[Annotated[float, 'kWh', 'unit_types.kWh']], limit: List[Annotated[float, 'kW', 'unit_types.kW']], output: List[Annotated[float, 'kW', 'unit_types.kW']], excess_power_at_coupling: List[Annotated[float, 'kW', 'unit_types.kW']], captured_excess_at_coupling: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class BESSHVACTimeSeries(*, loss: List[Annotated[float, 'kW', 'unit_types.kW']])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class GenerationPowerFlowTimeSeries(*, dc_bus: DCBusTimeSeries | None = None, inverter: InverterTimeSeries | None = None, lv_bus: BusTimeSeries | None = None, mv_xfmr: TransformerTimeSeries | None = None, mv_bus: BusTimeSeries | None = None, ac_wiring: ACWiringTimeSeries | None = None, hv_xfmr: TransformerTimeSeries | None = None, export_bus: BusTimeSeries, transmission: TransmissionTimeSeries, poi: POITimeSeries, pv: PVTimeSeries | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class GenerationYear1Waterfall(*, dc_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, inverter_clipping: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_consumption: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_tare: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_efficiency: Annotated[float, 'dec', 'unit_types.dec'] | None = None, lv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, mv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, ac_wiring: Annotated[float, 'dec', 'unit_types.dec'] | None = None, hv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, export_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'], transmission: Annotated[float, 'dec', 'unit_types.dec'], poi_clipping: Annotated[float, 'dec', 'unit_types.dec'], poi_adjustment: Annotated[float, 'dec', 'unit_types.dec'], poi_energy: Annotated[float, 'kWh', 'unit_types.kWh'], ghi: Annotated[float, 'Whm2', 'unit_types.Whm2'] | None = None, front_transposition: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_shading: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_soiling: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_iam: Annotated[float, 'dec', 'unit_types.dec'] | None = None, rear_poa: Annotated[float, 'dec', 'unit_types.dec'] | None = None, rear_bifaciality: Annotated[float, 'dec', 'unit_types.dec'] | None = None, poa_effective: Annotated[float, 'Whm2', 'unit_types.Whm2'] | None = None, array_area: Annotated[float, 'm2', 'unit_types.m2'] | None = None, poa_effective_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, stc_pv_module_effeciency: Annotated[float, 'dec', 'unit_types.dec'] | None = None, pv_dc_nominal_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, non_stc_irradiance_temperature: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mppt_clip: Annotated[float, 'dec', 'unit_types.dec'] | None = None, snow: Annotated[float, 'dec', 'unit_types.dec'] | None = None, pv_dc_gross_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, nameplate: Annotated[float, 'dec', 'unit_types.dec'] | None = None, lid: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mismatch: Annotated[float, 'dec', 'unit_types.dec'] | None = None, diodes: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_optimizer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, tracking_error: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_wiring: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_adjustment: Annotated[float, 'dec', 'unit_types.dec'] | None = None)

non_stc_irradiance_temperature: t.Optional[dec]: this includes DC derate due to beam shading (electrical effect), will be broken out in the future

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class StandalonePowerFlowTimesSeries(*, dc_bus: DCBusTimeSeries | None = None, inverter: InverterTimeSeries | None = None, lv_bus: BusTimeSeries | None = None, mv_xfmr: TransformerTimeSeries | None = None, mv_bus: BusTimeSeries | None = None, ac_wiring: ACWiringTimeSeries | None = None, hv_xfmr: TransformerTimeSeries | None = None, export_bus: BusTimeSeries, transmission: TransmissionTimeSeries, poi: POITimeSeries, bess: BESSTimeSeries, bess_hvac: BESSHVACTimeSeries | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class StandaloneYear1Waterfall(*, dc_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, inverter_clipping: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_consumption: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_tare: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_efficiency: Annotated[float, 'dec', 'unit_types.dec'] | None = None, lv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, mv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, ac_wiring: Annotated[float, 'dec', 'unit_types.dec'] | None = None, hv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, export_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'], transmission: Annotated[float, 'dec', 'unit_types.dec'], poi_clipping: Annotated[float, 'dec', 'unit_types.dec'], poi_adjustment: Annotated[float, 'dec', 'unit_types.dec'], poi_energy: Annotated[float, 'kWh', 'unit_types.kWh'], bess_efficiency: Annotated[float, 'dec', 'unit_types.dec'], bess_hvac: Annotated[float, 'dec', 'unit_types.dec'] | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class HybridPowerFlowTimeSeries(*, dc_bus: DCBusTimeSeries | None = None, inverter: InverterTimeSeries | None = None, lv_bus: BusTimeSeries | None = None, mv_xfmr: TransformerTimeSeries | None = None, mv_bus: BusTimeSeries | None = None, ac_wiring: ACWiringTimeSeries | None = None, hv_xfmr: TransformerTimeSeries | None = None, export_bus: BusTimeSeries, transmission: TransmissionTimeSeries, poi: POITimeSeries, bess: CoupledBESSTimeSeries, bess_hvac: BESSHVACTimeSeries | None = None, pv: PVTimeSeries | None = None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class HybridYear1Waterfall(*, dc_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, inverter_clipping: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_consumption: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_tare: Annotated[float, 'dec', 'unit_types.dec'] | None = None, inverter_efficiency: Annotated[float, 'dec', 'unit_types.dec'] | None = None, lv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, mv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mv_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, ac_wiring: Annotated[float, 'dec', 'unit_types.dec'] | None = None, hv_transformer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, export_bus_energy: Annotated[float, 'kWh', 'unit_types.kWh'], transmission: Annotated[float, 'dec', 'unit_types.dec'], poi_clipping: Annotated[float, 'dec', 'unit_types.dec'], poi_adjustment: Annotated[float, 'dec', 'unit_types.dec'], poi_energy: Annotated[float, 'kWh', 'unit_types.kWh'], bess_efficiency: Annotated[float, 'dec', 'unit_types.dec'], bess_hvac: Annotated[float, 'dec', 'unit_types.dec'] | None = None, ghi: Annotated[float, 'Whm2', 'unit_types.Whm2'] | None = None, front_transposition: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_shading: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_soiling: Annotated[float, 'dec', 'unit_types.dec'] | None = None, front_iam: Annotated[float, 'dec', 'unit_types.dec'] | None = None, rear_poa: Annotated[float, 'dec', 'unit_types.dec'] | None = None, rear_bifaciality: Annotated[float, 'dec', 'unit_types.dec'] | None = None, poa_effective: Annotated[float, 'Whm2', 'unit_types.Whm2'] | None = None, array_area: Annotated[float, 'm2', 'unit_types.m2'] | None = None, poa_effective_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, stc_pv_module_effeciency: Annotated[float, 'dec', 'unit_types.dec'] | None = None, pv_dc_nominal_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, non_stc_irradiance_temperature: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mppt_clip: Annotated[float, 'dec', 'unit_types.dec'] | None = None, snow: Annotated[float, 'dec', 'unit_types.dec'] | None = None, pv_dc_gross_energy: Annotated[float, 'kWh', 'unit_types.kWh'] | None = None, nameplate: Annotated[float, 'dec', 'unit_types.dec'] | None = None, lid: Annotated[float, 'dec', 'unit_types.dec'] | None = None, mismatch: Annotated[float, 'dec', 'unit_types.dec'] | None = None, diodes: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_optimizer: Annotated[float, 'dec', 'unit_types.dec'] | None = None, tracking_error: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_wiring: Annotated[float, 'dec', 'unit_types.dec'] | None = None, dc_adjustment: Annotated[float, 'dec', 'unit_types.dec'] | None = None, excess_power_at_coupling: Annotated[float, 'dec', 'unit_types.dec'], captured_excess_at_coupling: Annotated[float, 'dec', 'unit_types.dec'], bess_efficiency_generation: Annotated[float, 'dec', 'unit_types.dec'])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

non_stc_irradiance_temperature: this includes DC derate due to beam shading (electrical effect), will be broken out in the future

class GenerationModelResults(*, power_flow: GenerationPowerFlowTimeSeries, waterfall: GenerationYear1Waterfall, warnings: List[str] | None = None, sam_raw: dict | None = None, solar_resource: SolarResource | None = None)

Results schema returned when a PVGenerationModel, ACExternalGenerationModel or DCExternalGenerationModel simulation is run

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class StandaloneModelResults(*, power_flow: StandalonePowerFlowTimesSeries, waterfall: StandaloneYear1Waterfall, market_awards: MarketAwardsTimeSeries, warnings: List[str], optimizer: OptimizerTimeSeries | None = None)

Results schema returned when a StandaloneStorageModel simulation is run with a downstream_system specified

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class HybridModelResults(*, power_flow: HybridPowerFlowTimeSeries, waterfall: HybridYear1Waterfall, market_awards: MarketAwardsTimeSeries, warnings: List[str], optimizer: OptimizerTimeSeries | None = None, solar_only: GenerationModelResults | None = None)

Results schema returned when a PVStorageModel simulation is run

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Utilities for Importing Local Files

Equipment File Readers

generation_models.utils.pvsyst_readers.

pv_module_from_pan(pan_file: str, bifacial_ground_clearance_height=1.0, bifacial_transmission_factor: float = 0.013) → PVModuleMermoudLejeune

Generate a PV module simulation input object from a PAN file

Parameters:

pan_file – filepath to the PAN file
bifacial_ground_clearance_height – see bifacial_ground_clearance_height. Only relevant if the given PAN file is for a bifacial module. While this height is generally a feature of the racking system, it is specified here due to its association with the PV module’s bifacial submodel. The bifacial_ground_clearance_height attribute of the returned PVModuleMermoudLejeune object can be changed as needed to model different racking scenarios
bifacial_transmission_factor – see bifacial_transmission_factor. Only relevant if the given PAN file is for a bifacial module. While generally a feature of the racking system, it can be treated similarly to the bifacial_ground_clearance_height argument

Returns:

PVModuleMermoudLejeune object that can be used in a simulation via the pv_module attribute

inverter_from_ond(ond_file: str, includes_xfmr: bool = True) → ONDInverter

Generate an inverter simulation input object from an OND file

Parameters:

ond_file – filepath to the OND file
includes_xfmr – indicates whether the given OND file includes integrated medium voltage transformer effects. If it doesn’t, then a Transformer object should be passed in via the mv_transformer attribute

Returns:

ONDInverter object that can be used in a simulation via the inverter attribute on either PVGenerationModel or DCExternalGenerationModel

SolarResource/Weather File Readers

generation_models.utils.psm_readers.

solar_resource_from_psm_csv(filename: str, monthly_albedo: List[float] | None = None) → SolarResource

Generate a solar resource input object from a PSM/SAM-formatted CSV file. Info on the PSM/SAM data format can be found in section 1.1 of this PDF.

Parameters:

filename – filepath to the CSV file
monthly_albedo – optional specification of monthly average albedos to be used alongside the data in the CSV file. See monthly_albedo for more information.

Returns:

SolarResource object that can be passed into the simulation via the solar_resource attribute