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   9

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 const char *	openswmm_gpu_build_contract (void)
	v5 compatibility check, called BEFORE probe or factory.
OPENSWMM_GPU_ABI void	openswmm_destroy_gpu_explicit_solver (void *solver)
	Destroy on the execution owner through the allocating plugin.
OPENSWMM_GPU_ABI const char *	openswmm_gpu_last_error (void)
	Last construction error on this controlling thread; plugin-owned text.
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. Discovery uses C symbols, but solver calls cross a C++ ABI. The core requires matching headers, host toolchain and build configuration before probing or constructing a solver.

The principal entry points are:

• 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); the core adapter dispatches calls and plugin-owned destruction through a single controlling thread.

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

Apache-2.0

Macro Definition Documentation

OPENSWMM_GPU_ABI

#define OPENSWMM_GPU_ABI

OPENSWMM_GPU_ABI_VERSION

#define OPENSWMM_GPU_ABI_VERSION   9

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

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_destroy_gpu_explicit_solver()

OPENSWMM_GPU_ABI void openswmm_destroy_gpu_explicit_solver

(

void *

solver

)

Destroy on the execution owner through the allocating plugin.

Destroy a solver using the same plugin that allocated it.

Parameters

[in]

solver

Owned factory result from this loaded plugin; NULL is safe. Foreign/already-destroyed pointers are unsupported.

Postcondition

Releases solver-owned host/device state without finalizing the process Kokkos runtime.

Note

Call on the controlling execution-owner thread after all solver work/callers finish, before unloading the plugin. Consumes the pointer; no status is returned.

openswmm_gpu_build_contract()

OPENSWMM_GPU_ABI const char * openswmm_gpu_build_contract

(

void

)

v5 compatibility check, called BEFORE probe or factory.

Borrow the plugin's generated C++ compatibility fingerprint.

Returns

Immutable NUL-terminated build-contract string owned by the loaded plugin, valid until library unload. Do not modify/free it; copy if retained beyond unload.

Note

Must be checked before probing or creating a solver. No runtime initialization, allocation or solver ownership transfer.

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.

Returns

Effective initialized host worker count, or zero before initialization/on a device backend. Read-only process-level query; no runtime is initialized by this call.

openswmm_gpu_last_error()

OPENSWMM_GPU_ABI const char * openswmm_gpu_last_error

(

void

)

Last construction error on this controlling thread; plugin-owned text.

Borrow the controlling thread's most recent factory diagnostic.

Returns

Plugin-owned NUL-terminated thread-local error text, empty after a successful factory call. Do not free/modify; copy before the next factory call on that thread, thread exit, or library unload.

Note

Does not report arbitrary solver/runtime errors or clear the diagnostic.

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.

Note

out must be non-NULL and point to a full current-ABI record; NULL returns nonzero. Successful metadata strings are bounded NUL-terminated copies and requested_threads is reset to zero.

Does not construct a solver or retain the record. Device probes may initialize driver query state; the OpenMP probe advertises one host backend without initializing Kokkos. A failed non-NULL probe can still overwrite metadata.

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.

Parameters

[in]

probe

Optional borrowed current-ABI probe; OpenMP reads requested_threads and device plugins ignore it. NULL selects backend defaults.

Returns

Plugin-allocated ISurfaceSolver pointer represented as void*, or NULL for initialization/allocation failure. Obtain diagnostic text from openswmm_gpu_last_error().

Note

No probe pointer is retained. The core must dispatch use and destruction on its execution-owner thread, call openswmm_destroy_gpu_explicit_solver() exactly once, and keep the library loaded until destruction. Kokkos initializes lazily and is not finalized by solver destruction.

Here is the call graph for this function: