Documentation Quality Pass — Design Spec¶

Date: 2026-03-17 Status: Approved Goal: Improve all public header doc comments to include meaningful descriptions, LaTeX math, literature references with DOIs, usage examples, template constraints, and cross-references.

Audience¶

Lab members and collaborators who extend forge by adding operators, modifying solvers, or integrating GPU backends. Priority is "how it works" and "how to compose" over "how to install."

Math Notation Standard¶

All formulas use Doxide-compatible LaTeX: - Inline: $...$ (renders via MathJax/arithmatex, already configured) - Display: $$...$$ - Convert existing Unicode math (β, ½, ‖·‖) to LaTeX equivalents ( $\beta$ , $\frac{1}{2}$ , $\|{\cdot}\|$ ) - Legacy Doxygen math (@f$) is also supported but prefer $ for readability

Literature References¶

Use @see tags with author-year citation and DOI:

/// @see Fessler & Sutton, "Nonuniform Fast Fourier Transforms Using
///      Min-Max Interpolation," IEEE TSP, 2003.
///      https://doi.org/10.1109/TSP.2002.807005

Example Format¶

Brief @code blocks on every public class showing typical composition:

/// @code
/// Gnufft<float> G(n1, n2, kx, ky, kz, ix, iy, iz, FM, t);
/// SENSE<float, Gnufft<float>> S(G, SMap, nc);
/// auto result = S / kdata;  // adjoint: k-space -> image
/// @endcode

Tiers and Review Strategy¶

Tier 1: Operators, Penalties, Solvers (pause for user review)¶

These have the most domain-sensitive math. User reviews the diff before committing.

File	Current Rating	Key Additions
`forge/Operators/Gdft.h`	Good	DFT forward model in LaTeX: $d_j = \sum_k x_k e^{-i(2\pi \mathbf{k}_j \cdot \mathbf{r}_k + \omega_k t_j)}$ where $\omega_k$ is the field map in rad/s (matching the code's `FM` parameter convention). Usage example. Ref: Fessler. Cross-ref to GdftR2, Gnufft.
`forge/Operators/GdftR2.h`	Good	First-order Taylor expansion formula for R2 correction. Gradient computation explanation. When to use vs plain Gdft. Ref: relevant R2 literature.
`forge/Operators/Gnufft.h`	Fair	KB gridding formula (convolution + FFT + sampling). Kaiser-Bessel kernel definition with shape parameter $\beta$. `gridos` guidance (typically 2.0). LUT accuracy notes. Refs: Pipe & Menon 1999, Jackson et al. 1991, Beatty et al. 2005. Example.
`forge/Operators/Gfft.h`	Good	Minimal — add usage example and cross-refs to Gnufft.
`forge/Operators/SENSE.h`	Fair	Multi-coil model: $\mathbf{d}_c = G(S_c \circ \mathbf{x})$ with stacking. Template constraint: Tobj must support `operator*` and `operator/`. Example composing with Gnufft. Cross-ref to pcSENSE. Ref: Pruessmann et al. 1999.
`forge/Operators/pcSENSE.h`	Fair	Per-shot phase-corrected model formula. Distinction from SENSE (shot-varying phase maps). Example. Cross-ref to pcSenseTimeSeg. Refs: Liu, Moseley & Bammer, MRM, 2005 (original pcSENSE); Holtrop & Sutton, J Med Imaging, 2016 (multislab spiral implementation that this code is based on).
`forge/Operators/pcSenseTimeSeg.h`	Fair	Combined phase + time-segmentation model formula. When to use vs pcSENSE alone. Example.
`forge/Penalties/Robject.h`	Good	Potential function family: $\psi(d)$, $\dot\psi(d) = \psi'(d)$, $\omega(d) = \psi'(d)/d$. Subclass implementation contract (which methods to override). Finite-difference operator $C$.
`forge/Penalties/QuadPenalty.h`	Good	$R(\mathbf{x}) = \frac{\beta}{2}\\|C\mathbf{x}\\|^2$ in LaTeX. $\beta$ selection guidance. Potential functions: $\psi(d) = \frac{1}{2}d^2$, $\omega(d) = 1$, $\dot\psi(d) = d$. Example.
`forge/Penalties/TVPenalty.h`	Fair	Hyperbola/Charbonnier potential in LaTeX: $\psi(d) = \delta^2(\sqrt{1 + (d/\delta)^2} - 1)$. Correct existing header (mislabeled as "Fair" potential). Derivative and weight functions. $\delta$ selection guidance. Ref: Rudin, Osher & Fatemi 1992 (exact TV context). Example.
`forge/Solvers/solve_pwls_pcg.hpp`	Good	PWLS objective in LaTeX: $\min_{\mathbf{x}} \\|\mathbf{W}^{1/2}(\mathbf{y} - A\mathbf{x})\\|^2 + R(\mathbf{x})$. PCG algorithm outline (Polak-Ribière). Convergence threshold rationale (1e-10, 1e-20). Example. Ref: Fessler, "Penalized Weighted Least-Squares Image Reconstruction for PET," IEEE TMI, 1994.
`forge/Solvers/reconSolve.h`	Good	Workflow example showing full pipeline. Relationship to solve_pwls_pcg. Image coordinate initialization formula.
`forge/Gridding/TimeSegmentation.h`	Fair	Time-segmentation approximation formula: $e^{-i \omega(\mathbf{r}) t} \approx \sum_l b_l(t) e^{-i \omega(\mathbf{r}) \tau_l}$ where $\omega$ is in rad/s. Interpolation types (Hanning, min-max). $L$ selection guidance. Refs: Sutton et al. 2003, Man et al. 1997. Example wrapping Gnufft.
`forge/Gridding/gridding.h`	Fair	Gridding/degridding formulas. KB kernel: $\kappa(u) = \frac{1}{L} I_0(\beta\sqrt{1-(2u/L)^2})$. Oversampling factor. LUT sizing. Density compensation role. Refs: Pipe & Menon 1999, Jackson et al. 1991, Beatty et al. 2005.

Tier 2: Core Types (autonomous, no review pause)¶

File	Current Rating	Key Additions
`forge/Core/forgeCol.hpp`	Fair	GPU/CPU sync semantics (`isOnGPU` lifecycle). View safety and lifetime rules. Metal dispatch threshold (N >= 4096). `getArma()` cost (memcpy). Example: create, operate, convert.
`forge/Core/forgeMat.hpp`	Fair	`set_size(nCols, nRows)` convention warning. Column-major layout. `getArma()` const vs non-const. `col()` returns view, `col_copy()` returns owned. Example.
`forge/Core/forgeComplex.hpp`	Fair	Memory layout identical to `std::complex<T>`. Operator docs. GPU compatibility notes (no virtual methods). Example.

Tier 3: Utilities (autonomous, no review pause)¶

File	Current Rating	Key Additions
`forge/Core/ForgeLog.hpp`	Good	Progress bar lifecycle (add → tick → done). JSONL message types enumeration. Example.
`forge/IO/processIsmrmrd.hpp`	Fair	Template function docs. Data layout conventions (stacking, ordering).
`forge/IO/processNIFTI.hpp`	Fair	Coordinate system notes (LPS → RAS). Quaternion conversion reference.
`forge/FFT/fftCPU.h`	Good	FFTW plan notes. Memory layout (interleaved real/imag).
`forge/FFT/ftCpu.h`	Fair	Add LaTeX math for DFT kernel, literature refs. Has basic `@param`/`@returns` already.
`forge/FFT/ftCpuWithGrads.h`	Fair	DFT with R2* gradient kernel docs. Cross-ref to GdftR2.
`forge/FFT/fftAccelerate.h`	Good	Apple Accelerate/vDSP wrapper. Minimal additions — example, cross-refs.
`forge/FFT/fftGPU.h`	Good	cuFFT wrapper. Minimal additions — example, cross-refs.
`forge/Gridding/griddingSupport.h`	Fair	KB kernel helpers (`bessi0`, `calculateLUT`, `kernel_value_LUT`, deapodization). LaTeX for KB kernel formula. Cross-ref to gridding.h.
`forge/Core/griddingTypes.h`	Fair	`ReconstructionSample<T1>` and `parameters<T1>` struct docs. Field descriptions.
`forge/IO/directRecon.h`	Fair	Direct gridding reconstruction. Density compensation, SoS combination docs.
`forge/IO/acqTracking.h`	Fair	ISMRMRD acquisition tracking. Data organization docs.
`forge/Solvers/solve_grad_desc.hpp`	Fair	Gradient descent objective, step size, convergence. Cross-ref to solve_pwls_pcg.

Key Literature References (with DOIs)¶

Topic	Reference	DOI
NUFFT / Min-max interpolation	Fessler & Sutton, IEEE TSP, 2003	`10.1109/TSP.2002.807005`
KB gridding	Jackson et al., IEEE TMI, 1991	`10.1109/42.75611`
Sampling density compensation	Pipe & Menon, MRM, 1999	`10.1002/(SICI)1522-2594(199901)41:1<179::AID-MRM25>3.0.CO;2-V`
Gridding with oversampling	Beatty et al., IEEE TMI, 2005	`10.1109/TMI.2004.842452`
SENSE	Pruessmann et al., MRM, 1999	`10.1002/(SICI)1522-2594(199911)42:5<952::AID-MRM16>3.0.CO;2-S`
Time segmentation	Sutton et al., IEEE TMI, 2003	`10.1109/TMI.2002.808360`
Time segmentation (original)	Man et al., IEEE TMI, 1997	`10.1109/42.611354`
PWLS reconstruction	Fessler, IEEE TMI, 1994	`10.1109/42.363108`
Total variation	Rudin, Osher & Fatemi, Physica D, 1992	`10.1016/0167-2789(92)90242-F`
pcSENSE (original)	Liu, Moseley & Bammer, MRM, 2005	`10.1002/mrm.20706`
pcSENSE (multislab spiral)	Holtrop & Sutton, J Med Imaging, 2016	`10.1117/1.JMI.3.2.023501`

Cross-Reference Convention¶

Use @see ClassName for cross-references between related classes. Doxide converts these to links automatically.

/// @see SENSE for the multi-coil wrapper without phase correction.
/// @see pcSenseTimeSeg for the combined phase + time-segmentation variant.

Rating Scale¶

Good — Has descriptions and @param/@returns tags. Needs math, refs, examples.
Fair — Has basic docs but missing math, refs, examples, or has gaps in coverage.
Poor — Minimal or missing docs on public API.

Validation¶

After each tier, verify: 1. doxide build — no new warnings from malformed comments 2. mkdocs build — site builds cleanly 3. Spot-check rendered API pages — LaTeX renders via MathJax, @see links work, @code examples display

Unit Convention¶

The codebase uses field maps (FM) in rad/s throughout. All formulas must be consistent with this convention — use $\omega$ (rad/s) not $2\pi f$ (Hz) for field map terms.

Tier 4: Metal Shaders (autonomous, no review pause)¶

Document Metal compute shaders for reference when building future CUDA modules.

File	Current Rating	Key Additions
`forge/Metal/vectorops_metal.metal`	Poor	Per-kernel docs: inputs, outputs, dispatch semantics. Data layout (interleaved complex). Threadgroup sizing notes.
`forge/Metal/MetalVectorOps.h`	Fair	Obj-C++ wrapper docs. Dispatch strategy (buffer binding, command encoding). Cross-ref to forgeCol dispatch.
`forge/Metal/MetalVectorOps.mm`	Fair	Implementation notes for each dispatch function. Error handling.
`forge/Metal/MetalNufftPipeline.h`	Fair	Full GPU NUFFT pipeline docs. Stage descriptions (gridding, FFT, deapodization).
`forge/Metal/MetalNufftPipeline.mm`	Fair	Implementation notes. Metal resource management.
Other `*.metal` files	Poor	Per-kernel docs matching the vectorops pattern.

Tier 5: Private/Internal Methods (autonomous, no review pause)¶

Basic pass on private/internal methods across all files already covered in Tiers 1-4. For lab members working on the code internals.

Focus on: - Private helper functions in operator classes (e.g., internal gridding loops, phase computation helpers) - Internal state management in forgeCol/forgeMat (memory allocation, GPU sync internals) - Implementation details in solvers (step-size selection, convergence checks) - SFINAE/template machinery (detail::has_pgcol_ops, guard functions)

Not every private method needs a paragraph — a one-liner explaining "what" and "why" is sufficient for most.

Tier 6: Hand-Authored Guides Refresh (autonomous, no review pause)¶

Light-touch update of the hand-authored Markdown guides to reflect current code and layout.

File	Key Updates
`docs/guides/operators-and-solvers.md`	Verify operator table matches current headers. Add any new operators/solvers. Update code example if API has changed.
`docs/guides/forge-types.md`	Verify against current forgeCol/forgeMat API. Update operator tables, add any new free functions.
`docs/guides/metal-backend.md`	Verify build commands match current CMakeLists.txt. Update kernel list if new Metal shaders added. Check phase status (1/2/3).
`docs/guides/forgeview.md`	Verify JSONL message types match current ForgeLog.hpp. Update CLI flags if changed.
`docs/guides/mpi.md`	Verify MPI executable names and flags match current code.
`docs/getting-started/building.md`	Verify CMake options table. Check Docker image names.
`docs/getting-started/installation.md`	Verify dependency versions against CMakeLists.txt.
`docs/getting-started/first-reconstruction.md`	Verify CLI flags match current Boost.ProgramOptions definitions.

What This Does NOT Cover¶

CI integration for doc builds

File	Current Rating	Key Additions
`forge/Operators/Gdft.h`	Good	DFT forward model in LaTeX: \(d_j = \sum_k x_k e^{-i(2\pi \mathbf{k}_j \cdot \mathbf{r}_k + \omega_k t_j)}\) where \(\omega_k\) is the field map in rad/s (matching the code's `FM` parameter convention). Usage example. Ref: Fessler. Cross-ref to GdftR2, Gnufft.
`forge/Operators/GdftR2.h`	Good	First-order Taylor expansion formula for R2 correction. Gradient computation explanation. When to use vs plain Gdft. Ref: relevant R2 literature.
`forge/Operators/Gnufft.h`	Fair	KB gridding formula (convolution + FFT + sampling). Kaiser-Bessel kernel definition with shape parameter \(\beta\). `gridos` guidance (typically 2.0). LUT accuracy notes. Refs: Pipe & Menon 1999, Jackson et al. 1991, Beatty et al. 2005. Example.
`forge/Operators/Gfft.h`	Good	Minimal — add usage example and cross-refs to Gnufft.
`forge/Operators/SENSE.h`	Fair	Multi-coil model: \(\mathbf{d}_c = G(S_c \circ \mathbf{x})\) with stacking. Template constraint: Tobj must support `operator*` and `operator/`. Example composing with Gnufft. Cross-ref to pcSENSE. Ref: Pruessmann et al. 1999.
`forge/Operators/pcSENSE.h`	Fair	Per-shot phase-corrected model formula. Distinction from SENSE (shot-varying phase maps). Example. Cross-ref to pcSenseTimeSeg. Refs: Liu, Moseley & Bammer, MRM, 2005 (original pcSENSE); Holtrop & Sutton, J Med Imaging, 2016 (multislab spiral implementation that this code is based on).
`forge/Operators/pcSenseTimeSeg.h`	Fair	Combined phase + time-segmentation model formula. When to use vs pcSENSE alone. Example.
`forge/Penalties/Robject.h`	Good	Potential function family: \(\psi(d)\), \(\dot\psi(d) = \psi'(d)\), \(\omega(d) = \psi'(d)/d\). Subclass implementation contract (which methods to override). Finite-difference operator \(C\).
`forge/Penalties/QuadPenalty.h`	Good	\(R(\mathbf{x}) = \frac{\beta}{2}\\|C\mathbf{x}\\|^2\) in LaTeX. \(\beta\) selection guidance. Potential functions: \(\psi(d) = \frac{1}{2}d^2\), \(\omega(d) = 1\), \(\dot\psi(d) = d\). Example.
`forge/Penalties/TVPenalty.h`	Fair	Hyperbola/Charbonnier potential in LaTeX: \(\psi(d) = \delta^2(\sqrt{1 + (d/\delta)^2} - 1)\). Correct existing header (mislabeled as "Fair" potential). Derivative and weight functions. \(\delta\) selection guidance. Ref: Rudin, Osher & Fatemi 1992 (exact TV context). Example.
`forge/Solvers/solve_pwls_pcg.hpp`	Good	PWLS objective in LaTeX: \(\min_{\mathbf{x}} \\|\mathbf{W}^{1/2}(\mathbf{y} - A\mathbf{x})\\|^2 + R(\mathbf{x})\). PCG algorithm outline (Polak-Ribière). Convergence threshold rationale (1e-10, 1e-20). Example. Ref: Fessler, "Penalized Weighted Least-Squares Image Reconstruction for PET," IEEE TMI, 1994.
`forge/Solvers/reconSolve.h`	Good	Workflow example showing full pipeline. Relationship to solve_pwls_pcg. Image coordinate initialization formula.
`forge/Gridding/TimeSegmentation.h`	Fair	Time-segmentation approximation formula: \(e^{-i \omega(\mathbf{r}) t} \approx \sum_l b_l(t) e^{-i \omega(\mathbf{r}) \tau_l}\) where \(\omega\) is in rad/s. Interpolation types (Hanning, min-max). \(L\) selection guidance. Refs: Sutton et al. 2003, Man et al. 1997. Example wrapping Gnufft.
`forge/Gridding/gridding.h`	Fair	Gridding/degridding formulas. KB kernel: \(\kappa(u) = \frac{1}{L} I_0(\beta\sqrt{1-(2u/L)^2})\). Oversampling factor. LUT sizing. Density compensation role. Refs: Pipe & Menon 1999, Jackson et al. 1991, Beatty et al. 2005.