API for SphericalChunk3D type meshes

Salvus version: 0.12.16

This document describes all the various parameters and settings for meshes of the SphericalChunk3D type available when using the simple_mesh interface of SalvusMesh:

Copy
from salvus.mesh import simple_mesh
m = simple_mesh.SphericalChunk3D(...)
# Accessing the elements_per_wavelength parameter in the basic group
m.basic.elements_per_wavelength = 2.0

Basic Parameters group [basic]

The most important parameters for seismic wave simulations.

Required: True

Detailed description of all parameters:

• model

  • Pretty name: 1D Model

  • Description: Model Name for predefined 1D models or filename for external 1D model file.

  • Parameter type: string

  • Required: True

• min_period_in_seconds

  • Pretty name: Minumum Period in Seconds

  • Description: The desired minmimum period resolved by the mesh.

  • Parameter type: number

  • Required: True

• elements_per_wavelength

  • Pretty name: Elements per Wavelength

  • Description: Number of elements per wavelength at the mimimum period. Used to calculate element sizes in the 1D model as a function of depth.

  • Parameter type: number

  • Required: True

Advanced Parameters group [advanced]

Advanced parameters for more control on seismic wave sisimulation meshes.

Required: True

Detailed description of all parameters:

• courant_number

  • Pretty name: Courant Number

  • Description: Courant Number used to estimate dt.

  • Parameter type: number

  • Required: True

  • Default: 0.6

• tensor_order

  • Pretty name: Tensor Order

  • Description: Spatial order used for shape mapping and model representation.

  • Parameter type: integer

  • Required: True

  • Default: 1

• model_parameters

  • Pretty name: Model Parameters

  • Description: Model parameters to put into the mesh, defaults to the parametrization used by the 1D background model. This can be used for example to create an anisotropic parametrization of an isotropic model.

  • Parameter type: array of strings

  • Required: False

  • Default: []

  • Possible values: "g", "dg", "VP", "VS", "VSV", "VSH", "VPV", "VPH", "RHO", "QMU", "QKAPPA", "C11", "C12", "C13", "C14", "C15", "C16", "C21", "C22", "C23", "C24", "C25", "C26", "C31", "C32", "C33", "C34", "C35", "C36", "C41", "C42", "C43", "C44", "C45", "C46", "C51", "C52", "C53", "C54", "C55", "C56", "C61", "C62", "C63", "C64", "C65", "C66", "A", "C", "L", "N", "F", "XI", "PHI", "LAMBDA", "MU", "KAPPA", "ETA"

• velocity_model_representation

  • Pretty name: Velocity Model Representation

  • Description: How to represent the velocity model on the mesh. element_nodes: values are stored on each node of each element, allows discontinuities and variations inside each element, but produces large files. elements: one value per element, allows discontinuities but the model will be piecewise constant. nodes: one value per node, enforces a continuous model, using mean at values on discontinuities. The Salvus solver currently only supports 'element_nodes'.

  • Parameter type: string

  • Required: True

  • Default: "element_nodes"

  • Possible values: "element_nodes", "elements", "nodes"

• model_spline_order

  • Pretty name: Model Spline Order

  • Description: Spline order used for model interpolation in case of layered models. Ignored for polynomial models like PREM.

  • Parameter type: integer

  • Required: True

  • Default: 3

• compression

  • Pretty name: Compress Mesh

  • Description: If true, the final mesh will be compressed with gzip compression level 2. Compression is most effective for constant values and the compression level does matter much in that case. Slows down the mesh IO.

  • Parameter type: boolean

  • Required: True

  • Default: true

Attenuation Arguments group [attenuation]

Parameters for the memory variable approximation of attenuation. A detailed description can be found in van Driel et al. 2014b.

Required: True

Detailed description of all parameters:

• number_of_linear_solids

  • Pretty name: Number of Linear Solids

  • Description: The number of standard linear solids used. 5 is conservative, in many applications 3 may be sufficient.

  • Parameter type: integer

  • Required: True

  • Default: 5

• frequencies

  • Pretty name: Frequencies

  • Description: Minimum and maximum frequencies in the attenuation band. If either is not set, it will be determined automatically. Will be overwritten by 'auto_band'.

  • Parameter type: array of numbers

  • Required: False

  • Default: [0.001, 1.0]

• power_law_reference_frequency

  • Pretty name: Power Law Reference Frequency

  • Description: Reference frequency for power law Q = Q_0 (f / f_0)^alpha, where Q_0 is taken from background model [Hz]. Also see Fichtner & van Driel 2014.*

  • Parameter type: number

  • Required: True

  • Default: 1.0

• power_law_alpha

  • Pretty name: Power Law Alpha

  • Description: Exponent alpha for power law Q = Q_0 (f / f_0)^alpha. Also see Fichtner & van Driel 2014.*

  • Parameter type: number

  • Required: True

  • Default: 0.0

• auto_band

  • Pretty name: Auto frequency bands

  • Description: Automatically determine attenuation band [f_min, f_max] using an empirical relation for the bandwidth and the resolved frequency of the mesh (provided in basic). Will overwrite any given frequencies.

  • Parameter type: boolean

  • Required: True

  • Default: true

Spherical Arguments group [spherical]

Parameters for spherical meshes.

Required: True

Detailed description of all parameters:

• min_radius

  • Pretty name: Mimumum Radius

  • Description: Minimum radius in km.

  • Parameter type: number

  • Required: True

  • Default: 0.0

• ellipticity

  • Pretty name: Ellipticity

  • Description: Ellipticity of the planet (WGS84: 0.0033528106647474805, GRS80: 0.003352810681182319, MARS: 0.00589). If nonzero, the mesh will be deformed according to the Clairaut equation to match the given ellipticity at the surface.

  • Parameter type: number

  • Required: True

  • Default: 0.0

• gravity

  • Pretty name: Gravity

  • Description: Add gravitational acceleration from the 1D model as a field to the mesh. Solves the Poisson equation in the 1D model.

  • Parameter type: boolean

  • Required: True

  • Default: false

Refinement Arguments group [refinement]

Parameters for refinement of the meshes.

Required: True

Detailed description of all parameters:

• refinement_style

  • Pretty name: Refinement Style

  • Description: The mesh refinement style. 'doubling' produces the highest quality elements, but requires twice the number of layers to refine compared to 'doubling_single_layer'. 'tripling' is best for models with strong velocity constrasts.

  • Parameter type: string

  • Required: True

  • Default: "doubling"

  • Possible values: "doubling", "tripling", "doubling_single_layer"

• hmax_refinement

  • Pretty name: h_max Refinement

  • Description: Criterion (vertical oversamping factor BEFORE the refinement) for moving refinement layers downwards to avoid small timesteps caused by placing a refinement into a thin layer. Smaller values = more aggressive, needs to be > 1. For coarse meshes, larger values may be required. Ignored for 'local' refinement styles, if available.

  • Parameter type: number

  • Required: True

  • Default: 1.5

• refinement_bottom_up

  • Pretty name: Refinement Bottom Up

  • Description: There are two approaches of locating refinements in the mesh: top down approach means minimizing number of elements at the surface at the cost of more elements at the bottom (default). If the option refinement_bottom_up is set, the bottom up approach is used instead, that is minimizing number of elements at the bottom at the cost of more elements at the surface. Which one is more efficient depends on the velocity model and refinement style. Ignored for 'local' refinement styles, if available.

  • Parameter type: boolean

  • Required: True

  • Default: false

• horizontal_max_slowness_layer_index

  • Pretty name: Horizontal maximum slowness layer index (EXPERIMENTAL)

  • Description: For low velocity layers at the surface, horizontal refinements can be avoided if the source is below the LVL and hence cannot excite waves above a certain slowness. This is a 1D argument and might not me valid in 3D, hence check carefully. Ignored for 'local' refinement styles, if available.

  • Parameter type: integer

  • Required: True

  • Default: 0

3D Chunk Arguments group [chunk]

Parameters for single cubed sphere chunk 3D meshes.

Required: True

Detailed description of all parameters:

• max_colatitude1

  • Pretty name: Maximum Colatitude

  • Description: Maximum colatitude of the mesh from the center.

  • Parameter type: number

  • Required: True

  • Default: 45.0

• max_colatitude2

  • Pretty name: Maximum Colatitude

  • Description: Maximum colatitude of the mesh from the center.

  • Parameter type: number

  • Required: True

  • Default: 45.0

• euler_angles

  • Pretty name: Euler Angles

  • Description: Euler angles to rotate a spherical chunk. E.g. to rotate to a center given by longitude and geocentric latitude use [latitude, longitude, 0]. The last angle then determines the azimuth.

  • Parameter type: array of null or number

  • Required: True

  • Default: [None, None, None]

Absorbing Boundary group [absorbing_boundaries]

Parameters for the addition of absorbing boundary elements.

Required: True

Detailed description of all parameters:

• number_of_wavelengths

  • Pretty name: Number of Wavelengths.

  • Description: Width of the absorbing boundary in number of wavelengths at the reference velocity and frequency. For best performance, we recommend that this parameter is set to 3.5 or more. If set to zero, only first order absorbing boundaries are used.

  • Parameter type: number

  • Required: True

  • Default: 0.0

• reference_velocity

  • Pretty name: Reference Velocity

  • Description: Reference velocity which is used in the 'number_of_wavelengths' calculation. If the velocity is varying along the boundary, an average value may suffice. If undesirable reflections are still encountered it is best to trend towards the lowest velocity in the mesh, leading to a thicker absorbing layer.

  • Parameter type: number

  • Required: True

  • Default: 0.0

• reference_frequency

  • Pretty name: Reference Frequency

  • Description: Reference frequency used in the 'number_of_wavelengths' calculation. This may require some tuning for optimal performance, but a good starting point is setting it to the center frequency of your source. Use lower values to be more conervative.

  • Parameter type: ['number', 'string']

  • Required: True

  • Default: inf

• side_sets

  • Pretty name: Side Sets

  • Description: List of absorbing side sets to extended for sponge layers. At the moment only supports ['all'] and ['all_except_free_surface'] for cartesian and only ['all_except_free_surface'] for spherical meshes, or ['none'].

  • Parameter type: array of strings

  • Required: True

  • Default: ['none']

Topography Arguments group [topography]

Adding topography to the mesh.

Required: True

Detailed description of all parameters:

• topography_file

  • Pretty name: Topography Filename

  • Description: Filename for topography, see here

  • Parameter type: string

  • Required: True

  • Default: ""

• topography_varname

  • Pretty name: Topography Variable Name

  • Description: Variablename inside the topography file

  • Parameter type: string

  • Required: True

  • Default: ""

• moho_topography_file

  • Pretty name: Moho Topography Filename

  • Description: Filename for moho topography, see here

  • Parameter type: string

  • Required: True

  • Default: ""

• moho_topography_varname

  • Pretty name: Moho Topography Variable Name

  • Description: Variablename inside the moho topography file

  • Parameter type: string

  • Required: True

  • Default: ""

• anisotropic_refinement_style

  • Pretty name: Refinement Style for Anisotropic Refinement

  • Description: Use anisotropic refinement to adapt the number of elements in vertical direction to the crustal thickness. Assumes to have a single crustal layer. 'doubling' should be the preferred method, but is not compatible with a true ocean layer or a gravity mesh.

  • Parameter type: string

  • Required: True

  • Default: "none"

  • Possible values: "none", "doubling", "tripling"

Ocean Arguments group [ocean]

Adding a fluid ocean layer to the mesh.

Required: True

Detailed description of all parameters:

• bathymetry_file

  • Pretty name: Bathymetry Filename

  • Description: Filename for bathymetry, see here

  • Parameter type: string

  • Required: True

  • Default: ""

• bathymetry_varname

  • Pretty name: Bathymetry Variable name

  • Description: Variablename inside the bathymetry file

  • Parameter type: string

  • Required: True

  • Default: ""

• ocean_layer_vp

  • Pretty name: Ocean Layer vp

  • Description: P-wave velocity in the ocean in m/s.

  • Parameter type: number

  • Required: True

  • Default: 1450.0

• ocean_layer_density

  • Pretty name: Ocean Layer Density

  • Description: Density in the ocean in kg/m**3.

  • Parameter type: number

  • Required: True

  • Default: 1020.0

• ocean_layer_cutoff

  • Pretty name: Ocean Layer Cutoff

  • Description: Minimum bathymetry in km to be treated as fluid elements, smaller elements will be masked out and ocean loading approximation is used.

  • Parameter type: number

  • Required: True

  • Default: 1.0

• ocean_layer_maximum_element_oversize

  • Pretty name: Ocean Layer Maximum Element Oversize

  • Description: Maximum oversize in the lateral element dimension in the ocean layer, 1 meaning fully resolving all waves and larger values referg to the aspect ratio. A natural additional maximum to this is given by the ratio of vs in the crust to vp in the water.

  • Parameter type: number

  • Required: True

  • Default: 10.0

• shore_smoothing_factor

  • Pretty name: Shore smoothing factor

  • Description: Fraction of the element size to move the shore edge towards the water. For complicated shore lines smaller values might work better.

  • Parameter type: number

  • Required: True

  • Default: 0.0

• ocean_layer_style

  • Pretty name: Ocean Layer Meshing Style

  • Description: How to add the ocean layer. 'loading' only adds the bathymetry as a variable to be used for ocean loading, 'extrude' adds a single layer, 'anisotropic_' adds a locally varying number of elements. The latter is not compatible with anisotropic_refinement_style 'doubling' in the crust'. Only 'anisotropic_tripling' is compatible with a mesh in the external domain.*

  • Parameter type: string

  • Required: True

  • Default: "none"

  • Possible values: "none", "loading", "extrude", "anisotropic_doubling", "anisotropic_tripling"