DeepGPR 0.0.14__tar.gz → 0.0.16__tar.gz

{deepgpr-0.0.14 → deepgpr-0.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeepGPR
-Version: 0.0.14
+Version: 0.0.16
 Summary: PyTorch and CUDA for GPR FWI
 Author-email: Lei Liu <liulei990222@gmail.com>
 License-Expression: MIT
@@ -72,7 +72,7 @@ import matplotlib.pyplot as plt
 
 # Set up the parameters and models
 device=torch.device("cuda" if torch.cuda.is_available() else "cpu")
-dx=0.02
+dx=0.02  # Or [dx, dy, dz], for example [0.02, 0.015, 0.01]
 dt=3e-11
 nt=2000
 er = torch.ones(100, 100,1) * 2  
@@ -84,7 +84,9 @@ receiver_location=torch.tensor([[[10,90,0]]],device=device,dtype=torch.int)
 freq=2e8
 peak_time = 1 / freq
 source_amplitudes = torch.zeros((1,nt,1),device=device)
-source_amplitudes[0,:,0]=DeepGPR.ricker(freq, nt, dt, peak_time).to(device)
+source_amplitudes[0,:,0]=DeepGPR.wavelet.ricker(
+    freq, nt, dt, peak_time, device=device
+)
 
 
 #forward modeling
@@ -111,6 +113,28 @@ plt.show()
 
 There are more examples in the ./examples.
 
+## Source Wavelets
+
+Wavelets are available from the `DeepGPR.wavelet` module. Every function
+returns a one-dimensional PyTorch tensor and accepts optional `dtype` and
+`device` arguments.
+
+```python
+ricker = DeepGPR.wavelet.ricker(freq, nt, dt, peak_time, device=device)
+gaussian = DeepGPR.wavelet.gaussian(freq, nt, dt, peak_time, device=device)
+derivative = DeepGPR.wavelet.gaussian_derivative(
+    freq, nt, dt, peak_time, device=device
+)
+morlet = DeepGPR.wavelet.morlet(
+    freq, nt, dt, peak_time, cycles=3.0, device=device
+)
+burst = DeepGPR.wavelet.sine_burst(
+    freq, nt, dt, peak_time, cycles=3.0, device=device
+)
+```
+
+`DeepGPR.ricker(...)` remains available as a backward-compatible alias.
+
 
 
 The following figures present representative 2D and 3D full-waveform inversion (FWI) examples. For each case, the true model, initial model, and inverted result are shown to evaluate the reconstruction performance of the proposed method.
@@ -148,31 +172,48 @@ def compute(device, dx=None, dt=None,
             E=None, H=None, PML=None,
             pmlthick=10, source_direction=2, reciever_direction=2,
             model_gradient_sampling_interval=1,
+            wavefield_storage_dtype=torch.float32,
             use_async_offload=False,
             fdtd_order=2,
             mode=2,
-            debug=False):
+            debug=False,
+            print_parameters=False,
+            save_forward_wavefield_path=None):
 ```
+
+Set `print_parameters=True` on an ordinary call to print the normalized
+configuration and memory estimate immediately before the native solver starts:
+
+```python
+result = DeepGPR.compute(
+    device="cuda:0",
+    # Other model, source, and acquisition arguments...
+    print_parameters=True,
+)
+```
+
 ## 📥 Input Parameters
 ### 1. Basic Physics & Grid Parameters
 
 | Parameter | Data Type | Description |
 | :--- | :--- | :--- |
 | **`device`** | `torch.device` / `str` | PyTorch computation device, e.g., `'cuda:0'` or `'cpu'`. CUDA loads `deepgpr.so/.dll`; CPU loads `deepgpr_cpu.so/.dll/.dylib`. |
-| **`dx`** | `float` | Spatial grid step size (assuming an isotropic grid, i.e., $dx = dy = dz$). Typically in meters (m). |
-| **`dt`** | `float` | Time step size. **Note**: Must strictly satisfy the CFL (Courant-Friedrichs-Lewy) stability condition, or an exception will be raised. Typically in seconds (s). |
+| **`dx`** | `float` / 3-value `list`, `tuple`, or `Tensor` | Grid spacing in meters. A scalar uses an isotropic grid ($dx = dy = dz$). Three values specify independent $(dx, dy, dz)$ spacings for the finite differences, CFL condition, CPML coefficients, and source scaling. |
+| **`dt`** | `float` | Time step size. It is checked against a material-aware CFL limit that includes the selected 2/4/8-order stencil. Typically in seconds (s). |
 | **`fdtd_order`** | `int` | Spatial finite-difference order used by the FDTD field updates. Supported values are `2`, `4`, and `8`; default is `2` for compatibility with earlier versions. |
 | **`mode`** | `int` | FWI gradient mode. `2` keeps the previous Ez-only model-gradient calculation. `3` uses Ex, Ey, and Ez electric-field contributions for relative permittivity and conductivity gradients. |
-| **`debug`** | `bool` | Runs expensive NaN/Inf and zero-field validation checks when `True`. The default `False` keeps these checks disabled for faster production runs. |
+| **`debug`** | `bool` | Runs expensive NaN/Inf and zero-field validation checks when `True`. Backward validation covers material, source, and initial-state gradients actually requested by autograd. The default `False` keeps these checks disabled for faster production runs. |
+| **`print_parameters`** | `bool` | Prints a preflight summary before native FDTD execution. The summary includes all simulation options and a tensor-payload memory estimate for model/state tensors, CPML, saved `E_saved`/`R_saved` wavefields, receiver buffers, gradients, low-precision snapshots, and CUDA offload buffers. CPU and CUDA estimates are reported separately with a 20% capacity margin. |
+| **`save_forward_wavefield_path`** | `str` / path-like / `None` | Directory used to save `E_saved` after a successful forward run. The default `None` performs no file I/O. Files use the local 24-hour start time, for example `forward_wavefield_14-35.pt`; a numeric suffix prevents overwriting when multiple runs start in the same minute. |
 ### 2. Medium Model Parameters
 
 This section defines the electromagnetic properties of the simulation space. For 2D simulations, set `nz=1`.
 
 | Parameter | Data Type | Shape | Description |
 | :--- | :--- | :--- | :--- |
-| **`er`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permittivity ($\epsilon_r$). Values must be $\ge 1$. |
-| **`se`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Electrical conductivity ($\sigma$). Values must be non-negative. |
-| **`mr`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permeability ($\mu_r$). Optional; defaults to 1 for the entire space. Shape must match `er`. |
+| **`eps_r`** (`er`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permittivity ($\epsilon_r$). Values must be $\ge 1$. `er` is the deprecated alias. |
+| **`sigma`** (`se`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Electrical conductivity ($\sigma$). Values must be non-negative. `se` is the deprecated alias. |
+| **`mu_r`** (`mr`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permeability ($\mu_r$). Optional; defaults to 1 for the entire space. `mr` is the deprecated alias. |
 
 > **Dimension Key**: `nx`, `ny`, and `nz` represent the number of grid cells along the X, Y, and Z axes, respectively. 
 
@@ -186,7 +227,7 @@ This section defines the geometric observation system (coordinates) and the exci
 | **`source_location`** | `Tensor` (int) | `(nstep, nsr, 3)` | Grid coordinate indices of the sources.<br>The last dimension corresponds to `[x_idx, y_idx, z_idx]`. |
 | **`receiver_location`** | `Tensor` (int) | `(nstep, nrx, 3)` | Grid coordinate indices of the receivers.<br>The last dimension corresponds to `[x_idx, y_idx, z_idx]`. |
 | **`source_direction`** | `int` | Scalar | Polarization direction/component of the source excitation.<br>`0` = X, `1` = Y, `2` = Z (e.g., exciting $E_z$). |
-| **`reciever_direction`** | `int` | Scalar | The component direction recorded by the receivers. (Note: typo in variable name is kept as-is to match code).<br>`0` = $E_x$, `1` = $E_y$, `2` = $E_z$. |
+| **`receiver_component`** (`reciever_direction`) | `int` | Scalar | The component recorded by the receivers.<br>`0` = $E_x$, `1` = $E_y$, `2` = $E_z$. The misspelled name remains as a deprecated alias. |
 
 > **Core Shape Definitions**:
 > *   `nstep`: Number of shots/batches (independent simulation tasks running in parallel).
@@ -199,15 +240,26 @@ This section defines the geometric observation system (coordinates) and the exci
 | Parameter | Data Type | Format | Description |
 | :--- | :--- | :--- | :--- |
 | **`pmlthick`** | `int` / `list` / `Tensor`| Scalar or list of 6 | Thickness (in grid layers) of the PML (Perfectly Matched Layer) absorbing boundaries.<br>- Integer `p`: All six boundaries have thickness `p` (Z-boundaries are ignored in 2D).<br>- List `[x0, xm, y0, ym, z0, zm]`: Specific thicknesses for the 6 boundaries. |
-| **`model_gradient_sampling_interval`**| `int` | Scalar | Wavefield sampling interval during forward propagation (Default: 1).<br>A larger integer reduces the VRAM usage for the saved `Eall` tensor, but may decrease the accuracy of backpropagated gradients. |
-| **`use_async_offload`** | `bool` | Scalar | CUDA-only VRAM optimization flag (Default: `False`).<br>If `True`, the internal full wavefield tensor (`Eall`) is asynchronously offloaded to page-locked host memory (`pin_memory` CPU RAM). This drastically reduces GPU VRAM consumption at the cost of slightly slower computation times due to PCIe data transfer latency. On CPU this option is ignored. |
+| **`model_gradient_sampling_interval`**| `int` | Scalar | Wavefield sampling interval during forward propagation (Default: 1).<br>A larger integer reduces VRAM use for `E_saved` and `R_saved`, but uses an explicitly approximate model gradient. The last incomplete sampling block is weighted by its actual length. |
+| **`wavefield_storage_dtype`** | `torch.dtype` / `str` | `float32`, `float16`, or `bfloat16` | Storage format for saved `E_saved` and `R_saved` model-gradient wavefields. FDTD propagation remains float32. `float16` and `bfloat16` halve saved-wavefield memory at the cost of gradient accuracy; `bfloat16` has the safer dynamic range. String aliases such as `"fp16"` and `"bf16"` are accepted. |
+| **`use_async_offload`** | `bool` | Scalar | CUDA-only VRAM optimization flag (Default: `False`).<br>If `True`, `E_saved` and `R_saved` are asynchronously offloaded to page-locked host memory (`pin_memory` CPU RAM). This reduces GPU VRAM consumption at the cost of PCIe transfers. On CPU this option is ignored. |
 
 ### 4.1 FWI Gradient Mode
 
 `mode` only changes how the model gradients are accumulated during backpropagation:
 
-- `mode=2` (default): Saves Ez in `Eall` and computes relative permittivity/conductivity gradients from Ez only. This keeps the old behavior.
-- `mode=3`: Saves Ex, Ey, and Ez in `Eall` and computes relative permittivity/conductivity gradients from all three electric-field components. This is intended for complete 3D Maxwell FWI. The adjoint source polarization is not changed by this option.
+- `mode=2` (default): Saves Ez in `E_saved` and computes relative permittivity/conductivity gradients from Ez only.
+- `mode=3`: Saves Ex, Ey, and Ez in `E_saved` and computes relative permittivity/conductivity gradients from all three electric-field components. This is intended for complete 3D Maxwell FWI. The receiver component is not changed by this option.
+
+When `eps_r` or `sigma` requires gradients, `mode=2` is restricted to 2D Ez-TM modeling; use `mode=3` for 3D gradients. Source-waveform gradients are supported. Gradients with respect to `mu_r` are not currently implemented and are rejected explicitly.
+
+### 4.2 Discrete Adjoint Gradient
+
+The backward solver applies the exact reverse-mode transpose of each executed operation in reverse order: receiver sampling, source injection, electric CPML, electric update, magnetic CPML, and magnetic update. The derivative transpose is applied to the material-weighted field cotangent, so heterogeneous update coefficients and anisotropic grid spacing are handled by the executed discrete operator. Every electric and magnetic CPML auxiliary state has a separate cotangent recurrence on all six faces.
+
+CPML is treated as a fixed numerical boundary. Its boundary material averages are explicitly detached, and CPML cells are excluded from the returned material gradients. This separation must be retained when optimizing a model.
+
+Use `model_gradient_sampling_interval=1` and `wavefield_storage_dtype=torch.float32` for a directional derivative check in the physical model region. Temporal subsampling and lower-precision storage deliberately approximate the gradient. Run [the gradient-check notebook](examples/4.GradientCheck.ipynb) after rebuilding the native ABI 6 libraries.
 
 ## CPU Backend Build
 
@@ -253,20 +305,36 @@ For starting a forward simulation from scratch ($t=0$), these three parameters s
 The function returns a tuple of 5 elements. These are used to extract synthetic data, initiate the gradient flow for backpropagation, or serve as initial parameters (`E`, `H`, `PML`) for subsequent time-stepped calculations.
 
 ```python
-return Eall, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
+return E_saved, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
 ```
 
-1.  **`Eall`**: The electric field history saved for gradient calculation.
+1.  **`E_saved`**: The pre-update electric field history `E^n` saved for gradient calculation and diagnostics. An internal `R_saved` tensor stores the corresponding discrete right-hand side `R^n`.
     *   **Shape when `mode=2`**: `(nt_saved, nstep, nx, ny, nz)`, storing Ez only.
     *   **Shape when `mode=3`**: `(3, nt_saved, nstep, nx, ny, nz)`, storing components in `[Ex, Ey, Ez]` order.
     *   `nt_saved` depends on `nt` and `model_gradient_sampling_interval`.
+    *   Dtype is selected by `wavefield_storage_dtype`.
+    *   Set `save_forward_wavefield_path="/path/to/output"` to save this tensor as a CPU-loadable `.pt` file. Load it with `torch.load(path, map_location="cpu")`.
 2.  **`(Ex, Ey, Ez)`**: The 3D electric field state at the final time step. 
 3.  **`(Hx, Hy, Hz)`**: The 3D magnetic field state at the final time step.
 4.  **`(PML_Tuple)`**: A tuple of 24 Tensors recording the final time step state of the PML auxiliary $\Phi$ variables.
 5.  **`receiver_amplitudes`**: **The core output.** The waveform signals recorded by the receivers over the entire simulation time.
     *   **Shape**: `(nstep, nt, nrx)`
-    *   **Meaning**: `[Shot Index, Time Step, Receiver Index]`. Note that this output is already sliced to extract only the component specified by `reciever_direction`.
+    *   **Meaning**: `[Shot Index, Time Step, Receiver Index]`. This output is sliced to the component specified by `receiver_component` (or its deprecated alias `reciever_direction`).
+
+
+## Tests and Verification
+
+Fast unit tests and the complete numerical verification notebooks are kept in
+the single [`tests`](tests) directory:
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+python tests/run_notebook.py tests/00_local_backend_and_contracts.ipynb
+```
 
+Run notebooks `00` through `09` in numeric order, followed by
+`99_verification_summary.ipynb`. See [`tests/README.md`](tests/README.md) for
+the complete matrix and CUDA verification options.
 
 # Cite information
 If you find our codes useful, please kindly cite this article. Thanks.

{deepgpr-0.0.14 → deepgpr-0.0.16}/README.md

@@ -49,7 +49,7 @@ import matplotlib.pyplot as plt
 
 # Set up the parameters and models
 device=torch.device("cuda" if torch.cuda.is_available() else "cpu")
-dx=0.02
+dx=0.02  # Or [dx, dy, dz], for example [0.02, 0.015, 0.01]
 dt=3e-11
 nt=2000
 er = torch.ones(100, 100,1) * 2  
@@ -61,7 +61,9 @@ receiver_location=torch.tensor([[[10,90,0]]],device=device,dtype=torch.int)
 freq=2e8
 peak_time = 1 / freq
 source_amplitudes = torch.zeros((1,nt,1),device=device)
-source_amplitudes[0,:,0]=DeepGPR.ricker(freq, nt, dt, peak_time).to(device)
+source_amplitudes[0,:,0]=DeepGPR.wavelet.ricker(
+    freq, nt, dt, peak_time, device=device
+)
 
 
 #forward modeling
@@ -88,6 +90,28 @@ plt.show()
 
 There are more examples in the ./examples.
 
+## Source Wavelets
+
+Wavelets are available from the `DeepGPR.wavelet` module. Every function
+returns a one-dimensional PyTorch tensor and accepts optional `dtype` and
+`device` arguments.
+
+```python
+ricker = DeepGPR.wavelet.ricker(freq, nt, dt, peak_time, device=device)
+gaussian = DeepGPR.wavelet.gaussian(freq, nt, dt, peak_time, device=device)
+derivative = DeepGPR.wavelet.gaussian_derivative(
+    freq, nt, dt, peak_time, device=device
+)
+morlet = DeepGPR.wavelet.morlet(
+    freq, nt, dt, peak_time, cycles=3.0, device=device
+)
+burst = DeepGPR.wavelet.sine_burst(
+    freq, nt, dt, peak_time, cycles=3.0, device=device
+)
+```
+
+`DeepGPR.ricker(...)` remains available as a backward-compatible alias.
+
 
 
 The following figures present representative 2D and 3D full-waveform inversion (FWI) examples. For each case, the true model, initial model, and inverted result are shown to evaluate the reconstruction performance of the proposed method.
@@ -125,31 +149,48 @@ def compute(device, dx=None, dt=None,
             E=None, H=None, PML=None,
             pmlthick=10, source_direction=2, reciever_direction=2,
             model_gradient_sampling_interval=1,
+            wavefield_storage_dtype=torch.float32,
             use_async_offload=False,
             fdtd_order=2,
             mode=2,
-            debug=False):
+            debug=False,
+            print_parameters=False,
+            save_forward_wavefield_path=None):
 ```
+
+Set `print_parameters=True` on an ordinary call to print the normalized
+configuration and memory estimate immediately before the native solver starts:
+
+```python
+result = DeepGPR.compute(
+    device="cuda:0",
+    # Other model, source, and acquisition arguments...
+    print_parameters=True,
+)
+```
+
 ## 📥 Input Parameters
 ### 1. Basic Physics & Grid Parameters
 
 | Parameter | Data Type | Description |
 | :--- | :--- | :--- |
 | **`device`** | `torch.device` / `str` | PyTorch computation device, e.g., `'cuda:0'` or `'cpu'`. CUDA loads `deepgpr.so/.dll`; CPU loads `deepgpr_cpu.so/.dll/.dylib`. |
-| **`dx`** | `float` | Spatial grid step size (assuming an isotropic grid, i.e., $dx = dy = dz$). Typically in meters (m). |
-| **`dt`** | `float` | Time step size. **Note**: Must strictly satisfy the CFL (Courant-Friedrichs-Lewy) stability condition, or an exception will be raised. Typically in seconds (s). |
+| **`dx`** | `float` / 3-value `list`, `tuple`, or `Tensor` | Grid spacing in meters. A scalar uses an isotropic grid ($dx = dy = dz$). Three values specify independent $(dx, dy, dz)$ spacings for the finite differences, CFL condition, CPML coefficients, and source scaling. |
+| **`dt`** | `float` | Time step size. It is checked against a material-aware CFL limit that includes the selected 2/4/8-order stencil. Typically in seconds (s). |
 | **`fdtd_order`** | `int` | Spatial finite-difference order used by the FDTD field updates. Supported values are `2`, `4`, and `8`; default is `2` for compatibility with earlier versions. |
 | **`mode`** | `int` | FWI gradient mode. `2` keeps the previous Ez-only model-gradient calculation. `3` uses Ex, Ey, and Ez electric-field contributions for relative permittivity and conductivity gradients. |
-| **`debug`** | `bool` | Runs expensive NaN/Inf and zero-field validation checks when `True`. The default `False` keeps these checks disabled for faster production runs. |
+| **`debug`** | `bool` | Runs expensive NaN/Inf and zero-field validation checks when `True`. Backward validation covers material, source, and initial-state gradients actually requested by autograd. The default `False` keeps these checks disabled for faster production runs. |
+| **`print_parameters`** | `bool` | Prints a preflight summary before native FDTD execution. The summary includes all simulation options and a tensor-payload memory estimate for model/state tensors, CPML, saved `E_saved`/`R_saved` wavefields, receiver buffers, gradients, low-precision snapshots, and CUDA offload buffers. CPU and CUDA estimates are reported separately with a 20% capacity margin. |
+| **`save_forward_wavefield_path`** | `str` / path-like / `None` | Directory used to save `E_saved` after a successful forward run. The default `None` performs no file I/O. Files use the local 24-hour start time, for example `forward_wavefield_14-35.pt`; a numeric suffix prevents overwriting when multiple runs start in the same minute. |
 ### 2. Medium Model Parameters
 
 This section defines the electromagnetic properties of the simulation space. For 2D simulations, set `nz=1`.
 
 | Parameter | Data Type | Shape | Description |
 | :--- | :--- | :--- | :--- |
-| **`er`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permittivity ($\epsilon_r$). Values must be $\ge 1$. |
-| **`se`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Electrical conductivity ($\sigma$). Values must be non-negative. |
-| **`mr`** | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permeability ($\mu_r$). Optional; defaults to 1 for the entire space. Shape must match `er`. |
+| **`eps_r`** (`er`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permittivity ($\epsilon_r$). Values must be $\ge 1$. `er` is the deprecated alias. |
+| **`sigma`** (`se`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Electrical conductivity ($\sigma$). Values must be non-negative. `se` is the deprecated alias. |
+| **`mu_r`** (`mr`) | `Tensor` (float) | `(nx, ny, nz)` or `(nx, ny)` | Relative permeability ($\mu_r$). Optional; defaults to 1 for the entire space. `mr` is the deprecated alias. |
 
 > **Dimension Key**: `nx`, `ny`, and `nz` represent the number of grid cells along the X, Y, and Z axes, respectively. 
 
@@ -163,7 +204,7 @@ This section defines the geometric observation system (coordinates) and the exci
 | **`source_location`** | `Tensor` (int) | `(nstep, nsr, 3)` | Grid coordinate indices of the sources.<br>The last dimension corresponds to `[x_idx, y_idx, z_idx]`. |
 | **`receiver_location`** | `Tensor` (int) | `(nstep, nrx, 3)` | Grid coordinate indices of the receivers.<br>The last dimension corresponds to `[x_idx, y_idx, z_idx]`. |
 | **`source_direction`** | `int` | Scalar | Polarization direction/component of the source excitation.<br>`0` = X, `1` = Y, `2` = Z (e.g., exciting $E_z$). |
-| **`reciever_direction`** | `int` | Scalar | The component direction recorded by the receivers. (Note: typo in variable name is kept as-is to match code).<br>`0` = $E_x$, `1` = $E_y$, `2` = $E_z$. |
+| **`receiver_component`** (`reciever_direction`) | `int` | Scalar | The component recorded by the receivers.<br>`0` = $E_x$, `1` = $E_y$, `2` = $E_z$. The misspelled name remains as a deprecated alias. |
 
 > **Core Shape Definitions**:
 > *   `nstep`: Number of shots/batches (independent simulation tasks running in parallel).
@@ -176,15 +217,26 @@ This section defines the geometric observation system (coordinates) and the exci
 | Parameter | Data Type | Format | Description |
 | :--- | :--- | :--- | :--- |
 | **`pmlthick`** | `int` / `list` / `Tensor`| Scalar or list of 6 | Thickness (in grid layers) of the PML (Perfectly Matched Layer) absorbing boundaries.<br>- Integer `p`: All six boundaries have thickness `p` (Z-boundaries are ignored in 2D).<br>- List `[x0, xm, y0, ym, z0, zm]`: Specific thicknesses for the 6 boundaries. |
-| **`model_gradient_sampling_interval`**| `int` | Scalar | Wavefield sampling interval during forward propagation (Default: 1).<br>A larger integer reduces the VRAM usage for the saved `Eall` tensor, but may decrease the accuracy of backpropagated gradients. |
-| **`use_async_offload`** | `bool` | Scalar | CUDA-only VRAM optimization flag (Default: `False`).<br>If `True`, the internal full wavefield tensor (`Eall`) is asynchronously offloaded to page-locked host memory (`pin_memory` CPU RAM). This drastically reduces GPU VRAM consumption at the cost of slightly slower computation times due to PCIe data transfer latency. On CPU this option is ignored. |
+| **`model_gradient_sampling_interval`**| `int` | Scalar | Wavefield sampling interval during forward propagation (Default: 1).<br>A larger integer reduces VRAM use for `E_saved` and `R_saved`, but uses an explicitly approximate model gradient. The last incomplete sampling block is weighted by its actual length. |
+| **`wavefield_storage_dtype`** | `torch.dtype` / `str` | `float32`, `float16`, or `bfloat16` | Storage format for saved `E_saved` and `R_saved` model-gradient wavefields. FDTD propagation remains float32. `float16` and `bfloat16` halve saved-wavefield memory at the cost of gradient accuracy; `bfloat16` has the safer dynamic range. String aliases such as `"fp16"` and `"bf16"` are accepted. |
+| **`use_async_offload`** | `bool` | Scalar | CUDA-only VRAM optimization flag (Default: `False`).<br>If `True`, `E_saved` and `R_saved` are asynchronously offloaded to page-locked host memory (`pin_memory` CPU RAM). This reduces GPU VRAM consumption at the cost of PCIe transfers. On CPU this option is ignored. |
 
 ### 4.1 FWI Gradient Mode
 
 `mode` only changes how the model gradients are accumulated during backpropagation:
 
-- `mode=2` (default): Saves Ez in `Eall` and computes relative permittivity/conductivity gradients from Ez only. This keeps the old behavior.
-- `mode=3`: Saves Ex, Ey, and Ez in `Eall` and computes relative permittivity/conductivity gradients from all three electric-field components. This is intended for complete 3D Maxwell FWI. The adjoint source polarization is not changed by this option.
+- `mode=2` (default): Saves Ez in `E_saved` and computes relative permittivity/conductivity gradients from Ez only.
+- `mode=3`: Saves Ex, Ey, and Ez in `E_saved` and computes relative permittivity/conductivity gradients from all three electric-field components. This is intended for complete 3D Maxwell FWI. The receiver component is not changed by this option.
+
+When `eps_r` or `sigma` requires gradients, `mode=2` is restricted to 2D Ez-TM modeling; use `mode=3` for 3D gradients. Source-waveform gradients are supported. Gradients with respect to `mu_r` are not currently implemented and are rejected explicitly.
+
+### 4.2 Discrete Adjoint Gradient
+
+The backward solver applies the exact reverse-mode transpose of each executed operation in reverse order: receiver sampling, source injection, electric CPML, electric update, magnetic CPML, and magnetic update. The derivative transpose is applied to the material-weighted field cotangent, so heterogeneous update coefficients and anisotropic grid spacing are handled by the executed discrete operator. Every electric and magnetic CPML auxiliary state has a separate cotangent recurrence on all six faces.
+
+CPML is treated as a fixed numerical boundary. Its boundary material averages are explicitly detached, and CPML cells are excluded from the returned material gradients. This separation must be retained when optimizing a model.
+
+Use `model_gradient_sampling_interval=1` and `wavefield_storage_dtype=torch.float32` for a directional derivative check in the physical model region. Temporal subsampling and lower-precision storage deliberately approximate the gradient. Run [the gradient-check notebook](examples/4.GradientCheck.ipynb) after rebuilding the native ABI 6 libraries.
 
 ## CPU Backend Build
 
@@ -230,20 +282,36 @@ For starting a forward simulation from scratch ($t=0$), these three parameters s
 The function returns a tuple of 5 elements. These are used to extract synthetic data, initiate the gradient flow for backpropagation, or serve as initial parameters (`E`, `H`, `PML`) for subsequent time-stepped calculations.
 
 ```python
-return Eall, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
+return E_saved, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
 ```
 
-1.  **`Eall`**: The electric field history saved for gradient calculation.
+1.  **`E_saved`**: The pre-update electric field history `E^n` saved for gradient calculation and diagnostics. An internal `R_saved` tensor stores the corresponding discrete right-hand side `R^n`.
     *   **Shape when `mode=2`**: `(nt_saved, nstep, nx, ny, nz)`, storing Ez only.
     *   **Shape when `mode=3`**: `(3, nt_saved, nstep, nx, ny, nz)`, storing components in `[Ex, Ey, Ez]` order.
     *   `nt_saved` depends on `nt` and `model_gradient_sampling_interval`.
+    *   Dtype is selected by `wavefield_storage_dtype`.
+    *   Set `save_forward_wavefield_path="/path/to/output"` to save this tensor as a CPU-loadable `.pt` file. Load it with `torch.load(path, map_location="cpu")`.
 2.  **`(Ex, Ey, Ez)`**: The 3D electric field state at the final time step. 
 3.  **`(Hx, Hy, Hz)`**: The 3D magnetic field state at the final time step.
 4.  **`(PML_Tuple)`**: A tuple of 24 Tensors recording the final time step state of the PML auxiliary $\Phi$ variables.
 5.  **`receiver_amplitudes`**: **The core output.** The waveform signals recorded by the receivers over the entire simulation time.
     *   **Shape**: `(nstep, nt, nrx)`
-    *   **Meaning**: `[Shot Index, Time Step, Receiver Index]`. Note that this output is already sliced to extract only the component specified by `reciever_direction`.
+    *   **Meaning**: `[Shot Index, Time Step, Receiver Index]`. This output is sliced to the component specified by `receiver_component` (or its deprecated alias `reciever_direction`).
+
+
+## Tests and Verification
+
+Fast unit tests and the complete numerical verification notebooks are kept in
+the single [`tests`](tests) directory:
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+python tests/run_notebook.py tests/00_local_backend_and_contracts.ipynb
+```
 
+Run notebooks `00` through `09` in numeric order, followed by
+`99_verification_summary.ipynb`. See [`tests/README.md`](tests/README.md) for
+the complete matrix and CUDA verification options.
 
 # Cite information
 If you find our codes useful, please kindly cite this article. Thanks.

{deepgpr-0.0.14 → deepgpr-0.0.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "DeepGPR"
-version = "0.0.14"
+version = "0.0.16"
 authors = [
     { name = "Lei Liu", email = "liulei990222@gmail.com" }
 ]

{deepgpr-0.0.14 → deepgpr-0.0.16}/src/DeepGPR/__init__.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 _FLOAT_P = ctypes.POINTER(ctypes.c_float)
 _INT_P = ctypes.POINTER(ctypes.c_int)
+_VOID_P = ctypes.c_void_p
 
 _PACKAGE_DIR = Path(__file__).resolve().parent
 _LIB_DIR = _PACKAGE_DIR / "lib"
@@ -154,8 +155,17 @@ def _configure_deepgpr_library(lib: ctypes.CDLL) -> None:
     if getattr(lib, "_deepgpr_argtypes_configured", False):
         return
 
+    lib.deepgpr_abi_version.argtypes = []
+    lib.deepgpr_abi_version.restype = ctypes.c_int
+    abi_version = int(lib.deepgpr_abi_version())
+    if abi_version != 6:
+        raise RuntimeError(
+            f"Incompatible DeepGPR native ABI {abi_version}; expected ABI 6. "
+            "Rebuild the CPU/CUDA shared libraries from the current sources."
+        )
+
     lib.forward.argtypes = [
-        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _VOID_P, _VOID_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
@@ -175,16 +185,18 @@ def _configure_deepgpr_library(lib: ctypes.CDLL) -> None:
         _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
 
-        ctypes.c_float, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_float,
-        _INT_P, _FLOAT_P,
+        ctypes.c_float, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_float, ctypes.c_float, ctypes.c_float,
+        _INT_P, _FLOAT_P, ctypes.c_int,
         ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
         _INT_P, _FLOAT_P,
-        ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int,
     ]
     lib.forward.restype = None
 
     lib.backward.argtypes = [
-        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _VOID_P, _VOID_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P,
@@ -204,12 +216,15 @@ def _configure_deepgpr_library(lib: ctypes.CDLL) -> None:
         _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
         _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
 
-        ctypes.c_float, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_float,
+        ctypes.c_float, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_float, ctypes.c_float, ctypes.c_float,
         ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
         _INT_P, _FLOAT_P,
         ctypes.c_int,
+        ctypes.c_int, _INT_P, ctypes.c_int, _FLOAT_P, ctypes.c_int,
         _FLOAT_P, _FLOAT_P,
-        ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int,
     ]
     lib.backward.restype = None
 
@@ -245,7 +260,7 @@ def _load_deepgpr_library(kind: str) -> ctypes.CDLL:
             load_errors.append(f"{path}: {exc}")
             continue
 
-        _require_exported_symbols(lib, ("forward", "backward"), path)
+        _require_exported_symbols(lib, ("forward", "backward", "deepgpr_abi_version"), path)
         _configure_deepgpr_library(lib)
         lib._deepgpr_path = str(path.resolve())
         _LOADED_LIBS[kind] = lib
@@ -321,6 +336,7 @@ def set_library_fdtd_order(lib: ctypes.CDLL, fdtd_order: int) -> None:
 from .common import *
 from .compute2 import *
 from .multiscale import *
+from . import wavelet as wavelet
 from .wavelet import *