docs: how to accelerate awkward arrays with cppyy

.github/workflows/docs.yml

@@ -13,7 +13,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  X86_64_PYTHON_VERSION: "3.10.6"
+  X86_64_PYTHON_VERSION: "3.11.0"
   SOURCE_DATE_EPOCH: "1668811211"
 
 jobs:
@@ -67,7 +67,6 @@ jobs:
       with:
         submodules: true
 
-
     - name: Setup Python
       uses: actions/setup-python@v4
       with:
@@ -193,9 +192,56 @@ jobs:
         name: awkward
         path: dist/awkward*.whl
 
+  execute-cppyy:
+    needs: [awkward-cpp-x86-64, awkward]
+    runs-on: ubuntu-22.04
+    name: Execute cppyy notebook
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "${{ env.X86_64_PYTHON_VERSION }}"
+
+    - name: Extract pre-built manylinux cppyy wheels
+      uses: shrink/actions-docker-extract@v3
+      with:
+        image: "docker.io/agoose77/cppyy-wheels:cp311"
+        path: "/wheels/."
+        destination: "/tmp/wheels/"
+
+    - name: Download awkward wheel
+      uses: actions/download-artifact@v3
+      with:
+        name: awkward
+        path: /tmp/wheels/
+
+    - name: Download awkward-cpp x86_64 wheel
+      uses: actions/download-artifact@v3
+      with:
+        name: awkward-cpp-x86-64
+        path: /tmp/wheels/
+
+    - name: Install dependencies
+      working-directory: docs
+      run: python -m pip install /tmp/wheels/*.whl -r requirements.txt
+
+    - name: Execute cppyy notebook
+      working-directory: docs
+      run: jupyter nbconvert --to notebook --execute --inplace user-guide/how-to-use-in-cpp-cppyy.ipynb
+
+    - name: Save executed notebook
+      uses: actions/upload-artifact@v3
+      with:
+        name: how-to-use-in-cpp-cppyy
+        path: docs/user-guide/how-to-use-in-cpp-cppyy.ipynb
+
   build-docs:
     runs-on: ubuntu-22.04
-    needs: [awkward-cpp-wasm, awkward-cpp-x86-64, awkward]
+    needs: [awkward-cpp-wasm, awkward-cpp-x86-64, awkward, execute-cppyy]
     name: Build Docs
     defaults:
       run:
@@ -275,6 +321,12 @@ jobs:
       run: |
         echo "DOCS_VERSION=main" >> $GITHUB_ENV
 
+    - name: Download cppyy notebook
+      uses: actions/download-artifact@v3
+      with:
+        name: how-to-use-in-cpp-cppyy
+        path: docs/user-guide
+
     - name: Generate Python documentation
       run: sphinx-build -M html . _build/ -T
       working-directory: docs

.github/workflows/test.yml

@@ -267,11 +267,6 @@ jobs:
         if: matrix.python-version == '3.9'
 
   Linux-ROOT-dask-awkward:
-    strategy:
-      matrix:
-        python-version:
-          - '3.8'
-
     runs-on: ubuntu-20.04
 
     env:
@@ -296,7 +291,7 @@ jobs:
           cache-environment: true
           environment-name: awkward
           create-args: >-
-            python=${{ env.PYTHON_VERSION }}
+            python=3.8
             numpy
             root
 
@@ -308,7 +303,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ./awkward-cpp/dist
-          key: ${{ github.job }}-${{ matrix.python-version }}-${{ hashFiles('awkward-cpp/**') }}
+          key: ${{ github.job }}-${{ hashFiles('awkward-cpp/**') }}
 
       - name: Build awkward-cpp wheel
         if: steps.cache-awkward-cpp-wheel.outputs.cache-hit != 'true'
@@ -329,3 +324,57 @@ jobs:
 
       - name: Test
         run: python -m pytest -vv -rs tests
+
+  Linux-cppyy:
+    # TODO: remove this part of the workflow
+    # cppyy is not yet released. Let's load some pre-built wheels via docker (as a binary store)
+    runs-on: ubuntu-22.04
+
+    env:
+      PIP_ONLY_BINARY: cmake
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: 'Python ${{ matrix.python-version }}'
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Generate build files
+        run: pipx run nox -s prepare -- --headers --signatures --tests
+
+      - name: Cache awkward-cpp wheel
+        id: cache-awkward-cpp-wheel
+        uses: actions/cache@v3
+        with:
+          path: ./awkward-cpp/dist
+          key: ${{ github.job }}-${{ hashFiles('awkward-cpp/**') }}
+
+      - name: Build awkward-cpp wheel
+        if: steps.cache-awkward-cpp-wheel.outputs.cache-hit != 'true'
+        run: |
+          python -m pip install build
+          python -m build -w ./awkward-cpp
+
+      - name: Extract pre-built manylinux cppyy wheels
+        uses: shrink/actions-docker-extract@v3
+        with:
+          image: "docker.io/agoose77/cppyy-wheels:cp311"
+          path: "/wheels/."
+          destination: "/tmp/cppyy-wheels"
+
+      - name: Install awkward, awkward-cpp, and dependencies
+        run: >-
+          python -m pip install --only-binary "numpy,pandas,pyarrow,numexpr"
+          -v . ./awkward-cpp/dist/*.whl
+          pytest-github-actions-annotate-failures
+          /tmp/cppyy-wheels/*
+
+      - name: Print versions
+        run: python -m pip list
+
+      - name: Test
+        run: python -m pytest -vv -rs tests -k cppyy

docs/_toc.yml

@@ -153,6 +153,15 @@ subtrees:
                       - file: user-guide/how-to-use-in-numba-cuda
                         title: "Working with CUDA"
 
+              - file: user-guide/how-to-use-in-cpp
+                title: "Using arrays in C++"
+                subtrees:
+                  - entries:
+                      - file: user-guide/how-to-use-header-only-layoutbuilder
+                        title: "Building Awkward Arrays in C++ with LayoutBuilder"
+                      - file: user-guide/how-to-use-in-cpp-cppyy
+                        title: "JIT compiling operations with C++ in cppyy"
+
               - file: user-guide/how-to-specialize
                 title: "Specialized behavior"
                 subtrees:
@@ -167,7 +176,5 @@ subtrees:
                         title: "For physics: Lorentz vectors [todo]"
                       - file: user-guide/how-to-specialize-differentiate-jax
                         title: "Differentiation using JAX"
-                      - file: user-guide/how-to-use-header-only-layoutbuilder
-                        title: "Building Awkward Arrays in C++"
 
       - file: reference/index

docs/conf.py

@@ -161,7 +161,9 @@
 if not run_cuda_notebooks:
     nb_execution_excludepatterns = [
         # We have no CUDA executors, so disable this
-        "user-guide/how-to-use-in-numba-cuda.ipynb"
+        "user-guide/how-to-use-in-numba-cuda.ipynb",
+        # We have no cppyy 3.0.1 yet, so disable this
+        "user-guide/how-to-use-in-cpp-cppyy.ipynb",
     ]
 
 # Additional stuff

docs/requirements-wasm.txt

@@ -1,2 +1,2 @@
 pyodide-build==0.23.3
-pydantic<2
+pydantic<2

docs/requirements.txt

@@ -1,5 +1,5 @@
 # JupyterLite (kernel requires specific pyodide version)
-jupyterlite-pyodide-kernel==0.0.8
+jupyterlite-pyodide-kernel==0.1.0
 jupyterlite[piplite]==0.1.0
 jupyterlite-sphinx==0.8.0