GpuPluginAbi.h File Reference

Stable C ABI between the core engine and an optional GPU solver plugin. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	OpenSwmmGpuProbe

Macros
#define	OPENSWMM_GPU_ABI
#define	OPENSWMM_GPU_ABI_VERSION   4
#define	OPENSWMM_GPU_ABI_VERSION_ENV_THREADS_FALLBACK   3

Typedefs
typedef enum OpenSwmmGpuVendor	OpenSwmmGpuVendor
typedef struct OpenSwmmGpuProbe	OpenSwmmGpuProbe

Enumerations
enum	OpenSwmmGpuVendor {   OPENSWMM_GPU_VENDOR_NONE = 0 ,   OPENSWMM_GPU_VENDOR_CUDA = 1 ,   OPENSWMM_GPU_VENDOR_HIP = 2 ,   OPENSWMM_GPU_VENDOR_SYCL = 3 ,   OPENSWMM_GPU_VENDOR_OPENMP = 4 }

Functions
OPENSWMM_GPU_ABI int	openswmm_gpu_probe (OpenSwmmGpuProbe *out)
	Query the plugin for a usable GPU device.
OPENSWMM_GPU_ABI void *	openswmm_make_gpu_explicit_solver (const OpenSwmmGpuProbe *probe)
	Construct the Kokkos explicit LTS marcher surface solver.
OPENSWMM_GPU_ABI int	openswmm_gpu_host_threads (void)
	(v4, optional) Host thread count the plugin's Kokkos runtime is initialised with; 0 when not yet initialised or not a host backend.

Detailed Description

Stable C ABI between the core engine and an optional GPU solver plugin.

The GPU backend ships as a SEPARATE shared library that the core discovers and dlopen()s at runtime; it is never linked into openswmm_engine. Communication therefore crosses a plain C ABI so it is robust to compiler/toolchain differences between the core and the plugin (which may be built with nvcc/hipcc/icpx against Kokkos).

Two symbols form the contract:

• openswmm_gpu_probe() — cheap capability query
• openswmm_make_gpu_explicit_solver() — marcher factory

The factory returns an ISurfaceSolver* as a void* (the core casts it back); ownership transfers to the core, which deletes through the ISurfaceSolver virtual destructor.

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n Apache-2.0

Macro Definition Documentation

OPENSWMM_GPU_ABI

#define OPENSWMM_GPU_ABI

OPENSWMM_GPU_ABI_VERSION

#define OPENSWMM_GPU_ABI_VERSION   4

ABI version. The core refuses a plugin whose abi_version disagrees, except that a v3 plugin is still accepted through the thread-count environment fallback (see requested_threads below). v3: CVODE/ARKODE plugin solvers retired (D2, 2026-07-29) — the explicit marcher factory is the only solver entry, and SurfaceStateData dropped the active_set pointer, so a v2 plugin would mis-read the struct layout. v4: OpenSwmmGpuProbe gained requested_threads (core → plugin, appended so the v3 prefix layout is unchanged) and the optional entry point openswmm_gpu_host_threads() (plugin → core).

OPENSWMM_GPU_ABI_VERSION_ENV_THREADS_FALLBACK

#define OPENSWMM_GPU_ABI_VERSION_ENV_THREADS_FALLBACK   3

Typedef Documentation

OpenSwmmGpuProbe

typedef struct OpenSwmmGpuProbe OpenSwmmGpuProbe

Result of a capability probe. Filled by openswmm_gpu_probe().

OpenSwmmGpuVendor

typedef enum OpenSwmmGpuVendor OpenSwmmGpuVendor

GPU vendor / backend identifier reported by a plugin.

Enumeration Type Documentation

OpenSwmmGpuVendor

enum OpenSwmmGpuVendor

GPU vendor / backend identifier reported by a plugin.

Enumerator
OPENSWMM_GPU_VENDOR_NONE	no usable device / stub
OPENSWMM_GPU_VENDOR_CUDA	NVIDIA (Kokkos CUDA)
OPENSWMM_GPU_VENDOR_HIP	AMD (Kokkos HIP)
OPENSWMM_GPU_VENDOR_SYCL	Intel (Kokkos SYCL)
OPENSWMM_GPU_VENDOR_OPENMP	CPU multithreaded (Kokkos OpenMP, Phase 1)

Function Documentation

openswmm_gpu_host_threads()

OPENSWMM_GPU_ABI int openswmm_gpu_host_threads

(

void

)

(v4, optional) Host thread count the plugin's Kokkos runtime is initialised with; 0 when not yet initialised or not a host backend.

Kokkos initialises once per process, so this is the number every later solver in the process will run with regardless of requested_threads. The core dlsym()s it optionally — a plugin that does not export it is still accepted.

openswmm_gpu_probe()

OPENSWMM_GPU_ABI int openswmm_gpu_probe

(

OpenSwmmGpuProbe *

out

)

Query the plugin for a usable GPU device.

Must be cheap and side-effect-free beyond backend initialization.

Parameters

out	Caller-allocated struct to fill. Zero-initialized on entry by the plugin.

Returns

0 on success with at least one usable device; non-zero if no device is available or the probe failed. A non-zero return tells the core to fall back to the CPU solver.

openswmm_make_gpu_explicit_solver()

OPENSWMM_GPU_ABI void * openswmm_make_gpu_explicit_solver

(

const OpenSwmmGpuProbe *

probe

)

Construct the Kokkos explicit LTS marcher surface solver.

The only solver factory in the contract: the core dlsym()s it and falls back to the serial CPU ExplicitInertialSolver when a plugin does not export it. Implements BOTH cell closures (FLAT and VFR). Returns an ISurfaceSolver* (as void*) owned by the caller, or NULL.