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:
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:
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:
AcousticAPI page- Source on GitHub:
src/sweep/equations/acoustic.py
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 are4and8.device: target device for operator/kernel tensors, such as"cpu"or"cuda".backend: usually"torch"or"jax".dim: defaults to2forAcoustic.
Required Models¶
Acoustic.models returns:
You must therefore provide one model tensor, in this order:
vp: P-wave velocity model
Wavefields¶
Acoustic.wavefields returns:
Roughly:
h1,h2: main second-order wavefield statespsix,psiz,zetax,zetaz: CPML auxiliary states
Dimensions and Variants¶
Acoustic: 2D acoustic equationAcoustic3D: 3D counterpartAcousticVRZ: acoustic variant with impedance-like parameterizationAcousticBorn: acoustic LSRTM-oriented variant
Supported Backends¶
Acoustic is commonly used with:
backend="torch": pure PyTorch propagation and autogradbackend="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 importingsweep._C, which always succeeds
You can inspect this from the CLI:
Or from Python:
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:
- Extending: Adding a New Equation — the reference: the
interface contract, the
CUDALayoutSpecfield table, and the C++ registration pattern. - Add a new equation notebook
— a runnable walkthrough that builds and runs a toy
MyScalaragainstPropTorchend-to-end.
See Also¶
- API Reference — full API for every equation class, including
Acoustic,Elastic, and the 3D / VRZ / LSRTM variants. - Backends — choosing between
torchandjax, and betweenimpl="eager"andimpl="c". - Propagators — wiring an equation into
PropTorchorPropJax. - 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).