voro_bindings.cpp File Reference

Kokkos nanobind Python module peclet.voro. More...

#include "voro_bindings_common.hpp"

Include dependency graph for voro_bindings.cpp:

Functions
	NB_MODULE (_voro, m)

Detailed Description

Kokkos nanobind Python module peclet.voro.

Drives the production device path — multicore CPU (OpenMP), or GPU (CUDA/HIP), selected by the Kokkos backend the extension was built against — from Python. The PUBLIC surface (what a user of the method needs to set up, run and read out a computation; suite/docs/QUALITY_PLAN.md D2):

• peclet.voro.Tessellation — the bare moving-particle (power-)Voronoi tessellator, optionally SDF-clipped: a cold build plus the incremental two-pass repair update (the fast per-step path for moving points); volumes, neighbour / wall counts, and the energy layer.
• peclet.voro.FlowSolver — the static collocated / covolume Navier–Stokes solvers on the face mesh of a resident tessellation.
• peclet.voro.Simulation — the device-native compressible-Euler / Navier–Stokes moving-cell fluid (velocity-Verlet over the tessellation).
• optimize_volume_mesh, minimize_interface — the mesh optimisers on a periodic box.
• peclet.voro.pore_mesh (a lazily imported submodule) carries the SDF-walled pore-space family bound here (optimize_pore_mesh, sdf_voronoi_cells, sdf_voronoi_section).
• under PECLET_VORO_MPI: VoronoiHalo (ghost gather) and DistributedTessellation (the distributed repair driver, mpi/distributed_moving.hpp).

Every instrument, ablation switch and validity report lives on the object's diagnostics sub-object (t.diagnostics.build_report()), one per class, holding a reference to its owner.

String modes are validated against the accepted set and the error lists it; call-order requirements are state checks that name the correct order; the literals the engine is driven with are the named defaults below (also peclet.voro.defaults), and the docstrings are generated from them so they cannot drift.

Particle data crosses the boundary as NumPy arrays: positions/velocities are (N,3) float64, scalars (masses, viscosities, volumes) are (N,). Arrays move through the shared peclet::core::python bridge (core): returned arrays are backed by host buffers (no extra device copy).

Kokkos teardown follows the suite-wide pattern of peclet/core/python/kokkos_teardown.hpp: Kokkos is initialized at import; every bound Tessellation / FlowSolver / Simulation is a Releasable (registered on construction, release() drops its Views) and every zero-copy capsule of the shared bridge is one too; the module's single atexit hook (also peclet.voro.finalize()) releases all of them and THEN calls Kokkos::finalize, so an object still referenced at interpreter exit (script globals, a Jupyter/Quarto kernel) can no longer be destroyed after finalize – which is a Kokkos::abort (SIGABRT / exit 134, on OpenMP as on CUDA). Nothing needs del before exit.

Example

import numpy as np, peclet.voro
rng = np.random.default_rng(0)
pos = rng.random((100_000, 3))            # uniform points in the unit box
t = peclet.voro.Tessellation()
t.set_domain(extent=(1.0, 1.0, 1.0))
t.build(pos)                              # cold tessellation
vol = t.get_volumes()                     # (N,) cell volumes; sum ~= box volume
for _ in range(50):                       # move + repair each step (faster than rebuilding)
    pos = (pos + 1e-4 * rng.standard_normal(pos.shape)) % 1.0
    stats = t.step(pos)                   # {'flagged','pass1','pass2','rebuilt','fell_back'}
nbr = t.get_neighbor_counts()             # (N,) Voronoi neighbours per cell

Function Documentation

NB_MODULE()

NB_MODULE	(	_voro	,
		m
	)