Elastic3D¶
Governing equations¶
Elastic3D solves the three-dimensional isotropic elastic wave equation in
velocity–stress form (Virieux, 1986):
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
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):
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 ¶
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=4is fourth-order accurate. Internally the half-stencil width isM = 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 forspatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher falls through to the genericorder = -1runtime path (seesrc/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'/ atorch.devicefor 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 wantimpl='c', leave this on'torch'. Defaults to'torch'.
C_NAME
class-attribute
¶
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
¶
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
¶
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 ¶
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.