Model#
- class emg3d.models.Model(grid, property_x=1.0, property_y=None, property_z=None, mu_r=None, epsilon_r=None, mapping='Resistivity')[source]#
Bases:
object
A model containing the electromagnetic properties of the Earth.
A model provides the required model parameters to the solver. The x-, y-, and z-directed electrical properties are by default resistivities. However, they can be defined as resistivities, \(\rho\ (\Omega\,\mathrm{m})\), or conductivities, \(\sigma\ (\mathrm{S/m})\), either on a linear or on a logarithmic scale (log or ln), by choosing the appropriate
mapping
. Relative magnetic permeability \(\mu_\mathrm{r}\) is by default set to one and electric permittivity \(\varepsilon_\mathrm{r}\) is by default set to zero, but they can also be provided (isotropically). Keep in mind that the multigrid method as implemented in emg3d works for the diffusive approximation. When the displacement part in Maxwell’s equations becomes too dominant it will start to fail (high frequencies or very high electric permittivity).- Parameters:
- gridTensorMesh
The grid; a
emg3d.meshes.TensorMesh
instance.- property_{x;y;z}{None, array_like}, default: 1 (x), None (y, z)
Electrical material property in x-, y-, and z-directions. The properties are stored as Fortran-ordered arrays with the shape given by
grid.shape
. The provided value must be broadcastable to that shape.By default, property refers to electrical resistivity. However, this can be changed with an appropriate
mapping
(the internals of emg3d work, irrelevant of the map, with electrical conductivities).The properties have to be of finite value, bigger than zero (on linear scale). The four supported anisotropy cases are:
x;y=None;z=None
: isotropic (y=z=x
);x;y=None;z
: vertical transverse isotropy VTI (y=x
);x;y;z=None
: horizontal transverse isotropy HTI (z=x
);x;y;z
: triaxial anisotropy.
If a property is not initiated it cannot be set later on (e.g., if a VTI model is created, it is not possible to set
property_y
later on, instead, a new model has to be initiated).- mu_r, epsilon_r{None, array_like}, default: None
Relative magnetic permeability (-) and relative electric permittivity (-), respectively, both isotropic. The properties are stored as Fortran-ordered arrays with the shape given by
grid.shape
. The provided value must be broadcastable to that shape.The properties have to be of finite value, bigger than zero.
The relative magnetic permeability is assumed to be 1 if not provided.
The relative electric permittivity is assumed to be 0 if not provided, which ignores the displacement part completely (diffusive approximation)
- mappingstr, default: ‘Resistivity’
Defines what type the electrical input
property_{x;y;z}
-values correspond to. The implemented types are:'Resistivity'
; ρ (Ω m);'Conductivity'
; σ (S/m);'LgResistivity'
; log_10(ρ);'LgConductivity'
; log_10(σ);'LnResistivity'
; log_e(ρ);'LnConductivity'
; log_e(σ).
Attributes Summary
Relative electric permittivity.
Relative magnetic permeability.
Electrical property in x-direction.
Electrical property in y-direction.
Electrical property in z-direction.
Methods Summary
copy
()Return a copy of the Model.
extract_1d
(method, p0[, p1, ellipse, merge, ...])Return a layered (1D) model.
from_dict
(inp)Convert dictionary into
emg3d.models.Model
instance.interpolate_to_grid
(grid, **interpolate_opts)Interpolate the model to a new grid.
to_dict
([copy])Store the necessary information in a dict for serialization.
Attributes Documentation
- epsilon_r#
Relative electric permittivity.
- mu_r#
Relative magnetic permeability.
- property_x#
Electrical property in x-direction.
- property_y#
Electrical property in y-direction.
- property_z#
Electrical property in z-direction.
Methods Documentation
- extract_1d(method, p0, p1=None, ellipse=None, merge=False, return_imat=False)[source]#
Return a layered (1D) model.
The returned model has shape (1, 1, nz), where nz is the original number of cells in vertical direction (except if
merge=True
). How this 1D model is obtained depends on the input parameters.Note
If
method
is either'cylinder'
or'prism'
, anellipse
-dict has to be provided with at least the key-value pair for'radius'
. E.g.,ellipse={'radius': 1000}
.- Parameters:
- methodstr
Method how to obtain the layered model. Implemented are:
'midpoint'
: Returns the model at the midpoint betweenp0
andp1
. Ifp1
is not provided, the model atp0
is returned. The x- and y-width of the returned model corresponds to the selected cell.'cylinder'
: Volume-averages the values of each layer within a right elliptic cylinder, using the functionemg3d.maps.ellipse_indices
to obtain the ellipse. This method requires theellipse
-parameter. The x- and y-width of the returned model corresponds to the x- and y-width of the ellipse.'prism'
: Same as'cylinder'
, but an enveloping right rectangular prism is fit around the cylinder.
- p0, p1array_like
(x, y)-coordinates of two points. If
p1
is not provided, it is set top0
.- ellipsedict, default: None
Options-dict passed through to
emg3d.maps.ellipse_indices
. This is only used in the methods'cylinder'
and'prism'
, for which it is a required parameter.- mergebool, default: False
If True, adjacent layers of identical properties are combined. That implies that the returned model might have less (but larger) cells in z-direction than the original model.
- return_imatbool, default: False
If True, the interpolation matrix is returned in addition to the model. This matrix can be used, for instance, to inspect the chosen selection.
- Returns:
- layeredModel
The layered Model; a
emg3d.models.Model
instance.- imatndarray, returned if return_imat=True
Interpolation matrix of shape (nx, ny) of the original model.
- classmethod from_dict(inp)[source]#
Convert dictionary into
emg3d.models.Model
instance.- Parameters:
- inpdict
Dictionary as obtained from
emg3d.models.Model.to_dict
. The dictionary needs the keysproperty_x
,property_y
,property_z
,mu_r
,epsilon_r
,grid
, andmapping
;grid
itself is also a dict which needs the keyshx
,hy
,hz
, andorigin
.
- Returns:
- modelModel
A
emg3d.models.Model
instance.
- interpolate_to_grid(grid, **interpolate_opts)[source]#
Interpolate the model to a new grid.
If the provided grid is identical to the grid of the model, it returns the actual model (not a copy).
- Parameters:
- gridTensorMesh
Grid of the new model; a
emg3d.meshes.TensorMesh
instance.- interpolate_optsdict
Passed through to
emg3d.maps.interpolate
. Defaults aremethod='volume'
,log=True
, andextrapolate=True
.
- Returns:
- objModel
A new
emg3d.models.Model
instance ongrid
.