simulation.fdtd
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
2D acoustic finite-difference time-domain (FDTD) simulation.
A staggered-grid (Yee-style) pressure-velocity leapfrog solver for the linear acoustic equations in a non-moving medium, following the reference formulation of Attenborough & Van Renterghem, Predicting Outdoor Sound (2nd ed., CRC Press 2021), chapter 4:
- the governing first-order system in
pandv(Eqs. 4.3-4.4); - the staggered-in-place, staggered-in-time discretisation (Eqs. 4.11-4.12), with pressure at cell centres and velocity components on cell faces;
- the Courant stability condition with (Eqs. 4.13-4.14);
- rigid boundaries as zero normal face velocity (Eq. 4.32) and the frequency-independent real-impedance boundary update (Eqs. 4.33-4.35);
- absorbing edges as a graded sponge layer, the simple precursor of the perfectly-matched-layer treatment discussed in section 4.2.3.
Two API levels are exposed. fdtd_simulation is the result-object
entry point: it takes an FDTDRun, the record of a simulation that
checks every argument when it is built, steps it deterministically and
returns a frozen FDTDResult with per-probe pressure histories,
optional field snapshots and a .plot() method. FDTD2D is the underlying
stepping engine (also used by the documentation animations) for callers that
need frame-by-frame access to the field.
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: the eigenfrequencies of a rigid rectangular box and of an effectively 1D tube, the numerical dispersion relation of the leapfrog scheme (the discrete counterpart of Eq. 4.15), free-field pulse arrival times and cylindrical amplitude decay, the image-source echo of a rigid wall, the normal-incidence reflection coefficient of an impedance edge, and second-order convergence under grid refinement.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
ContourProbe
Section titled “ContourProbe”ContourProbe( engine: FDTD2D, ix0: int | np.integer[Any], ix1: int | np.integer[Any], iy0: int | np.integer[Any], iy1: int | np.integer[Any], frequencies: NumericArrayLike,)On-the-fly DFT of p and v_n on a closed rectangular contour.
Created by FDTD2D.add_contour_probe, or by hand: a probe
registers itself with the engine it is built for, so either way the
engine samples it from its next step, and at every step after for as
long as the engine lives. To integrate another window, call
reset on the same probe rather than building a new one, which
the engine would sample beside it. The contour is the closed
rectangle of cell faces around the cell block ix0..ix1 x
iy0..iy1 (inclusive); on each face the engine samples the outward
normal velocity (which lives exactly there on the staggered grid) and
the pressure averaged from the two adjacent cell centres, and folds
them into running DFT sums at each requested frequency, so a
continuous-wave run never stores full time histories.
After every step the sums gain with
the fields’ own leapfrog time stamps ( for
pressure, for velocity, so the half-step
stagger is handled
exactly). phasors scales the sums by 2 / n_samples into the
steady-state complex amplitudes of the library’s
convention. Accumulate only over the steady state: run the transient
out, call reset, then integrate a window as close as possible
to a whole number of periods (the residual leakage falls as one over
the number of periods).
The sums are kept in float64 on every device that has it, also when the
fields step in float32: the rounding of a sum grows with the number of
steps, and in float32 it would soon outweigh the field’s own. The
exception is torch:mps, which has no float64; there the sums are
float32 with Neumaier’s compensated summation.
Attributes
| Name | Description |
|---|---|
positions |
Face-sample positions (x, y) [m], shape (n_points, 2), ordered left, right, top, bottom face. |
normals |
Outward unit normals of each sample, same shape. |
frequencies |
The tracked frequencies [Hz]. |
Raises
| Exception | When |
|---|---|
| TypeError | if engine is not an FDTD2D, ix0, ix1, iy0 or iy1 is a flag, a text or an array where a count goes, or frequencies holds a complex number or a text. |
ContourProbe.n_samples
Section titled “ContourProbe.n_samples”property
Number of DFT samples accumulated since the last reset, one per step.
ContourProbe.phasors()
Section titled “ContourProbe.phasors()”ContourProbe.phasors(frequency: float) -> ContourPhasorsThe accumulated contour phasors at one tracked frequency.
Parameters
| Name | Description |
|---|---|
frequency |
One of the frequencies the probe was created with, in hertz. |
Returns: A ContourPhasors ready for far_field_from_contour.
Raises
| Exception | When |
|---|---|
| ValueError | If the frequency is past a float’s range, is not tracked, or nothing has been accumulated yet. |
| TypeError | If frequency is not one real number: an array, a text or a complex number, which a lookup through float would read as the number it spells or as its real part. |
ContourProbe.reset()
Section titled “ContourProbe.reset()”ContourProbe.reset() -> NoneClear the running sums (call once the field is steady).
CWSource
Section titled “CWSource”CWSource( *, ix: int | np.integer[Any], iy: int | np.integer[Any], frequency: float, amplitude: float = 1.0, ramp_cycles: float = 3.0,)A continuous sine drive with a smooth cosine-ramped onset.
The first ramp_cycles periods fade the amplitude in with a raised
cosine so the start does not splash a broadband transient over the field.
Attributes
| Name | Description |
|---|---|
ix |
Source column (x) index. |
iy |
Source row (y) index. |
frequency |
Drive frequency [Hz]. |
amplitude |
Steady-state source amplitude [Pa]. |
ramp_cycles |
Onset ramp length in periods of frequency. |
CWSource.value()
Section titled “CWSource.value()”CWSource.value(t: float) -> floatSource waveform at time t (seconds).
Raises
| Exception | When |
|---|---|
| TypeError | if t is anything but one real number: a complex number, a text, an array or None. |
| ValueError | if t is a number too large for a float. |
FDTD2D
Section titled “FDTD2D”FDTD2D( *, c: NumericArrayLike, dx: float, rho: NumericArrayLike = 1.2, 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, edge_impedance: Mapping[Literal['left', 'right', 'top', 'bottom'], NumericArrayLike] | None = None, obstacle_mask: NumericArrayLike | None = None, compute: Compute | None = None,)2D acoustic FDTD stepping engine on a staggered grid.
Pressure p lives at cell centres, shape (ny, nx) (row = y,
column = x, the imshow convention); vx at interior x-faces,
shape (ny, nx - 1); vy at interior y-faces, shape
(ny - 1, nx). Because only interior faces are stored, the domain
boundary is perfectly rigid (zero normal velocity, Eq. 4.32) by
construction; sponge layers and per-cell real impedances turn selected
sides into absorbing or locally reacting boundaries. Sources are soft
(additive) pressure injections.
The three fields 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 it, typed as an array of
floats, on every device.
Parameters
| Name | Description |
|---|---|
c |
Sound-speed map [m/s], shape (ny, nx). A scalar with an explicit shape is also accepted. |
dx |
Grid spacing [m] (square cells). |
rho |
Density map [kg/m3]; scalar or (ny, nx) array (default 1.2). |
cfl |
Courant number (Eq. 4.13); the explicit scheme is stable for (Eq. 4.14) 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). left/right are the low/high column edges and top/bottom the low/high row edges (the default imshow origin). |
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 applied to the whole field (a simple stand-in for air/wall absorption; 6.91 / T60 gives a T60 seconds reverberant decay) or an (ny, nx) map for locally lossy regions, e.g. an equivalent fluid modelling a porous sample (plane waves inside a uniform lossy region follow with the real characteristic impedance ). |
shape |
Grid shape (ny, nx), required only when c is a scalar; beside a map it must be the map’s own shape. |
edge_impedance |
Locally reacting boundary sides: a mapping from side name to a real specific acoustic impedance [Pa s/m], either a scalar or a per-edge-cell 1D array (length ny for left/ right, nx for top/bottom). Implements Eqs. (4.33)-(4.35); is a normal-incidence matched (anechoic) edge. A side cannot be both a sponge and an impedance boundary. |
obstacle_mask |
Boolean map, shape (ny, nx), of rigid cells: every face adjacent to a masked cell is closed (zero normal velocity, Eq. 4.32), 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, 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 edge_impedance is not a text, an impedance of edge_impedance is not a real number or an array of them (a flag, None or a text among them), 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 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 fdtd_simulation and write_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. |
FDTD2D.add_contour_probe()
Section titled “FDTD2D.add_contour_probe()”FDTD2D.add_contour_probe( ix0: int | np.integer[Any], ix1: int | np.integer[Any], iy0: int | np.integer[Any], iy1: int | np.integer[Any], *, frequencies: NumericArrayLike,) -> ContourProbeRecord p and v_n phasors on a closed rectangular contour.
The contour is the rectangle of cell faces enclosing the cell
block ix0..ix1 x iy0..iy1 (both ends inclusive): its sides
lie on , ,
and . From
the step after registration the engine
folds the face pressures (averaged from the two adjacent cell
centres) and the outward face normal velocities into running DFT
sums at each requested frequency; see ContourProbe
for the steady-state protocol and
far_field_from_contour for the
far-field transformation of the captured phasors.
Place the contour in open air: strictly around the scatterer, clear of sponge layers and of any source (point sources and plane-wave injection lines must stay outside so the enclosed region is source-free in a scattering run, or inside when the radiated field itself is the quantity of interest).
Parameters
| Name | Description |
|---|---|
ix0 |
First cell column inside the contour. |
ix1 |
Last cell column inside the contour. |
iy0 |
First cell row inside the contour. |
iy1 |
Last cell row inside the contour. |
frequencies |
Frequencies to track [Hz]. |
Returns: The registered ContourProbe.
Raises
| Exception | When |
|---|---|
| ValueError | For a block without open faces on all sides or invalid frequencies. |
| TypeError | For a cell index that is a flag, a text or an array, or frequencies that hold a complex number or a text. |
FDTD2D.add_plane_wave()
Section titled “FDTD2D.add_plane_wave()”FDTD2D.add_plane_wave( direction: Literal['down', 'up', 'left', 'right'], *, center_m: float, half_width_m: float, amplitude: float = 1.0, wavelength_m: float | None = None,) -> NoneSuperimpose a one-way plane wave packet as an initial condition.
A Gaussian envelope (optionally carrying a sine at wavelength_m)
is written onto the pressure field, and the leapfrog-consistent
particle velocity is written a half time step back, so the packet
propagates only toward direction (the axes of
plot_geometry: "down"/"up" along y,
"right"/"left" along x). The packet is uniform across the
transverse direction and adds to whatever fields are present.
Obstacles are not carved out of the initial condition: place the
packet in free field (its envelope clear of obstacle_mask
cells), as a physical incident wave would be.
Parameters
| Name | Description |
|---|---|
direction |
Travel direction, one of "down", "up", "left", "right". |
center_m |
Envelope centre along the travel axis [m]. |
half_width_m |
Gaussian envelope half-width [m], the 1/e point of , as GaussianPulse.half_width_s is in time. |
amplitude |
Peak pressure of the envelope [Pa]. |
wavelength_m |
Optional carrier wavelength [m]; None gives the pure Gaussian pulse. |
Raises
| Exception | When |
|---|---|
| ValueError | For an unknown direction, a non-positive or non-finite half_width_m/wavelength_m, or a non-finite center_m/amplitude. |
| TypeError | if direction is not a text, or amplitude, center_m, wavelength_m or half_width_m is not a single real number. |
FDTD2D.add_source()
Section titled “FDTD2D.add_source()”FDTD2D.add_source( source: GaussianPulse | CWSource | SignalSource | PlaneWaveSource,) -> NoneRegister a source: a point injection or a plane-wave line.
Point sources (GaussianPulse, CWSource,
SignalSource) inject additively at one cell. A
PlaneWaveSource injects a sustained one-way plane wave on
a full line of cells near its launch edge.
FDTD2D.energy()
Section titled “FDTD2D.energy()”FDTD2D.energy() -> floatTotal acoustic field energy [J per metre of depth].
FDTD2D.numpy_field()
Section titled “FDTD2D.numpy_field()”FDTD2D.numpy_field( field: Literal['p', 'vx', 'vy'],) -> NDArray[np.floating[Any]]A NumPy copy of the stored field, in this process, whatever the device.
Parameters
| Name | Description |
|---|---|
field |
"p" (cell centres), "vx" or "vy" (faces). |
Raises
| Exception | When |
|---|---|
| TypeError | if field is not a text. |
| ValueError | for a field the engine does not store. |
FDTD2D.plot_geometry()
Section titled “FDTD2D.plot_geometry()”FDTD2D.plot_geometry( ax: Axes | None = None, *, probes: Iterable[Sequence[int | np.integer[Any]]] | NDArray[np.integer[Any]] | None = None, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the configured domain before running it.
Domain extent, obstacles, sponge layers, impedance and rigid edges
and the added sources, with optional probe cells previewed; no
time stepping happens. Requires matplotlib
(the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
probes |
Optional probe cells as (ix, iy) index pairs, the cells FDTDRecording takes. Each is drawn at its cell centre ((ix + 0.5) * dx, (iy + 0.5) * dx), where the run records it (FDTDResult.probe_positions). |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the obstacle imshow. |
Raises
| Exception | When |
|---|---|
| TypeError | for a probe that is not a pair, or an index that is not a number, and for extent or origin in kwargs, which the grid sets: the obstacles are drawn on the grid the sources and probes are on. |
| ValueError | for a probe of more or fewer than two indices, an index that is not whole, or a cell outside the grid or inside an obstacle, refused in the words a run uses. |
FDTD2D.provenance
Section titled “FDTD2D.provenance”property
Where this engine steps: device, dtype and library versions.
FDTD2D.run()
Section titled “FDTD2D.run()”FDTD2D.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 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
FDTDRecording 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 a PlaneWaveSource 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 that waveform returns a number too large for a float. |
FDTD2D.step()
Section titled “FDTD2D.step()”FDTD2D.step() -> NoneAdvance the leapfrog scheme by one time step.
Every plane wave is sampled before any field moves, so a refused sample leaves the fields and the step count as they were. A plane wave a waveform adds while the step samples is registered at once: it stays registered when the step raises, and it enters on the next step.
Raises
| Exception | When |
|---|---|
| TypeError | if the waveform of a PlaneWaveSource returns anything but one real number. |
| ValueError | if that waveform returns a number too large for a float. |
FDTD2D.time
Section titled “FDTD2D.time”property
Elapsed simulated time [s].
fdtd_simulation
Section titled “fdtd_simulation”fdtd_simulation( run: FDTDRun, *, compute: Compute | None = None,) -> FDTDResultRun a deterministic 2D acoustic FDTD simulation.
Builds the staggered-grid domain (Attenborough & Van Renterghem 2021,
Eqs. 4.11-4.12), applies the requested boundary conditions, injects the
sources and integrates for duration_s seconds, recording the pressure
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 using the smallest
sound speed of the domain (), the
usual rule for
this lowest-order scheme: the worst-case (on-axis) numerical dispersion
error magnitude, from the discrete counterpart
of
Eq. 4.15 (the modelled frequency under-reads, so the signed error is
negative), is then about 1.6 % (about 1.4 % at the default cfl;
in a heterogeneous domain the slower cells run at a lower local Courant
number and sit nearer the 1.6 % bound) and finer grids reduce it
quadratically. The
simulation is 2D, so a point source is
physically a line source with cylindrical amplitude
spreading rather than the 3D spherical .
Parameters
| Name | Description |
|---|---|
run |
The simulation (FDTDRun): 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: A FDTDResult.
Raises
| Exception | When |
|---|---|
| TypeError | For a run that is not an FDTDRun, a compute that is neither a Compute nor None, or, when compute names a host, a run that cannot travel to a node: a source 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 the waveform of a PlaneWaveSource 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 that waveform returning 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. |
FDTDBoundaries
Section titled “FDTDBoundaries”FDTDBoundaries( *, sides: Literal['rigid', 'absorbing'] | Mapping[Literal['left', 'right', 'top', 'bottom'], Literal['rigid', 'absorbing'] | float | np.floating[Any] | np.integer[Any] | Sequence[float | np.floating[Any] | np.integer[Any]] | NDArray[np.floating[Any] | np.integer[Any]]] = 'rigid', absorbing_layer_cells: int | np.integer[Any] = 20,)How the four edges of the acoustic 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", or a mapping from side name (left/right/top/bottom) to "rigid", "absorbing", or a real specific impedance [Pa s/m] (scalar or per-edge-cell 1D array, Eqs. 4.33-4.35); a side the mapping leaves out is rigid. A mapping is held as a read-only copy, an impedance as the float a run reads, and a profile, given as a list or as an array of any real type, as a read-only float64 array of the record’s own, so a change to the caller’s dictionary, list or array 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 of sides that is not a text, a termination that is neither a name nor a real number or an array of them (a flag, None or a complex number among them), 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 name that is not "rigid" or "absorbing", a ragged impedance profile or an impedance too large for a float, or an absorbing_layer_cells that is not a whole number. |
FDTDRecording
Section titled “FDTDRecording”FDTDRecording( *, probes: Sequence[Sequence[int | np.integer[Any]]] | NDArray[np.integer[Any]] = (), snapshot_every: int | np.integer[Any] | None = None, snapshot_decimation: int | np.integer[Any] = 1,)What an acoustic run writes down: probe histories and field snapshots.
The two ways out of a running simulation. Probes record the pressure
history at named cells; snapshots record the whole pressure field every
snapshot_every steps. Recording nothing (the default) runs the
physics and keeps only the time axis.
Parameters
| Name | Description |
|---|---|
probes |
Pressure-probe cells as (ix, iy) index pairs. |
snapshot_every |
Record a full pressure-field snapshot every this many steps (and at ); None records none. |
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 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 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. |
FDTDResult
Section titled “FDTDResult”FDTDResult( times: NDArray[np.float64], pressures: NDArray[np.float64], probes: NDArray[np.int_], probe_positions: NDArray[np.float64], dx: float, dt: float, shape: tuple[int, int], sources: tuple[GaussianPulse | CWSource | SignalSource | PlaneWaveSource, ...], snapshots: NDArray[np.floating[Any]] | None, snapshot_times: NDArray[np.float64] | None, obstacle_mask: NDArray[np.bool_] | None, snapshot_decimation: int, provenance: RunProvenance,)Frozen result of a fdtd_simulation run.
Attributes
| Name | Description |
|---|---|
times |
Time axis [s], length n_steps + 1 (includes ). |
pressures |
Pressure history at each probe [Pa], shape (n_probes, n_steps + 1). |
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 pressure fields, 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. |
obstacle_mask |
Boolean map of rigid cells, or None. |
snapshot_decimation |
Every how many cells a snapshot keeps along each axis (1 keeps every cell). |
provenance |
Where the run stepped (RunProvenance). |
FDTDResult.plot()
Section titled “FDTDResult.plot()”FDTDResult.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 pressure time histories; "snapshot" renders one recorded pressure 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. |
FDTDResult.size
Section titled “FDTDResult.size”property
Domain size (lx, ly) [m].
FDTDRun
Section titled “FDTDRun”FDTDRun( *, c: NumericArrayLike, dx: float, duration_s: float, sources: Sequence[GaussianPulse | CWSource | SignalSource | PlaneWaveSource], shape: Sequence[int | np.integer[Any]] | NDArray[np.integer[Any]] | None = None, rho: NumericArrayLike = 1.2, cfl: float = 0.6, recording: FDTDRecording | None = None, boundaries: FDTDBoundaries | None = None, obstacle_mask: NumericArrayLike | None = None, damping: NumericArrayLike = 0.0,)One acoustic FDTD simulation: the domain, its sources and what it records.
Every argument is checked when the run is built, the grid’s included:
the time step, the density, the sponge and the damping, the impedance
edges, the obstacle, and the sources and the probes on the grid. A run
that builds is one fdtd_simulation can step here; one that
cannot travel to a node is refused when the function is called, and a
bad argument raises where the run is written, with the class and the
words the function always raised. The sources are held as a tuple
and each array as the run’s own read-only copy, so nothing the caller
changes afterwards reaches a checked run.
Parameters
| Name | Description |
|---|---|
c |
Sound-speed map [m/s], shape (ny, nx), or a scalar with an explicit shape. |
dx |
Grid spacing [m] (square cells). |
duration_s |
Physical time to simulate [s]. |
sources |
One or more of GaussianPulse, CWSource, SignalSource or PlaneWaveSource. |
shape |
Grid shape (ny, nx), required when c is a scalar; beside a map it must be the map’s own shape. |
rho |
Density map [kg/m3]; scalar or (ny, nx) array. |
cfl |
Courant number in (0, 1) (Eqs. 4.13-4.14); the time step is . Default 0.6. |
recording |
What the run records (FDTDRecording): the probe cells, and the snapshot cadence and decimation. None records nothing but the time axis. |
boundaries |
How the domain edges are terminated (FDTDBoundaries): the rigid, absorbing and impedance sides, and the sponge thickness of the absorbing ones. 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: a duration_s, cfl or dx that is not one number, a recording that is neither an FDTDRecording nor None, boundaries that are neither an FDTDBoundaries nor None, a shape that is not a pair or holds a count that is not a number, a medium (c, rho, damping) that holds a complex number or a text, or an obstacle_mask that is not boolean. |
| ValueError | If an argument is out of its range, a dx, a cfl and a fastest speed of c give a time step past a float’s range (zero or infinite), a shape is not two whole numbers of one cell 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. |
GaussianPulse
Section titled “GaussianPulse”GaussianPulse( *, ix: int | np.integer[Any], iy: int | np.integer[Any], half_width_s: float, t0: float | None = None, amplitude: float = 1.0,)A soft Gaussian pressure pulse injected at one cell.
, with
the half-width half_width_s and t0 defaulting to
4 * half_width_s so the pulse starts from (numerically) zero.
Attributes
| Name | Description |
|---|---|
ix |
Source column (x) index; the cell centre is at . |
iy |
Source row (y) index. |
half_width_s |
Gaussian half-width [s]; it sets the pulse bandwidth. The name carries the unit because the perfectly matched layer of this same module measures its own width in cells. |
t0 |
Pulse centre time [s] (default 4 * half_width_s). |
amplitude |
Peak source amplitude [Pa]. |
GaussianPulse.value()
Section titled “GaussianPulse.value()”GaussianPulse.value(t: float) -> floatSource waveform at time t (seconds).
Raises
| Exception | When |
|---|---|
| TypeError | if t is anything but one real number: a complex number, a text, an array or None. |
| ValueError | if t is a number too large for a float. |
PlaneWaveSource
Section titled “PlaneWaveSource”PlaneWaveSource( *, direction: Literal['down', 'up', 'left', 'right'], waveform: Callable[[float], float], offset: int | np.integer[Any] = 0, amplitude: float = 1.0,)A sustained one-way plane wave injected on a line near one edge.
A total-field/scattered-field style injection: each step the incident
wave is added simultaneously to the pressure on the injection line and
to the particle velocity on the adjacent face, so the wave launches
only toward direction and anything scattered back crosses the line
untouched (and can be absorbed by a sponge behind it).
direction is the travel direction ("down", "up",
"left", "right" in the FDTD2D.plot_geometry axes) and
the line sits offset cells in from the opposite edge (place it just
inside the sponge layer when one is configured on that side).
waveform maps time in seconds to the incident pressure in pascals
(any callable, or reuse the value method of a point source).
Attributes
| Name | Description |
|---|---|
direction |
Travel direction of the launched wave. One of "down", "up", "left" or "right". |
waveform |
Callable t -> p_inc(t) in pascals. |
offset |
Line position, in cells from the launch edge. |
amplitude |
Extra gain applied to waveform. |
SignalSource
Section titled “SignalSource”SignalSource( *, ix: int | np.integer[Any], iy: int | np.integer[Any], samples: NumericArrayLike, fs: float, amplitude: float = 1.0,)An arbitrary sampled waveform injected at one cell.
The samples are interpreted as the source signal at fs and
linearly interpolated onto the simulation time steps; outside the sampled
span the source is zero. fs therefore does not need to match
the simulation rate 1/dt, although a rate well above the highest
frequency of interest avoids interpolation roll-off.
Attributes
| Name | Description |
|---|---|
ix |
Source column (x) index. |
iy |
Source row (y) index. |
samples |
Source signal samples [Pa] (stored as a read-only 1D float64 array). |
fs |
Sampling rate of samples [Hz]. |
amplitude |
Scale factor applied to the samples. |
SignalSource.value()
Section titled “SignalSource.value()”SignalSource.value(t: float) -> floatSource waveform at time t (seconds), zero outside the span.
Raises
| Exception | When |
|---|---|
| TypeError | if t is anything but one real number: a complex number, a text, an array or None. |
| ValueError | if t is a number too large for a float. |