checkpoint_io Module

Unified on-disk format (current version: ckpt_version below): every dim writes magic(42), version(ckpt_version), dim | iter, t, extents(1:dim), neq, dt | grid_type(char32), fingerprint(2) | payload arrays (dim-specific). The dim field makes files self-identifying; cross-dim restarts are rejected with a clear error. Legacy formats (1D v2/v3, 2D magic-4242 v1) are NOT readable — rejected by the magic/version checks (owner-authorized break; no user-generated checkpoints exist).

MPI: agree_outcome/conclude_read wrap the collective par_lor decision points. Callers own the collective SEQUENCE — every rank must reach each call site uniformly.


Uses


Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: ckpt_magic = 42
integer, public, parameter :: ckpt_version = 6

Unified multi-dim format version. v5 (F2) adds two 1D-only trailing records after the (unchanged) v4 body — the Kahan t_comp compensation scalar and the boundary halo/ghost cells (see checkpoint.f90's module header) — so 1D files grow by those two records. 2D's on-disk content is byte-for-byte unchanged by this bump (checkpoint_2d.f90 gains no new fields); only the shared header's version number advances, since ckpt_version is one constant for both dims. v6 (Q2d) leaves 1D's record list UNCHANGED (fresh 1D files simply stamp v6) and adds 2D-only trailing records after the global solution array — the Kahan t_comp compensation scalar, the halo width h (validated on read), and the four global boundary-ghost-frame bands gh_l/gh_r/gh_b/gh_t — the 2D analogues of 1D's v5 records (see checkpoint_2d.f90's module header for the layout and the ghost-history rationale). Either way, legacy v4 files and now also v5 files (1D or 2D) are NOT readable — read_ckpt_header's strict version-equality check rejects them (owner-authorized break, third in the v4→v5→v6 series; no user-generated checkpoints exist).

Functions

public function ckpt_filename(base, iter) result(fname)

'_.bin' (width-agnostic I0 — never overflows the field).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: base
integer, intent(in) :: iter

Return Value character(len=512)

public function resolve_latest_pointer(pointer_file, fname, prefix, is_ok, message) result(actual)

If fname names the pointer file, read the real path from it; otherwise return fname unchanged. Detects >512-char truncation explicitly.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: pointer_file
character(len=*), intent(in) :: fname
character(len=*), intent(in) :: prefix
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message

Return Value character(len=512)

public function agree_outcome(local_ok, fail_text, is_ok, message) result(failed)

Collective outcome agreement (write-side): failed = any rank not ok. On failure the optional status pair gets fail_text; on SUCCESS the pair is left exactly as the caller preset it — hence intent(inout), NOT intent(out) (which would leave the caller's values undefined on the success path). COLLECTIVE — every rank must call.

Arguments

Type IntentOptional Attributes Name
logical, intent(in) :: local_ok
character(len=*), intent(in) :: fail_text
logical, intent(inout), optional :: is_ok
character(len=*), intent(inout), optional :: message

Return Value logical

public function conclude_read(local_ok, err, generic_text, is_ok, message) result(failed)

Shared read epilogue: ONE collective decision point (the only par_lor of the read path's conclusion); returns the agreed failure flag so callers write if (conclude_read(...)) return. The failing rank reports its own err, other ranks the generic text; error-stop fallback when the caller passed no status arguments. COLLECTIVE — every rank must call. Status pair semantics as in agree_outcome: assigned only on failure, caller presets preserved on success (intent(inout)).

Arguments

Type IntentOptional Attributes Name
logical, intent(in) :: local_ok
character(len=*), intent(in) :: err
character(len=*), intent(in) :: generic_text
logical, intent(inout), optional :: is_ok
character(len=*), intent(inout), optional :: message

Return Value logical


Subroutines

public subroutine update_latest_pointer(pointer_file, fname, prefix, is_ok, message)

Write the most-recent checkpoint path to the pointer file (rank 0 only — the caller gates on rank).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: pointer_file
character(len=*), intent(in) :: fname
character(len=*), intent(in) :: prefix
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message

public subroutine write_ckpt_header(u, dim, iter, t, extents, neq, dt, info)

Write the unified header (magic/ckpt_version/dim) + scalars. extents carries the dim global extents (1D: [n_pt_global]; 2D: [nx_global, ny_global]).

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: u
integer, intent(in) :: dim
integer, intent(in) :: iter
real(kind=wp), intent(in) :: t
integer, intent(in) :: extents(:)
integer, intent(in) :: neq
real(kind=wp), intent(in) :: dt
integer, intent(out) :: info

public subroutine read_ckpt_header(u, prefix, expected_dim, expected_extents, expected_neq, iter, t, dt, ok, err)

Read + validate the unified header against the caller's expectations. On any failure ok=.false. and err carries ': '.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: u
character(len=*), intent(in) :: prefix
integer, intent(in) :: expected_dim
integer, intent(in) :: expected_extents(:)
integer, intent(in) :: expected_neq
integer, intent(out) :: iter
real(kind=wp), intent(out) :: t
real(kind=wp), intent(out) :: dt
logical, intent(out) :: ok
character(len=*), intent(out) :: err

public subroutine write_grid_record(u, grid_type, fp, info)

Write the grid record: grid_type token + 2-component fingerprint.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: u
character(len=32), intent(in) :: grid_type
real(kind=wp), intent(in) :: fp(2)
integer, intent(out) :: info

public subroutine read_grid_record_and_check(u, prefix, grid_type, cur_fp, ok, err)

Read the grid record and compare against the configured grid using the historical 1e-12 relative tolerance.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: u
character(len=*), intent(in) :: prefix
character(len=32), intent(in) :: grid_type
real(kind=wp), intent(in) :: cur_fp(2)
logical, intent(out) :: ok
character(len=*), intent(out) :: err