GpuPluginStub.cpp File Reference

Placeholder GPU surface-solver plugin (Phase 0 scaffold). More...

#include "../solver/GpuPluginAbi.h"
#include <cstring>

Include dependency graph for GpuPluginStub.cpp:

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 *)
	Construct the Kokkos explicit LTS marcher surface solver.

Detailed Description

Placeholder GPU surface-solver plugin (Phase 0 scaffold).

Implements the GpuPluginAbi.h contract with NO actual GPU backend. It exists so the runtime discovery / dlopen / fallback wiring can be built and exercised without a device toolchain. The probe reports "no device", so the core's auto-selection falls back to the serial CPU ExplicitInertialSolver.

This translation unit deliberately depends on NOTHING beyond the C ABI header and the C++ standard library — no Kokkos — so it compiles with a plain host compiler on every platform.

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

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.

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.