construct_mesh

emg3d.meshes.construct_mesh(frequency, properties, center, domain=None, vector=None, seasurface=None, **kwargs)[source]

Return a TensorMesh for given parameters.

The constructed mesh is frequency- and conductivity-dependent, where properties are turned into conductivities through the provided mapping, which is 'Resistivity' by default. Some details are explained in other functions:

  • The minimum cell width \(\Delta_\text{min}\) is a function of frequency, properties[0], min_width_pps, and min_width_limits, see Equation (34).
  • The skin depth \(\delta\) is a function of frequency and properties, see Equation (32).
  • The wavelength \(\lambda\) is a function of frequency and properties, see Equation (33).

The relation of the survey domain, computational domain, and buffer zone is shown in Figure 12 for a x-z-section; the y-direction behaves the same as the x-direction (the figures are only visible in the web version on https://emg3d.rtfd.io).

Sketch for automatic gridding.

Figure 12: Relation between survey domain (Ds, domain), computational domain (Dc), and buffer zone. The survey domain should contain all sources and receivers as well as any important feature that should be represented in the data. The buffer zone is calculated as a function of wavelength with the provided property in the given direction.

By default, the buffer zone around the survey domain is one wavelength. This means that the signal has to travel two wavelengths to get from the end of the survey domain to the end of the computational domain and back. This approach is quite conservative and on the safe side. You can reduce the buffer thickness if you know what you are doing. There are three parameters which influence the thickness of the buffer for a given frequency: properties, which is used to calculate the skin depth and the wavelength, lambda_factor (default is 1) which sets how many times the wavelength is the thickness of the buffer (relative factor), and max_buffer, which is an absolute maximum for the buffer thickness. A graphical illustration is given in Figure 13.

Sketch for the buffer zone.

Figure 13: The thickness of the buffer zone (B) for (I) lambda_from_center=False (default) and for (II) lambda_from_center=True. The lambda_factor (\(\lambda_{fact}\)) is a simple scaling factor for the wavelength \(\lambda\). The max_buffer is an absolute limitation.

Parameters:
frequency : float

Frequency (Hz) to calculate skin depth; both the minimum cell width and the extent of the buffer zone, and therefore of the computational domain, are a function of skin depth.

properties : float or list

Properties to calculate the skin depths. The properties can be either resistivities, conductivities, or the logarithm (natural or base 10) thereof. By default it assumes resistivities, but it can be changed with the parameter mapping.

Four formats are recognized:

  • 1: Same property for everything;
  • 2: [min_width, buffer (+/-)] for all directions;
  • 4: [min_width, xy-buffer (+/-), z-, z+];
  • 7: [min_width, x-, x+, y-, y+, z-, z+].

The property min_width is usually the property at the center, hence at the source location. The other properties are used to define the extent of the buffer zone around the survey domain in the respective directions.

center : tuple

Tuple (or list, ndarray) of three floats for (x, y, z). The mesh is centered around this point, which means that here is the smallest cell. Usually this is the source location.

domain : tuple of lists, list, or None, optional

Contains the survey-domain limits. This domain should include all source and receiver positions as well as any important feature of the model. Format: ([xmin, xmax], [ymin, ymax], [zmin, zmax]).

It can be None, or individual lists can be None (e.g., (None, None, [zmin, zmax])), in which case you have to provide a vector, which is then assumed to span exactly the domain. If only one list is provided it is applied to all dimensions.

vector : tuple of three ndarrays, ndarray, or None, optional

Contains vectors of mesh-edges that should be used. If provided, the vector MUST at least include all of the survey domain. If domain is not provided, it is defined as the minimum/maximum of the provided vector. Format: (xvector, yvector, zvector).

It can be None, or individual ndarrays can be None (e.g., (xvector, yvector, None)), in which case you have to provide a domain. If only one ndarray is provided it is applied to all dimensions.

seasurface : float, optional

Air-sea interface. This has only to be set in the marine case, when the mesh in z-direction is sought for (and the interface is not contained in vector). If set, it will ensure that at the sea surface is an actual boundary. It has to be bigger then the lower limit of the survey domain. Default is None.

stretching : list or tuple of lists, optional

Maximum stretching factors in the form of [max Ds, max Dc]: the first value is the maximum stretching for the survey domain (default is 1.0), the second value is the maximum stretching for the buffer zone (default is 1.5). If a list is provided the same is used for all three dimension. Alternatively a tuple of three lists can be provided, (x, y, z). Note that the first value has no influence on dimensions where a vector is provided.

min_width_limits : float, list or None, optional

Passed through min_cell_width() as limits. A tuple of three can be provided for direction dependent values. Note that this value has no influence on dimensions where a vector is provided.

Default is None.

min_width_pps : float or int, optional

Passed through min_cell_width() as pps. A tuple of three can be provided for direction dependent values. Note that this value has no influence on dimensions where a vector is provided.

Default is 3.

lambda_factor : float, optional

The buffer is taken as one wavelength from the survey domain. This can be regarded as quite conservative (but safe). The parameter lambda_factor can be used to reduce (or increase) this factor. Default is 1.0.

max_buffer : float, optional

Maximum thickness of the buffer zone around survey domain. If lambda_from_center=True, this is the maximum distance from the center to the end of the computational domain. Default is 100,000 (100 km).

lambda_from_center : bool, optional

Flag how to compute the extent of the computational mesh as a function of wavelength:

  • False (default): The distance from the edge of the survey domain to the edge of the computational domain is one wavelength.
  • True: The distance from the center to the edge of the computational domain and back to the end of the survey domain is two wavelengths.
mapping : str or map, optional

Defines what type the input property_{x;y;z}-values correspond to. By default, they represent resistivities (Ohm.m). The implemented mappings are:

  • ‘Conductivity’; σ (S/m),
  • ‘LgConductivity’; log_10(σ),
  • ‘LnConductivity’; log_e(σ),
  • ‘Resistivity’; ρ (Ohm.m); Default,
  • ‘LgResistivity’; log_10(ρ),
  • ‘LnResistivity’; log_e(ρ).
cell_numbers : list, optional

List of possible numbers of cells. See good_mg_cell_nr(). Default is good_mg_cell_nr(1024, 5, 3), which corresponds to numbers 16, 24, 32, 40, 48, 64, 80, 96, 128, 160, 192, 256, 320, 384, 512, 640, 768, 1024.

verb : int, optional

Verbosity, -1 (error); 0 (warning), 1 (info), 2 (verbose). Default = 0 (Warnings only).
Returns:
origin : float

Origin of the mesh.

widths : ndarray

Cell widths of mesh.