Metadata-Version: 2.1
Name: pyawd
Version: 0.3.66
Summary: A Pytorch dataset for Acoustic Wave Propagation
Author-email: Tribel Pascal <pascal.tribel@ulb.be>
Project-URL: Homepage, https://github.com/pascaltribel/PyAWD
Project-URL: Issues, https://github.com/pascaltribel/PyAWD/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: devito
Requires-Dist: torch
Requires-Dist: matplotlib
Requires-Dist: tqdm
Requires-Dist: numpy
Requires-Dist: sympy
Requires-Dist: opencv-python
Requires-Dist: pyvista
Requires-Dist: trame
Requires-Dist: vtk
Requires-Dist: imageio
Requires-Dist: imageio-ffmpeg
Requires-Dist: npy-append-array
Requires-Dist: mpi4py

# PyAWD: a Python acoustic wave propagation dataset using PyTorch and Devito
A package for generating a Pytorch dataset containing simulations of the acoustic wave propagation in the Marmousi velocity field. It uses the [Devito Python Library](https://www.devitoproject.org) to solve the acoustic wave PDE from various random initial conditions.

## Acoustic Wave Equation
The equation of propagation of an acoustic wave is given by $\frac{d^2u}{dt^2} = c \nabla^2 u + f$, where
- $u(x, y, t)$ is the displacement field and can be either a scalar or a vector field
- $c(x, y, t)$ is the wave  propagation speed
- $\nabla^2$ is the _laplacian operator_
- $f(x, y, t)$ is an external force applied on the system, for which the value can vary through time

## Installation
The package (along with the dependencies) is accessible via [PyPI](https://pypi.org/project/PyAWD/):

```bash
pip install pyawd
```

## Documentation
The API documentation is available [here](https://pascaltribel.github.io/pyawd/).
Basic help is provided for each class and function and is accessible via the Python `help()` function.
We provide a bunch of Notebooks to start using the tool. They are presented in the [[examples](https://github.com/pascaltribel/pyawd/tree/main/examples) directory. Those are readable online:
- [`ScalarAcousticWavePropagation.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/ScalarAcousticWavePropagation.html): an introduction to PDE solving and simulation using Devito applied on the scalar acoustic wave propagation
- [`VectorAcousticWavePropagation.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/VectorAcousticWavePropagation.html): an introduction to PDE solving and simulation using Devito applied on the vector acoustic wave propagation
- [`VectorAcousticWaveDataset.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/VectorAcousticWaveDataset.html): an introduction to the VectorAcousticWaveDataset possibilities
- [`Marmousi.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/Marmousi.html): a visualisation of the Marmousi velocity field used in the simulations
- [`Interrogators.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/Interrogators.html): an introduction to the PyAWD Interrogators usage
- [`GenerateVectorAcousticWaveDataset.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/GenerateVectorAcousticWaveDataset.html): how to generate dataset using `pyawd`
- [`SpatioTemporalVaryingWavePropagationSpeedField.ipynb`](https://pascaltribel.github.io/pyawd/pyawd/SpatioTemporalVaryingWavePropagationSpeedField.html): how to create a spatio-temporal varying propagation field

## Getting started

Basic imports:
```python
from pyawd import *
```

Let us generate a Dataset made of 10 simulations. Each simulation is run in a $250\times 250$ matrix. We store the field state every $2$ seconds and we run the simulation for $10$ seconds:

```python
dataset = ScalarAcousticWaveDataset(2, nx=250, dt=2, t=10)
```

Then we plot the first simulation. The &#128960; character shows the interrogator position:

```python
dataset.plot_item(0)
```

Which outputs the following figure:

<img src="https://github.com/pascaltribel/pyawd/blob/8cc0547545559c3a02199e86d2cf504edf805a48/examples/example.png" alt="Example" width="60%"/>

By default, the point `(0, 0)` contains an interrogator. This means that the continuous measurement on this position (at least with a $\Delta t=dt$) can be obtained by:

```python
dataset.interrogate((0, 0))
```

## More advanced usage
Using the `VectorAcousticWaveDataset` class, you can produce simulations in 2D which are more realistic:

```python
dataset = VectorAcousticWaveDataset(2, nx=250, dt=2, interrogators=[(-10, 0), (10, 0)], t=10)
```

Especially, the `interrogate` method provides measurements along two orthogonal dimensions:

```python
dataset.plot_item(0)
dataset.plot_interrogators_response(0)
```
