Add Python interfaces based on nanobind

.github/workflows/check-litgen.yml

@@ -0,0 +1,79 @@
+name: Checks - litgen
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  litgen_check:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/llnl/sundials_spack_cache:llvm-17.0.4-h4lflucc3v2vage45opbo2didtcuigsn.spack
+    steps:
+      - name: Install dependencies with apt
+        run: |
+          apt update
+          apt install -y git python3 python3-pip
+
+      - name: Install black
+        run: pip install black
+
+      - name: Print black version
+        run: black --version
+
+      - name: Install cmake-format
+        run: pip install cmakelang
+
+      - name: Print cmake-format version
+        run: cmake-format --version
+
+      - name: Install fprettify
+        run: pip install fprettify
+
+      - name: Print fprettify version
+        run: fprettify --version
+
+      - name: Print clang-format version
+        run: clang-format --version
+
+      - name: Install sundials generator+litgen
+        run: |
+          pip install black isort pyyaml litgen@git+https://github.com/sundials-codes/litgen.git
+
+      - name: Check out repository code
+        uses: actions/checkout@v5
+        with:
+          submodules: true
+
+      - name: Add safe directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Run generator on code
+        run: |
+          cd bindings/sundials4py
+          python3 sundials4py-generate/generate.py .
+
+      - name: Run formatter on code
+        run: ./scripts/format.sh bindings/sundials4py
+
+      - name: Run git diff to see if anything changed
+        run: /usr/bin/git diff --exit-code
+
+      - name: Run git diff if we failed
+        if: failure()
+        run:  /usr/bin/git diff > litgen.patch
+
+      - name: Archive diff as a patch if we failed
+        uses: actions/upload-artifact@v5
+        if: failure()
+        with:
+          name: litgen.patch
+          path: |
+            ${{ github.workspace }}/litgen.patch

.github/workflows/sundials4py-wheels.yml

@@ -0,0 +1,120 @@
+name: sundials4py wheels
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+
+jobs:
+  build_sdist:
+    name: Build SDist
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        submodules: true
+
+    - name: Build SDist
+      run: pipx run build --sdist
+
+    - name: Check metadata
+      run: pipx run twine check dist/*
+
+    - uses: actions/upload-artifact@v5
+      with:
+        name: dist-sdist
+        path: dist/*.tar.gz
+
+
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, macos-15-intel, windows-latest]
+
+    steps:
+    - name: Set macOS deployment target
+      if: contains(matrix.os, 'macos')
+      run: echo "MACOSX_DEPLOYMENT_TARGET=$(sw_vers -productVersion | cut -d '.' -f 1-2)" >> $GITHUB_ENV
+
+    - uses: actions/checkout@v5
+      with:
+        submodules: true
+
+    - uses: pypa/[email protected]
+      env:
+        CIBW_TEST_COMMAND: "pytest {project}/bindings/sundials4py/test"
+
+    - name: Upload wheels
+      uses: actions/upload-artifact@v5
+      with:
+        path: wheelhouse/*.whl
+        name: dist-${{ matrix.os }}
+
+  build_wheels_extra:
+    name: Build extra wheels on ${{ matrix.os }} (${{ matrix.precision }}/${{ matrix.index }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        precision: [single, double]
+        index: [32, 64]
+
+    steps:
+    - name: Set macOS deployment target
+      if: contains(matrix.os, 'macos')
+      run: echo "MACOSX_DEPLOYMENT_TARGET=$(sw_vers -productVersion | cut -d '.' -f 1-2)" >> $GITHUB_ENV
+
+    - uses: actions/checkout@v5
+      with:
+        submodules: true
+
+    - uses: pypa/[email protected]
+      env:
+        CMAKE_ARGS: "-DSUNDIALS_PRECISION=${{ matrix.precision }} -DSUNDIALS_INDEX_SIZE=${{ matrix.index }}"
+        CIBW_TEST_COMMAND: "pytest {project}/bindings/sundials4py/test"
+
+    - name: Rename wheels to include config
+      run: |
+        for whl in wheelhouse/*.whl; do
+          mv "$whl" "$(echo $whl | sed 's/\.whl$/-${{ matrix.precision }}-${{ matrix.index }}.whl/')"
+        done
+      shell: bash
+
+    - name: Upload wheels
+      uses: actions/upload-artifact@v5
+      with:
+        path: wheelhouse/*.whl
+        name: dist-${{ matrix.os }}
+
+  upload:
+    name: Upload if release
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    steps:
+    - uses: actions/setup-python@v5
+    - uses: actions/download-artifact@v4
+      with:
+        path: dist
+        pattern: dist-*
+        merge-multiple: true
+
+    - uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.pypi_password }}

.gitignore

@@ -19,6 +19,7 @@
 /.pydevproject
 .vscode
 compile_commands.json
+.venv
 .clangd
 
 # custom test environment setup script
@@ -69,6 +70,7 @@ compile_commands.json
 /doc/build/
 /doc/*/build/
 /doc/shared/__pycache__
+/doc/shared/Python/sundials4py-*-functions.rst
 
 # PDFs of user guides and example docs
 /doc/*/*_guide.pdf
@@ -82,3 +84,7 @@ uberenv_libs
 
 # tools
 /tools/suntools/__pycache__
+
+# python
+.pytest_cache
+__pycache__

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "external/sundials-addon-example"]
 	path = external/sundials-addon-example
 	url = https://github.com/sundials-codes/sundials-addon-example.git
+[submodule "bindings/sundials4py/sundials4py-generate"]
+	path = bindings/sundials4py/sundials4py-generate
+	url = https://github.com/sundials-codes/sundials4py-generate.git

.readthedocs.yaml

@@ -7,9 +7,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.9"
+    python: "3.12"
   apt_packages:
     - graphviz
 

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Major Features
 
+SUNDIALS now has official Python interfaces! With this release, we are shipping a **beta version** of
+the sundials4py Python module (created with nanobind and litgen). sundials4py provides explicit
+interfaces to most features of SUNDIALS. 
+
 ### New Features and Enhancements
 
 The functions `CVodeGetUserDataB` and `IDAGetUserDataB` were added to CVODES

CMakeLists.txt

@@ -243,6 +243,10 @@ if(SUNDIALS_ENABLE_EXTERNAL_ADDONS)
   add_subdirectory(external)
 endif()
 
+if(SUNDIALS_ENABLE_PYTHON)
+  add_subdirectory(bindings/sundials4py)
+endif()
+
 # ===============================================================
 # Install configuration header files and license file.
 # ===============================================================