Merge pull request #445 from PyLops/dev

Move PyLops v2 from dev to master

Author: mrava87

.github/workflows/build.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2

.github/workflows/flake8.yaml

@@ -0,0 +1,24 @@
+# This workflow runs Flake8 on the PR
+# For more information see: https://github.com/marketplace/actions/python-flake8-lint
+name: PyLops-flake8
+
+on: [push, pull_request]
+
+jobs:
+  flake8-lint:
+    runs-on: ubuntu-latest
+    name: Lint
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@v2
+      - name: Set up Python environment
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+      - name: flake8 Lint
+        uses: py-actions/flake8@v2
+        with:
+          ignore: "E203,E501,W503,E402"
+          max-line-length: "88"
+          path: "pylops"
+          args: "--per-file-ignores=__init__.py:F401,F403,F405"

.gitignore

@@ -25,6 +25,7 @@ pylops/version.py
 .ipynb_checkpoints/
 notebooks
 TODO
+.vscode/
 
 # Documentation #
 docs/build

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
       - id: check-yaml
 
   - repo: https://github.com/psf/black
-    rev: 21.12b0
+    rev: 22.3.0
     hooks:
       - id: black
         args: # arguments to configure black
@@ -19,4 +19,12 @@ repos:
     hooks:
       - id: isort
         name: isort (python)
-        args: ["--profile", "black", "--filter-files", "--line-length=88"]
+        args:
+          [
+            "--profile",
+            "black",
+            "--skip",
+            "__init__.py",
+            "--filter-files",
+            "--line-length=88",
+          ]

CHANGELOG.md

@@ -1,3 +1,71 @@
+# 2.0.0
+PyLops has undergone significant changes in this release, including new ``LinearOperator``s, more features, new examples and bugfixes.
+To aid users in navigating the breaking changes, we provide the following document [MIGRATION_V1_V2.md](https://github.com/PyLops/pylops/blob/dev/MIGRATION_V1_V2.md).
+
+### New Features
+
+* Multiplication of linear operators by N-dimensional arrays is now supported via the new ``dims``/``dimsd`` properties.
+  Users do not need to use ``.ravel`` and ``.reshape`` as often anymore. See the migration guide for more information.
+* Typing annotations for several submodules (``avo``, ``basicoperators``, ``signalprocessing``, ``utils``, ``optimization``, ``waveeqprocessing``)
+* New [pylops.TorchOperator](https://pylops.readthedocs.io/en/latest/api/generated/pylops.TorchOperator.html#pylops.TorchOperator)
+  wraps a Pylops operator into a PyTorch function
+* New [pylops.signalprocessing.Patch3D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Patch3D.html)
+  applies a linear operator repeatedly to patches of the model vector
+* Each of [Sliding1D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Sliding1D.html),
+  [Sliding2D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Sliding2D.html),
+  [Sliding3D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Sliding3D.html),
+  [Patch2D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Patch2D.html) and
+  [Patch3D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.signalprocessing.Patch3D.html) have an associated
+  `slidingXd_design` or `patchXd_design` functions associated with them to aid the user in designing the windows
+* [FirstDerivative](https://pylops.readthedocs.io/en/latest/api/generated/pylops.FirstDerivative.html) and
+  [SecondDerivative](https://pylops.readthedocs.io/en/latest/api/generated/pylops.SecondDerivative.html), and therefore
+  other derivative operators which rely on the (e.g., [Gradient](https://pylops.readthedocs.io/en/latest/api/generated/pylops.Gradient.html))
+  support higher order stencils
+* [pylops.waveeqprocessing.Kirchhoff](https://pylops.readthedocs.io/en/latest/api/generated/pylops.waveeqprocessing.Kirchhoff.html)
+  substitutes [pylops.waveeqprocessing.Demigration](https://pylops.readthedocs.io/en/v1.18.3/api/generated/pylops.waveeqprocessing.Demigration.html)
+  and incorporates a variety of new functionalities
+* New [pylops.waveeqprocessing.AcousticWave2D](https://pylops.readthedocs.io/en/latest/api/generated/pylops.waveeqprocessing.AcousticWave2D.html) wraps the [Devito](https://www.devitoproject.org/)
+  acoutic wave propagator providing a wave-equation based Born modeling operator with a reverse-time migration adjoint
+* Solvers can now be implemented via the [pylops.optimization.basesolver.Solver](https://pylops.readthedocs.io/en/latest/api/generated/pylops.optimization.basesolver.Solver.html) class.
+  They can now be used through a functional interface with lowercase name (e.g., [splitbregman](https://pylops.readthedocs.io/en/latest/api/generated/pylops.optimization.sparsity.splitbregman.html))
+  or via class interface with CamelCase name (e.g., [SplitBregman](https://pylops.readthedocs.io/en/latest/api/generated/pylops.optimization.cls_sparsity.SplitBregman.html)).
+  Moreover, solvers now accept callbacks defined by the [Callbacks](https://pylops.readthedocs.io/en/latest/api/generated/pylops.optimization.callback.Callbacks.html)
+  interface (see e.g., [MetricsCallback](https://pylops.readthedocs.io/en/latest/api/generated/pylops.optimization.callback.MetricsCallback.html)).
+* [Metrics](https://pylops.readthedocs.io/en/latest/api/others.html#metrics) such as [mean absolute error (mae)](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.metrics.mae.html#pylops.utils.metrics.mae), [mean squared error (mse)](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.metrics.mse.html#pylops.utils.metrics.mse) and others
+* New [pylops.utils.signalprocessing.dip_estimate](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.signalprocessing.dip_estimate.html)
+  estimates local dips in an image (measured in radians) in a stabler way than [pylops.utils.signalprocessing.dip_estimate](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.signalprocessing.slope_estimate.html) did for slopes.
+* New [pylops.utils.tapers.tapernd](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.tapers.tapernd.html) for N-dimensional tapers
+* New wavelets [Klauder](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.wavelets.klauder.html) and [Ormsby](https://pylops.readthedocs.io/en/latest/api/generated/pylops.utils.wavelets.ormsby.html)
+
+### Documentation
+
+* [Installation](https://pylops.readthedocs.io/en/latest/installation.html) has been revamped
+* Revamped guide on how to [implement a new `LinearOperator` from scratch](https://pylops.readthedocs.io/en/latest/adding.html)
+* New guide on how to [implement a new solver from scratch](https://pylops.readthedocs.io/en/latest/addingsolver.html)
+* New tutorials:
+  * [Solvers (Advanced)](https://pylops.readthedocs.io/en/latest/tutorials/classsolvers.html)
+  * [Deblending](https://pylops.readthedocs.io/en/latest/tutorials/deblending.html)
+  * [Automatic Differentiation](https://pylops.readthedocs.io/en/latest/tutorials/torchop.html)
+* New gallery examples:
+  * [Patching](https://pylops.readthedocs.io/en/latest/gallery/plot_patching.html#sphx-glr-gallery-plot-patching-py)
+  * [Wavelets](https://pylops.readthedocs.io/en/latest/gallery/plot_wavs.html)
+
+# 1.18.3
+* Fixed ``pylops.optimization.basic.lsqr``, ``pylops.optimization.sparsity.ISTA``, and
+  ``pylops.optimization.sparsity.FISTA`` to work with cupy arrays. This change was required
+  by how recent cupy versions handle scalars, which are not converted directly into float types,
+  rather kept as cupy arrays.
+* Fixed bug in ``pylops.waveeqprocessing.Deghosting`` introduced in
+  commit [7e596d4](https://github.com/PyLops/pylops/commit/7e596d4dad3793d6430204b7a9b214a9dc39616c)
+
+# 1.18.2
+* Refractored `pylops.utils.dottest`, and added two new optional input parameters
+  (``atol`` and ``rtol``)
+* Added optional parameter ``densesolver`` to ``pylops.LinearOperator.div``
+
+# 1.18.1
+* !DELETED! due to a mistake in the release process
+
 # 1.18.0
 * Added `NMO` example to gallery
 * Extended `pylops.basicoperators.Laplacian` to N-dimensional arrays

CONTRIBUTING.md

@@ -2,10 +2,17 @@
 
 Contributions are welcome and greatly appreciated!
 
+The best way to get in touch with the core developers and maintainers is to
+join the [PyLops slack channel](https://pylops.slack.com/) as well as
+open new *Issues* directly from the GitHub repo.
 
-## Types of Contributions
+Moreover, take a look at the [Roadmap](https://pylops.readthedocs.io/en/stable/roadmap.html)
+page for a list of current ideas for improvements and additions to the PyLops library.
 
-### Report Bugs
+
+## Welcomed contributions
+
+### Bug reports
 
 Report bugs at https://github.com/PyLops/pylops/issues
 
@@ -16,7 +23,7 @@ reporting it including:
 * Any details about your Python environment.
 * Detailed steps to reproduce the bug.
 
-### Propose New Operators or Features
+### New operators and features
 
 The best way to send feedback is to open an issue at
 https://github.com/PyLops/pylops/issues
@@ -27,52 +34,57 @@ If you are proposing a new operator or a new feature:
 * Explain in detail how it should work.
 * Keep the scope as narrow as possible, to make it easier to implement.
 
-### Implement Operators or Features
-Look through the Git issues for operator or feature requests.
-Anything tagged with *enhancement* is open to whoever wants to
-implement it.
+### Fix issues
+There is always a backlog of issues that need to be dealt with.
+Look through the GitHub Issues for operator/feature requests or bugfixes.
 
-### Add Examples or improve Documentation
+### Add examples or improve documentation
 Writing new operators is not the only way to get involved and
 contribute. Create examples with existing operators as well as
 improving the documentation of existing operators is as important
 as making new operators and very much encouraged.
 
 
-## Getting Started to contribute
+## Step-by-step instructions for contributing
 
 Ready to contribute?
 
-1. Fork the `PyLops` repo.
+1. Follow all installation instructions in the [Step-by-step installation for developers](https://pylops.readthedocs.io/en/stable/installation.html#step-by-step-installation-for-developers) section of the documentation.
 
-2. Clone your fork locally:
+2. Create a branch for local development, usually starting from the dev branch:
     ```
-    git clone https://github.com/your_name_here/pylops.git
+    git checkout -b name-of-your-branch dev
     ```
+    Now you can make your changes locally.
 
-3. Follow the installation instructions for *developers* that you find
-in the README.md or in the online documentation.
-Ensure that you are able to *pass all the tests before moving forward*.
-
-4. Create a branch for local development:
+3. When you're done making changes, check that your code follows the guidelines for [Implementing new operators](https://pylops.readthedocs.io/en/stable/adding.html) and
+that the both old and new tests pass successfully:
     ```
-    git checkout -b name-of-your-branch
+    make tests
     ```
-    Now you can make your changes locally.
 
-5. When you're done making changes, check that old and new tests pass
-succesfully:
+4. Run flake8 to check the quality of your code:
     ```
-    make tests
+    make lint
     ```
+    Note that PyLops does not enforce full compliance with flake8, rather this is used as a
+guideline and will also be run as part of our CI.
+Make sure to limit to a minimum flake8 warnings before making a PR.
+
+5. Update the docs
+   ```
+   make docupdate
+   ```
 
-6. Commit your changes and push your branch to GitLab::
+6. Commit your changes and push your branch to GitHub:
     ```
     git add .
     git commit -m "Your detailed description of your changes."
     git push origin name-of-your-branch
     ```
     Remember to add ``-u`` when pushing the branch for the first time.
+    We recommend using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+    to format your commit messages, but this is not enforced.
 
 7. Submit a pull request through the GitHub website.
 
@@ -83,3 +95,13 @@ Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include new tests for all the core routines that have been developed.
 2. If the pull request adds functionality, the docs should be updated accordingly.
+3. Ensure that the updated code passes all tests.
+
+## Project structure
+This repository is organized as follows:
+* **pylops**:     Python library containing various linear operators and auxiliary routines
+* **pytests**:    set of pytests
+* **testdata**:   sample datasets used in pytests and documentation
+* **docs**:       Sphinx documentation
+* **examples**:   set of python script examples for each linear operator to be embedded in documentation using sphinx-gallery
+* **tutorials**:  set of python script tutorials to be embedded in documentation using sphinx-gallery