Merge branch 'main' into polo-smm

Author: kandersolar

docs/sphinx/source/reference/iotools.rst

@@ -233,7 +233,6 @@ lower quality.
 
    iotools.read_crn
 
-
 ECMWF ERA5
 ^^^^^^^^^^
 
@@ -244,6 +243,17 @@ A global reanalysis dataset providing weather and solar resource data.
 
    iotools.get_era5
 
+MERRA-2
+^^^^^^^
+
+A global reanalysis dataset providing weather, aerosol, and solar irradiance
+data.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_merra2
+
 
 Generic data file readers
 -------------------------

docs/sphinx/source/user_guide/index.rst

@@ -26,6 +26,7 @@ This user guide is an overview and explains some of the key features of pvlib.
    modeling_topics/clearsky
    modeling_topics/weather_data
    modeling_topics/singlediode
+   modeling_topics/temperature
 
 .. toctree::
    :maxdepth: 2

docs/sphinx/source/user_guide/modeling_topics/temperature.rst

@@ -0,0 +1,107 @@
+.. _temperature:
+
+Temperature models
+==================
+
+pvlib provides a variety of models for predicting the operating temperature
+of a PV module from irradiance and weather inputs.  These models range from
+simple empirical equations requiring just a few multiplications to more complex
+thermal balance models with numerical integration.
+
+Types of models
+---------------
+
+Temperature models predict one of two quantities:
+
+- *module temperature*: the temperature as measured at the back surface
+  of a PV module.  Easy to measure, but usually marginally less
+  than the cell temperature which determines efficiency.
+- *cell temperature*: the temperature of the PV cell itself.  The relevant
+  temperature for PV modeling, but almost never measured directly.
+
+Temperature models estimate these quantities using inputs like incident
+irradiance, ambient temperature, and wind speed.  Each model also takes
+a set of parameter values that represent how a PV module responds to
+those inputs.
+
+Parameter values generally depend on both the PV
+module technologies, the mounting configuration of the module,
+and on any weather parameters that are not included in the model.
+Note that, despite models conventionally being associated with either
+cell or module temperature, it is actually the parameter values that determine
+which of the two temperatures are predicted, as they will produce the same
+type of temperature from which they were originally derived.
+
+Another aspect of temperature models is whether they account for
+the thermal inertia of a PV module.  Temperature models are either:
+
+- *steady-state*: the module is assumed to have been at the specified operating
+  conditions for a sufficiently long time for its temperature to reach
+  equilibrium.
+- *transient*: the module's thermal inertia is included in the model,
+  causing a lag in modeled temperature change following changes in the inputs.
+
+Other effects that temperature models may consider include the
+photoconversion efficiency and radiative cooling.
+
+The temperature models currently available in pvlib are summarized in the
+following table:
+
++----------------------------------------------+--------+------------+---------------------------------------------------------------------------+
+| Model                                        | Type   | Transient? | Weather inputs                                                            |
+|                                              |        |            +----------------+---------------------+------------+-----------------------+
+|                                              |        |            | POA irradiance | Ambient temperature | Wind speed | Downwelling IR [#f1]_ |
++==============================================+========+============+================+=====================+============+=======================+
+| :py:func:`~pvlib.temperature.faiman`         | either |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.faiman_rad`     | either |            | ✓              | ✓                   | ✓          | ✓                     |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.fuentes`        | either | ✓          | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.generic_linear` | either |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.noct_sam`       | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.pvsyst_cell`    | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.ross`           | cell   |            | ✓              | ✓                   |            |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.sapm_cell`      | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.sapm_module`    | module |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+
+.. [#f1] Downwelling infrared radiation.
+
+In addition to the core models above, pvlib provides several other functions
+for temperature modeling:
+
+- :py:func:`~pvlib.temperature.prilliman`: an "add-on" model that reprocesses
+  the output of a steady-state model to apply transient effects.
+- :py:func:`~pvlib.temperature.sapm_cell_from_module`: a model for
+  estimating cell temperature from module temperature.
+
+
+Model parameters
+----------------
+
+Some temperature model functions provide default values for their parameters,
+and several additional sets of temperature model parameter values are
+available in :py:data:`pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS`.
+However, these generic values may not be suitable for all modules and mounting
+configurations. It should be noted that using the default parameter values for each 
+model generally leads to different modules temperature predictions. This alone
+does not mean one model is better than another; it's just evidence that the measurements
+used to derive the default parameter values were taken on different PV systems in different
+locations under different conditions.
+
+Parameter values for one model (e.g. ``u0``, ``u1`` for :py:func:`~pvlib.temperature.faiman`)
+can be converted to another model (e.g. ``u_c``, ``u_v`` for :py:func:`~pvlib.temperature.pvsyst_cell`)
+using :py:class:`~pvlib.temperature.GenericLinearModel`.
+
+Module-specific values can be obtained via testing, for example following
+the IEC 61853-2 standard for the Faiman model; however, such values still do not capture 
+the dependency of temperature on system design and other variables.
+
+Currently, pvlib provides no functionality for fitting parameter values
+using measured temperature.

docs/sphinx/source/whatsnew/v0.12.0.rst

@@ -94,7 +94,7 @@ Contributors
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
 * Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
 * Will Holmgren (:ghuser:`wholmgren`)
-* Sophie Pelland (:ghuser:`solphie-pelland`)
+* Sophie Pelland (:ghuser:`sophie-pelland`)
 * Will Hobbs (:ghuser:`williamhobbs`)
 * Karel De Brabandere (:ghuser:`kdebrab`)
 * Kenneth J. Sauer (:ghuser:`kjsauer`)

docs/sphinx/source/whatsnew/v0.13.2.rst

@@ -18,7 +18,6 @@ Deprecations
 Bug fixes
 ~~~~~~~~~
 
-
 Enhancements
 ~~~~~~~~~~~~
 * Add :py:func:`~pvlib.ivtools.sdm.fit_desoto_batzelis`, a function to estimate
@@ -43,12 +42,15 @@ Enhancements
   installed. (:issue:`2497`, :pull:`2571`)
 * Add :py:func:`~pvlib.iotools.get_era5`, a function for accessing
   ERA5 reanalysis data. (:pull:`2573`)
+* Add :py:func:`~pvlib.iotools.get_merra2`, a function for accessing
+  MERRA-2 reanalysis data. (:pull:`2572`)
 * Add :py:func:`~pvlib.spectrum.spectral_factor_polo`, a function for estimating
   spectral mismatch factors for vertical PV façades. (:issue:`2406`, :pull:`2491`)
 
 Documentation
 ~~~~~~~~~~~~~
 * Provide an overview of single-diode modeling functionality in :ref:`singlediode`. (:pull:`2565`)
+* Provide an overview of temperature modeling functionality in :ref:`temperature`. (:pull:`2591`)
 * Fix typo in parameter name ``atmos_refract`` in :py:func:`pvlib.solarposition.spa_python`
   and :py:func:`pvlib.spa.solar_position`. (:issue:`2532`, :pull:`2592`)
 
@@ -58,6 +60,8 @@ Testing
 * Add Python 3.14 to test suite. (:pull:`2590`)
 * Update pytest configuration in ``pyproject.toml`` to work with pytest 9.0.
   (:pull:`2596`)
+* Correct argument and value order in :py:func:`~pvlib.tests.ivtools.test_sde`,
+  in tests of :py:func:`~pvlib.ivtools.sde._fit_sandia_cocontent`. (:issue:`2613`, :pull:`2615`)
 
 
 Benchmarking

pvlib/iotools/__init__.py

@@ -43,3 +43,4 @@
 from pvlib.iotools.meteonorm import get_meteonorm_tmy  # noqa: F401
 from pvlib.iotools.nasa_power import get_nasa_power  # noqa: F401
 from pvlib.iotools.era5 import get_era5  # noqa: F401
+from pvlib.iotools.merra2 import get_merra2  # noqa: F401

pvlib/iotools/acis.py

@@ -413,8 +413,8 @@ def get_acis_station_data(station, start, end, trace_val=0.001,
                  'climdiv,valid_daterange,tzo,network')
     }
     df, metadata = _get_acis(start, end, params, map_variables, url, **kwargs)
-    df = df.replace("M", np.nan)
-    df = df.replace("T", trace_val)
+    df = df.mask(df == 'M', np.nan)
+    df = df.mask(df == 'T', trace_val)
     df = df.astype(float)
     return df, metadata
 

pvlib/iotools/era5.py

@@ -12,13 +12,15 @@
     'sp': 'pressure',
     'ssrd': 'ghi',
     'tp': 'precipitation',
+    'strd': 'longwave_down',
 
     # long names
     '2m_dewpoint_temperature': 'temp_dew',
     '2m_temperature': 'temp_air',
     'surface_pressure': 'pressure',
     'surface_solar_radiation_downwards': 'ghi',
     'total_precipitation': 'precipitation',
+    'surface_thermal_radiation_downwards': 'longwave_down',
 }