adam_maps_object

ADAM, maps class definition

Face direction codes (see inter_realm_neighbor_t).

Encoded as small integers rather than a Fortran enum because the values travel through the manifest INI parser and need stable, INI-friendly representations.

Source: src/lib/common/adam_maps_object.F90

Dependencies

Contents

• inter_realm_neighbor_t
• maps_object
• face_axis_sign
• blocks_reorder
• get_block_layout
• initialize
• make_comm_local_maps
• make_comm_local_maps_ghost
• mpi_gather_nodes_data
• save_local_map
• make_local_maps_bc
• alloc_comm_local_maps_ghost
• count_bc_numbers
• make_comm_map_recv_ghost_cell
• make_comm_map_send_ghost_cell
• make_local_map_ghost_cell
• dedupe_last_writer
• populate_comm_local_maps_ghost
• populate_local_map_bc_crown
• set_local_map_bc
• ijk_mmd
• ijk_mmd_ghost
• bc_cells_number

Variables

Name	Type	Attributes	Description
FACE_X_MAX	integer(kind=I4P)	parameter	+x face (max-x boundary of a block).
FACE_X_MIN	integer(kind=I4P)	parameter	-x face (min-x boundary of a block).
FACE_Y_MAX	integer(kind=I4P)	parameter	+y face.
FACE_Y_MIN	integer(kind=I4P)	parameter	-y face.
FACE_Z_MAX	integer(kind=I4P)	parameter	+z face.
FACE_Z_MIN	integer(kind=I4P)	parameter	-z face.
COUPLING_MIRROR	integer(kind=I4P)	parameter	Peer cells copied as-is (the trivial pass-through coupling).
COUPLING_PERIODIC	integer(kind=I4P)	parameter	Periodic identification across the inter-realm face (reserved, not
COUPLING_INTERPOLATE	integer(kind=I4P)	parameter	Interpolate across mismatched grids (reserved, not implemented).
CADENCE_END_OF_STEP	integer(kind=I4P)	parameter	α: once per step, after close_step_forest (default).
CADENCE_STAGE_COINCIDENT	integer(kind=I4P)	parameter	β: once per RK substage, inside the stage loop.

Derived Types

inter_realm_neighbor_t

Description of a single inter-realm face coupling.

One entry per (my realm, my block, my face) that touches a face on another realm. Populated by the forest during initialization from the [forest.topology] section of the manifest.

Architectural note: this type carries only intrinsic-typed components — no derived-type pointer components reachable from kernels. The peer_realm index is used by the consumer to look up the peer realm in the realm(:) array the forest passes through; the lookup happens on the host side outside any device region (R2).

Components

Name	Type	Attributes	Description
my_realm	integer(kind=I4P)		Realm index that owns this entry (1-based; redundant with the enclosing maps' realm, kept
my_block	integer(kind=I4P)		Block index in MY realm whose face touches the peer.
my_face	integer(kind=I4P)		Face code on MY block (FACE_X_MAX..FACE_Z_MIN).
peer_realm	integer(kind=I4P)		Realm index of the peer.
peer_block	integer(kind=I4P)		Block index in the peer realm whose face touches mine.
peer_face	integer(kind=I4P)		Face code on the peer block (typically opposite to my_face).
coupling	integer(kind=I4P)		Coupling kind (COUPLING_MIRROR | COUPLING_PERIODIC | COUPLING_INTERPOLATE).

maps_object

Maps class definition

Components

Name	Type	Attributes	Description
is_initialized_	logical		Flag: maps have been initialized.
seam_ghost_fill	integer(kind=I4P)		Coarse->fine seam ghost-fill regime (issue #21 N2): selects the
local_map	integer(kind=I8P)	allocatable	Local map, list block index changes of my nodes.
local_map_ghost	integer(kind=I8P)	allocatable	Local map for ghost cells updating [fec_number, 4].
local_map_ghost_cell	integer(kind=I8P)	allocatable	Local map ghost cells update, cells order.
local_map_bc_face	integer(kind=I8P)	allocatable	Local map for face BC ghost cells.
local_map_bc_edge	integer(kind=I8P)	allocatable	Local map for edge BC ghost cells.
local_map_bc_corner	integer(kind=I8P)	allocatable	Local map for corner BC ghost cells.
local_map_bc_crown	integer(kind=I8P)	allocatable	Local map for face BC ghost cells, crown order.
my_nodes_number	integer(kind=I4P)		Number of my nodes, keep_nodes_number + recv_nodes_number.
send_nodes_number	integer(kind=I4P)		Number of nodes to be sent.
recv_nodes_number	integer(kind=I4P)		Number of nodes to be received.
keep_nodes_number	integer(kind=I4P)		Number of nodes to be keept.
inner_blocks_number	integer(kind=I4P)		Number of inner blocks where I need fecs.
inner_outer_block_map	integer(kind=I4P)	allocatable	Inner/outer blocks map.
comm_map_n_send	integer(kind=I4P)	allocatable	Communication map, number of blocks to send [procs_number].
comm_map_n_recv	integer(kind=I4P)	allocatable	Communication map, number of blocks to recv [procs_number].
comm_map_send_ptr	integer(kind=I4P)	allocatable	Communication map, pointers in list to send [procs_number+1].
comm_map_recv_ptr	integer(kind=I4P)	allocatable	Communication map, pointers in list to recv [procs_number+1].
comm_map_send	integer(kind=I8P)	allocatable	Communication map, blocks to send [sum(comm_map_n_send)].
comm_map_recv	integer(kind=I8P)	allocatable	Communication map, blocks to receive [sum(comm_map_n_recv)].
comm_map_n_send_ghost	integer(kind=I4P)	allocatable	Communication map, number of ghost celss to send [procs_number].
comm_map_n_recv_ghost	integer(kind=I4P)	allocatable	Communication map, number of ghost celss to recv [procs_number].
comm_map_send_ptr_ghost	integer(kind=I4P)	allocatable	Communication map, pointers in list to send [procs_number+1].
comm_map_recv_ptr_ghost	integer(kind=I4P)	allocatable	Communication map, pointers in list to recv [procs_number+1].
comm_map_send_ghost	integer(kind=I8P)	allocatable	Communication map, send ghost cells, fec order.
comm_map_send_ghost_cell	integer(kind=I8P)	allocatable	Communication map, send ghost cells, cells order.
comm_map_recv_ghost	integer(kind=I8P)	allocatable	Communication map, recv ghost cells, fec order.
comm_map_recv_ghost_cell	integer(kind=I8P)	allocatable	Communication map, recv ghost cells, cells order.
send_buffer_ghost	real(kind=R8P)	allocatable	Send buffer of ghost cells.
recv_buffer_ghost	real(kind=R8P)	allocatable	Receive buffer of ghost cells.
inter_realm_neighbors	type(inter_realm_neighbor_t)	allocatable	Face couplings to other realms; unallocated when this
inter_realm_ghost_cell	integer(kind=I4P)	allocatable	Per-cell inter-realm ghost map; layout per the comment above.
inter_realm_face_register_index	integer(kind=I4P)	allocatable	(block, face_1_6) → signed flux register face index; 0 = not
seam_local_map_ghost_cell	integer(kind=I4P)	allocatable	Per-cell same-rank inter-realm ghost map; layout per the comment
seam_local_peer_realm	integer(kind=I4P)	allocatable	Peer realm index for each row range (one entry per distinct peer).
seam_local_peer_row_start	integer(kind=I4P)	allocatable	First row index in seam_local_map_ghost_cell for each peer.
seam_local_peer_row_count	integer(kind=I4P)	allocatable	Row count in seam_local_map_ghost_cell for each peer.
seam_local_cadence	integer(kind=I4P)	allocatable	Per-peer seam-fill cadence
seam_local_send_buf	real(kind=R8P)	allocatable	Per-peer pack buffer for same-rank seams.
seam_local_recv_buf	real(kind=R8P)	allocatable	Per-peer unpack buffer for same-rank seams.
seam_comm_map_send_ghost_cell	integer(kind=I4P)	allocatable
seam_comm_map_recv_ghost_cell	integer(kind=I4P)	allocatable
seam_comm_map_send_ptr_ghost	integer(kind=I4P)	allocatable
seam_comm_map_recv_ptr_ghost	integer(kind=I4P)	allocatable
seam_mpi_send_buf	real(kind=R8P)	allocatable
seam_mpi_recv_buf	real(kind=R8P)	allocatable

Type-Bound Procedures

Name	Attributes	Description
blocks_reorder	pass(self)	Reorder blocks indexes in field.
get_block_layout	pass(self)	Return block Morton codes and/or coordinates.
initialize	pass(self)	Initialize maps.
make_comm_local_maps	pass(self)	Make communication/local maps.
make_comm_local_maps_ghost	pass(self)	Make communication/local maps of ghost cells.
make_local_maps_bc	pass(self)	Make local maps of boundary conditions.
mpi_gather_nodes_data	pass(self)	Gather nodes data between MPI processes.
save_local_map	pass(self)	Save local map.
alloc_comm_local_maps_ghost	pass(self)	Allocate communication/local maps of ghost cells.
count_bc_numbers	pass(self)	Count BC numbers.
ijk_mmd	pass(self)	Return IJK min/max/delta.
ijk_mmd_ghost	pass(self)	Return IJK min/max/delta, ghost maps.
make_comm_map_recv_ghost_cell	pass(self)	Make communication recv map of ghost cells in cell order.
make_comm_map_send_ghost_cell	pass(self)	Make communication send map of ghost cells in cell order.
make_local_map_ghost_cell	pass(self)	Make local map of ghost cells in cell order.
populate_comm_local_maps_ghost	pass(self)	Populate communication/local maps of ghost cells.

Subroutines

face_axis_sign

Translate FACE_X_MAX / FACE_X_MIN / ... into (axis 1..3, sign ±1).

Canonical decoder for the FACE_* face-direction constants. Used by the forest's seam-topology builder, by inter-realm ghost-fill paths, and by realm-side reflux TBPs that need to map a face_code onto the corresponding axis and sign.

Attributes: pure

subroutine face_axis_sign(face_code, axis, sgn)

Arguments

Name	Type	Intent	Attributes	Description
face_code	integer(kind=I4P)	in		Face code (FACE_X_MAX..FACE_Z_MIN).
axis	integer(kind=I4P)	out		1=x, 2=y, 3=z. 0 on malformed input.
sgn	integer(kind=I4P)	out		+1 if MAX, -1 if MIN. 0 on malformed input.

Call graph

blocks_reorder

Reorder blocks indexes in field.

subroutine blocks_reorder(self, tree)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).

Call graph

get_block_layout

Return block Morton codes and/or coordinates from the underlying tree. Provides a single-level accessor so callers do not traverse tree directly.

subroutine get_block_layout(self, tree, code, coordinates)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	in		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
code	integer(kind=I8P)	out	optional	Block Morton codes [blocks_number].
coordinates	integer(kind=I4P)	out	optional	Block coordinates IJKL [4,blocks_number].

Call graph

initialize

Initialize maps.

subroutine initialize(self, tree, verbose)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	inout		Tree (sibling realm component, threaded in).
verbose	logical	in	optional	Trigger verbose output.

Call graph

make_comm_local_maps

Make communication/local maps.

   comm_map_send     = [ 17, 511, 92, 3, 54, 56, 11, 12...] (block index).
                          |   |       |  ||       |
   comm_map_send_ptr = [  0,  1,  3,  4,  4, 6, (8)]        (pointer to comm_map_send)
   comm_map_recv     = [ 23, 4, 51, 69, 145, 2, 72, 16, 6]  (block index).
                         |       |  ||          |       |
   comm_map_recv_prt = [ 0,  2,  3,  3,  6, 8, (9)]         (pointer to comm_map_recv)

subroutine make_comm_local_maps(self, tree)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	inout		Tree (sibling realm component, threaded in).

Call graph

make_comm_local_maps_ghost

Make communication/local maps of ghost cells.

subroutine make_comm_local_maps_ghost(self, tree, grid, nv)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).
nv	integer(kind=I4P)	in		Number of field variables.

Call graph

mpi_gather_nodes_data

Gather nodes data status between MPI processes.

subroutine mpi_gather_nodes_data(self, tree, node_member)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
node_member	character(len=*)	in		Node member to be shared.

Call graph

save_local_map

Save local map.

subroutine save_local_map(self, file_name)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	in		The maps.
file_name	character(len=*)	in		Output file name.

make_local_maps_bc

Make local maps of boundary conditions.

subroutine make_local_maps_bc(self, tree, grid, verbose)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).
verbose	logical	in	optional	Flag to activate verbose mode.

Call graph

alloc_comm_local_maps_ghost

Allocate communication/local maps of ghost cells, local_map_ghost, comm_map_send_ghost, comm_map_recv_ghost.

subroutine alloc_comm_local_maps_ghost(self, tree, grid, nv)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).
nv	integer(kind=I4P)	in		Number of field variables.

Call graph

count_bc_numbers

Count faces/edges/corners BC numbers.

subroutine count_bc_numbers(self, tree, fec_bc_faces_number, fec_bc_edges_number, fec_bc_corners_number)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
fec_bc_faces_number	integer(kind=I4P)	out		BC faces number.
fec_bc_edges_number	integer(kind=I4P)	out		BC edges number.
fec_bc_corners_number	integer(kind=I4P)	out		BC corners number.

Call graph

make_comm_map_recv_ghost_cell

Make communication receive map of ghost cells in cell order.

Coarse->fine octant clipping (issue #21 N3.5): out-of-slab octants of the widened donor range are skipped WITHOUT advancing recv_ctr — the sender applies the identical predicate on the identical walk order, so the packed buffer holds kept octants only and positions stay in lockstep.

subroutine make_comm_map_recv_ghost_cell(self, nv, nijk, ngc)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
nv	integer(kind=I4P)	in		Number of field variables.
nijk	integer(kind=I4P)	in		Block interior cell counts [ni,nj,nk].
ngc	integer(kind=I4P)	in		Ghost cells number (octant clip bound).

Call graph

make_comm_map_send_ghost_cell

Make communication send map of ghost cells in cell order.

Column 8 (issue #21 N1) carries the packed coarse->fine interpolation metadata (octant sub-position + shifted anchor positions, see seam_meta_pack) on "sending to finer" rows; 0 elsewhere. Pack-side interpolation (G5): the donor rank owns footprint and metadata; the recv map stays a plain buffer unpack. Consumers gate on the flag column (7), never on the metadata value.

Coarse->fine octant clipping (issue #21 N3.5): the "sending to finer" ranges are in the RECEIVER's frame (fec/portion of the receiver, see populate_comm_local_maps_ghost), so the sender evaluates the receiver's fine index 2*i + delta + c and skips out-of-slab octants with the identical predicate and walk order as the receive side — buffer positions stay in lockstep without shipping discarded values.

subroutine make_comm_map_send_ghost_cell(self, nv, nijk, ngc)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
nv	integer(kind=I4P)	in		Number of field variables.
nijk	integer(kind=I4P)	in		Block interior cell counts [ni,nj,nk].
ngc	integer(kind=I4P)	in		Ghost cells number (octant clip bound).

Call graph

make_local_map_ghost_cell

Make local map of ghost cells in cell order.

Column 10 (issue #21 N1) carries the packed coarse->fine interpolation metadata (octant sub-position + shifted anchor positions, see seam_meta_pack) on "receiving from coarser" rows; 0 elsewhere. Consumers gate on the flag column (9), never on the metadata value.

Coarse->fine octant clipping (issue #21 N3.5): the widened donor range ((ngc+1)/2 coarse layers, see ijk_mmd_ghost) generates one fine octant per donor pair that falls outside the ghost slab for odd ngc; count and fill loops skip it with the same predicate (fine index within [1-ngc, nijk+ngc] per direction).

subroutine make_local_map_ghost_cell(self, nijk, ngc)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
nijk	integer(kind=I4P)	in		Block interior cell counts [ni,nj,nk].
ngc	integer(kind=I4P)	in		Ghost cells number (octant clip bound).

Call graph

dedupe_last_writer

Remove duplicate-receiver rows from a ghost-cell map, keeping the LAST row per receiver cell (issue #22 F1).

Ghost-cell maps can carry several rows writing the SAME ghost cell (overlapping face/edge/corner fec regions). The CPU consumers process rows sequentially, so the last writer wins deterministically; the GPU consumers execute rows under !$acc parallel loop independent, so duplicate writers RACE. On uniform grids the duplicates agree in value (benign); at a 2:1 coarse-fine seam they disagree (different donors/levels) — observed as run-to-run nondeterministic seam divergences on FNL. Making last-writer-wins explicit at build time removes the race structurally: CPU results are bit-identical (that row was winning anyway), GPU becomes deterministic and CPU-equal, and both backends do less work. Rows for one receiver cell always appear as CONTIGUOUS runs of stride rows (stride = 1 for the cell-level local map, nv for the per-variable MPI recv map, whose do v=1,nv loop is innermost in every build branch) — so the survivor test is last_row(cell) - row < stride, and the winner table is keyed on the CELL only (no nv factor in its size).

subroutine dedupe_last_writer(map, cb, ci, cj, ck, stride, ngc)

Arguments

Name	Type	Intent	Attributes	Description
map	integer(kind=I8P)	inout	allocatable	Ghost-cell map (rows compacted in place).
cb	integer(kind=I4P)	in		Column of the receiver block index.
ci	integer(kind=I4P)	in		Column of the receiver i index.
cj	integer(kind=I4P)	in		Column of the receiver j index.
ck	integer(kind=I4P)	in		Column of the receiver k index.
stride	integer(kind=I4P)	in		Rows per receiver cell (1 = cell-level map, nv = per-variable map).
ngc	integer(kind=I4P)	in		Ghost cells number (index offset for the key).

Call graph

populate_comm_local_maps_ghost

Populate communication/local maps of ghost cells, local_map_ghost, comm_map_send_ghost, comm_map_recv_ghost.

subroutine populate_comm_local_maps_ghost(self, tree, grid)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	inout		The maps.
tree	type(tree_object)	in		Tree (sibling realm component, threaded in).
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).

Call graph

populate_local_map_bc_crown

Populate map of BC cells in crown order.

subroutine populate_local_map_bc_crown(local_map_bc, local_map_bc_crown, c_crown)

Arguments

Name	Type	Intent	Attributes	Description
local_map_bc	integer(kind=I8P)	in		Local map for BC ghost cells.
local_map_bc_crown	integer(kind=I8P)	inout		Local map for face BC ghost cells, crown order.
c_crown	integer(kind=I4P)	inout		Counter.

Call graph

set_local_map_bc

Set data into faces/edges/corners local map BC.

subroutine set_local_map_bc(fec, block_index, neighbor_bc_fec, ijk_min_max_delta, fec_bc_type, local_map_bc)

Arguments

Name	Type	Intent	Attributes	Description
fec	integer(kind=I4P)	in		Current fec.
block_index	integer(kind=I8P)	in		Block index in field blocks array.
neighbor_bc_fec	integer(kind=I8P)	in		Neighbors fec for BC.
ijk_min_max_delta	integer(kind=I8P)	in		IJK min/max/delta.
fec_bc_type	integer(kind=I8P)	in		BC type.
local_map_bc	integer(kind=I8P)	inout		Local map BC data.

Call graph

Functions

ijk_mmd

Return IJK min/max/delta.

Returns: integer(kind=I8P)

function ijk_mmd(self, grid, fec, neighbor_bc_fec) result(ijk_min_max_delta)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	in		The maps.
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).
fec	integer(kind=I4P)	in		Current fec number.
neighbor_bc_fec	integer(kind=I4P)	in		Neighbors fec for BC.

Call graph

ijk_mmd_ghost

Return IJK min/max/delta, ghost maps.

Returns: integer(kind=I8P)

function ijk_mmd_ghost(self, grid, fec, portion) result(ijk_min_max_delta)

Arguments

Name	Type	Intent	Attributes	Description
self	class(maps_object)	in		The maps.
grid	type(grid_object)	in		Grid (sibling realm component, threaded in).
fec	integer(kind=I4P)	in		Current fec number.
portion	integer(kind=I8P)	in		Current portion.

Call graph

bc_cells_number

Return BC cells number.

Returns: integer(kind=I4P)

function bc_cells_number(local_map_bc) result(cells_number)

Arguments

Name	Type	Intent	Attributes	Description
local_map_bc	integer(kind=I8P)	in		Local map for BC ghost cells.

Call graph