GwRechargePluginAbi.h File Reference

C ABI for groundwater recharge plugins. More...

#include "GpuPluginAbi.h"
#include <stdint.h>

Include dependency graph for GwRechargePluginAbi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	OpenSwmmGwCapabilitiesV1
struct	OpenSwmmGwRechargeInputV1

Macros
#define	OPENSWMM_GW_RECHARGE_ABI_VERSION   1
#define	OPENSWMM_GW_OPERATOR_CLOSED_FORM_RECHARGE   1u
#define	OPENSWMM_GW_HOST_WATER_AND_RECEIPTS   1u
#define	OPENSWMM_GW_HOST_TRANSPORT   2u
#define	OPENSWMM_GW_HOST_REACTIONS   4u
#define	OPENSWMM_GW_HOST_THERMAL   8u
#define	OPENSWMM_GW_EXECUTION_HOST_OPENMP   1u

Typedefs
typedef struct OpenSwmmGwCapabilitiesV1	OpenSwmmGwCapabilitiesV1
typedef struct OpenSwmmGwRechargeInputV1	OpenSwmmGwRechargeInputV1

Functions
OPENSWMM_GPU_ABI int	openswmm_gw_capabilities_v1 (OpenSwmmGwCapabilitiesV1 *)
	Query an independent host recharge-operator capability record.
OPENSWMM_GPU_ABI int	openswmm_gw_recharge_v1 (const OpenSwmmGwRechargeInputV1 *, int, double *, int)
	Evaluate a synchronous batch of independent CLOSED_FORM recharge cells.

Detailed Description

C ABI for groundwater recharge plugins.

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_GW_EXECUTION_HOST_OPENMP

#define OPENSWMM_GW_EXECUTION_HOST_OPENMP   1u

OPENSWMM_GW_HOST_REACTIONS

#define OPENSWMM_GW_HOST_REACTIONS   4u

OPENSWMM_GW_HOST_THERMAL

#define OPENSWMM_GW_HOST_THERMAL   8u

OPENSWMM_GW_HOST_TRANSPORT

#define OPENSWMM_GW_HOST_TRANSPORT   2u

OPENSWMM_GW_HOST_WATER_AND_RECEIPTS

#define OPENSWMM_GW_HOST_WATER_AND_RECEIPTS   1u

OPENSWMM_GW_OPERATOR_CLOSED_FORM_RECHARGE

#define OPENSWMM_GW_OPERATOR_CLOSED_FORM_RECHARGE   1u

OPENSWMM_GW_RECHARGE_ABI_VERSION

#define OPENSWMM_GW_RECHARGE_ABI_VERSION   1

Typedef Documentation

OpenSwmmGwCapabilitiesV1

typedef struct OpenSwmmGwCapabilitiesV1 OpenSwmmGwCapabilitiesV1

OpenSwmmGwRechargeInputV1

typedef struct OpenSwmmGwRechargeInputV1 OpenSwmmGwRechargeInputV1

Function Documentation

openswmm_gw_capabilities_v1()

OPENSWMM_GPU_ABI int openswmm_gw_capabilities_v1

(

OpenSwmmGwCapabilitiesV1 *

out

)

Query an independent host recharge-operator capability record.

Argument contract

• Argument 1 (out, caller-owned): Required OpenSwmmGwCapabilitiesV1 record with struct_size set to its exact current sizeof. Other fields are overwritten only after that shape check.

Returns

Zero on success; nonzero for unsupported/null record. OpenMP implementation returns one for invalid storage/shape and leaves it unchanged.

Note

Capability availability does not mean the operator has executed. Initializes no solver, keeps no caller pointers, and transfers no ownership. Plugin library must remain loaded while using its entry points.

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 a synchronous batch of independent CLOSED_FORM recharge cells.

Argument contract

• Argument 1 (in): Borrowed count-element host input array; NULL allowed only for count == 0. Each struct_size is exact, law in [0,3], Ks finite nonnegative m/s, 0 <= theta_r < theta_s <= 1, positive finite alpha 1/m, psi_b m, lambda, vg_n > 1, finite vg_L, positive length m and nonnegative hu m of water.
• Argument 2 (in): Nonnegative cell count.
• Argument 3 (out): Caller-owned count-double host array, NULL only for zero count. Receives raw recharge in m/s, positive downward and negative capillary rise. Must not overlap inputs.
• Argument 4 (in): Requested host worker count; positive requests participate in first-initialization selection, nonpositive uses defaults, and OPENSWMM_2D_THREADS takes precedence.

Returns

OpenMP implementation: zero on success/empty batch, one for input validation failure, two for runtime exceptions or nonfinite output.

Note

Validates all inputs before writing, but a runtime failure may leave partial output. Host-parallel work is fenced before returning. Calls are serialized by a recharge mutex; initialization uses a separate mutex and its effective thread count is process-wide. No accepted water/quality/heat state is committed and no pointers are retained.

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: