Simulation¶
-
class
emg3d.simulations.
Simulation
(name, survey, grid, model, max_workers=4, gridding='single', **kwargs)[source]¶ 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
andgridding_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 has currently a few limitations:
- survey.fixed: must be False;
- sources and receivers must be electric;
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]
ingridding_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 aemg3d.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 usingestimate_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. Seeestimate_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 keyseasurface
. Seeexpand_grid_model()
.
- ‘same’: Nothing,
- solver_opts : dict, optional
Passed through to
emg3d.solver.solve()
. The dict can contain any parameter that is accepted by theemg3d.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.- 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 1.
- -1: Error.
- 0: Warning.
- 1: Info.
- 2: Debug.
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. 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.
-
misfit
¶ Return the misfit function.
Methods Documentation
-
clean
(what='computed')[source]¶ 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)[source]¶ 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')[source]¶ Return a copy of the Simulation.
See to_file for more information regarding what.
-
classmethod
from_dict
(inp)[source]¶ 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)[source]¶ 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)[source]¶ Return electric field for given source and frequency.
-
get_efield_info
(source, frequency)[source]¶ Return the solver information of the corresponding computation.
-
get_hfield
(source, frequency, **kwargs)[source]¶ Return magnetic field for given source and frequency.
-
to_dict
(what='computed', copy=False)[source]¶ 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)[source]¶ 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()
.