Merge branch 'main' into rajeeja/zonal-mean-analytic-band

Author: rajeeja

docs/_static/examples/gradient/fig.svg

@@ -0,0 +1,230 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c51bdab8875e6859",
+   "metadata": {},
+   "source": [
+    "## Gradients\n",
+    "\n",
+    "This user-guide notebook showcases how to compute the gradient of a data variable."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "initial_id",
+   "metadata": {},
+   "source": [
+    "import holoviews as hv\n",
+    "import numpy as np\n",
+    "\n",
+    "import uxarray as ux\n",
+    "\n",
+    "hv.extension(\"bokeh\")"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ac4c02fb09053a2d",
+   "metadata": {},
+   "source": [
+    "## Data\n",
+    "\n",
+    "This notebook uses a subset of a 30km MPAS stmopshere grid, taken centered at 45 degrees longitiude and 0 degrees latitude with a radius of 2 degrees. \n",
+    "- `face_lon`: Longitude at cell-centers\n",
+    "- `face_lat`: Latitude at cell-centers\n",
+    "- `gaussian`: Gaussian initialized at the center of the grid\n",
+    "- `inverse_gaussian`: Inverse of the gaussian above. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "51f3db3a8821295c",
+   "metadata": {},
+   "source": [
+    "base_path = \"../../test/meshfiles/mpas/dyamond-30km/\"\n",
+    "grid_path = base_path + \"gradient_grid_subset.nc\"\n",
+    "data_path = base_path + \"gradient_data_subset.nc\"\n",
+    "uxds = ux.open_dataset(grid_path, data_path)\n",
+    "uxds"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5614a18b0a8033ec",
+   "metadata": {},
+   "source": [
+    "## Gradient Computation\n",
+    "\n",
+    "### Background\n",
+    "\n",
+    "Suppose our scalar field values are stored on the faces of a hexagonal grid and we wish to approximate the gradient at the cell center \\$C^\\*\\$. We leverage the **Green–Gauss theorem**:\n",
+    "\n",
+    "$$\n",
+    "\\int_V \\nabla\\phi \\, dV = \\oint_{\\partial V} \\phi \\, dS\n",
+    "$$\n",
+    "\n",
+    "To apply this:\n",
+    "\n",
+    "1. Construct a closed control volume around \\$C^\\*\\$ by connecting the centroids of its neighboring cells.\n",
+    "2. Approximate the surface integral on each face using a midpoint (or trapezoidal) rule.\n",
+    "3. Sum the contributions and normalize by the cell volume.\n",
+    "\n",
+    "While the schematic below is drawn on a “flat” hexagon, in practice our grid resides on the sphere, so all lengths \\$l\\_{ij}\\$ and normals \\$\\mathbf{n}\\_{ij}\\$ are computed on the curved surface.\n",
+    "\n",
+    "\n",
+    "### Implementation\n",
+    "\n",
+    "In a finite-volume context, the gradient of a scalar field \\$\\phi\\$ is obtained by summing fluxes across each cell face and dividing by the cell’s volume.\n",
+    "\n",
+    "| **Input**             |    **Usage**   | **Output**                  |\n",
+    "| --------------------- | :------------: | --------------------------- |\n",
+    "| Scalar field \\$\\phi\\$ | `φ.gradient()` | Vector field \\$\\nabla\\phi\\$ |\n",
+    "\n",
+    "#### Finite-volume discretization\n",
+    "\n",
+    "$$\n",
+    "\\int_V \\nabla\\phi \\, dV = \\oint_{\\partial V} \\phi \\, dS\n",
+    "$$\n",
+    "\n",
+    "#### Discrete gradient at cell center \\$C^\\*\\$\n",
+    "\n",
+    "$$\n",
+    "\\nabla\\phi(C^*)\n",
+    "\\;\\approx\\;\n",
+    "\\frac{1}{\\mathrm{Vol}(C^*)}\n",
+    "\\sum_{f\\in\\partial C^*}\n",
+    "\\left(\n",
+    "  \\frac{\\phi(C_i) + \\phi(C_j)}{2}\n",
+    "\\right)\n",
+    "\\;l_{ij}\\;\\mathbf{n}_{ij}\n",
+    "$$\n",
+    "\n",
+    "<div style=\"text-align: center;\">\n",
+    "  <img src=\"../_static/examples/gradient/fig.svg\" alt=\"Gradient schematic\" width=\"300\"/>\n",
+    "</div>\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "57434fa8-bc70-47aa-a40c-420fadb8c9fa",
+   "metadata": {},
+   "source": [
+    "## Usage\n",
+    "\n",
+    "Gradients can be computed using the `UxDataArray.gradient()` method on a face-centered data variable. \n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "584726e9-6d27-45f1-a39a-6d07c2b9ca06",
+   "metadata": {},
+   "source": [
+    "grad_lat = uxds[\"face_lat\"].gradient()\n",
+    "grad_lon = uxds[\"face_lon\"].gradient()\n",
+    "grad_gauss = uxds[\"gaussian\"].gradient()\n",
+    "grad_inv_gauss = uxds[\"inverse_gaussian\"].gradient()"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "98448402-76ed-492f-8ddd-5b6e25db8e8d",
+   "metadata": {},
+   "source": [
+    "Examining one of the outputs, we find that the `zonal_gradient` and `meridional_gradient` data variables store the rate of change along longitude (east–west) and latitude (north–south), respectively."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7c38c68e-18e5-4b3a-b4e2-eb3806c3427a",
+   "metadata": {},
+   "source": [
+    "## Plotting\n",
+    "\n",
+    "To visualuze the gradients, we can represent them as a `hv.VectorField` and overlay the vectors on top of the original data variable. Below is a utility function that can be used."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "1b5e1fa5-a455-4fb6-b637-38ab3b948e13",
+   "metadata": {},
+   "source": [
+    "def plot_gradient_vectors(uxda_grad, **kwargs):\n",
+    "    \"\"\"\n",
+    "    Plots gradient vectors using HoloViews\n",
+    "    \"\"\"\n",
+    "    uxgrid = uxda_grad.uxgrid\n",
+    "    mag = np.hypot(uxda_grad.zonal_gradient, uxda_grad.meridional_gradient)\n",
+    "    angle = np.arctan2(uxda_grad.meridional_gradient, uxda_grad.zonal_gradient)\n",
+    "\n",
+    "    return hv.VectorField(\n",
+    "        (uxgrid.face_lon, uxgrid.face_lat, angle, mag), **kwargs\n",
+    "    ).opts(magnitude=\"Magnitude\")"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "7a8ae073-3dd7-48dd-b152-58fa5265d775",
+   "metadata": {},
+   "source": [
+    "# Overlay the gradient vector field on top of the original data variable\n",
+    "p1 = (\n",
+    "    uxds[\"face_lat\"].plot(cmap=\"Oranges\", aspect=1) * plot_gradient_vectors(grad_lat)\n",
+    ").opts(title=\"∇ Cell Latitudes\")\n",
+    "p2 = (\n",
+    "    uxds[\"face_lon\"].plot(cmap=\"Oranges\", aspect=1) * plot_gradient_vectors(grad_lon)\n",
+    ").opts(title=\"∇ Cell Longitudes\")\n",
+    "p3 = (\n",
+    "    uxds[\"gaussian\"].plot(cmap=\"Oranges\", aspect=1) * plot_gradient_vectors(grad_gauss)\n",
+    ").opts(title=\"∇ Gaussian\")\n",
+    "p4 = (\n",
+    "    uxds[\"inverse_gaussian\"].plot(cmap=\"Oranges\", aspect=1)\n",
+    "    * plot_gradient_vectors(grad_inv_gauss)\n",
+    ").opts(title=\"∇ Inverse Gaussian\")\n",
+    "\n",
+    "# Compose all four plots in a 2 column layout\n",
+    "(p1 + p2 + p3 + p4).cols(2).opts(shared_axes=False)"
+   ],
+   "outputs": [],
+   "execution_count": null
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user-guide/calculus.ipynb

@@ -67,8 +67,8 @@ These user guides provide detailed explanations of the core functionality in UXa
 `Weighted Mean <user-guide/weighted_mean.ipynb>`_
  Compute the weighted average
 
-`Calculus Operators <user-guide/calculus.ipynb>`_
- Apply calculus operators (gradient, integral) on unstructured grid data
+`Gradients <user-guide/gradients.ipynb>`_
+ Compute the gradient of a data variable
 
 `Tree Structures <user-guide/tree_structures.ipynb>`_
  Data structures for nearest neighbor queries
@@ -117,7 +117,7 @@ These user guides provide additional details about specific features in UXarray.
    user-guide/remapping.ipynb
    user-guide/topological-aggregations.ipynb
    user-guide/weighted_mean.ipynb
-   user-guide/calculus.ipynb
+   user-guide/gradients.ipynb
    user-guide/tree_structures.ipynb
    user-guide/area_calc.ipynb
    user-guide/dual-mesh.ipynb