Acoustic1st¶
Governing equation¶
Acoustic1st solves the two-dimensional variable-density acoustic equations
in first-order pressure–velocity form,
where \(p\) is the pressure p (the default source and receiver field),
\(v_x\) and \(v_z\) are the particle velocities vx and vz, \(v_p\) is the
model vp and \(\rho\) the model rho; \(\rho v_p^2\) is the bulk modulus.
The fields lie on a staggered grid: \(p\) on the integer nodes and \(v_x\), \(v_z\)
half a cell away along their own axis. The first derivatives are staggered
differences of order spatial_order (default 4). Time is discretised with a
staggered leapfrog: the velocities are updated from \(p^{n}\), then the
pressure from the new velocities. After each step the wavelet sample is added
to \(p\) at the source cell, without scaling.
Boundary conditions¶
The default pml_type="cpmls" gives each of the four derivatives its own
memory field: psix, psiz for \(\partial_x p\) and \(\partial_z p\), and
phix, phiz for \(\partial_x v_x\) and \(\partial_z v_z\); see
Absorbing boundaries. The alternative
pml_type="spml" is the split-field PML described there; its fields are
px, pz, vx, vz with \(p = p_x + p_z\), the default source field is
px and the default receiver field is vx. In this mode the step solves
\(\rho\, \partial_t \mathbf{v} = +\nabla p\) and
\(\partial_t p = +\rho v_p^2 \nabla \cdot \mathbf{v}\), so the pressure obeys
the same wave equation but the velocities have the opposite sign to those of
cpmls.
The step applies no free-surface condition. free_surface=True is accepted,
but it only removes the absorbing layer from the top face, which then
becomes the edge of the grid; it is not a calibrated pressure-release
surface.
sweep.equations.Acoustic1st ¶
Bases: sweep.equations.base.FirstOrderEquation
First-order 2-D acoustic wave equation in pressure-velocity form.
Variable-density scalar acoustics on a staggered grid: a pressure field
p and particle velocities (vx, vz) evolve together. The default
boundary type is 'cpmls' (staggered-grid recursive CPML), which
couples four memory variables (phix, phiz, psix, psiz);
'spml' is also supported and switches to a split-pressure
formulation with two pressure components (px, pz) instead of
p.
Reference: 10.1190/GEO2011-0345.1.
Models (constructor input order)
vp(m/s): Acoustic P-wave velocity model.rho(kg/m^3): Density model.
Wavefields (cpmls mode — the default)
p(aliases:pressure): Acoustic pressure field; default source and receiver.vx(aliases:velocity_x): Particle velocity in the x direction.vz(aliases:velocity_z): Particle velocity in the z direction.phix: CPML memory variable for the x-derivative term (internal).phiz: CPML memory variable for the z-derivative term (internal).psix: CPML auxiliary field in the x direction (internal).psiz: CPML auxiliary field in the z direction (internal).
Wavefields (spml mode)
px: Split-field pressure component in the x direction (internal).pz: Split-field pressure component in the z direction (internal).vx(aliases:velocity_x): Particle velocity in the x direction.vz(aliases:velocity_z): Particle velocity in the z direction.
Defaults
source_type:['p']receiver_type:['p']pml_type:'cpmls'
Build the first-order acoustic equation operator.
Parameters:
-
spatial_order–FD accuracy order of the staggered first-derivative operator — 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, …). Higher orders reduce grid dispersion at the cost of more compute per step and a wider PML halo. This equation has no compiledimpl='c'path; useimpl='eager'(the default). The PyTorch / JAX eager path accepts any even order. Defaults to 4. -
device–Device for the operator's static gradient kernels. Use
'cuda'/ atorch.devicefor GPU runs. Defaults to'cpu'. -
backend–Array / programming backend,
'torch'or'jax'. Defaults to'jax'for this class (the original research implementation); passbackend='torch'to stay on PyTorch. -
**kwargs–forwarded to :class:
FirstOrderEquationfor forward-compatibility (currently unused).
free_surface_unsupported_reason
class-attribute
¶
free_surface_unsupported_reason = "its time step has no free-surface implementation (the top would stay the edge of the padded array, not a pressure-release surface)"
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_free_surface
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.
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.
interior_substeps ¶
The lossless-interior leapfrog as an ordered list of reversible sub-steps (single source of truth — used for BOTH forward and reverse).
Each sub-step updates ONE field group using the OTHER (a pure shear), so
evaluating it at -dt exactly inverts it; composing the list in
reverse order at -dt therefore inverts the whole step exactly — no
separate, sign-flipped reverse body to maintain. The forward step is
compose(substeps, +dt) in order (+ CPML, handled by func).