Skip to content

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

\[ x = \xi, \qquad z = h(\xi) + D(\xi)\,\eta, \qquad D(\xi) = z_{\mathrm{b}} - h(\xi), \qquad 0 \le \eta \le 1, \]

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

\[ \frac{\partial \eta}{\partial x} = \alpha(\xi, \eta) = -\frac{h'(\xi)\,(1 - \eta)}{D(\xi)}, \qquad \frac{\partial \eta}{\partial z} = \beta(\xi) = \frac{1}{D(\xi)}, \]

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

\[ \nabla^2 p = p_{\xi\xi} + 2\alpha\, p_{\xi\eta} + \left( \alpha^2 + \beta^2 \right) p_{\eta\eta} + \left( \alpha_\xi + \alpha\, \alpha_\eta \right) p_\eta , \]

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:

\[ \rho J \frac{\partial v_i}{\partial t} = \frac{\partial}{\partial \xi} \left( J \sigma_{ix} \right) + \frac{\partial}{\partial \eta} \left( J\alpha\, \sigma_{ix} + \sigma_{iz} \right), \qquad \frac{\partial \sigma_{ij}}{\partial t} = \lambda\, \delta_{ij}\, \partial_k v_k + \mu \left( \partial_i v_j + \partial_j v_i \right), \]

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}\):

\[ \frac{\partial \boldsymbol{\sigma}}{\partial t} = \frac{4\mu (\lambda + \mu)}{\lambda + 2\mu}\, \dot{\varepsilon}_{tt}\, \mathbf{t}\mathbf{t}^{\mathsf{T}}, \]

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

AcousticCurvilinear(spatial_order=4, device='cpu', backend='torch', dim=2)

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

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.

set_curvilinear_metrics

set_curvilinear_metrics(alpha, metric_pηη, metric_pη, d_eta)

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

source_receiver_stencil

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.

surface_row property

surface_row

Index of the free-surface row in the padded runtime array.

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.

cfl_limit

cfl_limit(max_velocity)

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

set_curvilinear_metrics(alpha, metric_pηη, metric_pη, d_eta)

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\),

\[ \mathbf{R} = \frac{1}{2Z} \nabla Z = \frac{1}{2} \nabla \ln 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

\[ \frac{\partial^2 p}{\partial t^2} = v_p^2 \nabla^2 p + \left( v_p \nabla v_p - 2 v_p^2\, \mathbf{r} \right) \cdot \nabla p , \]

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:

\[ \frac{\partial p_i}{\partial t} = \frac{\partial \sigma_{ij}}{\partial x_j} . \]

For each wave type \(\alpha \in \{P, S\}\) the code forms

\[ \Gamma^{\alpha}_{ij} = V_\alpha \left( \partial_i V_\alpha \right) p_j - 2 V_\alpha^2 R_{\alpha,i}\, p_j + V_\alpha^2\, \partial_i p_j , \]

and updates the stresses as

\[ \frac{\partial \sigma_{xx}}{\partial t} = \Gamma^{P}_{xx} + \Gamma^{P}_{zz} - 2\Gamma^{S}_{zz}, \qquad \frac{\partial \sigma_{zz}}{\partial t} = \Gamma^{P}_{xx} + \Gamma^{P}_{zz} - 2\Gamma^{S}_{xx}, \qquad \frac{\partial \sigma_{xz}}{\partial t} = \Gamma^{S}_{xz} + \Gamma^{S}_{zx} . \]

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

AcousticVRR(spatial_order=4, device='cpu', backend='torch', dim=2)

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·∇p terms. Defaults to 4.

  • device –

    Device for the operator's static gradient kernels. Use 'cuda' / a torch.device for GPU runs. Defaults to 'cpu'.

  • backend –

    Array / programming backend, 'torch' or 'jax'. Defaults to 'torch'.

  • dim –

    Stored dimensionality. Always 2 for this class. Defaults to 2.

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.

sweep.equations.ElasticVRR

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

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

C_NAME = 'elastic_vr2d'

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

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 :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

prepare_models(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'

equation_class staticmethod

equation_class(*, method: str = 'duveneck', symmetry: str = 'vti', ndim: int = 2)

Return the equation class (not instance) for the given keys.

supported staticmethod

supported()

Return a list of supported (method, symmetry, ndim) triples.

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

AcousticVTI(
    spatial_order=4, device="cpu", backend="torch", dim=2, s_gradient="adjoint"
)

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=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, …). 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' / a torch.device for GPU eager runs. Defaults to 'cpu'.

  • backend –

    Array / programming backend, 'torch' or 'jax'. Defaults to 'torch'.

  • dim –

    Stored dimensionality. Always 2 for 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

C_HAS_RECURSIVE_CKPT = False

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

C_NAME = 'qp_vti2d'

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

supports_boundary_saving_eager = False

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

supports_free_surface = False

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

check_stability(models, dt, spacing)

Warn once when dt breaks the scheme's stability condition (:func:qp_stability_ratio); PropTorch calls it before every forward.

sweep.equations.AcousticTTI

AcousticTTI(
    spatial_order=4, device="cpu", backend="torch", dim=2, s_gradient="adjoint"
)

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=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, …). 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' / a torch.device for 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 2 for this class. Defaults to 2.

  • s_gradient –

    'adjoint', 'frozen' or 'exact' (see :class:AcousticVTI). Defaults to 'adjoint'.

C_HAS_RECURSIVE_CKPT class-attribute

C_HAS_RECURSIVE_CKPT = False

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

C_NAME = 'qp_tti2d'

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

supports_boundary_saving_eager = False

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

supports_free_surface = False

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

check_stability(models, dt, spacing)

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

AcousticVTIBorn(
    spatial_order=4, device="cpu", backend="torch", dim=2, s_gradient="adjoint"
)

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

C_NAME = 'qp_vti_born2d'

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

AcousticTTIBorn(
    spatial_order=4, device="cpu", backend="torch", dim=2, s_gradient="adjoint"
)

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

C_NAME = 'qp_tti_born2d'

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\):

\[ \frac{\partial^2 p}{\partial t^2} = (1 + 2\eta)\, v^2 \frac{\partial^2 p}{\partial x^2} + v_v^2 \frac{\partial^2 p}{\partial z^2} - 2\eta\, v^2 v_v^2 \frac{\partial^4 F}{\partial x^2 \partial z^2}, \qquad \frac{\partial^2 F}{\partial t^2} = p . \]

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

AcousticTariq(spatial_order=4, device='cpu', backend='torch', dim=2)

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=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, …). This equation has no compiled impl='c' path; use impl='eager' (the default). Defaults to 4.

  • device –

    Device for the operator's static kernels. Use 'cuda' / a torch.device for GPU eager runs. Defaults to 'cpu'.

  • backend –

    Array / programming backend, 'torch' or 'jax'. Defaults to 'torch'.

  • dim –

    Stored dimensionality. Always 2 for this class. Defaults to 2.

supports_free_surface class-attribute

supports_free_surface = False

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.

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):

\[ \rho \frac{\partial v_x}{\partial t} = \frac{\partial \sigma_H}{\partial x}, \qquad \rho \frac{\partial v_z}{\partial t} = \frac{\partial \sigma_V}{\partial z}, \]
\[ \frac{\partial \sigma_H}{\partial t} = c_{11} \frac{\partial v_x}{\partial x} + c_{13} \frac{\partial v_z}{\partial z}, \qquad \frac{\partial \sigma_V}{\partial t} = c_{13} \frac{\partial v_x}{\partial x} + c_{33} \frac{\partial v_z}{\partial z}, \]

with

\[ c_{11} = \rho v_p^2 (1 + 2\varepsilon), \qquad c_{33} = \rho v_p^2, \qquad c_{13} = \rho v_p^2 \sqrt{1 + 2\delta}, \]

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

AcousticVTI1st(spatial_order=4, device='cpu', backend='torch', free_surface=False)

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=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, …). Performance note (impl='c' on CUDA): the compiled kernels ship template specialisations only for spatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1 in src/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' / 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'.

  • 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 = 0 constraint couples d(vz)/dz to d(vx)/dx via the off-diagonal stiffness c13 (Robertsson 1996; Mittet 2002). Passing True raises NotImplementedError; use absorbing PML on all four sides instead. Defaults to False.

C_NAME class-attribute

C_NAME = 'acoustic_vti_1st_2d'

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_layout

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

supports_free_surface = False

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.

prepare_models

prepare_models(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

recommended_dt(vp_max, epsilon_max, h, cfl=0.5)

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

AcousticVTI1st3D(spatial_order=4, device='cpu', backend='torch', free_surface=False)

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=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, …). Performance note (impl='c' on CUDA): the compiled kernels ship template specialisations only for spatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1 in src/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' / 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'.

  • 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). Passing True raises NotImplementedError. Defaults to False.

C_NAME class-attribute

C_NAME = 'acoustic_vti_1st_3d'

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_layout

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

supports_free_surface = False

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.

prepare_models

prepare_models(models)

Pre-compute stiffness coefficients (identical logic to 2-D).

See AcousticVTI1st.prepare_models for details.

recommended_dt classmethod

recommended_dt(vp_max, epsilon_max, h, cfl=0.5)

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.py without 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.