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

`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 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

copy()[source]#: Return a copy of the Model.

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', an ellipse-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 between p0 and p1. If p1 is not provided, the model at p0 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 function emg3d.maps.ellipse_indices to obtain the ellipse. This method requires the ellipse-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 to p0.

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 keys property_x, property_y, property_z, mu_r, epsilon_r, grid, and mapping; grid itself is also a dict which needs the keys hx, hy, hz, and origin.

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 are method='volume', log=True, and extrapolate=True.

Returns:

objModel: A new emg3d.models.Model instance on grid.

to_dict(copy=False)[source]#

Store the necessary information in a dict for serialization.

Parameters:

copybool, default: False: If True, returns a deep copy of the dict.

Returns:

outdict: Dictionary containing all information to re-create the Model.