Skip to content

AcousticVRZ / AcousticVRZ3D

Governing equation

AcousticVRZ (2-D) and AcousticVRZ3D (3-D) solve the variable-density acoustic wave equation for the pressure alone,

\[ \frac{\partial^2 p}{\partial t^2} = \kappa\, \nabla \cdot \left( b\, \nabla p \right) = \kappa \left( b\, \nabla^2 p + \nabla b \cdot \nabla p \right), \qquad \kappa = Z v_p, \qquad b = \frac{v_p}{Z}, \]

where \(p\) is the pressure-like wavefield h1 (the source and receiver field), \(v_p\) is the model vp and \(Z\) is the model z. With \(Z = \rho v_p\), the acoustic impedance, \(\kappa = \rho v_p^2\) is the bulk modulus and \(b = 1/\rho\) the buoyancy, so the models (vp, z) are an impedance parameterisation of the variable-density equation. Time is discretised with the second-order central difference. \(\nabla^2 p\) is assembled from second-derivative stencils of order spatial_order (default 4), and \(\nabla p\) and \(\nabla b\) from first-derivative central differences of the same order. \(\nabla b\) is formed with the product rule from the two models, \(\nabla b = (\nabla v_p)/Z + v_p \nabla (1/Z)\), not by differencing \(v_p/Z\). After each update the wavelet sample is added to \(p^{n+1}\) at the source cell, without scaling.

Boundary conditions

The default pml_type="cpmlr" replaces \(\nabla^2 p\) by its stretched form and \(\nabla p\) in the \(\nabla b \cdot \nabla p\) term by \(\partial_x p + \psi_x\) (likewise \(y\), \(z\)), with the memory fields psix, zetax, psiz, zetaz (and psiy, zetay in 3-D); see Absorbing boundaries. With free_surface=True the top face is pressure-release, \(p = 0\).

References

  • Whitmore, N. D., J. Ramos-Martinez, Y. Yang, and A. Valenciano, 2020, Full wavefield modeling with vector reflectivity: EAGE 2020 Annual Conference & Exhibition Online, 1–5, doi:10.3997/2214-4609.202010332.

sweep.equations.AcousticVRZ

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

Bases: sweep.equations.base.SecondOrderEquation

Second-order 2-D acoustic wave equation in variable-density VRZ form.

Pressure-only scalar acoustics with explicit density coupling through an impedance-like auxiliary parameter z. The Laplacian carries an extra term ∇b · ∇p (with b = vp / z, κ = z · vp), so the propagator is a single second-order PDE in h1 that correctly refracts at sharp impedance 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.
  • z: Auxiliary parameter used by the VRZ formulation.

Wavefields

  • h1 (aliases: pressure, p): Primary VRZ acoustic pressure-like wavefield; default source and receiver.
  • h2 (aliases: pressure_prev): Previous-step VRZ 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 VRZ acoustic equation operator.

Parameters:

  • spatial_order –

    FD accuracy order of the spatial Laplacian and the auxiliary first-derivative kernels used by the ∇b · ∇p 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, …). 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_vrz2d/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' — the compiled CUDA kernels go through the Torch binding. Defaults to 'torch'.

  • dim –

    Stored dimensionality. Always 2 for this class; use :class:AcousticVRZ3D for 3-D. Defaults to 2.

BOUNDARY_BUFFER_REACH class-attribute

BOUNDARY_BUFFER_REACH = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

C_NAME class-attribute

C_NAME = 'acoustic_vrz2d'

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

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.

c_refuse_grads

c_refuse_grads(
    wavelet_grad,
    model_grad_mask,
    boundary_saving=False,
    boundary_dtype=None,
    checkpoint=False,
)

impl='c': the wavelet gradient is refused (refuse_c_grads).

sweep.equations.AcousticVRZ3D

AcousticVRZ3D(spatial_order=4, device='cpu', backend='torch', dim=3)

Bases: sweep.equations.base.SecondOrderEquation

Second-order 3-D acoustic wave equation in variable-density VRZ form.

Three-dimensional generalisation of :class:AcousticVRZ: a single pressure-like field h1 is propagated with an extra ∇b · ∇p coupling term (with b = vp / z, κ = z · vp) so that impedance contrasts refract correctly without needing a separate velocity field. Absorbing boundaries on every face via split-step CPML (cpmlr).

Reference: 10.3997/2214-4609.202010332.

Models (constructor input order)

  • vp (m/s): 3D acoustic velocity model.
  • z: Auxiliary parameter used by the 3D VRZ formulation.

Wavefields

  • h1 (aliases: pressure, p): Primary 3D VRZ acoustic pressure-like wavefield; default source and receiver.
  • h2 (aliases: pressure_prev): Previous-step 3D VRZ acoustic pressure-like wavefield (internal).
  • psix: CPML memory variable for the x-derivative term (internal).
  • psiy: CPML memory variable for the y-derivative term (internal).
  • psiz: CPML memory variable for the z-derivative term (internal).
  • zetax: CPML auxiliary wavefield for the x-direction update (internal).
  • zetay: CPML auxiliary wavefield for the y-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 3-D VRZ acoustic equation operator.

Parameters:

  • spatial_order –

    FD accuracy order of the spatial Laplacian and the auxiliary first-derivative kernels used by the ∇b · ∇p 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, …). 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_vrz3d/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' — the compiled CUDA kernels go through the Torch binding. Defaults to 'torch'.

  • dim –

    Stored dimensionality. Always 3 for this class; use :class:AcousticVRZ for 2-D. Defaults to 3.

BOUNDARY_BUFFER_REACH class-attribute

BOUNDARY_BUFFER_REACH = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

C_NAME class-attribute

C_NAME = 'acoustic_vrz3d'

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

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.

c_refuse_grads

c_refuse_grads(
    wavelet_grad,
    model_grad_mask,
    boundary_saving=False,
    boundary_dtype=None,
    checkpoint=False,
)

impl='c': the wavelet gradient is refused (refuse_c_grads).