Stable API

Here it is, three months of hard labour lead to v1.0.0!

There are many changes, and they are listed below for each module.

Your existing code will break, and I apologize for it. Please do not hesitate
to get in touch if you have troubles updating your code.

API: With version 1.0 the API becomes stable and you can expect that your
code will work fine for the duration of emg3d v1.x.

• Removed all deprecated features.
• Reduced top namespace to principal functions; get_receiver is not in the
  top namespace any longer. It is advised to use directly the field method:
  field.get_receiver.
• Moved emsig.github.io to emsig.xyz and emsig.readthedocs.io to
  emg3d.emsig.xyz.
• Changed principal repo branch from master to main.

Detailed changes by module

CLI

• Because frequencies are now dicts as well in a Survey they have to be named
  by their key instead of their value when selecting data in the parameter
  file.
• Entire configuration is now added to the log file.

Core

• restrict_weights: New signature.

Electrodes

• New module containing all sources and receivers. Currently implemented are
  TxElectricDipole, TxMagneticDipole, TxElectricWire,
  RxElectricPoint, and RxMagneticPoint.
• New class TxElectricWire for an arbitrary electric wire.
• Receivers can be defined in absolute coordinates, or in coordinates relative
  to source position if they move with the source. Latter makes only sense
  within a Survey/Simulation.
• dip is new called elevation to make it clear that it is the angle
  positive upwards (anticlockwise from the horizontal plane).
• Bugfix of the loop area for a magnetic dipole (the area was previously wrong
  except for dipoles of length of 1).
• Zero source strength does no longer mean "normalized", it means zero
  strength (hence no source).
• Besides the sources and receivers it contains utilities how to move
  electrodes in the coordinate system (e.g., rotation).

Fields

• fields.Field:

  • Is not a subclassed ndarray any longer; with all its advantages and
    disadvantages. E.g., operations on Field are not possible any longer
    and have to be carried out on Field.field. However, it should be easier
    to maintain and expand in the future.
  • New signature.
  • Knows new its grid. As a consequence, all functions that required
    previously the grid and the field require new only the field;
    e.g., emg3d.fields.get_receiver.
  • Has no property ensure_pec any longer, it is ensured directly in
    solver.prolongation.
  • Has new the methods interpolate_to_grid and get_receiver.

• Renamed parameters in all functions:

  • src to source;
  • freq to frequency;
  • rec to receiver.

• Removed functions and classes:

  • SourceField; it is just a regular Field now;
  • get_receiver (the name still exists, but it is now what was before
    fields.get_receiver_response).

• Renamed functions and classes (both do not take a grid any longer):

  • get_h_field to get_magnetic_field;
  • fields.get_receiver_response to fields.get_receiver.

I/O

• Model, Field, Survey, and Simulation instances saved with an
  older version of emg3d will not be able to de-serialize with version 1.0. You
  have to update those files, see this gist:
  https://gist.github.com/prisae/8345c3798e35f1c73efef617ac495538

Maps

• Changed function and class names:

  • _Map to BaseMap;
  • grid2grid to interpolate (new signature);
  • edges2cellaverages to interp_edges_to_vol_averages (new signature);
  • volume_average to interp_volume_average (new signature);
  • interp3d to interp_spline_3d (new signature).

• maps.interpolate:

  • Can now be used to interpolate values living on a grid to another grid or
    to points defined either by a tuple or by an ndarray.
  • The implemented interpolation methods are 'nearest' (new), 'linear',
    'cubic', and 'volume'. Volume averaging ('volume') only works for
    grid-to-grid interpolations, not for grid-to-points interpolations.
  • Does not accept entire fields any longer. Entire fields can be mapped with
    their own field.interpolate_to_grid method.

• Maps cannot be (de-)serialized any longer ({to;from_dict}); simply store
  its name, which can be provided to models.Model.

• Function rotation should be used for anything involving angles to use
  the defined coordinate system consistently.

Meshes

• Changed function and class names:

  • _TensorMesh to BaseMesh;
  • min_cell_width to cell_width.
  • get_origin_widths to origin_and_widths (has new finer loops to fine
    grid sizes than before).

• meshes.BaseMesh:

  • Reduced to the attributes origin, h, shape_{cells;nodes},
    n_{cells;edges;faces}, n_{edges;faces}_{x;y;z},
    {nodes;cell_centers}_{x;y;z}, shape_{edges;faces}_{x;y;z}, and
    cell_volumes. These are the only required attributes for emg3d.

• meshes.construct_mesh: domain, vector, distance,
  stretching, min_width_limits, and min_width_pps can now also
  be provided as a dict containing the three keys '{x;y;z}'.

• meshes.skin_depth takes new mu_r instead of mu.

• good_mg_cell_nr: max_prime is new max_lowest, as it could also
  be, e.g., 9, which is not a prime.

Models

• models.Model:

  • Knows new its grid. As a consequence, all the functions that used to
    require the grid and the model require new only the model;
    e.g., emg3d.solver.solve or emg3d.fields.get_magnetic_field.

  • If property_y or property_z are not set they return now None,
    not property_x.

  • If a float is provided for a property it is new expanded to the shape of
    the model, and not kept as a float.

  • Has to be initiated with all desired properties; it cannot be changed
    afterwards. E.g., if it was initiated without electric permittivity, it
    cannot be added afterwards. However, it can be initiated with dummy values
    and adjusted later.

  • Renamed interpolate2grid to interpolate_to_grid.

• models.VolumeModel: Does not take a grid any longer.

Simulations

• Simulation:

  • Works new for electric and magnetic dipole sources as well as electric wire
    sources; electric and magnetic point receivers.
  • Works now as well for surveys that contain receivers which are positioned
    relatively to the source.
  • New signature: no grid any longer, name is new an optional keyword
    parameter, new optional keyword parameter info.
  • Method get_sfield is removed.

• expand_grid_model and estimate_gridding_opts have new signatures and
  do not take a grid any longer.

Solver

• solver.solve:

  • New signature: no grid any longer; efield and cycle are moved
    to keyword arguments.

  • 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 keyword 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 (for consistency reasons throughout emg3d).
    The new levels are [old levels 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 updates now dynamically, just as level 2.

• solve_source(): New function, a shortcut for solve(). It takes a
  source and a frequency instead of a sfield, gets the sfield
  internally, and forwards everything to solver.solve.

• multigrid, krylov, smoothing, restriction, prolongation,
  residual, RegularGridProlongator: New signature, mainly not taking a
  grid any longer.

Surveys

• Survey:

  • frequencies is new a dict just like sources and receivers.
  • sources and receivers must be tuples or dicts; lists are no longer
    permitted. For this, the module surveys has new convenience functions
    txrx_coordinates_to_dict and txrx_lists_to_dict.
  • Has no attribute observed any longer; access it just like any other
    data through Survey.data.observed.
  • rec_coords and src_coords attributes changed to the methods
    receiver_coordinates and source_coordinates.
    receiver_coordinates takes an optional source key.
    For relatively located receivers, it returns by default all positions of
    this receiver for all source position. If a source-key is provided it only
    returns the receiver position for this source. This does not affect
    absolutely positioned receivers.
  • Has no attribute rec_types any longer.
  • name is new optional.
  • New optional keywords date and info.
  • noise_floor and relative_error are new stored as data array if they
    are not floats.
  • The keyword fixed has been dropped. To simulate fixed surveys define
    the receivers with a relative offs...

Magnetics in Simulation

• Simulation:

  • Sources and receivers can now be magnetic, also for the adjoint-state
    gradient (unit loops, not yet arbitrarily loops).

• fields.get_source_field:

  • The msrc argument introduced in v0.16.0 is renamed to electric, and
    has the opposite meaning. If True, the source is electric, if False, the
    source is magnetic. This was made to streamline the meaning with the
    meaning given in surveys.Dipole. The old parameter msrc is
    deprecated and will be removed. Warning, if msrc was provided as
    positional argument instead of as keyword argument it will now be taken as
    electric, with the opposite meaning (backwards incompatible).
  • The magnetic source was corrected and has the opposite sign now (factor -1;
    backwards incompatible).

• Bug fixes:

  • Simulation: Stop overwriting synthetic data if provided in the survey to a
    simulation.
  • CLI: Removed configuration info from output data; caused problems when
    storing to h5. This has to be resolved with properly addressing the io
    stuff. Currently only stores the data selection to output data.

Verbosity & Logging

• Solve has a new keyword log, which enables to log the solver messages
  in the returned info dictionary instead of printing them to screen. This is
  utilized in the CLI and in the Simulation class to log the solver info.

• Survey has a new attribute select, which returns a reduced survey
  containing the selected sources, receivers, and frequencies.

• CLI:

  • Configuration info is added to output data.
  • Checks now first if all required files and directories exist, and exits
    gracefully otherwise informing the user. (The default thrown Python errors
    would be good enough; but user of the CLI interface might not be familiar
    with Python, so it is better to throw a very simple, clear message.)
  • Log is more verbose with regards to solver (rel. error, time, nr of it.).

• Dipole throws new an error instead of a warning if it received an unknown
  keyword.

• Various small things with regard to how things are logged or shown on screen.

• Changed all DeprecationWarnings to FutureWarnings, meaning they will
  be removed in the next release.

• Bug fix with regards to data selection in the CLI; moved to Survey (see
  above).

Arbitrarily shaped sources

• fields.get_source_field:

  • Arbitrarily shaped sources (and therefore also loops) can now be created by
    providing a src that consists of x-, y-, and z-coordinates of all
    endpoints of the individual segments.

  • Simple "magnetic dipole" sources can now be created by providing a point
    dipole ([x, y, z, azm, dip]) and set msrc=True. This will create a
    square loop of lengthxlength m perpendicular to the defined point
    dipole, hence simulating a magnetic source. Default length is 1 meter.

  • Point dipoles and finite length dipoles were before treated differently.
    Point dipoles are new converted into finite length dipoles of provided
    length (default is 1 meter), and treated as finite length dipoles. This is
    backwards incompatible and means that the source field for point dipoles
    might not be exactly the same as before. However, in any properly set-up
    simulation this should have no influence on the result.

  • Bugfix: Fix floating point issue when the smaller coordinate of a finite
    length dipole source was very close to a node, but not exactly. This is
    done by rounding the grid locations and source position, and the precision
    can be controlled via decimals; default is micrometer.

• fields: Values outside the grid in get_receiver and
  get_receiver_response are new set to NaN's instead of zeroes.
  Additionally, the first and last values in each direction of the fields are
  ignored, to avoid effects form the boundary condition (receivers should not
  be placed that close to the boundary anyway).

• simulations:

  • Within the automatic gridding the properties are estimated much more
    conservative now, if not provided: before the log10-average of the last
    slice in a given direction was used; now it uses the maximum resistivity.
    This is usually the air value for x/y and positive z. This is very
    conservative, but avoids that users use too small computational domains in
    the case of land and shallow marine surveys. The downside is that it
    heavily over-estimates the required domain in the deep marine case.
    However, slower but safe is better in this case.
  • New method print_grids, which prints the info of all created grids.
    This is also used for logging in the CLI interface.

• maps: interp3d takes a new keyword cval, which is passed to
  map_coordinates.

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