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 = 0limit: 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).
ALUMINUM
Section titled “ALUMINUM”Constant (phonometry.simulation.elastic_fdtd.Material).
CONCRETE
Section titled “CONCRETE”Constant (phonometry.simulation.elastic_fdtd.Material).
elastic_fdtd_simulation
Section titled “elastic_fdtd_simulation”elastic_fdtd_simulation( run: ElasticRun, *, compute: Compute | None = None,) -> ElasticFDTDResultRun 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
Section titled “ElasticBoundaries”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
Section titled “ElasticFDTD2D”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()
Section titled “ElasticFDTD2D.add_source()”ElasticFDTD2D.add_source(source: ExplosionSource | ForceSource) -> NoneRegister 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()
Section titled “ElasticFDTD2D.collocated()”ElasticFDTD2D.collocated(field: Literal['p', 'vx', 'vy']) -> AnyOne 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()
Section titled “ElasticFDTD2D.energy()”ElasticFDTD2D.energy() -> floatTotal 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.
ElasticFDTD2D.from_regions()
Section titled “ElasticFDTD2D.from_regions()”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,) -> ElasticFDTD2DBuild 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()
Section titled “ElasticFDTD2D.numpy_field()”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
Section titled “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
Section titled “ElasticFDTD2D.provenance”property
Where this engine steps: device, dtype and library versions.
ElasticFDTD2D.run()
Section titled “ElasticFDTD2D.run()”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()
Section titled “ElasticFDTD2D.step()”ElasticFDTD2D.step() -> NoneAdvance 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. |
ElasticFDTD2D.time
Section titled “ElasticFDTD2D.time”property
Elapsed simulated time [s].
ElasticFDTDResult
Section titled “ElasticFDTDResult”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()
Section titled “ElasticFDTDResult.plot()”ElasticFDTDResult.plot( ax: Axes | None = None, *, kind: Literal['probes', 'snapshot'] = 'probes', frame: int = -1, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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
Section titled “ElasticFDTDResult.size”property
Domain size (lx, ly) [m].
ElasticRecording
Section titled “ElasticRecording”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
Section titled “ElasticRun”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
Section titled “ExplosionSource”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
Section titled “ForceSource”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
Section titled “Material”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. |
Material.is_fluid
Section titled “Material.is_fluid”property
True when the material carries no shear (c_s = 0).
scholte_speed
Section titled “scholte_speed”scholte_speed( fluid: Material | CatalogueRow | tuple[float, float, float], solid: Material | CatalogueRow | tuple[float, float, float],) -> floatExact 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).