Move to EMSiG

Various small things, mostly related to the automatic meshing.

• New parameter distance for get_origin_widths, as an alternative for
  domain and vector: distance defines the survey domain as distance
  from the center. This is then also available in construct_mesh and
  Simulation, including the CLI.
• Removed precision from skin_depth, wavelength,
  min_cell_width; all in meshes. It caused problems for high
  frequencies.
• All data is stored in the Survey, not partly in Survey and partly
  in Simulation.
• Deprecated collect_classes in io.
• Expanded the what-parameter in the Simulation-class to include
  properties related to the gradient.
• Moved from github.com/empymod to github.com/emsig.

Fix deploy; take 2

v0.15.2

Fix deploy; take 2

Bugfix deploy

Small bugfix release, as v0.15.0 never got deployed.

• Fix CI deploy script.
• Makefile for the most common dev-tasks.

discretize restructure

The package discretize went through a major restructuring with many name
changes and consequent deprecations (see below for a list of affected
mesh-properties for emg3d). This version updates emg3d to be compatible
with discretize>=0.6.0 in the long run. It also means that emg3d will, from
emg3d>=0.15.0 onwards, only work with discretize>=0.6.0.

Other notable changes:

• Bug fix re storing/loading synthetics
• Moved from Travis CI to GitHub Actions.

The relevant aliases and deprecations for emg3d are (consult the release
notes of discretize for all changes):

Aliases: Aliases (left) remain valid pointers to the new names (right).

• x0 => origin
• nC => n_cells
• vnC => shape_cells
• nN => n_nodes
• vnN => shape_nodes
• nE => n_edges
• nEx => n_edges_x
• nEy => n_edges_y
• nEz => n_edges_z
• vnE => n_edges_per_direction
• vnEx => shape_edges_x
• vnEy => shape_edges_y
• vnEz => shape_edges_z

Deprecations: Deprecated properties (left) raise a deprecation warning and
will be removed in the future. Currently, they still work and point to the new
names (right).

• hx => h[0]
• hy => h[1]
• hz => h[2]
• nCx => shape_cells[0]
• nCy => shape_cells[1]
• nCz => shape_cells[2]
• nNx => shape_nodes[0]
• nNy => shape_nodes[1]
• nNz => shape_nodes[2]
• vectorNx => nodes_x
• vectorNy => nodes_y
• vectorNz => nodes_z
• vectorCCx => cell_centers_x
• vectorCCy => cell_centers_y
• vectorCCz => cell_centers_z
• vol => cell_volumes

Bug fix discretize

• Bug fix for discretize>=0.6.0.

Bug fix

• Bug fix for Windows affecting good_mg_cell_nr (int32 issue).

Bug fix

• Fix for h5py>3.0.
• Improved docs re automatic gridding.

Automatic gridding

The simulation class comes new with an automatic gridding functionality, which should make it much easier to compute CSEM data. With that the entire optimization routine was improved too. See the API docs for more info of the relevant implementation.

• simulation:

  • Simulation: New gridding options 'single', 'frequency', 'source', and 'both'; new default is 'single'.
  • compute() takes a new argument, min_offset. If observed=True, it will add Gaussian random noise according to the standard deviation of the data; it will set receivers responses below the minimum offset to NaN.
  • There is no longer a reference model.
  • misfit and gradient can now handle observations with NaN's.

• survey: A Survey has new attributes standard_error, noise_floor, and relative_error.

• optimize: Completely changed misfit and data-weighting to more sensible functions.

• cli:

  • As a consequence of the changes the data_weight_opts got removed.
  • New sections [data] to select the wanted data and [gridding_opts] for options of the automatic gridding.
  • Section [simulation] has a new parameter min_offset (for creating observed data).
  • Output has a new parameter n_observations if misfit or gradient were called, which is the number of observations that were used to compute the misfit.

• meshes:

  • New functions construct_mesh, get_origin_widths, good_mg_cell_nr and other, smaller helper routines.
  • Deprecated the old meshing routines get_hx_h0, get_cell_numbers, get_stretched_h, get_domain, get_hx; they will be removed in the future.
  • Default of good_mg_cell_nr changed, and the documentation (and verbosity) with regards to «good» number of cells was improved.

• Bug fixes:

  • maps: Fixed the mapping of the gradients (Conductivity is the only mapping that was not affected by this bug).

• Removed deprecated features:

  • models.Model: Removed parameters res_{x;y;z}.
  • io.save: Removed deprecated parameter backend.
  • io.save: Removed default, file extension has to be provided.

CLI

• New Module cli for command-line interaction:

  The command-line interface can currently be used to forward model an entire Simulation, and also to compute the misfit of it with respect to some data and the gradient of the misfit function. See the section "CLI interface" in the documentation for more info.

Note that, while cli (v0.13.0) and optimize (v0.12.0) are implemented, they are still in development and are likely going to change throughout the next two minor releases or so.

• Other changes:

  • solver: Changes in verbosity for emg3d.solve:

    • New default verbosity is 1 (only warnings; before it was 2).
    • Verbosities {-1;0;1} remain unchanged.
    • Verbosities {2;3;4} => {3;4;5}.
    • New verbosity 2: Only shows a one-liner at the end (plus warnings).

  • survey and simulation: to_file and from_file have new a parameter name, to store and load with a particular name instead of the default survey/simulation (useful when storing, e.g., many surveys in one file).

  • survey: stores new also the reference-data; different data (observed, reference) is contained in a data-dict when storing.

  • simulation: takes new a verb parameter.

  • optimize:

    • Gradient now possible for arbitrarily rotated sources and receivers.
    • Falls back to synthetic instead of observed now if reference not found.

  • io: np.bool_ are converted back to bool when loading.

  • Re-arrange, improve, and update documentation.

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).