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

…eature/python-interfaces

Co-authored-by: David Gardner <[email protected]>

doc/shared/Python/Usage.rst

doc/superbuild/source/developers/getting_started/Checklist.rst

drreynolds · 2025-11-24T03:31:55Z

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

+
+This chapter covers details developers need to know about the SUNDIALS Python interfaces, distributed as the Python package sundials4py.
+
+We use `nanobind <https://github.com/wjakob/nanobind>__` for the Python bindings. nanobind is a sleeker, faster ``pybind11``.


Is nanobind a fork/version of pybind11? Is it just a completely separate package? As written, it sounds like the developers of pybind11 just cleaned things up and changed the name.

Suggested change

We use `nanobind <https://github.com/wjakob/nanobind>__` for the Python bindings. nanobind is a sleeker, faster ``pybind11``.

We use `nanobind <https://github.com/wjakob/nanobind>__` for the Python bindings. nanobind is a sleeker, faster replacement for ``pybind11``.

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

drreynolds

I've finished going through doc. I have a good amount of bindings/sundials4py to finish...

drreynolds

This looks great! I have a few more questions/comments, but I believe I've finished a first pass over my "assignments"

bindings/sundials4py/arkode/arkode_usersupplied.hpp

bindings/sundials4py/arkode/arkode_splittingstep.cpp

drreynolds · 2025-11-24T16:18:43Z

bindings/sundials4py/arkode/arkode_mristep.cpp

+using namespace sundials::experimental;
+


This is duplicated below

Suggested change

using namespace sundials::experimental;

drreynolds · 2025-11-24T16:20:00Z

bindings/sundials4py/arkode/arkode_mristep.cpp

+  // m.def("MRIStepInnerStepper_GetForcingData",
+  //       [](MRIStepInnerStepper stepper) -> std::tuple<int, sunrealtype, sunrealtype, std::vector<N_Vector>, int> {
+
+  //           sunrealtype tshift = 0.0;
+  //           sunrealtype tscale = 0.0;
+  //           N_Vector* forcing_1d  = nullptr;
+  //           int nforcing = 0;
+
+  //           int status = MRIStepInnerStepper_GetForcingData(stepper, &tshift, &tscale, &forcing_1d, &nforcing);
+
+  //           std::vector<N_Vector> forcing(nforcing);
+  //           // TODO(CJB): for some reason this causes a segfault unless you clone
+  //           // for (int i = 0; i < nforcing; i++) {
+  //           //   // forcing[i] = N_VClone(forcing_1d[i]);
+  //           //   forcing[i] = forcing_1d[i];
+  //           // }
+
+  //           return std::make_tuple(status, tshift, tscale, forcing, nforcing);
+  //       });


Should this commented-out code be removed or fixed?

bindings/sundials4py/arkode/arkode_arkstep.cpp

drreynolds · 2025-11-24T18:55:14Z

bindings/sundials4py/examples/arkode/ark_heat1D.py

+    assert status == ARK_SUCCESS
+
+    # PCG linear solver with no preconditioning, with up to N iterations
+    LS = SUNLinSol_PCG(y, 0, N, sunctx)


We should update the C example to use the enum as well:

Suggested change

LS = SUNLinSol_PCG(y, 0, N, sunctx)

LS = SUNLinSol_PCG(y, SUN_PREC_NONE, N, sunctx)

drreynolds · 2025-11-24T18:59:21Z

bindings/sundials4py/examples/arkode/ark_lotka_volterra_ASA.py

+    status = ark.ARKodeSetMaxNumSteps(arkode.get(), int((tf - t0) / dt) + 1)
+    assert status == ark.ARK_SUCCESS
+
+    # # Enable checkpointing during the forward run


Suggested change

# # Enable checkpointing during the forward run

# Enable checkpointing during the forward run

drreynolds · 2025-11-24T19:01:23Z

bindings/sundials4py/examples/cvodes/cvs_brusselator.py

+#    transition, both u and v continue to evolve somewhat
+#    rapidly for another 1.4 time units, and finish off smoothly.
+#
+# This program solves the problem with the DIRK method, using a


Suggested change

# This program solves the problem with the DIRK method, using a

# This program solves the problem with the BDF method, using a

bindings/sundials4py/examples/cvodes/cvs_brusselator.py

drreynolds · 2025-11-24T19:10:44Z

bindings/sundials4py/examples/kinsol/kinLaplace_bnd.py

+        # Reshape to 2D for vectorized operations
+        u2d = np.zeros((self.NX + 2, self.NY + 2), dtype=sunrealtype)
+        # Fill interior points
+        for i in range(1, self.NX + 1):
+            for j in range(1, self.NY + 1):
+                u2d[i, j] = u[idx(i, j)]


Based on your comment, it looks like you were attempting to use np.reshape but couldn't get it to work, so you ended up copying u into a new 2D array, u2d. If so, it's too bad that this didn't work, since numpy's multi-dimensional arrays are incredibly attractive for structured grid calculations, but I recommend that you modify the comment:

Suggested change

# Reshape to 2D for vectorized operations

u2d = np.zeros((self.NX + 2, self.NY + 2), dtype=sunrealtype)

# Fill interior points

for i in range(1, self.NX + 1):

for j in range(1, self.NY + 1):

u2d[i, j] = u[idx(i, j)]

# Copy state to 2D for vectorized operations

u2d = np.zeros((self.NX + 2, self.NY + 2), dtype=sunrealtype)

# Fill interior points

for i in range(1, self.NX + 1):

for j in range(1, self.NY + 1):

u2d[i, j] = u[idx(i, j)]

The comment was chatgpt and I missed updating it (chatgpt did a great job at the initial porting of C examples to Python). I did not try using np.reshape.

Co-authored-by: Daniel R. Reynolds <[email protected]>

Steven-Roberts

Review of docs. I now realize that wasn't assigned to me, but I needed to read it anyway to install and understand sundials4py.

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

doc/shared/Python/Introduction.rst

doc/shared/Python/Usage.rst

Steven-Roberts · 2025-11-25T01:00:20Z

doc/shared/Python/Usage.rst

+
+SUNDIALS packages and several modules/classes require user-supplied callback functions to define problem-specific behavior, 
+such as the right-hand side of an ODE or a nonlinear system function. In sundials4py, you can provide these as standard Python functions or lambdas.
+Somethings to note:


Suggested change

Somethings to note:

Here are some things to note:

bindings/sundials4py/arkode/arkode_usersupplied.hpp

doc/superbuild/source/developers/source_code/Naming.rst

doc/superbuild/source/developers/source_code/Rules.rst

balos1 and others added 30 commits October 15, 2025 16:22

Merge branch 'docs/breakout-fortran-ug' into feature/python-interfaces

94bbeed

Merge branch 'feature/python-interfaces' into feature/python-nanobind

e6c42da

add numpydoc to requirements.txt

1fc0857

fix duplicate section

df724c6

rename to sundials4py

6677ad1

developer note

6384028

format

402d4db

fix array type def

e32225b

build wheels for different precisions

01a5b47

add more doc sections on install and usage

e1a0d38

rst syntax fixes

38c9f12

minor doc fixes

435ba0d

add CIBW_TEST_COMMAND

a472311

comment out extra wheels for now

3b025bf

turn off some tests

04774a2

update developer docs

3d54c26

wip: gen arkode functions not previously generated

c293a35

format

7e28ac8

require python 3.12

dfccda2

note Python version requirement

0e7fb0e

fix version in pyproject toml

1225302

get rid of macos 13 and add macos arm versions

20f3db0

format

d41e295

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

1a9a835

…eature/python-interfaces

Merge branch 'feature/python-interfaces' into feature/python-nanobind

dbf6d99

unskip tests

32f410b

skip sunadaptcontroller tests

9c524ea

generate arkode functions not previously generated

8314827

fix include guards

1314408

turn off deprecated declaration warnings when building the python module

b396d75

balos1 and others added 21 commits November 17, 2025 15:08

address Steven's comments

e7fdf83

update docs

f5c73c3

Merge branch 'feature/enable-python' into feature/python-nanobind

bdc220c

use is_pointer<T>::value since we dont require c++17 in some c++ builds

49e6b50

remove class specialization

c6fed8a

fix noexcepts on convertibleto overrides

eb3bb33

regen swig

a968995

fix doc duplicate text

c287caf

Merge branch 'feature/enable-python' into feature/python-nanobind

8b143ed

fix docs, constructor, view name

9165791

fix docs, constructor, view name

f960e23

doc update

4fc7e0f

update docs

e712323

Merge branch 'feature/enable-python' into feature/python-nanobind

9a68200

use move assignment

68dd14c

remove const

98aea33

Apply suggestions from code review

fc2c06b

Co-authored-by: David Gardner <[email protected]>

move note

9cd8556

Merge branch 'develop' into feature/enable-python

9a3df22

Merge branch 'feature/enable-python' into feature/python-nanobind

237d2cf

ensure correct python min version

310e1b4

Base automatically changed from feature/enable-python to develop November 21, 2025 00:15

Merge branch 'develop' into feature/python-nanobind

20b2460

drreynolds reviewed Nov 24, 2025

View reviewed changes

balos1 and others added 3 commits November 24, 2025 17:03

fix doc structure

b5d50bb

fix layout

4fd7173

Apply suggestions from code review

bae2a7e

Co-authored-by: Daniel R. Reynolds <[email protected]>

Steven-Roberts reviewed Nov 25, 2025

View reviewed changes


		This chapter covers details developers need to know about the SUNDIALS Python interfaces, distributed as the Python package sundials4py.

		We use `nanobind <https://github.com/wjakob/nanobind>__` for the Python bindings. nanobind is a sleeker, faster ``pybind11``.

	LS = SUNLinSol_PCG(y, 0, N, sunctx)
	LS = SUNLinSol_PCG(y, SUN_PREC_NONE, N, sunctx)

	# # Enable checkpointing during the forward run
	# Enable checkpointing during the forward run

	# This program solves the problem with the DIRK method, using a
	# This program solves the problem with the BDF method, using a

Add Python interfaces based on nanobind #796

Are you sure you want to change the base?

Add Python interfaces based on nanobind #796

Conversation

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

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!

Uh oh!

Uh oh!

Uh oh!

drreynolds left a comment

Choose a reason for hiding this comment

Uh oh!

drreynolds left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Steven-Roberts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

balos1 commented Nov 11, 2025 •

edited

Loading