Revamped LSM module

MIGRATION_V1_V2.md

@@ -41,6 +41,13 @@ should be used as a checklist when converting a piece of code using PyLops from
   As previously stated in a warning message, the recommended option ``transpose=False`` is now selected as default.
   Ensure that the input array ``G`` is organized as follows ``[n_fmax X n_s X n_r]``.
 - The optional arguments ``design`` has been deprecated in ``pylops.waveeqprocessing.seismicinterpolation.SeismicInterpolation``.
+- The ``pylops.waveeqprocessing.lsm.Demigration`` operator has been renamed into
+  ``pylops.waveeqprocessing.kirchhoff.Kirchhoff``. Its internal working has been modified taking into account the
+  geometrical spreading of propagation. To maintain the previous behaviour simply fill the distance table ``dist`` with
+  ones.
+- The optional parameter ``engine`` has been added to ``pylops.waveeqprocessing.lsm.LSM`` to allow users to choose
+  between the original ``pylops.waveeqprocessing.kirchhoff.Kirchhoff`` modelling operator and the new
+  ``pylops.waveeqprocessing.twoway.AcousticWave2D`` modelling operator.
 
 ## Utils
 - `utils.dottest`: Change `tol` into `rtol`. Absolute tolerance is now also supported via the keyword `atol`.

docs/source/api/index.rst

@@ -122,7 +122,8 @@ Wave-Equation processing
     UpDownComposition3D
     MDC
     PhaseShift
-    Demigration
+    Kirchhoff
+    AcousticWave2D
 
 
 Geophysical subsurface characterization

docs/source/installation.rst

@@ -315,6 +315,52 @@ of GPUs should install it prior to installing PyLops as described in :ref:`Optio
    PyLops via ``make dev-install_conda`` (``conda``) or ``make dev-install`` (``pip``).
 
 
+In alphabetic order:
+
+
+Devito
+------
+`Devito <https://github.com/devitocodes/devito>`_ is library used to solve PDEs via
+the finite-difference method. It is used in PyLops to compute wavefields
+:py:class:`pylops.waveeqprocessing.AcousticWave2D`
+
+
+Install it via ``pip`` with
+
+.. code-block:: bash
+
+   >> pip install devito
+
+
+FFTW
+----
+Three different "engines" are provided by the :py:class:`pylops.signalprocessing.FFT` operator:
+``engine="numpy"`` (default), ``engine="scipy"`` and ``engine="fftw"``.
+
+The first two engines are part of the required PyLops dependencies.
+The latter implements the well-known `FFTW <http://www.fftw.org>`_
+via the Python wrapper :py:class:`pyfftw.FFTW`. While this optimized FFT tends to
+outperform the other two in many cases, it is not included by default.
+To use this library, install it manually either via ``conda``:
+
+.. code-block:: bash
+
+   >> conda install --channel conda-forge pyfftw
+
+or via pip:
+
+.. code-block:: bash
+
+   >> pip install pyfftw
+
+.. note::
+   FFTW is only available for :py:class:`pylops.signalprocessing.FFT`,
+   not :py:class:`pylops.signalprocessing.FFT2D` or :py:class:`pylops.signalprocessing.FFTND`.
+
+.. warning::
+   Intel MKL FFT is not supported.
+
+
 Numba
 -----
 Although we always strive to write code for forward and adjoint operators that takes advantage of
@@ -335,7 +381,8 @@ If interested to use Numba backend from ``conda``, you will need to manually ins
    >> conda install numba
 
 It is also advised to install the additional package
-`icc_rt <https://numba.pydata.org/numba-doc/latest/user/performance-tips.html#intel-svml>`_ to use optimised transcendental functions as compiler intrinsics.
+`icc_rt <https://numba.pydata.org/numba-doc/latest/user/performance-tips.html#intel-svml>`_ to use
+optimised transcendental functions as compiler intrinsics.
 
 .. code-block:: bash
 
@@ -344,12 +391,12 @@ It is also advised to install the additional package
 Through ``pip`` the equivalent would be:
 
 .. code-block:: bash
-   
+
    >> pip install numba
    >> pip install icc_rt
 
 However, it is important to note that ``icc_rt`` will only be identified by Numba if
-``LD_LIBRARY_PATH`` properly is set.
+``LD_LIBRARY_PATH`` is properly set.
 If you are using a virtual environment, you can ensure this with:
 
 .. code-block:: bash
@@ -371,39 +418,28 @@ Numba also offers threading parallelism through a variety of `Threading Layers <
 You may need to set the environment variable ``NUMBA_NUM_THREADS`` define how many threads to use out of the available ones (``numba -s | grep "CPU Count"``).
 It can also be checked dynamically with ``numba.config.NUMBA_DEFAULT_NUM_THREADS``.
 
-FFTW
-----
-Three different "engines" are provided by the :py:class:`pylops.signalprocessing.FFT` operator:
-``engine="numpy"`` (default), ``engine="scipy"`` and ``engine="fftw"``.
 
-The first two engines are part of the required PyLops dependencies.
-The latter implements the well-known `FFTW <http://www.fftw.org>`_
-via the Python wrapper :py:class:`pyfftw.FFTW`. While this optimized FFT tends to
-outperform the other two in many cases, it is not included by default.
-To use this library, install it manually either via ``conda``:
+PyWavelets
+----------
+`PyWavelets <https://pywavelets.readthedocs.io/en/latest/>`_ used to implement the wavelet operators.
+Install it via ``conda`` with:
 
 .. code-block:: bash
 
-   >> conda install --channel conda-forge pyfftw
+   >> conda install pywavelets
 
-or via pip:
+or via ``pip`` with
 
 .. code-block:: bash
 
-   >> pip install pyfftw
-
-.. note::
-   FFTW is only available for :py:class:`pylops.signalprocessing.FFT`,
-   not :py:class:`pylops.signalprocessing.FFT2D` or :py:class:`pylops.signalprocessing.FFTND`.
+   >> pip install PyWavelets
 
-.. warning::
-   Intel MKL FFT is not supported.
 
 scikit-fmm
 ----------
 `scikit-fmm <https://github.com/scikit-fmm/scikit-fmm>`_ is library which implements the
 fast marching method. It is used in PyLops to compute traveltime tables in the
-initialization of :py:class:`pylops.waveeqprocessing.Demigration`
+initialization of :py:class:`pylops.waveeqprocessing.Kirchhoff`
 when choosing ``mode="eikonal"``. As this may not be of interest for many users, this library has not been added
 to the mandatory requirements of PyLops. With ``conda``, install it via
 
@@ -417,6 +453,7 @@ or with ``pip`` via
 
    >> pip install scikit-fmm
 
+
 SPGL1
 -----
 `SPGL1 <https://spgl1.readthedocs.io/en/latest/>`_ is library used to solve sparsity-promoting
@@ -429,20 +466,6 @@ Install it via ``pip`` with:
 
    >> pip install spgl1
 
-PyWavelets
-----------
-`PyWavelets <https://pywavelets.readthedocs.io/en/latest/>`_ used to implement the wavelet operators.
-Install it via ``conda`` with:
-
-.. code-block:: bash
-
-   >> conda install pywavelets
-
-or via ``pip`` with
-
-.. code-block:: bash
-
-   >> pip install PyWavelets
 
 Sympy
 -----

environment-dev.yml

@@ -23,6 +23,7 @@ dependencies:
   - isort
   - black
   - pip:
+    - devito
     - scikit-fmm
     - spgl1
     - pytest-runner

pylops/waveeqprocessing/__init__.py

@@ -13,7 +13,8 @@
     UpDownComposition3D             3D Up-down wavefield composition.
     MDC                             Multi-dimensional convolution.
     PhaseShift                      Phase shift operator.
-    Demigration                     Kirchoff Demigration operator.
+    Kirchhoff                       Kirchoff demigration operator.
+    AcousticWave2D                  Two-way wave equation demigration operator.
 
 and a list of applications:
 
@@ -31,6 +32,7 @@
 from .mdd import *
 from .oneway import *
 from .seismicinterpolation import *
+from .twoway import *
 from .wavedecomposition import *
 
 __all__ = [
@@ -44,6 +46,7 @@
     "WavefieldDecomposition",
     "PhaseShift",
     "Deghosting",
-    "Demigration",
+    "Kirchhoff",
+    "AcousticWave2D",
     "LSM",
 ]