Skip to content

DAS family

Distributed Acoustic Sensing equations — strain / strain-rate forward operators for fiber-optic cable measurements. There are two formulations, each in 2D and 3D: Zhao (DASZhao / DASZhao3D, stress / normal-strain-rate) and Mu (DASMu / DASMu3D, velocity-stress plus integrated strain). The DAS facade runs either one (method="zhao" or method="mu"; 2D or 3D from shape). DASElastic / DASElastic3D are aliases of DASZhao / DASZhao3D, and DASModeler is the former name of DAS.

Facade

sweep.equations.DAS 

DAS(
    *,
    shape,
    method: str = "zhao",
    ndim: int | None = None,
    spatial_order: int = 4,
    source_type: Sequence[str] | None = None,
    receiver_type: Sequence[str] | None = None,
    gauge_cells: int | None = None,
    gauge_length: float | None = None,
    gauge_axis: int = -1,
    backend: str = "torch",
    impl: str | None = None,
    backend_options=None,
    eager_options=None,
    cuda_options=None,
    **propagator_kwargs
)

Bases: torch.nn.modules.module.Module

Unified Torch DAS (distributed acoustic sensing) modeling interface.

Facade nn.Module that wires one of the underlying DAS equations to a :class:PropTorch propagator and post-processes records into a uniform (batch, nt, nrec, nfield) layout. Two methods:

  • method="zhao" — runs the Zhao (2022) stress / normal-strain-rate equation (:class:DASZhao / :class:DASZhao3D); receivers are strain-rates already, no time differentiation needed.
  • method="mu" — runs the Mu (Mu & Hung 2022) velocity-stress equation augmented with integrated strain (:class:DASMu / :class:DASMu3D); strain-rate (exx_t etc.) and helical DAS receivers (das35_t, das54x_t, …) are derived by numerical time differentiation after the solve, which requires dt to be passed through propagator_kwargs.

Reference: Zhao Y. et al. 2022 (DAS strain-rate equation); Mu & Hung 2022 (velocity-stress-strain coupling).

Note

This class used to be called DASModeler; the shorter name mirrors the DAS field convention and matches the :class:AcousticAniso facade for anisotropic acoustic equations. DASModeler is kept as a back-compat alias at the bottom of this module.

Build the DAS facade.

Parameters:

  • shape –

    Spatial model shape (nz, nx) for 2-D or (nz, ny, nx) for 3-D.

  • method (str, default: 'zhao' ) –

    DAS formulation. One of 'zhao' (stress / normal-strain-rate, :class:DASZhao / :class:DASZhao3D) or 'mu' (velocity-stress + integrated strain, :class:DASMu / :class:DASMu3D). Defaults to 'zhao'.

  • ndim (int | None, default: None ) –

    Spatial dimensionality (2 or 3). Inferred from len(shape) when None. Defaults to None.

  • spatial_order (int, default: 4 ) –

    FD accuracy order — 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). Even integer. Defaults to 4.

  • source_type (Sequence[str] | None, default: None ) –

    Names of fields injected by the source. Defaults to the underlying equation's default_source_fields.

  • receiver_type (Sequence[str] | None, default: None ) –

    Names of receiver fields to extract. Mu can emit strain-rate (exx_t, ezz_t, …) and helical DAS-rate channels (das35_t, das54x_t, das54y_t, das54z_t); these require dt. Defaults to the underlying equation's default_receiver_fields.

  • gauge_cells (int | None, default: None ) –

    Gauge length in number of cells along the fibre axis for helical-fibre averaging. Mutually exclusive with gauge_length. Defaults to None (no averaging).

  • gauge_length (float | None, default: None ) –

    Gauge length in metres along the fibre axis; converted to cells using the propagator's dh. Defaults to None.

  • gauge_axis (int, default: -1 ) –

    Axis along which the gauge moving-average is applied. Defaults to -1.

  • backend (str, default: 'torch' ) –

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

  • impl (str | None, default: None ) –

    Propagator implementation. 'eager' for the PyTorch / JAX time loop, 'c' for the compiled CUDA kernel. Defaults to None (propagator decides).

  • backend_options –

    Forwarded to :class:PropTorch as backend-level options.

  • eager_options –

    Forwarded to :class:PropTorch for the eager path (e.g. checkpointing).

  • cuda_options –

    Forwarded to :class:PropTorch for the compiled CUDA path.

  • **propagator_kwargs –

    Extra propagator kwargs (dh, dt, abcn, dev, …).

2-D

sweep.equations.DASZhao 

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

Bases: sweep.equations.base.FirstOrderEquation

First-order 2-D stress / normal-strain-rate DAS equation (Zhao 2022).

The dynamic variables are normal strain-rates exx_t, ezz_t, normal stresses sxx, szz, and auxiliary stress-like components txx, tzz. The system is the 2-D, y-invariant reduction of Eq. (9) of the Zhao et al. paper; helical-fibre strain-rate projections (das35_t, das54x_t, das54z_t) are computed inline from exx_t and ezz_t. Staggered-grid CPML (cpmls, 8 profiles).

Reference: Zhao Y. et al. 2022, DAS modelling using a stress and normal-strain-rate elastic formulation.

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

  • exx_t: Normal strain-rate in the x direction; default receiver.
  • ezz_t: Normal strain-rate 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.
  • txx (aliases: tau_xx): Auxiliary stress-like variable tau_xx (internal).
  • tzz (aliases: tau_zz): Auxiliary stress-like variable tau_zz (internal).
  • m_sxx_xf: CPML memory variable for forward d(sxx)/dx (internal).
  • m_sxx_xb: CPML memory variable for backward d2(sxx)/dx2 (internal).
  • m_szz_zf: CPML memory variable for forward d(szz)/dz (internal).
  • m_szz_zb: CPML memory variable for backward d2(szz)/dz2 (internal).
  • m_txx_zf: CPML memory variable for forward d(txx)/dz (internal).
  • m_txx_zb: CPML memory variable for backward d2(txx)/dz2 (internal).
  • m_tzz_xf: CPML memory variable for forward d(tzz)/dx (internal).
  • m_tzz_xb: CPML memory variable for backward d2(tzz)/dx2 (internal).
  • das35_t: 35.3 degree helical-fiber axial strain-rate.
  • das54x_t: 54.7 degree helical-fiber axial strain-rate for x-oriented core.
  • das54z_t: 54.7 degree helical-fiber axial strain-rate for z-oriented core.

Defaults

  • source_type: ['sxx', 'szz']
  • receiver_type: ['exx_t', 'ezz_t']
  • pml_type: 'cpmls'

Build the 2-D Zhao DAS equation operator.

Parameters:

  • spatial_order –

    FD accuracy order of the staggered first-derivative operator (forward / backward FD pairs along x and z) — 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/das2d/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'.

C_NAME class-attribute 

C_NAME = 'das2d'

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.DASMu 

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

Bases: sweep.equations.base.FirstOrderEquation

First-order 2-D velocity-stress-strain DAS equation (Mu).

Standard 2-D elastic velocity-stress system augmented with three integrated strain fields exx, ezz, exz that track the velocity-gradient sources: exx_t = d(vx)/dx, ezz_t = d(vz)/dz, exz_t = 0.5 · (d(vx)/dz + d(vz)/dx). The :class:DAS facade differentiates the integrated strains in time to produce strain-rate (exx_t, …) and helical DAS-rate (das35_t, das54x_t, das54z_t) receivers — which requires dt to be passed through the propagator. Staggered-grid CPML (cpmls, 8 profiles).

Reference: Mu & Hung 2022, Velocity-stress-strain coupling for DAS forward modelling.

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.
  • vz (aliases: velocity_z): Particle velocity in the z direction.
  • sxx (aliases: stress_xx, sigma_xx): Normal stress in the x direction; default source.
  • szz (aliases: stress_zz, sigma_zz): Normal stress in the z direction; default source.
  • sxz (aliases: stress_xz, sigma_xz, sigma_zx): Shear stress component.
  • exx: Integrated normal strain in the x direction; default receiver.
  • ezz: Integrated normal strain in the z direction; default receiver.
  • exz: Integrated shear strain component; default receiver.
  • m_vxx: CPML memory variable for dvx/dx (internal).
  • m_vxz: CPML memory variable for dvx/dz (internal).
  • m_vzx: CPML memory variable for dvz/dx (internal).
  • m_vzz: CPML memory variable for dvz/dz (internal).
  • m_txxx: CPML memory variable for dsxx/dx (internal).
  • m_txxz: Reserved elastic auxiliary field (internal).
  • m_tzzx: Reserved elastic auxiliary field (internal).
  • m_tzzz: CPML memory variable for dszz/dz (internal).
  • m_txzx: CPML memory variable for dsxz/dx (internal).
  • m_txzz: CPML memory variable for dsxz/dz (internal).

Defaults

  • source_type: ['sxx', 'szz']
  • receiver_type: ['exx', 'ezz', 'exz']
  • pml_type: 'cpmls'

Build the 2-D Mu DAS 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/das_mu2d/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'.

C_NAME class-attribute 

C_NAME = 'das_mu2d'

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'.

3-D

sweep.equations.DASZhao3D 

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

Bases: sweep.equations.base.FirstOrderEquation

First-order 3-D stress / normal-strain-rate DAS equation (Zhao 2022).

Three-dimensional generalisation of :class:DASZhao from Eq. (9) of the Zhao et al. paper. The dynamic variables are normal strain-rates exx_t, eyy_t, ezz_t, normal stresses sxx, syy, szz, and auxiliary stress-like components txx, tyy, tzz. Helical-fibre strain-rate projections are computed inline using all three normal strain-rates. Staggered-grid CPML (cpmls, 12 profiles).

Reference: Zhao Y. et al. 2022.

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

  • exx_t: Normal strain-rate in the x direction; default receiver.
  • eyy_t: Normal strain-rate in the y direction; default receiver.
  • ezz_t: Normal strain-rate in the z direction; default receiver.
  • sxx (aliases: stress_xx): Normal stress in the x direction; default source.
  • syy (aliases: stress_yy): Normal stress in the y direction; default source.
  • szz (aliases: stress_zz): Normal stress in the z direction; default source.
  • txx (aliases: tau_xx): Auxiliary stress-like variable tau_xx (internal).
  • tyy (aliases: tau_yy): Auxiliary stress-like variable tau_yy (internal).
  • tzz (aliases: tau_zz): Auxiliary stress-like variable tau_zz (internal).
  • m_sxx_xf: CPML memory variable for forward d(sxx)/dx (internal).
  • m_sxx_xb: CPML memory variable for backward d2(sxx)/dx2 (internal).
  • m_syy_yf: CPML memory variable for forward d(syy)/dy (internal).
  • m_syy_yb: CPML memory variable for backward d2(syy)/dy2 (internal).
  • m_szz_zf: CPML memory variable for forward d(szz)/dz (internal).
  • m_szz_zb: CPML memory variable for backward d2(szz)/dz2 (internal).
  • m_txx_yf: CPML memory variable for forward d(txx)/dy (internal).
  • m_txx_yb: CPML memory variable for backward d2(txx)/dy2 (internal).
  • m_txx_zf: CPML memory variable for forward d(txx)/dz (internal).
  • m_txx_zb: CPML memory variable for backward d2(txx)/dz2 (internal).
  • m_tyy_xf: CPML memory variable for forward d(tyy)/dx (internal).
  • m_tyy_xb: CPML memory variable for backward d2(tyy)/dx2 (internal).
  • m_tyy_zf: CPML memory variable for forward d(tyy)/dz (internal).
  • m_tyy_zb: CPML memory variable for backward d2(tyy)/dz2 (internal).
  • m_tzz_xf: CPML memory variable for forward d(tzz)/dx (internal).
  • m_tzz_xb: CPML memory variable for backward d2(tzz)/dx2 (internal).
  • m_tzz_yf: CPML memory variable for forward d(tzz)/dy (internal).
  • m_tzz_yb: CPML memory variable for backward d2(tzz)/dy2 (internal).
  • das35_t: 35.3 degree helical-fiber axial strain-rate.
  • das54x_t: 54.7 degree helical-fiber axial strain-rate for x-oriented core.
  • das54y_t: 54.7 degree helical-fiber axial strain-rate for y-oriented core.
  • das54z_t: 54.7 degree helical-fiber axial strain-rate for z-oriented core.

Defaults

  • source_type: ['sxx', 'syy', 'szz']
  • receiver_type: ['exx_t', 'eyy_t', 'ezz_t']
  • pml_type: 'cpmls'

Build the 3-D Zhao DAS 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/das3d/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'.

C_NAME class-attribute 

C_NAME = 'das3d'

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_c class-attribute 

supports_boundary_saving_c = 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.

sweep.equations.DASMu3D 

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

Bases: sweep.equations.base.FirstOrderEquation

First-order 3-D velocity-stress-strain DAS equation (Mu).

Three-dimensional generalisation of :class:DASMu. Standard 3-D elastic velocity-stress system (nine physical fields) augmented with six integrated strain fields tracking the velocity gradients. The :class:DAS facade differentiates the integrated strains in time to produce strain-rate and helical DAS-rate receivers — which requires dt to be passed through the propagator. Staggered-grid CPML (cpmls, 12 profiles).

Reference: Mu & Hung 2022.

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.
  • vy (aliases: velocity_y): Particle velocity in the y direction.
  • vz (aliases: velocity_z): Particle velocity in the z direction.
  • sxx (aliases: stress_xx, sigma_xx): Normal stress in the x direction; default source.
  • syy (aliases: stress_yy, sigma_yy): Normal stress in the y direction; default source.
  • szz (aliases: stress_zz, sigma_zz): Normal stress in the z direction; default source.
  • sxy (aliases: stress_xy, sigma_xy, sigma_yx): Shear stress xy component.
  • sxz (aliases: stress_xz, sigma_xz, sigma_zx): Shear stress xz component.
  • syz (aliases: stress_yz, sigma_yz, sigma_zy): Shear stress yz component.
  • exx: Integrated normal strain in the x direction; default receiver.
  • eyy: Integrated normal strain in the y direction; default receiver.
  • ezz: Integrated normal strain in the z direction; default receiver.
  • exy: Integrated shear strain xy component; default receiver.
  • exz: Integrated shear strain xz component; default receiver.
  • eyz: Integrated shear strain yz component; default receiver.
  • m_vxx: CPML memory variable for dvx/dx (internal).
  • m_vxy: CPML memory variable for dvx/dy (internal).
  • m_vxz: CPML memory variable for dvx/dz (internal).
  • m_vyx: CPML memory variable for dvy/dx (internal).
  • m_vyy: CPML memory variable for dvy/dy (internal).
  • m_vyz: CPML memory variable for dvy/dz (internal).
  • m_vzx: CPML memory variable for dvz/dx (internal).
  • m_vzy: CPML memory variable for dvz/dy (internal).
  • m_vzz: CPML memory variable for dvz/dz (internal).
  • m_sxxx: CPML memory variable for dsxx/dx (internal).
  • m_szzz: CPML memory variable for dszz/dz (internal).
  • m_sxyx: CPML memory variable for dsxy/dx (internal).
  • m_sxyy: CPML memory variable for dsxy/dy (internal).
  • m_sxzx: CPML memory variable for dsxz/dx (internal).
  • m_sxzz: CPML memory variable for dsxz/dz (internal).
  • m_syyy: CPML memory variable for dsyy/dy (internal).
  • m_syzy: CPML memory variable for dsyz/dy (internal).
  • m_syzz: CPML memory variable for dsyz/dz (internal).

Defaults

  • source_type: ['sxx', 'syy', 'szz']
  • receiver_type: ['exx', 'eyy', 'ezz', 'exy', 'exz', 'eyz']
  • pml_type: 'cpmls'

Build the 3-D Mu DAS 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/das_mu3d/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'.

C_NAME class-attribute 

C_NAME = 'das_mu3d'

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'.