Other equations¶
Exported equation classes without a page of their own; see the
equation index for the families. Compiled impl='c' kernels exist
for ElasticVRR, AcousticVTI1st, AcousticVTI1st3D, AcousticVTI,
AcousticTTI and the Born pair AcousticVTIBorn / AcousticTTIBorn; every
other class on this page runs on the eager backend only.
Curvilinear-grid topography¶
AcousticCurvilinear and ElasticCurvilinear are eager-only: they have no
CUDA kernel, so impl='auto' runs them eager and an explicit impl='c' falls
back to eager with a UserWarning.
Coordinate mapping¶
Both classes map the physical domain \((x, z)\), whose top boundary is the surface \(z = h(x)\), onto a rectangular computational domain \((\xi, \eta)\) by the vertical linear stretch
where \(h\) is the propagator argument topography (row indices) times the grid
spacing, smoothed with a Gaussian kernel when it is integer-valued, and
\(z_{\mathrm{b}}\) is the depth of the last physical row. The computational top
row \(\eta = 0\) therefore follows the topography, and a computational row
\(\Delta\eta = 1/(n_z - 1)\) spans \(D(\xi)/(n_z - 1)\) metres. The inverse
metrics are
so that \(\partial_x = \partial_\xi + \alpha\,\partial_\eta\) and
\(\partial_z = \beta\,\partial_\eta\); the Jacobian is \(J = D\). The metric
coefficients are continued into the absorbing layers by replicating the
nearest physical value. Boundary-conforming grids of this kind are used by
Tessmer and Kosloff (1994) and Hestholm and Ruud (1998), the references cited
in sweep.utils.curvilinear.
AcousticCurvilinear¶
The class solves the constant-density equation of Acoustic,
\(\partial_t^2 p = v_p^2 \nabla^2 p\), with \(p\) the wavefield h1 and \(v_p\) the
model vp. Under the mapping the Laplacian becomes
where \(\alpha_\xi\) and \(\alpha_\eta\) are precomputed by central differences.
The second derivatives use the central stencils of order spatial_order
(default 4) on the computational grid, and the mixed derivative is formed as
\(\partial_\xi (\partial_\eta p)\). The time update is that of Acoustic. The
operator is split into a \(\xi\) part, \(p_{\xi\xi} + \alpha p_{\xi\eta}\), and an
\(\eta\) part holding the remaining terms; these replace \(\partial_{xx} p\) and
\(\partial_{zz} p\) in the CPML of Acoustic (default pml_type="cpmlr"; see
Absorbing boundaries). The \(z\) derivatives
in the CPML terms are taken in physical depth, \(\partial_Z = \beta\,\partial_\eta\),
since one computational row is \(D\,\Delta\eta\) metres rather than the grid
spacing. With a free surface the pressure-release condition of Acoustic is
applied at the computational top row, which coincides with the topography.
ElasticCurvilinear¶
The class solves the isotropic velocity-stress system in the conservative form of Bartana, Xu and Rickett, on a collocated grid:
where \(i, j \in \{x, z\}\), the physical derivatives in the constitutive law
are formed with \(\partial_x = \partial_\xi + \alpha\partial_\eta\) and
\(\partial_z = \beta\partial_\eta\), and \(J\beta = 1\) has been used in the
\(\eta\)-flux. The wavefields are vx, vz, sxx, szz, sxz; the models
vp, vs, rho give \(\lambda = \rho (v_p^2 - 2 v_s^2)\) and
\(\mu = \rho v_s^2\). All five fields share the same grid points. Spatial
derivatives use asymmetric first-derivative operators of half-width
\(L\) = spatial_order/2 (default spatial_order=16) on the velocities and
their negative transposes on the stress fluxes, which makes the semi-discrete
operator self-adjoint. The product \(J\alpha\) is evaluated as
\((1 - \eta)\,\partial_\xi J\) with the scheme's own operator, so that a uniform
stress produces no discrete force.
The top row of the computational grid is the free surface. Its stress rate is not taken from the constitutive law but from the traction-free condition in the frame of the surface tangent \(\mathbf{t} = (1, h') / \sqrt{1 + h'^2}\):
where \(\dot{\varepsilon}_{tt}\) is the tangential strain rate, computed from
derivatives along the surface only and corrected for surface curvature. The
traction on the surface row therefore stays zero, and all fields above it are
held at zero. By default (surface_closure="mirror") the \(\eta\)-derivative of
the stress flux at the surface is closed by an odd reflection about the
surface row, and a Kreiss-Oliger filter (surface_damping) is applied in a
band below the surface to remove a high-wavenumber stress mode that the
closure supports. Absorption uses the default pml_type="cpmls", with CPML
memory variables on the \(\xi\)- and \(\eta\)-derivatives (see
Absorbing boundaries).
sweep.equations.AcousticCurvilinear ¶
Bases: sweep.equations.base.SecondOrderEquation
Curvilinear-grid Acoustic 2-D for irregular topography.
Same field / source / receiver layout as :class:Acoustic. The
propagator must build a :class:CurvilinearGrid from the user's
topography and attach its padded metric tensors to this
equation via set_curvilinear_metrics before the first step.
Models (constructor input order)
vp(m/s): Acoustic P-wave velocity model.
Wavefields
h1(aliases:pressure,p): Primary acoustic pressure-like wavefield; default source and receiver.h2(aliases:pressure_prev): Previous-step pressure-like wavefield (internal).psix: CPML memory variable for the ξ-derivative term (internal).psiz: CPML memory variable for the η-derivative term (internal).zetax: CPML auxiliary wavefield for the ξ-direction update (internal).zetaz: CPML auxiliary wavefield for the η-direction update (internal).
Defaults
source_type:['h1']receiver_type:['h1']pml_type:'cpmlr'
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.
set_curvilinear_metrics ¶
Attach precomputed metric tensors (padded to runtime shape).
sweep.equations.ElasticCurvilinear ¶
ElasticCurvilinear(
spatial_order=16,
device="cpu",
backend="torch",
kmax_frac=0.56,
nyquist_real=-2.0,
surface_reach=1,
surface_closure="mirror",
surface_damping=0.03,
surface_damping_rows=None,
adjoint_boundary_weight=0.0,
project_adjoint=False,
boundary_nyquist_real=-0.5,
source_spread=2,
surface_mass_weight=1.0,
damp_velocity=True,
hourglass_frequency=0.0,
hourglass_rows=None,
)
Bases: sweep.equations.base.FirstOrderEquation
Curvilinear-grid elastic 2-D for irregular topography.
Collocated fields, asymmetric operators and a rotated traction-free
surface -- see the module docstring. Same field / source / receiver
layout as :class:Elastic; the propagator attaches the metrics.
Parameters¶
spatial_order : int
2L: the interior stencil has 2L + 1 coefficients and the
propagator allocates an L-cell halo. The paper uses L = 8
(spatial_order=16), which is the default here.
kmax_frac, nyquist_real, surface_reach : see
:class:sweep.operators.asymmetric.CollocatedAsymmetricOperator.
source_spread : int
Number of binomial passes applied to the source / receiver
footprint (2 -> a 5x5 stencil). See
:attr:source_receiver_stencil; 0 gives a bare point source.
surface_damping : float
Strength of the Kreiss-Oliger filter that suppresses the
near-static high-wavenumber stress mode the free-surface closure
supports (see :meth:_surface_damper). 0 disables it, which
is useful for showing that the mode is really there. 4e-3 is
the smallest value that turns the per-step amplification factor
from 1.00059 into 0.99998 at a third of the CFL limit, but
the record keeps improving well past that: on a flat half-space
the trailing tail behind the Rayleigh arrival is 10.4% of peak at
4e-3, 4.2% at 1e-2 and 2.9% at the default 3e-2, and
the agreement with the staggered image-method solver improves with
it (cos 0.9962 -> 0.9989), so the filter is removing the spurious
mode rather than the signal. Being a per-step filter it needs
raising if the run sits much closer to the CFL limit.
damp_velocity : bool
Apply the surface filter to the velocities as well as the stresses.
The spurious surface mode is stress-dominated but it is sustained
by the velocity-stress loop, so filtering only one side leaves the
loop running: with the stresses alone the trailing tail on a flat
half-space is 2.9% of peak, with both it is 1.5% -- the level of
the staggered image-method solver on the same grid -- and the
waveform agreement improves too (cos 0.9989 -> 0.9992).
surface_damping_rows : int or None
Depth of the filter taper in cells; None uses 4L. The
taper wants to be wider than the closure band it is cleaning up:
at 2L the flat-surface tail is 4.2% of peak, at 4L it is
2.9%, because a narrow taper is itself a sharp enough profile to
scatter the surface wave.
adjoint_boundary_weight : float
Alternative to the filter -- see
:class:sweep.operators.asymmetric.CollocatedAsymmetricOperator.
Blending toward the exact adjoint also stabilises the closure but
costs accuracy in the divergence right where the surface wave
lives, so the filter is the default route.
surface_closure : {'shifted', 'mirror', 'zero'}
How the eta-stencils are closed at the free surface. The paper
says only that there are no ghost points and that stencil points
above the surface contribute zero, which are two different
prescriptions; all three readings are implemented.
``'shifted'`` takes "no ghost points" literally: the stencils are
truncated to the rows at or below the surface. ``'zero'`` takes
"contribute zero" literally; it is first-order *inconsistent* --
the eta-derivative of the traction flux on the surface row comes
out ~60% low -- and is kept only as a control.
``'mirror'`` (the default) reflects the traction flux
anti-symmetrically about the surface row. That is exact through
the quadratic term because the flux -- the surface traction --
vanishes there, so it is a symmetry of a quantity known to be
zero rather than an extrapolation, and on a boundary-fitted grid
the reflection is about a flat row and costs nothing. It departs
from the paper's "there are no ghost points" wording, and it is
the default because it measures better on every count: against
the staggered image-method solver on a flat half-space it reaches
cos 0.981 versus 0.938 for ``'shifted'``, its trailing tail is
2.13% of peak versus 2.48%, and on the steep hill its
near-surface band is 7.4x the interior rms versus 8.9x. Keep
``source_spread`` at 2 or below with it: a 7x7 footprint and the
mirror together were measurably worse than either alone.
Models (constructor input order)
vp(m/s): Elastic P-wave velocity model.vs(m/s): Elastic S-wave velocity model.rho(kg/m^3): Density model.
Wavefields
vx(aliases:velocity_x): Particle velocity in the x 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.szz(aliases:stress_zz): Normal stress in the z direction; default source.sxz(aliases:stress_xz,shear_xz): Shear stress component.m_vxx: CPML memory for dvx/dxi (internal).m_vxz: CPML memory for dvx/deta (internal).m_vzx: CPML memory for dvz/dxi (internal).m_vzz: CPML memory for dvz/deta (internal).m_txxx: CPML memory for the xi-flux of sigma_x (internal).m_txxz: CPML memory for the eta-flux of sigma_x (internal).m_tzzx: CPML memory for the xi-flux of sigma_z (internal).m_tzzz: CPML memory for the eta-flux of sigma_z (internal).m_txzx: CPML memory for the free-surface tangential velocity derivative (internal).hg_x: Hourglass-stiffness auxiliary for vx (internal).hg_z: Hourglass-stiffness auxiliary for vz (internal).
Defaults
source_type:['sxx', 'szz']receiver_type:['vx', 'vz']pml_type:'cpmls'
source_receiver_stencil
property
¶
Binomial footprint folded into source injection / receiver sampling.
A spatial delta excites every wavenumber the grid carries, and near
the free surface those are exactly the wavenumbers the boundary
closure handles worst -- with the source three cells down, the
grid-scale content of the top rows is ~170x what it is with the
same source below the closure band. Band-limiting the injection
removes that at no physical cost (the wavelet is band-limited
anyway); it is the same reason a spectral-element source, spread
over an element's nodes, leaves a cleaner near surface. None
(set source_spread=0) restores the single-cell injection.
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.
cfl_limit ¶
Largest stable dt for this operator and the attached grid.
The vertical physical spacing on a boundary-fitted grid is
D(xi) * d_eta and shrinks wherever the surface is elevated, so
the limit is taken over the whole grid.
set_curvilinear_metrics ¶
Attach metric tensors.
Only alpha (= T_31) and d_eta come through this hook;
beta (= T_33) and h_prime are assigned directly by the
propagator. The combined metric_p* fields are acoustic-only
and accepted for interface compatibility.
Vector reflectivity (VRR)¶
Both classes carry the density through the vector reflectivity of an impedance \(Z\),
instead of the density itself. The reflectivity components are model inputs;
for consistent models they are obtained from \((v_p, v_s, \rho)\) with
sweep.equations.elastic_vrr.compute_vector_reflectivity, which evaluates
this definition with \(Z_P = \rho v_p\) and \(Z_S = \rho v_s\) by central
differences.
AcousticVRR¶
AcousticVRR solves the scalar second-order equation
where \(p\) is the wavefield h1, \(v_p\) the model vp and
\(\mathbf{r} = (r_x, r_z)\) the models rx, rz. With
\(\mathbf{r} = \frac{1}{2}\nabla \ln(\rho v_p)\) the equation is identical to the
variable-density acoustic equation
\(\partial_t^2 p = \rho v_p^2 \nabla \cdot (\rho^{-1} \nabla p)\), since
\(-\nabla \ln \rho = -2\mathbf{r} + \nabla \ln v_p\); the code treats rx and
rz as independent models. Time and the Laplacian are discretised as in
Acoustic; \(\nabla v_p\) and \(\nabla p\) use central first-derivative stencils
of order spatial_order (default 4), and \(\nabla v_p\) is recomputed at every
step. In the absorbing layer the Laplacian and the first derivatives of \(p\)
both receive the CPML corrections of the default pml_type="cpmlr" (see
Absorbing boundaries). With
free_surface=True the selected faces are pressure-release, \(p = 0\), as in
Acoustic. The code cites Whitmore et al. (2020).
ElasticVRR¶
ElasticVRR implements the first-order formulation of Soares and Sacchi
(2025). The state variables are the particle momentum \(p_i = \rho v_i\) (px,
pz) and the Cartesian stress (sxx, szz, sxz), so that the equation of
motion contains no density:
For each wave type \(\alpha \in \{P, S\}\) the code forms
and updates the stresses as
Here \(V_P\) and \(V_S\) are the models vp and vs, and
\(\mathbf{R}_P = (R_{P,x}, R_{P,z})\) and \(\mathbf{R}_S\) are the models
Rp_x, Rp_z, Rs_x, Rs_z, with \(\mathbf{R}_\alpha = \frac{1}{2}\nabla
\ln(\rho V_\alpha)\). For consistent models the system is the isotropic
velocity-stress system with \(\lambda = \rho(V_P^2 - 2V_S^2)\) and
\(\mu = \rho V_S^2\). The fields sit on the staggered grid of Elastic, and the
momentum is updated before the stress. The gradients \(\partial_i V_\alpha\) are
central differences of order spatial_order (order 4 above 8), computed once
per run, and model values are multiplied with the staggered momentum without
interpolation. Absorption uses the default pml_type="cpmls" (see
Absorbing boundaries). With
free_surface=True the top row is treated as in Elastic: \(\sigma_{zz}\) and
\(\sigma_{xz}\) are set to zero, and \(\sigma_{xx}\) is advanced with
\(4 V_S^2 (V_P^2 - V_S^2) / V_P^2\, \partial_x p_x\), which is
\(4\mu(\lambda + \mu)/(\lambda + 2\mu)\, \partial_x v_x\) written in momentum
with \(\partial_x \rho\) neglected.
sweep.equations.AcousticVRR ¶
Bases: sweep.equations.base.SecondOrderEquation
Second-order 2-D acoustic wave equation in variable-density VRR form.
Pressure-only scalar acoustics with density coupling carried by two
auxiliary first-derivative parameters rx, rz (rather than the
impedance-like z of :class:AcousticVRZ). The propagator is a single
second-order PDE in h1,
∂²p/∂t² = vp²·∇²p + vp·(∇vp·∇p) − 2·vp²·(r·∇p) ,
so it refracts at sharp contrasts without needing a staggered velocity
field. Absorbing boundaries via split-step CPML (cpmlr).
Reference: 10.3997/2214-4609.202010332.
Models (constructor input order)
vp(m/s): Acoustic velocity model.rx: Auxiliary horizontal parameter used by the VRR formulation.rz: Auxiliary vertical parameter used by the VRR formulation.
Wavefields
h1(aliases:pressure,p): Primary VRR acoustic pressure-like wavefield; default source and receiver.h2(aliases:pressure_prev): Previous-step VRR acoustic pressure-like wavefield (internal).psix: CPML memory variable for the x-derivative term (internal).psiz: CPML memory variable for the z-derivative term (internal).zetax: CPML auxiliary wavefield for the x-direction update (internal).zetaz: CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['h1']pml_type:'cpmlr'
Build the 2-D VRR acoustic equation operator.
Parameters:
-
spatial_order(int, default:4) –The order of the Taylor expansion (must be even) for the spatial Laplacian and the auxiliary first-derivative kernels used by the
∇vp·∇p/r·∇pterms. Defaults to 4. -
device–Device for the operator's static gradient kernels. Use
'cuda'/ atorch.devicefor GPU runs. Defaults to'cpu'. -
backend–Array / programming backend,
'torch'or'jax'. Defaults to'torch'. -
dim–Stored dimensionality. Always
2for this class. Defaults to 2.
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.
sweep.equations.ElasticVRR ¶
Bases: sweep.equations.base.FirstOrderEquation
First-order 2-D elastic vector-reflectivity wave equation.
Soares & Sacchi 2025 momentum-stress formulation. State variables
are (px, pz, sxx, szz, sxz) with p_i = rho * v_i particle
momentum; physical Cartesian stress is unchanged. Models are
(vp, vs, Rp_x, Rp_z, Rs_x, Rs_z) -- NO density.
Reference: Soares, A. S. Q. and Sacchi, M. D. (2025). Vector-reflectivity Elastic Wave Equation with First-order formulation, SEG Technical Program Expanded Abstracts, doi 10.1190/image2025-4316471.1.
Models (constructor input order)
vp(m/s): Elastic P-wave velocity model.vs(m/s): Elastic S-wave velocity model.Rp_x: P-impedance vector reflectivity, x component.Rp_z: P-impedance vector reflectivity, z component.Rs_x: S-impedance vector reflectivity, x component.Rs_z: S-impedance vector reflectivity, z component.
Wavefields
px(aliases:momentum_x): Particle momentum x-component (= rho*vx); default receiver.pz(aliases:momentum_z): Particle momentum z-component (= rho*vz); default receiver.sxx(aliases:stress_xx): Normal stress in x; default source.szz(aliases:stress_zz): Normal stress in z; default source.sxz(aliases:stress_xz,shear_xz): Shear stress component.m_pxx: CPML memory variable for dpx/dx (internal).m_pxz: CPML memory variable for dpx/dz (internal).m_pzx: CPML memory variable for dpz/dx (internal).m_pzz: CPML memory variable for dpz/dz (internal).m_sxxx: CPML memory variable for dsxx/dx (internal).m_sxxz: Reserved auxiliary field (layout parity with Elastic) (internal).m_szzx: Reserved auxiliary field (layout parity with Elastic) (internal).m_szzz: CPML memory variable for dszz/dz (internal).m_sxzx: CPML memory variable for dsxz/dx (internal).m_sxzz: CPML memory variable for dsxz/dz (internal).
Defaults
source_type:['sxx', 'szz']receiver_type:['px', 'pz']pml_type:'cpmls'
Build the elastic vector-reflectivity operator.
Parameters:
-
spatial_order–FD accuracy order of the staggered first-derivative operator. Must be even (2, 4, 6, 8, ...). Defaults to 4.
-
device–Device for the operator. Defaults to 'cpu'.
-
backend–'torch' or 'jax'. 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 an elastic surface with topography use ElasticCurvilinear (2-D) or 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
:func:vr_momentum_substep / :func:vr_stress_substep that
:func:elastic_vr_step_core (and thus func) is built from. 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.
prepare_models ¶
The models as they are. The spatial gradients of vp and vs
need h, which only the step gets: the step makes them
(:meth:_precompute_velocity_gradients).
Anisotropic acoustic family¶
AcousticAniso is a factory: it returns an instance of one of the classes
below. The author-named aliases (AcousticVTILiang, AcousticTTILiang,
AcousticVTIAlkhalifah, AcousticVTIDuveneck, AcousticVTIDuveneck3D) and
the AcousticVTIDefault / AcousticVTIDefault3D routing names are these same
classes. method="duveneck" returns
AcousticVTI1st (ndim=2) or AcousticVTI1st3D (ndim=3, VTI only),
method="liang" returns AcousticVTI or AcousticTTI (2-D), and
method="alkhalifah" returns AcousticTariq (2-D, VTI only;
symmetry="tti" raises NotImplementedError).
sweep.equations.AcousticAniso ¶
Factory class — instantiating returns an equation instance.
Construction is intentionally lightweight: __new__ resolves the
target equation class and constructs it with the user-supplied
keyword arguments, returning that instance directly. isinstance(x,
AcousticAniso) will therefore be False — x is the actual
equation class (e.g. AcousticVTI1st).
Parameters¶
method : {"duveneck", "liang", "alkhalifah"}, default "duveneck" symmetry : {"vti", "tti"}, default "vti" ndim : {2, 3}, default 2 spatial_order : int, default 4 device : str, default "cpu" backend : str, default "torch" **equation_kwargs : forwarded to the resolved equation constructor.
Examples¶
from sweep.equations import AcousticAniso from sweep.propagator.torch import PropTorch eq = AcousticAniso(method="duveneck", symmetry="vti", ndim=2) isinstance(eq, AcousticAniso) False type(eq).name 'AcousticVTI1st'
The pure-qP pair and its Born equations: the derivation, the three
s_gradient modes and the compiled backend are in
Pure-qP VTI / TTI. AcousticVTI and
AcousticTTI solve the decoupled pure-qP equation obtained with the acoustic
approximation of Liang et al. (2023), in which the qSV phase velocity is set to
zero in every direction; the operator \(S_n\) follows Xu and Zhou (2014), as
cited in the code.
sweep.equations.AcousticVTI ¶
Bases: sweep.equations.base.SecondOrderEquation
Second-order 2-D pure-qP VTI wave equation (Liang et al. 2023).
The decoupled qP-wave equation of the "new acoustic approximation" (the
qSV phase velocity set to zero in every direction), solved in the space
domain: the pressure-like field h1 is driven by PML-corrected
Laplacian terms with anisotropy weights S_n that depend on the local
propagation direction of the wavefront, the spatial gradient of h1
itself (eqs. 19-23 of the paper). A pure qP equation: no auxiliary f
field as in the Alkhalifah / eta family, no qSV artefact, and stable for
epsilon < delta too.
source_type=['h1'] is the default. The explicit scheme is stable when
dt meets eq. B-9 of the paper, which tightens as epsilon grows;
PropTorch warns once when a forward breaks it
(:func:qp_stability_ratio). Also exposed as
:class:AcousticAniso(method='liang', symmetry='vti').
Reference: Liang K. et al. 2023, 10.1190/geo2022-0292.1; the S_n operator follows Xu and Zhou (2014), 10.1190/geo2014-0242.1.
Gradient (s_gradient). S_n takes its direction from the wavefield, so
the discrete step is nonlinear in h1; the forward is the same in all
three modes, the backward differs:
'adjoint'(default): the adjoint of the wavenumber-domain operator (eq. 14) is the same qP operator, so the adjoint wavefield is propagated with S_n taken from its own gradient; the model gradient is imaged with the forward field's S_n and its epsilon / delta derivatives. Well conditioned, and the back-propagated residuals travel with the right anisotropic kinematics.'frozen': the transpose of the step with S_n held at the forward field's value (the adjoint then travels with the forward wave's direction).'exact': the exact derivative of the discrete forward map, through S_n's wavefield direction too. Its adjoint coefficients (dS_n/dgrad p ~ 1/|grad p|) spike where the gradient vanishes and do not shrink with the amplitude, so it moves by percents with the forward's rounding (fp32 against fp64 eager ~2%); full storage only.
See docs/user-guide/qp_born.md.
Models (constructor input order)
vp(m/s): VTI acoustic reference velocity.epsilon: Thomsen epsilon parameter.delta: Thomsen delta parameter.
Wavefields
h1(aliases:pressure,p): Primary acoustic-VTI pressure-like wavefield; default source and receiver.h2(aliases:pressure_prev): Previous-step pressure-like wavefield (internal).psix: CPML memory variable for the x-derivative term (internal).psiz: CPML memory variable for the z-derivative term (internal).zetax: CPML auxiliary wavefield for the x-direction update (internal).zetaz: CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['h1']pml_type:'cpmlr'
Build the 2-D pure-qP VTI equation operator.
Parameters:
-
spatial_order–FD accuracy order of the spatial Laplacian and the auxiliary first-derivative kernels used by the anisotropy direction term — 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, …).impl='c'(CUDA) runs the same scheme with full or boundary-saving gradients (no checkpointing). Defaults to 4. -
device–Device for the operator's static kernels. Use
'cuda'/ atorch.devicefor GPU eager runs. Defaults to'cpu'. -
backend–Array / programming backend,
'torch'or'jax'. Defaults to'torch'. -
dim–Stored dimensionality. Always
2for this class. Defaults to 2. -
s_gradient–'adjoint','frozen'or'exact', how the gradient treats S_n (see the class docstring). Defaults to'adjoint'.
C_HAS_RECURSIVE_CKPT
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.
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'.
supports_boundary_saving_eager
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.
supports_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.
check_stability ¶
Warn once when dt breaks the scheme's stability condition
(:func:qp_stability_ratio); PropTorch calls it before every forward.
sweep.equations.AcousticTTI ¶
Bases: sweep.equations.base.SecondOrderEquation
Second-order 2-D pure-qP TTI wave equation (Liang et al. 2023, appendix A).
Tilted-symmetry-axis extension of :class:AcousticVTI. The
pressure-like field h1 is updated with anisotropy weights that
are computed in a tilted frame defined by theta; the Laplacian
along the symmetry axis is rotated accordingly, and an extra
∂²p/∂x∂z mixed-term carries the off-diagonal anisotropy.
A single-field pure qP equation -- no auxiliary f field. The paper gives
the TTI operator in the wavenumber domain (eq. A-7); here S_n takes the
wavefield gradient rotated into the symmetry-axis frame (eq. A-3). Also
exposed as :class:AcousticAniso(method='liang', symmetry='tti').
Reference: Liang K. et al. 2023, 10.1190/geo2022-0292.1.
s_gradient as :class:AcousticVTI ('adjoint', the default,
propagates the adjoint wavefield with its own S_n; 'frozen' holds S_n
at the forward field; 'exact' differentiates through its direction).
Models (constructor input order)
vp(m/s): TTI acoustic reference velocity.epsilon: Thomsen epsilon parameter.delta: Thomsen delta parameter.theta(rad): Tilt angle parameter.
Wavefields
h1(aliases:pressure,p): Primary acoustic-TTI pressure-like wavefield; default source and receiver.h2(aliases:pressure_prev): Previous-step pressure-like wavefield (internal).psix: CPML memory variable for the x-derivative term (internal).psiz: CPML memory variable for the z-derivative term (internal).zetax: CPML auxiliary wavefield for the x-direction update (internal).zetaz: CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['h1']pml_type:'cpmlr'
Build the 2-D pure-qP TTI equation operator.
Parameters:
-
spatial_order–FD accuracy order of the spatial Laplacian and the auxiliary first-derivative kernels used by the rotated-anisotropy term — 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, …).impl='c'(CUDA) runs the same scheme with full or boundary-saving gradients (no checkpointing). Defaults to 4. -
device–Device for the operator's static kernels. Use
'cuda'/ atorch.devicefor GPU eager runs. Defaults to'cpu'. -
backend–Array / programming backend,
'torch'or'jax'. Defaults to'torch'. Requires the matching array library to be importable. -
dim–Stored dimensionality. Always
2for this class. Defaults to 2. -
s_gradient–'adjoint','frozen'or'exact'(see :class:AcousticVTI). Defaults to'adjoint'.
C_HAS_RECURSIVE_CKPT
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.
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'.
supports_boundary_saving_eager
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.
supports_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.
check_stability ¶
Warn once when dt breaks the scheme's stability condition
(:func:~sweep.equations.qP_vti.qp_stability_ratio); PropTorch calls it before every forward.
sweep.equations.AcousticVTIBorn ¶
Bases: sweep.equations.qP_born._QPBorn
Born / LSRTM equation of the pure-qP VTI operator (:class:AcousticVTI).
A background qP field h1 in the smooth vp / epsilon /
delta and a scattered qP field sh1 driven by the reflectivity
mp (2 dv / v) times the background's v^2 F[p0]; each field
evaluates the anisotropy operator S_n on its own gradient (the Born
approximation of the wavenumber-domain eq. 14, see the module docstring).
Models (constructor input order)
vp(m/s): Background VTI reference velocity.epsilon: Thomsen epsilon parameter.delta: Thomsen delta parameter.mp: Velocity reflectivity 2 dv / v of the Born scattering.
Wavefields
h1(aliases:pressure,p,background): Background qP pressure-like wavefield; default source.h2(aliases:pressure_prev,background_prev): Previous-step background wavefield (internal).psix: Background CPML memory variable for the x-derivative term (internal).psiz: Background CPML memory variable for the z-derivative term (internal).zetax: Background CPML auxiliary wavefield for the x-direction update (internal).zetaz: Background CPML auxiliary wavefield for the z-direction update (internal).sh1(aliases:scattered,scattered_pressure,data): Scattered (Born) qP wavefield used for LSRTM data prediction; default receiver.sh2(aliases:scattered_prev): Previous-step scattered wavefield (internal).spsix: Scattered-wave CPML memory variable for the x-derivative term (internal).spsiz: Scattered-wave CPML memory variable for the z-derivative term (internal).szetax: Scattered-wave CPML auxiliary wavefield for the x-direction update (internal).szetaz: Scattered-wave CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['sh1']pml_type:'cpmlr'
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'.
sweep.equations.AcousticTTIBorn ¶
Bases: sweep.equations.qP_born._QPBorn
Born / LSRTM equation of the pure-qP TTI operator (:class:AcousticTTI).
As :class:AcousticVTIBorn, with the tilt theta (radians).
Models (constructor input order)
vp(m/s): Background TTI reference velocity.epsilon: Thomsen epsilon parameter.delta: Thomsen delta parameter.theta(rad): Tilt angle parameter.mp: Velocity reflectivity 2 dv / v of the Born scattering.
Wavefields
h1(aliases:pressure,p,background): Background qP pressure-like wavefield; default source.h2(aliases:pressure_prev,background_prev): Previous-step background wavefield (internal).psix: Background CPML memory variable for the x-derivative term (internal).psiz: Background CPML memory variable for the z-derivative term (internal).zetax: Background CPML auxiliary wavefield for the x-direction update (internal).zetaz: Background CPML auxiliary wavefield for the z-direction update (internal).sh1(aliases:scattered,scattered_pressure,data): Scattered (Born) qP wavefield used for LSRTM data prediction; default receiver.sh2(aliases:scattered_prev): Previous-step scattered wavefield (internal).spsix: Scattered-wave CPML memory variable for the x-derivative term (internal).spsiz: Scattered-wave CPML memory variable for the z-derivative term (internal).szetax: Scattered-wave CPML auxiliary wavefield for the x-direction update (internal).szetaz: Scattered-wave CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['sh1']pml_type:'cpmlr'
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'.
AcousticTariq¶
AcousticTariq solves the acoustic VTI equation of Alkhalifah (2000), written
as two second-order equations in the wavefield \(p\) (h1) and an auxiliary
field \(F\) (f1) with \(p = \partial_t^2 F\):
Here \(v\) is the model v, the NMO velocity \(v_{p0}\sqrt{1 + 2\delta}\);
\(v_v\) is the model vv, the vertical P-wave velocity; and \(\eta\) is the anellipticity eta. The horizontal
velocity is \(v\sqrt{1 + 2\eta}\). Both fields are advanced with the
second-order central difference in time, \(F\) with \(p^n\) on the right-hand
side. The second derivatives use central stencils of order spatial_order
(default 4), and the mixed term applies the \(x\) and \(z\) stencils in sequence.
The class has no tilt-angle model and is VTI only.
The default pml_type="cpmlr" stretches the \(\partial_{xx} p\) and
\(\partial_{zz} p\) terms as in Acoustic; the mixed term receives no CPML
correction (see Absorbing boundaries). The
class has no free surface and rejects free_surface=True.
sweep.equations.AcousticTariq ¶
Bases: sweep.equations.base.SecondOrderEquation
Second-order 2-D pseudo-acoustic VTI wave equation (Alkhalifah eta).
Two-field pseudo-acoustic formulation: the primary pressure-like
field h1 is coupled to an auxiliary integrated field f1
through the anellipticity parameter eta. The split into
(h1, f1) is what suppresses the shear-mode artifact that the
original Alkhalifah pseudo-acoustic exhibits. The model parameter
v here is the NMO velocity (v = vp · sqrt(1 + 2 delta)),
not the horizontal velocity; vv is the vertical velocity
(not its square: the step squares it). VTI only: there is no tilt
parameter. Source must include h1 (default
source_type=['h1'] is set by the propagator).
Reference: Alkhalifah T. 2000, An acoustic wave equation for anisotropic media, 10.1190/1.1444815.
Models (constructor input order)
vv(m/s): Vertical P-wave velocity.v(m/s): Velocity-like parameter for the Tariq qP formulation.eta: Anellipticity parameter for the Tariq qP formulation.
Wavefields
h1(aliases:pressure,p): Primary acoustic-Tariq qP pressure-like wavefield; default source and receiver.h2(aliases:pressure_prev): Previous-step pressure-like wavefield (internal).f1: Auxiliary wavefield integrating the primary pressure (Tariq qP) (internal).f2: Previous-step auxiliary wavefield (Tariq qP) (internal).psix: CPML memory variable for the x-derivative term (internal).psiz: CPML memory variable for the z-derivative term (internal).zetax: CPML auxiliary wavefield for the x-direction update (internal).zetaz: CPML auxiliary wavefield for the z-direction update (internal).
Defaults
source_type:['h1']receiver_type:['h1']pml_type:'cpmlr'
Build the 2-D Alkhalifah-eta pseudo-acoustic equation operator.
Parameters:
-
spatial_order–FD accuracy order of the spatial Laplacian and the auxiliary first-derivative kernels — 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, …). This equation has no compiledimpl='c'path; useimpl='eager'(the default). Defaults to 4. -
device–Device for the operator's static kernels. Use
'cuda'/ atorch.devicefor GPU eager runs. Defaults to'cpu'. -
backend–Array / programming backend,
'torch'or'jax'. Defaults to'torch'. -
dim–Stored dimensionality. Always
2for this class. Defaults to 2.
supports_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.
AcousticVTI1st and AcousticVTI1st3D¶
These classes solve the first-order acoustic VTI system of Duveneck et al.
(2008), which follows from the elastic VTI equations with the shear velocity
on the symmetry axis set to zero (Alkhalifah, 1998). In 2-D the state is the
particle velocity (vx, vz) and the two normal stresses
\(\sigma_H = \sigma_{xx} = \sigma_{yy}\) (sH) and \(\sigma_V = \sigma_{zz}\)
(sV):
with
where \(v_p\) is the vertical P-wave velocity vp, \(\varepsilon\) and \(\delta\)
are the Thomsen (1986) parameters epsilon and delta, and \(\rho\) is rho.
The square root in \(c_{13}\) is kept, not linearised. In 3-D, \(\sigma_H\) also
drives \(\rho\,\partial_t v_y = \partial_y \sigma_H\), and \(\partial_x v_x\) is
replaced by \(\partial_x v_x + \partial_y v_y\) in both stress equations. The
fields sit on a standard staggered grid with first-derivative stencils of
order spatial_order (default 4), and the velocities are updated before the
stresses. The system is unstable where \(\varepsilon < \delta\) (Grechka et al.,
2004); prepare_models warns in that case but does not stop the run.
Absorption uses the default pml_type="cpmls" (see
Absorbing boundaries). No free surface is
implemented, and free_surface=True raises NotImplementedError.
sweep.equations.AcousticVTI1st ¶
Bases: sweep.equations.base.FirstOrderEquation
First-order 2-D acoustic VTI wave equation on a standard staggered grid.
Velocity-stress formulation (Duveneck et al. 2008): four wavefields
(vx, vz, sH, sV) evolve together with four CPML memory variables.
The system uses the Alkhalifah (1998) V_S = 0 approximation, so
only two independent normal stresses exist: sH = sigma_11 =
sigma_22 (horizontal) and sV = sigma_33 (vertical). The four
cached stiffness coefficients are c11 = rho · vp² · (1 + 2·eps),
c33 = rho · vp², c13 = rho · vp² · sqrt(1 + 2·delta), and
inv_rho = 1 / rho. Variable density is supported natively; CPML
is the staggered-grid cpmls variant (8 profiles).
Stability requires eps >= delta everywhere
(Grechka et al. 2004); prepare_models issues a runtime warning
when this is violated. Free-surface BC is not yet supported (the
constructor raises NotImplementedError for free_surface=True)
— see the TODO_free_surface comment on the class. Also exposed
as :class:AcousticAniso(method='duveneck', symmetry='vti').
References
Duveneck E. et al. 2008, Acoustic VTI wave equations and their application for anisotropic reverse-time migration, SEG Las Vegas 2008, DOI: 10.1190/1.3059320. Alkhalifah T. 1998, Acoustic approximations for processing in TI media, Geophysics 63, 623–631. Thomsen L. 1986, Weak elastic anisotropy, Geophysics 51, 1954–1966.
Models (constructor input order)
vp(m/s): Vertical P-wave velocity.epsilon: Thomsen epsilon anisotropy parameter (ε ≥ δ required).delta: Thomsen delta anisotropy parameter.rho(kg/m^3): Density.
Wavefields
vx(aliases:velocity_x): Particle velocity in x.vz(aliases:velocity_z): Particle velocity in z; default receiver.sH(aliases:stress_h,sigma_H): Horizontal normal stress σ_11 = σ_22; default source.sV(aliases:stress_v,sigma_V): Vertical normal stress σ_33; default source.m_sHx: CPML memory variable for ∂σ_H/∂x (internal).m_sVz: CPML memory variable for ∂σ_V/∂z (internal).m_vxx: CPML memory variable for ∂v_x/∂x (internal).m_vzz: CPML memory variable for ∂v_z/∂z (internal).
Defaults
source_type:['sH', 'sV']receiver_type:['vz']pml_type:'cpmls'
Build the 2-D first-order acoustic VTI 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, …). Performance note (impl='c'on CUDA): the compiled kernels ship template specialisations only forspatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1insrc/sweep/csrc/cuda/equations/acoustic_vti_1st_2d/forward.cu) which uses more registers and runs 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'. -
free_surface–Enable a free-surface BC on the top face. Not currently supported for the VTI system — the naive isotropic image method is physically incorrect because the
sigma_V = 0constraint couplesd(vz)/dztod(vx)/dxvia the off-diagonal stiffnessc13(Robertsson 1996; Mittet 2002). PassingTrueraisesNotImplementedError; use absorbing PML on all four sides instead. Defaults toFalse.
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'.
cuda_layout
property
¶
CUDA buffer layout.
base_nvar = 4 (vx, vz, sH, sV)
pml_nvar = 4 (m_sHx, m_sVz, m_vxx, m_vzz)
last_two_storage_nvar = 4 (snapshot of vx, vz, sH, sV)
backward_workspace_nvar = 5 (the compiled backward's scratch: two
pre-multiplication buffers, one
read-only zero "previous stress", and
the two chunk-boundary seeds of the
checkpoint mode; the 8 adjoint
wavefields are passed separately via
adjoint_wavefields).
supports_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.
prepare_models ¶
Pre-compute stiffness coefficients from Thomsen parameters.
Warns (via warnings.warn) when ε < δ anywhere, since this
violates the stability condition identified by Grechka, Zhang, Rector
(2004), Geophysics 69, 576.
Cached outputs: c11 = ρV_P²(1+2ε), c33 = ρV_P², c13 = ρV_P²√(1+2δ), inv_rho = 1/ρ.
References¶
Thomsen (1986) Geophysics 51, 1954–1966. (ε, δ parameterisation.) Grechka et al. (2004) Geophysics 69, 576. (ε ≥ δ stability.)
recommended_dt
classmethod
¶
CFL-stable time step for the 2-D fourth-order scheme.
Δt ≤ CFL · h / (V_P_max · √(1 + 2 ε_max))
Parameters¶
vp_max : float Maximum vertical P-wave velocity in the model (m/s). epsilon_max : float Maximum Thomsen ε in the model. h : float Grid spacing (m). cfl : float, optional CFL number. Default 0.5 (safe for 4th-order spatial scheme).
sweep.equations.AcousticVTI1st3D ¶
Bases: sweep.equations.base.FirstOrderEquation
First-order 3-D acoustic VTI wave equation on a standard staggered grid.
Three-dimensional generalisation of :class:AcousticVTI1st: five
wavefields (vx, vy, vz, sH, sV) evolve together with six CPML
memory variables. The horizontal isotropy of VTI media gives
sH = sigma_11 = sigma_22 so only two distinct normal stresses
are tracked. Same Duveneck (2008) cached stiffness as the 2-D
variant. Variable density; CPML cpmls (12 profiles). Free
surface is not yet supported. Also exposed as
:class:AcousticAniso(method='duveneck', symmetry='vti', ndim=3).
Reference: Duveneck E. et al. 2008, 10.1190/1.3059320.
Models (constructor input order)
vp(m/s): Vertical P-wave velocity.epsilon: Thomsen epsilon anisotropy parameter (ε ≥ δ required).delta: Thomsen delta anisotropy parameter.rho(kg/m^3): Density.
Wavefields
vx(aliases:velocity_x): Particle velocity in x.vy(aliases:velocity_y): Particle velocity in y.vz(aliases:velocity_z): Particle velocity in z; default receiver.sH(aliases:stress_h,sigma_H): Horizontal normal stress σ_11 = σ_22; default source.sV(aliases:stress_v,sigma_V): Vertical normal stress σ_33; default source.m_sHx: CPML memory variable for ∂σ_H/∂x (internal).m_sHy: CPML memory variable for ∂σ_H/∂y (internal).m_sVz: CPML memory variable for ∂σ_V/∂z (internal).m_vxx: CPML memory variable for ∂v_x/∂x (internal).m_vyy: CPML memory variable for ∂v_y/∂y (internal).m_vzz: CPML memory variable for ∂v_z/∂z (internal).
Defaults
source_type:['sH', 'sV']receiver_type:['vz']pml_type:'cpmls'
Build the 3-D first-order acoustic VTI 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, …). Performance note (impl='c'on CUDA): the compiled kernels ship template specialisations only forspatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1insrc/sweep/csrc/cuda/equations/acoustic_vti_1st_3d/forward.cu) which uses more registers and runs 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'. -
free_surface–Enable a free-surface BC on the top face. Not currently supported for the VTI system — same reason as the 2-D case (see :class:
AcousticVTI1st). PassingTrueraisesNotImplementedError. Defaults toFalse.
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'.
cuda_layout
property
¶
CUDA buffer layout.
base_nvar = 5 (vx, vy, vz, sH, sV)
pml_nvar = 6 (m_sHx, m_sHy, m_sVz, m_vxx, m_vyy, m_vzz)
last_two_storage_nvar = 5 (snapshot of vx, vy, vz, sH, sV)
backward_workspace_nvar = 6 (the compiled backward's scratch: three
pre-multiplication buffers, one read-only
zero "previous stress", and the two
chunk-boundary seeds of the checkpoint
mode; the 11 adjoint wavefields are
passed separately via
adjoint_wavefields).
supports_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.
prepare_models ¶
Pre-compute stiffness coefficients (identical logic to 2-D).
See AcousticVTI1st.prepare_models for details.
recommended_dt
classmethod
¶
CFL-stable time step for the 3-D fourth-order scheme.
Same formula as the 2-D case (the fast horizontal P velocity governs).
References¶
- Alkhalifah, T., 1998, Acoustic approximations for processing in transversely isotropic media: Geophysics, 63(2), 623–631, doi:10.1190/1.1444361.
- Alkhalifah, T., 2000, An acoustic wave equation for anisotropic media: Geophysics, 65(4), 1239–1250, doi:10.1190/1.1444815.
- Bartana, A., J. Xu, and J. Rickett, Solving the elastodynamic equations in
curvilinear coordinates using asymmetric operators (cited in
elastic_curvilinear.pywithout publication details). - Duveneck, E., P. Milcik, P. M. Bakker, and C. Perkins, 2008, Acoustic VTI wave equations and their application for anisotropic reverse-time migration: SEG Technical Program Expanded Abstracts 2008, 2186–2190, doi:10.1190/1.3059320.
- Grechka, V., L. Zhang, and J. W. Rector III, 2004, Shear waves in acoustic anisotropic media: Geophysics, 69(2), 576–582, doi:10.1190/1.1707077.
- Hestholm, S., and B. Ruud, 1998, 3-D finite-difference elastic wave modeling including surface topography: Geophysics, 63(2), 613–622, doi:10.1190/1.1444360.
- Liang, K., D. Cao, S. Sun, and X. Yin, 2023, Decoupled wave equation and forward modeling of qP wave in VTI media with the new acoustic approximation: Geophysics, 88(1), WA335–WA344, doi:10.1190/geo2022-0292.1.
- Soares, A. S. Q., and M. D. Sacchi, 2025, Vector-reflectivity elastic wave equation with first-order formulation: Fifth International Meeting for Applied Geoscience & Energy, Expanded Abstracts, 1942–1946, doi:10.1190/image2025-4316471.1.
- Tessmer, E., and D. Kosloff, 1994, 3-D elastic modeling with surface topography by a Chebychev spectral method: Geophysics, 59(3), 464–473, doi:10.1190/1.1443608.
- Thomsen, L., 1986, Weak elastic anisotropy: Geophysics, 51(10), 1954–1966, doi:10.1190/1.1442051.
- Whitmore, N. D., J. Ramos-Martinez, Y. Yang, and A. Valenciano, 2020, Full wavefield modeling with vector reflectivity: EAGE 2020 Annual Conference & Exhibition Online, Extended Abstracts, 1–5, doi:10.3997/2214-4609.202010332.
- Xu, S., and H. Zhou, 2014, Accurate simulations of pure quasi-P-waves in complex anisotropic media: Geophysics, 79(6), T341–T348, doi:10.1190/geo2014-0242.1.