Model Schema

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: Literal['SAT'] | None = '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: Literal['FT'] | None = '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: 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: 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: 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: 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: ScalarUtilization | TimeSeriesUtilization | BudgetUtilization [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: List[float] | None = 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: Dict[str, ReserveMarket] | None = 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: Dict[str, ReserveMarket] | None = 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: ConstrainedListValue[float] [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

Constraints:

  • minItems = 1

field dam: ConstrainedListValue[float] [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

Constraints:

  • minItems = 1

field imbalance: ConstrainedListValue[float] | None = 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

Constraints:

  • minItems = 1

field rtorpa: ConstrainedListValue[float] | None = None

Deprecated, replaced with imbalance

Constraints:

  • minItems = 1

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: List[int] [Required]

Year value of the interval-beginning timestamp

  • 4 digit integer.

field month: List[int] [Required]

Month value of interval-beginning timestamp

  • Possible values: 1-12.

field day: List[int] [Required]

Day value of interval-beginning timestamp

  • Possible values: 1-31

field hour: List[int] [Required]

Hour value of interval-beginning timestamp

  • Possible values: 0-23

field minute: 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: List[float] [Required]

Dew point temperature

  • Units: °C

field df: List[float] [Required]

Diffuse Horizontal Irradiance

  • Units: W/m2

field dn: List[float] [Required]

Direct Normal Irradiance

  • Units: W/m2

field gh: List[float] [Required]

Global Horizontal Irradiance

  • Units: W/m2

field pres: List[float] [Required]

Ambient pressure

  • Units: milibar

field tdry: List[float] [Required]

Ambient Temperature (dry bulb)

  • Units: °C

field wdir: List[float] [Required]

Wind direction

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

field wspd: List[float] [Required]

Wind speed

  • Units: meter per second

field alb: List[float] | None = None

Surface albedo

  • Units: ratio of reflected GHI

  • Default value is 0.2

field snow: List[float] | None = 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: List[float] | None = 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: List[float] | None = 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: List[float] | None = 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: float | None = 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: 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: 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: 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: 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: 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: 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: float | None = None

Additional losses applied after efficiency and temperature derate when DC power is above aux_loss_threshold. This can be used to represent e.g. fan losses and should be based on manufacturer recommendations.

  • Units: W

  • Example value: 100.0

field aux_loss_threshold: float | None = 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: str | None = 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: int | None = None

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

  • Default value is 2

field horizontal: int | None = None

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

  • Default value is 48

field aspect_ratio: float | None = 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: float | None = 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. For example, use this input to apply a constant haircut to model system availability

  • Negative values can be used to represent power gains

  • Units: fraction

field transformer_load: float | None = None

Deprecated. Please use hv_transformer.

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

field transformer_no_load: float | None = None

Deprecated. Please use hv_transformer.

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

field hv_transformer: Transformer | None = 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: Transformer | None = 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: List[float] [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.

  • 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, and mismatch

  • 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. For example, use this input to apply a constant haircut to model system availability

  • Negative values can be used to represent power gains

  • Units: fraction

field transformer_load: float | None = None

Deprecated. Please use hv_transformer.

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

field transformer_no_load: float | None = None

Deprecated. Please use hv_transformer.

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

field hv_transformer: Transformer | None = 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: Transformer | None = 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: List[float] [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.

  • 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, and mismatch

  • 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: 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: 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: List[float] | None = 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 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: List[float] [Required]

The power at the MV AC bus (i.e. where a MV BESS system would tie-in)

  • 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: List[float] | None = 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: int | None = 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: int | None = 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: FixedTilt | SingleAxisTracking [Required]

A sub-model to represent the PV racking design

field azimuth: float | None = 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: Inverter | ONDInverter | str | FileComponent | None = None

Submodel for inverter used in system design. Required if model_losses_from is “DC”, otherwise ignored

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, GenerationModelResultsV0 is the results schema

field generation_type: Literal['ExternalAC'] | None = '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

field system_design: BaseSystemDesign [Required]

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

field project_type: Literal['generation'] | None = '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

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, GenerationModelResultsV0 is the results schema

field generation_type: Literal['ExternalDC'] | None = '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: Inverter | ONDInverter | str | FileComponent [Required]

Submodel for inverter to be used with generation source

field system_design: BaseSystemDesign [Required]

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

field project_type: Literal['generation'] | None = '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

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, GenerationModelResultsV0 is the results schema

field generation_type: Literal['PV'] | None = 'PV'

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

field solar_resource: SolarResource | 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="North America"

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

field inverter: Inverter | ONDInverter | str | FileComponent [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: PVModuleCEC | PVModuleMermoudLejeune | str | FileComponent [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: ArrayDegradationMode | None = 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

field project_type: Literal['generation'] | None = '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

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: 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: 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: 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: 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: float | None = 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 degradation_rate: float | None = 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 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: BatteryHVACParams | None = None

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

field capacity_degradation_model: TableCapDegradationModel | None = 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: TableEffDegradationModel | None = 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: float | None = 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 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: 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: 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: 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: EnergyStrategy | MarketConfig | None = None

Specifies energy market participation strategy

field dart: bool | None = 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: 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.

class MultiStorageInputs

Inputs related to BESS design, market participation and optimization

field batteries: List[BatteryParams] [Required]

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

  • Each BatteryParam 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.

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: 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: 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: 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: EnergyStrategy | MarketConfig | None = None

Specifies energy market participation strategy

field dart: bool | None = 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: 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.

class PVStorageModel

Simulation class for hybrid simulations. PVStorageModelResultsV0 is the results schema

field project_type: Literal['hybrid'] | None = 'hybrid'

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

field storage_inputs: MultiStorageInputs [Required]

Submodel for BESS design, market participation and optimization

field storage_coupling: StorageCoupling [Required]

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

field pv_inputs: PVGenerationModel | DCExternalGenerationModel | ACExternalGenerationModel [Required]

Submodel for PV or external power generation

field enable_grid_charge_year: float | None = 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: List[float] | None = None

list of prices to be assigned as additional revenue earned by solar in each time interval. Can be used to model Renewable Energy Credit (REC) revenue or Production Tax Credit (PTC) Revenue. 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.

property project_term: int

Equivalent to project_term provided in pv_inputs

property project_term_units: TermUnits

Equivalent to project_term_units provided in pv_inputs

field import_limit: List[float] | None = 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: List[float] | None = 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: DARTPrices | 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 reserve_markets: ReserveMarkets | None = None

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

field time_interval_mins: int | None = 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: LoadPeakReduction | None = None

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

class StandaloneStorageModel

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

field project_type: Literal['storage'] | None = 'storage'

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

field storage_inputs: MultiStorageInputs [Required]

Submodel for BESS design, market participation and optimization

field downstream_system: DownstreamSystem | None = 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: List[float] | SolarResourceLocation | None = 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

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: List[float] | None = 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: List[float] | None = 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: DARTPrices | 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 reserve_markets: ReserveMarkets | None = None

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

field time_interval_mins: int | None = 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: LoadPeakReduction | None = None

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

class SolarTimeSeriesV0
field ideal_tracker_rotation: list | None = None
field front_total_poa: list | None = None
field rear_total_poa: list | None = None
field effective_total_poa: list | None = None
field array_dc_snow_loss: list | None = None
field array_gross_dc_power: list | None = None
field array_dc_power: list | None = None
field array_dc_voltage: list | None = None
field inverter_mppt_dc_voltage: list | None = None
field inverter_mppt_loss: list | None = None
field inverter_clipping_loss: list | None = None
field inverter_night_tare_loss: list | None = None
field inverter_power_consumption_loss: list | None = None
field inverter_efficiency: list | None = None
field ambient_temp: list | None = None
field gross_ac_power: list [Required]
field mv_transformer_loss: list | None = None
field mv_transformer_load_loss: list | None = None
field mv_transformer_no_load_loss: list | None = None
field mv_ac_power: list [Required]
field ac_wiring_loss: list [Required]
field hv_transformer_loss: list | None = None
field hv_transformer_load_loss: list | None = None
field hv_transformer_no_load_loss: list | None = None
field transformer_load_loss: list [Required]
field transformer_no_load_loss: list [Required]
field hv_ac_power: list [Required]
field ac_transmission_loss: list [Required]
field gen: list [Required]
field poi_unadjusted: list [Required]
field system_power: list [Required]
field positive_system_power: list [Required]
field negative_system_power: list [Required]
field sam_design_parameters: dict [Required]
class SolarWaterfallVO
field gh_ann: float | None = None
field nominal_poa_ann: float | None = None
field shading_lp: float | None = None
field soiling_lp: float | None = None
field reflection_lp: float | None = None
field bifacial_lp: float | None = None
field dc_nominal_ann: float | None = None
field snow_lp: float | None = None
field module_temp_lp: float | None = None
field mppt_lp: float | None = None
field mismatch_lp: float | None = None
field diodes_lp: float | None = None
field dc_wiring_lp: float | None = None
field tracking_error_lp: float | None = None
field mppt_error_lp: float | None = None
field nameplate_lp: float | None = None
field dc_optimizer_lp: float | None = None
field dc_avail_lp: float | None = None
field dc_net_ann: float | None = None
field inverter_clipping_lp: float | None = None
field inverter_consumption_lp: float | None = None
field inverter_nightcons_lp: float | None = None
field inverter_efficiency_lp: float | None = None
field ac_gross_ann: float | None = None
field mv_transformer_lp: float | None = None
field ac_wiring_lp: float | None = None
field hv_transformer_lp: float | None = None
field transformer_lp: float [Required]
field transmission_lp: float [Required]
field poi_clipping_lp: float [Required]
field ac_availcurtail_lp: float [Required]
field annual_energy: float [Required]
class SolarStorageTimeSeriesV0
field battery_internal_energy: list [Required]
field battery_internal_energy_max: list [Required]
field battery_limit: float | list [Required]
field battery_output: list [Required]
field excess_power_at_coupling: list [Required]
field captured_excess_at_coupling: list [Required]
field solar_storage_dc_voltage: list | None = None
field solar_storage_dc_power: list | None = None
field solar_storage_power_at_coupling: list | None = None
field inverter_clipping_loss: list | None = None
field inverter_tare_loss: list | None = None
field inverter_parasitic_loss: list | None = None
field inverter_consumption_loss: list | None = None
field inverter_efficiency: list | None = None
field solar_storage_gross_ac_power: list | None = None
field mv_xfmr_loss: list | None = None
field mv_xfmr_load_loss: list | None = None
field mv_xfmr_no_load_loss: list | None = None
field pre_hvac_solar_storage_ac_power: list [Required]
field solar_storage_ac_power: list [Required]
field ac_wiring_loss: list | None = None
field hv_xfmr_loss: list | None = None
field hv_xfmr_load_loss: list | None = None
field hv_xfmr_no_load_loss: list | None = None
field transformer_loss: list | None = None
field solar_storage_hv_ac_power: list [Required]
field transmission_loss: list [Required]
field solar_storage_gen: list [Required]
field solar_storage_poi_unadjusted: list [Required]
field solar_storage_poi: list [Required]
field positive_solar_storage_poi: list [Required]
field negative_solar_storage_poi: list [Required]
class SolarStorageWaterfallV0
field gh_ann: float | None = None
field nominal_poa_ann: float | None = None
field shading_lp: float | None = None
field soiling_lp: float | None = None
field reflection_lp: float | None = None
field bifacial_lp: float | None = None
field dc_nominal_ann: float | None = None
field snow_lp: float | None = None
field module_temp_lp: float | None = None
field mppt_lp: float | None = None
field mismatch_lp: float | None = None
field diodes_lp: float | None = None
field dc_wiring_lp: float | None = None
field tracking_error_lp: float | None = None
field mppt_error_lp: float | None = None
field nameplate_lp: float | None = None
field dc_optimizer_lp: float | None = None
field dc_avail_lp: float | None = None
field dc_net_ann: float | None = None
field inverter_clipping_lp: float | None = None
field inverter_consumption_lp: float | None = None
field inverter_nightcons_lp: float | None = None
field inverter_efficiency_lp: float | None = None
field ac_gross_ann: float | None = None
field mv_transformer_lp: float | None = None
field ac_wiring_lp: float | None = None
field hv_transformer_lp: float | None = None
field transformer_lp: float [Required]
field transmission_lp: float [Required]
field poi_clipping_lp: float [Required]
field ac_availcurtail_lp: float [Required]
field annual_energy: float [Required]
field battery_operation_lp: float [Required]
field excess_power_at_coupling_lp: float [Required]
field captured_excess_at_coupling_lp: float [Required]
class OptimizerTimeSeriesV0
field hvac_load: list [Required]
field nominal_hvac_load: list [Required]
field storage_discharge_max: list [Required]
field import_limit_at_coupling: list | None = None
field export_limit_at_coupling: list | None = None
field target_load: list | None = None
field charge_actual: list [Required]
field discharge_actual: list [Required]
field charge: list [Required]
field discharge: list [Required]
field charge_hi: list [Required]
field discharge_hi: list [Required]
field charge_lo: list [Required]
field discharge_lo: list [Required]
field battery_output: list [Required]
field output: list [Required]
field total_output: list [Required]
field internal_energy: list [Required]
field soe_actual: list [Required]
field soe_lo: list [Required]
field soe_hi: list [Required]
field soe_hb_actual: list [Required]
field soe_hb_lo: list [Required]
field soe_hb_hi: list [Required]
field soe_mean_actual: list [Required]
field soe_mean_lo: list [Required]
field soe_mean_hi: list [Required]
field dam_charge: list | None = None
field dam_discharge: list | None = None
field dam_base_point: list | None = None
field negative_dam_base_point: list | None = None
field dam_solar: list | None = None
field rtm_charge: list | None = None
field rtm_discharge: list | None = None
field rtm_base_point: list | None = None
field negative_rtm_base_point: list | None = None
field rtm_solar: list | None = None
field rtm_price: list | None = None
field dam_price: list | None = None
field imbalance: list | None = None
field theoretical_dam_soe: list | None = None
field solar_actual: list | None = None
field solar_hi: list | None = None
field solar_lo: list | None = None
field net_load: list | None = None
class MarketAwardsTimeSeriesV0
field charge: list [Required]
field discharge: list [Required]
field total_output: list [Required]
field rt_tare: list [Required]
field dam_charge: list [Required]
field dam_discharge: list [Required]
field dam_base_point: list [Required]
field negative_dam_base_point: list [Required]
field rtm_charge: list [Required]
field rtm_discharge: list [Required]
field rtm_base_point: list [Required]
field solar_actual: list | None = None
field dam_solar: list | None = None
field rtm_solar: list | None = None
class StandaloneStorageSystemTimeSeriesV0
field dc_power: list | None = None
field dc_voltage: list | None = None
field inverter_clipping_loss: list | None = None
field inverter_tare_loss: list | None = None
field inverter_parasitic_loss: list | None = None
field inverter_consumption_loss: list | None = None
field inverter_efficiency: list | None = None
field gross_ac_power: list | None = None
field max_mv_power: list [Required]
field pre_hvac_ac_power: list [Required]
field ac_power: list [Required]
field mv_xfmr_loss: list | None = None
field mv_xfmr_load_loss: list | None = None
field mv_xfmr_no_load_loss: list | None = None
field ac_wiring_loss: list | None = None
field hv_xfmr_loss: list | None = None
field hv_xfmr_load_loss: list | None = None
field hv_xfmr_no_load_loss: list | None = None
field transformer_loss: list | None = None
field hv_ac_power: list [Required]
field transmission_loss: list [Required]
field gen: list [Required]
field poi_unadjusted: list [Required]
field poi: list [Required]
field positive_poi: list [Required]
field negative_poi: list [Required]
class GenerationModelResultsV0

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

field ideal_tracker_rotation: list | None = None
field front_total_poa: list | None = None
field rear_total_poa: list | None = None
field effective_total_poa: list | None = None
field array_dc_snow_loss: list | None = None
field array_gross_dc_power: list | None = None
field array_dc_power: list | None = None
field array_dc_voltage: list | None = None
field inverter_mppt_dc_voltage: list | None = None
field inverter_mppt_loss: list | None = None
field inverter_clipping_loss: list | None = None
field inverter_night_tare_loss: list | None = None
field inverter_power_consumption_loss: list | None = None
field inverter_efficiency: list | None = None
field ambient_temp: list | None = None
field gross_ac_power: list [Required]
field mv_transformer_loss: list | None = None
field mv_transformer_load_loss: list | None = None
field mv_transformer_no_load_loss: list | None = None
field mv_ac_power: list [Required]
field ac_wiring_loss: list [Required]
field hv_transformer_loss: list | None = None
field hv_transformer_load_loss: list | None = None
field hv_transformer_no_load_loss: list | None = None
field transformer_load_loss: list [Required]
field transformer_no_load_loss: list [Required]
field hv_ac_power: list [Required]
field ac_transmission_loss: list [Required]
field gen: list [Required]
field poi_unadjusted: list [Required]
field system_power: list [Required]
field positive_system_power: list [Required]
field negative_system_power: list [Required]
field sam_design_parameters: dict [Required]
field tyba_api_loss_waterfall: SolarWaterfallVO [Required]
field warnings: List[str] [Required]
field coupling: None [Required]
time_series_df()
class PVStorageModelResultsV0

Results schema returned when a PVStorageModel simulation is run

field solar_only: SolarTimeSeriesV0 [Required]
field solar_storage: SolarStorageTimeSeriesV0 [Required]
field waterfall: SolarStorageWaterfallV0 [Required]
field optimizer: OptimizerTimeSeriesV0 [Required]
field market_awards: MarketAwardsTimeSeriesV0 | None = None
field warnings: List[str] [Required]
field coupling: str [Required]
time_series_df()
class StandaloneStorageModelWithDownstreamResultsV0

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

field system: StandaloneStorageSystemTimeSeriesV0 [Required]
field optimizer_outputs: OptimizerTimeSeriesV0 [Required]
field market_awards: MarketAwardsTimeSeriesV0 | None = None
time_series_df()
class StandaloneStorageModelSimpleResultsV0

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

field hvac_load: list [Required]
field nominal_hvac_load: list [Required]
field storage_discharge_max: list [Required]
field import_limit_at_coupling: list | None = None
field export_limit_at_coupling: list | None = None
field target_load: list | None = None
field charge_actual: list [Required]
field discharge_actual: list [Required]
field charge: list [Required]
field discharge: list [Required]
field charge_hi: list [Required]
field discharge_hi: list [Required]
field charge_lo: list [Required]
field discharge_lo: list [Required]
field battery_output: list [Required]
field output: list [Required]
field total_output: list [Required]
field internal_energy: list [Required]
field soe_actual: list [Required]
field soe_lo: list [Required]
field soe_hi: list [Required]
field soe_hb_actual: list [Required]
field soe_hb_lo: list [Required]
field soe_hb_hi: list [Required]
field soe_mean_actual: list [Required]
field soe_mean_lo: list [Required]
field soe_mean_hi: list [Required]
field dam_charge: list | None = None
field dam_discharge: list | None = None
field dam_base_point: list | None = None
field negative_dam_base_point: list | None = None
field dam_solar: list | None = None
field rtm_charge: list | None = None
field rtm_discharge: list | None = None
field rtm_base_point: list | None = None
field negative_rtm_base_point: list | None = None
field rtm_solar: list | None = None
field rtm_price: list | None = None
field dam_price: list | None = None
field imbalance: list | None = None
field theoretical_dam_soe: list | None = None
field solar_actual: list | None = None
field solar_hi: list | None = None
field solar_lo: list | None = None
field net_load: list | None = None
field pre_hvac_output: list [Required]
field pre_hvac_battery_output: list [Required]
field pre_hvac_total_output: list [Required]
time_series_df()
class GenerationTimeSeriesV2
classmethod default_include()
field dc_bus_power_kW: List[float] | None = None
field dc_bus_voltage_V: List[float] | None = None
field inverter_clipping_loss_kW: List[float] | None = None
field inverter_efficiency: List[float] | None = None
field inverter_tare_loss_kW: List[float] | None = None
field inverter_consumption_loss_kW: List[float] | None = None
field lv_bus_power_kW: List[float] | None = None
field mv_xfmr_total_loss_kW: List[float] | None = None
field mv_xfmr_load_loss_kW: List[float] | None = None
field mv_xfmr_no_load_loss_kW: List[float] | None = None
field mv_bus_power_kW: List[float] | None = None
field ac_wiring_loss_kW: List[float] | None = None
field hv_xfmr_total_loss_kW: List[float] | None = None
field hv_xfmr_load_loss_kW: List[float] | None = None
field hv_xfmr_no_load_loss_kW: List[float] | None = None
field export_bus_power_kW: List[float] [Required]
field transmission_loss_kW: List[float] [Required]
field poi_power_pre_clip_kW: List[float] [Required]
field poi_power_pre_adjustment_kW: List[float] [Required]
field poi_power_kW: List[float] [Required]
field poi_power_positive_kW: List[float] [Required]
field poi_power_negative_kW: List[float] [Required]
field ghi_Wm2: List[float] | None = None
field tracker_rotation_angle_deg: List[float] | None = None
field front_poa_nominal_Wm2: List[float] | None = None
field front_poa_shaded_Wm2: List[float] | None = None
field front_poa_shaded_soiled_Wm2: List[float] | None = None
field front_poa_Wm2: List[float] | None = None
field rear_poa_Wm2: List[float] | None = None
field poa_effective_Wm2: List[float] | None = None
field poa_effective_power_kW: List[float] | None = None
field cell_temperature_quasi_steady_C: List[float] | None = None
field cell_temperature_C: List[float] | None = None
field module_efficiency: List[float] | None = None
field dc_shading_loss_kW: List[float] | None = None
field dc_snow_loss_kW: List[float] | None = None
field mppt_window_loss_kW: List[float] | None = None
field pv_gross_dc_power_kW: List[float] | None = None
field pv_dc_power_undegraded_kW: List[float] | None = None
class GenerationYear1WaterfallV2
field dc_bus_energy_kWh: float | None = None
field inverter_clipping: float | None = None
field inverter_consumption: float | None = None
field inverter_tare: float | None = None
field inverter_efficiency: float | None = None
field lv_bus_energy_kWh: float | None = None
field mv_transformer: float | None = None
field mv_bus_energy_kWh: float | None = None
field ac_wiring: float | None = None
field hv_transformer: float | None = None
field export_bus_energy_kWh: float [Required]
field transmission: float [Required]
field poi_clipping: float [Required]
field poi_adjustment: float [Required]
field poi_energy_kWh: float [Required]
field ghi_Whm2: float | None = None
field front_transposition: float | None = None
field front_shading: float | None = None
field front_soiling: float | None = None
field front_iam: float | None = None
field rear_poa: float | None = None
field rear_bifaciality: float | None = None
field poa_effective_annual_Whm2: float | None = None
field array_area_m2: float | None = None
field poa_effective_energy_kWh: float | None = None
field stc_pv_module_effeciency: float | None = None
field pv_dc_nominal_energy_kWh: float | None = None
field non_stc_irradiance_temperature: float | None = None

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

field mppt_clip: float | None = None
field snow: float | None = None
field pv_dc_gross_energy_kWh: float | None = None
field nameplate: float | None = None
field lid: float | None = None
field mismatch: float | None = None
field diodes: float | None = None
field dc_optimizer: float | None = None
field tracking_error: float | None = None
field dc_wiring: float | None = None
field dc_adjustment: float | None = None
class GenerationModelResultsV2

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

field time_series: GenerationTimeSeriesV2 [Required]
field waterfall: GenerationYear1WaterfallV2 [Required]
field sam_raw: dict | None = None
field solar_resource: SolarResource | None = None
field warnings: List[str] | None = None
time_series_df()
default_dict()