From ad6fce244cfd081ebb7944dce374a126a979ce35 Mon Sep 17 00:00:00 2001 From: Chirag3841 Date: Wed, 26 Nov 2025 19:18:47 +0530 Subject: [PATCH 1/2] 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 cc3928586e4a84464f94638ecd4140a4cf8eb5fb Mon Sep 17 00:00:00 2001 From: Chirag3841 Date: Wed, 26 Nov 2025 20:03:02 +0530 Subject: [PATCH 2/2] Add detailed docstrings for WEATHER_KEYS, POA_KEYS, and TEMPERATURE_KEYS --- pvlib/modelchain.py | 28 +++++++--------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py index 9096b1a637..73581729a6 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 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. +# Keys used to detect input data and assign values to the appropriate +# ModelChain attributes. +# Weather-related input columns for ModelChain.weather WEATHER_KEYS = ( 'ghi', # Global Horizontal Irradiance (W/m^2) 'dhi', # Diffuse Horizontal Irradiance (W/m^2) @@ -34,30 +27,23 @@ 'temp_air', # Ambient air temperature (°C) 'precipitable_water' # Column precipitable water (cm) ) - -# For ModelChain.total_irrad: -# Plane-of-array irradiance components. -#: list[str]: Required POA irradiance input columns. +# 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 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. +# Temperature-related optional input columns for ModelChain TEMPERATURE_KEYS = ( 'module_temperature', # Back-surface module temperature (°C) 'cell_temperature', # Direct cell temperature input (°C) ) +# 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: