YAC as an optional remapping backend for uxarray

.github/workflows/ci.yml

@@ -11,6 +11,8 @@ jobs:
     #   github.repository == 'UXARRAY/uxarray'
     name: Python (${{ matrix.python-version }}, ${{ matrix.os }})
     runs-on: ${{ matrix.os }}
+    env:
+      MPLBACKEND: Agg
     defaults:
       run:
         shell: bash -l {0}

.github/workflows/yac-optional.yml

@@ -0,0 +1,142 @@
+name: YAC Optional CI
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/yac-optional.yml"
+      - "uxarray/remap/**"
+      - "test/test_remap_yac.py"
+  workflow_dispatch:
+
+jobs:
+  yac-optional:
+    name: YAC core v3.14.0_p1 (Ubuntu)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    env:
+      YAC_VERSION: v3.14.0_p1
+      YAXT_VERSION: v0.11.5.1
+      MPIEXEC: /usr/bin/mpirun
+      MPIRUN: /usr/bin/mpirun
+      MPICC: /usr/bin/mpicc
+      MPIFC: /usr/bin/mpif90
+      MPIF90: /usr/bin/mpif90
+      OMPI_ALLOW_RUN_AS_ROOT: 1
+      OMPI_ALLOW_RUN_AS_ROOT_CONFIRM: 1
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ github.token }}
+
+      - name: conda_setup
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: uxarray_build
+          channel-priority: strict
+          python-version: "3.11"
+          channels: conda-forge
+          environment-file: ci/environment.yml
+          miniforge-variant: Miniforge3
+          miniforge-version: latest
+
+      - name: Install build dependencies (apt)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            autoconf \
+            automake \
+            gawk \
+            gfortran \
+            libopenmpi-dev \
+            libtool \
+            make \
+            openmpi-bin \
+            pkg-config
+      - name: Verify MPI tools
+        run: |
+          which mpirun
+          which mpicc
+          which mpif90
+          mpirun --version
+          mpicc --version
+          mpif90 --version
+      - name: Install Python build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install cython wheel
+      - name: Build and install YAXT
+        run: |
+          set -euxo pipefail
+          YAC_PREFIX="${GITHUB_WORKSPACE}/yac_prefix"
+          echo "YAC_PREFIX=${YAC_PREFIX}" >> "${GITHUB_ENV}"
+          git clone --depth 1 --branch "${YAXT_VERSION}" https://gitlab.dkrz.de/dkrz-sw/yaxt.git
+          if [ ! -x yaxt/configure ]; then
+            if [ -x yaxt/autogen.sh ]; then
+              (cd yaxt && ./autogen.sh)
+            else
+              (cd yaxt && autoreconf -i)
+            fi
+          fi
+          mkdir -p yaxt/build
+          cd yaxt/build
+          ../configure \
+            --prefix="${YAC_PREFIX}" \
+            --without-regard-for-quality \
+            CC="${MPICC}" \
+            FC="${MPIF90}"
+          make -j2
+          make install
+      - name: Build and install YAC
+        run: |
+          set -euxo pipefail
+          git clone --depth 1 --branch "${YAC_VERSION}" https://gitlab.dkrz.de/dkrz-sw/yac.git
+          if [ ! -x yac/configure ]; then
+            if [ -x yac/autogen.sh ]; then
+              (cd yac && ./autogen.sh)
+            else
+              (cd yac && autoreconf -i)
+            fi
+          fi
+          mkdir -p yac/build
+          cd yac/build
+          ../configure \
+            --prefix="${YAC_PREFIX}" \
+            --with-yaxt-root="${YAC_PREFIX}" \
+            --disable-mci \
+            --disable-utils \
+            --disable-examples \
+            --disable-tools \
+            --disable-netcdf \
+            --enable-python-bindings \
+            CC="${MPICC}" \
+            FC="${MPIF90}"
+          make -j2
+          make install
+      - name: Configure YAC runtime paths
+        run: |
+          set -euxo pipefail
+          PY_VER="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+          echo "LD_LIBRARY_PATH=${YAC_PREFIX}/lib:${LD_LIBRARY_PATH:-}" >> "${GITHUB_ENV}"
+          echo "PYTHONPATH=${YAC_PREFIX}/lib/python${PY_VER}/site-packages:${YAC_PREFIX}/lib/python${PY_VER}/dist-packages:${PYTHONPATH:-}" >> "${GITHUB_ENV}"
+      - name: Verify YAC core Python bindings
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import sys
+          candidates = []
+          for entry in sys.path:
+              pkg = Path(entry) / "yac"
+              candidates.extend(pkg.glob("core*.so"))
+              candidates.extend(pkg.glob("core*.pyd"))
+          assert candidates, "yac.core extension not found on sys.path"
+          print("Found yac.core extension:", candidates[0])
+          PY
+      - name: Install uxarray
+        run: |
+          python -m pip install . --no-deps
+      - name: Run tests (uxarray with YAC)
+        run: |
+          python -m pytest test/test_remap_yac.py

docs/user-guide/remapping.ipynb

@@ -15,7 +15,11 @@
     "\n",
     "- **Nearest Neighbor**  \n",
     "- **Inverse Distance Weighted**\n",
-    "- **Bilinear**\n"
+    "- **Bilinear**\n",
+    "\n",
+    "UXarray uses its native remapping backend by default. For `.remap(...)`, `.remap.nearest_neighbor(...)`, and `.remap.bilinear(...)`, you can also set `backend=\"yac\"` to route the operation through YAC when `yac.core` is installed.\n",
+    "\n",
+    "When `backend=\"yac\"`, the `yac_method` parameter selects the YAC interpolation method. Supported values are `nnn`, `average`, and `conservative`. `inverse_distance_weighted()` remains UXarray-only, and `bilinear(..., backend=\"yac\")` is a convenience wrapper for `yac_method=\"average\"`.\n"
    ]
   },
   {
@@ -132,6 +136,14 @@
     "- **remap_to**  \n",
     "  The grid element where values should be placed, one of `faces`, `edges`, or `nodes`.\n",
     "\n",
+    "- **backend**  \n",
+    "  The remapping backend to use. The default is `\"uxarray\"`; set `backend=\"yac\"` to route the remap through YAC.\n",
+    "\n",
+    "- **yac_method**  \n",
+    "  Required only when `backend=\"yac\"`. Supported values are `nnn`, `average`, and `conservative`; `nearest_neighbor()` defaults to `nnn`.\n",
+    "\n",
+    "- **yac_options**  \n",
+    "  Optional dictionary of method-specific keyword arguments forwarded to the selected YAC interpolation routine.\n",
     "\n",
     "```{warning}\n",
     "Nearest-neighbor remapping is fast and simple, but it does **not** conserve integrated quantities\n",
@@ -480,7 +492,9 @@
    "id": "6bec26ce-67b6-4300-a310-63cbac2b289a",
    "metadata": {},
    "source": [
-    "Bilinear remapping breaks down the grid into triangles, and then finds the triangle that contains each point on the destinitation grid. It then uses the values stored at each vertex to bilinearly find a value for the point, depending on it's postion inside the triangle."
+    "Bilinear remapping breaks down the grid into triangles, and then finds the triangle that contains each point on the destinitation grid. It then uses the values stored at each vertex to bilinearly find a value for the point, depending on it's postion inside the triangle.\n",
+    "\n",
+    "When `backend=\"yac\"`, `remap.bilinear()` delegates to YAC's `average` method. This is the only YAC method exposed through the bilinear convenience accessor; use `.remap(..., backend=\"yac\", yac_method=...)` if you need to select another YAC method explicitly."
    ]
   },
   {