DeepGPR 0.1.0__tar.gz → 0.1.3__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: DeepGPR
-Version: 0.1.0
+Version: 0.1.3
 Summary: PyTorch and CUDA for GPR FWI
 Author-email: Lei Liu <liulei990222@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/songc0a/DeepGPR
 Project-URL: Repository, https://github.com/songc0a/DeepGPR
 Project-URL: Documentation, https://songc0a.github.io/DeepGPR/
-Project-URL: Changelog, https://github.com/songc0a/DeepGPR/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/songc0a/DeepGPR/blob/main/docs/CHANGELOG.md
 Keywords: ground penetrating radar,GPR,FDTD,full waveform inversion,PyTorch,CUDA
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: Microsoft :: Windows
@@ -44,10 +44,10 @@ DeepGPR provides a wave propagation module for PyTorch, designed for application
 
 - 2D and 3D forward modeling of Maxwell's equations with the Finite-Difference Time-Domain (FDTD) method, for single and multiple excitations.
 - Gradients of the receiver data with respect to relative permittivity, conductivity, the initial wavefield and the source amplitudes, computed by an exact discrete adjoint.
-- 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.
+- Automatic extension of the physical model into a CPML with an independent thickness on every face. Supply only air and the target region; sensitivities from replicated PML materials are summed back to the input model edges. Absorption uses a fixed `pml_max_velocity` reference (vacuum light speed by default).
 - 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), FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory. Material gradients with PML require `wavefield_history_region="extended"`; physical-only histories remain available for diagnostics, source/initial-state gradients and models without PML. See [`docs/API.md`](docs/API.md) §4.3-4.6.
 
 ## System requirements
 
@@ -68,8 +68,7 @@ pip install "DeepGPR[examples]"     # + scipy, scikit-image, jupyter for the not
 For development from a clone:
 
 ```bash
-pip install -r requirements-dev.txt
-pip install -e .
+pip install -e ".[dev,examples]"
 ```
 
 The prebuilt native libraries ship in `src/DeepGPR/lib`. To rebuild them see [`docs/BUILDING.md`](docs/BUILDING.md).
@@ -114,7 +113,7 @@ DeepGPR.visualization.plot_model(eps_r.grad, ax=ax[1], title="Gradient", cmap="s
 plt.show()
 ```
 
-![result](Fig/example.png)
+![result](docs/Fig/example.png)
 
 More examples are in [`examples/`](examples) (forward modeling, 2D FWI, 3D FWI).
 
@@ -141,15 +140,15 @@ The figures show the true model, the initial model and the inverted result.
 
 | True model | Initial model | Inverted result |
 | --- | --- | --- |
-| ![2D true model](Fig/2dfwitrue.png) | ![2D initial model](Fig/2dfwiinit.png) | ![2D inverted result](Fig/2dfwipred.png) |
+| ![2D true model](docs/Fig/2dfwitrue.png) | ![2D initial model](docs/Fig/2dfwiinit.png) | ![2D inverted result](docs/Fig/2dfwipred.png) |
 
 ### 3D FWI (central slice)
 
 | Model | Central slice |
 | --- | --- |
-| True model | ![3D true model central slice](Fig/3dfwitrue.png) |
-| Initial model | ![3D initial model central slice](Fig/3dfwiinit.png) |
-| Inverted result | ![3D inverted result central slice](Fig/3dfwipred.png) |
+| True model | ![3D true model central slice](docs/Fig/3dfwitrue.png) |
+| Initial model | ![3D initial model central slice](docs/Fig/3dfwiinit.png) |
+| Inverted result | ![3D inverted result central slice](docs/Fig/3dfwipred.png) |
 
 ## API overview
 
@@ -162,6 +161,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 |
@@ -197,10 +197,10 @@ src/DeepGPR/
 ├── utils/                 logging, exceptions, validators, diagnostics
 ├── lib/                   deepgpr.cu, deepgpr_cpu.c, deepgpr.h and prebuilt binaries
 ├── common.py, compute2.py, multiscale.py, wavelet.py   compatibility modules
-docs/                      API reference, build guide, code audit
+docs/                      API reference, build guide, changelog, manifest and Fig/
 examples/                  forward, 2D FWI and 3D FWI notebooks
 tests/                     unit tests, verification notebooks, benchmarks
-tools/                     verify_equivalence.py
+website/                   static pages, assets, scripts/, tools/ and promo_pixel/
 ```
 
 Data flow of one `compute` call:
@@ -215,8 +215,8 @@ and the saved history.
 python -m unittest discover -s tests -p "test_*.py"     # unit tests
 python -m unittest tests/test_native_abi.py             # ABI check, no PyTorch needed
 python tests/run_notebook.py tests/00_local_backend_and_contracts.ipynb
-python tools/verify_equivalence.py --reference-src /path/to/DeepGPR-0.0.20/src/DeepGPR
-bash tools/run_local_validation.sh /path/to/DeepGPR-0.0.20   # rebuild CPU+CUDA libs, run everything
+python website/tools/verify_equivalence.py --no-pml --reference-src /path/to/DeepGPR-0.0.20/src/DeepGPR
+bash website/tools/run_local_validation.sh /path/to/DeepGPR-0.0.20   # rebuild CPU+CUDA libs, run everything
 ```
 
 Run the notebooks `00` to `09` in numeric order, followed by
@@ -224,20 +224,22 @@ 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
-TV (see [`CHANGELOG.md`](CHANGELOG.md)). Use `apply_filter(..., legacy=True)`,
+TV (see [`docs/CHANGELOG.md`](docs/CHANGELOG.md)). Use `apply_filter(..., legacy=True)`,
 `design_fir_filter(..., legacy=True)`, `hilbert_transform(..., legacy=True)`
 and `TVRegularization(method="legacy_isotropic")` to reproduce earlier numbers.
 
 ## Development
 
-- Code style: PEP 8, enforced with `ruff check src/DeepGPR tools` (configuration in `pyproject.toml`).
+- Code style: PEP 8, enforced with `ruff check src/DeepGPR website/tools docs/build_support.py` (configuration in `pyproject.toml`).
 - Type hints throughout; `mypy` configuration in `pyproject.toml`.
-- Changes are recorded in [`CHANGELOG.md`](CHANGELOG.md); known issues and recommended native work in [`docs/AUDIT.md`](docs/AUDIT.md).
+- Changes are recorded in [`docs/CHANGELOG.md`](docs/CHANGELOG.md); known issues and recommended native work in [`docs/AUDIT.md`](docs/AUDIT.md).
 - Changes to `lib/deepgpr.h` must be mirrored in `src/DeepGPR/native/abi.py`; `tests/test_native_abi.py` enforces it.
 
 ## Citation

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

@@ -8,10 +8,10 @@ DeepGPR provides a wave propagation module for PyTorch, designed for application
 
 - 2D and 3D forward modeling of Maxwell's equations with the Finite-Difference Time-Domain (FDTD) method, for single and multiple excitations.
 - Gradients of the receiver data with respect to relative permittivity, conductivity, the initial wavefield and the source amplitudes, computed by an exact discrete adjoint.
-- 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.
+- Automatic extension of the physical model into a CPML with an independent thickness on every face. Supply only air and the target region; sensitivities from replicated PML materials are summed back to the input model edges. Absorption uses a fixed `pml_max_velocity` reference (vacuum light speed by default).
 - 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), FP16/BF16 or GPU-native INT8 wavefield histories and asynchronous offload to host memory. Material gradients with PML require `wavefield_history_region="extended"`; physical-only histories remain available for diagnostics, source/initial-state gradients and models without PML. See [`docs/API.md`](docs/API.md) §4.3-4.6.
 
 ## System requirements
 
@@ -32,8 +32,7 @@ pip install "DeepGPR[examples]"     # + scipy, scikit-image, jupyter for the not
 For development from a clone:
 
 ```bash
-pip install -r requirements-dev.txt
-pip install -e .
+pip install -e ".[dev,examples]"
 ```
 
 The prebuilt native libraries ship in `src/DeepGPR/lib`. To rebuild them see [`docs/BUILDING.md`](docs/BUILDING.md).
@@ -78,7 +77,7 @@ DeepGPR.visualization.plot_model(eps_r.grad, ax=ax[1], title="Gradient", cmap="s
 plt.show()
 ```
 
-![result](Fig/example.png)
+![result](docs/Fig/example.png)
 
 More examples are in [`examples/`](examples) (forward modeling, 2D FWI, 3D FWI).
 
@@ -105,15 +104,15 @@ The figures show the true model, the initial model and the inverted result.
 
 | True model | Initial model | Inverted result |
 | --- | --- | --- |
-| ![2D true model](Fig/2dfwitrue.png) | ![2D initial model](Fig/2dfwiinit.png) | ![2D inverted result](Fig/2dfwipred.png) |
+| ![2D true model](docs/Fig/2dfwitrue.png) | ![2D initial model](docs/Fig/2dfwiinit.png) | ![2D inverted result](docs/Fig/2dfwipred.png) |
 
 ### 3D FWI (central slice)
 
 | Model | Central slice |
 | --- | --- |
-| True model | ![3D true model central slice](Fig/3dfwitrue.png) |
-| Initial model | ![3D initial model central slice](Fig/3dfwiinit.png) |
-| Inverted result | ![3D inverted result central slice](Fig/3dfwipred.png) |
+| True model | ![3D true model central slice](docs/Fig/3dfwitrue.png) |
+| Initial model | ![3D initial model central slice](docs/Fig/3dfwiinit.png) |
+| Inverted result | ![3D inverted result central slice](docs/Fig/3dfwipred.png) |
 
 ## API overview
 
@@ -126,6 +125,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 |
@@ -161,10 +161,10 @@ src/DeepGPR/
 ├── utils/                 logging, exceptions, validators, diagnostics
 ├── lib/                   deepgpr.cu, deepgpr_cpu.c, deepgpr.h and prebuilt binaries
 ├── common.py, compute2.py, multiscale.py, wavelet.py   compatibility modules
-docs/                      API reference, build guide, code audit
+docs/                      API reference, build guide, changelog, manifest and Fig/
 examples/                  forward, 2D FWI and 3D FWI notebooks
 tests/                     unit tests, verification notebooks, benchmarks
-tools/                     verify_equivalence.py
+website/                   static pages, assets, scripts/, tools/ and promo_pixel/
 ```
 
 Data flow of one `compute` call:
@@ -179,8 +179,8 @@ and the saved history.
 python -m unittest discover -s tests -p "test_*.py"     # unit tests
 python -m unittest tests/test_native_abi.py             # ABI check, no PyTorch needed
 python tests/run_notebook.py tests/00_local_backend_and_contracts.ipynb
-python tools/verify_equivalence.py --reference-src /path/to/DeepGPR-0.0.20/src/DeepGPR
-bash tools/run_local_validation.sh /path/to/DeepGPR-0.0.20   # rebuild CPU+CUDA libs, run everything
+python website/tools/verify_equivalence.py --no-pml --reference-src /path/to/DeepGPR-0.0.20/src/DeepGPR
+bash website/tools/run_local_validation.sh /path/to/DeepGPR-0.0.20   # rebuild CPU+CUDA libs, run everything
 ```
 
 Run the notebooks `00` to `09` in numeric order, followed by
@@ -188,20 +188,22 @@ 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
-TV (see [`CHANGELOG.md`](CHANGELOG.md)). Use `apply_filter(..., legacy=True)`,
+TV (see [`docs/CHANGELOG.md`](docs/CHANGELOG.md)). Use `apply_filter(..., legacy=True)`,
 `design_fir_filter(..., legacy=True)`, `hilbert_transform(..., legacy=True)`
 and `TVRegularization(method="legacy_isotropic")` to reproduce earlier numbers.
 
 ## Development
 
-- Code style: PEP 8, enforced with `ruff check src/DeepGPR tools` (configuration in `pyproject.toml`).
+- Code style: PEP 8, enforced with `ruff check src/DeepGPR website/tools docs/build_support.py` (configuration in `pyproject.toml`).
 - Type hints throughout; `mypy` configuration in `pyproject.toml`.
-- Changes are recorded in [`CHANGELOG.md`](CHANGELOG.md); known issues and recommended native work in [`docs/AUDIT.md`](docs/AUDIT.md).
+- Changes are recorded in [`docs/CHANGELOG.md`](docs/CHANGELOG.md); known issues and recommended native work in [`docs/AUDIT.md`](docs/AUDIT.md).
 - Changes to `lib/deepgpr.h` must be mirrored in `src/DeepGPR/native/abi.py`; `tests/test_native_abi.py` enforces it.
 
 ## Citation

{deepgpr-0.1.0 → deepgpr-0.1.3/docs}/CHANGELOG.md

@@ -4,11 +4,131 @@ 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
+
+### Repository layout
+
+- Website tools, statistics scripts and pixel film sources now live under
+  `website/tools`, `website/scripts` and `website/promo_pixel`. Their input/output
+  paths and CI commands follow the new locations; Pages publishes public assets
+  without the source tool directories.
+- Figures, changelog and the source-distribution template now live in `docs`.
+  The setuptools build hook reads `docs/MANIFEST.in`, including when building a
+  wheel from a source archive. Documentation and package metadata links updated.
+- Development dependencies are installed with `pip install -e ".[dev,examples]"`.
+  Removed the duplicate development requirements file and local assistant
+  configuration, and cleaned embedded tool attribution from media metadata.
+
+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 physical cells for forward diagnostics,
+  source/initial-state gradients, or models without PML. Material inversion
+  with PML requires `"extended"`. 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 async-offload calls reuse streams, synchronization events and staging
+  buffers (audit N-8). Workspaces are exclusive to each call, partitioned by
+  device, and cached only after successful synchronization. At most one idle
+  workspace with up to 64 MiB of staging is retained per device;
+  `DeepGPR.clear_cuda_resource_cache(device=None)` releases idle resources.
+  Native forward/backward signatures and ABI 6 are unchanged. Measurements:
+  [CUDA resource cache report](../tests/profiling_results/cuda_resource_cache_report.md).
+- 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
+
+- PML materials remain derived from the physical model, with CPU/CUDA material
+  sensitivities retained throughout PML and summed back to model edges,
+  intersections and corners. Absorbing profiles use `pml_max_velocity`, a fixed
+  reference speed (default vacuum), instead of changing boundary material
+  averages. Keep it fixed during optimization, FD checks and checkpointing.
+  Old native libraries are rejected for PML material gradients via the new
+  `deepgpr_supports_pml_material_gradients` probe; ABI 6 is unchanged.
+- Exactly zero local material sensitivities remain zero even when an
+  unobservable outer-CPML state cotangent overflows in long lossless runs.
+  CPU, CUDA and INT8 avoid `0 * Inf` without clipping nonzero sensitivities
+  or changing the forward equations. Arbitrary long-time initial-state
+  cotangents can still overflow on these outer cells.
+- Corrected material gradients at Yee components that do not execute the base
+  electric update; source and CPML corrections still contribute through `cb`.
+- Total variation losses preserve the input dtype, including float64.
+- 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
 documented code base and fixes the defects found in the review
-([`docs/AUDIT.md`](docs/AUDIT.md)).
+([`docs/AUDIT.md`](AUDIT.md)).
 
 **What changes numerically** (all deliberate, see [Numerical fixes](#numerical-fixes)):
 
@@ -117,7 +237,7 @@ from the 0.1.0 sources. The CUDA (`deepgpr.so`, `deepgpr.dll`) and the Windows /
 macOS CPU binaries are still the 0.0.20 builds until the *Build Native
 Libraries* workflow runs; they load and compute as before but without error
 reporting (and, for the CPU ones, without the deterministic adjoint).
-`tools/run_local_validation.sh` rebuilds the CPU and CUDA libraries locally
+`website/tools/run_local_validation.sh` rebuilds the CPU and CUDA libraries locally
 and runs the full validation.
 
 ### Fixed
@@ -149,7 +269,7 @@ and runs the full validation.
   (same `forward_wavefield_HH-MM[_NN].pt` scheme). Partially written files are
   removed on failure.
 - **Invalid requirement shipped in the wheel.** `src/DeepGPR/requirements.txt`
-  contained `torch+cu` and was packaged via `MANIFEST.in`; removed.
+  contained `torch+cu` and was packaged via `docs/MANIFEST.in`; removed.
 - Error message of `apply_filter` used full-width punctuation (`。`).
 
 ### Changed
@@ -215,7 +335,7 @@ measurable:
 - `tests/test_signal_and_regularization.py` (FIR, envelope and TV against
   independent NumPy implementations; legacy switches).
 - `tests/test_cpu_determinism.py` (bitwise equality for 1, 2 and 5 threads).
-- `tools/verify_equivalence.py` (comparison with a reference release: forward
+- `website/tools/verify_equivalence.py` (comparison with a reference release: forward
   and gradient tolerances, legacy reproduction, determinism, error reporting).
 - `legacy=` keyword for `design_fir_filter`, `apply_filter`,
   `hilbert_transform`; `remove_dc=` for `hilbert_transform`; `epsilon=` and
@@ -223,7 +343,7 @@ measurable:
 - Native functions `deepgpr_supports_error_reporting`, `deepgpr_last_error`,
   `deepgpr_clear_last_error`, `deepgpr_deterministic_adjoint` (ABI 6, additive).
 - `.github/workflows/quality.yml` (ruff, ABI test, CPU unit tests, equivalence).
-- `requirements.txt`, `requirements-dev.txt`, ruff/mypy/pytest configuration.
+- `requirements.txt`, development extras in `pyproject.toml`, ruff/mypy/pytest configuration.
 
 ### Removed / internal changes
 
@@ -268,7 +388,7 @@ which is byte-identical to the 0.0.21 PyPI release):
 
 | Check | Scope | Result |
 |---|---|---|
-| `tools/verify_equivalence.py` | CPU and CUDA: 2D/3D × order 2/4/8 × fp32/fp16/bf16 × sampling 1/3, no/asymmetric PML, forward-only, mode 3, checkpoint segments; CUDA INT8 (2D/3D), async offload, fp16 conversion backends; legacy switches; error reporting; CPU determinism for 1/2/4/8 threads | all passed; forward outputs **bitwise identical**, gradients within 1.9·10⁻⁶ (CPU) / 4.7·10⁻⁷ (CUDA) relative |
+| `website/tools/verify_equivalence.py` | CPU and CUDA: 2D/3D × order 2/4/8 × fp32/fp16/bf16 × sampling 1/3, no/asymmetric PML, forward-only, mode 3, checkpoint segments; CUDA INT8 (2D/3D), async offload, fp16 conversion backends; legacy switches; error reporting; CPU determinism for 1/2/4/8 threads | all passed; forward outputs **bitwise identical**, gradients within 1.9·10⁻⁶ (CPU) / 4.7·10⁻⁷ (CUDA) relative |
 | Unit tests | 105 tests, `OMP_NUM_THREADS` = 1, 2, 4, 8 | all passed (1 skip: needs two GPUs) |
 | Verification notebooks `tests/00`–`09`, `99` | `DEEPGPR_REQUIRE_CUDA=1` | 108 checks passed, CUDA parity evidence present |
 | CI simulation | Python 3.12, PyTorch 2.x CPU: unit tests and `verify_equivalence.py --device cpu --quick`; `ruff check src/DeepGPR tools` | all passed |

{deepgpr-0.1.0 → deepgpr-0.1.3/docs}/MANIFEST.in

@@ -1,5 +1,4 @@
 include README.md
-include CHANGELOG.md
 include license
 include pyproject.toml
 include requirements.txt
@@ -9,14 +8,17 @@ recursive-include src/DeepGPR *.py *.typed *.cu *.h *.c *.dll *.so *.dylib
 # Exclude local state and repository-only resources.
 prune .*
 prune validation
-prune Fig
 prune docs
 prune examples
-prune scripts
 prune tests
-prune tools
 prune website
 
+# Keep the relocated manifest and its build hook available in the sdist.
+include docs/MANIFEST.in
+include docs/build_support.py
+include docs/CHANGELOG.md
+recursive-include docs/Fig *.png
+
 global-exclude .DS_Store
 global-exclude *.py[cod]
 global-exclude __pycache__

deepgpr-0.1.3/docs/build_support.py

@@ -0,0 +1,20 @@
+"""Keep the source-distribution manifest alongside the project documentation."""
+
+from pathlib import Path
+
+from setuptools.command.egg_info import egg_info, manifest_maker
+
+
+class EggInfo(egg_info):
+    """Use docs/MANIFEST.in when setuptools generates the source file list."""
+
+    def find_sources(self):
+        template = Path("docs/MANIFEST.in")
+        if not template.is_file():
+            raise FileNotFoundError("Source distribution template missing: docs/MANIFEST.in")
+        maker = manifest_maker(self.distribution)
+        maker.ignore_egg_info_dir = self.ignore_egg_info_in_manifest
+        maker.template = str(template)
+        maker.manifest = str(Path(self.egg_info) / "SOURCES.txt")
+        maker.run()
+        self.filelist = maker.filelist

{deepgpr-0.1.0 → deepgpr-0.1.3}/pyproject.toml

@@ -39,12 +39,15 @@ dev = ["ruff>=0.5", "mypy>=1.8", "pytest>=7", "nbformat", "nbclient"]
 Homepage = "https://github.com/songc0a/DeepGPR"
 Repository = "https://github.com/songc0a/DeepGPR"
 Documentation = "https://songc0a.github.io/DeepGPR/"
-Changelog = "https://github.com/songc0a/DeepGPR/blob/main/CHANGELOG.md"
+Changelog = "https://github.com/songc0a/DeepGPR/blob/main/docs/CHANGELOG.md"
 
 [tool.setuptools]
-package-dir = { "" = "src" }
+package-dir = { "" = "src", docs = "docs" }
 include-package-data = true
 
+[tool.setuptools.cmdclass]
+egg_info = "docs.build_support.EggInfo"
+
 [tool.setuptools.dynamic]
 version = { attr = "DeepGPR._version.__version__" }
 
@@ -77,8 +80,8 @@ DeepGPR = [
 [tool.ruff]
 line-length = 100
 target-version = "py38"
-src = ["src", "tests", "tools"]
-extend-exclude = ["tests/*.ipynb", "examples", "website", "scripts"]
+src = ["src", "tests", "website/tools"]
+extend-exclude = ["tests/*.ipynb", "examples", "website/assets", "website/scripts", "website/promo_pixel"]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "B", "UP", "SIM", "C4"]

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

@@ -34,6 +34,7 @@ from __future__ import annotations
 from . import config, utils
 from ._version import __version__
 from .native.loader import (
+    clear_cuda_resource_cache,
     get_deepgpr_lib,
     get_deepgpr_library_path,
     set_library_fdtd_order,
@@ -66,6 +67,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,
@@ -96,6 +98,7 @@ __all__ = [
     "check_cfl",
     "check_tensors_for_nan_inf",
     "checkpoint_initial_field",
+    "clear_cuda_resource_cache",
     "common",
     "compute",
     "compute2",
@@ -122,10 +125,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.3}/src/DeepGPR/_version.py

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

{deepgpr-0.1.0 → deepgpr-0.1.3}/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",
 ]