Skip to content

Elastic3D

Governing equations

Elastic3D solves the three-dimensional isotropic elastic wave equation in velocity–stress form (Virieux, 1986):

\[ \begin{aligned} \rho \frac{\partial v_i}{\partial t} &= \sum_{j} \frac{\partial \sigma_{ij}}{\partial x_j}, \\ \frac{\partial \sigma_{ii}}{\partial t} &= \lambda\, \nabla \cdot \mathbf{v} + 2\mu \frac{\partial v_i}{\partial x_i}, \\ \frac{\partial \sigma_{ij}}{\partial t} &= \mu \left( \frac{\partial v_i}{\partial x_j} + \frac{\partial v_j}{\partial x_i} \right), \qquad i \neq j, \end{aligned} \]

with \(i, j \in \{x, y, z\}\) and no summation over repeated \(i\) in the second line. The particle velocities \(v_x\), \(v_y\), \(v_z\) are the fields vx, vy, vz, and the stresses \(\sigma_{xx}\), \(\sigma_{yy}\), \(\sigma_{zz}\), \(\sigma_{xy}\), \(\sigma_{xz}\), \(\sigma_{yz}\) are sxx, syy, szz, sxy, sxz, syz. The Lamé parameters are computed from the models vp, vs and rho as

\[ \lambda = \rho \left( v_p^2 - 2 v_s^2 \right), \qquad \mu = \rho\, v_s^2 . \]

The grid is the three-dimensional analogue of Elastic: the normal stresses sit at the integer nodes, each velocity component is shifted half a cell along its own axis, and each shear stress \(\sigma_{ij}\) is shifted half a cell along both \(i\) and \(j\). The first derivatives are staggered differences of order spatial_order (default 4), and the time stepping is leapfrog (velocities first, then stresses). \(\rho\), \(\lambda\) and \(\mu\) are not averaged onto the staggered positions. After each step the wavelet sample is added, unscaled, to every source field at the source cell; the default source fields sxx, syy and szz form an explosive source. The default receiver fields are vx, vy and vz; the shear stresses can be source but not receiver fields.

Boundary conditions

The default pml_type="cpmls" is the staggered-grid C-PML, with one memory variable per first derivative (m_vxx, ..., m_syzz); see Absorbing boundaries.

The free surface is available on the top face only (free_surface=True). The traction-free condition \(\sigma_{zz} = \sigma_{xz} = \sigma_{yz} = 0\) is imposed on the plane of the first model row by the image method: \(\sigma_{zz}\), \(v_x\) and \(v_y\) are mirrored about that plane, and \(\sigma_{xz}\), \(\sigma_{yz}\) and \(v_z\) about the plane half a cell above it (Kristek et al., 2002); the stresses and \(v_z\) are odd, \(v_x\) and \(v_y\) even. After each step \(\sigma_{zz}\) is set to zero on the surface row, and the surface values of \(\sigma_{xx}\) and \(\sigma_{yy}\) are updated with the moduli that follow from \(\sigma_{zz} = 0\) (Robertsson, 1996):

\[ \frac{\partial \sigma_{xx}}{\partial t} = \frac{4\mu (\lambda + \mu)}{\lambda + 2\mu} \frac{\partial v_x}{\partial x} + \frac{2\lambda\mu}{\lambda + 2\mu} \frac{\partial v_y}{\partial y}, \]

and likewise for \(\sigma_{yy}\) with \(x\) and \(y\) exchanged. With topography (impl='eager' only), the surface follows a staircase of per-column surface rows.

References

  • Kristek, J., P. Moczo, and R. J. Archuleta, 2002, Efficient methods to simulate planar free surface in the 3D 4th-order staggered-grid finite-difference schemes: Studia Geophysica et Geodaetica, 46(2), 355–381, doi:10.1023/a:1019866422821.
  • Robertsson, J. O. A., 1996, A numerical free-surface condition for elastic/viscoelastic finite-difference modeling in the presence of topography: Geophysics, 61(6), 1921–1934, doi:10.1190/1.1444107.
  • Virieux, J., 1986, P-SV wave propagation in heterogeneous media: Velocity-stress finite-difference method: Geophysics, 51(4), 889–901, doi:10.1190/1.1442147.

sweep.equations.Elastic3D

Elastic3D(spatial_order=4, device='cpu', backend='torch')

Bases: sweep.equations.base.FirstOrderEquation

First-order 3-D elastic wave equation on a staggered grid (Virieux 1986).

Three-dimensional velocity-stress formulation. The nine physical fields (vx, vy, vz, sxx, syy, szz, sxy, sxz, syz) are evolved together with eighteen CPML memory variables (one per first-derivative direction). Sources are typically an explosion (['sxx', 'syy', 'szz'] — the default) or a directional body force; receivers usually read particle velocities or stresses.

Reference: J. Virieux, 1986, P-SV wave propagation in heterogeneous media: velocity-stress finite-difference method, Geophysics 51(4), 10.1190/1.1442147.

Models (constructor input order)

  • vp (m/s): 3D elastic P-wave velocity model.
  • vs (m/s): 3D elastic S-wave velocity model.
  • rho (kg/m^3): 3D density model.

Wavefields

  • vx (aliases: velocity_x): Particle velocity in the x direction; default receiver.
  • vy (aliases: velocity_y): Particle velocity in the y direction; default receiver.
  • vz (aliases: velocity_z): Particle velocity in the z direction; default receiver.
  • sxx (aliases: stress_xx): Normal stress in the x direction; default source.
  • syy (aliases: stress_yy): Normal stress in the y direction; default source.
  • szz (aliases: stress_zz): Normal stress in the z direction; default source.
  • sxy (aliases: stress_xy, shear_xy): Shear stress component.
  • sxz (aliases: stress_xz, shear_xz): Shear stress component.
  • syz (aliases: stress_yz, shear_yz): Shear stress component.
  • m_vxx: CPML memory variable for dvx/dx (internal).
  • m_vxy: CPML memory variable for dvx/dy (internal).
  • m_vxz: CPML memory variable for dvx/dz (internal).
  • m_vyx: CPML memory variable for dvy/dx (internal).
  • m_vyy: CPML memory variable for dvy/dy (internal).
  • m_vyz: CPML memory variable for dvy/dz (internal).
  • m_vzx: CPML memory variable for dvz/dx (internal).
  • m_vzy: CPML memory variable for dvz/dy (internal).
  • m_vzz: CPML memory variable for dvz/dz (internal).
  • m_sxxx: CPML memory variable for dsxx/dx (internal).
  • m_szzz: CPML memory variable for dszz/dz (internal).
  • m_sxyx: CPML memory variable for dsxy/dx (internal).
  • m_sxyy: CPML memory variable for dsxy/dy (internal).
  • m_sxzx: CPML memory variable for dsxz/dx (internal).
  • m_sxzz: CPML memory variable for dsxz/dz (internal).
  • m_syyy: CPML memory variable for dsyy/dy (internal).
  • m_syzy: CPML memory variable for dsyz/dy (internal).
  • m_syzz: CPML memory variable for dsyz/dz (internal).

Defaults

  • source_type: ['sxx', 'syy', 'szz']
  • receiver_type: ['vx', 'vy', 'vz']
  • pml_type: 'cpmls'

Build the 3-D elastic equation operator.

Parameters:

  • spatial_order –

    FD accuracy order of the staggered first-derivative operator — e.g. spatial_order=4 is fourth-order accurate. Internally the half-stencil width is M = spatial_order // 2 (used for loop bounds and PML padding). Must be an even integer (2, 4, 6, 8, 10, …). Higher orders reduce grid dispersion — most visibly on the slower S-wave — at the cost of more compute per step and a wider PML halo. Performance note (impl='c' on CUDA): the compiled kernels are template-specialised only for spatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher falls through to the generic order = -1 runtime path (see src/sweep/csrc/cuda/equations/elastic3d/forward.cu) which is noticeably slower; the PyTorch eager path is unaffected. Defaults to 4.

  • device –

    Device for the operator's static gradient kernels. Use 'cuda' / a torch.device for GPU runs so the propagator can follow without a host↔device copy. Defaults to 'cpu'.

  • backend –

    Array / programming backend, 'torch' or 'jax'. When you later want impl='c', leave this on 'torch'. Defaults to 'torch'.

C_NAME class-attribute

C_NAME = 'elastic3d'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

image_topography_hint class-attribute

image_topography_hint = "The elastic image-method staircase was removed; for a 3-D elastic surface with topography use PropSEM."

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

supports_bs_free_surface class-attribute

supports_bs_free_surface = True

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

takes_invariants class-attribute

takes_invariants = True

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

interior_substeps

interior_substeps()

The leapfrog as two reversible sub-steps, REUSING the velocity_substep / stress_substep that :func:step (and thus func) is built from -- no rewritten copy of the physics. Called with pml zeroed (boundary saving reconstructs only the lossless interior) but the free-surface BC kept, so the eager boundary-saving 'substep' driver inverts the step exactly by composing the list in reverse order at -dt.