Skip to content

ViscoElastic

Governing equations

ViscoElastic solves the two-dimensional visco-elastic wave equation for a generalised standard linear solid: \(L\) standard linear solids (n_sls, default 3) in parallel, with stress relaxation times \(\tau_{\sigma l}\) fixed by a frequency band. The velocity equations are those of Elastic,

\[ \rho \frac{\partial v_x}{\partial t} = \frac{\partial \sigma_{xx}}{\partial x} + \frac{\partial \sigma_{xz}}{\partial z}, \qquad \rho \frac{\partial v_z}{\partial t} = \frac{\partial \sigma_{xz}}{\partial x} + \frac{\partial \sigma_{zz}}{\partial z}, \]

and the stresses carry one memory variable per component and mechanism (Robertsson et al., 1994). With \(\theta = \partial_x v_x + \partial_z v_z\),

\[ \begin{aligned} \frac{\partial \sigma_{xx}}{\partial t} &= \pi_U\, \theta - 2\mu_U \frac{\partial v_z}{\partial z} + \sum_{l=1}^{L} r_{xx,l}, \\ \frac{\partial \sigma_{zz}}{\partial t} &= \pi_U\, \theta - 2\mu_U \frac{\partial v_x}{\partial x} + \sum_{l=1}^{L} r_{zz,l}, \\ \frac{\partial \sigma_{xz}}{\partial t} &= \mu_U \left( \frac{\partial v_x}{\partial z} + \frac{\partial v_z}{\partial x} \right) + \sum_{l=1}^{L} r_{xz,l}, \\ \frac{\partial r_{xx,l}}{\partial t} &= -\frac{1}{\tau_{\sigma l}} \left( r_{xx,l} + \pi_R \tau^{p}_{l}\, \theta - 2\mu_R \tau^{s}_{l} \frac{\partial v_z}{\partial z} \right), \\ \frac{\partial r_{zz,l}}{\partial t} &= -\frac{1}{\tau_{\sigma l}} \left( r_{zz,l} + \pi_R \tau^{p}_{l}\, \theta - 2\mu_R \tau^{s}_{l} \frac{\partial v_x}{\partial x} \right), \\ \frac{\partial r_{xz,l}}{\partial t} &= -\frac{1}{\tau_{\sigma l}} \left( r_{xz,l} + \mu_R \tau^{s}_{l} \left( \frac{\partial v_x}{\partial z} + \frac{\partial v_z}{\partial x} \right) \right), \end{aligned} \]

where \(r_{xx,l}\), \(r_{zz,l}\), \(r_{xz,l}\) are the fields r_xx_l, r_zz_l, r_xz_l (\(l\) counted from 0 in the field names), \(\pi_R\) and \(\mu_R\) are the relaxed P-wave and shear moduli, and the unrelaxed moduli are

\[ \pi_U = \pi_R \Big( 1 + \sum_{l} \tau^{p}_{l} \Big), \qquad \mu_U = \mu_R \Big( 1 + \sum_{l} \tau^{s}_{l} \Big). \]

Each modulus \(M\) (\(\pi\) with strengths \(\tau^{p}_{l}\), \(\mu\) with \(\tau^{s}_{l}\)) is therefore

\[ M(\omega) = M_R \left( 1 + \sum_{l=1}^{L} \tau_l \frac{i\omega\tau_{\sigma l}}{1 + i\omega\tau_{\sigma l}} \right). \]

The relaxation times are \(\tau_{\sigma l} = 1/(2\pi f_l)\) with \(f_l\) log-spaced over f_band \(= (f_{\min}, f_{\max})\); the default band is \((f_{\mathrm{ref}}/\sqrt{12},\ f_{\mathrm{ref}}\sqrt{12})\) and the default reference frequency f_ref is 10 Hz. The strengths \(\tau^{p}_{l}\) and \(\tau^{s}_{l}\) follow from the models Qp and Qs by the least-squares constant-\(Q\) fit of Emmerich and Korn (1987): with \(a_l = (\omega\tau_{\sigma l})^2 / (1 + (\omega\tau_{\sigma l})^2)\) and \(b_l = \omega\tau_{\sigma l} / (1 + (\omega\tau_{\sigma l})^2)\), the condition \(\operatorname{Re} M / \operatorname{Im} M = Q\) reads

\[ \sum_{l=1}^{L} \tau_l \left( Q\, b_l(\omega) - a_l(\omega) \right) = 1, \]

which is solved in the least-squares sense at 200 log-spaced frequencies in the band (see GSLSFit below). The solution is a rational function of \(1/Q\), so Qp and Qs are differentiable models.

The models vp and vs are phase velocities at f_ref. The relaxed moduli are set so that \(\operatorname{Re}\sqrt{\rho / M(\omega_{\mathrm{ref}})} = 1/v\):

\[ \pi_R = \rho\, v_p^2\, \frac{\cos^2(\phi_p/2)}{|m_p|}, \qquad \mu_R = \rho\, v_s^2\, \frac{\cos^2(\phi_s/2)}{|m_s|}, \qquad m = \frac{M(\omega_{\mathrm{ref}})}{M_R} = |m|\, e^{i\phi}, \]

with \(m_p\) evaluated with \(\tau^{p}_{l}\) and \(m_s\) with \(\tau^{s}_{l}\). With Qp = Qs = inf all strengths vanish and the equation reduces exactly to Elastic.

The grid, stencil and leapfrog are those of Elastic. The memory variables are stored at integer time levels and advanced with the trapezoidal rule,

\[ r_l^{n+1} = \frac{1 - \Delta t / 2\tau_{\sigma l}}{1 + \Delta t / 2\tau_{\sigma l}}\, r_l^{n} - \frac{\Delta t / \tau_{\sigma l}}{1 + \Delta t / 2\tau_{\sigma l}}\, F_l, \]

where \(F_l\) is the bracketed source term above evaluated with the velocities at \(n + 1/2\); the stress update adds \(\tfrac{\Delta t}{2} \sum_l (r_l^{n+1} + r_l^{n})\). The explicit update runs at the unrelaxed velocities \(\sqrt{\pi_U/\rho}\) and \(\sqrt{\mu_U/\rho}\), which exceed vp and vs for finite \(Q\), so \(\Delta t\) must satisfy the stability condition for these velocities (unrelaxed_velocities). \(Q\) must exceed q_min, below which the fit gives a negative strength.

Boundary conditions

The default pml_type="cpmls" is the staggered-grid C-PML of Elastic; see Absorbing boundaries. The C-PML acts on the velocity derivatives that drive both the stresses and the memory variables.

A flat free surface is supported on any subset of the four faces; topography is not. The image method of Elastic is used, but instead of the elastic surface modulus the normal strain rate on the surface row (\(\partial_z v_z\) on a \(z\) face, \(\partial_x v_x\) on an \(x\) face) is solved from the condition that the normal stress stays zero through the full update, memory variables included. In the elastic limit this gives the modulus \(4\mu(\lambda + \mu)/(\lambda + 2\mu)\) used by Elastic. As for Elastic, a PML between two unabsorbed faces of the other axis, one of them free, is refused; attenuation does not stop the PML amplifying the plate's backward Lamb modes.

References

  • Emmerich, H., and M. Korn, 1987, Incorporation of attenuation into time-domain computations of seismic wave fields: Geophysics, 52(9), 1252–1264, doi:10.1190/1.1442386.
  • Robertsson, J. O. A., J. O. Blanch, and W. W. Symes, 1994, Viscoelastic finite-difference modeling: Geophysics, 59(9), 1444–1456, doi:10.1190/1.1443701.

sweep.equations.ViscoElastic

ViscoElastic(
    spatial_order=4, device="cpu", backend="torch", f_ref=10.0, f_band=None, n_sls=3
)

Bases: sweep.equations.base.FirstOrderEquation

First-order 2-D visco-elastic wave equation (GSLS, nearly constant Q).

Velocity-stress staggered grid as :class:~sweep.equations.elastic.Elastic plus 3 L memory variables (r_xx_l, r_zz_l, r_xz_l, one triple per standard linear solid). With relaxed P and shear moduli pi_R, mu_R, strengths tp_l = tau_l(Qp), ts_l = tau_l(Qs) and theta = dvx/dx + dvz/dz::

dsxx/dt = pi_U theta - 2 mu_U dvz/dz + sum_l r_xx_l
dszz/dt = pi_U theta - 2 mu_U dvx/dx + sum_l r_zz_l
dsxz/dt = mu_U (dvx/dz + dvz/dx)    + sum_l r_xz_l
dr_xx_l/dt = -(r_xx_l + pi_R tp_l theta - 2 mu_R ts_l dvz/dz) / tau_sigma_l
(r_zz_l, r_xz_l analogous)

with unrelaxed moduli pi_U = pi_R (1 + sum_l tp_l), mu_U = mu_R (1 + sum_l ts_l), i.e. M(w) = M_R (1 + sum_l tau_l i w tau_sigma_l / (1 + i w tau_sigma_l)). The memory variables live at integer time levels and are advanced with the trapezoidal rule (unconditionally stable for any dt / tau_sigma_l); the stress picks up their time average.

Models are vp, vs, rho, Qp, Qs; vp/vs are phase velocities at the reference frequency f_ref (SPECFEM's READ_VELOCITIES_AT_f0 = .true.), converted exactly to the relaxed moduli through the GSLS complex modulus at f_ref. All five models are differentiable. Qp = Qs = inf reduces bit-exactly to Elastic.

The tau_sigma_l are fixed by (n_sls, f_band) at construction (relaxation frequencies log-spaced over the band) and are not model parameters; tau_l(Q) is the least-squares constant-Q fit (see :class:GSLSFit).

Stability: the explicit stress update runs at the UNRELAXED velocities, which exceed vp/vs (e.g. ~8% at Q = 10 for a 12x band), so choose dt from the CFL condition on sqrt((lam_U + 2 mu_U) / rho) (:meth:unrelaxed_velocities). Q must exceed self.q_min (about 1.3 for the default 3 mechanisms), below which the fit would need a negative relaxation strength; n_sls >= 5 is refused for the same reason.

Free surface (flat, per edge): the surface-row normal strain rate is solved so that the normal traction stays exactly zero INCLUDING the memory variables; in the elastic limit this is Robertsson's modified coefficient 4 mu (lam + mu) / (lam + 2 mu) used by Elastic.

Backends: eager and compiled CUDA (impl='c'; forward, and the full, chunk- and recursive-checkpoint backwards with a hand-derived exact adjoint). Not supported: boundary saving (the attenuation is dissipative, so reverse reconstruction is unstable; impl='c' defaults to full), topography, domain decomposition, per-shot batched models.

References

Robertsson, J. O., Blanch, J. O. and Symes, W. W., 1994, Viscoelastic finite-difference modeling: Geophysics, 59(9), 1444-1456, doi:10.1190/1.1443701 -- the staggered-grid memory-variable scheme. Emmerich, H. and Korn, M., 1987, Incorporation of attenuation into time-domain computations of seismic wave fields: Geophysics, 52(9), 1252-1264, doi:10.1190/1.1442386 -- the constant-Q fit (linear least squares for the strengths at fixed relaxation frequencies).

Models (constructor input order)

  • vp (m/s): P-wave phase velocity at f_ref.
  • vs (m/s): S-wave phase velocity at f_ref.
  • rho (kg/m^3): Density model.
  • Qp: P-wave quality factor (inf = no attenuation).
  • Qs: S-wave quality factor (inf = no attenuation).

Wavefields

  • vx (aliases: velocity_x): Particle velocity in the x direction; default receiver.
  • vz (aliases: velocity_z): Particle velocity 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.
  • sxz (aliases: stress_xz, shear_xz): Shear stress component.
  • r_xx_0: GSLS memory variable xx, mechanism 0 (internal).
  • r_zz_0: GSLS memory variable zz, mechanism 0 (internal).
  • r_xz_0: GSLS memory variable xz, mechanism 0 (internal).
  • r_xx_1: GSLS memory variable xx, mechanism 1 (internal).
  • r_zz_1: GSLS memory variable zz, mechanism 1 (internal).
  • r_xz_1: GSLS memory variable xz, mechanism 1 (internal).
  • r_xx_2: GSLS memory variable xx, mechanism 2 (internal).
  • r_zz_2: GSLS memory variable zz, mechanism 2 (internal).
  • r_xz_2: GSLS memory variable xz, mechanism 2 (internal).
  • 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: ['vx', 'vz']
  • pml_type: 'cpmls'

Args: spatial_order: FD order (as Elastic). device: Device for the gradient kernels. backend: 'torch' only. f_ref: Reference frequency (Hz) at which vp / vs are given. f_band: (f_min, f_max) over which Q is fitted constant. Defaults to a factor 12 centred (geometrically) on f_ref, the band of SPECFEM2D's original fit (its current one spans f_ref / 10 to 10 f_ref). For FWI set it to the inverted band. n_sls: Number of standard linear solids (SPECFEM default 3).

C_NAME class-attribute

C_NAME = 'visco_elastic2d'

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

free_plate_unstable class-attribute

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

prepare_models_for_c class-attribute

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

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.

supports_per_edge_free_surface class-attribute

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

supports_per_edge_free_surface_c class-attribute

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

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_eq_aux

c_eq_aux(prop)

eq_aux for the CUDA kernels: one float32 CPU tensor [a_0 .. a_{L-1}, c_0 .. c_{L-1}], evaluated exactly as the eager step evaluates them (float32 dt).

prepare_models

prepare_models(models)

(vp, vs, rho, Qp, Qs) -> [lam_U, mu_U, rho, lam_U + 2 mu_U, pi_R tp_0 .. pi_R tp_{L-1}, mu_R ts_0 .. mu_R ts_{L-1}] -- the step coefficients shared by the eager step and the CUDA kernels (rho third, where elastic2d's kernels keep it). The unrelaxed Lame set is exactly Elastic._lame of the unrelaxed velocities, so at Q = inf (tau_l = 0 -> factors exactly 1) the elastic part is bit-identical to Elastic.

impl='c' hands (B, 1, nz, nx) repeats of one shared model (this equation has no per-shot models): the coefficients are computed once and repeated, and the repeat's backward sums the per-shot gradients.

relaxation_coefficients

relaxation_coefficients(dt)

Trapezoidal memory-update weights r+ = a_l r - c_l F: a_l = (1 - dt/2ts) / (1 + dt/2ts), c_l = (dt/ts) / (1 + dt/2ts). dt may be the eager step's float32 0-d tensor (possibly inside a compiled step: kept symbolic); :meth:c_eq_aux evaluates the same expressions so both backends see identical float32 weights.

unrelaxed_velocities

unrelaxed_velocities(models)

(vp_U, vs_U) for (vp, vs, rho, Qp, Qs): the velocities the explicit stress update actually runs at (above vp / vs for finite Q, equal at Q = inf) -- take dt from the CFL condition on vp_U.

sweep.equations.visco_elastic.GSLSFit

GSLSFit(tau_sigma, f_min, f_max, n_freq=200)

Per-mechanism strengths tau_l(Q) for fixed tau_sigma_l.

With a_l(w) = (w ts_l)^2 / (1 + (w ts_l)^2) and b_l(w) = w ts_l / (1 + (w ts_l)^2), M(w)/M_R = 1 + sum_l tau_l (a_l + i b_l). Constant Q means sum_l tau_l (Q b_l - a_l) = 1 on the band; the least-squares tau solves (BB - (BA + AB) q + AA q^2) tau = q (sb - sa q) with q = 1/Q (sampled at n_freq log-spaced frequencies). By Cramer's rule tau_l = q N_l(q) / D(q) with polynomial D (degree 2L) and N_l; :meth:tau evaluates that form elementwise (q = 0 gives tau = 0 exactly), :meth:tau_np the direct solve (reference).

min_valid_q

min_valid_q(q_grid=None)

Smallest Q above which every tau_l(Q) > 0 (a physical, dissipative relaxation spectrum). Raises if even the high-Q limit has a non-positive strength (too many mechanisms for the band).

tau

tau(Q)

Torch: Q of any shape -> list of L tensors tau_l (same shape/dtype as Q), differentiable in Q.

modulus_ratio

modulus_ratio(tau, freq)

Numpy M(w)/M_R for strengths tau (length L) at freq.

q_of_frequency

q_of_frequency(Q, freq)

Exact Q(f) realised for a target Q (numpy; checks the fit).

sweep.equations.gsls_nonlinear.GSLSNonlinearFit

GSLSNonlinearFit(n_sls, f_min, f_max, n_freq=None)

Relaxation times and strengths of n_sls standard linear solids fitted for a constant Q over [f_min, f_max] by the nonlinear least squares at n_freq log-spaced frequencies (default 4 n_sls, SPECFEM2D's). See the module docstring. :meth:params maps a tensor of Q elementwise (differentiable), :meth:params_np fits one Q directly (the reference).

params

params(Q)

Torch: Q of any shape -> (tau_sigma, w), two lists of n_sls tensors shaped and typed as Q, differentiable in Q.

params_np

params_np(Q)

Numpy, one Q: (tau_sigma, w) of a direct fit from SPECFEM2D's start.

modulus_ratio staticmethod

modulus_ratio(tau_sigma, w, freq)

Numpy M(f) / M_R of the relaxation times tau_sigma and strengths w (length n_sls each) at freq.

q_of_frequency

q_of_frequency(Q, freq)

Q(f) the fit realises for a target Q (numpy).