peclet::core::python Namespace Reference

Classes
class	Releasable
	Base of everything on the binding side that owns Kokkos Views on Python's behalf. More...
struct	ViewCapsule
	The payload of a zero-copy capsule: a reference to the exported View, registered as a Releasable so the module's shutdown can drop it before Kokkos::finalize. More...

Functions
std::vector< std::function< void()> > &	release_hooks ()
	Extra release callbacks (e.g. a C++ class's own releaseAll), run after the registry.
void	add_release_hook (std::function< void()> f)
void	release_all () noexcept
	Drop every Kokkos View owned on Python's behalf in this module (registry + hooks).
void	shutdown () noexcept
	release_all() and then Kokkos::finalize().
template<class T >
void	destruct_bound_instance (T *self) noexcept
	Release a bound wrapper by destroying its C++ instance in place (for types whose Kokkos state cannot be dropped member by member).
void	install (nb::module_ &m)
	Module setup: initialize Kokkos (once per module — each module carries its own static Kokkos), register the atexit shutdown, expose finalize() and execution_space.
template<class MemorySpace >
std::pair< int, int >	dlpack_device ()
	Map a Kokkos memory space to a DLPack {device_type, device_id} pair.
template<class T >
void	require_dtype (const nb::ndarray<> &a, const char *who)
	Throw if a's element type is not T.
template<class V , std::size_t N>
auto	view_to_ndarray (const V &view, const std::array< std::size_t, N > &shape, const std::array< std::int64_t, N > &strides)
	Export a Kokkos View to a Python array without copying, with an explicit logical shape and element-unit strides over the View's memory (e.g.
template<class V >
auto	view_to_ndarray (const V &view)
	Export a Kokkos View to a Python array without copying.
template<class T >
nb::ndarray< nb::numpy, T >	vector_to_ndarray (std::vector< T > &&v, std::initializer_list< std::size_t > shape, std::initializer_list< std::int64_t > strides)
	Export a host std::vector<T> as a NumPy array of the given logical shape and element-unit strides, without the extra copy the old to_xyz made: the vector is moved into a capsule that backs the array.
template<class T >
peclet::core::View< T >	ndarray_to_view (const nb::ndarray<> &a, const std::string &label)
	Import a (contiguous) Python array into a freshly-allocated flat device peclet::core::View<T>.
template<class T >
std::vector< T >	ndarray_to_vector (const nb::ndarray<> &a)
	Import a (contiguous) Python array into a host std::vector<T>.

Variables
template<class MemorySpace >
constexpr bool	is_host_space_v
	True when MemorySpace is reachable from the host (NumPy export path); false for a device-resident space (CUDA/HIP — DLPack/CuPy export path).

Function Documentation

release_hooks()

std::vector< std::function< void()> > & peclet::core::python::release_hooks ( )

inline

Extra release callbacks (e.g. a C++ class's own releaseAll), run after the registry.

Definition at line 75 of file kokkos_teardown.hpp.

Referenced by add_release_hook(), and release_all().

add_release_hook()

void peclet::core::python::add_release_hook ( std::function< void()>  f )

inline

Definition at line 79 of file kokkos_teardown.hpp.

References release_hooks().

release_all()

void peclet::core::python::release_all ( )

inlinenoexcept

Drop every Kokkos View owned on Python's behalf in this module (registry + hooks).

Idempotent. Iterates a snapshot: a release() may destroy its object and thereby unregister it.

Definition at line 85 of file kokkos_teardown.hpp.

References peclet::core::python::Releasable::registry(), and release_hooks().

Referenced by shutdown().

shutdown()

void peclet::core::python::shutdown ( )

inlinenoexcept

release_all() and then Kokkos::finalize().

This is the module's atexit hook and its finalize() function; safe to call more than once.

Definition at line 97 of file kokkos_teardown.hpp.

References release_all().

Referenced by install().

destruct_bound_instance()

template<class T >

void peclet::core::python::destruct_bound_instance ( T *  self )

inlinenoexcept

Release a bound wrapper by destroying its C++ instance in place (for types whose Kokkos state cannot be dropped member by member).

Runs the destructor now; nanobind marks the Python object uninitialized (later calls raise TypeError, final dealloc skips the destructor). No-op if self is not (or no longer) a live bound instance.

Definition at line 108 of file kokkos_teardown.hpp.

install()

void peclet::core::python::install ( nb::module_ &  m )

inline

Module setup: initialize Kokkos (once per module — each module carries its own static Kokkos), register the atexit shutdown, expose finalize() and execution_space.

Definition at line 116 of file kokkos_teardown.hpp.

References peclet::core::defaultHostThreads(), and shutdown().

dlpack_device()

template<class MemorySpace >

std::pair< int, int > peclet::core::python::dlpack_device ( )

inline

Map a Kokkos memory space to a DLPack {device_type, device_id} pair.

Host → cpu; otherwise the active GPU backend (CUDA, or ROCm under a HIP build), with the default device's id.

Definition at line 53 of file ndarray_interop.hpp.

require_dtype()

template<class T >

void peclet::core::python::require_dtype ( const nb::ndarray<> &  a, const char *  who  )

inline

Throw if a's element type is not T.

Definition at line 67 of file ndarray_interop.hpp.

view_to_ndarray() [1/2]

template<class V , std::size_t N>

auto peclet::core::python::view_to_ndarray	(	const V &	view,
		const std::array< std::size_t, N > &	shape,
		const std::array< std::int64_t, N > &	strides
	)

Export a Kokkos View to a Python array without copying, with an explicit logical shape and element-unit strides over the View's memory (e.g.

a flat padded field re-shaped to its 3-D block). Either a host or device View. The returned array references view's memory and keeps it alive via a capsule owning a (ref-counted) reference to the View; host views come back as numpy.ndarray, device views as a DLPack array (consume with cupy.from_dlpack).

Definition at line 89 of file ndarray_interop.hpp.

Referenced by view_to_ndarray().

view_to_ndarray() [2/2]

template<class V >

auto peclet::core::python::view_to_ndarray

(

const V &

view

)

Export a Kokkos View to a Python array without copying.

Works for any rank and either a host or device View. Shape and element-unit strides are taken from the View, so non-contiguous / padded views (e.g. a ghosted inner region) export correctly. See the overload above for the ownership contract.

Definition at line 112 of file ndarray_interop.hpp.

References view_to_ndarray().

vector_to_ndarray()

template<class T >

nb::ndarray< nb::numpy, T > peclet::core::python::vector_to_ndarray	(	std::vector< T > &&	v,
		std::initializer_list< std::size_t >	shape,
		std::initializer_list< std::int64_t >	strides
	)

Export a host std::vector<T> as a NumPy array of the given logical shape and element-unit strides, without the extra copy the old to_xyz made: the vector is moved into a capsule that backs the array.

Use for solver getters that already return a host vector (e.g. a ghost-stripped x-fastest field → shape {nx,ny,nz}, strides {1,nx,nx*ny}).

Definition at line 128 of file ndarray_interop.hpp.

ndarray_to_view()

template<class T >

peclet::core::View< T > peclet::core::python::ndarray_to_view	(	const nb::ndarray<> &	a,
		const std::string &	label
	)

Import a (contiguous) Python array into a freshly-allocated flat device peclet::core::View<T>.

A host array is staged up (deep_copy from an unmanaged host wrap == the old peclet::core::toDevice); a device array on this build's backend is wrapped unmanaged and copied on-device (no host bounce — the CuPy zero-copy-onto-GPU path). An array on an incompatible device throws. The caller must pass a contiguous array (bindings enforce this via a typed nb::ndarray<T, nb::c_contig> / nb::f_contig parameter); the data is read as a flat buffer of a.size() elements.

Definition at line 145 of file ndarray_interop.hpp.

ndarray_to_vector()

template<class T >

std::vector< T > peclet::core::python::ndarray_to_vector

(

const nb::ndarray<> &

a

)

Import a (contiguous) Python array into a host std::vector<T>.

A host array is memcpy'd; a device array is copied down to the host (for solver APIs whose setters take host vectors). The caller enforces contiguity / element order via a typed binding parameter; the array is read as a flat buffer of a.size() elements.

Definition at line 172 of file ndarray_interop.hpp.

Variable Documentation

is_host_space_v

template<class MemorySpace >

constexpr bool peclet::core::python::is_host_space_v

inlineconstexpr

Initial value:

=
    Kokkos::SpaceAccessibility<Kokkos::HostSpace, MemorySpace>::accessible

True when MemorySpace is reachable from the host (NumPy export path); false for a device-resident space (CUDA/HIP — DLPack/CuPy export path).

Definition at line 47 of file ndarray_interop.hpp.