Metadata-Version: 2.1
Name: sweep-loss
Version: 0.1.0
Summary: A PyTorch library of misfit (loss) functions for Full Waveform Inversion (sweep plugin).
Author-email: Shaowen Wang <shaowen.wang@kaust.edu.sa>
License: MIT
Project-URL: Homepage, https://github.com/DeepWave-KAUST/sweep-loss
Project-URL: Issues, https://github.com/DeepWave-KAUST/sweep-loss/issues
Keywords: fwi,geophysics,loss,misfit,seismic,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.13
Requires-Dist: numpy>=1.20
Provides-Extra: gsot
Requires-Dist: scipy>=1.8; extra == "gsot"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: scipy>=1.8; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: scipy>=1.8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"

# sweep-loss

A PyTorch library of misfit (loss) functions for **Full Waveform Inversion (FWI)**.
Designed as a plugin for the [`sweep`](https://github.com/DeepWave-KAUST/sweep) FWI
toolkit — but works in any PyTorch-based FWI / inversion workflow because the
losses are plain `torch.nn.Module` objects.

The package collects, from a single API, the loss functions that have been
proposed in the FWI literature - from classical least-squares to optimal-transport,
adaptive matching filters, and instantaneous-phase / envelope variants - and
exposes them as `torch.nn.Module` so they can be dropped into any PyTorch-based
FWI workflow (e.g. the `sweep` propagator).

## Data convention

All losses accept tensors with the shape used throughout the `sweep` ecosystem:

```
(nshots, nt, nreceivers, nchannel)
```

* `nshots`     - number of independent source experiments in the mini-batch.
* `nt`         - number of time samples (axis = -3, the **time axis**).
* `nreceivers` - number of receivers per shot.
* `nchannel`   - number of recorded components (1 for pressure, 2/3 for elastic, ...).

For convenience every loss also accepts a plain `(nt,)` or `(nt, nrec)` tensor
(treated as a single trace / single shot).

## Quick start

```python
import torch
from sweep_loss import L2Loss

syn = torch.randn(2, 1024, 64, 1, requires_grad=True)   # (nshots, nt, nrec, nchan)
obs = torch.randn(2, 1024, 64, 1)

loss_fn = L2Loss(reduction="mean")
loss = loss_fn(syn, obs)
loss.backward()
```

## Implemented losses

See [`docs/report.md`](docs/report.md) (also rendered on the mkdocs site,
see below) for the full list of misfit formulas with **DOI-linked
references**. Each loss also has its own page under
[`docs/losses/`](docs/losses/).

## Documentation site

The repository ships with an [MkDocs](https://www.mkdocs.org/) +
[Material](https://squidfunk.github.io/mkdocs-material/) site:

```bash
pip install mkdocs mkdocs-material
mkdocs serve   # http://127.0.0.1:8000
# or
mkdocs build   # outputs to ./site
```

The site is configured in `mkdocs.yml`; pages live under `docs/`.

## Installation

```bash
pip install sweep-loss
```

From a clone, with the test extras: `pip install -e ".[test]"`.

## Running the tests

```bash
pytest -q
```

## License

MIT
