Add Python interfaces based on nanobind #796

balos1 · 2025-11-11T10:12:10Z

This PR adds sundials4py, which is a Python interface to SUNDIALS.

The generator code can be found here: https://github.com/sundials-codes/sundials4py-generate.

Rendered docs: https://sundials--796.org.readthedocs.build/en/796/.

Review Requests

@drreynolds:

@gardner48:

Everything but can skip:

_generated.hpp files (Steven and I will review these)
bindings/sundials4py/examples (Steven and Dan are both reviewing these)
bindings/sundials4py/arkode (Steven and Dan both reviewing these)
bindings/sundials4py/idas (Steven and Dan both reviewing these)

@Steven-Roberts

…obind

…eature/python-nanobind

gardner48

Finished a pass over the PR updates. Still need to make a pass over the docs.

gardner48 · 2026-01-10T21:14:17Z

.github/workflows/sundials4py-wheels.yml

+        merge-multiple: true
+
+    - name: Upload wheels to release
+      uses: softprops/action-gh-release@v1


I was going to suggest we enable immutable releases in the repo, do you know if this action would work with a draft release (see the suggested workflow)?

I believe that it should work with drafts.

Only actions from a limited number for sources are allowed (see the error here), so we'll need to remove this job.

bindings/sundials4py/arkode/arkode.cpp

bindings/sundials4py/arkode/arkode_lsrkstep.cpp

bindings/sundials4py/test/test_cvodes.py

bindings/sundials4py/test/test_lsrkstep.py

examples/python/arkode/ark_lotka_volterra_ASA.py

gardner48 · 2026-01-12T01:38:55Z

src/cvode/cvode.c


  if (cv_mem->proj_mem) { cvProjFree(&(cv_mem->proj_mem)); }

-  free(cv_mem->python);


Should we remove python from CVodeMemRec?

Also need to remove free(IDA_mem->python); in src/ida.c (and maybe remove python from IDAMemRec).

Yeah, we could remove it from CVode and IDA. I will do that.

gardner48

Starting in on the docs

doc/arkode/guide/source/Python/index.rst

gardner48 · 2026-01-13T06:27:18Z

doc/requirements.txt

 sphinx-toolbox
 sphinxcontrib-googleanalytics
-sphinx-multitoc-numbering
+sphinxcontrib.bibtex
+git+https://github.com/LLNL/sundials.git@feature/python-nanobind


This works for building the docs in this PR but what should this be after this is merged?

sundials4py or the main/develop branch

Would this work for newly added functions in a PR?

We probably need to replace the entry in the requirements.txt with a pip install command in the driver script(s) that uses the cloned branch. Now, though, I am curious how this may work with RTD builds. Particularly, for features like CUDA support. RTD would need to have a build with CUDA enabled. We may need to generate the API files offline.

We could probably setup up a workflow for CUDA like we have for SYCL where it's just for build testing. AMReX has something like this here (and similarly for hip here).

bindings/sundials4py/cvodes/cvodes.cpp

gardner48 · 2026-01-13T06:49:31Z

bindings/sundials4py/sundials4py.cpp

+
+void bind_sunadjointcheckpointscheme_fixed(nb::module_& m);
+
+void bind_sundomeigest_power(nb::module_& m);


It might be helpful to users to have a table like we do for Fortran e.g., we list the core but it's not clear which of the implementations of the core classes are included without searching the list of functions provided by the core module.

gardner48 · 2026-01-14T23:13:39Z

bindings/sundials4py/test/test_arkstep.py

+    status = ARKodeSetLinearSolver(ark.get(), ls, A)
+    assert status == ARK_SUCCESS
+
+    def jac_fn(t, yvec, fyvec, J, tmp1, tmp2, tmp3, _):


Is the underscore in the right place?

Suggested change

def jac_fn(t, yvec, fyvec, J, tmp1, tmp2, tmp3, _):

def jac_fn(t, yvec, fyvec, J, _, tmp1, tmp2, tmp3):

gardner48 · 2026-01-14T23:17:59Z

doc/shared/Python/Usage.rst

+   #     sunrealtype* lambdaR, sunrealtype* lambdaI,
+   #     void* user_data, N_Vector temp1,
+   #     N_Vector temp2, N_Vector temp3)
+   def dom_eig(t, yvec, fnvec, temp1, temp2, temp3, _):


Is this ordering correct?

Suggested change

def dom_eig(t, yvec, fnvec, temp1, temp2, temp3, _):

def dom_eig(t, yvec, fnvec, _, temp1, temp2, temp3):

gardner48 · 2026-01-14T23:43:57Z

doc/shared/Python/index.rst

+
+   Introduction.rst
+   Usage.rst
+   sundials4py-core-functions.rst


A couple of comments from looking over the autogenerated docs. Not sure how easy some of these are to address (or if they need to be), so this might be something that we work on while the interface is in beta.

The SUNErrCode enum is listed but I thought these values were not accessible from Python (see this comment)

Maybe some things should be excluded from the docs e.g.,

Enumerations, since they have the same values as in C

Structures the user shouldn't need to interact with like class sundials4py.core._generic_N_Vector_Ops(*args, **kwargs). The addition of (*args, **kwargs) might also be confusing (I assume they are unused)

It might be more useful to co-locate the python signatures with the C functions since they are mostly a link back to the C docs for additional details about the function and its inputs/outputs.

The signatures are maybe more verbose than necessary e.g.,
sundials4py.core.N_VMake_Serial(vec_length: int, v_data_1d: numpy.ndarray[dtype=float64, shape=(*), order='C'], sunctx: sundials4py.core.SUNContext_) → [sundials4py.core._generic_N_Vector]
could maybe be more like
N_VMake_Serial(vec_length, v_data_1d, sunctx) → [N_Vector]
or the additional details about the types could be in the body of the function documentation.

gardner48 · 2026-01-15T01:10:07Z

doc/superbuild/source/developers/python/index.rst

+   cd sundials_root_directory
+   python -m venv .venv  # create python virtual environment
+   . .venv/bin/activate  # activate the python virtual environment
+   pip install scikit-build-core[pyproject] hatchling nanobind # this is a prerequisite for the next step


To build the interface I had to do

pip install scikit-build-core[pyproject] hatchling nanobind setuptools scikit-build pybind11

gardner48 · 2026-01-15T01:14:39Z

doc/superbuild/source/developers/python/index.rst

+
+If you are developing new features inside of sundials, you may also need to install the Python code generator package,
+`sundials4py-generate <https://github.com/sundials-codes/sundials4py-generate>`__. The steps to install this package are
+found in its repo.


Maybe I'm missing it, but I don't see install instructions in the repo

gardner48 · 2026-01-15T01:41:02Z

.github/workflows/sundials4py-wheels.yml

+        merge-multiple: true
+
+    - name: Upload wheels to release
+      uses: softprops/action-gh-release@v1


Only actions from a limited number for sources are allowed (see the error here), so we'll need to remove this job.

gardner48

Finished a pass over the docs

gardner48 · 2026-01-15T15:24:26Z

doc/superbuild/source/developers/python/index.rst

+not the correctness of SUNDIALS itself.
+
+
+User-supplied functions


Add a note about about when/why we need the StdFn version of the wrappers (see this comment).

gardner48 · 2026-01-15T15:29:35Z

doc/superbuild/source/developers/python/index.rst

+     *jcurPtrB = std::get<1>(result);
+
+     return std::get<0>(result);
+   }


It would be good to add a section on things to note when handwriting wrappers. A few things that came up in the review:

When a wrapper can't be autogenerated and needs to be handwritten (for example this comment)

Using keep_alive (see this comment)

Use .none() when we need to allow for passing None (see this comment)

balos1 added 30 commits October 30, 2025 16:35

all tests passing with shared_ptr approach

7dd2e91

missed one

b7ad2fb

remove print

1f1ef75

remove unused view classes

a71abab

remove generate_all script

c1d8822

update examples

c0a8400

fix typo

b18ab0b

fix more nurse,patient edge cases

3ea0862

format

3a8a57e

add custom exception

4ab6a9c

Merge remote-tracking branch 'origin/develop' into feature/python-nan…

f2fca2f

…obind

Merge branch 'develop' into docs/breakout-fortran-ug

ddc1840

Merge remote-tracking branch 'origin/docs/breakout-fortran-ug' into f…

14e080d

…eature/python-nanobind

remove extra using

5cb329a

remove fortran (lowercase f) directory

79cd452

remove git status debugging steps in wheels workflow

26f21c2

dont generate MRIStepSetPreInnerFn/MRIStepSetPostInnerFn

62b62f6

dont generate some

9f2c368

more function pointer set functions

e8fa248

one more missing function pointer setter

8469810

another arkode setter

d4f5998

memory helper test

753ab0b

typo

feda9ee

formatt

930b5b8

see what happens with linearcombination off

45477d1

fix runner tags

fe1a97d

comment out setarraypointer test

6091707

fix tags

3f142db

regen and format

9145e55

ensure MACOSX_DEPLOYMENT_TARGET set

3c64ced

balos1 added 17 commits January 6, 2026 16:35

idas: add extern C function to destroy python function table

e4d61da

kinsol: add extern C function to destroy python function table

a504230

core: add extern C function to destroy python function table

f842571

add test submodule

f53f7cd

format

3b75d5a

move examples

e54b08b

format and spelling

340a546

ls wheelhouse

f2f970d

formatting

828377f

add missing c:func: to nitpick_ignore

4fbb375

unique artifact names

03be64c

dont autogen functions in Jenkins

04cfeb6

dont autogen functions in Jenkins

f302d3d

attach wheels to releases

2562cd2

update sphinx requirements

a402f11

fix MRIStepInnerStepper_GetForcingData

36678e1

check if running on jenkins

469807f

balos1 requested review from Steven-Roberts and drreynolds January 10, 2026 00:31

balos1 added 4 commits January 9, 2026 21:12

generate stub files

a7fae94

fix path

e199db9

fix path

d3dcd0e

fix paths again ...

47c69c2

gardner48 requested changes Jan 12, 2026

View reviewed changes

gardner48 added 2 commits January 12, 2026 21:52

add option to use mock module when building docs

50aa728

update superbuild for mock module

c80970a

gardner48 reviewed Jan 13, 2026

View reviewed changes

minor doc updates

abd3047

gardner48 reviewed Jan 15, 2026

View reviewed changes

gardner48 requested changes Jan 15, 2026

View reviewed changes


		if (cv_mem->proj_mem) { cvProjFree(&(cv_mem->proj_mem)); }

		free(cv_mem->python);


		void bind_sunadjointcheckpointscheme_fixed(nb::module_& m);

		void bind_sundomeigest_power(nb::module_& m);

	def jac_fn(t, yvec, fyvec, J, tmp1, tmp2, tmp3, _):
	def jac_fn(t, yvec, fyvec, J, _, tmp1, tmp2, tmp3):

	def dom_eig(t, yvec, fnvec, temp1, temp2, temp3, _):
	def dom_eig(t, yvec, fnvec, _, temp1, temp2, temp3):

		not the correctness of SUNDIALS itself.


		User-supplied functions

Add Python interfaces based on nanobind #796

Are you sure you want to change the base?

Add Python interfaces based on nanobind #796

Uh oh!

Conversation

balos1 commented Nov 11, 2025 • edited by Steven-Roberts Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gardner48 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gardner48 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

balos1 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gardner48 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

balos1 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gardner48 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gardner48 Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gardner48 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

balos1 commented Nov 11, 2025 •

edited by Steven-Roberts

Loading

balos1 Jan 13, 2026 •

edited

Loading

gardner48 Jan 13, 2026 •

edited

Loading

balos1 Jan 13, 2026 •

edited

Loading

gardner48 Jan 13, 2026 •

edited

Loading

gardner48 Jan 14, 2026 •

edited

Loading