Re-work Solver

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 # Sphinx
 docs/_build/
 docs/api/
+docs/savefig/
 
 # Pytest and coverage related
 htmlcov

CHANGELOG.rst

@@ -34,6 +34,75 @@ latest: towards v1.0
 
   - No ``name`` parameter any longer.
 
+- ``Model``:
+
+  - A ``Model`` knows now its ``grid``. As a consequence, all the functions
+    that required the ``grid`` and the ``model`` require now only the
+    ``model``; e.g., ``emg3d.solver.solve`` or ``emg3d.fields.get_h_field``.
+
+- ``TensorMesh``:
+
+  - The basic mesh (without ``discretize``) is renamed from ``_TensorMesh`` to
+    ``BaseMesh``.
+
+  - Reduced ``BaseMesh`` to the attributes ``origin``, ``h``, ``shape_cells``,
+    ``shape_nodes``, ``n_cells``, ``n_edges_x``, ``n_edges_y``, ``n_edges_z``,
+    ``nodes_x``, ``nodes_y``, ``nodes_z``, ``cell_centers_x``,
+    ``cell_centers_y``, ``cell_centers_z``, ``shape_edges_x``,
+    ``shape_edges_y``, ``shape_edges_z``, and ``cell_volumes``. These are the
+    only required attributes for ``emg3d``.
+
+- ``solver.solve``:
+
+  - New signature: ``def solve(model, sfield, sslsolver, semicoarsening,
+    linerelaxation, verb, **kwargs)`` (the old signature was ``def solve(grid,
+    model, sfield, efield, cycle, sslsolver, semicoarsening, linerelaxation,
+    verb, **kwargs)``):
+
+    - ``grid`` is no longer a parameter; it is contained in ``model``.
+    - ``efield`` and ``cycle`` are degraded to ``kwargs``.
+
+  - The defaults for ``sslsolver``, ``semicoarsening``, and ``linerelaxation``
+    is new ``True`` (before it was ``False``). This is not necessarily the
+    fastest setting, but generally the most robust setting.
+
+  - New parameter ``plain``, which is by default ``False``. If it is set to
+    ``True`` it uses plain multigrid, hence ``sslsolver=False``,
+    ``semicoarsening=False``, and ``linerelaxation=False``, unless these
+    parameters were set to anything different than ``True``.
+
+  - Some verbosity levels changed (consistency throughout module). The new
+    levels are [old level in brackets]:
+
+    - -1: Nothing. [0]
+    - 0: Warnings. [1]
+    - 1: One-liner at the end. [2]
+    - 2: One-liner (dynamically updated). [-1]
+    - 3: Runtime and information about the method. [same]
+    - 4: Additional information for each MG-cycle. [same]
+    - 5: Everything (slower due to additional error computations). [same]
+
+    Level three now updates dynamically just as level 2.
+
+- Other changes in ``solver``:
+
+  - ``RegularGridProlongator``: Changed signature from ``x, y, cxy`` to ``cx,
+    cy, x, y`` (it now incorporates the function
+    ``_get_prolongation_coordinates``.)
+
+- ``fields``:
+
+  - The function ``emg3d.fields.get_receiver`` was removed and replaced by
+    its successor ``emg3d.fields.get_receiver_response``;
+    ``emg3d.fields.get_receiver_response`` does not exist any longer.
+  - A ``Field`` knows now its ``grid``. As a consequence, all the functions
+    that required the ``grid`` and the ``field`` require now only the
+    ``field``; e.g., ``emg3d.fields.get_receiver``.
+
+
+- ``maps``:
+
+  - Renamed ``_Map`` to ``BaseMap``.
 
 - Removed all deprecated features.
 

CREDITS.rst

@@ -1,17 +1,24 @@
 Credits
 #######
 
-This project was started by **Dieter Werthmüller**. Every contributor will be
-listed here and is considered to be part of «The emg3d Developers»:
-
-- `Dieter Werthmüller <https://github.com/prisae>`_
-
-
-Various bits got improved through discussions on Slack at `SWUNG
-<https://softwareunderground.org>`_ and at `SimPEG <https://simpeg.xyz>`_,
-thanks to both communities. Special thanks to @jokva (general), @banesullivan
-(visualization), @joferkington (interpolation), and @jcapriot (volume
-averaging).
+This project was started by **Dieter Werthmüller** at
+`Delft University of Technology <https://www.tudelft.nl>`_ as part of the
+*Gitaro.JIM* project (till 05/2021, emg3d v1.0.0), funded through
+`MarTERA <https://www.martera.eu>`_ as part of Horizon 2020, a funding scheme
+of the European Research Area.
+
+For a list of code contributors see
+https://github.com/emsig/emg3d/graphs/contributors.
+
+There are various contributors who improved emg3d not through code commits but
+through discussions and help on Slack at
+`SWUNG <https://softwareunderground.org>`_ and at
+`SimPEG <https://simpeg.xyz>`_,
+thanks to both communities. Special thanks to
+`@jokva <https://github.com/jokva>`_ (general),
+`@banesullivan <https://github.com/banesullivan>`_ (visualization),
+`@joferkington <https://github.com/joferkington>`_ (interpolation), and
+`@jcapriot <https://github.com/jcapriot>`_ (volume averaging).
 
 
 Historical credits
@@ -27,15 +34,8 @@ original code was written in Matlab, where the most time- and memory-consuming
 parts were sped up through mex-files (written in C). It included multigrid with
 or without BiCGSTAB, VTI resistivity, semicoarsening, and line relaxation; the
 number of cells had to be powers of two, and coarsening was done only until the
-first dimension was at two cells. As such it corresponded roughly to *emg3d
-v0.3.0*.
+first dimension was at two cells. As such it corresponded roughly to ``emg3d
+v0.3.0``.
 
-See the :doc:`references` in the manual for the full citations and a more
+See the *References* section in the manual for the full citations and a more
 extensive list.
-
-.. note::
-
-    This software was initially (till 05/2021) developed at *Delft University
-    of Technology* (https://www.tudelft.nl) within the **Gitaro.JIM** project
-    funded through MarTERA as part of Horizon 2020, a funding scheme of the
-    European Research Area (ERA-NET Cofund, https://www.martera.eu).

MANIFEST.in

@@ -1,11 +1,12 @@
 prune docs
 prune tests
 prune .github
-exclude MAINTENANCE.rst
 exclude MANIFEST.in
+exclude CHANGELOG.rst
 exclude Makefile
 exclude requirements.txt
 exclude requirements-dev.txt
 exclude runtests.sh
 exclude .gitignore
 exclude .coveragerc
+exclude .readthedocs.yml

Makefile

@@ -18,11 +18,10 @@ dev-install:
 	pip install -r requirements-dev.txt && pip install -e .
 
 pytest:
-	rm -rf .coverage htmlcov/ .pytest_cache/    # clean up
-	pytest --cov=emg3d --flake8 && coverage html
+	rm -rf .coverage htmlcov/ .pytest_cache/ && pytest --cov=emg3d --flake8 && coverage html
 
 flake8:
-	flake8 docs/conf.py setup.py emg3d/ tests/
+	flake8 docs/ setup.py emg3d/ tests/
 
 doc:
 	cd docs && make html && cd ..
@@ -37,4 +36,4 @@ clean:
 	rm -rf build/ dist/ .eggs/ emg3d.egg-info/ emg3d/version.py  # build
 	rm -rf */__pycache__/ */*/__pycache__/      # python cache
 	rm -rf .coverage htmlcov/ .pytest_cache/    # tests and coverage
-	rm -rf docs/api/ docs/_build/               # docs
+	rm -rf docs/api/ docs/_build/ docs/savefig/ # docs

README.rst

@@ -4,111 +4,62 @@
 
 ----
 
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3229006.svg
+   :target: https://doi.org/10.5281/zenodo.3229006
+   :alt: Zenodo DOI
+.. image:: https://img.shields.io/badge/Slack-simpeg-4A154B.svg?logo=slack
+    :target: http://slack.simpeg.xyz
 .. image:: https://readthedocs.org/projects/emg3d/badge/?version=latest
    :target: https://emg3d.readthedocs.io/en/latest
    :alt: Documentation Status
 .. image:: https://github.com/emsig/emg3d/workflows/pytest/badge.svg?branch=master
    :target: https://github.com/emsig/emg3d/actions
    :alt: GitHub Actions
-.. image:: https://coveralls.io/repos/github/emsig/emg3d/badge.svg?branch=master
-   :target: https://coveralls.io/github/emsig/emg3d?branch=master
-   :alt: Coveralls
-.. image:: https://app.codacy.com/project/badge/Grade/0412e617e8cd42fea05303fe490b09b5
-   :target: https://www.codacy.com/gh/emsig/emg3d/dashboard?utm_source=github.com&utm_medium=referral&utm_content=emsig/emg3d&utm_campaign=Badge_Grade
-   :alt: Codacy
-.. image:: https://img.shields.io/badge/benchmark-asv-blue.svg?style=flat
-   :target: https://emsig.github.io/emg3d-asv
-   :alt: Airspeed Velocity
-.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3229006.svg
-   :target: https://doi.org/10.5281/zenodo.3229006
-   :alt: Zenodo DOI
 
-.. sphinx-inclusion-marker
+====
 
-A multigrid solver for 3D electromagnetic diffusion with tri-axial electrical
-anisotropy. The matrix-free solver can be used as main solver or as
-preconditioner for one of the Krylov subspace methods implemented in
-`scipy.sparse.linalg`, and the governing equations are discretized on a
-staggered Yee grid. The code is written completely in Python using the
-NumPy/SciPy-stack, where the most time- and memory-consuming parts are sped up
-through jitted numba-functions.
+.. sphinx-inclusion-marker
 
 
-More information
-================
-For more information regarding installation, usage, contributing, roadmap, bug
-reports, and much more, see
+A multigrid solver for 3D electromagnetic diffusion in Python.
 
-- **Website**: https://emsig.github.io,
-- **Documentation**: https://emg3d.readthedocs.io,
-- **Source Code**: https://github.com/emsig/emg3d,
-- **Examples**: https://emsig.github.io/emg3d-gallery.
+- **Website:** https://emsig.github.io
+- **Documentation:** https://emg3d.readthedocs.io
+- **Source Code:** https://github.com/emsig/emg3d
+- **Bug reports:** https://github.com/emsig/emg3d/issues
+- **Contributing:** https://emg3d.readthedocs.io/en/latest/development
 
 
 Features
-========
-
-- Multigrid solver for 3D electromagnetic (EM) diffusion with regular grids
-  (where source and receiver can be electric or magnetic).
-- Compute the 3D EM field in the complex frequency domain or in the real
-  Laplace domain.
-- Includes also routines to compute the 3D EM field in the time domain.
-- Can be used together with the `SimPEG <https://simpeg.xyz>`_-framework.
-- Can be used as a standalone solver or as a pre-conditioner for various Krylov
-  subspace methods implemented in SciPy, e.g., BiCGSTAB
-  (`scipy.sparse.linalg.bicgstab`) or CGS (`scipy.sparse.linalg.cgs`).
-- Tri-axial electrical anisotropy.
-- Isotropic magnetic permeability.
-- Semicoarsening and line relaxation.
-- Grid-size can be anything.
-- As a multigrid method it scales with the number of unknowns *N* and has
-  therefore optimal complexity *O(N)*.
+--------
+
+- **Iterative, matrix-free multigrid solver**, scaling linearly (CPU & RAM)
+  with the number of unknowns, O(N).
+- Uses **regular, stretched grids**.
+- Handles **tri-axial electrical anisotropy**, isotropic electric permittivity,
+  and isotropic magnetic permeability.
+- Written **purely in Python** using the NumPy/SciPy-stack, where the most time-
+  and memory-consuming parts are sped up through jitted **Numba**-functions;
+  works **cross-platform** on Linux, Mac, and Windows.
+- Can solve in the complex-valued **frequency domain** or the real-valued
+  **Laplace domain**. Includes routines to compute the 3D EM field in the
+  **time domain**.
+- **Command-line interface (CLI)**, through which emg3d can be used as forward
+  modelling kernel in inversion routines.
+- Computes the **gradient of the misfit function** using the adjoint-state
+  method.
+- Can handle **entire surveys** with **many sources, receivers, and
+  frequencies**, computing the solution in **parallel**.
 
 
 Installation
 ============
 
-You can install emg3d either via ``conda`` (preferred):
-
-.. code-block:: console
-
-   conda install -c conda-forge emg3d
-
-or via ``pip``:
-
-.. code-block:: console
-
-   pip install emg3d
-
-Minimum requirements are Python version 3.7 or higher and the modules ``scipy``
-and ``numba``. Various other packages are recommended or required for some
-advanced functionalities (``xarray``, ``discretize``, ``matplotlib``, ``h5py``,
-``empymod``, ``scooby``). Consult the installation notes in the `manual
-<https://emg3d.readthedocs.io/en/stable/usage.html#installation>`_ for more
-information regarding installation, requirements, and soft dependencies.
-
-
-Citation
-========
-
-If you publish results for which you used `emg3d`, please give credit by citing
-`Werthmüller et al. (2019) <https://doi.org/10.21105/joss.01463>`_:
-
-    Werthmüller, D., W. A. Mulder, and E. C. Slob, 2019,
-    emg3d: A multigrid solver for 3D electromagnetic diffusion:
-    Journal of Open Source Software, 4(39), 1463;
-    DOI: `10.21105/joss.01463 <https://doi.org/10.21105/joss.01463>`_.
-
-
-All releases have a Zenodo-DOI, which can be found on `10.5281/zenodo.3229006
-<https://doi.org/10.5281/zenodo.3229006>`_.
-
-See `CREDITS` for the history of the code.
-
-
-License information
-===================
-
-Copyright 2018-2021 The emg3d Developers.
-
-Licensed under the Apache License, Version 2.0, see the ``LICENSE``-file.
+Installable with ``pip`` from PyPI and with ``conda`` through the
+``conda-forge`` channel. Minimum requirements are Python version 3.7 or higher
+and the modules ``scipy`` and ``numba``. Various other packages are recommended
+or required for some advanced functionalities (``xarray``, ``discretize``,
+``matplotlib``, ``h5py``, ``empymod``, ``scooby``). Consult the installation
+notes in the `manual
+<https://emg3d.readthedocs.io/en/stable/user_guide/installation.html>`_ for
+more information regarding installation, requirements, and soft dependencies.

docs/Makefile

@@ -1,6 +1,3 @@
-# Disable numba, so jitted functions are nicely documented.
-export NUMBA_DISABLE_JIT=1
-
 # Command line options.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build