From 5f60c770a88fecf3084d36736f7d432d59adfbf4 Mon Sep 17 00:00:00 2001 From: Chirag3841 Date: Wed, 26 Nov 2025 19:18:47 +0530 Subject: [PATCH 1/3] Add detailed docstrings for WEATHER_KEYS, POA_KEYS, and TEMPERATURE_KEYS --- pvlib/modelchain.py | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index 09e4434e84..9096b1a637 100644 --- a/pvlib/modelchain.py +++ b/pvlib/modelchain.py @@ -22,20 +22,35 @@ # keys that are used to detect input data and assign data to appropriate # ModelChain attribute -# for ModelChain.weather -WEATHER_KEYS = ('ghi', 'dhi', 'dni', 'wind_speed', 'temp_air', - 'precipitable_water') -# for ModelChain.total_irrad -POA_KEYS = ('poa_global', 'poa_direct', 'poa_diffuse') +# For ModelChain.weather: +# Maps weather-related input columns to the weather DataFrame. +#: list[str]: Required or optional weather input columns. +WEATHER_KEYS = ( + 'ghi', # Global Horizontal Irradiance (W/m^2) + 'dhi', # Diffuse Horizontal Irradiance (W/m^2) + 'dni', # Direct Normal Irradiance (W/m^2) + 'wind_speed', # Wind speed (m/s) + 'temp_air', # Ambient air temperature (°C) + 'precipitable_water' # Column precipitable water (cm) +) -# Optional keys to communicate temperature data. If provided, -# 'cell_temperature' overrides ModelChain.temperature_model and sets -# ModelChain.cell_temperature to the data. If 'module_temperature' is provided, -# overrides ModelChain.temperature_model with -# pvlib.temperature.sapm_cell_from_module -TEMPERATURE_KEYS = ('module_temperature', 'cell_temperature') +# For ModelChain.total_irrad: +# Plane-of-array irradiance components. +#: list[str]: Required POA irradiance input columns. +POA_KEYS = ( + 'poa_global', # Total plane-of-array irradiance (W/m^2) + 'poa_direct', # Direct normal POA irradiance (W/m^2) + 'poa_diffuse' # Diffuse POA irradiance (W/m^2) +) +# Optional keys for temperature-specific inputs. +# These override or supplement temperature models. +#: list[str]: Temperature-related input columns. +TEMPERATURE_KEYS = ( + 'module_temperature', # Back-surface module temperature (°C) + 'cell_temperature', # Direct cell temperature input (°C) +) DATA_KEYS = WEATHER_KEYS + POA_KEYS + TEMPERATURE_KEYS # these dictionaries contain the default configuration for following From 840c198828f5b017aede610fab7b900e2bcdfdbd Mon Sep 17 00:00:00 2001 From: Chirag3841 Date: Wed, 26 Nov 2025 20:03:02 +0530 Subject: [PATCH 2/3] Add detailed docstrings for WEATHER_KEYS, POA_KEYS, and TEMPERATURE_KEYS --- pvlib/modelchain.py | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index 9096b1a637..5db0f1289d 100644 --- a/pvlib/modelchain.py +++ b/pvlib/modelchain.py @@ -19,13 +19,13 @@ from pvlib.tools import _build_kwargs from pvlib._deprecation import deprecated +# Keys used to detect input data and assign values to the appropriate +# ModelChain attributes. -# keys that are used to detect input data and assign data to appropriate -# ModelChain attribute - -# For ModelChain.weather: -# Maps weather-related input columns to the weather DataFrame. -#: list[str]: Required or optional weather input columns. +#: tuple[str] +#: Weather-related input columns used by :class:`ModelChain` to populate +#: ``ModelChain.weather``. Missing ``temp_air`` or ``wind_speed`` are +#: automatically filled (20 °C and 0 m/s). WEATHER_KEYS = ( 'ghi', # Global Horizontal Irradiance (W/m^2) 'dhi', # Diffuse Horizontal Irradiance (W/m^2) @@ -35,24 +35,26 @@ 'precipitable_water' # Column precipitable water (cm) ) -# For ModelChain.total_irrad: -# Plane-of-array irradiance components. -#: list[str]: Required POA irradiance input columns. +#: tuple[str] +#: Plane-of-array irradiance components used to populate +#: ``ModelChain.total_irrad`` when running from POA input. POA_KEYS = ( 'poa_global', # Total plane-of-array irradiance (W/m^2) - 'poa_direct', # Direct normal POA irradiance (W/m^2) + 'poa_direct', # Direct POA irradiance (W/m^2) 'poa_diffuse' # Diffuse POA irradiance (W/m^2) ) -# Optional keys for temperature-specific inputs. -# These override or supplement temperature models. -#: list[str]: Temperature-related input columns. +#: tuple[str] +#: Temperature-related input columns that override or supplement the +#: ModelChain temperature model. If ``cell_temperature`` is provided, +#: the temperature model is skipped. TEMPERATURE_KEYS = ( 'module_temperature', # Back-surface module temperature (°C) 'cell_temperature', # Direct cell temperature input (°C) ) +#: tuple[str] +#: All supported input keys recognized by ModelChain. DATA_KEYS = WEATHER_KEYS + POA_KEYS + TEMPERATURE_KEYS - # these dictionaries contain the default configuration for following # established modeling sequences. They can be used in combination with # ModelChain, particularly they are used by the methods From 196cd7c861fb9c5641087ed0e237a59edeced503 Mon Sep 17 00:00:00 2001 From: Chirag3841 Date: Thu, 27 Nov 2025 13:29:59 +0530 Subject: [PATCH 3/3] Fixed indentation in run_model_from_poa function --- pvlib/modelchain.py | 68 ++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index 5db0f1289d..2b145da4f8 100644 --- a/pvlib/modelchain.py +++ b/pvlib/modelchain.py @@ -5,27 +5,20 @@ library. With great power comes great responsibility: users should take the time to read the source code for the module. """ - from functools import partial import itertools import warnings import pandas as pd from dataclasses import dataclass, field from typing import Union, Tuple, Optional, TypeVar - from pvlib import pvsystem, iam import pvlib.irradiance # avoid name conflict with full import from pvlib.pvsystem import _DC_MODEL_PARAMS from pvlib.tools import _build_kwargs - from pvlib._deprecation import deprecated # Keys used to detect input data and assign values to the appropriate # ModelChain attributes. - -#: tuple[str] -#: Weather-related input columns used by :class:`ModelChain` to populate -#: ``ModelChain.weather``. Missing ``temp_air`` or ``wind_speed`` are -#: automatically filled (20 °C and 0 m/s). +# Weather-related input columns for ModelChain.weather WEATHER_KEYS = ( 'ghi', # Global Horizontal Irradiance (W/m^2) 'dhi', # Diffuse Horizontal Irradiance (W/m^2) @@ -34,32 +27,23 @@ 'temp_air', # Ambient air temperature (°C) 'precipitable_water' # Column precipitable water (cm) ) - -#: tuple[str] -#: Plane-of-array irradiance components used to populate -#: ``ModelChain.total_irrad`` when running from POA input. +# Plane-of-array irradiance input columns for ModelChain.total_irrad POA_KEYS = ( 'poa_global', # Total plane-of-array irradiance (W/m^2) 'poa_direct', # Direct POA irradiance (W/m^2) 'poa_diffuse' # Diffuse POA irradiance (W/m^2) ) - -#: tuple[str] -#: Temperature-related input columns that override or supplement the -#: ModelChain temperature model. If ``cell_temperature`` is provided, -#: the temperature model is skipped. +# Temperature-related optional input columns for ModelChain TEMPERATURE_KEYS = ( 'module_temperature', # Back-surface module temperature (°C) 'cell_temperature', # Direct cell temperature input (°C) ) -#: tuple[str] -#: All supported input keys recognized by ModelChain. +# All supported input keys combined DATA_KEYS = WEATHER_KEYS + POA_KEYS + TEMPERATURE_KEYS # these dictionaries contain the default configuration for following # established modeling sequences. They can be used in combination with # ModelChain, particularly they are used by the methods # ModelChain.with_pvwatts, ModelChain.with_sapm, etc. - # pvwatts documentation states that it uses the following reference for # a temperature model: Fuentes, M. K. (1987). A Simplified Thermal Model # for Flat-Plate Photovoltaic Arrays. SAND85-0330. Albuquerque, NM: @@ -1730,6 +1714,27 @@ def run_model_from_poa(self, data): of Arrays in the PVSystem. ValueError If the DataFrames in `data` have different indexes. + Examples + -------- + Single-array system: + + >>> import pandas as pd + >>> from pvlib.pvsystem import PVSystem + >>> from pvlib.location import Location + >>> from pvlib.modelchain import ModelChain + >>> + >>> system = PVSystem(module_parameters={'pdc0': 300}) + >>> location = Location(35, -110) + >>> mc = ModelChain(system, location) + >>> + >>> poa = pd.DataFrame({ + ... 'poa_global': [900, 850], + ... 'poa_direct': [600, 560], + ... 'poa_diffuse': [300, 290], + ... }, index=pd.date_range("2021-06-01", periods=2, freq="H")) + >>> + >>> mc.run_model_from_poa(poa) + Notes ----- @@ -1755,7 +1760,6 @@ def run_model_from_poa(self, data): self._run_from_effective_irrad(data) return self - def _run_from_effective_irrad(self, data): """ Executes the temperature, DC, losses and AC models. @@ -1774,7 +1778,7 @@ def _run_from_effective_irrad(self, data): Notes ----- - Assigns attributes:``cell_temperature``, ``dc``, ``ac``, ``losses``, + Assigns attributes:``cell_temperature, 'dc', ``ac', ``losses``, ``diode_params`` (if dc_model is a single diode model). """ self._prepare_temperature(data) @@ -1815,6 +1819,25 @@ def run_model_from_effective_irradiance(self, data): of Arrays in the PVSystem. ValueError If the DataFrames in `data` have different indexes. + Examples + -------- + >>> import pandas as pd + >>> from pvlib.pvsystem import PVSystem + >>> from pvlib.location import Location + >>> from pvlib.modelchain import ModelChain + >>> + >>> system = PVSystem(module_parameters={'pdc0': 300}) + >>> location = Location(35, -110) + >>> mc = ModelChain(system, location) + >>> + >>> eff = pd.DataFrame({ + ... 'effective_irradiance': [900, 920], + ... 'temp_air': [25, 24], + ... 'wind_speed': [2.0, 1.5], + ... }) + >>> + >>> mc.run_model_from_effective_irradiance(eff) + Notes ----- @@ -1853,6 +1876,7 @@ def run_model_from_effective_irradiance(self, data): return self + def _irrad_for_celltemp(total_irrad, effective_irradiance): """ Determine irradiance to use for cell temperature models, in order