solver_runtime Module

Solver execution lifecycle and I/O orchestration.

This module centralises the solver lifecycle behind the thin app/euler_1d.f90 program: CLI parsing, config loading, solver-state initialisation, adaptive-dt time loop, checkpoint/restart, live snapshots, iteration logging, and performance reporting.

Typical call sequence:

  call resolve_cli_namelist(ctx % nml_file)
  call read_config(ctx % nml_file, cfg)
  call initialize_runtime(ctx, cfg, ctx % nml_file)
  call run_solver(ctx)
  call finalize_runtime(ctx)
  call teardown_runtime(ctx)

Uses


Derived Types

type, public, extends(run_loop_ctx_t) ::  solver_run_context_t

Aggregate context bundling all state needed for a single solver run.

Read more…

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(solver_state_t), public :: state
type(timer_t), public :: t_total
type(timer_t), public :: t_io
type(timer_t), public :: t_iter
integer, public :: print_freq = 50
character(len=512), public :: nml_file = 'input.nml'
procedure(stepper_iface), public, pointer, nopass :: stepper => null()
logical, public :: timers_started = .false.
logical, public :: performance_reported = .false.

Type-Bound Procedures

procedure, public :: observe => hook_noop
procedure, public :: raw_dt => ctx1d_raw_dt
procedure, public :: set_dt => ctx1d_set_dt
procedure, public :: step => ctx1d_step
procedure, public :: write_checkpoint_now => ctx1d_checkpoint
procedure, public :: log_iteration_line => ctx1d_log_line
procedure, public :: begin_work => ctx1d_begin_work
procedure, public :: write_snapshot_now => ctx1d_snapshot
procedure, public :: finish_work => ctx1d_finish_work
procedure, public :: progress_residual => ctx1d_progress_residual

Functions

private function ctx1d_raw_dt(ctx) result(dt)

1D raw_dt hook: recompute state % dt from the CFL condition when CFL-driven, then return the stored dt (Q2c; body lifted verbatim from the pre-engine run_solver_steps loop).

Arguments

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

Return Value real(kind=wp)

private function ctx1d_progress_residual(ctx) result(r)

1D progress_residual hook: state residual norm for progress ticks.

Arguments

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

Return Value real(kind=wp)


Subroutines

public subroutine resolve_cli_namelist(nml_file)

Read the namelist filename from the first command-line argument. Falls back to 'input.nml' when no argument is supplied.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(out) :: nml_file

On return: path to the namelist file.

public subroutine resolve_cli(nml_file, cortex_uri, attached)

Parse the worker's CLI: --cortex-socket=URI plus a positional namelist path. Either may be absent. or empty.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(out) :: nml_file

On return: namelist path (defaults to 'input.nml').
character(len=*), intent(out) :: cortex_uri

On return: namelist path (defaults to 'input.nml'). On return: URI string if --cortex-socket was given,
logical, intent(out) :: attached

On return: .true. iff --cortex-socket was given.

public pure subroutine consume_cli_arg(arg, arg_len, nml_file, cortex_uri, attached)

Dispatch one parsed CLI token onto the worker-CLI state.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: arg

The argument buffer as filled by get_command_argument.
integer, intent(in) :: arg_len

The argument's reported TRUE length (may exceed
character(len=*), intent(inout) :: nml_file

Updated in place with a positional namelist path.
character(len=*), intent(inout) :: cortex_uri

Updated in place with a positional namelist path. Updated in place with a --cortex-socket= value.
logical, intent(inout) :: attached

Set .true. iff a --cortex-socket= token was seen.

public subroutine initialize_runtime(ctx, cfg, nml_file, is_ok, message)

Populate ctx and bring the solver to a ready-to-run state.

Read more…

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Context to initialise.
type(config_t), intent(in) :: cfg

Configuration loaded via read_config.
character(len=*), intent(in), optional :: nml_file

Optional namelist path stored in ctx % nml_file.
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message

public subroutine run_solver(ctx, on_progress, every_steps, every_seconds)

Execute the main time-marching loop until time_stop is reached.

Read more…

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Solver context; ctx % t and ctx % iter are updated in place.
procedure(progress_callback_i), optional :: on_progress
integer, intent(in), optional :: every_steps
real(kind=wp), intent(in), optional :: every_seconds

public subroutine run_solver_steps(ctx, max_steps, steps_taken, finished, is_ok, message, on_progress, every_steps, every_seconds)

Advance the main time loop by at most max_steps iterations.

Read more…

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx
integer, intent(in) :: max_steps
integer, intent(out) :: steps_taken
logical, intent(out) :: finished
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message
procedure(progress_callback_i), optional :: on_progress
integer, intent(in), optional :: every_steps
real(kind=wp), intent(in), optional :: every_seconds

private subroutine ctx1d_set_dt(ctx, dt)

1D set_dt hook: store the engine's clipped dt.

Arguments

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

private subroutine ctx1d_step(ctx)

1D step hook: advance one step, wrapped in the per-iteration timer.

Arguments

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

private subroutine ctx1d_checkpoint(ctx)

1D write_checkpoint_now hook: write the checkpoint and own the failure policy.

Arguments

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

private subroutine ctx1d_log_line(ctx)

1D log_iteration_line hook: one iteration summary line.

Arguments

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

private subroutine ctx1d_begin_work(ctx)

1D begin_work hook: start total wall-time accounting only when real work is about to begin, so a zero-step polling call does not consume elapsed time.

Arguments

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

private subroutine ctx1d_snapshot(ctx)

1D write_snapshot_now hook: live snapshot side channel.

Arguments

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

private subroutine ctx1d_finish_work(ctx)

1D finish_work hook: stop the total timer once the run finishes.

Arguments

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

public subroutine finalize_runtime(ctx)

Write the final solution to the output file and print the performance table.

Read more…

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Solver context (solution written from ctx % state % ub).

public subroutine report_performance_summary(ctx)

Print the end-of-run performance table once after a completed run.

Read more…

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Solver context (read-only except for the once-only guard flag).

public subroutine teardown_runtime(ctx)

Release all allocations held by ctx and finalise the logger. Must be the last call in the lifecycle; ctx is invalid afterwards.

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Solver context to tear down.

public subroutine write_solution_file(ctx, filename, is_ok, message)

Write the current solution to a text file.

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(inout) :: ctx

Solver context (solution written from ctx % state % ub).
character(len=*), intent(in) :: filename

Output path to overwrite.
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message

public subroutine copy_current_solution(ctx, x, rho, u, p, is_ok, message)

Copy the current solution into primitive-variable arrays.

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(in) :: ctx

Solver context (read-only).
real(kind=wp), intent(out) :: x(:)
real(kind=wp), intent(out) :: rho(:)
real(kind=wp), intent(out) :: u(:)
real(kind=wp), intent(out) :: p(:)
logical, intent(out), optional :: is_ok
character(len=*), intent(out), optional :: message

private subroutine log_iteration(ctx)

Log one iteration summary line (time, residual, per-iteration and elapsed wall time). The lightweight iter_s and elapsed_s fields are always populated. Called every ctx % print_freq iterations and once unconditionally after the loop.

Arguments

Type IntentOptional Attributes Name
class(solver_run_context_t), intent(in) :: ctx

Solver context (read-only).

private subroutine log_performance_summary(ctx)

Print the wall-clock performance table after the run completes. Reports total time, I/O time, and the three hot-path timers (compute_resid, flux precompute, face loop) plus overall throughput. Only called when ctx % state % cfg % do_timing is .true..

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(in) :: ctx

Solver context (read-only).

private subroutine write_snapshot(ctx)

Write a live snapshot of the current solution to snapshot_file. The file is overwritten on each call. A header comment records the current iteration and time; subsequent rows are (x, ρ, u, p) in '(4ES20.12)' format. Open/write failures are logged as warnings rather than fatal errors so that a snapshot glitch does not abort the run. This file path is retained for compatibility with legacy file-watching tooling; new integrations should prefer the polling session/API surface.

Arguments

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

Solver context (gather_buf is updated; all other fields are read-only).

private subroutine log_effective_config(ctx)

Log the effective (post-promotion) configuration at startup. Reads from the authoritative copy ctx % state % cfg, which may differ from the original namelist values when BC promotions have been applied (e.g. smooth_wave → periodic, woodward_colella → reflecting).

Arguments

Type IntentOptional Attributes Name
type(solver_run_context_t), intent(in) :: ctx

Solver context (read-only).