Simulation¶
-
class
emg3d.simulations.
Simulation
(name, survey, grid, model, max_workers=4, gridding='same', **kwargs)[source]¶ 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;
- 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 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.- 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.
- verb : int; optional
Level of verbosity. Default is 0.
- -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, 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[, 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, reference=False)[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.
- 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')[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
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
io.save()
.