run_step_engine Module

Owns the loop skeleton both solver runtimes share: max_steps/time_stop/ max_iter exits, the time_stop dt clip, Kahan-compensated time accumulation (F2/Q2b grouping — load-bearing, do not re-associate), iteration counters, checkpoint/print/snapshot cadences, the final "odd" log line, the run_complete latch, and the optional wall-clock progress tick. Everything dimension-specific arrives through run_loop_ctx_t type-bound hooks.

Ordering contract (byte-for-bit load-bearing): begin_work -> raw_dt -> clip/set_dt -> step -> Kahan -> counters -> observe -> log(print cadence) -> checkpoint -> snapshot -> [bottom max_iter exit] -> tick. The max_iter_top_check flag preserves the dims' historical exit positions (2D checks before stepping, 1D after the side effects, before the tick).


Uses


Abstract Interfaces

abstract interface

  • private function hook_dt_i(ctx) result(dt)

    Arguments

    Type IntentOptional Attributes Name
    class(run_loop_ctx_t), intent(inout) :: ctx

    Return Value real(kind=wp)

abstract interface

  • private subroutine hook_set_dt_i(ctx, dt)

    Arguments

    Type IntentOptional Attributes Name
    class(run_loop_ctx_t), intent(inout) :: ctx
    real(kind=wp), intent(in) :: dt

abstract interface

  • private subroutine hook_void_i(ctx)

    Arguments

    Type IntentOptional Attributes Name
    class(run_loop_ctx_t), intent(inout) :: ctx

abstract interface

  • public subroutine progress_callback_i(iter, sim_time, dt, residual, wallclock_s)

    Cooperative progress-tick callback signature (moved verbatim from solver_runtime; re-exported there so existing consumers are unaffected).

    Bound by adapters that want lightweight per-iteration progress updates from inside the bounded step loop. Called every every_steps iterations or every every_seconds wall-clock seconds, whichever comes first. Behaviour is purely advisory: returning has no effect on the solver beyond the callback's own side effects.

    Arguments

    Type IntentOptional Attributes Name
    integer, intent(in) :: iter
    real(kind=wp), intent(in) :: sim_time
    real(kind=wp), intent(in) :: dt
    real(kind=wp), intent(in) :: residual
    real(kind=wp), intent(in) :: wallclock_s

Derived Types

type, public, abstract ::  run_loop_ctx_t

Shared run bookkeeping + per-dim hooks. Extended by solver_run_context_t (1D) and solver_run_context_2d_t (2D); the concrete fields keep their historical names so ctx % t-style access throughout the codebase is unchanged.

Components

Type Visibility Attributes Name Initial
real(kind=wp), public :: t = 0.0_wp
real(kind=wp), public :: t_comp = 0.0_wp
integer, public :: iter = 0
logical, public :: run_complete = .false.

Type-Bound Procedures

procedure(hook_dt_i), public, deferred :: raw_dt
procedure(hook_set_dt_i), public, deferred :: set_dt
procedure(hook_void_i), public, deferred :: step
procedure(hook_void_i), public, deferred :: write_checkpoint_now
procedure(hook_void_i), public, deferred :: log_iteration_line
procedure, public :: begin_work => hook_noop
procedure, public :: observe => hook_noop
procedure, public :: write_snapshot_now => hook_noop
procedure, public :: finish_work => hook_noop
procedure, public :: progress_residual => hook_zero

(it is referenced inside the on_progress argument list).

Functions

private function hook_zero(ctx) result(r)

Default zero-residual hook body for progress_residual.

Arguments

Type IntentOptional Attributes Name
class(run_loop_ctx_t), intent(inout) :: ctx

Return Value real(kind=wp)

public pure function tick_seconds(delta, rate) result(s)

Convert a system_clock delta to seconds.

Read more…

Arguments

Type IntentOptional Attributes Name
integer(kind=int64), intent(in) :: delta

Clock-count difference (may be negative on wrap-around).
integer(kind=int64), intent(in) :: rate

Ticks per second from system_clock count_rate.

Return Value real(kind=wp)


Subroutines

private subroutine hook_noop(ctx)

Default no-op hook body for the overridable bindings.

Arguments

Type IntentOptional Attributes Name
class(run_loop_ctx_t), intent(inout) :: ctx

public subroutine run_bounded_steps(ctx, max_steps, steps_taken, finished, time_stop, max_iter, checkpoint_freq, print_freq, snapshot_freq, max_iter_top_check, on_progress, every_steps, every_seconds)

Advance ctx by at most max_steps iterations (see module header for the ordering contract). All cadence/exit arithmetic that was duplicated between the per-dim loops lives here and only here. Hooks must not mutate the cfg fields passed as cadence arguments (time_stop, max_iter, checkpoint_freq/print_freq/snapshot_freq are snapshotted at call time and alias the ctx).

Arguments

Type IntentOptional Attributes Name
class(run_loop_ctx_t), intent(inout) :: ctx
integer, intent(in) :: max_steps
integer, intent(out) :: steps_taken
logical, intent(out) :: finished
real(kind=wp), intent(in) :: time_stop
integer, intent(in) :: max_iter
integer, intent(in) :: checkpoint_freq
integer, intent(in) :: print_freq
integer, intent(in) :: snapshot_freq
logical, intent(in) :: max_iter_top_check
procedure(progress_callback_i), optional :: on_progress
integer, intent(in), optional :: every_steps
real(kind=wp), intent(in), optional :: every_seconds