Simulation¶
-
class
emg3d.simulations.
Simulation
(survey, 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 are 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.Note
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 both frequencies and 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, trying 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
or directly providing your own computational grids.Note
The package
xarray
has to be installed in order to useSimulation
:pip install xarray
orconda install -c conda-forge xarray
.- Parameters
- surveySurvey
The survey; a
emg3d.surveys.Survey
instance. The survey contains sources, receivers, frequencies, and optionally data.The survey-data will be modified in place. Provide
survey.copy()
if you want to avoid this.- modelModel
The model; a
emg3d.models.Model
instance.- max_workersint, default: 4
The maximum number of processes that can be used to execute the given calls.
- griddingstr, default: ‘single’
Method to create the computational grids.
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 the grid has to be provided ingridding_opts
instead of being automatically created.'dict'
: Same as'both'
, but the grids have to be provided ingridding_opts
in the form ofdict[source][frequency]
instead of being automatically created.
See the parameter
gridding_opts
for more details.- gridding_opts{dict, TensorMesh}, default: {}
Input format depends on
gridding
:'same'
: Nothing,gridding_opts
is not permitted.'single'
,'frequency'
,'source'
,'both'
: Described below.'input'
: Aemg3d.meshes.TensorMesh
.'dict'
: Dictionary of the formatdict[source][frequency]
containing aemg3d.meshes.TensorMesh
for each source-frequency pair.
The dict in the case of
'single'
,'frequency'
,'source'
,'both
’ is passed toemg3d.meshes.construct_mesh
; consult the corresponding documentation for more information. Parameters that are not provided are estimated from the provided model, grid, and survey usingemg3d.simulations.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. Seeemg3d.simulations.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 keyseasurface
. Seeemg3d.simulations.expand_grid_model
.
- solver_optsdict, default: {‘verb’: 2’}
Passed through to
emg3d.solver.solve
. The dict can contain any parameter that is accepted by theemg3d.solver.solve
except formodel
,sfield
,efield
,return_info
, andlog
. Default verbosity isverb=2
.- verbint, default: 0
Level of verbosity. Possible options:
-1: Errors.
0: Warnings.
1: Info.
- namestr, default: None
Name of the simulation.
- infostr, default: None
Simulation info or any other info (e.g., what was the purpose of this simulation).
Attributes Summary
Shortcut to survey.data.
Return the gradient of the misfit function.
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 dict into
emg3d.simulations.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.
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.
-
misfit
¶ Return the misfit function.
Methods Documentation
-
clean
(what='computed')[source]¶ Clean part of the data base.
- Parameters
- whatstr, default: ‘computed’
What to clean. Possibilities:
'computed'
: 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
- observedbool, default: False
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
ornoise_floor
, random Gaussian noise of standard deviation will be added to thedata.observed
(not todata.synthetic
). Also, data below the noise floor will be set to NaN.- min_offsetfloat, default: 0.0
Data points 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 regardingwhat
.
-
classmethod
from_dict
(inp)[source]¶ Convert dict into
emg3d.simulations.Simulation
instance.- Parameters
- inpdict
Dictionary as obtained from
emg3d.simulations.Simulation.to_dict
.
- Returns
- simulationSimulation
A
emg3d.simulations.Simulation
instance.
-
classmethod
from_file
(fname, name='simulation', **kwargs)[source]¶ Load Simulation from a file.
- Parameters
- fnamestr
Absolute or relative file name including extension.
- namestr, default: ‘simulation’
Name under which the simulation is stored within the file.
- kwargsKeyword arguments, optional
Passed through to
io.load
.
- Returns
- simulationSimulation
A
emg3d.simulations.Simulation
instance.- infostr, returned if verb<0
Info-string.
-
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
- fnamestr
Absolute or relative file name including ending, which defines the used data format. See
emg3d.io.save
for the options.- whatstr, default: ‘computed’
What to store. Possibilities:
'computed'
: 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).
- namestr, default: ‘simulation’
Name with which the simulation is stored in the file.
- kwargsKeyword arguments, optional
Passed through to
emg3d.io.save
.