1946 - Reduced memory usage option

[icui]

Overview

This PR improves undo-attenuation checkpoint replay and separates checkpoint
loading from ordinary periodic tasks.

• Renames the replay scheduler to wavefield_checkpoint.
• Passes the checkpoint reader explicitly to the undo-attenuation solver
  instead of discovering and filtering it from the periodic-task vector.
• Adds configurable in-memory replay subdivision through
  checkpointing.subdivide-buffer.
• Retains full forward state at subdivision boundaries, allowing smaller
  displacement buffers in exchange for additional forward replay.

Benchmark results

The 3D homogeneous viscoelastic-kernel benchmark was run with an 800-step
simulation and a 400-step disk-checkpoint interval.

subdivide-buffer	Buffer steps	In-memory checkpoints	Forward steps	Solver time	Peak RSS
1	400	0	800	95.23 s	2.79 GiB
3	134	2	1,332	119.27 s	2.10 GiB

Using three subdivisions reduced peak RSS by 24.6% (approximately
0.69 GiB) while increasing solver time by 25.2%. The previous run with
a 200-step checkpoint interval and subdivide-buffer: 1 took 94.08 seconds,
so increasing the interval to 400 without subdivision had little timing
impact.

Each configuration was run once using the release/serial build on an Apple M4
with macOS 26.5.2, so timings should be treated as indicative.

Numerical validation

• Kernel coordinates X, Y, and Z are bitwise identical between replay
  strategies.
• The worst relative L2 kernel difference is 1.04e-8.
• The worst absolute kernel difference is 8.67e-19.

These differences are consistent with floating-point ordering effects from the
alternative replay schedule.

Validation

• The release solver build passes.
• All seven WavefieldCheckpoint unit tests pass.
• Both benchmark configurations complete successfully.
• clang-format and git diff --check pass.

[Copilot]

Pull request overview

This PR adds a configurable “reduced memory usage” mode for combined undo-attenuation by subdividing each disk-checkpoint replay window into smaller in-memory displacement buffers, trading extra forward replay for lower peak RAM.

Changes:

• Extend wavefield_checkpoint to compute a subdivided replay schedule (leaf size, internal full-state checkpoint count, replay split point, forward-step cost).
• Rework combined undo-attenuation replay to use explicit checkpoint reader injection and the new subdivision schedule.
• Add YAML configuration and documentation for solver.time-marching.checkpointing.subdivide-buffer, plus new unit tests for the schedule logic.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit-tests/periodic_tasks/wavefield_checkpoint.cpp	Adds unit tests covering subdivided replay schedule calculations and invalid subdivision handling.
core/specfem/solver/time_marching/combined_undoatt.tpp	Implements subdivided replay with optional in-memory full-state checkpoints and leaf buffering.
core/specfem/solver/time_marching.hpp	Adds a checkpoint_buffer_subdivisions parameter to combined undo-attenuation time marching.
core/specfem/runtime_configuration/solver.tpp	Passes configured buffer subdivision count into the combined solver instantiation.
core/specfem/runtime_configuration/solver.hpp	Parses optional checkpointing.subdivide-buffer from YAML and stores the configuration.
core/specfem/runtime_configuration/setup.cpp	Switches setup to construct the solver with the simulation type enum and time-marching YAML node.
core/specfem/periodic_tasks/wavefield_checkpoint.hpp	Extends the replay task to support subdivided buffering and internal checkpoint slot computations.
benchmarks/src/dim3/homogeneous_viscoelastic_kernel/README.md	Documents the new checkpointing.subdivide-buffer option and its semantics.
benchmarks/src/dim3/homogeneous_viscoelastic_kernel/CMakeFiles/adjoint_config.yaml.in	Adds default checkpointing.subdivide-buffer: 1 to adjoint benchmark config.
benchmarks/src/dim3/homogeneous_viscoelastic_kernel/CMakeFiles/adjoint_config_mpi.yaml.in	Adds default checkpointing.subdivide-buffer: 1 to MPI adjoint benchmark config.
architecture/core-components/io.md	Updates I/O architecture docs to mention subdivided replay windows.
architecture.md	Updates top-level architecture docs to mention subdivided replay windows.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.