# simulation.elastic_fdtd

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-28
Updated: 2026-11-11T17:49:27Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: 2D elastic finite-difference time-domain (P-SV) simulation.

---

2D elastic finite-difference time-domain (P-SV) simulation.

A staggered-grid velocity-stress leapfrog solver for the 2D elastodynamic
equations in an isotropic linear medium, following the reference formulation
of Virieux, "P-SV wave propagation in heterogeneous media: velocity-stress
finite-difference method", *Geophysics* 51(4), 889-901 (1986):

* the governing first-order velocity-stress system in `(vx, vy)` and
  `(txx, tyy, txy)` (Eq. 2), which handles heterogeneous media without any
  explicit interface treatment;
* the fully staggered discretisation of Fig. 1 / Eq. 5, second order in
  space and time, arranged here so that the normal stresses share the cell
  centres of the acoustic solver ([`FDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#fdtd2d))
  and the velocities live on the cell faces;
* the Courant stability condition
  $c_\mathrm{P} \Delta t \sqrt{1/\Delta x^2 + 1/\Delta y^2} < 1$
  (Eqs. 6-7), which depends only on the P-wave speed, and the numerical
  dispersion relations of Eqs. 13-14 with the 10-cells-per-wavelength rule;
* liquids as the `c_s = 0` limit: shear-free cells propagate the acoustic
  wave equation and a fluid-solid contact needs no special treatment.

Heterogeneous media use the effective grid parameters of Moczo, Kristek,
Galis, Pazak & Balazovjech, "The finite-difference and finite-element
modeling of seismic wave propagation and earthquake motion", *Acta Physica
Slovaca* 57(2), 177-406 (2007): density arithmetically averaged onto the
faces and the shear modulus harmonically averaged onto the corners
(Eqs. 7.37-7.39), which is what makes internal interfaces (including
fluid-solid ones) converge to the physical traction continuity. Free
surfaces use the stress-imaging condition (Levander 1988; Moczo et al.
Eq. 9.9): zero normal stress on the surface plane and an antisymmetric
image of the shear stress above it.

Two API levels are exposed, mirroring the acoustic module.
[`elastic_fdtd_simulation`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elastic_fdtd_simulation) takes an [`ElasticRun`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrun), the record of
a simulation that checks every argument when it is built, steps it
deterministically and returns a frozen [`ElasticFDTDResult`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtdresult) with
per-probe signal histories, optional field snapshots and a `.plot()`
method.
[`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d) is the underlying stepping engine for callers that
need frame-by-frame access to the five field arrays.

The solver is deliberately deterministic: no random numbers, and every
operation in a fixed order. On NumPy in float64 identical inputs give
bit-identical outputs on the same platform. On CuPy in float64 the recorded
proof (`gpu-parity.lock`) found every field, snapshot and contour phasor
bit-identical to NumPy's over the scenarios of both engines, and the energy
within 1.79e-16 relative over them, because the GPU sums it in another
order; the guide on where a simulation runs names the hardware it was
measured on. Runs on torch's CPU device, runs on torch's MPS device (float32
only), and float32 runs on NumPy, agree with NumPy in float64 within the
tolerance that guide publishes for each device and dtype. Each of these
bounds is the worst over that scenario matrix (grids of up to 64 by 48
cells, up to 120 steps), not a promise about any run: float32 rounding grows
with the number of steps. An acoustic run of 8085 steps on a 200 by 300 cell
grid, driven by a 1 kHz `CWSource`, differed by 8.0e-06 relative at its
probe (4.0e-06 with a Gaussian pulse), on NumPy and on torch's CPU device
alike. A float32 run on CuPy, and any run on torch's CUDA device, is not
measured yet.

Validated against analytic oracles: P- and S-wave times of flight
$c_\mathrm{P} = \sqrt{(\lambda + 2\mu) / \rho}$ and
$c_\mathrm{S} = \sqrt{\mu / \rho}$, the
Rayleigh-wave speed from the exact characteristic equation (Cremer, Heckl &
Petersson 2005, Eq. 3.149), the Kirchhoff thin-plate flexural dispersion
$c_\mathrm{B} = (B'/m'')^{1/4} \sqrt{\omega}$ in its $\lambda_\mathrm{B} \gg h$
domain
(Eqs. 3.83-3.89), the normal-incidence fluid-solid reflection coefficient
$(Z_2 - Z_1)/(Z_2 + Z_1)$, the normal-incidence mass law of a thin
immersed
panel, and the exact reduction to the acoustic solver when `c_s = 0`
everywhere. The fluid-solid coupling is further pinned to the oblique
plane-wave reflection coefficient of Brekhovskikh & Godin, *Acoustics of
Layered Media I* (Springer 1990), Eqs. 4.2.22-4.2.26 (with the shear-wave
mode conversion active), to the Scholte interface-wave speed from the exact
characteristic equation of Eq. 4.4.20 (see [`scholte_speed`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#scholte_speed)), and to
the exact three-media transmission of an immersed plate (B&G Eqs. 2.4.10,
2.4.14) including its first thickness resonance $f_1 = c_\mathrm{P} / (2 h)$
(Eq. 2.4.19), following the fluid-solid finite-difference benchmark of
van Vossen, Robertsson & Chapman, *Geophysics* 67(2), 618-624 (2002).

> Auto-generated from the source docstrings by `scripts/generate_api_docs.py` (`make api-docs`). Do not edit by hand.

## AIR

*Constant* (`phonometry.simulation.elastic_fdtd.Material`).

## ALUMINUM

*Constant* (`phonometry.simulation.elastic_fdtd.Material`).

## CONCRETE

*Constant* (`phonometry.simulation.elastic_fdtd.Material`).

## elastic_fdtd_simulation

```python
elastic_fdtd_simulation(
    run: ElasticRun,
    *,
    compute: Compute | None = None,
) -> ElasticFDTDResult
```

Run a deterministic 2D elastic (P-SV) FDTD simulation.

Builds the staggered velocity-stress grid (Virieux 1986, Eq. 5), applies
the requested boundary conditions, injects the sources and integrates
for `duration_s` seconds, recording the selected fields at every probe
each time step and, optionally, full-field snapshots.

The grid covers `(nx * dx, ny * dx)` metres; a cell index `(ix, iy)`
maps to the physical cell centre `((ix + 0.5) * dx, (iy + 0.5) * dx)`.
Resolve at least 10 cells per shortest wavelength
($\Delta x \le c_{\mathrm{s},\min} / (10 f)$ with `c_s_min` the smallest
non-zero
`c_s` over the solid cells, since the S wave is always the shortest;
a wholly fluid map falls back to the acoustic rule on the smallest
`c_p`; Virieux's rule from the dispersion relations
Eqs. 13-14), and 15-20 cells per wavelength when a Rayleigh wave along a
free surface matters, the second-order stress-imaging surface being the
most dispersive part of the scheme. The simulation is 2D (plane strain):
a point source is physically a line source with cylindrical
$1/\sqrt{r}$ amplitude spreading.

**Parameters**

| Name | Description |
| :--- | :--- |
| `run` | The simulation ([`ElasticRun`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrun)): the domain, its sources and what it records, every argument checked when the run was built. |
| `compute` | Where the run steps ([`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute)); `None` follows [`use`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#use), then `PHONOMETRY_COMPUTE`, then NumPy. With a `host` the whole run goes to that node, named in the hosts file, and comes back as this function's record (see the guide on remote nodes). |

**Returns:** An [`ElasticFDTDResult`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtdresult).

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | For a `run` that is not an [`ElasticRun`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrun), a `compute` that is neither a [`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute) nor `None`, or, when `compute` names a host, a run that cannot travel to a node: an [`ExplosionSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#explosionsource) or a [`ForceSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#forcesource) whose waveform is a callable other than the `value` of a [`GaussianPulse`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#gaussianpulse), [`CWSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#cwsource) or [`SignalSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#signalsource), a subclass of one of the library's records, a whole number outside the range of an int64, a number or an array of floats wider than 64 bits (a `longdouble`), or a `Fraction` or a `Decimal` the run keeps as given, such as `dx=Fraction(1, 100)`; and, as the run steps, for a waveform that returns anything but one real number. |
| ValueError | For a `PHONOMETRY_COMPUTE` that does not parse, a hosts file that cannot be read or is malformed, or snapshots that would take more bytes than a NumPy array can hold in the run's dtype, refused before the run steps; and, as the run steps, for a waveform that returns a number too large for a float. |
| KeyError | For a `host` the hosts file does not name. |
| ComputeImportError | When the device's library is not installed or does not import, unless `fallback=True`. |
| ComputeDeviceError | When the device is not present, or fails a first small computation, unless `fallback=True`. |
| ComputeRemoteError | For a failure of the connection or of the node, unless `fallback=True`. |

**Warns**

| Warning | When |
| :--- | :--- |
| ComputeFallbackWarning | When `fallback=True` turns a [`ComputeImportError`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#computeimporterror), a [`ComputeDeviceError`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#computedeviceerror) or a [`ComputeRemoteError`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#computeremoteerror) into a run on NumPy here. |

## ElasticBoundaries

```python
ElasticBoundaries(
    *,
    sides: Literal['rigid', 'absorbing', 'free'] | Mapping[Literal['left', 'right', 'top', 'bottom'], Literal['rigid', 'absorbing', 'free']] = 'rigid',
    absorbing_layer_cells: int | np.integer[Any] = 20,
)
```

How the four edges of the elastic domain are terminated.

The sponge thickness only means anything where a side is absorbing, which
is why it travels with the sides rather than beside them.

**Parameters**

| Name | Description |
| :--- | :--- |
| `sides` | `"rigid"` (default), `"absorbing"`, `"free"`, or a mapping from side name (`left`/`right`/`top`/`bottom`) to one of those. A mapping is held as a read-only copy, so a change to the caller's dictionary afterwards does not reach the record. |
| `absorbing_layer_cells` | Sponge-layer thickness for absorbing sides, in cells, held as the whole number it names. |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | for `sides` that are neither a name nor a mapping, a side or a termination of `sides` that is not a text, or an `absorbing_layer_cells` that is a flag, a text, an array or anything else that is not a number. |
| ValueError | for a side that is not `"left"`, `"right"`, `"top"` or `"bottom"`, a termination that is not `"rigid"`, `"absorbing"` or `"free"`, or an `absorbing_layer_cells` that is not a whole number. |

## ElasticFDTD2D

```python
ElasticFDTD2D(
    *,
    c_p: NumericArrayLike,
    c_s: NumericArrayLike,
    dx: float,
    rho: NumericArrayLike,
    cfl: float = 0.6,
    absorbing_layer_cells: int | np.integer[Any] = 0,
    absorbing_sides: Literal['left', 'right', 'top', 'bottom'] | Iterable[Literal['left', 'right', 'top', 'bottom']] | None = None,
    absorbing_layer_reflection: float = 0.0001,
    damping: NumericArrayLike = 0.0,
    shape: Sequence[int | np.integer[Any]] | NDArray[np.integer[Any]] | None = None,
    free_sides: Literal['left', 'right', 'top', 'bottom'] | Iterable[Literal['left', 'right', 'top', 'bottom']] | None = None,
    obstacle_mask: NumericArrayLike | None = None,
    compute: Compute | None = None,
)
```

2D elastic (P-SV) FDTD stepping engine on a staggered grid.

The Virieux (1986) cell is shifted half a cell so it lands on the layout
of the acoustic [`FDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#fdtd2d): the normal
stresses `txx` and `tyy` share the cell centres, shape `(ny, nx)`
(row = y, column = x, the `imshow` convention; Virieux's downward z is
the growing row here); `vx` lives at interior x-faces, shape
`(ny, nx - 1)`; `vy` at interior y-faces, shape `(ny - 1, nx)`;
the shear stress `txy` at interior corners, shape `(ny - 1, nx - 1)`.
Because only interior faces are stored, the domain boundary has zero
normal velocity by construction and, with the corner shear stress taken
as zero on the edge, is a shear-free rigid wall; `free_sides` turns
selected sides into traction-free surfaces via stress imaging and sponge
layers into absorbing ones. Material maps are given as the measurable
wave speeds and converted internally to the Lame parameters
$\mu = \rho c_\mathrm{S}^2$ and
$\lambda = \rho (c_\mathrm{P}^2 - 2 c_\mathrm{S}^2)$;
density is
arithmetically averaged onto the faces and `mu` harmonically averaged
onto the corners (zero whenever any neighbour is a fluid), the Moczo
et al. (2007) effective parameters (Eqs. 7.37-7.39) that make internal
interfaces converge to the physical traction continuity.

The five fields, the synthetic pressure `p` and what
`collocated` returns are arrays of the library the engine steps
on, not NumPy arrays: a NumPy array on NumPy, a CuPy array on CuPy and a
tensor on PyTorch, typed `Any` for a type checker since no one array
type covers the three. Reading one in place keeps it on the device, and
`numpy_field` gives a NumPy copy of a stored field, typed as an
array of floats, on every device.

**Parameters**

| Name | Description |
| :--- | :--- |
| `c_p` | P-wave speed map [m/s], shape `(ny, nx)`. A scalar with an explicit `shape` is also accepted. |
| `c_s` | S-wave speed map [m/s]; scalar or `(ny, nx)` array. `c_s = 0` marks a fluid cell (the acoustic limit); every cell must satisfy $c_\mathrm{P}^2 \ge 2 c_\mathrm{S}^2$ (non-negative `lambda`). |
| `dx` | Grid spacing [m] (square cells). |
| `rho` | Density map [kg/m3]; scalar or `(ny, nx)` array. |
| `cfl` | Courant number $C_\mathrm{N} = c_{\mathrm{p},\max}\, \Delta t \sqrt{2} / \Delta x$; the scheme is stable for $C_\mathrm{N} < 1$ (Virieux Eqs. 6-7, a bound on `c_P` alone, independent of `c_S` and of the Poisson ratio) and values in `(0, 1)` are accepted. The default 0.6 keeps a wide stability margin with moderate numerical dispersion. |
| `absorbing_layer_cells` | Thickness of the absorbing (sponge) layer, in cells (default 0, no layer and no absorbing side). |
| `absorbing_sides` | Which sides absorb: a single side name or an iterable drawn from `{"left", "right", "top", "bottom"}` (default: all four when `absorbing_layer_cells > 0`). |
| `absorbing_layer_reflection` | Target round-trip amplitude reflection of the sponge layer; sets the peak absorption rate. |
| `damping` | Bulk amplitude decay rate [1/s]: a scalar for the whole field or an `(ny, nx)` map for locally lossy regions. |
| `shape` | Grid shape `(ny, nx)`, required only when `c_p` is a scalar; beside a map it must be the map's own shape. |
| `free_sides` | Sides carrying a traction-free surface (stress imaging, Moczo et al. Eq. 9.9): a single side name or an iterable drawn from `{"left", "right", "top", "bottom"}` (default: none). The surface plane runs through the boundary row/column of cell centres, the normal stress is pinned to zero there and the shear stress is imaged antisymmetrically above it. A side cannot be both free and absorbing. |
| `obstacle_mask` | Boolean map, shape `(ny, nx)`, of rigid cells: every face adjacent to a masked cell is closed (zero normal velocity) and every touching corner shear stress is zeroed, i.e. a shear-free rigid inclusion, rasterising arbitrary interior geometry. |
| `compute` | Where the engine steps ([`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute)); `None` follows [`use`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#use), then `PHONOMETRY_COMPUTE`, then NumPy. |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `cfl`, `dx` or `absorbing_layer_reflection` is not a single real number, `c_p`, `c_s`, `rho` or `damping` holds a complex number or a text, `absorbing_layer_cells` is a flag, a text or an array where a count goes, `shape` is not a pair or holds a count that is not a number, a side of `absorbing_sides` or `free_sides` is not a text, or `compute` is neither a [`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute) nor `None`. |
| ValueError | for an argument out of its range, a `dx`, a `cfl` and a fastest speed of `c_p` that give a time step past a float's range (zero or infinite), a `shape` given beside a map of another shape, a side that is not `"left"`, `"right"`, `"top"` or `"bottom"`, and for a `compute` that names a host: an engine steps in this process, and only [`elastic_fdtd_simulation`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elastic_fdtd_simulation) and [`write_elastic_fdtd_animation`](https://docs.jmrp.io/phonometry/reference/api/simulation/video/#write_elastic_fdtd_animation) run on a node. |
| ComputeImportError | when the library of the device `compute` asks for is not installed or does not import, unless `fallback=True`. |
| ComputeDeviceError | when that device is not present, or fails a first small computation, unless `fallback=True`. |

**Warns**

| Warning | When |
| :--- | :--- |
| ComputeFallbackWarning | with `fallback=True`, when the device's library does not import or the device is absent or fails its first computation; the engine then steps on NumPy. |

### ElasticFDTD2D.add_source()

```python
ElasticFDTD2D.add_source(source: ExplosionSource | ForceSource) -> None
```

Register an [`ExplosionSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#explosionsource) or a [`ForceSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#forcesource).

Explosions inject additively at one cell centre; forces at one
staggered velocity node. Positions are validated against the grid
and the obstacle mask.

### ElasticFDTD2D.collocated()

```python
ElasticFDTD2D.collocated(field: Literal['p', 'vx', 'vy']) -> Any
```

One field interpolated to the cell centres, shape `(ny, nx)`.

`"p"` is the synthetic pressure; `"vx"`/`"vy"` average the two
adjacent faces (domain-edge faces count as zero, their built-in
value), so probes and snapshots of every field share the cell-centre
positions. The result is on the engine's device, where the fields
live: a NumPy array by default, the backend's own array on another
device; `numpy_field` gives NumPy copies of the stored fields.

**Parameters**

| Name | Description |
| :--- | :--- |
| `field` | One of `"p"`, `"vx"` or `"vy"`. |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `field` is not a text. |
| ValueError | if `field` is not `"p"`, `"vx"` or `"vy"`. |

### ElasticFDTD2D.energy()

```python
ElasticFDTD2D.energy() -> float
```

Total elastic field energy [J per metre of depth].

Kinetic energy plus the plane-strain elastic energy expressed in
stresses by inverting the 2D stiffness (determinant
$4 \mu (\lambda + \mu)$); fluid cells (`mu = 0`) degenerate
to the acoustic $p^2 / (2 \lambda)$ and shear-free corners
contribute nothing.

### ElasticFDTD2D.from_regions()

*classmethod*

```python
ElasticFDTD2D.from_regions(
    shape: Sequence[int | np.integer[Any]] | NDArray[np.integer[Any]],
    dx: float,
    *,
    background: Material | CatalogueRow | tuple[float, float, float],
    regions: Iterable[tuple[Any, Material | CatalogueRow | tuple[float, float, float]]] = (),
    cfl: float = 0.6,
    absorbing_layer_cells: int | np.integer[Any] = 0,
    absorbing_sides: Literal['left', 'right', 'top', 'bottom'] | Iterable[Literal['left', 'right', 'top', 'bottom']] | None = None,
    absorbing_layer_reflection: float = 0.0001,
    damping: NumericArrayLike = 0.0,
    free_sides: Literal['left', 'right', 'top', 'bottom'] | Iterable[Literal['left', 'right', 'top', 'bottom']] | None = None,
    obstacle_mask: NumericArrayLike | None = None,
    compute: Compute | None = None,
) -> ElasticFDTD2D
```

Build the engine from named materials painted over a background.

Thin sugar over the map constructor for the common layered set-ups
(fluid over a solid half-space, an immersed plate, an inclusion):
the `(ny, nx)` maps of `c_p`, `c_s` and `rho` start uniform
at `background` and each `(where, material)` entry of
`regions` is painted over them in order (later entries overwrite
earlier ones), then everything is delegated to the normal
constructor. No new physics: a fluid-solid contact still needs no
explicit interface treatment, because the constructor's effective
parameters (Moczo et al. 2007, Eqs. 7.37-7.39) handle it from the
maps alone.

`where` selects the painted cells: a boolean `(ny, nx)` mask,
or any basic numpy index expression over the `(row, column)`
maps, e.g. `(slice(120, None), slice(None))` for the lower half
or `numpy.s_[120:, :]` for the same thing spelled as a slice.

**Parameters**

| Name | Description |
| :--- | :--- |
| `shape` | Grid shape `(ny, nx)`, a pair of whole numbers of at least two cells each. |
| `dx` | Grid spacing [m] (square cells). |
| `background` | The material filling the whole grid first: a [`Material`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#material), a `(c_p, c_s, rho)` triple, e.g. [`WATER`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#water), or a solid's catalogue row ([`SolidMaterial`](https://docs.jmrp.io/phonometry/reference/api/solids/catalogue/#solidmaterial)), whose bulk longitudinal speed, transverse speed and density are read through [`printed`](https://docs.jmrp.io/phonometry/reference/api/io/io/#cataloguerowprinted). |
| `regions` | `(where, material)` pairs painted in order, each material taken in any of the forms `background` takes. |
| `cfl` | Courant number, as [`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d) takes it. |
| `absorbing_layer_cells` | Thickness of the absorbing (sponge) layer, in cells (default 0, no layer). |
| `absorbing_sides` | Which sides absorb, as [`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d) takes them. One of `"left"`, `"right"`, `"top"` or `"bottom"`. Each one of `"left"`, `"right"`, `"top"` or `"bottom"`. |
| `absorbing_layer_reflection` | Target round-trip amplitude reflection of the sponge layer. |
| `damping` | Bulk amplitude decay rate [1/s], a scalar or an `(ny, nx)` map. |
| `free_sides` | Sides carrying a traction-free surface. One of `"left"`, `"right"`, `"top"` or `"bottom"`. Each one of `"left"`, `"right"`, `"top"` or `"bottom"`. |
| `obstacle_mask` | Boolean `(ny, nx)` map of rigid cells. |
| `compute` | Where the engine steps ([`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute)). |

**Returns:** The configured stepping engine.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `shape` is not two whole numbers of two cells or more, a mask does not match `shape` or a material spec is invalid, a catalogue row's refusal among them, an option out of the range [`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d) takes, or `compute` names a host: the engine steps in this process. |
| TypeError | For a `shape` that is not a pair or holds a count that is not a number (a text, a `bytes` or a `bytearray` among them), a `dx` that is not one real number, a material's speed or density that is a complex number or a text, a mask array that is not boolean, a catalogue row of a class that lacks any of the bulk longitudinal speed, the transverse speed and the density, an option of a type [`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d) refuses (`cfl`, `absorbing_layer_cells`, `absorbing_sides`, `absorbing_layer_reflection`, `damping`, `free_sides`), or a `compute` that is neither a [`Compute`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#compute) nor `None`. |
| ComputeImportError | When the library of the device `compute` asks for is not installed or does not import, unless `fallback=True`. |
| ComputeDeviceError | When that device is not present, or fails a first small computation, unless `fallback=True`. |

**Warns**

| Warning | When |
| :--- | :--- |
| ComputeFallbackWarning | With `fallback=True`, when the device's library does not import or the device is absent or fails its first computation, pointing at the line that called this method; the engine then steps on NumPy. |

### ElasticFDTD2D.numpy_field()

```python
ElasticFDTD2D.numpy_field(
    field: Literal['txx', 'tyy', 'txy', 'vx', 'vy'],
) -> NDArray[np.floating[Any]]
```

A NumPy copy of the stored *field*, in this process, whatever the device.

**Parameters**

| Name | Description |
| :--- | :--- |
| `field` | `"txx"` or `"tyy"` (cell centres), `"txy"` (interior corners), `"vx"` or `"vy"` (faces). |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `field` is not a text. |
| ValueError | for a field the engine does not store. |

### ElasticFDTD2D.p

*property*

Synthetic pressure `-(txx + tyy) / 2` at cell centres [Pa].

The mean compressive normal stress: in fluid (`c_s = 0`) regions
it is exactly the acoustic pressure, and in solids it is the
convenient scalar for probes and snapshots. It is computed on the
engine's device, where the stresses live: a NumPy array by default,
the backend's own array on another device; `numpy_field` gives
NumPy copies of the stresses it is built from.

### ElasticFDTD2D.provenance

*property*

Where this engine steps: device, dtype and library versions.

### ElasticFDTD2D.run()

```python
ElasticFDTD2D.run(
    n_steps: int | np.integer[Any],
    *,
    snapshot_every: int | np.integer[Any] | None = None,
    snapshot_decimation: int | np.integer[Any] = 1,
) -> NDArray[np.floating[Any]]
```

Advance `n_steps` steps, optionally recording pressure frames.

With `snapshot_every = k` a NumPy copy of the synthetic pressure
`p` is stored after every `k`-th step (and one of the initial
state), keeping every `snapshot_decimation`-th cell along each
axis; the stacked `(n_frames, ny', nx')` array plugs straight into
a `FuncAnimation` `imshow` update. Without `snapshot_every` an
empty array is returned and only the final state is kept (read it
with `numpy_field`). The two counts are taken by name, as
[`ElasticRecording`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrecording) takes them.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `snapshot_decimation`, `n_steps` or `snapshot_every` is a flag, a text or an array where a count goes, or the waveform of an [`ExplosionSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#explosionsource) or a [`ForceSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#forcesource) returns anything but one real number. |
| ValueError | if `n_steps` is not a whole number of 0 or more, `snapshot_every` or `snapshot_decimation` is not a whole number of 1 or more, the frames would take more bytes than a NumPy array can hold, or such a waveform returns a number too large for a float. |

### ElasticFDTD2D.step()

```python
ElasticFDTD2D.step() -> None
```

Advance the leapfrog scheme by one time step (Virieux Eq. 5).

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if the waveform of an [`ExplosionSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#explosionsource) or a [`ForceSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#forcesource) returns anything but one real number. |
| ValueError | if such a waveform returns a number too large for a float. |

### ElasticFDTD2D.time

*property*

Elapsed simulated time [s].

## ElasticFDTDResult

```python
ElasticFDTDResult(
    times: NDArray[np.float64],
    signals: NDArray[np.float64],
    probe_fields: tuple[Literal['p', 'vx', 'vy'], ...],
    probes: NDArray[np.int_],
    probe_positions: NDArray[np.float64],
    dx: float,
    dt: float,
    shape: tuple[int, int],
    sources: tuple[ExplosionSource | ForceSource, ...],
    snapshots: NDArray[np.floating[Any]] | None,
    snapshot_times: NDArray[np.float64] | None,
    snapshot_field: Literal['p', 'vx', 'vy'],
    obstacle_mask: NDArray[np.bool_] | None,
    free_sides: tuple[Literal['left', 'right', 'top', 'bottom'], ...],
    snapshot_decimation: int,
    provenance: RunProvenance,
)
```

Frozen result of an [`elastic_fdtd_simulation`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elastic_fdtd_simulation) run.

**Attributes**

| Name | Description |
| :--- | :--- |
| `times` | Time axis [s], length `n_steps + 1` (includes $t = 0$). |
| `signals` | Recorded histories, shape `(n_probes, n_fields, n_steps + 1)`, one row per probe and one layer per entry of `probe_fields` (velocities are interpolated to the probe cell centre). |
| `probe_fields` | The recorded fields, drawn from `("p", "vx", "vy")`. |
| `probes` | Probe cell indices `(ix, iy)`, shape `(n_probes, 2)`. |
| `probe_positions` | Probe cell-centre positions `(x, y)` [m], shape `(n_probes, 2)`. |
| `dx` | Grid spacing [m]. |
| `dt` | Time step [s]. |
| `shape` | Grid shape `(ny, nx)`. |
| `sources` | The source definitions of the run. |
| `snapshots` | Recorded cell-centre fields of `snapshot_field`, shape `(n_frames, ceil(ny / d), ceil(nx / d))` with `d` the `snapshot_decimation`, in the dtype the run stepped in, or `None` when no snapshots were requested. |
| `snapshot_times` | Time of each snapshot [s], or `None`. |
| `snapshot_field` | The field recorded in `snapshots`. One of `"p"`, `"vx"` or `"vy"`. |
| `obstacle_mask` | Boolean map of rigid cells, or `None`. |
| `free_sides` | Sides carrying a traction-free surface. Each one of `"left"`, `"right"`, `"top"` or `"bottom"`. |
| `snapshot_decimation` | Every how many cells a snapshot keeps along each axis (1 keeps every cell). |
| `provenance` | Where the run stepped ([`RunProvenance`](https://docs.jmrp.io/phonometry/reference/api/simulation/compute/#runprovenance)). |

### ElasticFDTDResult.plot()

```python
ElasticFDTDResult.plot(
    ax: Axes | None = None,
    *,
    kind: Literal['probes', 'snapshot'] = 'probes',
    frame: int = -1,
    language: Literal['en', 'es'] = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the probe histories or one recorded field snapshot.

**Parameters**

| Name | Description |
| :--- | :--- |
| `ax` | Existing axes, or `None` to create a figure. |
| `kind` | `"probes"` (default) draws the per-probe signal time histories; `"snapshot"` renders one recorded field with the geometry overlaid (`imshow` raster). |
| `frame` | Snapshot index for `kind="snapshot"` (default: the last recorded frame). |
| `language` | Label language, `"en"` (default) or `"es"`. |
| `kwargs` | Forwarded to the underlying `plot`/`imshow`. |

**Returns:** The axes.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | for a `kind` that is not a text, or `color_limit` with `kind="snapshot"`, which the field drawn sets (`vmin` and `vmax` reach `imshow`). |
| ValueError | for a `kind` other than `"probes"` and `"snapshot"`, a `language` other than `"en"` and `"es"`, or a snapshot asked of a result that holds none. |

### ElasticFDTDResult.size

*property*

Domain size `(lx, ly)` [m].

## ElasticRecording

```python
ElasticRecording(
    *,
    probes: Sequence[Sequence[int | np.integer[Any]]] | NDArray[np.integer[Any]] = (),
    probe_fields: Literal['p', 'vx', 'vy'] | Sequence[Literal['p', 'vx', 'vy']] = ('vy',),
    snapshot_every: int | np.integer[Any] | None = None,
    snapshot_field: Literal['p', 'vx', 'vy'] = 'p',
    snapshot_decimation: int | np.integer[Any] = 1,
)
```

What an elastic run writes down: probe traces and field snapshots.

The two ways out of a running simulation. Probes record a time history at
named cells, one trace per field of `probe_fields`; snapshots record the
whole domain every `snapshot_every` steps for one field. Recording
nothing (the default) runs the physics and keeps only the time axis.

**Parameters**

| Name | Description |
| :--- | :--- |
| `probes` | Probe cells as `(ix, iy)` index pairs. |
| `probe_fields` | Which fields each probe records, drawn from `("p", "vx", "vy")` (default `("vy",)`, the component a surface accelerometer would see); a single name records that field alone. |
| `snapshot_every` | Record a full field snapshot every this many steps (and at $t = 0$); `None` records none. |
| `snapshot_field` | Field recorded in the snapshots (`"p"`/`"vx"`/`"vy"`, interpolated to cell centres). |
| `snapshot_decimation` | Keep every this many cells along each axis in a snapshot (default 1, every cell); the result records it. |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | for a probe that is not a pair or has an index that is not a number, a field of `probe_fields` or a `snapshot_field` that is not a text, a `snapshot_every` that is a flag, a text, an array or anything else that is neither a number nor `None`, or a `snapshot_decimation` that is a flag, a text, an array or anything else that is not a number. |
| ValueError | for `probe_fields` that are empty, repeat a field or name one that is not `"p"`, `"vx"` or `"vy"`, a `snapshot_field` that is none of them, a probe of more or fewer than two indices or with an index that is not a whole number, or a `snapshot_every` or `snapshot_decimation` that is not a whole number of 1 or more. |

## ElasticRun

```python
ElasticRun(
    *,
    c_p: NumericArrayLike,
    c_s: NumericArrayLike,
    dx: float,
    duration_s: float,
    sources: Sequence[ExplosionSource | ForceSource],
    rho: NumericArrayLike,
    shape: Sequence[int | np.integer[Any]] | NDArray[np.integer[Any]] | None = None,
    cfl: float = 0.6,
    recording: ElasticRecording | None = None,
    boundaries: ElasticBoundaries | None = None,
    obstacle_mask: NumericArrayLike | None = None,
    damping: NumericArrayLike = 0.0,
)
```

One elastic (P-SV) FDTD simulation: the domain, its sources and what it records.

As [`FDTDRun`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#fdtdrun), for
[`elastic_fdtd_simulation`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elastic_fdtd_simulation): every argument is checked when the run
is built, the grid's included (the time step, the shear speed against
the P-wave speed, the density, the sponge and the damping, the free and
absorbing sides, the obstacle, and the sources and the probes on the
grid), and nothing the caller changes afterwards reaches a checked run.

**Parameters**

| Name | Description |
| :--- | :--- |
| `c_p` | P-wave speed map [m/s], shape `(ny, nx)`, or a scalar with an explicit `shape`. |
| `c_s` | S-wave speed map [m/s]; `c_s = 0` marks fluid cells. |
| `dx` | Grid spacing [m] (square cells). |
| `duration_s` | Physical time to simulate [s]. |
| `sources` | One or more of [`ExplosionSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#explosionsource) or [`ForceSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#forcesource). |
| `rho` | Density map [kg/m3]; scalar or `(ny, nx)` array. |
| `shape` | Grid shape `(ny, nx)`, required when `c_p` is scalar; beside a map it must be the map's own shape. |
| `cfl` | Courant number in `(0, 1)` (Virieux Eqs. 6-7); the time step is $\Delta t = C_\mathrm{N}\, \Delta x / (c_{\mathrm{p},\max} \sqrt{2})$. Default 0.6. |
| `recording` | What the run records ([`ElasticRecording`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrecording)): the probe cells and their fields, and the snapshot cadence and field. `None` records nothing but the time axis. |
| `boundaries` | How the domain edges are terminated ([`ElasticBoundaries`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticboundaries)); `None` is rigid on all four sides. |
| `obstacle_mask` | Boolean map, shape `(ny, nx)`, of rigid cells (rasterised interior geometry). |
| `damping` | Bulk amplitude decay rate [1/s]: a scalar for the whole field or an `(ny, nx)` map. |

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | If an argument is of the wrong type, among them a `cfl` or `dx` that is not one number, a `recording` that is neither an [`ElasticRecording`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticrecording) nor `None`, `boundaries` that are neither an [`ElasticBoundaries`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticboundaries) nor `None`, a `shape` that is not a pair or holds a count that is not a number, or a medium (`c_p`, `c_s`, `rho`, `damping`) that holds a complex number or a text. |
| ValueError | If an argument is out of its range, a `dx`, a `cfl` and a fastest speed of `c_p` give a time step past a float's range (zero or infinite), a `shape` is not two whole numbers of two cells or more or is given beside a map of another shape, a source, a probe or the obstacle does not fit the grid, or the `duration_s` covers more steps than the record holds: its time axis or its probe history would take more bytes than a NumPy array can hold. |

## ExplosionSource

```python
ExplosionSource(
    *,
    ix: int | np.integer[Any],
    iy: int | np.integer[Any],
    waveform: Callable[[float], float],
    amplitude: float = 1.0,
)
```

An isotropic (explosive) stress injection at one cell centre.

Virieux (1986) drives an explosion with equal increments on both normal
stresses at their shared node, which avoids the infinite amplitudes of a
velocity-node source. The sign convention here is pressure-like: the
waveform value is the injected compression, added as `-s(t)` to both
`txx` and `tyy` so the synthetic pressure
$p = -(t_{xx} + t_{yy})/2$ increases with a positive waveform (and
a `c_s = 0` run reproduces the acoustic solver driven by the same
waveform, sample by sample).

`waveform` maps time in seconds to the injected pressure in pascals:
any callable, typically the `value` method of a
[`GaussianPulse`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#gaussianpulse),
[`CWSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#cwsource) or
[`SignalSource`](https://docs.jmrp.io/phonometry/reference/api/simulation/fdtd/#signalsource) (their own `ix`/`iy`
are not used here).

**Attributes**

| Name | Description |
| :--- | :--- |
| `ix` | Source column (x) index; the cell centre is at $x = (i_x + 0.5)\,\Delta x$. |
| `iy` | Source row (y) index. |
| `waveform` | Callable `t -> s(t)` in pascals. |
| `amplitude` | Extra gain applied to `waveform`. |

## ForceSource

```python
ForceSource(
    *,
    ix: int | np.integer[Any],
    iy: int | np.integer[Any],
    direction: Literal['x', 'y'],
    waveform: Callable[[float], float],
    amplitude: float = 1.0,
)
```

A directional body-force injection at one velocity node.

The standard body-force term of the equation of motion (the `f` of the
Moczo et al. 2007 formulation): each step the target velocity component
receives `dt * f(t) / (rho * dx**2)`, i.e. `waveform` is a line
force per unit depth [N/m] spread over one cell. A vertical force just
below a free surface reproduces Lamb's problem and launches the Rayleigh
wave (Virieux 1986, Fig. 5).

`ix`/`iy` index the staggered velocity array directly: for
`direction = "x"` the x-face between cells `ix` and `ix + 1`
(position `((ix + 1) * dx, (iy + 0.5) * dx)`), for
`direction = "y"` the y-face between rows `iy` and `iy + 1`
(position `((ix + 0.5) * dx, (iy + 1) * dx)`).

**Attributes**

| Name | Description |
| :--- | :--- |
| `ix` | Source column index into the velocity array. |
| `iy` | Source row index into the velocity array. |
| `direction` | `"x"` (horizontal) or `"y"` (vertical, positive downward in the `imshow` axes). |
| `waveform` | Callable `t -> f(t)` in newtons per metre of depth. |
| `amplitude` | Extra gain applied to `waveform`. |

## Material

```python
Material(*, c_p: float, c_s: float, rho: float)
```

An isotropic elastic medium as measurable wave speeds and density.

The three numbers the solver's material maps are built from: the
compressional speed $c_\mathrm{P} = \sqrt{(\lambda + 2\mu) / \rho}$,
the shear
speed $c_\mathrm{S} = \sqrt{\mu / \rho}$ and the density `rho`.
`c_s = 0`
marks a fluid (the acoustic `mu = 0` limit of the elastic scheme,
Virieux 1986), so the same dataclass names both fluids and solids.
Every material must satisfy $c_\mathrm{P}^2 \ge 2 c_\mathrm{S}^2$
(non-negative first
Lame parameter), the constructor bound of [`ElasticFDTD2D`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#elasticfdtd2d).

The module constants [`AIR`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#air), [`WATER`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#water), [`STEEL`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#steel),
[`ALUMINUM`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#aluminum) and [`CONCRETE`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#concrete) carry the nominal round-number
properties used throughout the documentation and the validation suite,
mirroring the documented default media of the acoustic solver.

Wherever a [`Material`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#material) is taken, a solid's catalogue row is taken
too, one of [`PUBLISHED_SOLIDS`](https://docs.jmrp.io/phonometry/reference/api/solids/catalogue/#published_solids) or one read from
a catalogue file of your own: its bulk longitudinal speed, its transverse
speed and its density are read through
[`printed`](https://docs.jmrp.io/phonometry/reference/api/io/io/#cataloguerowprinted), which refuses a cell the
page does not print, in the page's own terms. The plate and bar speeds a
table prints beside them are never read, because they are not the bulk
speed this solver integrates.

**Attributes**

| Name | Description |
| :--- | :--- |
| `c_p` | Compressional (P) wave speed [m/s], strictly positive. |
| `c_s` | Shear (S) wave speed [m/s], non-negative; 0 marks a fluid. |
| `rho` | Density [kg/m3], strictly positive. |

### Material.is_fluid

*property*

`True` when the material carries no shear (`c_s = 0`).

## scholte_speed

```python
scholte_speed(
    fluid: Material | CatalogueRow | tuple[float, float, float],
    solid: Material | CatalogueRow | tuple[float, float, float],
) -> float
```

Exact Scholte-wave speed of a fluid over an elastic half-space [m/s].

The Scholte wave is the true interface wave of a fluid-solid contact:
evanescent on both sides, elliptical particle motion, no low-frequency
cut-off, and non-dispersive over homogeneous half-spaces (Jensen,
Kuperman, Porter & Schmidt, *Computational Ocean Acoustics* 2e,
Sections 4.5.2 and 8.5.4). Its speed `v` lies below both the fluid
sound speed and the solid shear speed, and solves the exact
characteristic equation of Brekhovskikh & Godin, *Acoustics of Layered
Media I* (1990), Eq. 4.4.20, written in the notation of Eq. 4.4.18
($q = c_\mathrm{S}^2/c_\mathrm{P}^2$, $r = c_\mathrm{S}^2/c^2$,
$s = v^2/c_\mathrm{S}^2$,
$m = \rho_{\mathrm{solid}}/\rho_{\mathrm{fluid}}$):

$$
4 \sqrt{1-s} \sqrt{1-qs} - (2-s)^2 = \frac{s^2}{m} \sqrt{\frac{1-sq}{1-sr}}
$$

A root always exists (B&G Section 4.4.3); the $m \to \infty$
limit of the left side is the Rayleigh equation. For stiff beds the
root hugs the fluid speed (water over steel: 1479.6 m/s, 0.027 % below
`c`) while for soft sediments it drops well below it, which is why
measured seabed interface waves probe the sediment shear speed
($v \approx 0.85 c_\mathrm{S}$ rule, Jensen et al. Section 5.10.5).

**Parameters**

| Name | Description |
| :--- | :--- |
| `fluid` | Fluid half-space: a [`Material`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#material) with `c_s = 0` (or a `(c_p, 0.0, rho)` triple). |
| `solid` | Elastic half-space: a [`Material`](https://docs.jmrp.io/phonometry/reference/api/simulation/elastic-fdtd/#material) with `c_s > 0`, a `(c_p, c_s, rho)` triple or a solid's catalogue row ([`SolidMaterial`](https://docs.jmrp.io/phonometry/reference/api/solids/catalogue/#solidmaterial)), whose bulk longitudinal speed, transverse speed and density are read through [`printed`](https://docs.jmrp.io/phonometry/reference/api/io/io/#cataloguerowprinted). |

**Returns:** The Scholte-wave phase speed [m/s].

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `fluid` carries shear or `solid` does not, or a row does not print one of the three numbers, in the row's terms. |
| TypeError | For a catalogue row of a class that lacks any of the bulk longitudinal speed, the transverse speed and the density. |

## STEEL

*Constant* (`phonometry.simulation.elastic_fdtd.Material`).

## WATER

*Constant* (`phonometry.simulation.elastic_fdtd.Material`).
