Metadata-Version: 2.2
Name: tide-GPR
Version: 0.0.22
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
- **Snapshot Compression**: optional `storage_compression="bf16"` for intermediate storage

## Installation

### From PyPI

Ensure you have proper PyTorch installation with CUDA binding for your system.

Maybe you need 
```bash
uv pip install torch --index-url https://download.pytorch.org/whl/cu128
``` 
cu128 is for CUDA 12.8, change it according to your CUDA version.

Then install TIDE via uv or pip:

```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
```

To rebuild only the native backend during development:

```bash
bash scripts/build_csrc.sh
```

**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

## Mixed Precision

`tide.maxwelltm` exposes an explicit TM2D mixed-precision mode:

```python
out = tide.maxwelltm(
    epsilon,
    sigma,
    mu,
    grid_spacing=0.02,
    dt=4e-11,
    source_amplitude=src,
    source_location=src_loc,
    receiver_location=rec_loc,
    compute_precision="fp16_scaled",
)
```

Notes:
- External API remains SI-compatible (`epsilon_r`, `mu_r`, `sigma`, `dx/dy`, `dt`).
- `compute_precision="fp16_scaled"` is CUDA-only and keeps public tensors in
  float32 while using fp16 field/snapshot storage internally.
- `storage_compression="bf16"` remains available on the default path. It is not
  supported together with `compute_precision="fp16_scaled"`.
- The v1 `fp16_scaled` path primarily reduces memory footprint; it does not
  promise faster kernels by itself.

## 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
- [`example_wavefield_animation.py`](examples/example_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.
