Usage Example, Python Frontend, documentation updates (#17)

CONTRIBUTING.md

@@ -4,12 +4,12 @@ Thanks for considering making a contribution to pyRTE-RRTMGP!
 
 ## How to Report a Bug?
 
-Please file a bug report on the [Github page](https://github.com/earth-system-radiation/pyRTE-RRTMGP/issues/new/choose).
+Please file a bug report on the [GitHub page](https://github.com/earth-system-radiation/pyRTE-RRTMGP/issues/new/choose).
 If possible, your issue should include a [minimal, complete, and verifiable example](https://stackoverflow.com/help/mcve) of the bug.
 
 ## How to Propose a New Feature?
 
-Please file a feature request on the [Github page](https://github.com/earth-system-radiation/pyRTE-RRTMGP/issues/new/choose).
+Please file a feature request on the [GitHub page](https://github.com/earth-system-radiation/pyRTE-RRTMGP/issues/new/choose).
 
 ## How to Set up a Local Development Environment?
 
@@ -51,13 +51,13 @@ pytest tests
 ## How to Contribute a Patch That Fixes a Bug?
 
 Please fork this repository, branch from `main`, make your changes, and open a
-Github [pull request](https://github.com/earth-system-radiation/pyRTE-RRTMTP/pulls)
+GitHub [pull request](https://github.com/earth-system-radiation/pyRTE-RRTMTP/pulls)
 against the `main` branch.
 
 ## How to Contribute New Features?
 
 Please fork this repository, branch from `main`, make your changes, and open a
-Github [pull request](https://github.com/earth-system-radiation/pyRTE-RRTMTP/pulls)
+GitHub [pull request](https://github.com/earth-system-radiation/pyRTE-RRTMTP/pulls)
 against the `main` branch.
 
 Pull Requests for new features should include tests and documentation.

README.md

@@ -105,7 +105,7 @@ Currently, the following functions are available in the `pyrte_rrtmgp` package:
 
 ### Prerequisites
 
-pyRTE-RRTMGP is currently only tested on x86_64 architecture with Linux (and, to some extend, macOS on Intel processors).
+pyRTE-RRTMGP is currently only tested on x86_64 architecture with Linux (and, to some extent, macOS on Intel processors).
 
 The package source code is hosted [on GitHub](https://github.com/earth-system-radiation/pyRTE-RRTMGP) and uses git submodules to include the [RTE+RRTMGP Fortran software](https://earth-system-radiation.github.io/rte-rrtmgp/). The easiest way to install pyRTE-RRTMGP is to use `git`. You can install git from [here](https://git-scm.com/downloads).
 

conda.recipe/meta.yaml

@@ -38,13 +38,17 @@ requirements:
   run:
     - python
     - numpy >=1.21.0
+    - xarray >=2023.5.0
+    - netcdf4 >=1.5.7
 
 test:
   imports:
     - pyrte_rrtmgp
   requires:
     - numpy>=1.21
     - pytest>=7.4
+    - xarray >=2023.5.0
+    - netcdf4 >=1.5.7
   source_files:
     - tests
   commands:

docs/source/conf.py

@@ -4,29 +4,59 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import datetime as dt
+import os
+import sys
+import tomllib
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+
+def get_version_from_toml():
+    if os.path.isfile("../../pyproject.toml"):
+        # read pyproject.toml
+        with open("../../pyproject.toml", "rb") as f:
+            pyproject = tomllib.load(f)
+        # get version from pyproject.toml
+        version = pyproject.get("project", {}).get("version", {})
+    else:
+        version = None
+    return version if version else "dev"
+
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "pyRTE-RRTMGP"
 copyright = f"{dt.datetime.now().year}, Atmospheric and Environmental Research"
 author = "Atmospheric and Environmental Research"
-release = "0.1"
+version = get_version_from_toml()
+release = version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "myst_parser",
     "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = []
 
+autodoc_mock_imports = [
+    "pyrte_rrtmgp.pyrte_rrtmgp",
+    "numpy",
+    "xarray",
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+
+html_theme_options = {
+    "display_version": True,
+}

docs/source/contributor_guide/roadmap.md

@@ -11,6 +11,6 @@ It fits into the broader scientific Python ecosystem and is designed to be intui
 - Documentation for all functions, multiple usage examples
 - Comprehensive test suite
 - Continuous integration and deployment
-- Support for Windows, macOS ARM and other platforms
+- Support for Windows, macOS ARM, and other platforms
 - Package installable via PyPI
 - Support for vertical (GPU) and horizontal (parallelization, e.g. with Dask) scaling

docs/source/index.rst

@@ -9,9 +9,9 @@ Welcome to pyRTE-RRTMGP's documentation!
 pyRTE-RRTMGP provides a **Python interface** to the
 `RTE+RRTMGP <https://earth-system-radiation.github.io/rte-rrtmgp/>`_ Fortran software package.
 
-This package uses [pybind11](https://github.com/pybind/pybind11) to create a Python interface to a subset of the RTE+RRTMGP functions available in Fortran.
+This package uses `pybind11 <https://github.com/pybind/pybind11>`_ to create a Python interface to a subset of the RTE+RRTMGP functions available in Fortran.
 
-The RTE+RRTMGP package is a set of libraries for for computing radiative fluxes
+The RTE+RRTMGP package is a set of libraries for computing radiative fluxes
 in planetary atmospheres. RTE+RRTMGP is described in a
 `paper <https://doi.org/10.1029/2019MS001621>`_ in
 `Journal of Advances in Modeling Earth Systems <http://james.agu.org/>`_.
@@ -26,6 +26,8 @@ in planetary atmospheres. RTE+RRTMGP is described in a
 
    user_guide/installation
    user_guide/usage
+   reference_guide/pyrte_rrtmgp_low_level
+   reference_guide/pyrte_rrtmgp_python_modules
 
 .. toctree::
    :maxdepth: 2

docs/source/reference_guide/pyrte_rrtmgp_low_level.md

@@ -0,0 +1,20 @@
+(low_level_interface)=
+# Low-Level Interface
+
+The `pyrte_rrtmgp.pyrte_rrtmgp` module provides a low-level interface to the RTE-RRTMGP and RRTMGP functions. It is generated by pybind11 from C headers of RTE-RRTMGP.
+
+See the [RTE-RRTMGP repository on GitHub](https://github.com/earth-system-radiation/pyRTE-RRTMGP) and the [RTE-RRTMGP documentation](https://earth-system-radiation.github.io/rte-rrtmgp/) for more information about these functions.
+
+The following RTE functions from [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP) are currently available in the `pyrte_rrtmgp.pyrte_rrtmgp` module:
+
+```{include} ../../../README.md
+:start-after: <!-- start-rte-functions-section -->
+:end-before: <!-- end-rte-functions-section -->
+```
+
+The following RRTMGP functions from [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP) are currently available in the `pyrte_rrtmgp.pyrte_rrtmgp` module:
+
+```{include} ../../../README.md
+:start-after: <!-- start-rrtmgp-functions-section -->
+:end-before: <!-- end-rrtmgp-functions-section -->
+```

docs/source/reference_guide/pyrte_rrtmgp_python_modules.rst

@@ -0,0 +1,33 @@
+.. _module_ref:
+
+Python Modules
+==============
+
+The documentation below provides details for several of the high-level functions wrapping the underlying Fortran code.
+
+For more information about the low-level functions available in the ``pyrte_rrtmgp.pyrte_rrtmgp`` submodule, please go to :ref:`low_level_interface`.
+
+
+pyrte\_rrtmgp.rte module
+------------------------
+
+.. automodule:: pyrte_rrtmgp.rte
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pyrte\_rrtmgp.rrtmgp module
+---------------------------
+
+.. automodule:: pyrte_rrtmgp.rrtmgp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pyrte\_rrtmgp.utils module
+--------------------------
+
+.. automodule:: pyrte_rrtmgp.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/user_guide/usage.md

@@ -2,17 +2,27 @@
 
 This section provides a brief overview of how to use `pyrte_rrtmgp` with Python.
 
-## Importing the Package
+## Python Package Structure
 
-To use any of the RTE-RRTMGP functions in Python, you must first import the `pyrte_rrtmgp` package:
+The `pyrte_rrtmgp` package contains the following submodules:
 
-```python
-import pyrte_rrtmgp.pyrte_rrtmgp
+- `pyrte_rrtmgp.pyrte_rrtmgp`: The main module that provides access to a subset of RTE-RRTMGP's Fortran functions in Python. The functions available in this module mirror the Fortran functions (see below). You can think of this as the low-level implementation that allows you to access the respective Fortran functions directly in Python. See [](low_level_interface) for more information.
+- `pyrte_rrtmgp.rte`: A high-level module that provides a more user-friendly Python interface for select RTE functions. This module is still under development and will be expanded in future releases. See [](module_ref) for details.
+- `pyrte_rrtmgp.rrtmgp`: A high-level module that provides a more user-friendly Python interface for select RRTMGP functions. This module is still under development and will be expanded in future releases. See [](module_ref) for details.
+- `pyrte_rrtmgp.utils`: A module that provides utility functions for working with RTE-RRTMGP data. This module is still under development and will be expanded in future releases. See [](module_ref) for details.
+
+```{seealso}
+The folder `examples` in the repository contains a Jupyter notebook example that demonstrates how to use the package.
+
+The functions in `pyrte_rrtmgp.rte`, `pyrte_rrtmgp.rrtmgp`, and `pyrte_rrtmgp.utils` contain docstrings that are available in IDEs with features such as IntelliSense (in VSCode).
 ```
 
-This gives you access to [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP)'s Fortran functions directly in Python.
+## Importing the Package
+
+To use any of the RTE-RRTMGP functions in Python, you first need to import `pyrte_rrtmgp` and the respective submodule you want to use.
+For example: ``import pyrte_rrtmgp.pyrte_rrtmgp`` or ``import pyrte_rrtmgp.rrtmgp as rrtmgp``.
 
-For example:
+The example below uses the `pyrte_rrtmgp.pyrte_rrtmgp` submodule, which gives you low-level access to [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP)'s Fortran functions in Python:
 
 ```python
 import pyrte_rrtmgp.pyrte_rrtmgp as py
@@ -21,25 +31,3 @@ args = list_of_arguments
 
 py.rte_lw_solver_noscat(*args)
 ```
-
-## RTE Functions
-
-The following RTE functions from [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP) are currently available in the `pyrte_rrtmgp` package:
-
-```{include} ../../../README.md
-:start-after: <!-- start-rte-functions-section -->
-:end-before: <!-- end-rte-functions-section -->
-```
-
-## RRTMGP Functions
-
-The following RRTMGP functions from [RTE-RRTMGP](https://github.com/earth-system-radiation/pyRTE-RRTMGP) are currently available in the `pyrte_rrtmgp` package:
-
-```{include} ../../../README.md
-:start-after: <!-- start-rrtmgp-functions-section -->
-:end-before: <!-- end-rrtmgp-functions-section -->
-```
-
-```{seealso}
-See the [RTE-RRTMGP repository on GitHub](https://github.com/earth-system-radiation/pyRTE-RRTMGP) and the [RTE-RRTMGP documentation](https://earth-system-radiation.github.io/rte-rrtmgp/) for more information about these functions.
-```

examples/lw_noscat.ipynb

@@ -0,0 +1,80 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyrte_rrtmgp.gas_optics import GasOptics\n",
+    "import xarray as xr\n",
+    "import numpy as np\n",
+    "from pyrte_rrtmgp.rte import lw_solver_noscat\n",
+    "\n",
+    "ERROR_TOLERANCE = 1e-4\n",
+    "\n",
+    "rte_rrtmgp_dir = \"../rrtmgp-data\"\n",
+    "clear_sky_example_files = f\"{rte_rrtmgp_dir}/examples/rfmip-clear-sky/inputs\"\n",
+    "\n",
+    "rfmip = xr.load_dataset(\n",
+    "    f\"../tests/test_python_frontend/multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-1-2_none.nc\"\n",
+    ")\n",
+    "rfmip = rfmip.sel(expt=0)  # only one experiment\n",
+    "\n",
+    "kdist = xr.load_dataset(f\"../tests/test_python_frontend/rrtmgp-gas-lw-g256.nc\")\n",
+    "\n",
+    "# RRTMGP won't run with pressure less than its minimum. so we add a small value to the minimum pressure\n",
+    "# There was an issue replicating k_dist%get_press_min() + epsilon(k_dist%get_press_min()) in python, sys.epsilon is not the same\n",
+    "min_index = rfmip[\"pres_level\"].argmin()\n",
+    "rfmip[\"pres_level\"][:, min_index] = 1.0051835744630002\n",
+    "\n",
+    "gas_optics = GasOptics(kdist, rfmip)\n",
+    "gas_optics.source_is_internal\n",
+    "tau, layer_src, level_src, sfc_src, sfc_src_jac = gas_optics.gas_optics()\n",
+    "\n",
+    "# Expand the surface emissivity to ngpt\n",
+    "sfc_emis = rfmip[\"surface_emissivity\"].values\n",
+    "sfc_emis = np.stack([sfc_emis]*tau.shape[2]).T\n",
+    "\n",
+    "_, solver_flux_up, solver_flux_down, _, _ = lw_solver_noscat(\n",
+    "    tau=tau,\n",
+    "    lay_source=layer_src,\n",
+    "    lev_source=level_src,\n",
+    "    sfc_emis=sfc_emis,\n",
+    "    sfc_src=sfc_src,\n",
+    "    sfc_src_jac=sfc_src_jac\n",
+    ")\n",
+    "\n",
+    "rlu = xr.load_dataset(\"../tests/test_python_frontend/rlu_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc\")\n",
+    "ref_flux_up = rlu.isel(expt=0)[\"rlu\"].values\n",
+    "\n",
+    "rld = xr.load_dataset(\"../tests/test_python_frontend/rld_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc\")\n",
+    "ref_flux_down = rld.isel(expt=0)[\"rld\"].values\n",
+    "\n",
+    "assert np.isclose(solver_flux_up, ref_flux_up, atol=ERROR_TOLERANCE).all()\n",
+    "assert np.isclose(solver_flux_down, ref_flux_down, atol=ERROR_TOLERANCE).all()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}