Model Schema

get_deprecator(msg: str) → BeforeValidator

Use this in an Annotated type to trigger a DeprecationWarning when a deprecated field is passed explicitly.

Parameters:

msg (str)

Return type:

BeforeValidator

class StorageCoupling(value)

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

N-S oriented single axis tracker model

field tracking_type: t.Literal['SAT'] = 'SAT'

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

field rotation_limit: float = 45.0

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°

field backtrack: bool = True

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

class FixedTilt

Fixed tilt array model

field tracking_type: t.Literal['FT'] = 'FT'

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

field tilt: float [Required]

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°

class ScalarUtilization

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

field actual: float [Required]

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

field lower: float [Required]

The lower bound dispatched capacity.

  • Units: fraction of capacity award for the specific service

  • Example values: 0.0 indicating no operations

field upper: float [Required]

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.

class TimeSeriesUtilization

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

field actual: t.List[float] [Required]

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

field lower: t.List[float] [Required]

The lower bound dispatched capacity.

  • Units: fraction of capacity award for the specific service

  • Example values: 0.0 indicating no operations

field upper: t.List[float] [Required]

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.

class ReserveMarket

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.

field price: t.List[float] [Required]

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

field offer_cap: float [Required]

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. Assumed to be hourly. The list length must be equivalent to the hourly sum of all battery terms.

  • Units: MW

  • Maximum value: 200% of nameplate power

field utilization: t.Union[ScalarUtilization, TimeSeriesUtilization] [Required]

Sub-model to account for utilization uncertainty. See ScalarUtilization. If using TimeSeriesUtilization, must be same length as price.

field duration_requirement: float = 0.0

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

market requirement for offer duration (hours)

field obligation: t.Optional[t.List[float]] = None

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

Container for holding ancillary/reserve market inputs

field up: t.Optional[t.Dict[str, ReserveMarket]] = None

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(...)
}
field down: t.Optional[t.Dict[str, ReserveMarket]] = None

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

class DARTPrices

Energy prices used for the energy arbitrage application.

field rtm: conlist(float, min_length=1) [Required]

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

field dam: conlist(float, min_length=1) [Required]

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

field imbalance: t.Optional[conlist(float, min_length=1)] = None

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

class SolarResourceTimeSeries

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 is assumed to represent the “typical” resource in a location such that the data can be tiled across all the years of a project’s lifetime. If data is for a Typical Year (TY) and is intended to be tiled, it must: - represent one full year of data (8760 hours) - not contain any leap days - start with the 0th hour of January 1st.

field year: t.List[int] [Required]

Year value of the interval-beginning timestamp

  • 4 digit integer.

field month: t.List[int] [Required]

Month value of interval-beginning timestamp

  • Possible values: 1-12.

field day: t.List[int] [Required]

Day value of interval-beginning timestamp

  • Possible values: 1-31

field hour: t.List[int] [Required]

Hour value of interval-beginning timestamp

  • Possible values: 0-23

field minute: t.List[int] [Required]

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)

field tdew: t.List[float] [Required]

Dew point temperature

  • Units: °C

field df: t.List[float] [Required]

Diffuse Horizontal Irradiance

  • Units: W/m2

field dn: t.List[float] [Required]

Direct Normal Irradiance

  • Units: W/m2

field gh: t.List[float] [Required]

Global Horizontal Irradiance

  • Units: W/m2

field pres: t.List[float] [Required]

Ambient pressure

  • Units: milibar

field tdry: t.List[float] [Required]

Ambient Temperature (dry bulb)

  • Units: °C

field wdir: t.List[float] [Required]

Wind direction

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

field wspd: t.List[float] [Required]

Wind speed

  • Units: meter per second

field alb: t.Optional[t.List[float]] = None

Surface albedo

  • Units: ratio of reflected GHI

  • Default value is 0.2

field snow: t.Optional[t.List[float]] = None

Snow depth

  • Units: centimeters

class SolarResource

Sub-model for full specification of solar resource inputs

field latitude: float [Required]

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

  • Example: 38.0 for 38.0°N

field longitude: float [Required]

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

  • Example: -80.0 for 80.0°W

field time_zone_offset: float [Required]

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)

field elevation: float [Required]

Height above (or below) sea level.

  • Units: meters

  • Example: 358.0 for 358 meters above sea level

field data: SolarResourceTimeSeries [Required]

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

field monthly_albedo: t.Optional[t.List[float]] = None

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

class PSMRegion(value)

Enum class for selecting world region when pulling PSM solar resource data

NorthAmerica = 'North America'

Selects the North American dataset

AsiaPacific = 'Asia/Pacific'

Selects the North American dataset

class SolarResourceLocation

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

field latitude: float [Required]

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

  • Example: 38.0 for 38.0°N

field longitude: float [Required]

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

  • Example: -80.0 for 80.0°W

field region: PSMRegion = PSMRegion.NorthAmerica

regional data set to be queried

class FileComponent

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

field path: str [Required]

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

class PVModuleCEC

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.

field bifacial: bool [Required]

Whether or not the module is bifacial

field a_c: float [Required]

Module area

  • Units: m2

  • Example value: 2.17 m2

field n_s: float [Required]

Number of cells

  • Example value: 72

field i_sc_ref: float [Required]

Short circuit current at STC

  • Units: Adc

  • Example value: 11.3 Adc

field v_oc_ref: float [Required]

Open circuit voltage at STC

  • Units: Vdc

  • Example value: 48.6 Vdc

field i_mp_ref: float [Required]

Max power current at STC

  • Units: Adc

  • Example value: 10.8 Adc

field v_mp_ref: float [Required]

Max power voltage at STC

  • Units: Vdc

  • Example value: 40.1Vdc

field alpha_sc: float [Required]

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

field beta_oc: float [Required]

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

field t_noct: float [Required]

Nominal operating cell temperature

  • Units: °C

  • Example value: 44.0°C

field a_ref: float [Required]

Ideality factor at STC

  • Units: V

  • Example value: 1.81 V

field i_l_ref: float [Required]

Light current at STC

  • Units: A

  • Example value: 11.47 A

field i_o_ref: float [Required]

Diode saturation current at STC

  • Units: A

  • Example value: 2.63e-11 A

field r_s: float [Required]

Reference series resistance

  • Units: \(\\Omega\)

  • Example value: 0.27\(\\Omega\)

field r_sh_ref: float [Required]

Reference shunt resistance

  • Units: \(\\Omega\)

  • Example value: 453.56\(\\Omega\)

field adjust: float [Required]

Temperature coefficient adjustment factor

  • Format as a float that represents the percentage

  • Example value: 7.64 for 7.64%

field gamma_r: float [Required]

Temperature coefficient of maximum power

  • Units: %/°C

  • Example value: -0.36%/°CC

field bifacial_transmission_factor: float [Required]

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%

field bifaciality: float [Required]

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%

field bifacial_ground_clearance_height: float [Required]

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

class MermoudModuleTech(value)

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

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()

field bifacial: bool [Required]

Whether or not the module is bifacial

field bifacial_transmission_factor: float [Required]

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%

field bifaciality: float [Required]

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%

field bifacial_ground_clearance_height: float [Required]

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

field tech: MermoudModuleTech [Required]

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.

field iam_c_cs_iam_value: t.Optional[t.List[float]] = None

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.]

field iam_c_cs_inc_angle: t.Optional[t.List[float]] = None

Incident angle modifier angles

  • Corresponds to iam_c_cs_iam_value

  • Units: degrees

  • Example values: [0, 15, 30, 45, 60, 75, 90]

field i_mp_ref: float [Required]

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

  • Units: Adc

  • Example value: 10.8 Adc

field i_sc_ref: float [Required]

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

  • Units: Adc

  • Example value: 11.3 Adc

field length: float [Required]

Long dimension of solar module

  • Units: m

  • Example value: 1.956m

field n_diodes: int [Required]

Number of diodes in solar cell

  • Units: quantity

  • Example value: 3

field n_parallel: int [Required]

Number of cells in parallel

  • Units: quantity

  • Example value: 1

field n_series: int [Required]

Number of cells in series

  • Units: quantity

  • Example value: 72

field r_s: float [Required]

Reference series resistance

  • Units: \(\\Omega\)

  • Example value: 0.27

field r_sh_0: float [Required]

Shunt resistance in 0 irradiance

  • Units: \(\\Omega\)

  • Example value: 2500

field r_sh_exp: float [Required]

Shunt resistance exponential factor

  • Units: \(\\Omega\)

  • Example value: 5.5

field r_sh_ref: float [Required]

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

  • Units: \(\\Omega\)

  • Example value: 600

field s_ref: float [Required]

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

  • Units: W/m2

  • Example value: 1000

field t_c_fa_alpha: float [Required]

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

  • Units: unitless

  • Example value: 0.90

field t_ref: float [Required]

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

  • Units: °C

  • Example value: 25.0

field v_mp_ref: float [Required]

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

  • Units: Vdc

  • Example value: 40.1Vdc

field v_oc_ref: float [Required]

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

  • Units: Vdc

  • Example value: 48.6Vdc

field width: float [Required]

Short dimension of solar module

  • Units: m

  • Example value: 0.992 m

field alpha_sc: float [Required]

Temperature coefficient of short circuit current

  • Units: A/K

  • Example value: 0.00461 A/K

field beta_oc: float [Required]

Temperature coefficient of open circuit voltage

  • Units: V/K

  • Example value: -0.1406 V/K

field mu_n: float [Required]

Temperature coefficient of diode non-ideality factor

  • Units: 1/K

  • Example value: -0.0007 1/K

field n_0: float [Required]

Diode non-ideality factor

  • Units: 1/K

  • Example value: 0.967

field custom_d2_mu_tau: t.Optional[float] = None

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

class Inverter

Inputs for modeling inverter performance using the Sandia Inverter Model.

field pso: float [Required]

Power use during operation

  • Units: Wdc

  • Example value: 6429 Wdc

field pdco: float [Required]

Maximum DC power

  • Units: Wdc

  • Example value: 4272031 Wdc

field c0: float [Required]

First Sandia Coefficients

  • Units: 1/Wac

  • Example value: 2.84059e-9 1/Wac

field c1: float [Required]

Second Sandia Coefficient

  • Units: 1/Vdc

  • Example values: 1.1e-5

field c2: float [Required]

Third Sandia Coefficient

  • Units: 1/Vdc

  • Example values: 0.001713

field c3: float [Required]

Fourth Sandia Coefficient

  • Units: 1/Vdc

  • Example values: 0.001056

field vdcmax: float [Required]

Maximum DC Voltage

  • Units: Vdc

  • Example value: 1200 Vdc

field mppt_low: float [Required]

Minimum MPPT DC Voltage

  • Units: Vdc

  • Example value: 1003 Vdc

field mppt_high: float [Required]

Maximum MPPT DC Voltage

  • Units: Vdc

  • Example value: 1200 Vdc

field paco: float [Required]

Maximum AC power

  • Units: Wac

  • Example value: 4198240 Wac

field vdco: float [Required]

Nominal DC Voltage

  • Units: Vdc

  • Example value: 1062 Vdc

field pnt: float [Required]

Standby/Nighttime power use

  • Units: Wac

  • Example value: 1259.47 Wac

field includes_xfmr: bool = False

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

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.

field ambient_temp: t.List[float] [Required]

Temperatures in the derate curve, corresponding to max_ac_power

  • Units: °C

  • Example values: [25.0, 50.0, 60.0]

field max_ac_power: t.List[float] [Required]

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

  • Units: W

  • Example values: [14000, 12000, 10000]

class ONDEfficiencyCurve

Efficiency curve inputs for use with ONDInverter

field dc_power: t.List[float] [Required]

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]

field ac_power: t.List[float] [Required]

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]

class ONDInverter

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

field temp_derate_curve: ONDTemperatureDerateCurve [Required]

Curve of maximum AC power vs ambient temperature

field nominal_voltages: t.List[float] [Required]

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]

field power_curves: t.List[ONDEfficiencyCurve] [Required]

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

field dc_turn_on: float [Required]

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

  • Units: W

  • Example value: 100.0

field aux_loss: t.Optional[float] = None

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

field aux_loss_threshold: t.Optional[float] = None

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

  • Units: W

  • Example value: 200.0

field mppt_low: float [Required]

Minimum MPPT DC Voltage

  • Units: Vdc

  • Example value: 1003 Vdc

field mppt_high: float [Required]

Maximum MPPT DC Voltage

  • Units: Vdc

  • Example value: 1200 Vdc

field paco: float [Required]

Maximum AC power

  • Units: Wac

  • Example value: 4198240 Wac

field vdco: float [Required]

Nominal DC Voltage

  • Units: Vdc

  • Example value: 1062 Vdc

field pnt: float [Required]

Standby/Nighttime power use

  • Units: Wac

  • Example value: 1259.47 Wac

field includes_xfmr: bool = False

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

Inputs related to the configuration of PV modules within their racking

field orientation: t.Optional[str] = None

The orientation of the PV modules within their racking.

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

  • Default is “portrait”

field vertical: t.Optional[int] = None

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

  • Default value is 2

field horizontal: t.Optional[int] = None

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

  • Default value is 48

field aspect_ratio: t.Optional[float] = None

The ratio of the module length to module width.

  • Default value is 1.7

class Transformer

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

field rating: t.Optional[float] = None

The transformer’s rated power capacity

  • Units: kW

  • Example value: 100000.0

field load_loss: float [Required]

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

field no_load_loss: float [Required]

The transformer’s constant loss factor (core losses)

  • Units: unitless

  • Recommended values:

    • HV transformer/GSU = 0.002

    • MV transformer = 0.001

class ACLosses

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

field ac_wiring: float = 0.01

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

  • Units: fraction

field transmission: float = 0.0

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

  • Units: fraction

field poi_adjustment: float = 0.0

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

field transformer_load: t.Optional[float] = None

Deprecated. Please use hv_transformer.

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

field transformer_no_load: t.Optional[float] = None

Deprecated. Please use hv_transformer.

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

field hv_transformer: t.Optional[Transformer] = None

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

field mv_transformer: t.Optional[Transformer] = None

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

class DCLosses

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

field dc_optimizer: float = 0.0

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

  • Units: fraction

  • Max value: 0.2

field enable_snow_model: bool = False

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

field dc_wiring: float = 0.02

Losses from DC wiring resistance within the array.

  • Units: fraction

  • Max value: 0.2

field soiling: conlist(float, min_length=12, max_length=12) [Optional]

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.

  • Units: fraction

  • Format as a list of 12 floats representing the decimal value of loss

  • Max value for each month: 0.2

field diodes_connections: float = 0.005

Losses from voltage drops of diodes and electrical connections.

  • Units: fraction

  • Max value: 0.2

field mismatch: float = 0.01

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

  • Max value: 0.2

field nameplate: float = 0.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

  • Example: A module with 405W nameplate power and +5W binning tolerance could be represented by a 400W module model and \(nameplate = 1 - (1 + 0.05/2)(405/400) = -0.0378\)

field rear_irradiance: float = 0.0

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

field mppt_error: float = 0.0

Deprecated (as well as misnamed). Use tracking_error instead

field tracking_error: float = 0.0

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

  • Units: fraction

field lid: float = 0.0

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

  • Units: fraction

field dc_array_adjustment: float = 0.0

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 Losses

Container class that combines ACLosses and DCLosses for use with PVGenerationModel

field ac_wiring: float = 0.01

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

  • Units: fraction

field transmission: float = 0.0

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

  • Units: fraction

field poi_adjustment: float = 0.0

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

field transformer_load: t.Optional[float] = None

Deprecated. Please use hv_transformer.

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

field transformer_no_load: t.Optional[float] = None

Deprecated. Please use hv_transformer.

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

field hv_transformer: t.Optional[Transformer] = None

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

field mv_transformer: t.Optional[Transformer] = None

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

field dc_optimizer: float = 0.0

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

  • Units: fraction

  • Max value: 0.2

field enable_snow_model: bool = False

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

field dc_wiring: float = 0.02

Losses from DC wiring resistance within the array.

  • Units: fraction

  • Max value: 0.2

field soiling: conlist(float, min_length=12, max_length=12) [Optional]

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.

  • Units: fraction

  • Format as a list of 12 floats representing the decimal value of loss

  • Max value for each month: 0.2

field diodes_connections: float = 0.005

Losses from voltage drops of diodes and electrical connections.

  • Units: fraction

  • Max value: 0.2

field mismatch: float = 0.01

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

  • Max value: 0.2

field nameplate: float = 0.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

  • Example: A module with 405W nameplate power and +5W binning tolerance could be represented by a 400W module model and \(nameplate = 1 - (1 + 0.05/2)(405/400) = -0.0378\)

field rear_irradiance: float = 0.0

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

field mppt_error: float = 0.0

Deprecated (as well as misnamed). Use tracking_error instead

field tracking_error: float = 0.0

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

  • Units: fraction

field lid: float = 0.0

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

  • Units: fraction

field dc_array_adjustment: float = 0.0

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

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

field power: t.List[float] [Required]

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].

field voltage: t.List[float] [Required]

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.

field ambient_temp: t.Optional[t.List[float]] = None

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

  • Units: - Units: °C

  • Example values: [25.0, 35.0, 45.0]

class BoundedSignal

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

field min: t.List[float] [Required]

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.

field actual: t.List[float] [Required]

Time series of the expected signal values. For example, for PV array power, this might be a time series of P50 production.

field max: t.List[float] [Required]

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.

class ACProductionProfile

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

field power: t.Union[t.List[float], BoundedSignal] [Required]

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

field ambient_temp: t.Optional[t.List[float]] = None

Hourly ambient temperature. Used for HVAC model if applicable.

  • Units: - Units: °C

  • Example values: [25.0, 35.0, 45.0]

class BaseSystemDesign

Base class for system design objects

field dc_capacity: float [Required]

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

  • Units: kWdc

  • Example: 1000.0 for a 1000 kWdc system

field ac_capacity: float [Required]

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

  • Units: kWac

  • Example: 1000.0 for a 1,000 kWac system

field poi_limit: float [Required]

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 PVSystemDesign

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

field modules_per_string: t.Optional[int] = None

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.

field strings_in_parallel: t.Optional[int] = None

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.

field tracking: TrackingTypes [Required]

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

field azimuth: t.Optional[float] = None

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

field gcr: float [Required]

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

field dc_capacity: float [Required]

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

  • Units: kWdc

  • Example: 1000.0 for a 1000 kWdc system

field ac_capacity: float [Required]

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

  • Units: kWac

  • Example: 1000.0 for a 1,000 kWac system

field poi_limit: float [Required]

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(value)

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(value)

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

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

field losses: ACLosses [Required]

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.

field system_design: BaseSystemDesign [Required]

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

field model_losses_from: Bus [Required]

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

field inverter: t.Optional[InverterTypes] = None

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

class ACExternalGenerationModel

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

field system_design: BaseSystemDesign [Required]

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

field project_type: t.Literal['generation'] = 'generation'

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

field time_interval_mins: int = 60

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

  • Units: minutes

field project_term: int = 1

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

field project_term_units: TermUnits = 'years'

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

field generation_type: t.Literal['ExternalAC'] = 'ExternalAC'

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

field losses: ACLosses = ACLosses(ac_wiring=0.01, transmission=0.0, poi_adjustment=0.0, transformer_load=None, transformer_no_load=None, hv_transformer=None, mv_transformer=None)

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

field production_override: ACProductionProfile [Required]

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

class DCExternalGenerationModel

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

field system_design: BaseSystemDesign [Required]

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

field project_type: t.Literal['generation'] = 'generation'

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

field time_interval_mins: int = 60

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

  • Units: minutes

field project_term: int = 1

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

field project_term_units: TermUnits = 'years'

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

field generation_type: t.Literal['ExternalDC'] = 'ExternalDC'

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

field 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=None, mv_transformer=None)

Submodel for system losses

field production_override: DCProductionProfile [Required]

Submodel for time series related to generator power.

  • Assumed to be at DC bus/inverter MPPT inputs

  • Assumed to include any aging/degradation effects

field inverter: InverterTypes [Required]

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(value)

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

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

field project_type: t.Literal['generation'] = 'generation'

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

field time_interval_mins: int = 60

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

  • Units: minutes

field project_term: int = 1

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

field project_term_units: TermUnits = 'years'

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

field generation_type: t.Literal['PV'] = 'PV'

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

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

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

field inverter: InverterTypes [Required]

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

field pv_module: PVModuleTypes [Required]

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

field layout: Layout = Layout(orientation=None, vertical=None, horizontal=None, aspect_ratio=None)

Inputs that describe module/racking geometry

field 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=None, mv_transformer=None)

Submodel for both array and AC-side losses

field system_design: PVSystemDesign [Required]

Inputs for system size and geometry

field array_degradation_rate: float = 0.005

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

field array_degradation_mode: t.Optional[ArrayDegradationMode] = ArrayDegradationMode.linear

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

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

field annual_capacity_derates: t.List[float] [Required]

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

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

field annual_efficiency_derates: t.List[float] [Required]

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

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

field container_temperature: float [Required]

Target temperature that BESS container is assumed to be maintained at

  • Units: °C

  • Example value: 25°C

field cop: float [Required]

The HVAC’s coefficient of performance.

  • Example value: 3.0

field u_ambient: float [Required]

The heat transfer coefficient between ambient and the container

  • Units: W/Km2

  • Example value: 100.0W/Km2

field discharge_efficiency_container: float [Required]

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

field charge_efficiency_container: float [Required]

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

field aux_xfmr_efficiency: float [Required]

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

  • Units: fraction

  • Example value: 0.99

field container_surface_area: float = 20.0

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: m2

  • Example value: 20.0

field design_energy_per_container: float = 750.0

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

Inputs for modeling the physical performance of a BESS

field power_capacity: float [Required]

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

field energy_capacity: float [Required]

The maximum usable capacity of the battery to store energy.

  • Units: kWh

  • Example value: 2000kWh

field charge_efficiency: t.Union[float, BoundedFloat] [Required]

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

field discharge_efficiency: t.Union[float, BoundedFloat] [Required]

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

field self_discharge_rate: t.Optional[float] = None

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

field parasitic_soe_loss: t.Optional[float] = None

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

  • Units: kW

  • Example value: 100kW

field degradation_rate: t.Optional[float] = None

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\\%\)

field degradation_annual_cycles: float = 261

Assumed number of annual cycles corresponding to degradation_rate. See degradation_rate for more details

field hvac: t.Optional[BatteryHVACParams] = None

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

field capacity_degradation_model: t.Optional[TableCapDegradationModel] = None

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

field efficiency_degradation_model: t.Optional[TableEffDegradationModel] = None

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

field term: t.Optional[float] = None

The number of years this specific battery will be active.

class EnergyStrategy(value)

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(value)

An enumeration.

dart_pq_qo = MarketConfig(da=<BidOfferStrategy.price_quantity: 'price-quantity'>, rt=<BidOfferStrategy.quantity_only: 'quantity-only'>)

Price-quantity bid-offers in DAM with quantity-only bid-offers in RTM

rt_redispatch_qo = MarketConfig(da=<BidOfferStrategy.awarded: 'awarded'>, rt=<BidOfferStrategy.quantity_only: 'quantity-only'>)

Quantity-only RTM bid-offers with DA & ancillaries already awarded.

class StorageSolverOptions

Inputs related to BESS market participation and optimization

field cycling_cost_adder: float = 0.0

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

field annual_cycle_limit: t.Optional[float] = None

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

field window: t.Optional[int] = None

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

field step: t.Optional[int] = None

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

field flexible_solar: bool = False

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.

field symmetric_reg: bool = False

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

field energy_strategy: t.Optional[t.Union[EnergyStrategy, MarketConfig]] = None

Specifies energy market participation strategy

field dart: t.Optional[bool] = None

Deprecated, use energy_strategy to specify co-optimization

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

  • Default value: False

field no_virtual_trades: bool = False

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

field initial_soe: t.Union[float, BoundedFloat] = 0.0

State-of-Energy of BESS at beginning of simulation as a fraction of BESS energy capacity

field duration_requirement_on_discharge: bool = True

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.

field no_stop_offers: bool = False

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.

field rtm_bp_tol: t.Optional[float] = None

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.

class MultiStorageInputs

Inputs related to BESS design, market participation and optimization

field cycling_cost_adder: float = 0.0

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

field annual_cycle_limit: t.Optional[float] = None

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

field window: t.Optional[int] = None

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

field step: t.Optional[int] = None

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

field flexible_solar: bool = False

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.

field symmetric_reg: bool = False

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

field energy_strategy: t.Optional[t.Union[EnergyStrategy, MarketConfig]] = None

Specifies energy market participation strategy

field dart: t.Optional[bool] = None

Deprecated, use energy_strategy to specify co-optimization

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

  • Default value: False

field no_virtual_trades: bool = False

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

field initial_soe: t.Union[float, BoundedFloat] = 0.0

State-of-Energy of BESS at beginning of simulation as a fraction of BESS energy capacity

field duration_requirement_on_discharge: bool = True

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.

field no_stop_offers: bool = False

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.

field rtm_bp_tol: t.Optional[float] = None

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.

field batteries: t.List[BatteryParams] [Required]

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

Inputs that describe peak to be reduced as part of LoadPeakReduction

field mask: t.List[bool] [Required]

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

field price: float [Required]

Price to be applied to the peak load calculated for all the time intervals defined by mask

class LoadPeakReduction

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

field load: t.List[float] [Required]

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

field max_load: t.List[float] [Required]

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.

field 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.

field 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

Simulation class for hybrid simulations. PVStorageModelResults is the results schema

field import_limit: t.Optional[t.List[float]] = None

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,]

field export_limit: t.Optional[t.List[float]] = None

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,]

field energy_prices: t.Union[DARTPrices, t.List[float], DARTPriceScenarios] [Required]

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

field storage_inputs: MultiStorageInputs [Required]

Submodel for BESS design, market participation and optimization

field reserve_markets: t.Optional[ReserveMarkets] = None

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

field time_interval_mins: int = 60

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

field load_peak_reduction: t.Optional[LoadPeakReduction] = None

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

field project_type: t.Literal['hybrid'] = 'hybrid'

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

field storage_coupling: StorageCoupling [Required]

Specify the point at which the BESS and generation source are coupled

field pv_inputs: GenerationModel [Required]

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

field enable_grid_charge_year: t.Optional[float] = None

Simulation year in which to allow grid charging. Currently, many hybrid systems are not allowed to charge from the grid, but are expected to be able to sometime in the future

field solar_revenue_adder: t.Optional[t.Union[t.List[float], float]] = None

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

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

field project_term: int = 1

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

field project_term_units: TermUnits = 'years'

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

field import_limit: t.Optional[t.List[float]] = None

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,]

field export_limit: t.Optional[t.List[float]] = None

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,]

field energy_prices: t.Union[DARTPrices, t.List[float], DARTPriceScenarios] [Required]

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

field storage_inputs: MultiStorageInputs [Required]

Submodel for BESS design, market participation and optimization

field reserve_markets: t.Optional[ReserveMarkets] = None

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

field time_interval_mins: int = 60

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

field load_peak_reduction: t.Optional[LoadPeakReduction] = None

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

field project_type: t.Literal['storage'] = 'storage'

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

field downstream_system: t.Optional[DownstreamSystem] = None

Optional submodel for detailed treatment of losses. The point at which detailed losses are considered can be controlled with DownstreamSystem.model_losses_from

field ambient_temp: t.Optional[t.Union[t.List[float], SolarResourceLocation]] = None

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(value)

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)

class SolarTimeSeries

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

field ideal_tracker_rotation: t.Optional[list] = None

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

field front_total_poa: t.Optional[list] = None

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

field rear_total_poa: t.Optional[list] = None

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

field effective_total_poa: t.Optional[list] = None

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}\)

field array_dc_snow_loss: t.Optional[list] = None

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.

field array_gross_dc_power: t.Optional[list] = None

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)

field array_dc_power: t.Optional[list] = None

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).

field array_dc_voltage: t.Optional[list] = None

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).

field inverter_mppt_dc_voltage: t.Optional[list] = None

Deprecated, instead use array_dc_voltage.

field inverter_mppt_loss: t.Optional[list] = None

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.

field inverter_clipping_loss: t.Optional[list] = None

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

field inverter_night_tare_loss: t.Optional[list] = None

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

field inverter_power_consumption_loss: t.Optional[list] = None

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.

field inverter_efficiency: t.Optional[list] = None

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

field ambient_temp: t.Optional[list] = None

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

field gross_ac_power: list [Required]

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

  • Units: kW

field mv_transformer_loss: t.Optional[list] = None

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

field mv_transformer_load_loss: t.Optional[list] = None

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

field mv_transformer_no_load_loss: t.Optional[list] = None

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

field mv_ac_power: list [Required]

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

field ac_wiring_loss: list [Required]

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

field hv_transformer_loss: t.Optional[list] = None

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.

field hv_transformer_load_loss: t.Optional[list] = None

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

field hv_transformer_no_load_loss: t.Optional[list] = None

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

field transformer_load_loss: list [Required]

Deprecated, see hv_transformer_load_loss.

field transformer_no_load_loss: list [Required]

Deprecated, see hv_transformer_no_load_loss.

field hv_ac_power: list [Required]

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

field ac_transmission_loss: list [Required]

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

field gen: list [Required]

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

field poi_unadjusted: list [Required]

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

  • Units: kW

field system_power: list [Required]

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

  • Units: kW

field positive_system_power: list [Required]

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

field negative_system_power: list [Required]

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

field sam_design_parameters: dict [Required]

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.

class SolarWaterfall

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.

field gh_ann: t.Optional[float] = None

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

field nominal_poa_ann: t.Optional[float] = None

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

field shading_lp: t.Optional[float] = None

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”)

field soiling_lp: t.Optional[float] = None

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

field reflection_lp: t.Optional[float] = None

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

field bifacial_lp: t.Optional[float] = None

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).

field dc_nominal_ann: t.Optional[float] = None

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

field snow_lp: t.Optional[float] = None

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

field module_temp_lp: t.Optional[float] = None

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”)

field mppt_lp: t.Optional[float] = None

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.

field mismatch_lp: t.Optional[float] = None

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

field diodes_lp: t.Optional[float] = None

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

field dc_wiring_lp: t.Optional[float] = None

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

field tracking_error_lp: t.Optional[float] = None

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

field mppt_error_lp: t.Optional[float] = None

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

field nameplate_lp: t.Optional[float] = None

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.

field dc_optimizer_lp: t.Optional[float] = None

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

field dc_avail_lp: t.Optional[float] = None

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.

field dc_net_ann: t.Optional[float] = None

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).

field inverter_clipping_lp: t.Optional[float] = None

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.

field inverter_consumption_lp: t.Optional[float] = None

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.

field inverter_nightcons_lp: t.Optional[float] = None

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

field inverter_efficiency_lp: t.Optional[float] = None

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.

field ac_gross_ann: float [Required]

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

field mv_transformer_lp: float [Required]

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

  • Units: unitless fraction

field ac_wiring_lp: float [Required]

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

field hv_transformer_lp: float [Required]

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

  • Units: unitless fraction

field transformer_lp: float [Required]

Deprecated, see :attr: hv_transformer_lp.

  • Units: unitless fraction

field transmission_lp: float [Required]

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

field poi_clipping_lp: float [Required]

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

field ac_availcurtail_lp: float [Required]

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

  • Units: unitless fraction

field annual_energy: float [Required]

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

  • Units: kWh

class SolarStorageTimeSeries

Power flow-related time series results for hybrid simulations

field battery_internal_energy: list [Required]

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

field battery_internal_energy_max: list [Required]

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

field battery_limit: t.Union[float, list] [Required]

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.

field battery_output: list [Required]

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

field excess_power_at_coupling: list [Required]

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

field captured_excess_at_coupling: list [Required]

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

field solar_storage_dc_voltage: t.Optional[list] = None

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)

field solar_storage_dc_power: t.Optional[list] = None

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)

field solar_storage_power_at_coupling: list [Required]

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.

field inverter_clipping_loss: t.Optional[list] = None

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

field inverter_tare_loss: t.Optional[list] = None

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

field inverter_parasitic_loss: t.Optional[list] = None

Duplicate of inverter_tare_loss

field inverter_consumption_loss: t.Optional[list] = None

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.

field inverter_efficiency: t.Optional[list] = None

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

field solar_storage_gross_ac_power: t.Optional[list] = None

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

field mv_xfmr_loss: t.Optional[list] = None

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

field mv_xfmr_load_loss: t.Optional[list] = None

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

field mv_xfmr_no_load_loss: t.Optional[list] = None

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

field solar_storage_ac_power: list [Required]

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

field solar_storage_mv_ac_power: t.Optional[list] = None

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

field hvac_loss: t.Optional[list] = None

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

field ac_wiring_loss: t.Optional[list] = None

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.

field hv_xfmr_loss: t.Optional[list] = None

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.

field hv_xfmr_load_loss: t.Optional[list] = None

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

field hv_xfmr_no_load_loss: t.Optional[list] = None

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

field transformer_loss: t.Optional[list] = None

Deprecated, see :attr: hv_xfmr_loss.

field solar_storage_hv_ac_power: list [Required]

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

field transmission_loss: list [Required]

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

field solar_storage_gen: list [Required]

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

field solar_storage_poi_unadjusted: list [Required]

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

  • Units: kW

field solar_storage_poi: list [Required]

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

  • Units: kW

field positive_solar_storage_poi: list [Required]

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

  • Units: kW

field negative_solar_storage_poi: list [Required]

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

  • Units: kW

class SolarStorageWaterfall

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.

field battery_operation_lp: float [Required]

Annual fractional energy impact due to operation of the BESS

  • Units: unitless fraction

field excess_power_at_coupling_lp: float [Required]

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

field captured_excess_at_coupling_lp: float [Required]

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

field bess_hvac_lp: t.Optional[float] = None

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

field gh_ann: t.Optional[float] = None

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

field nominal_poa_ann: t.Optional[float] = None

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

field shading_lp: t.Optional[float] = None

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”)

field soiling_lp: t.Optional[float] = None

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

field reflection_lp: t.Optional[float] = None

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

field bifacial_lp: t.Optional[float] = None

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).

field dc_nominal_ann: t.Optional[float] = None

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

field snow_lp: t.Optional[float] = None

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

field module_temp_lp: t.Optional[float] = None

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”)

field mppt_lp: t.Optional[float] = None

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.

field mismatch_lp: t.Optional[float] = None

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

field diodes_lp: t.Optional[float] = None

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

field dc_wiring_lp: t.Optional[float] = None

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

field tracking_error_lp: t.Optional[float] = None

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

field mppt_error_lp: t.Optional[float] = None

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

field nameplate_lp: t.Optional[float] = None

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.

field dc_optimizer_lp: t.Optional[float] = None

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

field dc_avail_lp: t.Optional[float] = None

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.

field dc_net_ann: t.Optional[float] = None

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).

field inverter_clipping_lp: t.Optional[float] = None

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.

field inverter_consumption_lp: t.Optional[float] = None

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.

field inverter_nightcons_lp: t.Optional[float] = None

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

field inverter_efficiency_lp: t.Optional[float] = None

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.

field ac_gross_ann: float [Required]

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

field mv_transformer_lp: float [Required]

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

  • Units: unitless fraction

field ac_wiring_lp: float [Required]

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

field hv_transformer_lp: float [Required]

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

  • Units: unitless fraction

field transformer_lp: float [Required]

Deprecated, see :attr: hv_transformer_lp.

  • Units: unitless fraction

field transmission_lp: float [Required]

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

field poi_clipping_lp: float [Required]

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

field ac_availcurtail_lp: float [Required]

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

  • Units: unitless fraction

field annual_energy: float [Required]

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

  • Units: kWh

class OptimizerTimeSeries

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).

field hvac_loss: t.Optional[list] = None

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.

field import_limit_at_coupling: t.Optional[list] = None

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

field export_limit_at_coupling: t.Optional[list] = None

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

field target_load: t.Optional[list] = None

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.

field charge_actual: list [Required]

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

field discharge_actual: list [Required]

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

field charge: list [Required]

Duplicate of charge_actual

field discharge: list [Required]

Duplicate of discharge_actual

field charge_hi: list [Required]

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

field discharge_hi: list [Required]

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

field charge_lo: list [Required]

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

field discharge_lo: list [Required]

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

field battery_output: list [Required]

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

field output: list [Required]

Duplicate of battery_output

field total_output: list [Required]

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.

field internal_energy: list [Required]

Duplicate of soe_actual

field soe_actual: list [Required]

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

field soe_lo: list [Required]

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

field soe_hi: list [Required]

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

field soe_hb_actual: list [Required]

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

field soe_hb_lo: list [Required]

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

field soe_hb_hi: list [Required]

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

field soe_mean_actual: list [Required]

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

field soe_mean_lo: list [Required]

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

field soe_mean_hi: list [Required]

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

field dam_charge: t.Optional[list] = None

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)

field dam_discharge: t.Optional[list] = None

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)

field dam_solar: t.Optional[list] = None

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

  • Units: kW

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

field dam_base_point: t.Optional[list] = None

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)

field rtm_charge: t.Optional[list] = None

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)

field rtm_discharge: t.Optional[list] = None

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)

field rtm_solar: t.Optional[list] = None

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

  • Units: kW

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

field rtm_base_point: t.Optional[list] = None

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)

field rtm_price: t.Optional[list] = None

Real-time market (RTM) prices. Equivalent to the rtm input, but included in the results for convenience.

field dam_price: t.Optional[list] = None

Day Ahead Market (DAM) prices. Equivalent to the dam input, but included in the results for convenience.

field imbalance: t.Optional[list] = None

Imbalance market prices. Equivalent to the imbalance input, but included in the results for convenience.

field theoretical_dam_soe: t.Optional[list] = None

Theoretical energy that would be stored in the BESS based solely on Day Ahead Market (DAM) participation. Associated with constraint that DAM participation be physically realistic when participating in both DAM and Real Time Markets (RTM).

  • Units: kWh

  • Only generated when modeling DAM participation

field solar_actual: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field solar_hi: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field solar_lo: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field net_load: t.Optional[list] = None

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.

field RESERVE_MARKET_price: t.Optional[list] = None

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

field RESERVE_MARKET_offer: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_max: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_min: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_actual: t.Optional[list] = None

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

field RESERVE_MARKET_realized: t.Optional[list] = None

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

field RESERVE_MARKET_flex_offer: t.Optional[list] = None

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

field RESERVE_MARKET_flex_max: t.Optional[list] = None

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

field RESERVE_MARKET_flex_min: t.Optional[list] = None

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

field RESERVE_MARKET_flex_actual: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_max: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_min: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_max: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_min: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_charge_max: t.Optional[list] = None

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

field RESERVE_MARKET_charge_min: t.Optional[list] = None

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

field RESERVE_MARKET_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_max: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_min: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_actual: t.Optional[list] = None

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

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

field charge: list [Required]

Equivalent to OptimizerTimeSeries.charge_actual but corrected to represent charge power at the point of interconnection (POI).

  • Units: kW

field discharge: list [Required]

Equivalent to OptimizerTimeSeries.discharge_actual but corrected to represent discharge power at the point of interconnection (POI).

  • Units: kW

field total_output: list [Required]

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

field rt_tare: list [Required]

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

field dam_charge: list [Required]

Equivalent to OptimizerTimeSeries.dam_charge but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field dam_discharge: list [Required]

Equivalent to OptimizerTimeSeries.dam_discharge but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field dam_base_point: list [Required]

Equivalent to OptimizerTimeSeries.dam_base_point but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field negative_dam_base_point: list [Required]

Negative of dam_base_point.

  • Units: kW

field rtm_charge: list [Required]

Equivalent to OptimizerTimeSeries.rtm_charge but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field rtm_discharge: list [Required]

Equivalent to OptimizerTimeSeries.rtm_discharge but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field rtm_base_point: list [Required]

Equivalent to OptimizerTimeSeries.rtm_base_point but corrected to represent settlement at the point of interconnection (POI).

  • Units: kW

field solar_actual: t.Optional[list] = None

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.

field dam_solar: t.Optional[list] = None

Equivalent to OptimizerTimeSeries.dam_solar but corrected to represent settlement at the point of interconnection (POI).

field rtm_solar: t.Optional[list] = None

Equivalent to OptimizerTimeSeries.rtm_solar but corrected to represent settlement at the point of interconnection (POI).

field RESERVE_MARKET_offer: t.Optional[list] = None

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

field RESERVE_MARKET_realized: t.Optional[list] = None

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

field RESERVE_MARKET_flex_actual: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_actual: t.Optional[list] = None

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

Time series results for standalone storage simulations where downstream_system is not None

field battery_internal_energy: list [Required]

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

field battery_internal_energy_max: list [Required]

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

field battery_limit: t.Union[float, list] [Required]

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.

field battery_output: list [Required]

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

field dc_power: t.Optional[list] = None

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)

field dc_voltage: t.Optional[list] = None

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)

field inverter_clipping_loss: t.Optional[list] = None

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

field inverter_tare_loss: t.Optional[list] = None

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

field inverter_parasitic_loss: t.Optional[list] = None

Duplicate of inverter_tare_loss

field inverter_consumption_loss: t.Optional[list] = None

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.

field inverter_efficiency: t.Optional[list] = None

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

field gross_ac_power: t.Optional[list] = None

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

field mv_xfmr_loss: t.Optional[list] = None

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

field mv_xfmr_load_loss: t.Optional[list] = None

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

field mv_xfmr_no_load_loss: t.Optional[list] = None

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

field ac_power: list [Required]

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

field mv_ac_power: t.Optional[list] = None

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

  • Units: kW

field hvac_loss: t.Optional[list] = None

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

field ac_wiring_loss: t.Optional[list] = None

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.

field hv_xfmr_loss: t.Optional[list] = None

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.

field hv_xfmr_load_loss: t.Optional[list] = None

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

field hv_xfmr_no_load_loss: t.Optional[list] = None

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

field transformer_loss: t.Optional[list] = None

Deprecated, see :attr: hv_xfmr_loss.

field hv_ac_power: list [Required]

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

field transmission_loss: list [Required]

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

field gen: list [Required]

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

field poi_unadjusted: list [Required]

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

  • Units: kW

field poi: list [Required]

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

  • Units: kW

field positive_poi: list [Required]

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

  • Units: kW

field negative_poi: list [Required]

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

  • Units: kW

class GenerationModelResults

Results schema returned when a PVGenerationModel, ACExternalGenerationModel or DCExternalGenerationModel simulation is run

field ideal_tracker_rotation: t.Optional[list] = None

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

field front_total_poa: t.Optional[list] = None

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

field rear_total_poa: t.Optional[list] = None

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

field effective_total_poa: t.Optional[list] = None

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}\)

field array_dc_snow_loss: t.Optional[list] = None

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.

field array_gross_dc_power: t.Optional[list] = None

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)

field array_dc_power: t.Optional[list] = None

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).

field array_dc_voltage: t.Optional[list] = None

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).

field inverter_mppt_dc_voltage: t.Optional[list] = None

Deprecated, instead use array_dc_voltage.

field inverter_mppt_loss: t.Optional[list] = None

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.

field inverter_clipping_loss: t.Optional[list] = None

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

field inverter_night_tare_loss: t.Optional[list] = None

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

field inverter_power_consumption_loss: t.Optional[list] = None

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.

field inverter_efficiency: t.Optional[list] = None

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

field ambient_temp: t.Optional[list] = None

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

field gross_ac_power: list [Required]

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

  • Units: kW

field mv_transformer_loss: t.Optional[list] = None

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

field mv_transformer_load_loss: t.Optional[list] = None

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

field mv_transformer_no_load_loss: t.Optional[list] = None

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

field mv_ac_power: list [Required]

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

field ac_wiring_loss: list [Required]

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

field hv_transformer_loss: t.Optional[list] = None

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.

field hv_transformer_load_loss: t.Optional[list] = None

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

field hv_transformer_no_load_loss: t.Optional[list] = None

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

field transformer_load_loss: list [Required]

Deprecated, see hv_transformer_load_loss.

field transformer_no_load_loss: list [Required]

Deprecated, see hv_transformer_no_load_loss.

field hv_ac_power: list [Required]

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

field ac_transmission_loss: list [Required]

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

field gen: list [Required]

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

field poi_unadjusted: list [Required]

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

  • Units: kW

field system_power: list [Required]

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

  • Units: kW

field positive_system_power: list [Required]

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

field negative_system_power: list [Required]

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

field sam_design_parameters: dict [Required]

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.

field tyba_api_loss_waterfall: SolarWaterfall [Required]

Waterfall-style loss data for first year (8760 hours) or results

field warnings: t.List[str] [Required]

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.

field coupling: None [Required]

Key used internally. coupling equal to None indicates that the simulation is PV- (or generation) only and does not consider storage.

time_series_df()
class PVStorageModelResults

Results schema returned when a PVStorageModel simulation is run

field solar_only: SolarTimeSeries [Required]

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

field solar_storage: SolarStorageTimeSeries [Required]

Power flow-related time series results

field waterfall: SolarStorageWaterfall [Required]

Waterfall-style loss data for first year (8760 hours) or results

field optimizer: OptimizerTimeSeries [Required]

Time series results associated with BESS optimization and operation

field market_awards: t.Optional[MarketAwardsTimeSeries] = None

Time series results intended to represent market awards for use in revenue calculation

field warnings: t.List[str] [Required]

List of warnings generated during simulations. See GenerationModelResults.warnings for more information

field coupling: str [Required]

Key used internally. Reflects the storage_coupling input

time_series_df()
class StandaloneStorageModelWithDownstreamResults

Results schema returned when a StandaloneStorageModel simulation is run with a downstream_system specified

field system: StandaloneStorageSystemTimeSeries [Required]

Power flow-related time series results

field optimizer_outputs: OptimizerTimeSeries [Required]

Time series results associated with BESS optimization and operation

field market_awards: t.Optional[MarketAwardsTimeSeries] = None

Time series results intended to represent market awards for use in revenue calculation

time_series_df()
class StandaloneStorageModelSimpleResults

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).

field hvac_loss: t.Optional[list] = None

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.

field import_limit_at_coupling: t.Optional[list] = None

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

field export_limit_at_coupling: t.Optional[list] = None

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

field target_load: t.Optional[list] = None

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.

field charge_actual: list [Required]

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

field discharge_actual: list [Required]

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

field charge: list [Required]

Duplicate of charge_actual

field discharge: list [Required]

Duplicate of discharge_actual

field charge_hi: list [Required]

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

field discharge_hi: list [Required]

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

field charge_lo: list [Required]

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

field discharge_lo: list [Required]

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

field battery_output: list [Required]

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

field output: list [Required]

Duplicate of battery_output

field total_output: list [Required]

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.

field internal_energy: list [Required]

Duplicate of soe_actual

field soe_actual: list [Required]

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

field soe_lo: list [Required]

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

field soe_hi: list [Required]

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

field soe_hb_actual: list [Required]

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

field soe_hb_lo: list [Required]

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

field soe_hb_hi: list [Required]

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

field soe_mean_actual: list [Required]

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

field soe_mean_lo: list [Required]

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

field soe_mean_hi: list [Required]

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

field dam_charge: t.Optional[list] = None

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)

field dam_discharge: t.Optional[list] = None

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)

field dam_solar: t.Optional[list] = None

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

  • Units: kW

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

field dam_base_point: t.Optional[list] = None

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)

field rtm_charge: t.Optional[list] = None

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)

field rtm_discharge: t.Optional[list] = None

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)

field rtm_solar: t.Optional[list] = None

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

  • Units: kW

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

field rtm_base_point: t.Optional[list] = None

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)

field rtm_price: t.Optional[list] = None

Real-time market (RTM) prices. Equivalent to the rtm input, but included in the results for convenience.

field dam_price: t.Optional[list] = None

Day Ahead Market (DAM) prices. Equivalent to the dam input, but included in the results for convenience.

field imbalance: t.Optional[list] = None

Imbalance market prices. Equivalent to the imbalance input, but included in the results for convenience.

field theoretical_dam_soe: t.Optional[list] = None

Theoretical energy that would be stored in the BESS based solely on Day Ahead Market (DAM) participation. Associated with constraint that DAM participation be physically realistic when participating in both DAM and Real Time Markets (RTM).

  • Units: kWh

  • Only generated when modeling DAM participation

field solar_actual: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field solar_hi: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field solar_lo: t.Optional[list] = None

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.generation_models.PVStorageModel.solar_revenue_adder and (2) if solar participates in reserve markets (i.e. flexible_solar is True)

field net_load: t.Optional[list] = None

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.

field RESERVE_MARKET_price: t.Optional[list] = None

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

field RESERVE_MARKET_offer: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_max: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_min: t.Optional[list] = None

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

field RESERVE_MARKET_utilized_actual: t.Optional[list] = None

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

field RESERVE_MARKET_realized: t.Optional[list] = None

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

field RESERVE_MARKET_flex_offer: t.Optional[list] = None

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

field RESERVE_MARKET_flex_max: t.Optional[list] = None

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

field RESERVE_MARKET_flex_min: t.Optional[list] = None

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

field RESERVE_MARKET_flex_actual: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_max: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_min: t.Optional[list] = None

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

field RESERVE_MARKET_discharge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_max: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_min: t.Optional[list] = None

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

field RESERVE_MARKET_stop_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_charge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_charge_max: t.Optional[list] = None

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

field RESERVE_MARKET_charge_min: t.Optional[list] = None

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

field RESERVE_MARKET_charge_actual: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_offer: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_max: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_min: t.Optional[list] = None

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

field RESERVE_MARKET_stop_discharge_actual: t.Optional[list] = None

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

time_series_df()

V2 Results Schema (in progress)

class BusTimeSeries
field power: t.List[kW] [Required]
class DCBusTimeSeries
field voltage: t.List[V] [Required]
field power: t.List[kW] [Required]
class InverterTimeSeries
field clipping_loss: t.List[kW] [Required]
field efficiency: t.List[dec] [Required]
field tare_loss: t.List[kW] [Required]
field consumption_loss: t.List[kW] [Required]
class TransformerTimeSeries
field total_loss: t.List[kW] [Required]
field load_loss: t.Optional[t.List[kW]] = None
field no_load_loss: t.Optional[t.List[kW]] = None
class ACWiringTimeSeries
field loss: t.List[kW] [Required]
class TransmissionTimeSeries
field loss: t.List[kW] [Required]
class POITimeSeries
field power_pre_clip: t.List[kW] [Required]
field power_pre_adjustment: t.List[kW] [Required]
field power: t.List[kW] [Required]
field power_positive: t.List[kW] [Required]
field power_negative: t.List[kW] [Required]
class PVTimeSeries
field ghi: t.List[Wm2] [Required]
field tracker_rotation_angle: t.Optional[t.List[deg]] = None
field front_poa_nominal: t.Optional[t.List[Wm2]] = None
field front_poa_shaded: t.Optional[t.List[Wm2]] = None
field front_poa_shaded_soiled: t.Optional[t.List[Wm2]] = None
field front_poa: t.List[Wm2] [Required]
field rear_poa: t.List[Wm2] [Required]
field poa_effective: t.List[Wm2] [Required]
field poa_effective_power: t.Optional[t.List[kW]] = None
field cell_temperature_quasi_steady: t.Optional[t.List[degC]] = None
field cell_temperature: t.Optional[t.List[degC]] = None
field module_efficiency: t.Optional[t.List[dec]] = None
field dc_shading_loss: t.Optional[t.List[kW]] = None
field dc_snow_loss: t.Optional[t.List[kW]] = None
field mppt_window_loss: t.Optional[t.List[kW]] = None
field gross_dc_power: t.List[kW] [Required]
field dc_power_undegraded: t.Optional[t.List[kW]] = None
field dc_power: t.Optional[t.List[kW]] = None
field dc_voltage: t.Optional[t.List[V]] = None
class GenerationYear1Waterfall
field ghi: t.Optional[Whm2] = None
field front_transposition: t.Optional[dec] = None
field front_shading: t.Optional[dec] = None
field front_soiling: t.Optional[dec] = None
field front_iam: t.Optional[dec] = None
field rear_poa: t.Optional[dec] = None
field rear_bifaciality: t.Optional[dec] = None
field poa_effective: t.Optional[Whm2] = None
field array_area: t.Optional[m2] = None
field poa_effective_energy: t.Optional[kWh] = None
field stc_pv_module_effeciency: t.Optional[dec] = None
field pv_dc_nominal_energy: t.Optional[kWh] = None
field non_stc_irradiance_temperature: t.Optional[dec] = None

this includes DC derate due to beam shading (electrical effect), will be broken out in the future

field mppt_clip: t.Optional[dec] = None
field snow: t.Optional[dec] = None
field pv_dc_gross_energy: t.Optional[kWh] = None
field nameplate: t.Optional[dec] = None
field lid: t.Optional[dec] = None
field mismatch: t.Optional[dec] = None
field diodes: t.Optional[dec] = None
field dc_optimizer: t.Optional[dec] = None
field tracking_error: t.Optional[dec] = None
field dc_wiring: t.Optional[dec] = None
field dc_adjustment: t.Optional[dec] = None
field dc_bus_energy: t.Optional[kWh] = None
field inverter_clipping: t.Optional[dec] = None
field inverter_consumption: t.Optional[dec] = None
field inverter_tare: t.Optional[dec] = None
field inverter_efficiency: t.Optional[dec] = None
field lv_bus_energy: t.Optional[kWh] = None
field mv_transformer: t.Optional[dec] = None
field mv_bus_energy: t.Optional[kWh] = None
field ac_wiring: t.Optional[dec] = None
field hv_transformer: t.Optional[dec] = None
field export_bus_energy: kWh [Required]
field transmission: dec [Required]
field poi_clipping: dec [Required]
field poi_adjustment: dec [Required]
field poi_energy: kWh [Required]
class GenerationPowerFlowTimeSeries
field pv: t.Optional[PVTimeSeries] = None
field dc_bus: t.Optional[DCBusTimeSeries] = None
field inverter: t.Optional[InverterTimeSeries] = None
field lv_bus: t.Optional[BusTimeSeries] = None
field mv_xfmr: t.Optional[TransformerTimeSeries] = None
field mv_bus: t.Optional[BusTimeSeries] = None
field ac_wiring: t.Optional[ACWiringTimeSeries] = None
field hv_xfmr: t.Optional[TransformerTimeSeries] = None
field export_bus: BusTimeSeries [Required]
field transmission: TransmissionTimeSeries [Required]
field poi: POITimeSeries [Required]
class GenerationModelResults

Results schema returned when a PVGenerationModel, ACExternalGenerationModel or DCExternalGenerationModel simulation is run

field power_flow: GenerationPowerFlowTimeSeries [Required]
field waterfall: GenerationYear1Waterfall [Required]
field sam_raw: t.Optional[dict] = None
field solar_resource: t.Optional[SolarResource] = None
field warnings: t.Optional[t.List[str]] = None