adam_seam_interpolation_library

Weight tables and pure evaluators for the 2:1 coarse->fine seam ghost fill (issue #21, plan amendment v2, milestone N0).

Geometry. Uniform Cartesian 2:1 refinement, cell-centered point values. The 8 fine ghost cells overlying a coarse donor (anchor) cell sit at octant sub-positions eta = -1/4 (sub=1) and eta = +1/4 (sub=2) of the coarse spacing, per direction. Weights are 1D vectors composed in tensor product (w = wxwywz) by the evaluators; the fill kernel (N2) reads the same tables.

Anchor position ("shift state", G3/G4). The anchor cell occupies position p of the 1D footprint; node offsets relative to the anchor are ([1..n] - p). Centered states: tricubic p=2 for sub=2, p=3 for sub=1; compatible p=2 for both. Off-centered states implement the shift-inward rule at tangential block boundaries (donors are real cells, always).

The two regimes (G1 as amended, #21 issuecomment-4869444520). Exact restriction-compatibility R o P = I (R = the existing 8-cell-mean restriction, one_or_eight=8) is PROVABLY incompatible with reproduction of quadratics for point values: any P exact on quadratics fills the octants of f = x^2 with the exact values (all H^2/16), whose 8-mean is H^2/16 /= 0 = f(anchor). Hence:

• SEAM_FILL_TRICUBIC (default candidate): plain tensor tricubic, exact for per-direction degree <= 3, ghost accuracy q = 4, mean defect O(H^2).
• SEAM_FILL_COMPATIBLE (diagnostic arm): the unique symmetric 3-node pair with exact R o P = I for arbitrary data, exact for linears only (q = 2). The quadratic set is the G3 safety valve (centered only; must never be reached in production maps -- reaching it is a maps-build bug).

All weights are integer/2^k rationals: EXACT in binary floating point. Partition of unity therefore holds to 0 ulp in every table.

Device availability (issue #22 F2). Every public procedure carries !$acc routine seq: single-source host/device, callable from OpenACC parallel regions on the FNL backend (weight tables are parameters, materialized by the compiler on device). Inert comments on non-OpenACC builds. Pinned on device by test_seam_interpolation_fnl.

Source: src/lib/common/adam_seam_interpolation_library.F90

Dependencies

Contents

• seam_meta_unpack
• seam_tricubic_centered_pos
• seam_compatible_centered_pos
• seam_interpolate_tricubic
• seam_interpolate_compatible
• seam_shift_anchor_pos
• seam_meta_pack
• seam_interpolate_quadratic

Variables

Name	Type	Attributes	Description
SEAM_FILL_INJECTION	integer(kind=I4P)	parameter	Regime: 0th-order injection (legacy behavior).
SEAM_FILL_COMPATIBLE	integer(kind=I4P)	parameter	Regime: restriction-compatible fill, q=2 (diagnostic arm).
SEAM_FILL_TRICUBIC	integer(kind=I4P)	parameter
SEAM_W_TRICUBIC	real(kind=R8P)	parameter	1D cubic Lagrange weights at eta = -+1/4: (node 1:4, sub 1:2, anchor position p 1:4).
SEAM_W_COMPATIBLE	real(kind=R8P)	parameter	1D restriction-compatible weights (node 1:3, sub 1:2, anchor position p 1:3):
SEAM_W_QUADRATIC	real(kind=R8P)	parameter	1D centered quadratic weights (node 1:3 at offsets -1..1, sub 1:2): the G3

Subroutines

seam_meta_unpack

Unpack the per-fine-ghost interpolation metadata (inverse of seam_meta_pack).

Attributes: pure

subroutine seam_meta_unpack(meta, sub, p4, p3)

Arguments

Name	Type	Intent	Attributes	Description
meta	integer(kind=I4P)	in		Packed metadata.
sub	integer(kind=I4P)	out		Octant sub-position per direction (1|2).
p4	integer(kind=I4P)	out		Tricubic anchor position per direction (1..4).
p3	integer(kind=I4P)	out		Compatible anchor position per direction (1..3).

Call graph

Functions

seam_tricubic_centered_pos

Centered anchor position for the tricubic footprint: nodes -1..2 for eta=+1/4 (p=2), nodes -2..1 for eta=-1/4 (p=3).

Attributes: pure

Returns: integer(kind=I4P)

function seam_tricubic_centered_pos(sub) result(p)

Arguments

Name	Type	Intent	Attributes	Description
sub	integer(kind=I4P)	in		Octant sub-position (1 => eta=-1/4, 2 => eta=+1/4).

Call graph

seam_compatible_centered_pos

Centered anchor position for the compatible footprint (p=2 for both subs).

Attributes: pure

Returns: integer(kind=I4P)

function seam_compatible_centered_pos(sub) result(p)

Arguments

Name	Type	Intent	Attributes	Description
sub	integer(kind=I4P)	in		Octant sub-position (unused: symmetric footprint).

Call graph

seam_interpolate_tricubic

Tensor tricubic interpolation on a 4x4x4 coarse footprint. footprint(i,j,k) holds the donor values at node offsets (i - anchor_pos(1), j - anchor_pos(2), k - anchor_pos(3)) in coarse-cell units; the target is the octant center (eta(sub(1)), eta(sub(2)), eta(sub(3))), eta = (-1)^sub / 4.

Attributes: pure

Returns: real(kind=R8P)

function seam_interpolate_tricubic(footprint, sub, anchor_pos) result(value_)

Arguments

Name	Type	Intent	Attributes	Description
footprint	real(kind=R8P)	in		Coarse donor values.
sub	integer(kind=I4P)	in		Octant sub-position per direction (1|2).
anchor_pos	integer(kind=I4P)	in		Anchor position per direction (1..4).

Call graph

seam_interpolate_compatible

Tensor restriction-compatible interpolation on a 3x3x3 coarse footprint; same index conventions as the tricubic evaluator.

Attributes: pure

Returns: real(kind=R8P)

function seam_interpolate_compatible(footprint, sub, anchor_pos) result(value_)

Arguments

Name	Type	Intent	Attributes	Description
footprint	real(kind=R8P)	in		Coarse donor values.
sub	integer(kind=I4P)	in		Octant sub-position per direction (1|2).
anchor_pos	integer(kind=I4P)	in		Anchor position per direction (1..3).

Call graph

seam_shift_anchor_pos

Anchor position after the G3 shift-inward rule: clamp the centered position so the footprint node offsets ([1..footprint_n] - p) around anchor stay inside the donor block's REAL cells [1..n_cells]. Valid for n_cells >= footprint_n and anchor in [1..n_cells] (both guaranteed at maps-build; the maps pass asserts n_cells >= 4).

Attributes: pure

Returns: integer(kind=I4P)

function seam_shift_anchor_pos(anchor, n_cells, p_centered, footprint_n) result(p)

Arguments

Name	Type	Intent	Attributes	Description
anchor	integer(kind=I4P)	in		Donor anchor cell index (interior, 1-based).
n_cells	integer(kind=I4P)	in		Donor block interior cell count in this direction.
p_centered	integer(kind=I4P)	in		Centered anchor position for the active sub-position.
footprint_n	integer(kind=I4P)	in		Footprint width (4 tricubic, 3 compatible).

Call graph

seam_meta_pack

Pack the per-fine-ghost interpolation metadata into one integer (map-row payload, G4): bits 0-2 = octant (sub-1 per direction), bits 3-8 = tricubic anchor positions - 1 (2 bits each), bits 9-14 = compatible anchor positions - 1 (2 bits each). Regime-independent: the kernel unpacks the field matching the active fill regime. NOTE: 0 is a VALID packed value — consumers must gate on the map's flag column, never on meta /= 0.

Attributes: pure

Returns: integer(kind=I4P)

function seam_meta_pack(sub, p4, p3) result(meta)

Arguments

Name	Type	Intent	Attributes	Description
sub	integer(kind=I4P)	in		Octant sub-position per direction (1|2).
p4	integer(kind=I4P)	in		Tricubic anchor position per direction (1..4).
p3	integer(kind=I4P)	in		Compatible anchor position per direction (1..3).

Call graph

seam_interpolate_quadratic

Tensor centered quadratic interpolation on a 3x3x3 coarse footprint (safety valve: centered anchor only, node offsets -1..1 per direction).

Attributes: pure

Returns: real(kind=R8P)

function seam_interpolate_quadratic(footprint, sub) result(value_)

Arguments

Name	Type	Intent	Attributes	Description
footprint	real(kind=R8P)	in		Coarse donor values.
sub	integer(kind=I4P)	in		Octant sub-position per direction (1|2).

Call graph