reV.SAM.generation.AbstractSamPv

class AbstractSamPv(resource, meta, sam_sys_inputs, site_sys_inputs=None, output_request=None, drop_leap=False)[source]

Bases: AbstractSamSolar, ABC

Photovoltaic (PV) generation with either pvwatts of detailed pv.

Initialize a SAM solar object.

See the PySAM Pvwattsv8 (or older version model) or Pvsamv1 documentation for the configuration keys required in the sam_sys_inputs config for the respective models. Some notable keys include the following to enable a lifetime simulation (non-exhaustive):

system_use_lifetime_output : Integer flag indicating whether or not to run a full lifetime model (0 for off, 1 for on). If running a lifetime model, the resource file will be repeated for the number of years specified as the lifetime of the plant and a performance degradation term will be used to simulate reduced performance over time.

analysis_period : Integer representing the number of years to include in the lifetime of the model generator. Required if ``system_use_lifetime_output``=1.

dc_degradation : List of percentage values representing the annual DC degradation of capacity factors. Maybe a single value that will be compound each year or a vector of yearly rates. Required if ``system_use_lifetime_output``=1.

You may also include the following reV-specific keys:

reV_outages : Specification for reV-scheduled stochastic outage losses. For example:
outage_info = [
    {
        'count': 6,
        'duration': 24,
        'percentage_of_capacity_lost': 100,
        'allowed_months': ['January', 'March'],
        'allow_outage_overlap': True
    },
    {
        'count': 10,
        'duration': 1,
        'percentage_of_capacity_lost': 10,
        'allowed_months': ['January'],
        'allow_outage_overlap': False
    },
    ...
]
See the description of add_scheduled_losses() or the reV losses demo notebook for detailed instructions on how to specify this input.
reV_outages_seed : Integer value used to seed the RNG used to compute stochastic outage losses.

time_index_step : Integer representing the step size used to sample the time_index in the resource data. This can be used to reduce temporal resolution (i.e. for 30 minute NSRDB input data, time_index_step=1 yields the full 30 minute time series as output, while time_index_step=2 yields hourly output, and so forth).

Note

The reduced data shape (i.e. after applying a step size of time_index_step) must still be an integer multiple of 8760, or the execution will fail.

clearsky : Boolean flag value indicating wether computation should use clearsky resource data to compute generation data.

Parameters:

resource (pd.DataFrame) – Timeseries solar or wind resource data for a single location with a pandas DatetimeIndex. There must be columns for all the required variables to run the respective SAM simulation. Remapping will be done to convert typical NSRDB/WTK names into SAM names (e.g. DNI -> dn and wind_speed -> windspeed)
meta (pd.DataFrame | pd.Series) – Meta data corresponding to the resource input for the single location. Should include values for latitude, longitude, elevation, and timezone.
sam_sys_inputs (dict) – Site-agnostic SAM system model inputs arguments.
site_sys_inputs (dict) – Optional set of site-specific SAM system inputs to complement the site-agnostic inputs.
output_request (list) – Requested SAM outputs (e.g., ‘cf_mean’, ‘annual_energy’, ‘cf_profile’, ‘gen_profile’, ‘energy_yield’, ‘ppa_price’, ‘lcoe_fcr’).
drop_leap (bool) – Drops February 29th from the resource data. If False, December 31st is dropped from leap years.

Methods

`ac`()	Get AC inverter power generation profile (local timezone) in kW.
`add_scheduled_losses`([resource])	Add stochastically scheduled losses to SAM config file.
`agg_albedo`(time_index, albedo)	Aggregate a timeseries of albedo data to monthly values w len 12 as required by pysam Pvsamv1
`annual_energy`()	Get annual energy generation value in kWh from SAM.
`assign_inputs`()	Assign the self.sam_sys_inputs attribute to the PySAM object.
`cf_mean`()	Get mean capacity factor (fractional) from SAM.
`cf_mean_ac`()	Get mean AC capacity factor (fractional) from SAM.
`cf_profile`()	Get hourly capacity factor (frac) profile in local timezone.
`cf_profile_ac`()	Get hourly AC capacity factor (frac) profile in local timezone.
`check_resource_data`(resource)	Check resource dataframe for NaN values
`clipped_power`()	Get the clipped DC power generated behind the inverter (local timezone) in kW.
`collect_outputs`([output_lookup])	Collect SAM output_request, convert timeseries outputs to UTC, and save outputs to self.outputs property.
`dc`()	Get DC array power generation profile (local timezone) in kW.
`default`()	Get the executed default pysam object.
`drop_leap`(resource)	Drop Feb 29th from resource df with time index.
`energy_yield`()	Get annual energy yield value in kwh/kw from SAM.
`ensure_res_len`(arr, time_index)	Ensure time_index has a constant time-step and only covers 365 days (no leap days).
`execute`()	Call the PySAM execute method.
`gen_profile`()	Get AC inverter power generation profile (local timezone) in kW.
`get_sam_res`(args, *kwargs)	Get the SAM resource iterator object (single year, single file).
`get_time_interval`(time_index)	Get the time interval.
`make_datetime`(series)	Ensure that pd series is a datetime series with dt accessor
`outputs_to_utc_arr`()	Convert array-like SAM outputs to UTC np.ndarrays
`reV_run`(points_control, res_file, site_df[, ...])	Execute SAM generation based on a reV points control instance.
`run`()	Run a reV-SAM generation object by assigning inputs, executing the SAM simulation, collecting outputs, and converting all arrays to UTC.
`run_gen_and_econ`()	Run SAM generation with possibility for follow on econ analysis.
`set_latitude_tilt_az`(sam_sys_inputs, meta)	Check if tilt is specified as latitude and set tilt=lat, az=180 or 0
`set_resource_data`(resource, meta)	Set NSRDB resource data arrays.
`system_capacity_ac`()	Get AC system capacity from SAM inputs.
`tz_elev_check`(sam_sys_inputs, ...)	Check timezone+elevation input and use json config timezone+elevation if not in resource meta.

Attributes

`DIR`
`IGNORE_ATTRS`
`MODULE`
`OUTAGE_CONFIG_KEY`	Specify outage information in the config file using this key.
`OUTAGE_SEED_CONFIG_KEY`	Specify a randomizer seed in the config file using this key.
`PYSAM`
`attr_dict`	Get the heirarchical PySAM object attribute dictionary.
`has_timezone`	Returns true if instance has a timezone set
`input_list`	Get the list of lowest level input attribute/variable names.
`meta`	Get meta data property.
`module`	Get module property.
`outage_seed`	A value to use as the seed for the outage losses.
`pysam`	Get the pysam object.
`site`	Get the site number for this SAM simulation.

PYSAM = None

set_resource_data(resource, meta)[source]

Set NSRDB resource data arrays.

Parameters:

resource (pd.DataFrame) – Timeseries solar or wind resource data for a single location with a pandas DatetimeIndex. There must be columns for all the required variables to run the respective SAM simulation. Remapping will be done to convert typical NSRDB/WTK names into SAM names (e.g. DNI -> dn and wind_speed -> windspeed)
meta (pd.Series) – Meta data corresponding to the resource input for the single location. Should include values for latitude, longitude, elevation, and timezone.

:raises ValueError : If lat/lon outside of -90 to 90 and -180 to 180,: respectively.

static set_latitude_tilt_az(sam_sys_inputs, meta)[source]

Check if tilt is specified as latitude and set tilt=lat, az=180 or 0

Parameters:

sam_sys_inputs (dict) – Site-agnostic SAM system model inputs arguments.
meta (pd.Series) – Meta data corresponding to the resource input for the single location. Should include values for latitude, longitude, elevation, and timezone.

Returns:

sam_sys_inputs (dict) – Site-agnostic SAM system model inputs arguments. If for a pv simulation the “tilt” parameter was originally not present or set to ‘lat’ or ‘latitude’, the tilt will be set to the absolute value of the latitude found in meta and the azimuth will be 180 if lat>0, 0 if lat<0.

system_capacity_ac()[source]

Get AC system capacity from SAM inputs.

NOTE: AC nameplate = DC nameplate / ILR

Returns:: cf_profile (float) – AC nameplate = DC nameplate / ILR

cf_mean()[source]

Get mean capacity factor (fractional) from SAM.

NOTE: PV capacity factor is the AC power production / the DC nameplate

Returns:: output (float) – Mean capacity factor (fractional). PV CF is calculated as AC power / DC nameplate.

cf_mean_ac()[source]

Get mean AC capacity factor (fractional) from SAM.

NOTE: This value only available in PVWattsV8 and up.

Returns:: output (float) – Mean AC capacity factor (fractional). PV AC CF is calculated as AC power / AC nameplate.

cf_profile()[source]

Get hourly capacity factor (frac) profile in local timezone. See self.outputs attribute for collected output data in UTC.

NOTE: PV capacity factor is the AC power production / the DC nameplate

Returns:: cf_profile (np.ndarray) – 1D numpy array of capacity factor profile. Datatype is float32 and array length is 8760*time_interval. PV CF is calculated as AC power / DC nameplate.

cf_profile_ac()[source]

Get hourly AC capacity factor (frac) profile in local timezone. See self.outputs attribute for collected output data in UTC.

NOTE: PV AC capacity factor is the AC power production / the AC nameplate. AC nameplate = DC nameplate / ILR

Returns:: cf_profile (np.ndarray) – 1D numpy array of capacity factor profile. Datatype is float32 and array length is 8760*time_interval. PV AC CF is calculated as AC power / AC nameplate.

gen_profile()[source]

Get AC inverter power generation profile (local timezone) in kW. This is an alias of the “ac” SAM output variable if PySAM version>=3. See self.outputs attribute for collected output data in UTC.

Returns:: output (np.ndarray) – 1D array of AC inverter power generation in kW. Datatype is float32 and array length is 8760*time_interval.

ac()[source]

Get AC inverter power generation profile (local timezone) in kW. See self.outputs attribute for collected output data in UTC.

Returns:: output (np.ndarray) – 1D array of AC inverter power generation in kW. Datatype is float32 and array length is 8760*time_interval.

dc()[source]

Get DC array power generation profile (local timezone) in kW. See self.outputs attribute for collected output data in UTC.

Returns:: output (np.ndarray) – 1D array of DC array power generation in kW. Datatype is float32 and array length is 8760*time_interval.

clipped_power()[source]

Get the clipped DC power generated behind the inverter (local timezone) in kW. See self.outputs attribute for collected output data in UTC.

Returns:: clipped (np.ndarray) – 1D array of clipped DC power in kW. Datatype is float32 and array length is 8760*time_interval.

abstract static default()[source]: Get the executed default pysam object.

collect_outputs(output_lookup=None)[source]

Collect SAM output_request, convert timeseries outputs to UTC, and save outputs to self.outputs property.

Parameters:: output_lookup (dict | None) – Lookup dictionary mapping output keys to special output methods. None defaults to generation default outputs.

OUTAGE_CONFIG_KEY = 'reV_outages': Specify outage information in the config file using this key.

OUTAGE_SEED_CONFIG_KEY = 'reV_outages_seed': Specify a randomizer seed in the config file using this key.

add_scheduled_losses(resource=None)

Add stochastically scheduled losses to SAM config file.

This function reads the information in the reV_outages key of the sam_sys_inputs dictionary and computes stochastically scheduled losses from that input. If the value for reV_outages is a string, it must have been generated by calling json.dumps() on the list of dictionaries containing outage specifications. Otherwise, the outage information is expected to be a list of dictionaries containing outage specifications. See Outage for a description of the specifications allowed for each outage. The scheduled losses are passed to SAM via the hourly key to signify which hourly capacity factors should be adjusted with outage losses. If no outage info is specified in sam_sys_inputs, no scheduled losses are added.

Parameters:: resource (pd.DataFrame, optional) – Time series resource data for a single location with a pandas DatetimeIndex. The year value of the index will be used to seed the stochastically scheduled losses. If None, no yearly seed will be used.