DeepGPR 0.0.9__tar.gz → 0.0.10__tar.gz

{deepgpr-0.0.9 → deepgpr-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeepGPR
-Version: 0.0.9
+Version: 0.0.10
 Summary: PyTorch and CUDA for GPR FWI
 Author-email: Lei Liu <liulei990222@gmail.com>
 Classifier: Programming Language :: Python :: 3
@@ -28,22 +28,26 @@ Gradients of the output receiver data can be computed with respect to model para
 
 Utilizes CPML, allowing the width of the PML layer to be configured independently for each boundary.
 
-All operations are executed on the GPU.
+The compute backend can run on CUDA GPUs or on CPU. The CPU backend is implemented in C and is selected automatically when `device='cpu'`.
+
+The FDTD spatial finite-difference order can be selected with `fdtd_order=2`, `4`, or `8` (default: `2`).
+
+The FWI gradient mode can be selected with `mode=2` or `mode=3`. `mode=2` keeps the previous Ez-only gradient behavior, while `mode=3` uses Ex, Ey, and Ez forward/adjoint electric-field contributions for relative permittivity and conductivity gradients.
 
 Supports techniques such as checkpointing, DDP, and the utilization of CPU memory to minimize GPU memory consumption, thereby enabling the execution of large-scale models.
 
 
 ## System Requirements
 
-- **OS**: Linux and Windows
-- **Environment**: Python 3.8+, CUDA Toolkit 
-- **Libraries**: `torch` (with CUDA support), `numpy`, `scipy`, `matplotlib`
-- **Hardware**: NVIDIA GPU with sufficient VRAM for 3D computational grids.
+- **OS**: Linux, Windows, and macOS for CPU execution; Linux and Windows for CUDA execution
+- **Environment**: Python 3.8+, CUDA Toolkit for CUDA execution
+- **Libraries**: `torch`, `numpy`, `scipy`, `matplotlib`
+- **Hardware**: NVIDIA GPU with sufficient VRAM for CUDA execution; CPU execution works without a GPU.
 
 
 ## Start
 
-Before use, you must ensure that you have an NVIDIA graphics card and have installed a CUDA-enabled version of PyTorch.
+Before CUDA use, you must ensure that you have an NVIDIA graphics card and have installed a CUDA-enabled version of PyTorch. For CPU use, install a CPU build of PyTorch and include a compiled `deepgpr_cpu` shared library in `src/DeepGPR/lib`.
 
 DeepGPR can then be installed using
 
@@ -61,7 +65,7 @@ import DeepGPR
 import matplotlib.pyplot as plt
 
 # Set up the parameters and models
-device=torch.device("cuda")
+device=torch.device("cuda" if torch.cuda.is_available() else "cpu")
 dx=0.02
 dt=3e-11
 nt=2000
@@ -83,7 +87,8 @@ r = DeepGPR.compute(
     source_amplitudes=source_amplitudes,
     source_location=source_location, 
     receiver_location=receiver_location, 
-    er=er, se=se
+    er=er, se=se,
+    fdtd_order=2
 )
 
 (r[-1]**2).sum().backward()
@@ -137,16 +142,20 @@ 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,
-            use_async_offload=False):
+            use_async_offload=False,
+            fdtd_order=2,
+            mode=2):
 ```
 ## 📥 Input Parameters
 ### 1. Basic Physics & Grid Parameters
 
 | Parameter | Data Type | Description |
 | :--- | :--- | :--- |
-| **`device`** | `torch.device` / `str` | PyTorch computation device, e.g., `'cuda:0'`. Determines where the computation takes place. |
+| **`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). |
+| **`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. |
 ### 2. Medium Model Parameters
 
 This section defines the electromagnetic properties of the simulation space. For 2D simulations, set `nz=1`.
@@ -165,7 +174,7 @@ This section defines the geometric observation system (coordinates) and the exci
 
 | Parameter | Data Type | Shape | Description |
 | :--- | :--- | :--- | :--- |
-| **`source_amplitudes`** | `Tensor` (float) | `(num_waveforms, nt)` | Source excitation waveforms. `nt` is the total number of time steps.<br>- If `num_waveforms == 1`: All sources share this single waveform.<br>- If `num_waveforms == nsr`: Each source uses its corresponding waveform. |
+| **`source_amplitudes`** | `Tensor` (float) | `(num_waveforms, nt, 1)` | Source excitation waveforms. `nt` is the total number of time steps.<br>- If `num_waveforms == 1`: All sources share this single waveform.<br>- If `num_waveforms == nsr`: Each source uses its corresponding waveform. |
 | **`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$). |
@@ -183,7 +192,34 @@ This section defines the geometric observation system (coordinates) and the exci
 | :--- | :--- | :--- | :--- |
 | **`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 | 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. |
+| **`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. |
+
+### 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.
+
+## CPU Backend Build
+
+The CPU backend is a plain C shared library and is built with OpenMP by default. Build it into `src/DeepGPR/lib` before running with `device='cpu'`. You can control CPU thread count with `OMP_NUM_THREADS`.
+
+```bash
+# Linux
+cc -std=c99 -O3 -fopenmp -fPIC -shared -o src/DeepGPR/lib/deepgpr_cpu.so src/DeepGPR/lib/deepgpr_cpu.c
+
+# macOS
+brew install libomp
+LIBOMP_PREFIX="$(brew --prefix libomp)"
+cc -std=c99 -O3 -Xpreprocessor -fopenmp -DDEEPGPR_USE_OPENMP -I"$LIBOMP_PREFIX/include" -Wl,-rpath,"$LIBOMP_PREFIX/lib" -L"$LIBOMP_PREFIX/lib" -fPIC -shared -o src/DeepGPR/lib/deepgpr_cpu.dylib src/DeepGPR/lib/deepgpr_cpu.c -lomp
+```
+
+On Windows, build `src\DeepGPR\lib\deepgpr_cpu.dll` with MSVC:
+
+```powershell
+cl /LD /O2 /openmp /Fe:src\DeepGPR\lib\deepgpr_cpu.dll src\DeepGPR\lib\deepgpr_cpu.c
+```
 
 ### 5. Field Variable States (Checkpoints / Initial Fields)
 
@@ -205,8 +241,10 @@ The function returns a tuple of 5 elements. These are used to extract synthetic
 return Eall, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
 ```
 
-1.  **`Eall`**: The global electric field history saved for gradient calculation.
-    *   **Shape**: `(nt_saved, nstep, nx, ny, nz)` (where `nt_saved` depends on `nt` and `model_gradient_sampling_interval`).
+1.  **`Eall`**: The electric field history saved for gradient calculation.
+    *   **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`.
 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.

{deepgpr-0.0.9 → deepgpr-0.0.10}/README.md

@@ -11,22 +11,26 @@ Gradients of the output receiver data can be computed with respect to model para
 
 Utilizes CPML, allowing the width of the PML layer to be configured independently for each boundary.
 
-All operations are executed on the GPU.
+The compute backend can run on CUDA GPUs or on CPU. The CPU backend is implemented in C and is selected automatically when `device='cpu'`.
+
+The FDTD spatial finite-difference order can be selected with `fdtd_order=2`, `4`, or `8` (default: `2`).
+
+The FWI gradient mode can be selected with `mode=2` or `mode=3`. `mode=2` keeps the previous Ez-only gradient behavior, while `mode=3` uses Ex, Ey, and Ez forward/adjoint electric-field contributions for relative permittivity and conductivity gradients.
 
 Supports techniques such as checkpointing, DDP, and the utilization of CPU memory to minimize GPU memory consumption, thereby enabling the execution of large-scale models.
 
 
 ## System Requirements
 
-- **OS**: Linux and Windows
-- **Environment**: Python 3.8+, CUDA Toolkit 
-- **Libraries**: `torch` (with CUDA support), `numpy`, `scipy`, `matplotlib`
-- **Hardware**: NVIDIA GPU with sufficient VRAM for 3D computational grids.
+- **OS**: Linux, Windows, and macOS for CPU execution; Linux and Windows for CUDA execution
+- **Environment**: Python 3.8+, CUDA Toolkit for CUDA execution
+- **Libraries**: `torch`, `numpy`, `scipy`, `matplotlib`
+- **Hardware**: NVIDIA GPU with sufficient VRAM for CUDA execution; CPU execution works without a GPU.
 
 
 ## Start
 
-Before use, you must ensure that you have an NVIDIA graphics card and have installed a CUDA-enabled version of PyTorch.
+Before CUDA use, you must ensure that you have an NVIDIA graphics card and have installed a CUDA-enabled version of PyTorch. For CPU use, install a CPU build of PyTorch and include a compiled `deepgpr_cpu` shared library in `src/DeepGPR/lib`.
 
 DeepGPR can then be installed using
 
@@ -44,7 +48,7 @@ import DeepGPR
 import matplotlib.pyplot as plt
 
 # Set up the parameters and models
-device=torch.device("cuda")
+device=torch.device("cuda" if torch.cuda.is_available() else "cpu")
 dx=0.02
 dt=3e-11
 nt=2000
@@ -66,7 +70,8 @@ r = DeepGPR.compute(
     source_amplitudes=source_amplitudes,
     source_location=source_location, 
     receiver_location=receiver_location, 
-    er=er, se=se
+    er=er, se=se,
+    fdtd_order=2
 )
 
 (r[-1]**2).sum().backward()
@@ -120,16 +125,20 @@ 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,
-            use_async_offload=False):
+            use_async_offload=False,
+            fdtd_order=2,
+            mode=2):
 ```
 ## 📥 Input Parameters
 ### 1. Basic Physics & Grid Parameters
 
 | Parameter | Data Type | Description |
 | :--- | :--- | :--- |
-| **`device`** | `torch.device` / `str` | PyTorch computation device, e.g., `'cuda:0'`. Determines where the computation takes place. |
+| **`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). |
+| **`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. |
 ### 2. Medium Model Parameters
 
 This section defines the electromagnetic properties of the simulation space. For 2D simulations, set `nz=1`.
@@ -148,7 +157,7 @@ This section defines the geometric observation system (coordinates) and the exci
 
 | Parameter | Data Type | Shape | Description |
 | :--- | :--- | :--- | :--- |
-| **`source_amplitudes`** | `Tensor` (float) | `(num_waveforms, nt)` | Source excitation waveforms. `nt` is the total number of time steps.<br>- If `num_waveforms == 1`: All sources share this single waveform.<br>- If `num_waveforms == nsr`: Each source uses its corresponding waveform. |
+| **`source_amplitudes`** | `Tensor` (float) | `(num_waveforms, nt, 1)` | Source excitation waveforms. `nt` is the total number of time steps.<br>- If `num_waveforms == 1`: All sources share this single waveform.<br>- If `num_waveforms == nsr`: Each source uses its corresponding waveform. |
 | **`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$). |
@@ -166,7 +175,34 @@ This section defines the geometric observation system (coordinates) and the exci
 | :--- | :--- | :--- | :--- |
 | **`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 | 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. |
+| **`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. |
+
+### 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.
+
+## CPU Backend Build
+
+The CPU backend is a plain C shared library and is built with OpenMP by default. Build it into `src/DeepGPR/lib` before running with `device='cpu'`. You can control CPU thread count with `OMP_NUM_THREADS`.
+
+```bash
+# Linux
+cc -std=c99 -O3 -fopenmp -fPIC -shared -o src/DeepGPR/lib/deepgpr_cpu.so src/DeepGPR/lib/deepgpr_cpu.c
+
+# macOS
+brew install libomp
+LIBOMP_PREFIX="$(brew --prefix libomp)"
+cc -std=c99 -O3 -Xpreprocessor -fopenmp -DDEEPGPR_USE_OPENMP -I"$LIBOMP_PREFIX/include" -Wl,-rpath,"$LIBOMP_PREFIX/lib" -L"$LIBOMP_PREFIX/lib" -fPIC -shared -o src/DeepGPR/lib/deepgpr_cpu.dylib src/DeepGPR/lib/deepgpr_cpu.c -lomp
+```
+
+On Windows, build `src\DeepGPR\lib\deepgpr_cpu.dll` with MSVC:
+
+```powershell
+cl /LD /O2 /openmp /Fe:src\DeepGPR\lib\deepgpr_cpu.dll src\DeepGPR\lib\deepgpr_cpu.c
+```
 
 ### 5. Field Variable States (Checkpoints / Initial Fields)
 
@@ -188,8 +224,10 @@ The function returns a tuple of 5 elements. These are used to extract synthetic
 return Eall, (Ex, Ey, Ez), (Hx, Hy, Hz), (x0EPhi1...zmHPhi2), receiver_amplitudes
 ```
 
-1.  **`Eall`**: The global electric field history saved for gradient calculation.
-    *   **Shape**: `(nt_saved, nstep, nx, ny, nz)` (where `nt_saved` depends on `nt` and `model_gradient_sampling_interval`).
+1.  **`Eall`**: The electric field history saved for gradient calculation.
+    *   **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`.
 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.
@@ -214,4 +252,4 @@ If you find our codes useful, please kindly cite this article. Thanks.
 
   publisher={Elsevier}
 
-}
+}

{deepgpr-0.0.9 → deepgpr-0.0.10}/pyproject.toml

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

deepgpr-0.0.10/src/DeepGPR/__init__.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+from pathlib import Path
+
+
+_FLOAT_P = ctypes.POINTER(ctypes.c_float)
+_INT_P = ctypes.POINTER(ctypes.c_int)
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _PACKAGE_DIR / "lib"
+_SYSTEM_NAME = platform.system()
+_LOADED_LIBS: dict[str, ctypes.CDLL] = {}
+
+
+def _candidate_library_paths(kind: str) -> list[Path]:
+    """Return platform-specific native library candidates.
+
+    Args:
+        kind: Backend kind, either "cuda" or "cpu".
+    """
+    if kind == "cuda":
+        if _SYSTEM_NAME == "Windows":
+            return [_LIB_DIR / "deepgpr.dll"]
+        if _SYSTEM_NAME == "Linux":
+            return [_LIB_DIR / "deepgpr.so", _LIB_DIR / "libdeepgpr.so"]
+        return []
+
+    if kind == "cpu":
+        if _SYSTEM_NAME == "Windows":
+            return [_LIB_DIR / "deepgpr_cpu.dll"]
+        if _SYSTEM_NAME == "Darwin":
+            return [_LIB_DIR / "libdeepgpr_cpu.dylib", _LIB_DIR / "deepgpr_cpu.dylib"]
+        if _SYSTEM_NAME == "Linux":
+            return [_LIB_DIR / "deepgpr_cpu.so", _LIB_DIR / "libdeepgpr_cpu.so"]
+        return []
+
+    raise ValueError(f"Unknown DeepGPR library kind: {kind}")
+
+
+def _available_library_files() -> list[str]:
+    """Return native library filenames currently present in the package.
+
+    Args:
+        None.
+    """
+    if not _LIB_DIR.is_dir():
+        return []
+    return sorted(p.name for p in _LIB_DIR.iterdir())
+
+
+def _add_windows_dll_search_paths() -> None:
+    """Add Windows DLL search paths for CUDA, conda, and package libraries.
+
+    Args:
+        None.
+    """
+    if _SYSTEM_NAME != "Windows" or not hasattr(os, "add_dll_directory"):
+        return
+
+    search_dirs: list[Path] = [_LIB_DIR]
+
+    cuda_path = os.environ.get("CUDA_PATH")
+    if cuda_path:
+        search_dirs.append(Path(cuda_path) / "bin")
+
+    for key, value in os.environ.items():
+        if key.startswith("CUDA_PATH_V") and value:
+            search_dirs.append(Path(value) / "bin")
+
+    conda_prefix = os.environ.get("CONDA_PREFIX")
+    if conda_prefix:
+        search_dirs.append(Path(conda_prefix) / "Library" / "bin")
+
+    seen = set()
+    for directory in search_dirs:
+        directory = Path(directory)
+        if directory in seen:
+            continue
+        seen.add(directory)
+
+        try:
+            if directory.is_dir():
+                os.add_dll_directory(str(directory))
+        except OSError:
+            pass
+
+
+def _require_exported_symbols(lib: ctypes.CDLL, symbols: tuple[str, ...], path: Path) -> None:
+    """Validate that a loaded native library exports required symbols.
+
+    Args:
+        lib: Loaded ctypes library object.
+        symbols: Symbol names that must be exported.
+        path: Filesystem path of the loaded library.
+    """
+    missing = [name for name in symbols if not hasattr(lib, name)]
+    if missing:
+        raise RuntimeError(
+            "The shared library was loaded, but the following exported C ABI symbols "
+            f"were not found: {missing}.\nLibrary: {path}"
+        )
+
+
+def _configure_deepgpr_library(lib: ctypes.CDLL) -> None:
+    """Configure ctypes signatures for the native DeepGPR library.
+
+    Args:
+        lib: Loaded ctypes library object to configure.
+    """
+    if getattr(lib, "_deepgpr_argtypes_configured", False):
+        return
+
+    lib.forward.argtypes = [
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+
+        ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int, ctypes.c_int, ctypes.c_int,
+
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _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_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        _INT_P, _FLOAT_P,
+        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,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P,
+
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+
+        ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        ctypes.c_int, ctypes.c_int, ctypes.c_int,
+
+        _FLOAT_P, _FLOAT_P, _FLOAT_P, _FLOAT_P,
+        _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_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        _INT_P, _FLOAT_P,
+        ctypes.c_int,
+        _FLOAT_P, _FLOAT_P,
+        ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+    ]
+    lib.backward.restype = None
+
+    if hasattr(lib, "set_fdtd_order"):
+        lib.set_fdtd_order.argtypes = [ctypes.c_int]
+        lib.set_fdtd_order.restype = None
+
+    lib._deepgpr_argtypes_configured = True
+
+
+def _load_deepgpr_library(kind: str) -> ctypes.CDLL:
+    """Load and configure a native DeepGPR backend library.
+
+    Args:
+        kind: Backend kind, either "cuda" or "cpu".
+    """
+    if kind in _LOADED_LIBS:
+        return _LOADED_LIBS[kind]
+
+    _add_windows_dll_search_paths()
+    candidates = _candidate_library_paths(kind)
+    load_errors: list[str] = []
+
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            lib = ctypes.CDLL(str(path.resolve()))
+        except OSError as exc:
+            load_errors.append(f"{path}: {exc}")
+            continue
+
+        _require_exported_symbols(lib, ("forward", "backward"), path)
+        _configure_deepgpr_library(lib)
+        lib._deepgpr_path = str(path.resolve())
+        _LOADED_LIBS[kind] = lib
+        return lib
+
+    expected = "\n".join(str(p) for p in candidates) or "No candidates for this platform."
+    details = "\n".join(load_errors) if load_errors else "No load attempts succeeded."
+    raise FileNotFoundError(
+        f"DeepGPR {kind.upper()} shared library was not found or could not be loaded.\n\n"
+        f"Current platform: {_SYSTEM_NAME}\n"
+        f"Expected one of:\n{expected}\n\n"
+        f"Available files in {_LIB_DIR}:\n{_available_library_files()}\n\n"
+        f"Load details:\n{details}"
+    )
+
+
+def _device_type(device) -> str:
+    """Convert a PyTorch device or device string to a backend name.
+
+    Args:
+        device: PyTorch device object or device string.
+    """
+    device_type = getattr(device, "type", None)
+    if device_type is not None:
+        return str(device_type).lower()
+    return str(device).split(":", 1)[0].lower()
+
+
+def get_deepgpr_lib(device) -> ctypes.CDLL:
+    """Return the native library for the requested device.
+
+    Args:
+        device: PyTorch device object or device string.
+    """
+    device_type = _device_type(device)
+    if device_type == "cpu":
+        return _load_deepgpr_library("cpu")
+    if device_type == "cuda":
+        return _load_deepgpr_library("cuda")
+    raise ValueError(f"Unsupported DeepGPR device: {device}")
+
+
+def get_deepgpr_library_path(device) -> str:
+    """Return the loaded native library path for a device.
+
+    Args:
+        device: PyTorch device object or device string.
+    """
+    return str(getattr(get_deepgpr_lib(device), "_deepgpr_path", ""))
+
+
+def set_library_fdtd_order(lib: ctypes.CDLL, fdtd_order: int) -> None:
+    """Set the FDTD spatial order on a native library.
+
+    Args:
+        lib: Loaded ctypes library object.
+        fdtd_order: Spatial finite-difference order, supported values are 2, 4, and 8.
+    """
+    if fdtd_order not in (2, 4, 8):
+        raise ValueError("fdtd_order must be one of 2, 4, or 8.")
+
+    if hasattr(lib, "set_fdtd_order"):
+        lib.set_fdtd_order(int(fdtd_order))
+        return
+
+    if fdtd_order != 2:
+        raise RuntimeError(
+            "The loaded DeepGPR shared library does not support fdtd_order. "
+            "Rebuild it from the updated C/CUDA sources to use 4th or 8th order FDTD."
+        )
+
+
+from .common import *
+from .compute2 import *
+from .multiscale import *
+from .wavelet import *
+
+
+_EXCLUDED_FROM_ALL = {
+    "ctypes",
+    "os",
+    "platform",
+    "Path",
+}
+
+__all__ = [
+    name for name in globals()
+    if not name.startswith("_") and name not in _EXCLUDED_FROM_ALL
+]