AcousticVRZ / AcousticVRZ3D¶
Governing equation¶
AcousticVRZ (2-D) and AcousticVRZ3D (3-D) solve the variable-density
acoustic wave equation for the pressure alone,
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 ¶
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 · ∇pterm — e.g.spatial_order=4is fourth-order accurate. Internally the half-stencil width isM = 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 forspatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1insrc/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'/ atorch.devicefor 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 wantimpl='c', leave this on'torch'— the compiled CUDA kernels go through the Torch binding. Defaults to'torch'. -
dim–Stored dimensionality. Always
2for this class; use :class:AcousticVRZ3Dfor 3-D. Defaults to 2.
BOUNDARY_BUFFER_REACH
class-attribute
¶
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
¶
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
¶
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 ¶
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 · ∇pterm — e.g.spatial_order=4is fourth-order accurate. Internally the half-stencil width isM = 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 forspatial_order ∈ {2, 4, 6, 8}. Above 8 the dispatcher drops to a generic runtime path (order = -1insrc/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'/ atorch.devicefor 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 wantimpl='c', leave this on'torch'— the compiled CUDA kernels go through the Torch binding. Defaults to'torch'. -
dim–Stored dimensionality. Always
3for this class; use :class:AcousticVRZfor 2-D. Defaults to 3.
BOUNDARY_BUFFER_REACH
class-attribute
¶
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
¶
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
¶
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).