TIDE

Documentation

Torch-based Inversion & Development Engine

TIDE is a PyTorch-first electromagnetic FDTD library for forward modeling and full-waveform inversion. It provides differentiable 2D and 3D Maxwell solvers, native C/CUDA kernels, and configurable snapshot storage for memory-intensive gradient calculations.

Capabilities

Capability	API	Status
2D TM forward/inverse modeling	tide.MaxwellTM	Stable
3D forward/inverse modeling	tide.Maxwell3D	Stable with constraints
JVP, VJP, and second VJP	operator.linearize(model)	Stable
Snapshot storage	storage_mode	Device, CPU, disk, none, or auto
Snapshot compression	storage_compression	Optional BF16 compression
Debye dispersion	DebyeDispersion	Advanced

TIDE also includes PML boundaries, staggered-grid operators, callbacks, CFL resampling, shot batching, and inversion workflow helpers. Check the limitations guide before scaling up 3D or inversion workloads.

Installation

TIDE requires Python 3.12 or newer and PyTorch 2.12 or newer.

Install the package from PyPI:

uv pip install tide-GPR

You can also use pip:

pip install tide-GPR

For GPU use, install the PyTorch build that matches your CUDA environment before installing TIDE.

Build from source

Building from source requires CMake 3.28 or newer. A CUDA Toolkit is optional.

git clone https://github.com/vcholerae1/tide.git
cd tide
uv build

See the build guide for native-backend builds and troubleshooting.

Quick start

This example runs a small 2D TM forward simulation on CUDA when available and falls back to CPU otherwise:

import torch
import tide

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
epsilon = torch.full((96, 96), 4.0, device=device)
model = tide.EMModel(
    epsilon=epsilon,
    sigma=torch.zeros_like(epsilon),
    mu=torch.ones_like(epsilon),
)

nt, dt = 300, 4e-11
experiment = tide.Experiment(
    acquisition=tide.Acquisition(
        source_location=torch.tensor([[[20, 48]]], device=device),
        receiver_location=torch.tensor([[[20, 60]]], device=device),
    ),
    source_amplitude=tide.ricker(8e8, nt, dt, device=device).view(1, 1, nt),
)
operator = tide.MaxwellTM(
    tide.Discretization(
        spacing=0.02,
        dt=dt,
        boundary=tide.CPML(width=10),
    ),
    experiment,
    execution=tide.ExecutionOptions(fallback=tide.FallbackPolicy.REFERENCE),
)

result = operator(model)
print(result.receiver_data.shape)  # [nt, n_shots, n_receivers]

Documentation

Start with the path that matches your task:

• Getting started: installation, backend checks, and a first 2D simulation
• API orientation: models, experiments, operators, and derivative sessions
• Modeling: sources, receivers, boundaries, and tensor layouts
• Inversion: losses, backpropagation, and optimizer workflows
• Configuration: storage, callbacks, backends, and CFL controls
• API reference: public contracts and operators

Before relying on advanced configurations, review the known limitations and verification guide.

Development

Install the development dependencies and run the test suite:

uv sync --group dev
uv run pytest

Preview the documentation:

npm install
npm run dev

Issues and pull requests are welcome.

Citation

If you use TIDE in your research, cite:

@software{tide2025,
  author = {Vcholerae1},
  title = {TIDE: Torch-based Inversion \& Development Engine},
  year = {2025},
  url = {https://github.com/vcholerae1/tide}
}

Acknowledgments

TIDE includes code derived from Deepwave by Alan Richardson.

License

TIDE is available under the MIT License.