diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index f83f8ab96d..8cc49153fa 100644 --- a/pvlib/modelchain.py +++ b/pvlib/modelchain.py @@ -245,12 +245,15 @@ def get_orientation(strategy, **kwargs): return surface_tilt, surface_azimuth +# Type for fields that vary between arrays +T = TypeVar('T') + + +PerArray = Union[T, Tuple[T, ...]] + + @dataclass class ModelChainResult: - _T = TypeVar('T') - PerArray = Union[_T, Tuple[_T, ...]] - """Type for fields that vary between arrays""" - # these attributes are used in __setattr__ to determine the correct type. _singleton_tuples: bool = field(default=False) _per_array_fields = {'total_irrad', 'aoi', 'aoi_modifier', @@ -260,27 +263,99 @@ class ModelChainResult: # system-level information solar_position: Optional[pd.DataFrame] = field(default=None) + """Solar position in a DataFrame containing columns ``'apparent_zenith'``, + ``'zenith'``, ``'apparent_elevation'``, ``'elevation'``, ``'azimuth'`` + (all in degrees), with possibly other columns depending on the solar + position method; see :py:func:`~pvlib.solarposition.get_solarposition` + for details.""" + airmass: Optional[pd.DataFrame] = field(default=None) + """Air mass in a DataFrame containing columns ``'airmass_relative'``, + ``'airmass_absolute'`` (unitless); see + :py:meth:`~pvlib.location.Location.get_airmass` for details.""" + ac: Optional[pd.Series] = field(default=None) + """AC power from the PV system, in a Series [W]""" + tracking: Optional[pd.DataFrame] = field(default=None) + """Orientation of modules on a single axis tracker, in a DataFrame with + columns ``'surface_tilt'``, ``'surface_azimuth'``, ``'aoi'``; see + :py:func:`~pvlib.tracking.singleaxis` for details. + """ + + losses: Optional[Union[pd.Series, float]] = field(default=None) + """Series containing DC loss as a fraction of total DC power, as + calculated by ``ModelChain.losses_model``. + """ # per DC array information total_irrad: Optional[PerArray[pd.DataFrame]] = field(default=None) + """ DataFrame (or tuple of DataFrame, one for each array) containing + columns ``'poa_global'``, ``'poa_direct'`` ``'poa_diffuse'``, + ``poa_sky_diffuse'``, ``'poa_ground_diffuse'`` (W/m2); see + :py:func:`~pvlib.irradiance.get_total_irradiance` for details. + """ + aoi: Optional[PerArray[pd.Series]] = field(default=None) + """ + Series (or tuple of Series, one for each array) containing angle of + incidence (degrees); see :py:func:`~pvlib.irradiance.aoi` for details. + """ + aoi_modifier: Optional[PerArray[Union[pd.Series, float]]] = \ field(default=None) + """Series (or tuple of Series, one for each array) containing angle of + incidence modifier (unitless) calculated by ``ModelChain.aoi_model``, + which reduces direct irradiance for reflections; + see :py:meth:`~pvlib.pvsystem.PVSystem.get_iam` for details. + """ + spectral_modifier: Optional[PerArray[Union[pd.Series, float]]] = \ field(default=None) + """Series (or tuple of Series, one for each array) containing spectral + modifier (unitless) calculated by ``ModelChain.spectral_model``, which + adjusts broadband plane-of-array irradiance for spectral content. + """ + cell_temperature: Optional[PerArray[pd.Series]] = field(default=None) + """Series (or tuple of Series, one for each array) containing cell + temperature (C). + """ + effective_irradiance: Optional[PerArray[pd.Series]] = field(default=None) + """Series (or tuple of Series, one for each array) containing effective + irradiance (W/m2) which is total plane-of-array irradiance adjusted for + reflections and spectral content. + """ + dc: Optional[PerArray[Union[pd.Series, pd.DataFrame]]] = \ field(default=None) + """Series or DataFrame (or tuple of Series or DataFrame, one for + each array) containing DC power (W) for each array, calculated by + ``ModelChain.dc_model``. + """ + diode_params: Optional[PerArray[pd.DataFrame]] = field(default=None) + """DataFrame (or tuple of DataFrame, one for each array) containing diode + equation parameters (columns ``'I_L'``, ``'I_o'``, ``'R_s'``, ``'R_sh'``, + ``'nNsVth'``, present when ModelChain.dc_model is a single diode model; + see :py:func:`~pvlib.pvsystem.singlediode` for details. + """ + dc_ohmic_losses: Optional[PerArray[pd.Series]] = field(default=None) - losses: Optional[Union[pd.Series, float]] = field(default=None) + """Series (or tuple of Series, one for each array) containing DC ohmic + loss (W) calculated by ``ModelChain.dc_ohmic_model``. + """ + # copies of input data, for user convenience weather: Optional[PerArray[pd.DataFrame]] = None + """DataFrame (or tuple of DataFrame, one for each array) contains a + copy of the input weather data. + """ + times: Optional[pd.DatetimeIndex] = None + """DatetimeIndex containing a copy of the index of the input weather data. + """ def _result_type(self, value): """Coerce `value` to the correct type according to diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 1cd8618ca9..7623cc009f 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -3074,6 +3074,10 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, Rw: numeric Equivalent resistance [ohm] + See Also + -------- + :py:func:`~pvlib.pvsystem.dc_ohmic_losses` + References ---------- .. [1] PVsyst 7 Help. "Array ohmic wiring loss". @@ -3105,6 +3109,10 @@ def dc_ohmic_losses(resistance, current): loss: numeric Power Loss [W] + See Also + -------- + :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` + References ---------- .. [1] PVsyst 7 Help. "Array ohmic wiring loss".