Survey & Simulation

This is a big release with many new features, and unfortunately not completely
backwards compatible. The main new features are the new Survey and
Simulation classes, as well as some initial work for optimization
(misfit, gradient). Also, a Model can now be a resistivity model, a
conductivity model, or the logarithm (natural or base 10) therefore. Receivers
can now be arbitrarily rotated, just as the sources. In addition to the
existing soft-dependencies empymod, discretize, and h5py there are
the new soft-dependencies xarray and tqm; discretize is now much tighter
integrated. For the new survey and simulation classes xarray is a required
dependency. However, the only hard dependency remain scipy and numba, if
you use emg3d purely as a solver. Data reading and writing has new a
JSON-backend, in addition to the existing HDF5 and NumPy-backends.

In more detail:

• Modules:

  • surveys (new; requires xarray):

    • Class surveys.Survey, which combines sources, receivers, and data.
    • Class surveys.Dipole, which defines electric or magnetic point dipoles
      and finite length dipoles.

  • simulations (new; requires xarray; soft-dependency tqdm):

    • Class simulations.Simulation, which combines a survey with a model. A
      simulation computes the e-field (and h-field) asynchronously using
      concurrent.futures. This class will include automatic, source- and
      frequency-dependent gridding in the future. If tqdm is installed it
      displays a progress bar for the asynchronous computation. Note that the
      simulation class has still some limitations, consult the class
      documentation.

  • models:

    • Model instances take new the parameters property_{x;y;z} instead of
      res_{x;y;z}. The properties can be either resistivity, conductivity, or
      log_{e;10} thereof. What is actually provided has to be defined with the
      parameter mapping. By default, it remains resistivity, as it was until
      now. The keywords res_{x;y;z} are deprecated, but still accepted at
      the moment. The attributes model.res_{x;y;z} are still available too,
      but equally deprecated. However, it is no longer possible to
      assign values to these attributes, which is a backwards
      incompatible change.
    • A model knows now how to interpolate itself from its grid to another grid
      (interpolate2grid).

  • maps:

    • New mappings for models.Model instances: The mappings take care of
      how to transform the investigation variable to conductivity and back, and
      how it affects its derivative.
    • New interpolation routine edges2cellaverages.

  • fields:

    • Function get_receiver_response (new), which returns the response
      for arbitrarily rotated receivers.

    • Improvements to Field and SourceField:

      • _sval and _smu0 not stored any longer, derived from _freq.
      • SourceField is now using the copy() and from_dict() from its
        parents class Field.

  • io:

    • File-format json (new), writes to a hierarchical, plain json file.
    • Deprecated the use of backend, it uses the file extension of
      fname instead.
    • This means .npz (instead of numpy), .h5 (instead of h5py), and
      new .json.
    • New parameter collect_classes, which can be used to switch-on
      collection of the main classes in root-level dictionaries. By default,
      they are no longer collected (changed).

  • meshes:

    • meshes.TensorMesh new inherits from discretize if installed.
    • Added __eq__ to models.TensorMesh to compare meshes.

  • optimize (new)

    • Functionalities related to inversion (data misfit, gradient, data
      weighting, and depth weighting). This module is in an early stage, and
      the API will likely change in the future. Current functions are misfit,
      gradient (using the adjoint-state method), and data_weighting. These
      functionalities are best accessed through the Simulation class.

• Dependencies:

  • empymod is now a soft dependency (no longer a hard dependency), only
    required for utils.Fourier (time-domain modelling).
  • Existing soft dependency discretize is now baked straight into meshes.
  • New soft dependency xarray for the Survey class (and therefore also for
    the Simulation class and the optimize module).
  • New soft dependency tqdm for nice progress bars in asynchronous
    computation.

• Deprecations and removals:

  • Removed deprecated functions data_write and data_read.
  • Removed all deprecated functions from utils.

• Miscellaneous:

  • Re-organise API-docs.
  • Much bookkeeping (improve error raising and checking; chaining errors,
    numpy types, etc).