Simulation

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

Bases: object

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

A simulation can be used to compute responses for an entire survey, hence for an arbitrary amount of sources, receivers, and frequencies. The responses can be computed in parallel over sources and frequencies. It can also be used to compute the misfit with the data and to compute the gradient of the misfit function.

The computational grid(s) can either be provided, or automatic gridding can be used; see the description of the parameters gridding and gridding_opts for more details.

Warning

The automatic gridding does its best to generate meshes that are suitable for the provided model and survey. However, CSEM spans a wide range of acquisition layouts, and frequencies as well as conductivities or resistivities span many orders of magnitude. This makes it hard to have a function that fits all purposes. Check the meshes with your expert knowledge. Also, the automatic gridding is conservative in its estimate, in order to be on the save side (correct results over speed). This means, however, that often smaller grids could be used by providing the appropriate options in gridding_opts.

Note

The Simulation-class is currently only implemented for survey.fixed=False.

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 : emg3d.meshes.TensorMesh

The grid. See emg3d.meshes.TensorMesh.

model : emg3d.models.Model

The model. See emg3d.models.Model.

gridding : str, optional

Method how the computational grids are computed. Default is ‘single’. The different methods are:

• ‘same’: Same grid as for the input model.
• ‘single’: A single grid for all sources and frequencies.
• ‘frequency’: Frequency-dependent grids.
• ‘source’: Source-dependent grids.
• ‘both’: Frequency- and source-dependent grids.
• ‘input’: Same as ‘single’, but instead of automatically generate the mesh it has to be provided in gridding_opts.
• ‘dict’: Same as ‘both’, but instead of automatically generate the meshes they have to be provided as a dict[source][frequency] in gridding_opts.

See the parameter gridding_opts for more details.

gridding_opts : dict or TensorMesh, optional

Input format depends on gridding:

• ‘same’: Nothing, gridding_opts is not permitted.
• ‘single’, ‘frequency’, ‘source’, ‘both’: Described below.
• ‘input’: A emg3d.meshes.TensorMesh.
• ‘dict’: Dictionary of the format dict[source][frequency] containing a emg3d.meshes.TensorMesh for each source-frequency pair.

The dict in the case of ‘single’, ‘frequency’, ‘source’, ‘both’ is passed to emg3d.meshes.construct_mesh(); consult the corresponding documentation for more information. Parameters that are not provided are estimated from the model, grid, and survey using estimate_gridding_opts(), which documentation contains more information too.

There are two notably differences to the parameters described in emg3d.meshes.construct_mesh():

• vector: besides the normal possibility it can also be a string containing one or several of ‘x’, ‘y’, and ‘z’. In these cases the corresponding dimension of the input mesh is provided as vector. See estimate_gridding_opts().
• expand: in the format of [property_sea, property_air]; if provided, the input model is expanded up to the seasurface with sea water, and an air layer is added. The actual height of the seasurface can be defined with the key seasurface. See expand_grid_model().

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, efield, return_info, and log. If not provided the following defaults are used:

• sslsolver=True;
• semicoarsening=True;
• linerelaxation=True;
• verb=2;

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.

max_workers : int

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

verb : int; optional

Level of verbosity. Default is 0. These are propagated to the called function if not defined above in the possible options.

• -1: Error.
• 0: Warning.
• 1: Info.

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])	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[, name])	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.
print_grid_info([verb, return_info])	Print info for all generated grids.
print_solver_info([field, verb, return_info])	Print solver info.
to_dict([what, copy])	Store the necessary information of the Simulation in a dict.
to_file(fname[, what, name])	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, **kwargs)

Compute efields asynchronously for all sources and frequencies.

Parameters:

observed : bool

If True, it stores the current result also as observed model. This is usually done for pure forward modelling (not inversion). It will as such be stored within the survey. If the survey has either relative_error or noise_floor, random Gaussian noise with std will be added to the data.observed (not to data.synthetic). Also, data below the noise floor will be set to NaN.

min_offset : float

Default is 0.0. Data in data.observed where the offset < min_offset are set to NaN.

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, name='simulation', **kwargs)

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

name : str

Name under which the simulation is stored within the file.

kwargs : Keyword arguments, optional

Passed through to emg3d.io.load().

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.

print_grid_info(verb=1, return_info=False)

Print info for all generated grids.

print_solver_info(field='efield', verb=1, return_info=False)

Print solver info.

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', name='simulation', **kwargs)

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

name : str

Name under which the survey is stored within the file.

kwargs : Keyword arguments, optional

Passed through to emg3d.io.save().