Skip to content

Reproducing the papers on a CUDA server

This runbook lists the exact commands that regenerate the headline tables of NeTMY (arXiv 2605.13988) and NeFTY (arXiv 2603.11045) with nefi, what they cost, and which caveats to check before comparing numbers. Everything runs from a fresh clone; nothing is downloaded.

HOST=gpu-server scripts/sync_to_server.sh     # or: git clone https://github.com/CAB-Lab-Princeton/NEFI.git
ssh gpu-server
cd ~/nefi && pip install -e ".[dev]" && nefi list instances
make smoke                                     # ~1 min sanity check on the GPU node

Add --device cuda to every command below (or export NEFI_DEVICE=cuda). Results land under runs/<name>/ with result.pt, config.yaml, metrics.json, history.csv, benchmark tables as markdown / CSV / JSON, and python examples/visualize_result.py runs/<dir> --html renders the figures.

NeTMY — NV relaxometry

Paper protocol (§5.1, App. E.1): 512 samples = 8 scene classes × 64, spectra generated by the direct source-side simulator F3, inverted under F2 (and F1 for the cross-fidelity comparison), 3 seeds, mean ± 95 % CI. configs/nv_relaxometry_paper.yaml holds Tab. 5–7 (architecture, schedule, loss weights) and the F3 data generator.

# Tab. 1 (cross-fidelity: NeTMY and Tikhonov under F2 and F1), all 8 classes
nefi bench configs/nv_relaxometry_paper.yaml --methods netmy,f1,grid,grid_f1 \
     --classes all --by-class --n 64 --seeds 0,1,2 --device cuda --out runs/netmy_tab1

# one sample end to end with figures
nefi run configs/nv_relaxometry_paper.yaml --scene many/close --seed 0 --plot --device cuda

# Tab. 3 cumulative ablation (annealing, PE, multiscale, ℓ1, gate, R_ds)
nefi ablate nv_relaxometry --set preset=paper \
     --variants no_annealing,no_pe,single_stage,drop_loss:l1,no_gate,drop_loss:direct_density \
     --n 16 --seeds 0,1,2 --device cuda --out runs/netmy_tab3

# Tab. 10 sweeps
nefi sweep nv_relaxometry --set preset=paper --axis lr --values 1e-4,5e-4,1e-3,5e-3,1e-2 --n 8
nefi sweep nv_relaxometry --set preset=paper --axis n_octaves --values 4,8,12,16,20 --n 8

# §5.3 mechanism diagnostics (iter-0 gradient, energy barrier, filter-kernel rows)
nefi diagnose configs/nv_relaxometry_paper.yaml --solve --plot --device cuda

Cost: the paper reports a 273 s median per sample on an A6000 (10 000 steps); the CPU-measured step times here are 9 ms at 32² and 27 ms at 64², so expect roughly 3–5 min per sample on a modern GPU (--batched amortizes many samples per step for this FFT-based operator, see performance). --n 64 × 3 seeds × 4 methods is ~10 GPU-hours.

Caveats to check (docs/instances/nv_relaxometry.md): - Larmor fill outside the predicted support defaults to the band centre (larmor_fill: 0.0 reproduces Eq. (26) literally; it lowers Hungarian F1 under F2). - log_eps is noise-aware by default (1e-10 reproduces Eq. (19) literally). - anneal_reset: false helps at short budgets; the paper's Tab. 6 (reset) is the default. - Use restarts: 2 to probe the App. E.10 centred-collapse trapping (~5 % of samples).

NeFTY — thermal tomography

Paper protocol (§5.1, App. E.1): 1 000 synthetic samples per configuration (homogeneous / layered), 64 × 64 × 16, 100 frames at Δt = 0.05, explicit substepped data generator, single-stage 10 000-step optimization. configs/thermal_tomography_paper.yaml holds Tab. 5; the layered preset switches the scene class.

# Tab. 1 label-free reconstruction (NeFTY vs Grid Opt. vs soft PINN vs PPT/TSR), both settings
nefi bench thermal_tomography --set preset=paper --methods nefty,grid,pinn_soft,ppt,tsr \
     --classes homogeneous,layered --by-class --n 32 --seeds 0,1,2 --device cuda \
     --set compile_solver=true --out runs/nefty_tab1

# Tab. 3 cumulative ablation (PE, annealing, bounded output, harmonic mean, TV)
nefi ablate thermal_tomography --set preset=paper \
     --variants no_pe,no_annealing,set_config:face_mode=arithmetic,drop_loss:tv \
     --n 8 --seeds 0,1 --device cuda --out runs/nefty_tab3

# Tab. 4 solver-level efficiency (fwd / bwd time, peak memory: adjoint vs checkpoint vs autograd)
python -c "from nefi.bench import runtime_table; print(runtime_table.__doc__)"   # see tutorial 6
python examples/thermal_tomography.py --config configs/thermal_tomography_paper.yaml \
     --device cuda --set grad_mode=adjoint      # repeat with checkpoint / autograd (16 GB!)

# App. G.5 frequency-domain diagnostics and App. G.7 failure mode are in the instance docs page

Cost: with compile_solver=true expect ~0.1 s per step (~15–20 min per specimen; the paper reports 9.6 min); eager mode is 5–10× slower. Memory is a few GB (MLP activations on 65 536 points); never use grad_mode=autograd at paper scale.

Caveats to check (docs/instances/thermal_tomography.md): - Model-error floor. Implicit Euler at one step per camera frame cannot resolve the fast through-thickness decay of the thin flash layer; re-simulating the ground truth with the inversion operator reaches only ~46–51 dB surface PSNR against the explicit data, so the paper's 82 dB (Tab. 7) is not reachable under a time-accurate generator. Run the implicit_substeps ∈ {1, 2} × flash_width_z ∈ {0.1, 0.2} grid first and compare surface_psnr with the floor before reading IoU. - Flash amplitude / widths and defect sizes are not given in the paper; the config documents the choices. - The App. H mask rule uses the MAD of the signed deficit (the literal clipped rule collapses).

Real PVC data (NeFTY §5.3)

The PVC-Infrared / PVC-Depth benchmarks (Wei et al. 2023) are not bundled. Download them to the server, then follow the "Real data" section of docs/instances/thermal_tomography.md (load_frames → measurement_from_frames → PhysicalScales → pvc_overrides → ThermalTomography(cfg).build_problem(meas)), and compare against the ppt / tsr baselines through the 2-D IoU / Dice and 2.5-D depth metrics.

Everything else

Each physics-zoo instance ships a configs/<name>_full.yaml sized for a GPU; run them the same way (nefi run configs/<name>_full.yaml --device cuda, nefi bench configs/<name>_full.yaml --methods neural,grid,... --n 8 --seeds 0,1,2). python examples/gallery.py --budget 1.0 --device cuda --out runs/gallery --html regenerates the multi-physics gallery at full budgets.