GpuPluginHip.cpp File Reference

Plugin entry points for the Phase 5 Kokkos/HIP surface solver (AMD). More...

#include "../solver/GpuPluginAbi.h"
#include "../solver/ISurfaceSolver.hpp"
#include "GpuPluginSupport.hpp"
#include <mutex>
#include <stdexcept>
#include <Kokkos_Core.hpp>
#include <hip/hip_runtime.h>
#include <cstring>

Include dependency graph for GpuPluginHip.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

Plugin entry points for the Phase 5 Kokkos/HIP surface solver (AMD).

Exports the GpuPluginAbi.h contract for the openswmm_gpu_hip plugin. Identical in shape to GpuPluginCuda.cpp — the probe advertises an AMD device and the factory constructs the Kokkos marcher — but the solver's execution space is Kokkos::HIP (selected by the OPENSWMM_GPU_EXECSPACE_HIP define the CMake target sets), so the whole RHS / preconditioner / vector pipeline runs device-resident.

Per strategy §6.1, this file plus a CMake branch, the ExecSpace typedef, and a vcpkg feature are the entire AMD delta: the solver and kernel sources are reused verbatim from the CUDA backend.

Kokkos is initialized lazily on first solver construction and is intentionally NOT finalized (same rationale as the CUDA plugin): only this plugin uses Kokkos, and finalizing at dlclose risks destroying device Views that outlive the call.

Compiles only with a ROCm toolchain (hipcc) against a HIP-enabled Kokkos. Not buildable on macOS/Apple Silicon.

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.

Here is the call graph for this function: