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   2

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_surface_solver (const OpenSwmmGpuProbe *probe)
	Construct the GPU surface solver.
OPENSWMM_GPU_ABI void *	openswmm_make_gpu_inertial_solver (const OpenSwmmGpuProbe *probe)
	Construct the GPU LOCAL-INERTIAL surface solver (MOMENTUM=inertial).

Detailed Description

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

Phase 0 scaffolding for the portable GPU CVODE strategy (docs/2D_GPU_PORTABLE_CVODE_STRATEGY.md §4.1). 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_surface_solver()— factory for the backend

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 MIT License

Macro Definition Documentation

OPENSWMM_GPU_ABI

#define OPENSWMM_GPU_ABI

OPENSWMM_GPU_ABI_VERSION

#define OPENSWMM_GPU_ABI_VERSION   2

ABI version. The core refuses a plugin whose abi_version disagrees. v2: SurfaceStateData grew the active_set pointer (dry-cell masking) — a v1 plugin would mis-read the struct layout.

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_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_inertial_solver()

OPENSWMM_GPU_ABI void * openswmm_make_gpu_inertial_solver

(

const OpenSwmmGpuProbe *

probe

)

Construct the GPU LOCAL-INERTIAL surface solver (MOMENTUM=inertial).

OPTIONAL ABI symbol (does not bump OPENSWMM_GPU_ABI_VERSION): the core dlsym()s it only when the model selects the local-inertial momentum closure, and falls back to the serial CPU ArkodeSurfaceSolver when a plugin does not export it. Returns an ISurfaceSolver* (as void*) owned by the caller, or NULL.

openswmm_make_gpu_surface_solver()

OPENSWMM_GPU_ABI void * openswmm_make_gpu_surface_solver

(

const OpenSwmmGpuProbe *

probe

)

Construct the GPU surface solver.

Parameters

probe

The probe result the core obtained from openswmm_gpu_probe().

Returns

An ISurfaceSolver* (as void*) owned by the caller, or NULL on failure. The core deletes it via the ISurfaceSolver destructor.