Skip to content

Acoustic1st

Governing equation

Acoustic1st solves the two-dimensional variable-density acoustic equations in first-order pressure–velocity form,

\[ \rho \frac{\partial v_x}{\partial t} = -\frac{\partial p}{\partial x}, \qquad \rho \frac{\partial v_z}{\partial t} = -\frac{\partial p}{\partial z}, \qquad \frac{\partial p}{\partial t} = -\rho v_p^2 \left( \frac{\partial v_x}{\partial x} + \frac{\partial v_z}{\partial z} \right), \]

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

Acoustic1st(spatial_order=4, device='cpu', backend='jax', **kwargs)

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=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, …). Higher orders reduce grid dispersion at the cost of more compute per step and a wider PML halo. This equation has no compiled impl='c' path; use impl='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' / a torch.device for GPU runs. Defaults to 'cpu'.

  • backend –

    Array / programming backend, 'torch' or 'jax'. Defaults to 'jax' for this class (the original research implementation); pass backend='torch' to stay on PyTorch.

  • **kwargs –

    forwarded to :class:FirstOrderEquation for 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

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

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.

interior_substeps

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