cpvlib.cpvsystem module

The cpvsystem module contains functions for modeling the output and performance of CPV modules.

class cpvlib.cpvsystem.CPVSystem(module=None, module_parameters=None, temperature_model_parameters=None, modules_per_string=1, strings_per_inverter=1, inverter=None, inverter_parameters=None, racking_model='freestanding', losses_parameters=None, name=None, albedo=None, surface_type=None, **kwargs)[source]

Bases: pvlib.pvsystem.PVSystem

The CPVSystem class defines a set of CPV system attributes and modeling functions. This class describes the collection and interactions of CPV system components installed on a Dual Axis Tracker.

It inheritates from pvlib.pvsystem.PVSystem, modifying those methods that are specific for a CPV system following the PVSyst implementation. Besides, specific CPV utilization factors are added as defined in https://doi.org/10.1063/1.3509185 as new methods and new specific CPV parameters are passes to these methods.

The class supports basic system topologies consisting of:

  • N total modules arranged in series (modules_per_string=N, strings_per_inverter=1).

  • M total modules arranged in parallel (modules_per_string=1, strings_per_inverter=M).

  • NxM total modules arranged in M strings of N modules each (modules_per_string=N, strings_per_inverter=M).

The attributes should generally be things that don’t change about the system, such the type of module and the inverter. The instance methods accept arguments for things that do change, such as irradiance and temperature.

Parameters:

  • albedo (None or float, default None) – The ground albedo. If None, will attempt to use surface_type and irradiance.SURFACE_ALBEDOS to lookup albedo.

  • surface_type (None or string, default None) – The ground surface type. See irradiance.SURFACE_ALBEDOS for valid values.

  • module (None or string, default None) – The model name of the modules. May be used to look up the module_parameters dictionary via some other method.

  • module_parameters (None, dict or Series, default None) – Module parameters as defined by the SAPM, CEC, or other.

  • modules_per_string (int or float, default 1) – See system topology discussion above.

  • strings_per_inverter (int or float, default 1) – See system topology discussion above.

  • inverter (None or string, default None) – The model name of the inverters. May be used to look up the inverter_parameters dictionary via some other method.

  • inverter_parameters (None, dict or Series, default None) – Inverter parameters as defined by the SAPM, CEC, or other.

  • racking_model (None or string, default 'freestanding') – Used for cell and module temperature calculations.

  • losses_parameters (None, dict or Series, default None) – Losses parameters as defined by PVWatts or other.

  • name (None or string, default None) –

  • **kwargs – Arbitrary keyword arguments. Included for compatibility, but not used.

get_am_util_factor(airmass, am_thld=None, am_uf_m_low=None, am_uf_m_high=None)[source]

Retrieves the utilization factor for airmass.

Parameters:

  • airmass (numeric) – absolute airmass.

  • am_thld (numeric) – limit between the two regression lines of the utilization factor.

  • am_uf_m_low (numeric) – slope of the first regression line of the utilization factor for airmass.

  • am_uf_m_high (numeric) – slope of the second regression line of the utilization factor for airmass.

Returns:

am_uf (numeric) – the utilization factor for airmass.

get_dni_util_factor(dni, dni_thld=None, dni_uf_m_low=None, dni_uf_m_high=None)[source]

Retrieves the utilization factor for DNI.

Parameters:

  • dni (numeric) – Direct Normal Irradiance

  • dni_thld (numeric) – limit between the two regression lines of the utilization factor.

  • dni_uf_m_low (numeric) – slope of the first regression line of the utilization factor for DNI.

  • dni_uf_m_low_uf_m_high (numeric) – slope of the second regression line of the utilization factor for DNI.

Returns:

dni_uf (numeric) – the utilization factor for DNI.

get_global_utilization_factor(airmass_absolute, temp_air)[source]

Retrieves the global utilization factor (Air mass and Air temperature CPV effects)

Parameters:

  • airmass (numeric) – absolute airmass.

  • temp_air (numeric) – Ambient dry bulb temperature in degrees C.

Returns:

uf_global (numeric) – the global utilization factor.

get_irradiance(solar_zenith, solar_azimuth, dni, ghi, dhi, dni_extra=None, airmass=None, model='haydavies', **kwargs)[source]

Uses the irradiance.get_total_irradiance() function to calculate the plane of array irradiance components on a Dual axis tracker.

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

  • dni (float or Series) – Direct Normal Irradiance

  • ghi (float or Series) – Global horizontal irradiance

  • dhi (float or Series) – Diffuse horizontal irradiance

  • dni_extra (None, float or Series, default None) – Extraterrestrial direct normal irradiance

  • airmass (None, float or Series, default None) – Airmass

  • model (String, default 'haydavies') – Irradiance model.

  • **kwargs – Passed to irradiance.total_irrad().

Returns:

poa_irradiance (DataFrame) – Column names are: total, beam, sky, ground.

get_tempair_util_factor(temp_air, ta_thld=None, ta_uf_m_low=None, ta_uf_m_high=None)[source]

Retrieves the utilization factor for ambient temperature.

Parameters:

  • temp_air (numeric) – Ambient dry bulb temperature in degrees C.

  • ta_thld (numeric) – limit between the two regression lines of the utilization factor.

  • ta_uf_m_low (numeric) – slope of the first regression line of the utilization factor for ambient temperature.

  • ta_uf_m_high (numeric) – slope of the second regression line of the utilization factor for ambient temperature.

Returns:

ta_uf (numeric) – the utilization factor for ambient temperature.

pvsyst_celltemp(poa_global, temp_air, wind_speed=1.0)[source]

Uses pvsystem.pvsyst_celltemp() to calculate module temperatures based on self.racking_model and the input parameters.

Parameters:

pvsystem.pvsyst_celltemp for details (See) –

Returns:

See pvsystem.pvsyst_celltemp for details

class cpvlib.cpvsystem.StaticCPVSystem(surface_tilt=0, surface_azimuth=180, module=None, module_parameters=None, temperature_model_parameters=None, in_singleaxis_tracker=False, b=None, parameters_tracker=None, modules_per_string=1, strings_per_inverter=1, inverter=None, inverter_parameters=None, racking_model='freestanding', losses_parameters=None, name=None, **kwargs)[source]

Bases: cpvlib.cpvsystem.CPVSystem

The StaticCPVSystem class defines a set of Static CPV system attributes and modeling functions. This class describes the collection and interactions of Static CPV system components installed on a Fixed Panel or a Single Axis tracker.

It inheritates from CPVSystem, modifying those methods that are specific for a Static CPV system following the PVSyst implementation.

The class supports basic system topologies consisting of:

  • N total modules arranged in series (modules_per_string=N, strings_per_inverter=1).

  • M total modules arranged in parallel (modules_per_string=1, strings_per_inverter=M).

  • NxM total modules arranged in M strings of N modules each (modules_per_string=N, strings_per_inverter=M).

The attributes should generally be things that don’t change about the system, such the type of module and the inverter. The instance methods accept arguments for things that do change, such as irradiance and temperature.

Parameters:

  • surface_tilt (float or array-like, default 0) – Surface tilt angles in decimal degrees. The tilt angle is defined as degrees from horizontal (e.g. surface facing up = 0, surface facing horizon = 90)

  • surface_azimuth (float or array-like, default 180) – Azimuth angle of the module surface. North=0, East=90, South=180, West=270.

  • module (None or string, default None) – The model name of the modules. May be used to look up the module_parameters dictionary via some other method.

  • module_parameters (None, dict or Series, default None) – Module parameters as defined by the SAPM, CEC, or other.

  • modules_per_string (int or float, default 1) – See system topology discussion above.

  • strings_per_inverter (int or float, default 1) – See system topology discussion above.

  • inverter (None or string, default None) – The model name of the inverters. May be used to look up the inverter_parameters dictionary via some other method.

  • inverter_parameters (None, dict or Series, default None) – Inverter parameters as defined by the SAPM, CEC, or other.

  • racking_model (None or string, default 'freestanding') – Used for cell and module temperature calculations.

  • losses_parameters (None, dict or Series, default None) – Losses parameters as defined by PVWatts or other.

  • in_singleaxis_tracker (None or bool, defult False) – Conttros if the system is mounted in a NS single axis tracker If true, it affects get_aoi() and get_irradiance()

  • name (None or string, default None) –

  • **kwargs – Arbitrary keyword arguments. Included for compatibility, but not used.

get_aoi(solar_zenith, solar_azimuth)[source]

Get the angle of incidence on the system.

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

Returns:

aoi (Series) – The angle of incidence

get_effective_irradiance(solar_zenith, solar_azimuth, dni)[source]

Calculates the effective irradiance (taking into account the IAM)

Parameters:

  • solar_zenith (float or Series) – Solar zenith angle.

  • solar_azimuth (float or Series) – Solar azimuth angle.

  • dni (float or Series) – Direct Normal Irradiance

Returns:

dii_effective (float or Series) – Effective Direct (on the) Inclinated (plane) Irradiance Beam component of the plane of array irradiance plus the effect of AOI

get_iam(aoi, iam_model)[source]

Determine the incidence angle modifier using the method specified by iam_model.

Parameters for the selected IAM model are expected to be in StaticCPVSystem.module_parameters.

Parameters:

  • aoi (numeric) – The angle of incidence in degrees.

  • aoi_model (string) – The IAM model to be used. Valid strings are ‘ashrae’ and ‘interp’.

Returns:

iam (numeric) – The AOI modifier.

Raises:

  • AttributeError if b for 'ashrae' or theta_ref or iam_red for 'interp' are missing –

  • ValueError if iam_model is not a valid model name. –

get_irradiance(solar_zenith, solar_azimuth, dni)[source]

Uses the pvlib.irradiance.beam_component() function to calculate the beam component of the plane of array irradiance.

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

  • dni (float or Series) – Direct Normal Irradiance

Returns:

dii (numeric) – Direct (on the) Inclinated (plane) Irradiance Beam component of the plane of array irradiance

class cpvlib.cpvsystem.StaticFlatPlateSystem(surface_tilt=0, surface_azimuth=180, module=None, module_parameters=None, temperature_model_parameters=None, modules_per_string=1, in_singleaxis_tracker=False, parameters_tracker=None, strings_per_inverter=1, inverter=None, inverter_parameters=None, racking_model='freestanding', losses_parameters=None, name=None, **kwargs)[source]

Bases: pvlib.pvsystem.PVSystem

The StaticFlatPlateSystem class defines a set of Static FlatPlate system attributes and modeling functions. This class describes the collection and interactions of Static FlatPlate system components installed on a Fixed Panel or a Single Axis tracker.

It inheritates from PVSystem, modifying those methods that are specific for a Static FlatPlate system following the PVSyst implementation.

The class supports basic system topologies consisting of:

  • N total modules arranged in series (modules_per_string=N, strings_per_inverter=1).

  • M total modules arranged in parallel (modules_per_string=1, strings_per_inverter=M).

  • NxM total modules arranged in M strings of N modules each (modules_per_string=N, strings_per_inverter=M).

The attributes should generally be things that don’t change about the system, such the type of module and the inverter. The instance methods accept arguments for things that do change, such as irradiance and temperature.

Parameters:

  • surface_tilt (float or array-like, default 0) – Surface tilt angles in decimal degrees. The tilt angle is defined as degrees from horizontal (e.g. surface facing up = 0, surface facing horizon = 90)

  • surface_azimuth (float or array-like, default 180) – Azimuth angle of the module surface. North=0, East=90, South=180, West=270.

  • module (None or string, default None) – The model name of the modules. May be used to look up the module_parameters dictionary via some other method.

  • module_parameters (None, dict or Series, default None) – Module parameters as defined by the SAPM, CEC, or other.

  • modules_per_string (int or float, default 1) – See system topology discussion above.

  • strings_per_inverter (int or float, default 1) – See system topology discussion above.

  • inverter (None or string, default None) – The model name of the inverters. May be used to look up the inverter_parameters dictionary via some other method.

  • inverter_parameters (None, dict or Series, default None) – Inverter parameters as defined by the SAPM, CEC, or other.

  • racking_model (None or string, default 'freestanding') – Used for cell and module temperature calculations.

  • losses_parameters (None, dict or Series, default None) – Losses parameters as defined by PVWatts or other.

  • in_singleaxis_tracker (None or bool, defult False) – Conttros if the system is mounted in a NS single axis tracker If true, it affects get_aoi() and get_irradiance()

  • name (None or string, default None) –

  • **kwargs – Arbitrary keyword arguments. Included for compatibility, but not used.

get_aoi(solar_zenith, solar_azimuth)[source]

Get the angle of incidence on the system.

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

Returns:

aoi (Series) – The angle of incidence

get_effective_irradiance(solar_zenith, solar_azimuth, dni=None, ghi=None, dhi=None, dii=None, gii=None, dni_extra=None, airmass=None, model='haydavies', spillage=0, **kwargs)[source]

Calculates the plane of array irradiance of a Static Flat Plate system from dii and gii. If any is missing then is calculated from ghi, dhi and dhi using corresponding pvlib function.

Internal aoi_limit parameter from module_parameters sets the limit of tracking of the Static CPV system and therefore when the dii irradiance is added to the poa_diffuse.

Spillage factor accounts for the dii fraction that is allowed to pass into the system

See https://doi.org/10.1002/pip.3387 for details

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

  • dni (numeric) – Direct Normal Irradiance

  • ghi (numeric) – Global horizontal irradiance

  • dhi (numeric) – Diffuse horizontal irradiance

  • dii (numeric) – Direct (on the) Inclinated (plane) Irradiance

  • gii (numeric) – Global (on the) Inclinated (plane) Irradiance

  • dni_extra (None or numeric, default None) – Extraterrestrial direct normal irradiance

  • airmass (None or numeric, default None) – Airmass

  • model (String, default 'isotropic') – Irradiance model.

  • spillage (float) – Percentage of dii allowed to pass into the system

Returns:

poa_flatplate_static (numeric) – Plane of Array Irradiance

get_iam(aoi)[source]

Determines the angle of incidence modifier for the dii part

Parameters:

aoi (numeric) – The angle of incidence in degrees.

Returns:

iam (numeric) – The AOI modifier.

get_spillage_iam(aoi)[source]

Determines the spillage using an specific IAM that accounts for the spot size. Since the spot increases, IAM values shoud be > 1

Parameters:

aoi (numeric) – The angle of incidence in degrees.

Returns:

iam (numeric) – The AOI modifier.

pvsyst_celltemp(poa_flatplate_static, temp_air, wind_speed=1.0)[source]

Uses pvsystem.pvsyst_celltemp() to calculate module temperatures based on self.racking_model and the input parameters.

Parameters:

pvsystem.pvsyst_celltemp for details (See) –

Returns:

See pvsystem.pvsyst_celltemp for details

class cpvlib.cpvsystem.StaticHybridSystem(surface_tilt=30, surface_azimuth=180, module_cpv=None, module_parameters_cpv=None, temperature_model_parameters_cpv=None, module_flatplate=None, module_parameters_flatplate=None, temperature_model_parameters_flatplate=None, in_singleaxis_tracker=False, parameters_tracker=None, modules_per_string=1, strings_per_inverter=1, inverter=None, inverter_parameters=None, racking_model='insulated', losses_parameters=None, name=None, **kwargs)[source]

Bases: object

The StaticHybridSystem class defines a set of Static Hybrid system attributes and modeling functions. This class describes the collection and interactions of Static CPV system components installed on a Fixed Panel or a Single Axis tracker.

It is the composition of two subsystems: StaticCPVSystem and StaticFlatPlateSystem

The class supports basic system topologies consisting of:

  • N total modules arranged in series (modules_per_string=N, strings_per_inverter=1).

  • M total modules arranged in parallel (modules_per_string=1, strings_per_inverter=M).

  • NxM total modules arranged in M strings of N modules each (modules_per_string=N, strings_per_inverter=M).

The attributes should generally be things that don’t change about the system, such the type of module and the inverter. The instance methods accept arguments for things that do change, such as irradiance and temperature.

See https://doi.org/10.1002/pip.3387

Parameters:

  • surface_tilt (float or array-like, default 0) – Surface tilt angles in decimal degrees. The tilt angle is defined as degrees from horizontal (e.g. surface facing up = 0, surface facing horizon = 90)

  • surface_azimuth (float or array-like, default 180) – Azimuth angle of the module surface. North=0, East=90, South=180, West=270.

  • module (None or string, default None) – The model name of the modules. May be used to look up the module_parameters dictionary via some other method.

  • module_parameters (None, dict or Series, default None) – Module parameters as defined by the SAPM, CEC, or other.

  • modules_per_string (int or float, default 1) – See system topology discussion above.

  • strings_per_inverter (int or float, default 1) – See system topology discussion above.

  • inverter (None or string, default None) – The model name of the inverters. May be used to look up the inverter_parameters dictionary via some other method.

  • inverter_parameters (None, dict or Series, default None) – Inverter parameters as defined by the SAPM, CEC, or other.

  • racking_model (None or string, default 'freestanding') – Used for cell and module temperature calculations.

  • losses_parameters (None, dict or Series, default None) – Losses parameters as defined by PVWatts or other.

  • in_singleaxis_tracker (None or bool, defult False) – Conttros if the system is mounted in a NS single axis tracker If true, it affects get_aoi() and get_irradiance()

  • name (None or string, default None) –

  • **kwargs – Arbitrary keyword arguments. Included for compatibility, but not used.

calcparams_pvsyst(dii, poa_flatplate_static, temp_cell_cpv, temp_cell_flatplate)[source]

Use the calcparams_pvsyst() function, the input parameters and self.module_parameters to calculate the module currents and resistances.

Parameters:

  • dii (numeric) – Direct (on the) Inclinated (plane) Irradiance [StaticCPVSystem]

  • poa_flatplate_static (numeric) – Plane of Array Irradiance [StaticFlatPlateSystem]

  • temp_cell (float or Series) – The average cell temperature of cells within a module in C.

Returns:

See pvsystem.calcparams_pvsyst for details

get_effective_irradiance(solar_zenith, solar_azimuth, dni, ghi=None, dhi=None, dii=None, gii=None, dni_extra=None, airmass=None, model='haydavies', spillage=0, **kwargs)[source]

Calculates the effective irradiance (taking into account the IAM) TO BE VALIDATED

Parameters:

  • solar_zenith (float or Series.) – Solar zenith angle.

  • solar_azimuth (float or Series.) – Solar azimuth angle.

  • dni (numeric) – Direct Normal Irradiance

  • ghi (numeric) – Global horizontal irradiance

  • dhi (numeric) – Diffuse horizontal irradiance

  • dii (numeric) – Direct (on the) Inclinated (plane) Irradiance

  • gii (numeric) – Global (on the) Inclinated (plane) Irradiance

  • dni_extra (None or numeric, default None) – Extraterrestrial direct normal irradiance

  • airmass (None or numeric, default None) – Airmass

  • model (String, default 'isotropic') – Irradiance model.

  • spillage (float) – Percentage of dii allowed to pass into the system

Returns:

  • dii_effective (float or Series) – Effective Direct (on the) Inclinated (plane) Irradiance [StaticCPVSystem] Beam component of the plane of array irradiance plus the effect of AOI

  • poa_flatplate_static_effective (float or Series) – Effective Direct (on the) Inclinated (plane) Irradiance [StaticFlatPlateSystem] Plane of array irradiance plus the effect of AOI

get_global_utilization_factor_cpv(airmass_absolute, temp_air)[source]

Retrieves the global utilization factor (Air mass and Air temperature CPV effects) for the StaticCPVSystem subsystem

Parameters:

  • airmass (numeric) – absolute airmass.

  • temp_air (numeric) – Ambient dry bulb temperature in degrees C.

Returns:

uf_global (numeric) – the global utilization factor.

pvsyst_celltemp(dii, poa_flatplate_static, temp_air, wind_speed=1.0)[source]

Uses pvsystem.pvsyst_celltemp() to calculate module temperatures based on self.racking_model and the input parameters.

Parameters:

  • dii (numeric) – Direct (on the) Inclinated (plane) Irradiance [StaticCPVSystem]

  • poa_flatplate_static (numeric) – Plane of Array Irradiance [StaticFlatPlateSystem]

  • pvsystem.pvsyst_celltemp for details (See) –

Returns:

See pvsystem.pvsyst_celltemp for details

singlediode(diode_parameters_cpv, diode_parameters_flatplate, ivcurve_pnts=None)[source]

Wrapper around the singlediode() function.

Parameters:

pvsystem.singlediode for details [StaticCPVSystem & StaticFlatPlateSystem()] (See) –

Returns:

See pvsystem.singlediode for details

cpvlib.cpvsystem.get_simple_util_factor(x, thld, m_low, m_high)[source]

Retrieves the utilization factor for a variable.

Parameters:

  • x (numeric / pd.Series) – variable value(s) for the utilization factor calc.

  • thld (numeric) – limit between the two regression lines of the utilization factor.

  • m_low (numeric) – slope of the first regression line of the utilization factor.

  • m_high (numeric) – slope of the second regression line of the utilization factor.

Returns:

single_uf (numeric) – utilization factor for the x variable.