DeepGPR 0.1.1__tar.gz → 0.1.3__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: DeepGPR
-Version: 0.1.1
+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 (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.
+- 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
 
@@ -198,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:
@@ -216,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
@@ -232,15 +231,15 @@ 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.1 → 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 (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.
+- 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
 
@@ -162,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:
@@ -180,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
@@ -196,15 +195,15 @@ 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.1 → deepgpr-0.1.3/docs}/CHANGELOG.md

@@ -6,8 +6,21 @@ All notable changes to this project are documented here. The format follows
 
 ## [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).
+[`tests/profiling_results/history_adjoint_gpu_report.md`](../tests/profiling_results/history_adjoint_gpu_report.md).
 
 ### Added
 
@@ -29,14 +42,21 @@ Measurements, protocol and per-item decisions:
   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
+  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
@@ -75,6 +95,21 @@ Measurements, protocol and per-item decisions:
 
 ### 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.
@@ -93,7 +128,7 @@ Measurements, protocol and per-item decisions:
 
 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)):
 
@@ -202,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
@@ -234,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
@@ -300,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
@@ -308,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
 
@@ -353,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.1 → 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.1 → 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.1 → 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,
@@ -97,6 +98,7 @@ __all__ = [
     "check_cfl",
     "check_tensors_for_nan_inf",
     "checkpoint_initial_field",
+    "clear_cuda_resource_cache",
     "common",
     "compute",
     "compute2",

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

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

{deepgpr-0.1.1 → deepgpr-0.1.3}/src/DeepGPR/inversion/regularization.py

@@ -137,7 +137,7 @@ class TVRegularization(nn.Module):
             raise ValueError("TVRegularization needs at least one of ep or sigma.")
         reference = ep if ep is not None else sigma
         assert reference is not None
-        loss = torch.tensor(0.0, device=reference.device)
+        loss = reference.new_zeros(())
         if ep is not None and self.weight_ep > 0:
             loss += self.weight_ep * self._compute_tv(ep)
         if sigma is not None and self.weight_sigma > 0:

deepgpr-0.1.3/src/DeepGPR/lib/cuda_resources.h

@@ -0,0 +1,156 @@
+#ifndef DEEPGPR_CUDA_RESOURCES_H
+#define DEEPGPR_CUDA_RESOURCES_H
+
+#include <cuda_runtime.h>
+#include <list>
+#include <mutex>
+#include <new>
+#include <utility>
+
+/* A workspace is leased exclusively to one native call. Only drained,
+ * successful calls return it to the cache; histories remain caller-owned. */
+struct CudaAsyncWorkspace {
+    int device = -1;
+    unsigned char* e = nullptr;
+    unsigned char* r = nullptr;
+    size_t e_capacity = 0;
+    size_t r_capacity = 0;
+    cudaStream_t streams[2] = {nullptr, nullptr};
+    cudaEvent_t events[4] = {nullptr, nullptr, nullptr, nullptr};
+
+    CudaAsyncWorkspace() = default;
+    CudaAsyncWorkspace(const CudaAsyncWorkspace&) = delete;
+    CudaAsyncWorkspace& operator=(const CudaAsyncWorkspace&) = delete;
+
+    void swap(CudaAsyncWorkspace& other) noexcept
+    {
+        std::swap(device, other.device);
+        std::swap(e, other.e);
+        std::swap(r, other.r);
+        std::swap(e_capacity, other.e_capacity);
+        std::swap(r_capacity, other.r_capacity);
+        for (int i = 0; i < 2; ++i) std::swap(streams[i], other.streams[i]);
+        for (int i = 0; i < 4; ++i) std::swap(events[i], other.events[i]);
+    }
+
+    ~CudaAsyncWorkspace()
+    {
+        if (device < 0) return;
+        int previous;
+        // During runtime shutdown CUDA may already be unavailable.
+        if (cudaGetDevice(&previous) != cudaSuccess) return;
+        if (previous != device && cudaSetDevice(device) != cudaSuccess) return;
+        for (auto stream : streams) {
+            if (stream) cudaStreamSynchronize(stream);
+        }
+        if (e) cudaFree(e);
+        if (r) cudaFree(r);
+        for (auto event : events) {
+            if (event) cudaEventDestroy(event);
+        }
+        for (auto stream : streams) {
+            if (stream) cudaStreamDestroy(stream);
+        }
+        if (previous != device) cudaSetDevice(previous);
+    }
+
+    static cudaError_t reserve(unsigned char*& pointer, size_t& capacity, size_t bytes)
+    {
+        if (bytes <= capacity) return cudaSuccess;
+        // The old workspace is idle. Release before growing to avoid holding
+        // both old and new allocations at peak memory usage.
+        if (pointer) {
+            cudaError_t error = cudaFree(pointer);
+            if (error != cudaSuccess) return error;
+            pointer = nullptr;
+            capacity = 0;
+        }
+        cudaError_t error = cudaMalloc(&pointer, bytes);
+        if (error == cudaSuccess) capacity = bytes;
+        return error;
+    }
+
+    cudaError_t prepare(size_t e_bytes, size_t r_bytes)
+    {
+        for (auto& stream : streams) {
+            if (!stream) {
+                cudaError_t error = cudaStreamCreate(&stream);
+                if (error != cudaSuccess) return error;
+            }
+        }
+        for (auto& event : events) {
+            if (!event) {
+                cudaError_t error = cudaEventCreateWithFlags(&event, cudaEventDisableTiming);
+                if (error != cudaSuccess) return error;
+            }
+        }
+        cudaError_t error = reserve(e, e_capacity, e_bytes);
+        if (error != cudaSuccess) return error;
+        return reserve(r, r_capacity, r_bytes);
+    }
+};
+
+class CudaAsyncCache {
+    std::mutex mutex_;
+    std::list<CudaAsyncWorkspace> idle_;
+
+public:
+    // Retain at most one idle workspace and 64 MiB of staging per device.
+    // Oversized calls still run, but their workspace is released on return.
+    static constexpr size_t max_bytes = 64 * size_t(1024) * 1024;
+
+    void take(int device, CudaAsyncWorkspace& workspace)
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (auto it = idle_.begin(); it != idle_.end(); ++it) {
+            if (it->device == device) {
+                workspace.swap(*it);
+                idle_.erase(it);
+                return;
+            }
+        }
+        workspace.device = device;
+    }
+
+    void put(CudaAsyncWorkspace& workspace)
+    {
+        if (workspace.e_capacity > max_bytes
+            || workspace.r_capacity > max_bytes - workspace.e_capacity) return;
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (const auto& entry : idle_) {
+            if (entry.device == workspace.device) return;
+        }
+        // A cache miss must not turn a successful solver call into an error.
+        try {
+            idle_.emplace_back();
+        } catch (const std::bad_alloc&) {
+            return;
+        }
+        idle_.back().swap(workspace);
+    }
+
+    void clear(int device)
+    {
+        CudaAsyncWorkspace discarded;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            for (auto it = idle_.begin(); it != idle_.end(); ++it) {
+                if (it->device == device) {
+                    discarded.swap(*it);
+                    idle_.erase(it);
+                    break;
+                }
+            }
+        }
+        // CUDA calls happen outside the lock. Active calls own separate
+        // workspaces and may repopulate the cache after clear() returns.
+    }
+};
+
+inline CudaAsyncCache& cuda_async_cache()
+{
+    static CudaAsyncCache cache;
+    return cache;
+}
+
+#endif