GpuPluginOmp.cpp File Reference

Plugin entry points for the Phase 1 Kokkos/OpenMP surface solver. More...

#include "../solver/GpuPluginAbi.h"
#include "../solver/GwRechargePluginAbi.h"
#include "../subsurface/SoilCharacteristic.hpp"
#include "../solver/ISurfaceSolver.hpp"
#include "GpuPluginSupport.hpp"
#include <stdexcept>
#include <Kokkos_Core.hpp>
#include <cstdlib>
#include <cmath>
#include <atomic>
#include <mutex>
#include <cstring>

Include dependency graph for GpuPluginOmp.cpp:

Functions
OPENSWMM_GPU_ABI int	openswmm_gpu_probe (OpenSwmmGpuProbe *out)
	Query the plugin for a usable GPU device.
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.
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_gw_capabilities_v1 (OpenSwmmGwCapabilitiesV1 *out)
	Advertise the host-parallel pure recharge extension without starting Kokkos.
OPENSWMM_GPU_ABI int	openswmm_gw_recharge_v1 (const OpenSwmmGwRechargeInputV1 *input, int count, double *output, int threads)
	Evaluate validated raw recharge rates using the shared soil law on OpenMP.

Detailed Description

Plugin entry points for the Phase 1 Kokkos/OpenMP surface solver.

Exports the GpuPluginAbi.h contract for the openswmm_gpu_omp plugin. The probe advertises a usable Kokkos-OpenMP backend; the factory constructs an ExplicitKokkosSurfaceSolver. The core casts the returned void* back to ISurfaceSolver* and owns it.

Kokkos is initialized lazily on first solver construction and is intentionally NOT finalized: only this plugin uses Kokkos, and finalizing at plugin/process teardown risks destroying Views that outlive the call. Leaving the runtime resident is the safe choice for a dlopen()ed plugin.

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

OPENSWMM_GPU_ABI int openswmm_gw_capabilities_v1

(

OpenSwmmGwCapabilitiesV1 *

out

)

Advertise the host-parallel pure recharge extension without starting Kokkos.

Query an independent host recharge-operator capability record.

Parameters

[in,out]

out

Required caller record whose struct_size equals sizeof(*out).

Returns

Zero after replacing the capability record, one for NULL/shape mismatch without modification.

Note

Supports CLOSED_FORM, all four soil laws, and host-owned water/quality/heat. Label storage is inline and NUL-terminated. No pointer retention or allocation.

openswmm_gw_recharge_v1()

OPENSWMM_GPU_ABI int openswmm_gw_recharge_v1	(	const OpenSwmmGwRechargeInputV1 *	input,
		int	count,
		double *	output,
		int	threads )

Evaluate validated raw recharge rates using the shared soil law on OpenMP.

Evaluate a synchronous batch of independent CLOSED_FORM recharge cells.

Parameters

[in]	input	Borrowed count-element host input records; SI units and bounds are specified by openswmm_gw_recharge_v1's ABI contract. NULL only for count zero.
[in]	count	Nonnegative batch cell count; zero returns success without initialization.
[out]	output	Caller-owned count-double recharge array, m/s downward-positive. NULL only for zero count; must not overlap inputs.
[in]	threads	Preferred first-initialization worker count; environment override and an existing Kokkos runtime take precedence.

Returns

Zero after a successful fence and finite output check; one for preflight input refusal; two for runtime exceptions or nonfinite output. A runtime failure can leave partial output.

Note

Complete preflight precedes writes. A mutex serializes recharge launches; no water/quality/heat state or receipts are mutated, and no pointers retained. The core owns availability limits and acceptance.

Here is the call graph for this function:

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: