tide-GPR 0.0.9__py3-none-manylinux_2_28_x86_64.whl

tide/utils.py

@@ -0,0 +1,274 @@
+import math
+from typing import Sequence
+
+import torch
+
+# Physical constants
+EP0 = 8.8541878128e-12  # vacuum permittivity
+MU0 = 1.2566370614359173e-06  # vacuum permeability
+C0 = 1.0 / math.sqrt(EP0 * MU0)  # speed of light in vacuum
+
+
+def prepare_parameters(
+    epsilon_r: torch.Tensor, sigma: torch.Tensor, mu_r: torch.Tensor, dt: float
+) -> tuple:
+    """Prepare update coefficients for Maxwell equations.
+
+    Args:
+        epsilon_r: Relative permittivity.
+        sigma: Conductivity (S/m).
+        mu_r: Relative permeability.
+        dt: Time step (s).
+
+    Returns:
+        Tuple of (ca, cb, cq) coefficients.
+    """
+    # Convert to absolute values
+    epsilon = epsilon_r * EP0
+    mu = mu_r * MU0
+
+    # Ca and Cb for E-field update: E^{n+1} = Ca*E^n + Cb*(curl H)
+    # Ca = (1 - sigma*dt/(2*epsilon)) / (1 + sigma*dt/(2*epsilon))
+    # Cb = dt/epsilon / (1 + sigma*dt/(2*epsilon))
+    denom = 1.0 + sigma * dt / (2.0 * epsilon)
+    ca = (1.0 - sigma * dt / (2.0 * epsilon)) / denom
+    cb = (dt / epsilon) / denom
+
+    # Cq for H-field update: H^{n+1/2} = H^{n-1/2} - Cq*(curl E)
+    cq = dt / mu
+
+    return ca, cb, cq
+
+
+def setup_pml(
+    pml_width: Sequence[int],
+    pml_start: Sequence[float],
+    max_pml: float,
+    dt: float,
+    n: int,
+    max_vel: float,
+    dtype: torch.dtype,
+    device: torch.device,
+    pml_freq: float,
+    start: float = 0.0,
+    r_val: float = 1e-8,
+    n_power: int = 4,
+    eps: float = 1e-9,
+    grid_spacing: float = 1.0,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Creates a, b, and k profiles for electromagnetic C-PML.
+
+    This implementation follows the standard CPML formulation for electromagnetic
+    wave simulation with proper physical parameters.
+
+    Only the first fd_pad[0]+pml_width[0] and last fd_pad[1]+pml_width[1]
+    elements of the profiles will be non-zero.
+
+    Args:
+        pml_width: list of two integers specifying the width of the PML
+            region [left/bottom, right/top].
+        pml_start: list of two floats specifying the coordinates (in grid
+            cells) of the start of the PML regions.
+        max_pml: Float specifying the length (in distance units) of the
+            longest PML over all sides and dimensions.
+        dt: Time step interval.
+        n: Integer specifying desired profile length, including fd_pad and
+           pml_width.
+        max_vel: Maximum wave speed (not used in EM formulation, kept for API).
+        dtype: PyTorch datatype to use.
+        device: PyTorch device to use.
+        pml_freq: The frequency value to use for the profile (not used in EM,
+            kept for API compatibility).
+        start: Float specifying the coordinate (in grid cells) of the first
+            element. Optional, default 0.
+        r_val: The reflection coefficient. Optional, default 1e-8.
+        n_power: The power for the profile. Optional, default 4.
+        eps: A small number to prevent division by zero. Optional,
+            default 1e-9.
+        grid_spacing: The grid spacing (dx or dy). Optional, default 1.0.
+
+    Returns:
+        A tuple containing the (a, b, k) profiles as Tensors.
+        - a: CPML 'a' coefficient for recursive convolution
+        - b: CPML 'b' coefficient for recursive convolution
+        - k: CPML stretching factor
+
+    """
+    # CPML parameters for electromagnetic waves
+    k_max_cpml = 5.0  # maximum stretching factor
+    alpha_max_cpml = 0.008  # maximum frequency shift
+
+    # Create output tensors
+    a = torch.zeros(n, device=device, dtype=dtype)
+    b = torch.zeros(n, device=device, dtype=dtype)
+    k = torch.ones(n, device=device, dtype=dtype)
+
+    if max_pml == 0 or (pml_width[0] == 0 and pml_width[1] == 0):
+        return a, b, k
+
+    # Standard CPML sigma_max: sig0 = (Npower+1) / (150 * pi * dx)
+    sigma0 = (n_power + 1) / (150.0 * math.pi * grid_spacing)
+
+    # Calculate profiles for each grid point
+    x = torch.arange(start, start + n, device=device, dtype=dtype)
+
+    # Left/bottom PML region
+    if pml_width[0] > 0:
+        origin_left = pml_start[0]  # This is the inner edge of PML (in grid cells)
+        abscissa_left = origin_left - x  # Distance from inner edge (in grid cells)
+        mask_left = abscissa_left >= 0
+
+        # Normalized distance into PML (0 at inner edge, 1 at outer edge)
+        # abscissa_left is in grid cells, pml_width[0] is also in grid cells
+        abscissa_norm_left = torch.clamp(abscissa_left / pml_width[0], 0, 1)
+
+        # Sigma, k, alpha profiles with polynomial grading
+        sigma_left = sigma0 * (abscissa_norm_left**n_power)
+        k_left = 1.0 + (k_max_cpml - 1.0) * (abscissa_norm_left**n_power)
+        alpha_left = alpha_max_cpml * (1.0 - abscissa_norm_left) + 0.1 * alpha_max_cpml
+
+        # Apply to left region
+        k = torch.where(mask_left, k_left, k)
+
+        # Calculate b = exp(-(sigma/k + alpha) * dt / epsilon0)
+        b_left = torch.exp(-(sigma_left / k_left + alpha_left) * dt / EP0)
+        b = torch.where(mask_left, b_left, b)
+
+        # Calculate a = sigma * (b - 1) / (k * (sigma + k * alpha))
+        denom_left = k_left * (sigma_left + k_left * alpha_left) + eps
+        a_left = sigma_left * (b_left - 1.0) / denom_left
+        # Only apply where sigma is significant
+        a_left = torch.where(sigma_left > 1e-6, a_left, torch.zeros_like(a_left))
+        a = torch.where(mask_left, a_left, a)
+
+    # Right/top PML region
+    if pml_width[1] > 0:
+        origin_right = pml_start[1]  # This is the inner edge of PML (in grid cells)
+        abscissa_right = x - origin_right  # Distance from inner edge (in grid cells)
+        mask_right = abscissa_right >= 0
+
+        # Normalized distance into PML (0 at inner edge, 1 at outer edge)
+        # abscissa_right is in grid cells, pml_width[1] is also in grid cells
+        abscissa_norm_right = torch.clamp(abscissa_right / pml_width[1], 0, 1)
+
+        # Sigma, k, alpha profiles
+        sigma_right = sigma0 * (abscissa_norm_right**n_power)
+        k_right = 1.0 + (k_max_cpml - 1.0) * (abscissa_norm_right**n_power)
+        alpha_right = (
+            alpha_max_cpml * (1.0 - abscissa_norm_right) + 0.1 * alpha_max_cpml
+        )
+
+        # Apply to right region
+        k = torch.where(mask_right, k_right, k)
+
+        # Calculate b = exp(-(sigma/k + alpha) * dt / epsilon0)
+        b_right = torch.exp(-(sigma_right / k_right + alpha_right) * dt / EP0)
+        b = torch.where(mask_right, b_right, b)
+
+        # Calculate a = sigma * (b - 1) / (k * (sigma + k * alpha))
+        denom_right = k_right * (sigma_right + k_right * alpha_right) + eps
+        a_right = sigma_right * (b_right - 1.0) / denom_right
+        a_right = torch.where(sigma_right > 1e-6, a_right, torch.zeros_like(a_right))
+        a = torch.where(mask_right, a_right, a)
+
+    return a, b, k
+
+
+def setup_pml_half(
+    pml_width: Sequence[int],
+    pml_start: Sequence[float],
+    max_pml: float,
+    dt: float,
+    n: int,
+    max_vel: float,
+    dtype: torch.dtype,
+    device: torch.device,
+    pml_freq: float,
+    start: float = 0.0,
+    r_val: float = 1e-8,
+    n_power: int = 4,
+    eps: float = 1e-9,
+    grid_spacing: float = 1.0,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Creates a, b, and k profiles for C-PML at half grid points.
+
+    This is used for staggered grid implementations where some field components
+    are located at half grid points (e.g., H fields in Yee grid).
+
+    Args:
+        Same as setup_pml.
+
+    Returns:
+        A tuple containing the (a_half, b_half, k_half) profiles as Tensors.
+
+    """
+    # CPML parameters for electromagnetic waves
+    k_max_cpml = 5.0
+    alpha_max_cpml = 0.008
+
+    a = torch.zeros(n, device=device, dtype=dtype)
+    b = torch.zeros(n, device=device, dtype=dtype)
+    k = torch.ones(n, device=device, dtype=dtype)
+
+    if max_pml == 0 or (pml_width[0] == 0 and pml_width[1] == 0):
+        return a, b, k
+
+    # Standard CPML sigma_max: sig0 = (Npower+1) / (150 * pi * dx)
+    sigma0 = (n_power + 1) / (150.0 * math.pi * grid_spacing)
+
+    # Half grid positions (shifted by dx/2 or dy/2)
+    x = torch.arange(start, start + n, device=device, dtype=dtype) + 0.5
+
+    # Left/bottom PML region (half grid)
+    if pml_width[0] > 0:
+        origin_left = pml_start[0]  # Inner edge of PML (in grid cells)
+        abscissa_left = origin_left - x  # Distance in grid cells
+        mask_left = abscissa_left >= 0
+
+        # Normalized distance (both in grid cells)
+        abscissa_norm_left = torch.clamp(abscissa_left / pml_width[0], 0, 1)
+
+        sigma_left = sigma0 * (abscissa_norm_left**n_power)
+        k_left = 1.0 + (k_max_cpml - 1.0) * (abscissa_norm_left**n_power)
+        alpha_left = alpha_max_cpml * (1.0 - abscissa_norm_left) + 0.1 * alpha_max_cpml
+
+        k = torch.where(mask_left, k_left, k)
+
+        # b = exp(-(sigma/k + alpha) * dt / epsilon0)
+        b_left = torch.exp(-(sigma_left / k_left + alpha_left) * dt / EP0)
+        b = torch.where(mask_left, b_left, b)
+
+        # a = sigma * (b - 1) / (k * (sigma + k * alpha))
+        denom_left = k_left * (sigma_left + k_left * alpha_left) + eps
+        a_left = sigma_left * (b_left - 1.0) / denom_left
+        a_left = torch.where(sigma_left > 1e-6, a_left, torch.zeros_like(a_left))
+        a = torch.where(mask_left, a_left, a)
+
+    # Right/top PML region (half grid)
+    if pml_width[1] > 0:
+        origin_right = pml_start[1]  # Inner edge of PML (in grid cells)
+        abscissa_right = x - origin_right  # Distance in grid cells
+        mask_right = abscissa_right >= 0
+
+        # Normalized distance (both in grid cells)
+        abscissa_norm_right = torch.clamp(abscissa_right / pml_width[1], 0, 1)
+
+        sigma_right = sigma0 * (abscissa_norm_right**n_power)
+        k_right = 1.0 + (k_max_cpml - 1.0) * (abscissa_norm_right**n_power)
+        alpha_right = (
+            alpha_max_cpml * (1.0 - abscissa_norm_right) + 0.1 * alpha_max_cpml
+        )
+
+        k = torch.where(mask_right, k_right, k)
+
+        # b = exp(-(sigma/k + alpha) * dt / epsilon0)
+        b_right = torch.exp(-(sigma_right / k_right + alpha_right) * dt / EP0)
+        b = torch.where(mask_right, b_right, b)
+
+        # a = sigma * (b - 1) / (k * (sigma + k * alpha))
+        denom_right = k_right * (sigma_right + k_right * alpha_right) + eps
+        a_right = sigma_right * (b_right - 1.0) / denom_right
+        a_right = torch.where(sigma_right > 1e-6, a_right, torch.zeros_like(a_right))
+        a = torch.where(mask_right, a_right, a)
+
+    return a, b, k

tide/validation.py

@@ -0,0 +1,71 @@
+"""Validation helpers for user-facing parameters."""
+
+
+def validate_model_gradient_sampling_interval(
+    model_gradient_sampling_interval: int,
+) -> int:
+    """Validate the model gradient sampling interval parameter.
+
+    The gradient sampling interval controls memory usage during backpropagation.
+    Setting it > 1 reduces memory by storing fewer snapshots.
+
+    Args:
+        model_gradient_sampling_interval: Number of time steps between
+            gradient snapshots.
+
+    Returns:
+        Validated interval value.
+
+    Raises:
+        TypeError: If not an integer.
+        ValueError: If negative.
+    """
+    if not isinstance(model_gradient_sampling_interval, int):
+        raise TypeError("model_gradient_sampling_interval must be an int")
+    if model_gradient_sampling_interval < 0:
+        raise ValueError("model_gradient_sampling_interval must be >= 0")
+    return model_gradient_sampling_interval
+
+
+def validate_freq_taper_frac(freq_taper_frac: float) -> float:
+    """Validate the frequency taper fraction parameter.
+
+    Args:
+        freq_taper_frac: Fraction of frequencies to taper (0.0-1.0).
+
+    Returns:
+        Validated fraction value.
+
+    Raises:
+        TypeError: If not convertible to float.
+        ValueError: If not in [0, 1].
+    """
+    try:
+        freq_taper_frac = float(freq_taper_frac)
+    except (TypeError, ValueError) as e:
+        raise TypeError("freq_taper_frac must be convertible to float") from e
+    if not 0.0 <= freq_taper_frac <= 1.0:
+        raise ValueError(f"freq_taper_frac must be in [0, 1], got {freq_taper_frac}")
+    return freq_taper_frac
+
+
+def validate_time_pad_frac(time_pad_frac: float) -> float:
+    """Validate the time padding fraction parameter.
+
+    Args:
+        time_pad_frac: Fraction of time axis for zero padding (0.0-1.0).
+
+    Returns:
+        Validated fraction value.
+
+    Raises:
+        TypeError: If not convertible to float.
+        ValueError: If not in [0, 1].
+    """
+    try:
+        time_pad_frac = float(time_pad_frac)
+    except (TypeError, ValueError) as e:
+        raise TypeError("time_pad_frac must be convertible to float") from e
+    if not 0.0 <= time_pad_frac <= 1.0:
+        raise ValueError(f"time_pad_frac must be in [0, 1], got {time_pad_frac}")
+    return time_pad_frac

tide/wavelets.py

@@ -0,0 +1,72 @@
+"""Common electromagnetic wavelets for TIDE simulations.
+
+This module provides various source wavelet functions commonly used in
+electromagnetic wave simulations, particularly for Ground Penetrating Radar (GPR)
+and other time-domain electromagnetic methods.
+
+All wavelets return PyTorch tensors and support optional dtype specification.
+"""
+
+import math
+from typing import Optional
+
+import torch
+
+
+def ricker(
+    freq: float,
+    length: int,
+    dt: float,
+    peak_time: Optional[float] = None,
+    dtype: Optional[torch.dtype] = None,
+    device: Optional[torch.device] = None,
+) -> torch.Tensor:
+    """Return a Ricker wavelet (Mexican hat wavelet).
+
+    The Ricker wavelet is the negative normalized second derivative of a
+    Gaussian function. It is commonly used in seismic and GPR simulations.
+
+    The formula used is:
+        w(t) = -(2*pi^2*(f*t' - 1)^2 - 1) * exp(-pi^2*(f*t' - 1)^2)
+
+    where t' = t - peak_time.
+
+    Args:
+        freq: The central (dominant) frequency in Hz.
+        length: The number of time samples.
+        dt: The time sample spacing in seconds.
+        peak_time: The time (in seconds) of the peak amplitude. If None,
+            defaults to 1/freq (one period after start).
+        dtype: The PyTorch datatype to use. Optional, defaults to float32.
+        device: The PyTorch device to use. Optional, defaults to CPU.
+
+    Returns:
+        A PyTorch tensor representing the Ricker wavelet.
+
+    Example:
+        >>> # Create a 100 MHz Ricker wavelet for GPR
+        >>> freq = 100e6  # 100 MHz
+        >>> dt = 1e-10    # 0.1 ns time step
+        >>> length = 500  # 500 time samples
+        >>> wavelet = ricker(freq, length, dt)
+
+    """
+    if dt == 0:
+        raise ValueError("dt cannot be zero.")
+    if freq <= 0:
+        raise ValueError("freq must be positive.")
+    if length <= 0:
+        raise ValueError("length must be positive.")
+
+    if peak_time is None:
+        peak_time = 1.0 / freq  # Default: one period
+
+    t = torch.arange(float(length), dtype=dtype, device=device) * dt
+    t_shifted = t - peak_time
+
+    # Ricker wavelet formula
+    pi2_f2_t2 = (math.pi * freq * t_shifted) ** 2
+    y = (1 - 2 * pi2_f2_t2) * torch.exp(-pi2_f2_t2)
+
+    return y
+

tide_gpr-0.0.9.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.2
+Name: tide-GPR
+Version: 0.0.9
+Summary: Torch-based Inversion & Development Engine for electromagnetic wave propagation
+Keywords: pytorch,electromagnetic,wave-propagation,maxwell-equations,fdtd,full-waveform-inversion,fwi,geophysics,inverse-problems,cuda
+Author-Email: "V.cholerae" <v.cholerae1@gmail.com>
+Maintainer-Email: "V.cholerae" <v.cholerae1@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: scipy>=1.16.3
+Requires-Dist: torch>=2.9.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Description-Content-Type: text/markdown
+
+# TIDE
+
+**T**orch-based **I**nversion & **D**evelopment **E**ngine
+
+TIDE is a PyTorch-based library for  high frequa electromagnetic wave propagation and inversion, built on Maxwell's equations. It provides efficient CPU and CUDA implementations for forward modeling, gradient computation, and full waveform inversion (FWI).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Maxwell Equation Solvers**: 
+  - 2D TM mode propagation (`MaxwellTM`)
+  - Other propagation is on the way 
+- **Automatic Differentiation**: Gradient support through PyTorch's autograd
+- **High Performance**: Optimized C/CUDA kernels for critical operations
+- **Flexible Storage**: Multiple storage modes for gradient computation (memory/disk/optional BF16 compressed)
+- **Staggered Grid**: Industry-standard FDTD staggered grid implementation
+- **PML Boundaries**: Perfectly Matched Layer absorbing boundaries
+
+## Installation
+
+### From PyPI
+
+
+```bash
+uv pip install tide-GPR
+```
+
+or
+
+```bash
+pip install tide-GPR
+```
+
+### From Source
+
+We recommend using [uv](https://github.com/astral-sh/uv) for building:
+
+```bash
+git clone https://github.com/vcholerae1/tide.git
+cd tide
+uv build
+```
+
+**Requirements:**
+- Python >= 3.12
+- PyTorch >= 2.9.1
+- CUDA Toolkit (optional, for GPU support)
+- CMake >= 3.28 (optional, for building from source)
+
+## Quick Start
+
+```python
+import torch
+import tide
+
+# Create a simple model
+nx, ny = 200, 100
+epsilon = torch.ones(ny, nx) * 4.0  # Relative permittivity
+epsilon[50:, :] = 9.0  # Add a layer
+
+# Set up source
+source_amplitudes = tide.ricker(
+    freq=1e9,           # 1 GHz
+    nt=1000,
+    dt=1e-11,
+    peak_time=5e-10
+).reshape(1, 1, -1)
+
+source_locations = torch.tensor([[[10, 100]]])
+receiver_locations = torch.tensor([[[10, 150]]])
+
+# Run forward simulation
+receiver_data = tide.maxwelltm(
+    epsilon=epsilon,
+    dx=0.01,
+    dt=1e-11,
+    source_amplitudes=source_amplitudes,
+    source_locations=source_locations,
+    receiver_locations=receiver_locations,
+    pml_width=10
+)
+
+print(f"Recorded data shape: {receiver_data.shape}")
+```
+
+## Core Modules
+
+- **`tide.maxwelltm`**: 2D TM mode Maxwell solver
+- **`tide.wavelets`**: Source wavelet generation (Ricker, etc.)
+- **`tide.staggered`**: Staggered grid finite difference operators
+- **`tide.callbacks`**: Callback state and factories
+- **`tide.resampling`**: Upsampling/downsampling utilities
+- **`tide.cfl`**: CFL condition helpers
+- **`tide.padding`**: Padding and interior masking helpers
+- **`tide.validation`**: Input validation helpers
+- **`tide.storage`**: Gradient checkpointing and storage management
+
+## Examples
+
+See the [`examples/`](examples/) directory for complete workflows:
+
+- [`example_multiscale_filtered.py`](examples/example_multiscale_filtered.py): Multi-scale FWI with frequency filtering
+- [`example_multiscale_random_sources.py`](examples/example_multiscale_random_sources.py): FWI with random source encoding
+- [`wavefield_animation.py`](examples/wavefield_animation.py): Visualize wave propagation
+
+## Documentation
+
+For detailed API documentation and tutorials, visit: [Documentation]() *(coming soon)*
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest tests/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Acknowledgments
+
+This project includes code derived from [Deepwave](https://github.com/ar4/deepwave) by Alan Richardson. We gratefully acknowledge the foundational work that made TIDE possible.
+
+## Citation
+
+If you use TIDE in your research, please cite:
+
+```bibtex
+@software{tide2025,
+  author = {Vcholerae1},
+  title = {TIDE: Torch-based Inversion \& Development Engine},
+  year = {2025},
+  url = {https://github.com/vcholerae1/tide}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+
+
+```mermaid
+graph TD
+    %% --- Styling Definitions ---
+    classDef userLayer fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b;
+    classDef apiLayer fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
+    classDef coreLayer fill:#ffe0b2,stroke:#f57c00,stroke-width:2px,color:#e65100;
+    classDef supportLayer fill:#e8f5e9,stroke:#388e3c,stroke-width:1px,color:#1b5e20;
+    classDef nativeLayer fill:#cfd8dc,stroke:#455a64,stroke-width:3px,color:#263238;
+    classDef torchFrame fill:none,stroke:#ee3333,stroke-width:2px,stroke-dasharray: 5 5,color:#ee3333;
+
+    %% --- Top Level ---
+    UserCode[用户代码 / 脚本<br>FWI, 建模任务]:::userLayer
+
+    subgraph PyTorch_Environment [PyTorch 生态系统 <br> Autograd Engine & Tensor Management]
+        style PyTorch_Environment fill:#fff3f3,stroke:#ffcdd2
+
+        %% --- Layer 1: User API ---
+        subgraph L1_UserAPI [第1层: 用户 API 层]
+            direction LR
+            MaxwellTM([MaxwellTM <br> nn.Module 子类]):::apiLayer
+            Utils[工具函数 <br> ricker, wavelets, validation]:::apiLayer
+        end
+
+        UserCode -->|初始化 & 调用| MaxwellTM
+        UserCode -.->|使用| Utils
+
+        %% --- Layer 3: Support (Side by Side) ---
+        subgraph L3_Support [第3层: 数值计算与辅助支持]
+            Staggered[staggered.py <br> 交错网格/PML定义]:::supportLayer
+            Callbacks[callbacks.py <br> 状态监控/观察者]:::supportLayer
+            Storage[storage.py <br> 波场快照存储策略<br>CPU/GPU/DISK/Compress]:::supportLayer
+        end
+
+        %% --- Layer 2: Core Solver ---
+        subgraph L2_Core [第2层: 核心求解器 maxwell.py]
+            MaxwellTMForwardFunc{{MaxwellTMForwardFunc <br> autograd.Function}}:::coreLayer
+            BackendDispatch[后端分发器 <br> maxwell_func]:::coreLayer
+        end
+
+        %% Connections within Python Levels
+        MaxwellTM -->|调用 forward| MaxwellTMForwardFunc
+        MaxwellTMForwardFunc -->|管理| BackendDispatch
+        MaxwellTMForwardFunc -.->|依赖| Storage
+        MaxwellTM -.->|配置| Staggered
+        MaxwellTM -->|触发| Callbacks
+
+        %% --- Data Flow Arrows ---
+        %% Forward Path
+        MaxwellTMForwardFunc == "正向传播 (Forward Pass)<br>FDTD 时间步进" ==> BackendDispatch
+        BackendDispatch -- 路径 A: Python (调试) --> PyImpl[纯 Python 实现<br>update_E/H]:::supportLayer
+
+        %% Backward Path
+        PyTorch_Environment -.- |"loss.backward() <br> 触发自动微分"| MaxwellTMForwardFunc
+        BackendDispatch <== "反向传播 (Backward Pass)<br>伴随状态法 / 梯度计算" == MaxwellTMForwardFunc
+    end
+
+    %% --- Layer 4: Native Backend ---
+    subgraph L4_Native [第4层: C/CUDA 内核层 libtide_C.so]
+        direction LR
+        CUDA_Kernels[maxwell.cu <br> GPU FDTD 内核]:::nativeLayer
+        Born_Kernels[maxwell_born.cu <br> Born 近似内核]:::nativeLayer
+        C_Staggered[staggered_grid.h <br> C数据结构]:::nativeLayer
+    end
+
+    %% Crossing the boundary
+    BackendDispatch -- "路径 B: C/CUDA (高性能)<br>ctypes 调用" --> CUDA_Kernels
+    BackendDispatch -- "反向路径调用" --> Born_Kernels
+    CUDA_Kernels -.-> C_Staggered
+    Born_Kernels -.-> C_Staggered
+    Storage -.->|C++实现| CUDA_Kernels
+
+    %% Legend
+    subgraph Legend [图例]
+        L_Py[Python 模块]:::apiLayer
+        L_Core[核心 Autograd]:::coreLayer
+        L_Sup[辅助支持]:::supportLayer
+        L_Nat[C/CUDA 原生库]:::nativeLayer
+        L_Flow_F[正向数据流] ==> L_Flow_F_End
+        L_Flow_B[反向数据流] <== L_Flow_B_End
+    end
+```