nanobind Based Interface

[philip-paul-mueller]

Adds a Python <-> C interface that uses nanobind instead of ctypes.
The NanobindCompiledSDFG wrapper is not intended to replace the original ctypes based CompiledSDFG class but to act as an alternative and is thus provided as an opt-in.
The advantages of it is that calling it is much faster than before as (most) argument processing is moved into C++.

However, since nanobind works a bit differently and the interface was designed for performance, not everything that the ctypes interface supports is supported by the nanobind interface as well.

Most Important Changes

Here is a short summary of the most important changes a user should be aware before switching.

• Before CompiledSDFG made sure that for every instance there was a separate .so file and performed a copy if needed.
  This is no longer possible as the name of the file now has a significance for Python.
  Instead now multiple NanobindCompiledSDFG instances can use the same .so file.
• The above change implies that the .so file can not have a state.
  All state information is contained in the handle, which is (still) managed by the compiled SDFG object.
• Before it was possible to unload a .so file, which was done when the CompiledSDFG was garbage collected or finalize() was called.
  This is no longer possible as Python does not allow to unload modules.
  If an SDFG is compiled while its identity is already loaded (see below) it will be silently renamed.
• The generated .so files are now Python C extensions that are "normal" modules that can be imported.
  They are imported under the dace.generated package, as dace.generated.<magic>.<name>, where <magic> is a hash of the resolved build folder.
  A module's identity is thus the pair (build folder, SDFG name): SDFGs with the same name that build into different folders coexist in one process.
  Loading the same pair again returns the already imported module; the loader verifies that it refers to the same file and fails loudly otherwise.
  The generated C++ types additionally carry a content hash in their namespace, so two different programs sharing an SDFG name can not be dispatched into each other (nanobind's type registry is process wide and keyed by type name).
• Recompiling an UNCHANGED SDFG whose identity is already loaded reuses the loaded module: the module bakes the source SDFG's pre-codegen content hash, compile() compares against it and, on a match, returns a fresh handle - no rename, no rebuild.
  A changed SDFG still renames and rebuilds (a module cannot be reloaded), and instrumentation changes count as changes (they alter the generated code even though the semantic SDFG hash ignores them).
  Hash instability can only cause a redundant rebuild, never a wrong reuse.
  SDFGs carrying unresolved external nested SDFGs participate as well: the reuse key is computed on a resolved deepcopy (via the new SDFG.load_external_nsdfgs() helper), so the caller's object is never mutated by the lazy loading.
  Gated by compiler.nanobind_reuse_loaded (default: enabled).
• compile() now returns a handle whose sdfg attribute is an isolated deepcopy (pinned to the build folder) on EVERY return path.
  Previously the cached-binary (use_cache) path and the no-regenerate path passed the original object, so later mutations of the caller's SDFG leaked into the handle.
  Note that this deliberately also applies to the ctypes interface (the paths are shared).
• The renaming on a collision follows two regimes.
  If the build folder is derived from the configuration (cache set to name, hash or unique) the renamed program also derives its own build folder from the new name, thus it never overwrites the artifacts of the original folder.
  If the build folder was set explicitly (which essentially behaves as cache set to single) the folder is fixed and the renamed program builds in place inside it; keeping such a folder consistent is the responsibility of the user.
  Instead of renaming, an error can be requested through compiler.nanobind_name_collision.
• NanobindCompiledSDFG no longer stores the (processed) arguments of the previous call.
  This means that calls such as get_workspace_sizes() and set_workspace() now needs the symbols.
  However, they accept the same call arguments as __call__() and initialize().
• Compilation is significantly longer and the resulted files are larger.
  It is thus recommended to set compiler.build_folder_mode to production.
• Scalar pyobject arguments are supported: the object passes through as an opaque PyObject* (typical use: forwarded into a callback) and arrives there as the very same object.
  The wrapper keeps the object alive for the duration of the call; the program must not retain the pointer beyond it.
  Arrays of pyobjects are supported too: a numpy dtype=object array binds through
  __array_interface__ (DLPack refuses object arrays outright), and the caller's array keeps
  the contained objects alive for the call - the same lifetime contract as ctypes, which
  also hands out pointers into the caller's buffer.
  pyobject return values are supported and decay to the single contained object, matching
  the ctypes convention (_return_arrays[i].item()).
• The interface is able to perform symbol inferences in C.
  This means if the symbol argument N is also used as shape/strides of an array and is not provided, then it is taken from there.
  If it is present then no consistency check is performed.
  Note that symbols that are listed in arg_names can not be inferred but can act as source for symbol inferences.
  As an example, assume you have an array with symbolic shape of (a + b,) and you have added b to arg_names, then b can be inferred.
  However not all arrays can be used as source, for example arrays of structs are not considered only fundamental types can be used.
  Since return values are allocated inside the binding after inference ran, inferred symbols may also size return arrays.

Structured Call Signatures (user_args)

As an opt-in, an SDFG can declare a structured call signature through the new SDFG.user_args property.
Its entries are argument names or (nested) tuples of argument names; the property is serialized and thus enters the cache hash.
If it is set, the bindings additionally generate a user_call entry point, exposed as NanobindCompiledSDFG.user_bind_call().
This call path takes the declared positional layout directly (tuple entries arrive as Python tuples), performs no keyword processing at all and is the fastest way to call a compiled SDFG with full argument processing.
Every argument of the SDFG must either be listed in user_args or be inferable; this is verified at code-generation time and violations refuse to generate, naming the argument.
Return values are refused on this path and only primitive scalars, scalar pyobjects and plain arrays may be listed.
An empty string entry is an ignored placeholder slot: the position exists in the caller's convention, accepts any value (including None) and is never read; nested placeholder slots still count toward the tuple length check.
The GPU error-record check still applies (inside the compiled binding), unless disabled through the gpu_error_check property.

Both arg_names and user_args are implemented by the new ArgumentSignatureProperty type.
arg_names is still only allowed to have a flat list of strings, while user_args may have the nested structure.
While the json format is different than the old one, it is possible to load files that were generated before.

Things Still done in Python

There are some things that are not ported to C and are still done in Python.

• Hooks are still managed in Python.
• The callbacks are also fully processed in Python and are passed as arguments.

GPU errors are checked in the compiled binding, using the same mechanism as ctypes:
after each program call the binding reads (and clears) the error the generated code recorded for this SDFG (__dace_gpu_last_error) and raises it.
The process-global CUDA last-error slot is never consulted; it is per-host-thread and shared with every other GPU user in the process, so it can carry third-party state.
The check is only compiled in when a GPU target emitted its init/exit pair.
Translating a nonzero __dace_exit code in finalize() still goes through the Python-side GPU runtime.

Return values are allocated by the compiled binding itself (through NumPy/CuPy via the Python API, so ownership and dtype semantics are unchanged), AFTER the compiled symbol inference - so inferred symbols may size a return array.
The binding also builds and returns the result (bare array or tuple); a call with return values no longer needs any Python-side processing.
Whether a caller-provided __return* buffer is accepted is baked in at code generation from compiler.nanobind_allow_return_override (changing it requires a recompile); an accepted buffer is validated against the symbol-derived return shape (struct-element returns excepted).
Return arrays must have offset 0 (violations refuse at code generation), and when do_not_execute suppresses the program run the call returns None.

Good to Know

To achieve best performance the following rules should be followed:

• Only pass arrays of primitive types.
• Do not use callbacks (as their processing is done in Python and slow).
• NanobindCompiledSDFG.gpu_error_check (also a constructor argument) can disable the per-call GPU error check, but it is now a plain in-library read of the SDFG's own error record, so disabling it buys next to nothing.
• If your call arguments can be decomposed in a nested structure of tuples, i.e. struct of array, use SDFG.user_args and call through user_bind_call().
• It is no longer possible to copy and rename the generated file.
• The original ctypes based CompiledSDFG class was renamed to CtypesCompiledSDFG and put into a different file.
  compiled_sdfg.py now contains the definition of a protocol but also exports CompiledSDFG as a deprecated alias.
• The fast_call() interface is no longer supported, a call can only be made using __call__().
• An SDFG with external (workspace) memory refuses to run before set_workspace() was called, with a clear error naming the storage type.
  Under ctypes the same call silently dereferences a null workspace pointer (usually a segfault).
  The requirement is per state: finalize() drops the association, so a re-initialized handle must be given its workspace again.
• Generated code compiles with the same flags as under ctypes:
  nanobind_add_module()'s defaults are disabled (NOMINSIZE, PROTECT_STACK), since they would apply to the whole module and thus override compiler.build_type's optimization level (-Os) and drop the stack protector on the kernels.

Not Supported

• Return values are arrays, or a pyobject (which decays to the single contained object, as under ctypes).
  Python scalar returns are unsupported on BOTH interfaces - SDFG.validate rejects them, so this is not a compatibility gap.
• Scalars of the low-precision types bfloat16, float8_e4m3fn and float8_e5m2 are rejected at code generation (they would need nanobind value type-casters).
  Low-precision RETURN arrays are supported: the in-binding allocation imports ml_dtypes (without it NumPy cannot resolve the dtype name) and the pointer comes from the array-interface dict.
  The storage is not special-cased - a GPU return hands the dtype to CuPy exactly as the ctypes allocator does, and CuPy succeeds or raises on its own (CuPy gained experimental ml_dtypes.bfloat16 support in v15.0.0a1; float8 is not covered).
  Arrays of these types ARE supported, but through a weaker mechanism than other arrays: numpy cannot export ml_dtypes-backed arrays via DLPack or the buffer protocol, so the raw pointer is extracted from __array_interface__ (__cuda_array_interface__ on GPU) - the same protocol the ctypes marshaller uses.
  The only check is the itemsize from the interface's typestr; there is no dtype identity and no contiguity check, and such arrays cannot serve as symbol-inference sources nor appear in user_args.
• SDFG.safe_call() is refused (it hides the compiled object, whose collision rename would make post-call queries on the original SDFG unsound, e.g. get_latest_report()).
  Use compile() and CompiledSDFG.safe_call() instead, and query instrumentation reports via the compiled object's sdfg.
• The same rename unsoundness affects data-instrumentation report lookups:
  a same-name recompile (e.g. re-instrumenting a program that is already loaded) renames into its own build folder, so an implicit "latest report" lookup on the new compiled object finds nothing.
  Pass the report explicitly (dace.instrument_data(..., restore_from=dreport)); SDFG.call_with_instrumented_data always receives it explicitly and works unchanged.
  Programs sharing one name also share report folders under ctypes already - give programs distinct names when their reports must stay apart.
• Passing None for an array requires the descriptor to be marked optional, e.g. an Optional[T] type hint.
  ctypes silently passes a null pointer for any array argument.
• Lossy scalar casts, e.g. float -> int parameters are now rejected.
• NumPy scalars are accepted unless compiler.nanobind_strict_scalar_cast is specified.
• Passing float16 scalars as arguments is not possible, but passing float16 arrays is supported.
• Python lists and __array_interface__-style objects are not coerced to arrays; pass numpy arrays.
• Views pass zero-copy via DLPack; compiler.allow_view_arguments is a ctypes-marshalling concept and is not consulted.
• No caching of previous call arguments (_lastargs):
  the workspace getters/setters take the symbol values they need per call.
• An already-imported module cannot be reloaded after a same-path recompile, CPython cannot unload extension modules, ctypes ReloadableDLL covers that workflow.
  Recompilation under a taken (build folder, name) identity renames instead.
• Thread-safety model is documented on the class and in the generated code
  (same initialization race as ctypes; no shared per-call state, unlike _lastargs).

Configuration added

The following configurations were added:

• compiler.interface (ctypes | nanobind, default ctypes):
  Decides which backend is used.
• compiler.nanobind_strict_scalar_cast (default off):
  Decides if (safe) widening casts are allowed (only applies to Python scalars)
• compiler.nanobind_allow_return_override (default off):
  Decides if it is allowed to explicitly pass the implicit __return arguments to __call__().
  Consulted at code generation only - the decision is baked into the module, changing the option requires a recompile.
• compiler.nanobind_name_collision (rename | error, default rename):
  Decides what happens when an SDFG is compiled while its (build folder, name) identity is already loaded: silently rename or refuse.
• compiler.nanobind_reuse_loaded (default on):
  Reuse an already-loaded, content-identical module on recompile instead of rename-and-recompile (see "Most Important Changes").

Modified Tests

Here is an explanation for all skip that were added.

Python lists not Coerced (skip_list_arg_on_nanobind)

ctypes' marshaller runs np.asarray on every argument, so a Python list passed for an array parameter is silently converted to an array (and any writes to that array are not propagated).
The nanobind binding is nb::ndarray<T>.noconvert(), which accepts only objects exposing the DLPack or buffer protocol, a bare list has neither and is rejected at dispatch.

__array_interface__-Style Objects not Coerced (skip_arraylike_args_on_nanobind)

ctypes reads NumPy's __array_interface__ protocol to obtain a data pointer, so an object exposing it (wrapping real memory) is passed by reference.
nanobind's nb::ndarray speaks DLPack / buffer protocol, not __array_interface__, so such an object is not recognised at dispatch and leads to an error.
(The low-precision types are the deliberate exception: their arrays bypass nb::ndarray and read __array_interface__ directly, see "Most Important Changes".)
Implementing it in C would mean to reimplement the array processing in nanobind.
A Python fallback would be possible, but be slow.

Module Reload After Same-Path Recompile (skip_lib_reuse, skip_recompile_folder_mode, skip_recompile_reload)

These assert that recompiling an SDFG in place yields a fresh, reloaded library within the same process.
ctypes wraps the shared object in ReloadableDLL (dlclose + dlopen).
A nanobind module is a CPython extension module, which cannot be unloaded or reloaded once imported, a recompile is therefore renamed (into its own build folder for configuration-derived folders, in place for explicitly set ones), and a same-path reimport returns the already-loaded module.
The reload semantics cannot exist under nanobind.

ctypes Pointer-Array Input Form (skip_ctypes_pointer_array_on_nanobind)

A ContainerArray (array of pointers) can be supplied on ctypes as a ctypes pointer array ((POINTER(c_double) * m)(...)).
nanobind takes the same pointers as a NumPy uint64 array instead.
It is the ctypes-specific input form that is skipped, the nanobind form has its own container-array test.

View Rejection not Applicable (skip_view_rejection_on_nanobind)

compiler.allow_view_arguments is a ctypes-marshalling switch that, when off, rejects non-contiguous / view arrays.
nanobind passes any DLPack-compatible view zero-copy and never consults that config, so the "views are rejected" assertion does not apply.

Return-override is opt-in (skip_return_override_on_nanobind)

ctypes lets a caller pass their own buffer for a __return value.
nanobind forbids this by default, this can be enabled by setting compiler.nanobind_allow_return_override (baked in at code generation; changing it requires a recompile).
The default-behaviour assertion differs, the opt-in path has its own nanobind test.

Lossy Scalar Cast Rejected vs. Warned (test_bad_cast_csdfg)

ctypes' marshaller emits a Casting UserWarning and truncates a lossy scalar, e.g. 0.1 -> int parameter.
nanobind rejects a lossy cast outright (overflow-checked casters), so there is no warning to assert.
This is an implementation detail of nanobind.

SDFG.safe_call() Refused (skip_sdfg_safe_call_on_nanobind)

SDFG.safe_call() compiles internally and hides the compiled object; a compiled nanobind module cannot be reloaded, so a recompile under an already-loaded identity is silently renamed into its own build folder.
Post-call queries on the original SDFG (e.g. get_latest_report()) would then silently look in the wrong folder, hence the method raises on the nanobind interface.
The four tests exercising it are skipped; the *_precompiled variants cover the supported route (compile() + CompiledSDFG.safe_call(), reports queried via the compiled object's sdfg).

Weakened

• Missing-argument error type: a missing program argument raises KeyError
  on ctypes and TypeError from the nanobind dispatcher; the test accepts both.
• Workspace symbols per call: the external-memory API takes the symbol values
  it needs per call under nanobind (there is no _lastargs cache),
  so the test passes symbols to the workspace getters under nanobind and none under ctypes.