adam_forest_manifest

ADAM, forest manifest parser — reads forest.ini into a transient struct.

A forest manifest is the small INI that lists the realms making up a forest and how they couple. This module reads such a manifest and returns the data the driver needs to allocate the realm array and the topology data the forest needs to populate per-realm maps%inter_realm_neighbors after each realm has been initialized.

See docs/guide/forest.md for the conceptual overview of the multi-realm machinery and src/lib/common/README.md → "Forest orchestration" for the library-developer contract surface.

Manifest shape:

   [forest]
   realms_number = 2

   [realm.1]
   ini = realm_1.ini       ; path relative to forest.ini's directory

   [realm.2]
   ini = realm_2.ini

   [forest.topology]
   inter_realm_faces_number = 1

   [forest.topology.face_1]
   realm_a          = 1
   face_a           = +x
   realm_b          = 2
   face_b           = -x
   coupling         = mirror             ; mirror | periodic | interpolate
   coupling_cadence = end_of_step        ; end_of_step (α default) | stage_coincident (β opt-in)

Single-INI detection: callers MUST check whether the file actually IS a manifest before invoking this parser — a plain PRISM input.ini has no [forest] section and is_forest_manifest returns .false. without loading any state. This lets the driver short-circuit to the legacy single-INI path.

Architectural invariants:

• No singletons read. This module is a pure data-transform on a file path; it does not touch mpih, grid, or any other program-scope state. That keeps the manifest parser callable BEFORE any of those singletons have been initialized.
• No realm-typed components. The forest_manifest_t struct carries only intrinsic-typed components — realm paths as character strings, face/coupling codes as integers. The realm objects themselves are allocated by the driver from realms_number; the topology entries are translated to inter_realm_neighbor_t instances on the realm-side by forest_object%populate_inter_realm_topology.

Source: src/lib/common/adam_forest_manifest.F90

Dependencies

Contents

• forest_face_pair_t
• forest_manifest_t
• read_forest_manifest
• read_face_pair
• is_forest_manifest
• parse_face
• parse_coupling
• parse_cadence

Variables

Name	Type	Attributes	Description
MAX_INI_PATH_LEN	integer(kind=I4P)	parameter	Buffer length for realm INI paths.

Derived Types

forest_face_pair_t

One inter-realm face coupling as parsed from a [forest.topology.face_<n>] block.

The struct is symmetric: both realms know about the same coupling. Later (during forest%initialize) each realm's maps%inter_realm_neighbors is populated with TWO inter_realm_neighbor_t entries per face pair — one from realm_a's perspective and one from realm_b's perspective.

Components

Name	Type	Attributes	Description
realm_a	integer(kind=I4P)		First realm in the pair (1-based).
face_a	integer(kind=I4P)		Face code on realm_a (FACE_X_MAX..FACE_Z_MIN).
realm_b	integer(kind=I4P)		Second realm in the pair.
face_b	integer(kind=I4P)		Face code on realm_b.
coupling	integer(kind=I4P)		Coupling kind (default MIRROR for the first use case).
coupling_cadence	integer(kind=I4P)		Seam-fill cadence (α default, β opt-in).

forest_manifest_t

Parsed contents of a forest.ini manifest.

Transient data structure: built by read_forest_manifest, consumed once by the driver (to allocate realm(:)) and the forest (to wire inter-realm topology), then discarded. NOT stored as a long-lived component on forest_object (which is behavior-only by design).

Components

Name	Type	Attributes	Description
realms_number	integer(kind=I4P)		Number of realms in the forest.
realm_ini	character(len=MAX_INI_PATH_LEN)	allocatable	Per-realm INI path (1:realms_number).
face_pairs	type(forest_face_pair_t)	allocatable	Inter-realm couplings; unallocated when none declared.

Subroutines

read_forest_manifest

Parse a forest manifest INI into manifest.

Caller is responsible for confirming the file IS a manifest via is_forest_manifest first; this routine error-stops on any malformed or missing required entry (so a caller that gets here trusts the parse to succeed).

subroutine read_forest_manifest(filename, manifest)

Arguments

Name	Type	Intent	Attributes	Description
filename	character(len=*)	in		Path to the manifest INI.
manifest	type(forest_manifest_t)	out		Parsed result.

Call graph

read_face_pair

Read one [forest.topology.face_<n>] section into a face-pair struct.

subroutine read_face_pair(handle, section_name, pair, context)

Arguments

Name	Type	Intent	Attributes	Description
handle	type(file_ini)	inout		FiNeR handle.
section_name	character(len=*)	in		Section name to read from.
pair	type(forest_face_pair_t)	out		Parsed face pair.
context	character(len=*)	in		Caller's filename for error messages.

Call graph

Functions

is_forest_manifest

Return .true. iff the file is recognizable as a forest manifest.

Detection rule: the file loads successfully via FiNeR AND contains a [forest] realms_number = N entry with N >= 1. A plain PRISM input.ini has no [forest] section and returns .false. — the driver then falls back to the legacy single-INI path.

Returns: logical

function is_forest_manifest(filename) result(yes)

Arguments

Name	Type	Intent	Attributes	Description
filename	character(len=*)	in		Path to test.

Call graph

parse_face

Translate "+x" / "-x" / "+y" / "-y" / "+z" / "-z" to the face code constant.

Returns: integer(kind=I4P)

function parse_face(text, section_name, context) result(code)

Arguments

Name	Type	Intent	Attributes	Description
text	character(len=*)	in		Face spec from the INI.
section_name	character(len=*)	in		Section name (for error message).
context	character(len=*)	in		Manifest filename (for error message).

Call graph

parse_coupling

Translate "mirror" / "periodic" / "interpolate" to the coupling code constant.

Returns: integer(kind=I4P)

function parse_coupling(text, section_name, context) result(code)

Arguments

Name	Type	Intent	Attributes	Description
text	character(len=*)	in		Coupling spec from the INI.
section_name	character(len=*)	in		Section name (for error message).
context	character(len=*)	in		Manifest filename (for error message).

Call graph

parse_cadence

Translate "end_of_step" / "stage_coincident" to the cadence code constant.

Returns: integer(kind=I4P)

function parse_cadence(text, section_name, context) result(code)

Arguments

Name	Type	Intent	Attributes	Description
text	character(len=*)	in		Cadence spec from the INI.
section_name	character(len=*)	in		Section name (for error message).
context	character(len=*)	in		Manifest filename (for error message).

Call graph