simulation.video
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.
Writing an FDTD run straight to a video file.
write_fdtd_animation steps the run
fdtd_simulation steps, an
FDTDRun checked when it was built, and draws
the pressure into a video as it is computed, through the encoders of
phonometry.io.write_video, and write_elastic_fdtd_animation
does the same for elastic_fdtd_simulation and
an ElasticRun, drawing the field
ElasticRecording.snapshot_field names, with the colour limit of
AnimationFrame in that field’s unit. No snapshot is stored: a long run on a
large grid writes a long video in the memory one frame takes here (a GIF
apart, whose palette ffmpeg computes from every frame it holds). The run’s
result comes back with its probes and times and without snapshots.
How each frame is drawn is one record, AnimationFrame (the labels’
language, the size in pixels, the colour limit); how the video is encoded is
another, phonometry.io.VideoOptions, the one
phonometry.io.write_video takes. Before the first step ffmpeg is
found and run, and the encoder of a WebM or an MP4 is chosen by a real
one-frame encode at the frame’s size (a GIF has no encoder to choose), so
neither a missing ffmpeg nor an encoder that cannot write the video costs a
run. A raw ffmpeg_encoder is only looked for in that ffmpeg’s list of
encoders, with no trial, as phonometry.io.VideoOptions says.
The frames show what the snapshot plot of the simulation function’s result
(plot with kind="snapshot")
shows: the same field on the same colormap, symmetric about zero, with the
same marks and labels, the limit of the scale being the video’s own (fixed
for the whole video, given or found, as the next paragraph says); a
writer’s own result holds no snapshots to plot. A frame is laid
out once for the whole run, for the widest title it shows (the time of its
last frame) and the labels of its axes and colour scale, so that no text
leaves the frame and nothing moves from one frame to the next; the title is
centred over the frame. Every text keeps its own size: a frame is at least
479 by 245 pixels, the smallest in which every text, at its own size, stays
clear of the frame’s margin and covers no other, with the field still in
view for a grid up to ten times longer one way than the other, on every
matplotlib version the library is tested with. An axis too short for the
numbers matplotlib would write along it keeps fewer of them, never one over
another: a tall grid’s narrow field may show a single number under it. That
holds for a run whose last frame comes before ten seconds; a later one
writes more digits in its title’s time, and needs a frame about 10.6 pixels
wider for each digit past four before the point in milliseconds: a narrower
one is refused before the run starts, with the width it needs. The frames are drawn
once and then updated in place, under matplotlib’s default style whatever
the caller’s settings say, so a video written here and one written on
another machine look alike. One frame is drawn every
run.recording.snapshot_every steps, at the decimation
run.recording.snapshot_decimation gives.
The colour scale is fixed for the whole video. With a limit given, each frame is drawn as the run computes it. Without one the run steps twice: a first pass, which stops at the last frame, finds, on the device, the largest magnitude the drawn field reaches outside the source cells, the plane-wave injection lines and the absorbing layer, where the field is what the source or the sponge makes it rather than the wave the video shows, and the second pass draws with that limit. Neither pass stores a snapshot.
With a host in compute the run is computed, drawn and encoded on
that node, named in the hosts file (see the guide on remote nodes), and only
the result and the video’s bytes come back. Every argument is checked here
first, so a call refused here never starts ssh, and ffmpeg is found and run
on the node: this machine runs it only when a node that failed falls back
to it (fallback=True). The bytes go, as they arrive, into a partial file
beside path, whose name starts with a dot (hidden on Linux and macOS),
created before ssh starts so that a directory that does not take it fails
first: never more of them than the frames can take, and none that do not
begin as the container path names. That file takes path’s place once
the node’s whole answer has been read and checked, and is removed if
anything fails before (or stays, under its own name, if the system does not
let it go, which hides no error). As the file a video written here goes
into, it is readable by its owner alone while it replaces a file, and the
video then keeps the permission bits of the file it replaces.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
AnimationFrame
Section titled “AnimationFrame”AnimationFrame( *, language: Literal['en', 'es'] = 'en', size: Sequence[int | np.integer[Any]] | NDArray[np.integer[Any]] = (960, 540), color_limit: float | None = None,)How each frame of a simulation video is drawn: in which language, at what size, on what scale.
Parameters
| Name | Description |
|---|---|
language |
Label language, "en" (default) or "es". |
size |
(width, height) of a frame in pixels, a tuple, a list, a NumPy array or any other sequence of the two whole numbers, at least 479 by 245, the smallest frame in which every text, at its own size, stays clear of the frame’s margin and the field still shows (for a grid up to ten times longer one way than the other), on every matplotlib version the library is tested with (default (960, 540)). That is for a run whose last frame comes before ten seconds: a later one needs a wider frame for the time its last title writes, which the writers ask for before the run starts. |
color_limit |
The value at either end of the colour scale, fixed for the whole video, in the unit of the field drawn: pascals for an acoustic run (write_fdtd_animation), and for an elastic one (write_elastic_fdtd_animation) the unit of ElasticRecording.snapshot_field, pascals for "p" and metres per second for "vx" and "vy". None (default) finds it in a first pass over the run. |
Raises
| Exception | When |
|---|---|
| TypeError | for a size that is not a pair or holds something other than numbers, or a color_limit that is not one number (a bool is not one). |
| ValueError | for a language other than "en" and "es", a size of more or fewer than two sides, with a side that is not a whole number, or narrower than 479 or lower than 245 pixels, or a color_limit that is not a positive finite number. |
write_elastic_fdtd_animation
Section titled “write_elastic_fdtd_animation”write_elastic_fdtd_animation( path: str | os.PathLike[str], run: ElasticRun, *, compute: Compute | None = None, frame: AnimationFrame | None = None, video: VideoOptions | None = None,) -> ElasticFDTDResultStep an elastic FDTD run and write one of its fields to a video.
The run is the one elastic_fdtd_simulation
steps, checked when the ElasticRun was
built; a frame or video record of another type, a path whose container
rules out the options, an option ffmpeg could not honour, or a missing
ffmpeg is refused before the first step. The video draws the field
run.recording.snapshot_field names at the cell centres (the
synthetic pressure, or one velocity component), one frame at t = 0 and
one every run.recording.snapshot_every steps, as the snapshot plot
of elastic_fdtd_simulation’s result draws
it, laid out once for the whole run. See the module
documentation for how the frame is laid out and the colour scale fixed.
Parameters
| Name | Description |
|---|---|
path |
Where to write the video; .webm, .mp4 or .gif. |
run |
The run (ElasticRun). Its recording’s snapshot_every is required and is the frame cadence, its snapshot_field the field drawn, its snapshot_decimation the cells a frame keeps, and its probes are recorded in the result. |
compute |
Where the run steps (Compute); None follows use, then PHONOMETRY_COMPUTE, then NumPy; with a host the run is computed, drawn and encoded on that node, named in the hosts file (see the guide on remote nodes), and only the result and the video’s bytes come back. |
frame |
How each frame is drawn (AnimationFrame); None (default) is AnimationFrame(): 960 by 540 pixels, English labels and a colour limit found in a first pass. Its color_limit is in the unit of the field drawn: pascals for "p", metres per second for "vx" and "vy". |
video |
How the video is encoded (phonometry.io.VideoOptions); None (default) is VideoOptions(), which plays at 30 frames per second unless its fps says otherwise. |
Returns: The run’s ElasticFDTDResult, with its probes and times and no snapshots.
Raises
| Exception | When |
|---|---|
| TypeError | If run is not an ElasticRun, frame not an AnimationFrame, video not a VideoOptions, compute not a Compute, or path neither a text nor a path; or, when compute names a host, a part of the 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); or, as a run written here steps, a waveform that returns anything but one real number. |
| ValueError | If the run records no snapshots (run.recording is None, or its snapshot_every is), the frame is narrower than the title of the run’s last frame needs (a run whose last frame comes at ten seconds or later; the message gives the width), the path’s suffix is not one of the three, the path names a directory, or its container rules out the options, PHONOMETRY_COMPUTE is malformed, there is nothing to find the colour scale by (the message asks for AnimationFrame(color_limit=...)), or the hosts file is malformed; or, as a run written here steps, a waveform returns a number too large for a float. |
| FileNotFoundError | If the directory of path does not exist or cannot be reached (it sits inside a directory this process cannot search); before any step, and before ssh starts. |
| FFmpegNotFoundError | For a video written here (no host, or a node that failed with fallback=True), if ffmpeg is not found, or on Windows is found only in the working directory; before any step. |
| VideoEncoderError | If no encoder can write the video, a raw ffmpeg_encoder is not in this ffmpeg (both before any step), or the directory of path does not take a file (before any step, and before ssh starts; the message names path); if ffmpeg cannot be started or fails while writing it (the message names the encoder and quotes ffmpeg; ffmpeg_options it refuses fail at the first frames), this machine’s disk does not take the bytes of a node’s video as they arrive (it is full, say), or the finished video cannot take the place of path (the message says where it was left). |
| ComputeImportError | When the device’s library is not installed or does not import, unless fallback=True. |
| ComputeDeviceError | When the device is not present or not usable, unless fallback=True. |
| KeyError | For a host the hosts file does not name. |
| ComputeRemoteError | For a failure of the connection or of the node (one without matplotlib or the font every frame is drawn in, without ffmpeg, without an encoder that writes this video or the raw ffmpeg_encoder, or whose ffmpeg refuses the ffmpeg_options), or video bytes back that are more than the frames can take, too few to be a video, or not the container path names, unless fallback=True. |
| ImportError | If matplotlib is not installed, for a video written here. |
Warns
| Warning | When |
|---|---|
| ComputeFallbackWarning | Once, when fallback=True turns a ComputeImportError, a ComputeDeviceError or a ComputeRemoteError into a run on NumPy that writes the video here. |
write_fdtd_animation
Section titled “write_fdtd_animation”write_fdtd_animation( path: str | os.PathLike[str], run: FDTDRun, *, compute: Compute | None = None, frame: AnimationFrame | None = None, video: VideoOptions | None = None,) -> FDTDResultStep an acoustic FDTD run and write its pressure field to a video.
The run is the one fdtd_simulation steps,
checked when the FDTDRun was built. A
frame or video record of another type, a path whose container rules out
the options, an option ffmpeg could not honour (an encoder that does not
run here, a raw encoder this ffmpeg lacks), or a missing ffmpeg is
refused before the first step. One frame is drawn at t = 0 and one every
run.recording.snapshot_every steps; the video shows what the
snapshot plot of fdtd_simulation’s result
shows, laid out once for the whole run and updated in place, under
matplotlib’s default style. See the module documentation for how
the frame is laid out and the colour scale fixed.
Parameters
| Name | Description |
|---|---|
path |
Where to write the video; .webm, .mp4 or .gif, as phonometry.io.write_video writes them. |
run |
The run (FDTDRun). Its recording’s snapshot_every is required and is the frame cadence, its snapshot_decimation the cells a frame keeps, and its probes are recorded in the result. |
compute |
Where the run steps (Compute); None follows use, then PHONOMETRY_COMPUTE, then NumPy; with a host the run is computed, drawn and encoded on that node, named in the hosts file (see the guide on remote nodes), and only the result and the video’s bytes come back. |
frame |
How each frame is drawn (AnimationFrame); None (default) is AnimationFrame(): 960 by 540 pixels, English labels and a colour limit, in pascals, found in a first pass. |
video |
How the video is encoded (phonometry.io.VideoOptions); None (default) is VideoOptions(), which plays at 30 frames per second unless its fps says otherwise. |
Returns: The run’s FDTDResult, with its probes and times and no snapshots.
Raises
| Exception | When |
|---|---|
| TypeError | If run is not an FDTDRun, frame not an AnimationFrame, video not a VideoOptions, compute not a Compute, or path neither a text nor a path; or, when compute names a host, a part of the run that cannot travel to a node: a waveform 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); or, as a run written here steps, the waveform of a PlaneWaveSource that returns anything but one real number. |
| ValueError | If the run records no snapshots (run.recording is None, or its snapshot_every is), the frame is narrower than the title of the run’s last frame needs (a run whose last frame comes at ten seconds or later; the message gives the width), the path’s suffix is not one of the three, the path names a directory, or its container rules out the options, PHONOMETRY_COMPUTE is malformed, there is nothing to find the colour scale by (the message asks for AnimationFrame(color_limit=...)), or the hosts file is malformed; or, as a run written here steps, a waveform returns a number too large for a float. |
| FileNotFoundError | If the directory of path does not exist or cannot be reached (it sits inside a directory this process cannot search); before any step, and before ssh starts. |
| FFmpegNotFoundError | For a video written here (no host, or a node that failed with fallback=True), if ffmpeg is not found, or on Windows is found only in the working directory; before any step. |
| VideoEncoderError | If no encoder can write the video, a raw ffmpeg_encoder is not in this ffmpeg (both before any step), or the directory of path does not take a file (before any step, and before ssh starts; the message names path); if ffmpeg cannot be started or fails while writing it (the message names the encoder and quotes ffmpeg; ffmpeg_options it refuses fail at the first frames), this machine’s disk does not take the bytes of a node’s video as they arrive (it is full, say), or the finished video cannot take the place of path (the message says where it was left). |
| ComputeImportError | When the device’s library is not installed or does not import, unless fallback=True. |
| ComputeDeviceError | When the device is not present or not usable, unless fallback=True. |
| KeyError | For a host the hosts file does not name. |
| ComputeRemoteError | For a failure of the connection or of the node (one without matplotlib or the font every frame is drawn in, without ffmpeg, without an encoder that writes this video or the raw ffmpeg_encoder, or whose ffmpeg refuses the ffmpeg_options), or video bytes back that are more than the frames can take, too few to be a video, or not the container path names, unless fallback=True. |
| ImportError | If matplotlib is not installed, for a video written here. |
Warns
| Warning | When |
|---|---|
| ComputeFallbackWarning | Once, when fallback=True turns a ComputeImportError, a ComputeDeviceError or a ComputeRemoteError into a run on NumPy that writes the video here. |