Skip to content

simulation.elastic_fdtd

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) and the velocities live on the cell faces;
  • the Courant stability condition (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 takes an ElasticRun, the record of a simulation that checks every argument when it is built, steps it deterministically and returns a frozen ElasticFDTDResult with per-probe signal histories, optional field snapshots and a .plot() method. 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 and , the Rayleigh-wave speed from the exact characteristic equation (Cremer, Heckl & Petersson 2005, Eq. 3.149), the Kirchhoff thin-plate flexural dispersion in its domain (Eqs. 3.83-3.89), the normal-incidence fluid-solid reflection coefficient , 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), 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 (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.

Constant (phonometry.simulation.elastic_fdtd.Material).

Constant (phonometry.simulation.elastic_fdtd.Material).

Constant (phonometry.simulation.elastic_fdtd.Material).

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 ( 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 amplitude spreading.

Parameters

Name Description
run The simulation (ElasticRun): the domain, its sources and what it records, every argument checked when the run was built.
compute Where the run steps (Compute); None follows 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.

Raises

Exception When
TypeError For a run that is not an ElasticRun, a compute that is neither a Compute nor None, or, when compute names a host, a run that cannot travel to a node: an ExplosionSource or a ForceSource whose waveform is a callable other than the value of a GaussianPulse, CWSource or 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, a ComputeDeviceError or a ComputeRemoteError into a run on NumPy here.
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(
*,
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: 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 and ; 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 (non-negative lambda).
dx Grid spacing [m] (square cells).
rho Density map [kg/m3]; scalar or (ny, nx) array.
cfl Courant number ; the scheme is stable for (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); None follows 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 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 and 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(source: ExplosionSource | ForceSource) -> None

Register an ExplosionSource or a 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(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() -> 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 ); fluid cells (mu = 0) degenerate to the acoustic and shear-free corners contribute nothing.

classmethod

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, a (c_p, c_s, rho) triple, e.g. WATER, or a solid’s catalogue row (SolidMaterial), whose bulk longitudinal speed, transverse speed and density are read through printed.
regions (where, material) pairs painted in order, each material taken in any of the forms background takes.
cfl Courant number, as 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 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).

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 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 refuses (cfl, absorbing_layer_cells, absorbing_sides, absorbing_layer_reflection, damping, free_sides), or a compute that is neither a 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(
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.

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.

property

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

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 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 or a 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() -> None

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

Raises

Exception When
TypeError if the waveform of an ExplosionSource or a ForceSource returns anything but one real number.
ValueError if such a waveform returns a number too large for a float.

property

Elapsed simulated time [s].

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

Attributes

Name Description
times Time axis [s], length n_steps + 1 (includes ).
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).
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.

property

Domain size (lx, ly) [m].

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 ); 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(
*,
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, for 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 or 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 . Default 0.6.
recording What the run records (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); 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 nor None, boundaries that are neither an 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(
*,
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 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, CWSource or SignalSource (their own ix/iy are not used here).

Attributes

Name Description
ix Source column (x) index; the cell centre is at .
iy Source row (y) index.
waveform Callable t -> s(t) in pascals.
amplitude Extra gain applied to waveform.
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(*, 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 , the shear speed 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 (non-negative first Lame parameter), the constructor bound of ElasticFDTD2D.

The module constants AIR, WATER, STEEL, ALUMINUM and 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 is taken, a solid’s catalogue row is taken too, one of 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, 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.

property

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

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 (, , , ):

A root always exists (B&G Section 4.4.3); the 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 ( rule, Jensen et al. Section 5.10.5).

Parameters

Name Description
fluid Fluid half-space: a Material with c_s = 0 (or a (c_p, 0.0, rho) triple).
solid Elastic half-space: a Material with c_s > 0, a (c_p, c_s, rho) triple or a solid’s catalogue row (SolidMaterial), whose bulk longitudinal speed, transverse speed and density are read through printed.

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.

Constant (phonometry.simulation.elastic_fdtd.Material).

Constant (phonometry.simulation.elastic_fdtd.Material).