Restructure the undo-attenuation adjoint solver for readability

[Rohit-Kakodkar]

What this is

A readability-only pass over the UNDO_ATTENUATION adjoint solver. The algorithm is unchanged — this is about how it reads.

Based on undo-att/checkpoint3, not main, since the whole undo-attenuation feature is unmerged.

Why

combined_undoatt.tpp had a few things working against it:

• run() defined nine nested lambdas across ~100 lines before the ~40 lines of control flow that used them.
• The recursion went through std::function<void(int,int,int,int)> — four unnamed ints, so reverse_interval(start + left_length, end, available - 1, split_slot) was unreadable.
• base_slot == -1 was a magic sentinel meaning "reload from disk".
• Manual slot lifecycle across two parallel vectors (slots + free_slots).
• The 13-view attenuation list was written out four times, each with its own dim2/dim3 if constexpr.
• restore_attenuation_memory(medium, snapshot) wrote the medium; update_attenuation_snapshot(medium, snapshot) wrote the snapshot — near-identical signatures, opposite data direction.
• Overlapping vocabulary (subset, window, leaf, interval, slot, buffer, subdivision) never defined in one place, and a header comment describing a flat three-phase algorithm that the code stopped being some time ago.

What changed

combined_undoatt.tpp goes 537 → 143 lines and now reads straight down: validate config → build schedule → mass matrices → allocate buffer → reset adjoint attenuation → init tasks → loop windows backward → finalize.

Two concepts extracted into core/specfem/solver/impl/:

attenuation_snapshot.hpp — the view list lives in exactly one constexpr tuple of pointer-to-member pairs, which drives allocation, both copy directions, and zero-fill. A new memory variable is now a one-line registration. AttenuationState replaces the confusable pair with restore_into / refresh_from: the snapshot is always the subject, the preposition gives the direction.

checkpointed_replay.hpp / .tpp — carries the glossary (checkpoint / window / segment / leaf / retained snapshot) and turns every lambda into a named, documented member of CheckpointedReplay. The recursion is a real recursive member taking a StepRange and a ReplayOrigin. Because the origin carries its own step, an invariant that used to be implicit — a replay always resumes at exactly the step its origin describes — is now structural.

The slot pool is deleted, not reorganised. available always equals free_slots.size() and acquisition is strictly LIFO, so split_slot was always available - 1 — the recursion's own call stack does the job. Both vectors and the -1 sentinel collapse into a scoped local, released at exactly the point slots[split_slot].reset() released it. Peak resident snapshots is unchanged (= recursion depth).

Also dropped: the revolve naming. It alluded to Griewank–Walther REVOLVE, but this is a simple recursive binary split driven by wavefield_checkpoint::split(), so the word implied an algorithm that isn't there.

Verification

Kernels are bit-identical to the pre-refactor code, byte for byte, at subdivide-buffer 1–5 on the dim3 homogeneous_viscoelastic_kernel benchmark — 45 .npy files. That covers the flat path (1), the even split (2), the uneven short-leaf-first path (3: buffer_steps=67, split=66) and deeper recursion (4, 5).

Also: clean build of all three explicit instantiations (dim2/NGLL 5, dim2/NGLL 8, dim3/NGLL 5) with no warnings; 7/7 WavefieldCheckpoint tests passing; clang-format clean.

Two things worth knowing

1. The benchmark default never exercises the recursion. subdivide-buffer: 1 with nstep 800 / time-interval 200 gives checkpoint_slots(200) == 0, so every window takes the flat branch. An A/B at defaults would pass with the recursion completely broken — use ≥ 2.
2. Kernels are not bit-identical across different subdivide-buffer values — ~1e-7 relative at 1 vs 2, down to ~1e-12 by 5. That is float32 roundoff, not a bug: a forward state reloaded from an NPY disk checkpoint differs in its last bits from one retained in memory. Pre-existing and unaffected by this PR, but it means A/B comparisons must be same-subdivision.

Not included

No new tests. The recursion still has no automated coverage — verification rests on the benchmark A/B. The CheckpointedReplay shape leaves room to later template the schedule walk on an actions policy and pin its call sequence with a recording mock, but that changes a type signature and doesn't belong in a behavior-preserving pass.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Refactors the attenuating adjoint time-marching path by extracting checkpoint-replay + attenuation snapshotting into reusable implementation helpers.

Changes:

• Replace in-file combined_undoatt replay/snapshot logic with specfem::solver::impl::CheckpointedReplay.
• Introduce AttenuationState snapshot/reset utilities to manage attenuation memory variables consistently across dims.
• Add new replay driver (checkpointed_replay.{hpp,tpp}) to handle window/segment/leaf reconstruction and kernel accumulation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
core/specfem/solver/time_marching/combined_undoatt.tpp	Simplifies combined_undoatt run() by delegating replay to a new helper and using shared attenuation reset.
core/specfem/solver/impl/checkpointed_replay.hpp	Adds the replay driver public API + supporting types (StepRange, snapshots, origins).
core/specfem/solver/impl/checkpointed_replay.tpp	Implements recursive replay/leaf buffering and the adjoint correlation loop.
core/specfem/solver/impl/attenuation_snapshot.hpp	Adds attenuation snapshot/capture/restore/refresh and a reset helper.

---

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