pvlib 0.12.0__tar.gz → 0.13.0__tar.gz

{pvlib-0.12.0/pvlib.egg-info → pvlib-0.13.0}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.4
 Name: pvlib
-Version: 0.12.0
+Version: 0.13.0
 Summary: A set of functions and classes for simulating the performance of photovoltaic energy systems.
 Home-page: https://github.com/pvlib/pvlib-python
 Author-email: pvlib python Developers <pvlib-admin@googlegroups.com>
-License: BSD-3-Clause
+License-Expression: BSD-3-Clause
 Project-URL: Bug Tracker, https://github.com/pvlib/pvlib-python/issues
 Project-URL: Documentation, https://pvlib-python.readthedocs.io/
 Project-URL: Source Code, https://github.com/pvlib/pvlib-python
 Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python

pvlib-0.13.0/docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py

@@ -0,0 +1,163 @@
+"""
+Agrivoltaic system modeling
+===========================
+
+Irradiance at crop level between rows
+"""
+
+# %%
+# This example demonstrates how to calculate power output for a bifacial
+# agriPV plant as well as calculating the irradiance at crop level
+# using pvlib's infinite sheds model.
+# For an overview of agrivPV concepts and performance, the reader
+# is referred to :doi:`10.69766/XAEU5008`.
+#
+# This gallery example is based on an actual AgriPV plant, namely
+# European Energy's `Flakkebjerg AgriPV site
+# <https://europeanenergy.com/2023/12/20/using-the-same-land-twice-at-european-\
+# energys-flakkebjerg-solar-park/>`_.
+#
+# The first steps are to define the plant location and to calculate solar
+# position and clearsky irradiance for a single day as an example.
+#
+# .. figure:: ../../_images/agrivoltaics_system.jpg
+#    :align: center
+#    :width: 75%
+#    :alt: Photo of an agriPV system
+#
+#    Photo of an agriPV system.
+#    *Source: Adam R. Jensen*
+
+import pvlib
+import pandas as pd
+from pvlib.tools import cosd
+import matplotlib.pyplot as plt
+
+# sphinx_gallery_thumbnail_path = '_images/agrivoltaics_system.jpg'
+
+location = pvlib.location.Location(latitude=55, longitude=10)
+
+times = pd.date_range('2020-06-28', periods=24*60, freq='1min', tz='UTC')
+
+solpos = location.get_solarposition(times)
+
+clearsky = location.get_clearsky(times, model='ineichen')
+
+# %%
+# Next, we need to define the plant layout:
+
+height = 2.6  # [m] height of torque above ground
+pitch = 12  # [m] row spacing
+row_width = 2 * 2.384  # [m] two modules in portrait, each 2 m long
+gcr = row_width / pitch  # ground coverage ratio [unitless]
+axis_azimuth = 0  # [degrees] north-south tracking axis
+max_angle = 55  # [degrees] maximum rotation angle
+
+# %%
+# Before running the infinite sheds model, we need to know the orientation
+# of the trackers. For a single-axis tracker, this can be calculated as:
+
+tracking_orientations = pvlib.tracking.singleaxis(
+    apparent_zenith=solpos['apparent_zenith'],
+    apparent_azimuth=solpos['azimuth'],
+    axis_azimuth=axis_azimuth,
+    max_angle=max_angle,
+    backtrack=True,
+    gcr=gcr,
+)
+
+# %%
+# For agrivPV systems, the local albedo is dependent on crop growth and thus
+# changes throughout the seasons. In this example, we only simulate one
+# day and thus use a constant value. Similarly, we will assume a constant
+# air temperature to avoid getting external data. Both albedo and air
+# temperature could be defined as Series with the same index as used for the
+# solar position calculations.
+
+albedo = 0.20  # [unitless]
+temp_air = 18  # [degrees C]
+
+# %%
+# Now, we are ready to calculate the front and rear-side irradiance using
+# the pvlib infinite sheds model.
+
+dni_extra = pvlib.irradiance.get_extra_radiation(times)
+
+irradiance = pvlib.bifacial.infinite_sheds.get_irradiance(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    surface_azimuth=tracking_orientations['surface_azimuth'],
+    solar_zenith=solpos['apparent_zenith'],
+    solar_azimuth=solpos['azimuth'],
+    gcr=gcr,
+    height=height,
+    pitch=pitch,
+    ghi=clearsky['ghi'],
+    dhi=clearsky['dhi'],
+    dni=clearsky['dni'],
+    albedo=albedo,
+    model='haydavies',
+    dni_extra=dni_extra,
+    bifaciality=0.7,  # [unitless] rear-side power relative to front-side
+)
+
+# %%
+# Once the in-plane irradiance is known, we can estimate the PV array power.
+# For simplicity, we use the PVWatts model:
+
+N_modules = 1512  # [unitless] Number of modules
+pdc0_per_module = 660  # [W] STC rating
+pdc0 = pdc0_per_module * N_modules
+
+gamma_pdc = -0.004  # [1/degrees C]
+
+temp_cell = pvlib.temperature.faiman(
+    poa_global=irradiance['poa_global'],
+    temp_air=temp_air,
+)
+
+power_dc = pvlib.pvsystem.pvwatts_dc(
+    effective_irradiance=irradiance['poa_global'],
+    temp_cell=temp_cell,
+    pdc0=pdc0,
+    gamma_pdc=gamma_pdc)
+
+power_dc.divide(1000).plot()
+plt.ylabel('DC power [kW]')
+plt.show()
+
+# %%
+# In addition to the power output of the PV array, we are also interested
+# in how much irradiance reaches the crops under the array. In this case
+# we calculate the average irradiance on the ground between two rows, using
+# the infinite sheds utility functions.
+#
+# This consists of two parts. First we determine the diffuse irradiance on
+# ground and second we calculate the fraction of the ground that is unshaded
+# (i.e., receives DNI).
+
+vf_ground_sky = pvlib.bifacial.utils.vf_ground_sky_2d_integ(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    gcr=gcr,
+    height=height,
+    pitch=pitch,
+)
+
+unshaded_ground_fraction = pvlib.bifacial.utils._unshaded_ground_fraction(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    surface_azimuth=tracking_orientations['surface_azimuth'],
+    solar_zenith=solpos['apparent_zenith'],
+    solar_azimuth=solpos['azimuth'],
+    gcr=gcr,
+)
+
+crop_avg_irradiance = (unshaded_ground_fraction * clearsky['dni']
+                       * cosd(solpos['apparent_zenith'])
+                       + vf_ground_sky * clearsky['dhi'])
+
+fig, ax = plt.subplots()
+clearsky['ghi'].plot(ax=ax, label='Horizontal irradiance above panels')
+crop_avg_irradiance.plot(ax=ax, label='Horizontal irradiance at crop level')
+ax.legend(loc='upper center')
+ax.set_ylabel('Irradiance [W/m$^2$]')
+ax.set_ylim(-10, 1050)
+plt.show()

{pvlib-0.12.0 → pvlib-0.13.0}/docs/examples/system-models/plot_oedi_9068.py

@@ -165,7 +165,7 @@ psm3, psm3_metadata = pvlib.iotools.get_psm3(latitude, longitude, api_key,
 # module fraction and returns the average irradiance over the total module
 # surface.
 
-solar_position = location.get_solarposition(psm3.index, latitude, longitude)
+solar_position = location.get_solarposition(psm3.index)
 tracker_angles = mount.get_orientation(
     solar_position['apparent_zenith'],
     solar_position['azimuth']

{pvlib-0.12.0 → pvlib-0.13.0}/docs/sphinx/source/conf.py

@@ -66,7 +66,7 @@ mathjax3_config = {'chtml': {'displayAlign': 'left',
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
     'matplotlib': ('https://matplotlib.org/stable', None),
 }
@@ -412,6 +412,41 @@ warnings.filterwarnings("ignore", category=UserWarning,
 # https://gist.github.com/flying-sheep/b65875c0ce965fbdd1d9e5d0b9851ef1
 
 
+# select correct base URL depending on the build system context
+def get_source_files_base_url():
+    """
+    Get the base URL for the source code to generate links to GitHub source.
+    If the build is on ReadTheDocs and it's a stable version, use the
+    versioned link. If it's a latest version, use the main link.
+
+    For other builds (e.g. pull requests), use the main link.
+    Local builds will also use the main link.
+
+    Resulting base URL should end with a trailing slash.
+
+    See https://docs.readthedocs.com/platform/stable/reference/environment-variables.html
+    """  # noqa: E501
+    repo_url = os.environ.get(
+        "READTHEDOCS_GIT_CLONE_URL",
+        default="https://github.com/pvlib/pvlib-python",
+    )
+    READTHEDOCS_ENV = os.environ.get("READTHEDOCS", None) == "True"
+    READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION", None)
+    READTHEDOCS_GIT_IDENTIFIER = os.environ.get(
+        "READTHEDOCS_GIT_IDENTIFIER", None
+    )
+    if READTHEDOCS_ENV:  # Building docs on ReadTheDocs
+        if READTHEDOCS_VERSION == "latest":  # latest version, commited to main
+            repo_url += "/blob/main/"
+        elif READTHEDOCS_VERSION == "stable":  # stable version, has a tag
+            repo_url += f"/blob/{READTHEDOCS_GIT_IDENTIFIER}/"
+        else:  # pull request, user and branch are unknown so use main
+            repo_url += "/blob/main/"
+    else:  # Local build
+        repo_url += "/blob/main/"  # can't tell where to point to
+    return repo_url
+
+
 def get_obj_module(qualname):
     """
     Get a module/class/attribute and its original module by qualname.
@@ -456,6 +491,9 @@ def get_linenos(obj):
         return start, start + len(lines) - 1
 
 
+URL_BASE = get_source_files_base_url()  # Edit on GitHub source code links
+
+
 def make_github_url(file_name):
     """
     Generate the appropriate GH link for a given docs page.  This function
@@ -463,11 +501,8 @@ def make_github_url(file_name):
 
     The target URL is built differently based on the type of page.  The pydata
     sphinx theme has a built-in `file_name` variable that looks like
-    "/docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst"
+    "docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst"
     """
-
-    URL_BASE = "https://github.com/pvlib/pvlib-python/blob/main/"
-
     # is it a gallery page?
     if any(d in file_name for d in sphinx_gallery_conf['gallery_dirs']):
         example_folder = file_name.split("/")[-2]

pvlib-0.13.0/docs/sphinx/source/reference/iotools.rst

@@ -0,0 +1,238 @@
+
+.. py:module:: pvlib.iotools
+
+.. currentmodule:: pvlib
+
+.. _iotools:
+
+IO Tools
+========
+
+Functions for retrieving, reading, and writing data from a variety
+of sources and file formats relevant to solar energy modeling.  See also
+:ref:`weatherdata`.
+
+.. contents:: Currently supported APIs
+    :depth: 3
+    :local:
+
+
+Gridded solar resource data
+---------------------------
+
+Modeled irradiance and meteorological data, available for large regions of
+the world.
+
+Public datasets
+^^^^^^^^^^^^^^^
+
+These APIs are free to access, although some require registration.
+
+PVGIS
+*****
+
+Multiple gridded irradiance datasets and weather data with global coverage.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_pvgis_tmy
+   iotools.read_pvgis_tmy
+   iotools.get_pvgis_hourly
+   iotools.read_pvgis_hourly
+   iotools.get_pvgis_horizon
+
+
+CAMS
+****
+
+Satellite-derived irradiance data for Europe, Africa, and Asia, and
+clear-sky irradiance globally.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_cams
+   iotools.read_cams
+   iotools.parse_cams
+
+
+NSRDB
+*****
+
+Satellite-derived irradiance and weather data for the Americas.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_nsrdb_psm4_aggregated
+   iotools.get_nsrdb_psm4_tmy
+   iotools.get_nsrdb_psm4_conus
+   iotools.get_nsrdb_psm4_full_disc
+   iotools.read_nsrdb_psm4
+   iotools.get_psm3
+   iotools.read_psm3
+   iotools.parse_psm3
+
+
+Commercial datasets
+^^^^^^^^^^^^^^^^^^^
+
+Accessing these APIs typically requires payment.
+Datasets provide near-global coverage.
+
+SolarAnywhere
+*************
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_solaranywhere
+   iotools.read_solaranywhere
+
+
+Solcast
+*******
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_solcast_tmy
+   iotools.get_solcast_historic
+   iotools.get_solcast_forecast
+   iotools.get_solcast_live
+
+
+Solargis
+********
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_solargis
+
+
+Ground station solar data
+-------------------------
+
+Measurements from various networks of ground stations
+focusing on solar irradiance.
+
+BSRN
+^^^^
+
+A global network dedicated to high-quality monitoring of solar and
+long-wave radiation.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_bsrn
+   iotools.read_bsrn
+   iotools.parse_bsrn
+
+
+SOLRAD
+^^^^^^
+
+A solar radiation network in the USA, run by NOAA.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_solrad
+   iotools.get_solrad
+
+
+SURFRAD
+^^^^^^^
+
+A solar radiation network in the USA, run by NOAA.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_surfrad
+
+
+MIDC
+^^^^
+
+A solar radiation network in the USA, run by NREL.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_midc
+   iotools.read_midc_raw_data_from_nrel
+
+
+SRML
+^^^^
+
+A solar radiation network in the northwestern USA, run by
+the University of Oregon.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_srml
+   iotools.get_srml
+
+
+Weather data
+------------
+
+Meteorological data from a variety of modeled and measured datasets.
+
+ACIS
+^^^^
+
+A combination of many meteorological datasets providing temperature,
+precipitation, wind speed, and other weather measurements.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_acis_prism
+   iotools.get_acis_nrcc
+   iotools.get_acis_mpe
+   iotools.get_acis_station_data
+   iotools.get_acis_available_stations
+
+
+CRN
+^^^
+
+A network of ground stations from NOAA.  Irradiance measurements are of
+lower quality.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_crn
+
+
+Generic data file readers
+-------------------------
+
+Functions for reading irradiance/weather data files.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_tmy2
+   iotools.read_tmy3
+   iotools.read_epw
+   iotools.parse_epw
+   iotools.read_panond
+
+
+A :py:class:`~pvlib.location.Location` object may be created from metadata
+in some files.
+
+.. autosummary::
+   :toctree: generated/
+
+   location.Location.from_tmy
+   location.Location.from_epw

{pvlib-0.12.0 → pvlib-0.13.0}/docs/sphinx/source/reference/pv_modeling/parameters.rst

@@ -12,6 +12,7 @@ Functions for fitting single diode models
     ivtools.sdm.fit_cec_sam
     ivtools.sdm.fit_desoto
     ivtools.sdm.fit_pvsyst_sandia
+    ivtools.sdm.fit_pvsyst_iec61853_sandia_2025
     ivtools.sdm.fit_desoto_sandia
 
 Functions for fitting the single diode equation

{pvlib-0.12.0/docs/sphinx/source/user_guide → pvlib-0.13.0/docs/sphinx/source/user_guide/getting_started}/installation.rst

@@ -133,7 +133,7 @@ Follow these steps to obtain the library using git/GitHub:
    This button is circled in the image below. Remember the system path that
    you clone the library to.
 
-.. image:: ../_images/clonebutton.png
+.. image:: ../../_images/clonebutton.png
 
 Please see GitHub's
 `Forking Projects <https://guides.github.com/activities/forking/>`_,

pvlib-0.13.0/docs/sphinx/source/user_guide/index.rst

@@ -0,0 +1,34 @@
+.. _user_guide:
+
+==========
+User Guide
+==========
+
+This user guide is an overview and explains some of the key features of pvlib.
+
+.. toctree::
+   :caption: Getting started
+   :maxdepth: 2
+
+   getting_started/package_overview
+   getting_started/installation
+   getting_started/introtutorial
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Modeling topics
+
+   modeling_topics/pvsystem
+   modeling_topics/modelchain
+   modeling_topics/timetimezones
+   modeling_topics/bifacial
+   modeling_topics/clearsky
+   modeling_topics/weather_data
+   modeling_topics/singlediode
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Extras
+
+   extras/nomenclature
+   extras/faq

{pvlib-0.12.0/docs/sphinx/source/user_guide → pvlib-0.13.0/docs/sphinx/source/user_guide/modeling_topics}/bifacial.rst

@@ -80,7 +80,7 @@ The model operates in the following steps:
    determines the fraction of ground-reflected irradiance that reaches the row
    surface.
 4. Find the fraction of the row surface that is shaded from direct irradiance.
-   Only sky and ground-reflected irradiance reach the the shaded fraction of
+   Only sky and ground-reflected irradiance reach the shaded fraction of
    the row surface.
 5. For the front and rear surfaces, apply the incidence angle modifier to
    the direct irradiance and sum the diffuse sky, diffuse ground, and direct

{pvlib-0.12.0/docs/sphinx/source/user_guide → pvlib-0.13.0/docs/sphinx/source/user_guide/modeling_topics}/modelchain.rst

@@ -371,7 +371,7 @@ DC quantities to the output of the full PVSystem.
     mc.results.dc
 
 We’ve established that the ``ModelChain.pvwatts_dc`` and
-``ModelChain.sapm`` have the same API: they take the same arugments
+``ModelChain.sapm`` have the same API: they take the same arguments
 (``self``) and they both set the ``dc`` attribute.\* Because the methods
 have the same API, we can call them in the same way. ModelChain includes
 a large number of methods that perform the same API-unification roles
@@ -489,7 +489,7 @@ Temperature data are passed in the ``weather`` DataFrame and can include:
   method is used to calculate cell temperature. If ``ModelChain.temperature_model``
   is set to any other model, ``'module_temperature'`` is ignored.
 * ambient air temperature (``'temp_air'``). In this case ``ModelChain.temperature_model``
-  is used to calculate cell temeprature.
+  is used to calculate cell temperature.
 
 Cell temperature models also can use irradiance as input. All cell
 temperature models expect POA irradiance (``'poa_global'``) as  input. When

{pvlib-0.12.0/docs/sphinx/source/user_guide → pvlib-0.13.0/docs/sphinx/source/user_guide/modeling_topics}/pvsystem.rst

@@ -75,7 +75,7 @@ data irradiance and temperature.
 
 .. ipython:: python
 
-    pdc = system.pvwatts_dc(g_poa_effective=1000, temp_cell=30)
+    pdc = system.pvwatts_dc(effective_irradiance=1000, temp_cell=30)
     print(pdc)
 
 Methods attached to a PVSystem object wrap the corresponding functions in
@@ -84,8 +84,8 @@ using data stored in the PVSystem attributes. Compare the
 :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc` method signature to the
 :py:func:`~pvlib.pvsystem.pvwatts_dc` function signature:
 
-    * :py:meth:`PVSystem.pvwatts_dc(g_poa_effective, temp_cell) <pvlib.pvsystem.PVSystem.pvwatts_dc>`
-    * :py:func:`pvwatts_dc(g_poa_effective, temp_cell, pdc0, gamma_pdc, temp_ref=25.) <pvlib.pvsystem.pvwatts_dc>`
+    * :py:meth:`PVSystem.pvwatts_dc(effective_irradiance, temp_cell) <pvlib.pvsystem.PVSystem.pvwatts_dc>`
+    * :py:func:`pvwatts_dc(effective_irradiance, temp_cell, pdc0, gamma_pdc, temp_ref=25.) <pvlib.pvsystem.pvwatts_dc>`
 
 How does this work? The :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc`
 method looks in `PVSystem.module_parameters` for the `pdc0`, and
@@ -240,7 +240,7 @@ operates in a similar manner.
 
 
 The `PVSystem` method :py:meth:`~pvlib.pvsystem.PVSystem.get_aoi`
-operates on all `Array` instances in the `PVSystem`, whereas the the
+operates on all `Array` instances in the `PVSystem`, whereas the
 `Array` method operates only on its `Array` instance.
 
 .. ipython:: python

{pvlib-0.12.0/docs/sphinx/source/user_guide → pvlib-0.13.0/docs/sphinx/source/user_guide/modeling_topics}/weather_data.rst

@@ -35,7 +35,7 @@ them.
    source of weather information. However, the coverage depends on
    a weather station having been set up in advance for the location and
    times of interest. Some ground station networks like the BSRN and SURFRAD
-   make their measurement data publicly available. An global overview of ground
+   make their measurement data publicly available. A global overview of ground
    stations is available at https://SolarStations.org.
    
    Data from public ground station measurement networks are useful if you
@@ -50,7 +50,7 @@ them.
    weather station. They have high spatial and temporal resolution
    corresponding to the source satellite imagery, and are generally
    optimised to estimate solar irradiance for PV applications. Free sources
-   such as PVGIS, NSRDB, and CAMS are available, and commerical sources such
+   such as PVGIS, NSRDB, and CAMS are available, and commercial sources such
    as SolarAnywhere, Solcast, and Solargis provide paid options though often
    have free trials.
    
@@ -76,7 +76,7 @@ them.
 Usage
 -----
 
-With some exceptions, the :py:mod:`pvlib.iotools` functions
+The :py:mod:`pvlib.iotools` functions
 provide a uniform interface for accessing data across many formats.
 Specifically, :py:mod:`pvlib.iotools` functions usually return two objects:
 a :py:class:`pandas.DataFrame` of the actual dataset, plus a metadata
@@ -89,8 +89,7 @@ Typical usage looks something like this:
 
 .. code-block:: python
 
-    # get_pvgis_tmy returns two additional values besides df and metadata
-    df, _, _, metadata = pvlib.iotools.get_pvgis_tmy(latitude, longitude, map_variables=True)
+    df, metadata = pvlib.iotools.get_pvgis_tmy(latitude, longitude, map_variables=True)
 
 This code will fetch a Typical Meteorological Year (TMY) dataset from PVGIS,
 returning a :py:class:`pandas.DataFrame` containing the hourly weather data