DeepGPR 0.1.0__tar.gz → 0.1.1__tar.gz

{deepgpr-0.1.0 → deepgpr-0.1.1}/CHANGELOG.md

@@ -4,6 +4,91 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased] — History memory and CUDA adjoint performance
+
+Measurements, protocol and per-item decisions:
+[`tests/profiling_results/history_adjoint_gpu_report.md`](tests/profiling_results/history_adjoint_gpu_report.md).
+
+### Added
+
+- `model_gradient_sampling_interval="auto"` selects
+  `S = max(1, floor(1 / (4 f_max dt)))`, with `f_max` the highest frequency at
+  which the source amplitude spectrum exceeds `3e-3` of its peak (about
+  `3 f_peak` for a Ricker wavelet; several waveforms use the smallest `S`).
+  `DeepGPR.recommended_sampling_interval` and `DeepGPR.source_max_frequency`
+  expose the bound so segmented/checkpointed runs can evaluate it once on the
+  full waveform. The default stays `1`.
+- `wavefield_rhs_history` (`"auto"`, `"stored"`, `"reconstructed"`). With
+  sampling interval 1 the adjoint rebuilds `R^n = (E^(n+1) - ca E^n) / cb` from
+  consecutive saved E frames, so only E is stored (plus one internal final
+  frame). The default `"auto"` does this for uncompressed `float32` histories:
+  history memory halves, the forward no longer runs the R-snapshot kernel, and
+  gradients are unchanged (bitwise on CPU). Low-precision and INT8 histories
+  keep E+R by default (rebuilding from two rounded frames was measurably less
+  accurate in some cases) and can opt in with `"reconstructed"`. New native
+  capability probe `deepgpr_supports_rhs_reconstruction` (ABI 6 unchanged);
+  older libraries fall back to E+R.
+- `wavefield_history_region` (`"extended"` default, `"physical"`). `"physical"`
+  stores E/R histories only on the physical model cells (CPML cells never get
+  a material gradient), so history memory falls with the cell count and
+  gradients are unchanged. INT8 histories widen the box to whole tiles of the
+  full-grid tiling so tiles and scales are identical to `"extended"`. New probe
+  `deepgpr_supports_physical_history`; saved files record the region.
+
+### Performance
+
+- CUDA full-grid kernels (E/H update and adjoint) take the shot from
+  `blockIdx.y` and decode `(i, j, k)` from a 32-bit per-shot index with a
+  multiply-high divider instead of four 64-bit `/` and `%` per thread. Grids
+  above `2^31 - 1` cells per shot are rejected explicitly.
+- CUDA 2D TM fast path: for 2D models with an Ez source and zero Ex/Ey/Hz
+  states the solver launches only the `k = 0` layer and updates/transposes
+  only Ez, Hx and Hy (probe `deepgpr_supports_tm2d_fast_path`). Receiver data
+  is bitwise unchanged; initial-state gradients of Ex/Ey/Hz are zero on this
+  path. Other calls use the general kernels.
+
+- CUDA 2D TM adjoint as a gather (AUDIT N-7): on the 2D TM fast path the
+  transposed curl and CPML updates no longer scatter with `atomicAdd`; every
+  target point gathers its source stencil in a fixed order with CPML
+  derivative weights from phi-sized scratch (2D backward about 30 % faster,
+  bitwise reproducible). Receiver and source-waveform adjoints add coincident
+  points in a fixed order on every path. The general (3D) CUDA adjoint keeps
+  the atomic scatter, which measured faster than a gather there;
+  `deepgpr_deterministic_adjoint()` stays 0. Gradients differ from the
+  previous release at rounding level only.
+- CUDA kernel fusion on the 2D TM fast path: each cell's CPML corrections run
+  inside `update_e_gpu` / `update_h_gpu` right after its base update (same
+  face order and arithmetic; the other field is read only), and float32 /
+  float16 / bfloat16 E histories are written by `update_h_gpu`, where E is not
+  modified. Forward launches per time step drop from 6 to 3 (2D forward
+  11-18 % faster; with INT8 histories 6-10 %). INT8 and `native_vec2`
+  histories and the stored-R snapshot keep their own kernels. The general
+  (3D) forward keeps separate CPML and snapshot kernels: fused, it was faster
+  on small 3D grids but up to 8 % slower on a 140^3 grid. The general scatter
+  adjoint applies the CPML transposes inside `adjoint_e_gpu` /
+  `adjoint_h_gpu` (6 to 4 launches per reverse step; 3D fp32 backward about
+  3.5 % faster, other storage modes within noise). Receiver data, states and
+  histories are bitwise unchanged; 2D TM gradients are bitwise unchanged, 3D
+  gradients change at atomic-ordering level only. The material-gradient
+  kernel stays separate (it reduces over shots per cell in a fixed order and
+  runs only every `S` steps).
+
+### Changed
+
+- An explicit `model_gradient_sampling_interval > 1` no longer always raises a
+  `RuntimeWarning`; it warns (and states the bound) only above
+  `floor(1 / (4 f_max dt))`. Intervals inside the bound are logged at INFO.
+- **Default history layout:** float32 histories at sampling interval 1 no
+  longer allocate `R_saved`; pass `wavefield_rhs_history="stored"` to restore
+  the previous layout. `estimate_compute_memory` gained `reconstruct_rhs` and a
+  `final_e_frame` entry; `print_parameters` reports the R-history mode.
+- The native `storage_type` argument reserves bits 4-7 for history flags (the
+  storage kind now uses bits 0-3).
+- Documentation: README, `docs/API.md`, `docs/BUILDING.md` (new capability
+  probes) and the website describe the new history options; the website now
+  links to `docs/API.md` instead of a README anchor that moved in 0.1.0 and no
+  longer lists SciPy as a runtime dependency.
+
 ## [0.1.0] — Structural refactor and numerical fixes
 
 This release reorganises the Python package into a layered, typed and

{deepgpr-0.1.0/src/DeepGPR.egg-info → deepgpr-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeepGPR
-Version: 0.1.0
+Version: 0.1.1
 Summary: PyTorch and CUDA for GPR FWI
 Author-email: Lei Liu <liulei990222@gmail.com>
 License-Expression: MIT
@@ -47,7 +47,7 @@ DeepGPR provides a wave propagation module for PyTorch, designed for application
 - Automatic extension of the physical model into a CPML with an independent thickness on every face. Supply only air and the target region; material gradients keep the input model shape.
 - CUDA GPU backend and a C/OpenMP CPU backend (selected automatically with `device='cpu'`).
 - Spatial FDTD order 2, 4 or 8 (`fdtd_order`), and gradient mode 2 (Ez only) or 3 (Ex, Ey, Ez).
-- Large models: checkpointing, DDP, temporal sub-sampling, FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory.
+- Large models: checkpointing, DDP, temporal sub-sampling (fixed or `"auto"` from the source spectrum), E-only float32 histories (default; half the memory of E+R), histories restricted to the physical model (`wavefield_history_region="physical"`), FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory. See [`docs/API.md`](docs/API.md) §4.3-4.6.
 
 ## System requirements
 
@@ -162,6 +162,7 @@ The figures show the true model, the initial model and the inverted result.
 | `DeepGPR.apply_filter`, `DeepGPR.hilbert_transform` | low-pass FIR and envelope for multi-scale FWI |
 | `DeepGPR.max_stable_time_step(...)` | largest CFL-stable `dt` for a grid, order and material |
 | `DeepGPR.estimate_compute_memory(...)` | memory estimate (also printed by `print_parameters=True`) |
+| `DeepGPR.recommended_sampling_interval(...)`, `DeepGPR.source_max_frequency(...)` | gradient sampling interval bound `floor(1 / (4 f_max dt))` from a source waveform (what `model_gradient_sampling_interval="auto"` uses) |
 | `DeepGPR.decompress_wavefield_history(...)` | decode a packed INT8 history for diagnostics |
 | `DeepGPR.visualization.plot_*` | models, radargrams, traces, true/initial/inverted comparison |
 | `DeepGPR.configure_logging(level)` | enable DeepGPR log output |
@@ -224,8 +225,10 @@ Run the notebooks `00` to `09` in numeric order, followed by
 the complete matrix and CUDA options.
 
 **Reproducibility.** The CPU backend gives bitwise identical forward results
-and gradients for any `OMP_NUM_THREADS`. The CUDA adjoint accumulates with
-atomics and can differ in the last bits between runs.
+and gradients for any `OMP_NUM_THREADS`. On CUDA, 2D Ez-TM runs (the 2D fast
+path) gather their adjoint without atomics and are bitwise reproducible; the
+general (3D) CUDA adjoint accumulates with atomics and can differ in the last
+bits between runs.
 
 **Reproducing results from DeepGPR ≤ 0.0.20.** 0.1.0 corrects the FIR design
 for even filter lengths, the envelope for odd trace lengths and the isotropic

{deepgpr-0.1.0 → deepgpr-0.1.1}/README.md

@@ -11,7 +11,7 @@ DeepGPR provides a wave propagation module for PyTorch, designed for application
 - Automatic extension of the physical model into a CPML with an independent thickness on every face. Supply only air and the target region; material gradients keep the input model shape.
 - CUDA GPU backend and a C/OpenMP CPU backend (selected automatically with `device='cpu'`).
 - Spatial FDTD order 2, 4 or 8 (`fdtd_order`), and gradient mode 2 (Ez only) or 3 (Ex, Ey, Ez).
-- Large models: checkpointing, DDP, temporal sub-sampling, FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory.
+- Large models: checkpointing, DDP, temporal sub-sampling (fixed or `"auto"` from the source spectrum), E-only float32 histories (default; half the memory of E+R), histories restricted to the physical model (`wavefield_history_region="physical"`), FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory. See [`docs/API.md`](docs/API.md) §4.3-4.6.
 
 ## System requirements
 
@@ -126,6 +126,7 @@ The figures show the true model, the initial model and the inverted result.
 | `DeepGPR.apply_filter`, `DeepGPR.hilbert_transform` | low-pass FIR and envelope for multi-scale FWI |
 | `DeepGPR.max_stable_time_step(...)` | largest CFL-stable `dt` for a grid, order and material |
 | `DeepGPR.estimate_compute_memory(...)` | memory estimate (also printed by `print_parameters=True`) |
+| `DeepGPR.recommended_sampling_interval(...)`, `DeepGPR.source_max_frequency(...)` | gradient sampling interval bound `floor(1 / (4 f_max dt))` from a source waveform (what `model_gradient_sampling_interval="auto"` uses) |
 | `DeepGPR.decompress_wavefield_history(...)` | decode a packed INT8 history for diagnostics |
 | `DeepGPR.visualization.plot_*` | models, radargrams, traces, true/initial/inverted comparison |
 | `DeepGPR.configure_logging(level)` | enable DeepGPR log output |
@@ -188,8 +189,10 @@ Run the notebooks `00` to `09` in numeric order, followed by
 the complete matrix and CUDA options.
 
 **Reproducibility.** The CPU backend gives bitwise identical forward results
-and gradients for any `OMP_NUM_THREADS`. The CUDA adjoint accumulates with
-atomics and can differ in the last bits between runs.
+and gradients for any `OMP_NUM_THREADS`. On CUDA, 2D Ez-TM runs (the 2D fast
+path) gather their adjoint without atomics and are bitwise reproducible; the
+general (3D) CUDA adjoint accumulates with atomics and can differ in the last
+bits between runs.
 
 **Reproducing results from DeepGPR ≤ 0.0.20.** 0.1.0 corrects the FIR design
 for even filter lengths, the envelope for odd trace lengths and the isotropic

{deepgpr-0.1.0 → deepgpr-0.1.1}/src/DeepGPR/__init__.py

@@ -66,6 +66,7 @@ from .preprocessing.stability import max_stable_time_step
 from .solver.autograd import DeepGPR
 from .solver.modeling import compute
 from .solver.memory import estimate_compute_memory
+from .solver.sampling import recommended_sampling_interval, source_max_frequency
 from .solver.storage import decompress_wavefield_history
 from .utils.exceptions import (
     CFLConditionError,
@@ -122,10 +123,12 @@ __all__ = [
     "pmlthick_revert",
     "postprocessing",
     "preprocessing",
+    "recommended_sampling_interval",
     "ricker",
     "set_library_fdtd_order",
     "sine_burst",
     "solver",
+    "source_max_frequency",
     "utils",
     "visualization",
     "wavelet",

{deepgpr-0.1.0 → deepgpr-0.1.1}/src/DeepGPR/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{deepgpr-0.1.0 → deepgpr-0.1.1}/src/DeepGPR/config/constants.py

@@ -101,6 +101,17 @@ CPML_PHI_TENSOR_COUNT: Final[int] = CPML_FACE_COUNT * CPML_PHI_TENSORS_PER_FACE
 #: Human readable CPML face names in native order.
 CPML_FACE_NAMES: Final[Tuple[str, ...]] = ("x0", "xm", "y0", "ym", "z0", "zm")
 
+# ---------------------------------------------------------------------------
+# Temporal sampling of the gradient history
+# ---------------------------------------------------------------------------
+
+#: Relative amplitude at which a source spectrum counts as decayed when
+#: ``model_gradient_sampling_interval="auto"`` locates ``f_max``. For a Ricker
+#: wavelet ``|W(f)| / |W(f_peak)| = (f/f_peak)^2 exp(1 - (f/f_peak)^2)`` equals
+#: 3.0e-3 at ``f ~= 3 f_peak``, so the recommended interval is
+#: ``floor(1 / (12 f_peak dt))``.
+SOURCE_SPECTRUM_CUTOFF_FRACTION: Final[float] = 3.0e-3
+
 # ---------------------------------------------------------------------------
 # Native library ABI
 # ---------------------------------------------------------------------------
@@ -120,6 +131,32 @@ WAVEFIELD_STORAGE_FLOAT16: Final[int] = 1
 WAVEFIELD_STORAGE_BFLOAT16: Final[int] = 2
 WAVEFIELD_STORAGE_INT8: Final[int] = 3
 
+#: Bits 0-3 of ``storage_type`` hold the storage code; bits 4-7 are history flags.
+WAVEFIELD_STORAGE_KIND_MASK: Final[int] = 0x0F
+
+#: History flag: store only E^n (sampling interval 1). ``R_saved`` receives the
+#: final E^nt frame and the adjoint rebuilds R^n = (E^(n+1) - ca E^n) / cb.
+#: Only set when the library reports ``deepgpr_supports_rhs_reconstruction``.
+WAVEFIELD_RHS_FROM_E: Final[int] = 1 << 4
+
+#: History flag: E/R frames cover only the physical model cells (no CPML).
+#: Only set when the library reports ``deepgpr_supports_physical_history``.
+WAVEFIELD_PHYSICAL_HISTORY: Final[int] = 1 << 5
+
+#: Solver flag: 2D Ez-TM fast path (CUDA). Set only for nz = 1, an Ez source
+#: and zero Ex/Ey/Hz states and when ``deepgpr_supports_tm2d_fast_path`` is 1.
+SOLVER_TM2D: Final[int] = 1 << 6
+
+#: Indices of the CPML auxiliary arrays (in the 24-array native order) that
+#: couple only Ex, Ey and Hz in 2D: x0/xm/y0/ym E-phi1 and H-phi2.
+TM2D_INACTIVE_PHI_INDICES: Final[Tuple[int, ...]] = (0, 3, 4, 7, 8, 11, 12, 15)
+
+#: Accepted values of ``wavefield_history_region``.
+WAVEFIELD_HISTORY_REGIONS: Final[Tuple[str, ...]] = ("extended", "physical")
+
+#: Accepted values of ``wavefield_rhs_history``.
+WAVEFIELD_RHS_HISTORY_MODES: Final[Tuple[str, ...]] = ("auto", "stored", "reconstructed")
+
 #: Bit offsets and mask of the INT8 block shape inside ``storage_type``.
 INT8_BLOCK_X_SHIFT: Final[int] = 8
 INT8_BLOCK_Y_SHIFT: Final[int] = 14
@@ -219,17 +256,25 @@ __all__ = [
     "MIN_RELATIVE_PERMITTIVITY",
     "NATIVE_ABI_VERSION",
     "PEC_CONDUCTIVITY_THRESHOLD",
+    "SOLVER_TM2D",
+    "SOURCE_SPECTRUM_CUTOFF_FRACTION",
     "SPEED_OF_LIGHT",
     "SUPPORTED_FDTD_ORDERS",
     "SUPPORTED_GRADIENT_MODES",
+    "TM2D_INACTIVE_PHI_INDICES",
     "TV_ISOTROPIC_EPSILON",
     "VACUUM_PERMEABILITY",
     "VACUUM_PERMITTIVITY",
     "WAVEFIELD_CONVERSION_BACKENDS",
     "WAVEFIELD_CONVERSION_SHIFT",
     "WAVEFIELD_HISTORY_DISABLED",
+    "WAVEFIELD_HISTORY_REGIONS",
+    "WAVEFIELD_PHYSICAL_HISTORY",
+    "WAVEFIELD_RHS_FROM_E",
+    "WAVEFIELD_RHS_HISTORY_MODES",
     "WAVEFIELD_STORAGE_BFLOAT16",
     "WAVEFIELD_STORAGE_FLOAT16",
     "WAVEFIELD_STORAGE_FLOAT32",
     "WAVEFIELD_STORAGE_INT8",
+    "WAVEFIELD_STORAGE_KIND_MASK",
 ]

{deepgpr-0.1.0 → deepgpr-0.1.1}/src/DeepGPR/config/defaults.py

@@ -30,6 +30,13 @@ DEFAULT_GRADIENT_SAMPLING_INTERVAL: Final[int] = 1
 #: Saved-history compression mode.
 DEFAULT_WAVEFIELD_COMPRESSION: Final[str] = "none"
 
+#: Storage of the electric right-hand-side history R^n ("auto": rebuilt from
+#: consecutive E frames when the sampling interval is 1).
+DEFAULT_WAVEFIELD_RHS_HISTORY: Final[str] = "auto"
+
+#: Cells covered by the saved E/R history ("extended": whole grid incl. CPML).
+DEFAULT_WAVEFIELD_HISTORY_REGION: Final[str] = "extended"
+
 #: CUDA FP16/BF16 conversion backend selector.
 DEFAULT_CONVERSION_BACKEND: Final[str] = "auto"
 
@@ -67,6 +74,8 @@ __all__ = [
     "DEFAULT_TV_WEIGHT_CONDUCTIVITY",
     "DEFAULT_TV_WEIGHT_PERMITTIVITY",
     "DEFAULT_WAVEFIELD_COMPRESSION",
+    "DEFAULT_WAVEFIELD_HISTORY_REGION",
+    "DEFAULT_WAVEFIELD_RHS_HISTORY",
     "DEFAULT_WAVELET_CYCLES",
     "FIR_TAPS_PER_PERIOD",
     "FORWARD_WAVEFIELD_PREFIX",