Data pvlib integration

.github/workflows/pr_test.yml

@@ -46,4 +46,14 @@ jobs:
           pip install pytest
           pip install setuptools
           pip install -e ".[download]"
-          pytest tests/pr/
+          # Set environment variables for debugging
+          export PYTEST_CURRENT_TEST=1
+          export DASK_DISTRIBUTED__DIAGNOSTICS__NVML=False
+          # Run pytest with verbose output and show all logs
+          pytest tests/pr/ \
+            -v \
+            --tb=long \
+            --log-cli-level=DEBUG \
+            --log-cli-format="%(asctime)s [%(levelname)8s] %(name)s: %(message)s" \
+            --capture=no \
+            -s

.gitignore

@@ -138,3 +138,6 @@ scripts/cluster
 
 # PDM
 .pdm-python
+
+# macos specific
+.DS_Store   

.readthedocs.yaml

@@ -4,13 +4,12 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.12"
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+  jobs:
+    # Avoid `pip install .[docs]`, which resolves geopandas, rasterio, dask, pvlib,
+    # etc. and often OOMs on RTD builders. Docs only need Sphinx + the source tree.
+    install:
+      - pip install -r docs/requirements.txt
+      - pip install --no-deps .
 
 sphinx:
   configuration: docs/source/conf.py

README.md

@@ -23,7 +23,7 @@ Installation will also install the following dependencies:
 * `bottleneck`
 * `numexpr`
 * `xarray`
-* `netcdf4`
+* `h5netcdf`
 * `dask`
 * `boto3`
 * `toolz`

docs/requirements.txt

@@ -0,0 +1,8 @@
+# Sphinx stack (matches pyproject [project.optional-dependencies] docs)
+sphinx>=8.0.0
+myst-nb>=1.1.2
+sphinx-book-theme>=1.1.3
+sphinx-autoapi==3.3.2
+
+# Install geodata itself without pulling the full runtime dependency tree
+# (see .readthedocs.yaml: pip install --no-deps .)

docs/source/conf.py

@@ -6,12 +6,21 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-from geodata import __version__
+import re
+from pathlib import Path
+
+# Read version without importing geodata (RTD installs with --no-deps).
+_version_file = Path(__file__).resolve().parents[2] / "src" / "geodata" / "_version.py"
+_release = re.search(
+    r'^__version__\s*=\s*["\']([^"\']+)["\']', _version_file.read_text(), re.M
+)
+if _release is None:
+    raise RuntimeError(f"Could not parse __version__ from {_version_file}")
+release = _release.group(1)
 
 project = "Geodata"
 copyright = "2025, Geodata Contributors"
 author = "Geodata Contributors"
-release = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/datasets/era5.rst

@@ -1,81 +1,89 @@
 ERA5 Specific Instructions
 ==========================
 
-This page explains how you can set up access to ERA5 data from the `Copernicus Data Store <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=overview>`_.
+This page covers **CDS account and API credential setup** for ERA5. Once credentials
+are in place, use the dataset classes — do not call ``cdsapi`` by hand for routine
+downloads.
 
-Creating a CDS account
-----------------------
-
-To download ERA5 data from the CDS, you'll need to create a free `CDS account here <https://cds.climate.copernicus.eu/>`_.
-
-Download data through CDS API
+Recommended download method
 -----------------------------
 
-Once your account has been created, set up access to the API by following these steps:
+The **recommended way** to fetch ERA5 data in Geodata is:
 
-1. Log into your CDS account and visit your `profile page <https://cds.climate.copernicus.eu/profile>`_.
-2. Install the API key. There will be a section called **Personal Access Token**.
-   Copy these two lines into a file called ``.cdsapirc`` in your user root folder.
+1. Complete the CDS setup below (one-time).
+2. Follow :ref:`downloading-era5-data` in :doc:`overview` — ``load_dataset``,
+   instantiate with ``years`` / ``months`` / optional ``bounds``, then ``download()``.
 
-- **macOS/Linux**: Open a terminal and run:
+Geodata's ERA5 classes (for example ``ERA5Wind3DHourlyDataset``) create a
+``cdsapi.Client`` internally and submit the correct product requests for each
+registered ``weather_config``.
 
-  .. code-block:: bash
+Creating a CDS account
+----------------------
 
-      touch ~/.cdsapirc
+To download ERA5 data from the CDS, create a free `CDS account here <https://cds.climate.copernicus.eu/>`_.
 
-  Then add the lines using:
+Configure CDS API credentials
+-----------------------------
 
-  .. code-block:: bash
+Once your account exists, install local API access:
 
-      echo [line 1 of the code] >> ~/.cdsapirc
-      echo [line 2 of the code] >> ~/.cdsapirc
+1. Log into your CDS account and visit your `profile page <https://cds.climate.copernicus.eu/profile>`_.
+2. Under **Personal Access Token**, copy the two lines for your ``.cdsapirc`` file
+   (URL and key).
 
+**macOS/Linux** — create ``~/.cdsapirc``:
 
-  - **Windows**: The process is slightly more complicated. Please refer to the in-depth guide at the Copernicus Knowledge Base `here <https://confluence.ecmwf.int/display/CKB/How+to+install+and+use+CDS+API+on+Windows>`_.
+.. code-block:: bash
 
-3. Install the CDS API client by opening a terminal/shell and running
+   touch ~/.cdsapirc
+   # Paste the two lines from your CDS profile into ~/.cdsapirc
 
-.. code-block:: bash
+**Windows** — see the Copernicus guide on
+`installing the CDS API on Windows <https://confluence.ecmwf.int/display/CKB/How+to+install+and+use+CDS+API+on+Windows>`_.
 
-     pip install ".[download]"
+Ensure ``cdsapi`` is available (it is a dependency of Geodata when you install the
+package). Then proceed to :ref:`downloading-era5-data` in :doc:`overview`.
 
-(Assuming you are in Geodata's *root directory*.)
+Verify CDS API access (optional)
+--------------------------------
 
-1. Once you've installed the API key and the API client, confirm access by running an
-   example in a Python script or a Jupyter notebook:
+You can confirm credentials with a minimal ``cdsapi`` script. This is **optional** —
+Geodata dataset downloads use the same client and credentials.
 
 .. code-block:: python
 
-     import cdsapi
-
-     c = cdsapi.Client()
-
-     c.retrieve(
-          "reanalysis-era5-single-levels",
-          {
-               "product_type": "reanalysis",
-               "format": "netcdf",
-               "variable": [
-                    "2m_dewpoint_temperature",
-                    "2m_temperature",
-               ],
-               "year": "2011",
-               "month": [
-                    "01",
-               ],
-               "day": ["01", "02", "03"],
-               "time": [
-                    "00:00",
-                    "12:00",
-               ],
-          },
-          "download.nc",
-     )
-
-The above example downloads 2m temperature and 2m dewpoint temperature with data points
-at 00:00 and 12:00 for each day, from January 1-3, 2011, in NetCDF format.
-
-If this works, you have successfully set up access to the ERA5 data through the CDS API.
-Please subsequently refer to the `general documentation on datasets <../overview.rst>`_
-for more information on how to download ERA5-based datasets using the ``geodata``
-package.
+   import cdsapi
+
+   c = cdsapi.Client()
+
+   c.retrieve(
+       "reanalysis-era5-single-levels",
+       {
+           "product_type": "reanalysis",
+           "format": "netcdf",
+           "variable": [
+               "2m_dewpoint_temperature",
+               "2m_temperature",
+           ],
+           "year": "2011",
+           "month": ["01"],
+           "day": ["01", "02", "03"],
+           "time": ["00:00", "12:00"],
+       },
+       "download.nc",
+   )
+
+This example fetches 2 m temperature and dewpoint at 00:00 and 12:00 UTC for
+2011-01-01 through 2011-01-03. If it succeeds, your ``.cdsapirc`` is valid.
+
+For production workflows, prefer :ref:`downloading-era5-data` in :doc:`overview` so
+Geodata requests the correct ERA5 products, paths, and post-processing for
+``wind_3d_hourly``, ``wind_solar_hourly``, and other registered configs.
+
+What's next
+-----------
+
+- :ref:`downloading-era5-data` in :doc:`overview` — **recommended** download workflow
+- :doc:`../development/offline-era5-fixture-datasets` — offline ``*_test`` configs for CI
+- :doc:`../modeling/wind/index` or :doc:`../modeling/pvlib/index` — run models on downloaded data