Simulation

class emg3d.simulations.Simulation(name, survey, grid, model, max_workers=4, gridding='same', **kwargs)

Bases: object

Create a simulation for a given survey on a given model.

The computational grid(s) can be either the same as the provided model grid, or automatic gridding can be used.

Note

The Simulation-class has currently a few limitations:

• gridding must be ‘same’;
• survey.fixed: must be False;
• sources and receivers must be electric;
• sources strength is always normalized to 1 Am.
• Anything related to optimization is considered experimental/alpha, and might change in the future.

Parameters:

survey : emg3d.surveys.Survey

The survey layout, containing sources, receivers, frequencies, and optionally the measured data.

The survey-data will be modified in place. Provide survey.copy() if you want to avoid this.

grid : meshes.TensorMesh

The grid. See meshes.TensorMesh.

model : emg3d.models.Model

The model. See emg3d.models.Model.

max_workers : int

The maximum number of processes that can be used to execute the given calls. Default is 4.

gridding : str, TensorMesh, or dict

Method how the computational grids are computed. The default is currently ‘same’, the only supported string-method so far (automatic gridding will be implemented in the future).

• ‘same’: Same grid as for the input model.
• TensorMesh: The provided TensorMesh is used for all sources and frequencies.
• dict: The dict must have the form dict[source][frequency], containing a TensorMesh for each source-frequency pair.

solver_opts : dict, optional

Passed through to emg3d.solver.solve(). The dict can contain any parameter that is accepted by the emg3d.solver.solve() except for grid, model, sfield, and efield. If not provided the following defaults are used:

• sslsolver = True;
• semicoarsening = True;
• linerelaxation = True;
• verb = 0 (yet warnings are capture and shown).

Note that these defaults are different from the defaults in emg3d.solver.solve(). The defaults chosen here will be slower in many cases, but they are the most robust combination at which you can throw most things.

data_weight_opts : dict, optional

Applied in emg3d.optimize.data_weighting() (defaults in <brackets>):

• gamma_d : float <0.5>; Offset weighting exponent.
• beta_d : float <1.0>; Data weighting exponent.
• beta_f : float <0.25>; Frequency weighting exponent.
• noise_floor : float <1e-15>; Data with amplitudes below the noise floor are switched off.
• min_off: float <1000>; Receiver closer to the source than min_offest are switched off.
• reference: str <’reference’>; Name of the data to use for normalization. By default the data from the reference model; if not found, the observed data are used.

Attributes Summary

data	Shortcut to survey.data.
gradient	Return the gradient of the misfit function.
misfit	Return the misfit function.

Methods Summary

clean([what])	Clean part of the data base.
compute([observed, reference])	Compute efields asynchronously for all sources and frequencies.
copy([what])	Return a copy of the Simulation.
from_dict(inp)	Convert dictionary into Simulation instance.
from_file(fname[, verb])	Load Simulation from a file.
get_efield(source, frequency, **kwargs)	Return electric field for given source and frequency.
get_efield_info(source, frequency)	Return the solver information of the corresponding computation.
get_grid(source, frequency)	Return computational grid of the given source and frequency.
get_hfield(source, frequency, **kwargs)	Return magnetic field for given source and frequency.
get_model(source, frequency)	Return model on the grid of the given source and frequency.
get_sfield(source, frequency)	Return source field for given source and frequency.
to_dict([what, copy])	Store the necessary information of the Simulation in a dict.
to_file(fname[, what, compression, …])	Store Simulation to a file.

Attributes Documentation

data

Shortcut to survey.data.

gradient

Return the gradient of the misfit function.

See emg3d.optimize.gradient().

misfit

Return the misfit function.

See emg3d.optimize.misfit().

Methods Documentation

clean(what='computed')

Clean part of the data base.

Parameters:

what : str

What to clean. Currently implemented:

• ‘computed’ (default): Removes all computed properties: electric and magnetic fields and responses at receiver locations.
• ‘keepresults’: Removes everything except for the responses at receiver locations.
• ‘all’: Removes everything (leaves it plain as initiated).

compute(observed=False, reference=False)

Compute efields asynchronously for all sources and frequencies.

Parameters:

observed : bool

By default, the data at receiver locations is stored in the Survey as synthetic. If observed=True, however, it is stored in observed.

reference : bool

If True, it stores the current result also as reference model, which is used by the data weighting functions. This is usually done for the initial model in an inversion.

copy(what='computed')

Return a copy of the Simulation.

See to_file for more information regarding what.

classmethod from_dict(inp)

Convert dictionary into Simulation instance.

Parameters:

inp : dict

Dictionary as obtained from Simulation.to_dict().

Returns:

obj : Simulation instance

classmethod from_file(fname, verb=1)

Load Simulation from a file.

Parameters:

fname : str

File name including extension. Used backend depends on the file extensions:

• ‘.npz’: numpy-binary
• ‘.h5’: h5py-binary (needs h5py)
• ‘.json’: json

verb : int

Silent if 0, verbose if 1.

Returns:

simulation : Simulation

The simulation that was stored in the file.

get_efield(source, frequency, **kwargs)

Return electric field for given source and frequency.

get_efield_info(source, frequency)

Return the solver information of the corresponding computation.

get_grid(source, frequency)

Return computational grid of the given source and frequency.

get_hfield(source, frequency, **kwargs)

Return magnetic field for given source and frequency.

get_model(source, frequency)

Return model on the grid of the given source and frequency.

get_sfield(source, frequency)

Return source field for given source and frequency.

to_dict(what='computed', copy=False)

Store the necessary information of the Simulation in a dict.

See to_file for more information regarding what.

to_file(fname, what='computed', compression='gzip', json_indent=2, verb=1)

Store Simulation to a file.

Parameters:

fname : str

File name inclusive ending, which defines the used data format. Implemented are currently:

• .h5 (default): Uses h5py to store inputs to a hierarchical, compressed binary hdf5 file. Recommended file format, but requires the module h5py. Default format if ending is not provided or not recognized.
• .npz: Uses numpy to store inputs to a flat, compressed binary file. Default format if h5py is not installed.
• .json: Uses json to store inputs to a hierarchical, plain text file.

what : str

What to store. Currently implemented:

• ‘computed’ (default): Stores all computed properties: electric fields and responses at receiver locations.
• ‘results’: Stores only the response at receiver locations.
• ‘all’: Stores everything.
• ‘plain’: Only stores the plain Simulation (as initiated).

compression : int or str, optional

Passed through to h5py, default is ‘gzip’.

json_indent : int or None

Passed through to json, default is 2.

verb : int

Silent if 0, verbose if 1.