Skip to content

Equations

This section documents the equation classes in sweep.equations.

Overview

An equation defines:

  • the physical model parameters required by the solver
  • the wavefields carried during propagation
  • the user-facing source and receiver field choices
  • the numerical update rule used by the propagator
  • whether it has CUDA-core bindings (impl='c': C_NAME declared, supports_torch_binding() True)

Shared Equation Interface

Every equation exposes:

  • models: ordered model names required by solver(..., models=[...])
  • wavefields: full internal wavefield list, including auxiliary and CPML fields

Most user-facing equations now also expose structured metadata through FieldSpec and ModelSpec, plus helper methods on the base WaveEquation.

Field metadata helpers:

  • available_fields()
  • available_fields(role="source")
  • available_fields(role="receiver")
  • describe_field(name)
  • default_source_fields
  • default_receiver_fields

Model metadata helpers:

  • available_models()
  • describe_model(name)

available_fields() is the recommended way to discover what users should pass into source_type and receiver_type. By default it filters out internal and boundary-related fields such as CPML memory variables.

available_models() is the recommended way to discover the expected model order for solver(..., models=[...]).

Metadata Types

  • FieldSpec Describes one wavefield entry. It carries the canonical name, aliases, description, source/receiver support flags, and whether the field is internal or boundary-related.
  • ModelSpec Describes one model parameter. It carries the canonical name, aliases, description, units, and whether the parameter is required.

Ordering Semantics

Field and model metadata are not just documentation.

  • FieldSpec order is semantically significant. The propagators map source and receiver names to positional wavefield indices, and equation step functions are expected to return tensors in the same order.
  • ModelSpec order defines the required order of solver(..., models=[...]). If an equation lists ["vp", "vs", "rho"], then the runtime model list must follow the same order.

For equations with CUDA-core bindings, runtime buffer metadata is now grouped under:

  • cuda_layout

This replaces the older pattern of scattering core-specific scalar properties through the equation class.

Note

In equation constructors, the backend argument refers to the tensor and operator backend, not the propagator implementation. For the compiled c implementation, the equation backend should still normally be "torch", not "cuda".

API Tabs

class Acoustic(
    spatial_order=4,
    device="cpu",
    backend="torch",
    dim=2,
)

Second-order 2D acoustic equation with CPML-compatible auxiliary fields.

See Acoustic for parameter meanings.

class Acoustic3D(
    spatial_order=4,
    device="cpu",
    backend="torch",
    dim=3,
)

Second-order 3D acoustic equation.

See Acoustic3D for parameter meanings.

class Elastic(
    spatial_order=4,
    device="cpu",
    backend="torch",
)

First-order 2D elastic velocity-stress equation.

See Elastic for parameter meanings.

class Elastic3D(
    spatial_order=4,
    device="cpu",
    backend="torch",
)

First-order 3D elastic velocity-stress equation.

See Elastic3D for parameter meanings.

class ElasticTTI(
    spatial_order=8,
    device="cpu",
    backend="torch",
    checkerboard_smoothing=True,
)

First-order 2-D three-component TTI elastic equation on a rotated staggered grid (RSG); eager-only.

See ElasticTTI for parameter meanings.

class ElasticTTISG(
    spatial_order=8,
    device="cpu",
    backend="torch",
)

First-order 2-D three-component TTI elastic equation on an axis-aligned staggered grid; supports the CUDA core (impl='c').

See ElasticTTISG for parameter meanings; the 3-D variant is ElasticTTISG3D (axis-aligned SG, 21 Bond-rotated stiffness entries, full/bs/ckpt CUDA backward).

from sweep.equations import (
    DAS,                            # unified facade (was DASModeler)
    DASElastic, DASElastic3D,       # aliases of DASZhao / DASZhao3D
    DASMu, DASMu3D,
    DASZhao, DASZhao3D,
)

Strain-rate / helical-fiber receiver equations for DAS modelling. The four raw equation classes (DASZhao / DASZhao3D, DASMu / DASMu3D) share ['vp', 'vs', 'rho'] and have CUDA-core bindings; DASElastic / DASElastic3D are aliases of DASZhao / DASZhao3D. DAS is the unified facade — pass method="zhao" or method="mu" to pick a variant.

See DAS family for the API and the DAS table in the user guide for a comparison.

Equation Pages

The following pages document constructor parameters, required models, wavefields, and backend / binding behavior:

Acoustic family

Elastic family

DAS family

  • DAS family overview — covers DAS (the unified facade, formerly named DASModeler), plus the raw equation classes DASZhao / DASZhao3D and DASMu / DASMu3D (DASElastic / DASElastic3D are aliases of DASZhao / DASZhao3D).

Other equations

  • Other equations — curvilinear-grid topography (AcousticCurvilinear, ElasticCurvilinear; eager-only), vector reflectivity (AcousticVRR, ElasticVRR), and the anisotropic acoustic classes below with the AcousticAniso factory.

Anisotropic acoustic family

The raw equation classes (API on Other equations) are:

Class Symmetry Dim Reference
AcousticVTI VTI 2D Liang K. et al. 2022 (2nd-order pseudo-acoustic)
AcousticTTI TTI 2D Liang K. et al. 2022 (TTI extension)
AcousticTariq VTI / TTI 2D Alkhalifah 2000 (qP η-formulation)
AcousticVTI1st / AcousticVTI1st3D VTI 2D / 3D Duveneck et al. 2008 (1st-order velocity-stress)

AcousticAniso is a thin factory that dispatches by (method, symmetry, ndim) and returns one of the above instances; it does not wrap a solver. The user constructs PropTorch separately:

from sweep.equations import AcousticAniso
from sweep.propagator.torch import PropTorch

eq = AcousticAniso(method="duveneck", symmetry="vti", ndim=2)
prop = PropTorch(eq, shape=(nz, nx), source_type=["sH", "sV"],
                 receiver_type=["vz"], dh=10.0, dt=1e-3, abcn=30)
record = prop(wavelet, sources, receivers, models=[vp, eps, delta, rho])

Author-named aliases also exist for the raw classes: AcousticVTILiang, AcousticTTILiang, AcousticVTIAlkhalifah, AcousticTTIAlkhalifah, AcousticVTIDuveneck, AcousticVTIDuveneck3D. Use sweep show <ClassName> from the CLI to inspect any of them; the CLI page has a full output example.