Skip to content

Equations

This page summarizes the available equation classes and the model parameters they expect. The goal is to make it easy to answer three practical questions:

  • Which physical system does this equation represent?
  • Which model tensors must be provided, and in what order?
  • Which dimensions/backends does it support?

Summary Table

Equations are grouped by physics family. The impl="c" column reflects whether compiled CUDA kernels exist in the shipped core; the eager path (impl="eager") is supported for every class.

Acoustic family

Equation Models Dim Notes impl="c"
Acoustic ['vp'] 2D Second-order acoustic wave equation with CPML ✅
Acoustic3D ['vp'] 3D 3D counterpart of Acoustic ✅
Acoustic1st ['vp', 'rho'] 2D First-order velocity-pressure formulation ❌
ViscoAcoustic ['vp', 'Q', 'omega'] 2D Nearly constant-Q attenuation (Zhu & Harris 2014); decoupled dispersion / damping switches ✅
AcousticVRZ ['vp', 'z'] 2D Variable-density acoustic, impedance-style parameterization (z = impedance) ✅
AcousticVRZ3D ['vp', 'z'] 3D 3D counterpart of AcousticVRZ ✅
AcousticBorn ['vp', 'mp'] 2D LSRTM-oriented variant (mp = reflectivity perturbation) ✅
AcousticBorn3D ['vp', 'mp'] 3D 3D counterpart of AcousticBorn ✅
AcousticVRR ['vp', 'rx', 'rz'] 2D Variable-density acoustic in vector-reflectivity form (rx, rz first-derivative density parameters) ❌
AcousticCurvilinear ['vp'] 2D Acoustic on a curvilinear grid for irregular topography (topography=); eager only ❌

Anisotropic acoustic family

Equation Models Dim Notes impl="c"
AcousticAniso varies (see facade) 2D / 3D Unified facade — method= picks duveneck / liang / alkhalifah; mirrors the DAS facade varies
AcousticVTI ['vp', 'epsilon', 'delta'] 2D Pure qP VTI, new acoustic approximation (Liang K. et al. 2023) — aliases AcousticVTILiang / AcousticVTIDefault; s_gradient= picks the adjoint (forward, adjoint and Born) ✅ full / bs
AcousticTTI ['vp', 'epsilon', 'delta', 'theta'] 2D Pure qP TTI (Liang K. et al. 2023, appendix A) — alias AcousticTTILiang ✅ full / bs
AcousticVTIBorn ['vp', 'epsilon', 'delta', 'mp'] 2D Born / LSRTM pair of AcousticVTI (background h1, scattered sh1, reflectivity mp) ✅ full / bs, mp gradient
AcousticTTIBorn ['vp', 'epsilon', 'delta', 'theta', 'mp'] 2D Born / LSRTM pair of AcousticTTI ✅ full / bs, mp gradient
AcousticTariq ['vv', 'v', 'eta'] 2D qP η-formulation, Alkhalifah 2000 — alias AcousticVTIAlkhalifah; VTI only ❌
AcousticVTI1st ['vp', 'epsilon', 'delta', 'rho'] 2D 1st-order velocity-stress, Duveneck et al. 2008 — alias AcousticVTIDuveneck ✅
AcousticVTI1st3D ['vp', 'epsilon', 'delta', 'rho'] 3D 3D counterpart of AcousticVTI1st — aliases AcousticVTIDuveneck3D / AcousticVTIDefault3D ✅

Elastic family

Equation Models Dim Notes impl="c"
Elastic ['vp', 'vs', 'rho'] 2D Velocity-stress elastic propagation (Virieux 1986) ✅
Elastic3D ['vp', 'vs', 'rho'] 3D 3D counterpart of Elastic ✅
ElasticBorn ['vp', 'vs', 'rho', 'dvp', 'dvs', 'drho'] 2D Born modelling of Elastic (background + scattered field), elastic LSRTM / RWI ✅
ElasticCurvilinear ['vp', 'vs', 'rho'] 2D Elastic on a curvilinear grid for irregular topography (topography=); eager only ❌
ElasticVRR ['vp', 'vs', 'Rp_x', 'Rp_z', 'Rs_x', 'Rs_z'] 2D Vector-reflectivity elastic (Soares & Sacchi 2025), momentum-stress form, no density model ✅
ViscoElastic ['vp', 'vs', 'rho', 'Qp', 'Qs'] 2D Nearly constant-Q visco-elastic, generalized standard linear solid (as SPECFEM2D); vp/vs given at f_ref, all five models differentiable ✅
ElasticTTI ['vp0', 'vs0', 'rho', 'epsilon', 'delta', 'gamma', 'theta', 'phi'] 2D Rotated-staggered-grid elastic TTI ❌
ElasticTTISG ['vp0', 'vs0', 'rho', 'epsilon', 'delta', 'gamma', 'theta', 'phi'] 2D Standard-staggered-grid elastic TTI ✅
ElasticTTISG3D ['vp0', 'vs0', 'rho', 'epsilon', 'delta', 'gamma', 'theta', 'phi'] 3D Standard-staggered-grid elastic TTI ✅
ElasticTTI2nd ['vh', 'vs', 'rho', 'epsilon', 'eta', 'theta'] 2D Displacement-based elastic TTI (Oh et al. 2020) ✅

Poroelastic

Equation Models Dim Notes impl="c"
Biot ['H', 'mu', 'C', 'M', 'rho', 'rho_f', 'm', 'b'] 2D Low-frequency Biot poroelasticity: solid velocity, Darcy flux, total stress and pore pressure; exact viscous drag, open-pore free surface; build the coefficients with biot_from_rock; eager only ❌

Distributed Acoustic Sensing (DAS) family

All DAS classes take elastic models — ['vp', 'vs', 'rho'] — and read out strain or strain-rate at the receivers; the choice of formulation only changes the receiver-side discretisation.

Equation Models Dim Notes impl="c"
DAS ['vp', 'vs', 'rho'] 2D / 3D Unified facade — method= picks zhao / mu (formerly DASModeler) ✅
DASZhao / DASZhao3D ['vp', 'vs', 'rho'] 2D / 3D Zhao-style DAS formulation ✅
DASMu / DASMu3D ['vp', 'vs', 'rho'] 2D / 3D Mu & Hung (2022) velocity-stress formulation with integrated strain ✅
DASElastic / DASElastic3D ['vp', 'vs', 'rho'] 2D / 3D Elastic DAS variant (alias of DASZhao / DASZhao3D) ✅

SEM family (spectral elements)

The spectral-element classes live in sweep.sem.equations and are driven by PropSEM rather than PropTorch; models are the same grid tensors (vp in m/s, etc.) — PropSEM interpolates them onto the GLL nodes. Deformed means the Quad9 / Hex27 curved-mesh variant: it carries surface topography and is the one to pick whenever the mesh is not a flat box (the flat Quad4 / Hex8 forms trade that for a cheaper constant-Jacobian stencil). The impl="c" column says whether PropSEM(impl='c') can route the class to the CUDA kernels; every class runs on impl="eager". The BoundarySaving() column is the CUDA-side coverage of boundary saving -- on impl="eager" it works for every class but the dissipative ones (Biot, visco-elastic, visco-acoustic); ✅ = both backends, "eager" = eager only (impl=None runs those on eager with BoundarySaving()), and the C-PML is required wherever the ring IS the C-PML band.

Equation Models Mesh Dim Notes impl="c" BoundarySaving()
AcousticPotentialSEM2D ['vp'] quad9 2D Potential form (SPECFEM), the density from density=; the FWI workhorse — shot batching, per-shot models and batched boundary saving live here ✅ ✅ (C-PML; fp32/bf16/int8; batched)
AcousticSEM2D ['vp'] quad4 2D Constant-density displacement form, flat mesh ❌ eager
AcousticSEM2DDeformed ['vp'] quad9 2D Topography-capable variant of AcousticSEM2D ❌ eager
AcousticSEM3D ['vp'] hex8 3D 3-D acoustic, flat mesh ✅ ✅ (fp32/bf16/int8)
AcousticSEM3DDeformed ['vp'] hex27 3D 3-D acoustic with topography ✅ ✅ (fp32/bf16/int8)
ElasticSEM2D ['vp', 'vs', 'rho'] quad4 2D 2nd-order displacement (Newmark), flat; no C-PML — superseded by the Deformed form ❌ eager
ElasticSEM2DDeformed ['vp', 'vs', 'rho'] quad9 2D SPECFEM2D-style displacement elastic: topography + C-PML ✅ ✅ (C-PML; fp32)
ElasticSEM3D ['vp', 'vs', 'rho'] hex8 3D 3-D displacement elastic; no C-PML (3-D displacement C-PML is not modelled) ✅ eager
ElasticSEM3DDeformed ['vp', 'vs', 'rho'] hex27 3D 3-D displacement elastic with topography; no C-PML ✅ eager
ElasticVSSEM2DDeformed ['vp', 'vs', 'rho'] quad9 2D 1st-order velocity–stress elastic: topography + C-PML ✅ eager
ElasticSHSEM2DDeformed ['vs', 'rho'] quad9 2D SH waves (u_y, SPECFEM2D's P_SV = .false.): the potential form's operators, traction-free surface, topography + C-PML; records u_y, vy ❌ eager
ElasticVSSEM3D ['vp', 'vs', 'rho'] hex8 3D 3-D velocity–stress elastic with C-PML, flat mesh ✅ eager
ElasticVSSEM3DDeformed ['vp', 'vs', 'rho'] hex27 3D 3-D elastic with both topography and absorbing boundaries (the velocity–stress family is where 3-D C-PML exists) ✅ eager
ElasticVTISEM2DDeformed ['vp', 'vs', 'rho', 'epsilon', 'delta'] quad9 2D VTI anisotropic velocity–stress: topography + C-PML ✅ eager
ElasticTTISEM2DDeformed ['vp', 'vs', 'rho', 'epsilon', 'delta', 'theta'] quad9 2D TTI: the VTI medium with its symmetry axis tilted by theta (radians, the FD ElasticTTI2nd's tilt): topography + C-PML ✅ eager
ElasticVTISEM3D ['vp', 'vs', 'rho', 'epsilon', 'delta', 'gamma'] hex8 3D VTI velocity–stress in 3-D (Thomsen epsilon, delta, gamma): C-PML, flat mesh ✅ eager
ElasticVTISEM3DDeformed ['vp', 'vs', 'rho', 'epsilon', 'delta', 'gamma'] hex27 3D VTI in 3-D with topography + C-PML ✅ eager
ElasticTTISEM3D ['vp', 'vs', 'rho', 'epsilon', 'delta', 'gamma', 'theta', 'phi'] hex8 3D TTI in 3-D: the axis tilted by theta toward the azimuth phi (radians), all 21 stiffnesses (the FD ElasticTTISG3D's parameters and rotation): C-PML, flat mesh ✅ eager
ElasticTTISEM3DDeformed ['vp', 'vs', 'rho', 'epsilon', 'delta', 'gamma', 'theta', 'phi'] hex27 3D TTI in 3-D with topography + C-PML ✅ eager
ViscoElasticVSSEM2DDeformed ['vp', 'vs', 'rho', 'Qp', 'Qs'] quad9 2D Visco-elastic velocity–stress, the GSLS of the FD ViscoElastic and of SPECFEM2D (vp, vs at f_ref): topography + C-PML; f_ref, f_band, n_sls through equation_options ✅ ❌ (dissipative)
ViscoElasticVSSEM3D ['vp', 'vs', 'rho', 'Qp', 'Qs'] hex8 3D Visco-elastic velocity–stress in 3-D, the 2-D class's GSLS on ElasticVSSEM3D: C-PML, flat mesh ✅ ❌ (dissipative)
ViscoElasticVSSEM3DDeformed ['vp', 'vs', 'rho', 'Qp', 'Qs'] hex27 3D Visco-elastic velocity–stress in 3-D with topography + C-PML (ElasticVSSEM3DDeformed's geometry) ✅ ❌ (dissipative)
ViscoElasticSEM2DDeformed ['vp', 'vs', 'rho', 'Qk', 'Qmu'] quad9 2D Visco-elastic displacement form: SPECFEM2D's ATTENUATION_VISCOELASTIC (element memories, Newmark update; Qkappa, Qmu; its defaults, vp, vs unrelaxed): topography + C-PML (no attenuation in the layer); f_ref, f_band, n_sls, n_fit, velocities through equation_options ❌ ❌ (dissipative)
ViscoAcousticPotentialSEM2D ['vp', 'Qk'] quad9 2D Visco-acoustic potential form: SPECFEM2D's ATTENUATION_VISCOACOUSTIC (weak form, node memories), the density from density=; f_ref, f_band, n_sls, n_fit, velocities through equation_options ❌ ❌ (dissipative)
AcousticElasticSEM2D ['vp', 'vs', 'rho'] quad9 2D Coupled fluid–solid (ocean over seabed): split acoustic + elastic C-PML, records p, vx, vz by default under PropSEM (also chi, u_x, u_z) ✅ ✅ (C-PML; fp32; +anchors)
BiotVSSEM2DDeformed ['H', 'mu', 'C', 'M', 'rho', 'rho_f', 'm', 'b'] quad9 2D Biot poroelastic velocity–stress with Darcy flux, the FD Biot's equations and names (pore pressure continuous, flux element-local): topography + C-PML, open-pore surface, fluid (rho = 0) and dry elastic (M = 0) regions, viscous attenuation (viscous_q), records vx, vz, p, qx, qz, sxx, szz, sxz ✅ ❌ (dissipative)
BiotAnisoPermSEM2DDeformed ['H', 'mu', 'C', 'M', 'rho', 'rho_f', 'm', 'b_xx', 'b_xz', 'b_zz'] quad9 2D BiotVSSEM2DDeformed with an anisotropic permeability (drag tensor) ✅ ❌ (dissipative)
ViscoBiotVSSEM2DDeformed ['H', 'mu', 'C', 'M', 'rho', 'rho_f', 'm', 'b', 'Qp', 'Qs'] quad9 2D BiotVSSEM2DDeformed with a GSLS frame: Qp on the drained P modulus, Qs on the shear modulus ✅ ❌ (dissipative)
BiotVSSEM3DDeformed ['H', 'mu', 'C', 'M', 'rho', 'rho_f', 'm', 'b'] hex27 3D BiotVSSEM2DDeformed in 3-D: topography + C-PML, open-pore surface, fluid and dry elastic regions (water over an elastic rock: SPECFEM3D's acoustic-elastic coupling to round-off), viscous attenuation (viscous_q), an isotropic drag; moment-tensor sources sxx ... syz ✅ ❌ (dissipative)

For the authoritative list of equations exported by your installation, with their models and compiled-binding support, use the CLI:

sweep list equations

It lists the SEM classes after the finite-difference ones, and sweep show <Class> prints one class's fields, source and receiver types and models (see CLI). The SEM API is in the SEM reference.

Or from Python:

from sweep.equations import equation_classes, torch_binding_supported_equations

print(sorted(equation_classes().keys()))
print(torch_binding_supported_equations())

Five SEM classes additionally run multi-GPU model decomposition on impl='c' (x strips; the 3-D cut is a YZ plane) — AcousticPotentialSEM2D, ElasticSEM2DDeformed, AcousticElasticSEM2D, AcousticSEM3D and AcousticSEM3DDeformed; the first two also compose it with boundary saving. See Domain decomposition. The whitelist is exact, so any other class, a subclass of one of these included, raises rather than falling through to a sibling's path.

The SEM registry has its own one-liner — mesh family, topography and C-PML support, field counts and receiver components for every class:

import sweep.sem.equations
print(sweep.sem.equations.describe())

Acoustic

What It Represents

Acoustic implements the second-order acoustic wave equation with CPML absorbing boundaries. In the PyTorch path it is usually the default choice for scalar wave propagation, forward modeling, and acoustic FWI examples.

Implementation:

Constructor

from sweep.equations import Acoustic

eq = Acoustic(
    spatial_order=4,
    device="cuda",
    backend="torch",
)

Main constructor arguments:

  • spatial_order: finite-difference order. Must be even. Common values are 4 and 8.
  • device: target device for operator/kernel tensors, such as "cpu" or "cuda".
  • backend: usually "torch" or "jax".
  • dim: defaults to 2 for Acoustic.

Required Models

Acoustic.models returns:

['vp']

You must therefore provide one model tensor, in this order:

  • vp: P-wave velocity model

Wavefields

Acoustic.wavefields returns:

['h1', 'h2', 'psix', 'psiz', 'zetax', 'zetaz']

Roughly:

  • h1, h2: main second-order wavefield states
  • psix, psiz, zetax, zetaz: CPML auxiliary states

Dimensions and Variants

  • Acoustic: 2D acoustic equation
  • Acoustic3D: 3D counterpart
  • AcousticVRZ: acoustic variant with impedance-like parameterization
  • AcousticBorn: acoustic LSRTM-oriented variant

Supported Backends

Acoustic is commonly used with:

  • backend="torch": pure PyTorch propagation and autograd
  • backend="jax": JAX propagation and differentiation

Torch Binding Support

Acoustic ships compiled CUDA kernels in the core (C_NAME = "acoustic2d").

That means:

  • equation-level torch binding support: yes
  • runtime availability depends on a visible CUDA GPU and a fitting core (sweep.backend.torch.binding.is_available()), not on importing sweep._C, which always succeeds

You can inspect this from the CLI:

sweep list equations

Or from Python:

import sweep

print(sweep.backend.torch.binding.is_available())

Notes

  • In the current PyTorch implementation, the acoustic path uses separable Laplace operators and, on CUDA, fixed-stencil gradient kernels where available.

Inspecting available sources and receivers

Every equation class carries a structured FIELD_SPECS table that lists, for each wavefield it tracks, whether the user is allowed to inject a source there or place a receiver there. The propagator reads this when you pass source_type= / receiver_type=; you can query it yourself the same way.

from sweep.equations import Acoustic, Elastic, DASZhao

eq = Acoustic(device="cuda")
eq.default_source_fields            # ['h1']
eq.default_receiver_fields          # ['h1']
eq.available_source_fields()        # [FieldSpec(name='h1', aliases=('pressure','p'), ...)]
eq.describe_field("pressure")       # 'h1: ... Aliases: pressure, p.'  (aliases are accepted too)

Elastic(device="cuda").available_receiver_fields()
# → [vx, vz, sxx, szz]    (FieldSpec list; supports_receiver=True on each)

DASZhao(device="cuda").available_receiver_fields()
# → [exx_t, ezz_t, sxx, szz, das35_t, das54x_t, das54z_t]
#   — DAS exposes helical-fiber strain-rate readouts on top of the elastic basics

Each FieldSpec carries name, aliases, description, supports_source, supports_receiver, and internal flags — so an IDE / notebook can autocomplete through them without having to read the source. A handful of equations also have default_source_fields / default_receiver_fields populated, which is what PropTorch falls back to when source_type= / receiver_type= are omitted on the propagator.

If the default for an equation doesn't suit your survey (e.g. you want to inject on sxx + szz + sxz in Elastic instead of just sxx + szz), pass an explicit list:

solver = PropTorch(
    Elastic(device=dev),
    shape=shape, dh=dh, dt=dt, device=dev,
    source_type=["sxx", "szz", "sxz"],     # explicit override
    receiver_type=["vz"],
)

Adding your own equation

The equation classes above are plug-in units. The propagator owns the time loop and PML wiring, so a new equation is one Python file (eager) plus an optional CUDA equation directory and five entries in the core's C API table (csrc/core/capi.h, csrc/cuda/common/capi.cu) (impl="c"). Registration is a decorator plus an import: @register_equation() on the class claims its public name, and importing the module in src/sweep/equations/__init__.py is what makes the decorator run. Both are needed before it appears in sweep list equations or equation_classes().

Two entry points:

See Also

  • API Reference — full API for every equation class, including Acoustic, Elastic, and the 3D / VRZ / LSRTM variants.
  • Backends — choosing between torch and jax, and between impl="eager" and impl="c".
  • Propagators — wiring an equation into PropTorch or PropJax.
  • Pure-qP VTI / TTI — the forward, adjoint and Born equations of AcousticVTI / AcousticTTI.
  • Extending — adding a new equation class (reference) and the companion notebook (runnable walkthrough).