salvus.toolbox.helpers.wavefield_output
salvus.toolbox.helpers.wavefield_output salvus toolbox helpers wavefield_output Functions for manipulating SalvusCompute’s wavefield output.
Functions
get_wavefield_snapshots_sampling_interval()
get_wavefield_snapshots_sampling_interval()def get_wavefield_snapshots_sampling_interval(
number_of_snapshots: int, waveform: Waveform
) -> int: ...Compute the sampling interval for getting a specific number of snapshots.
This can be used as input for the sampling_interval_in_time_steps within
the extra_output_configuration when outputting wavefields for a surface
or a volume.
The mesh and the simulation parameters (start_time_in_seconds,
end_time_in_seconds, courant_number, and simulation_order) are all
extracted automatically from the provided Waveform simulation object.
For example, consider a case where one would wish to output approximately 300 snapshots for a wavefield animation. This could be achieved using something along the lines of the following:
sampling_interval = get_wavefield_snapshots_sampling_interval(
number_of_snapshots=300,
waveform=w,
)
p.simulations.launch(
...,
extra_output_configuration={
"volume_data": {
"sampling_interval_in_time_steps": sampling_interval,
"fields": ["displacement"],
},
},
)
Note that this estimate ignores absorbing boundary and attenuation
corrections to the time step. These shrink dt slightly, so the actual
simulation may take a few more steps than estimated.
number_of_snapshotsint — Approximate desired number of wavefield snapshots to output.waveformWaveform —Waveformsimulation object from which the mesh, the start and end times, the Courant number, and the simulation order are extracted.
list_time_reduced_datasets()
list_time_reduced_datasets()def list_time_reduced_datasets(
filename: pathlib.Path | str,
) -> dict[str, list[str]]: ...List the reductions stored in a time_reduced_data output file.
The names of the datasets in such a file are derived from the requested
reductions rather than chosen by the user, so this is the canonical way to
discover what a given file contains. They follow the pattern
<reduction>_<criterion>_<field>, prefixed with componentwise_ if the
criterion (signed or abs) reduces every component independently, and
additionally with time_of_ or state_of_ for the corresponding entries
of the reduction’s record list.
filenamepathlib.Path | str — Thetime_reduced_dataoutput file to inspect.
wavefield_output_enclosing_elements()
wavefield_output_enclosing_elements()def wavefield_output_enclosing_elements(
wo: WavefieldOutput,
points: tuple[npt.NDArray] | npt.NDArray | typing.Sequence[npt.ArrayLike],
number_of_threads: int | None = None,
) -> tuple[np.ndarray, np.ndarray]: ...Get the elements and reference coordinates for arbitrary points.
Given a WavefieldOutput object, usually constructed directly from a
SalvusCompute output file, this function locates the element enclosing each
point in an arbitrary list of points, and returns the coordinates of each
point within the reference element of its enclosing element. Together these
are everything wavefield_output_to_xarray needs to evaluate the
wavefield, so they can be computed once and reused across extractions.
The degrees of freedom of the wavefield output are treated as the control nodes of the enclosing element search, so the effective shape mapping order is the polynomial order of the wavefield rather than that of the simulation mesh.
woWavefieldOutput — The wavefield output object.pointstuple[npt.NDArray] | npt.NDArray | typing.Sequence[npt.ArrayLike] — Either a list of numpy arrays, indicating a structured grid, or one array of shape (n_pnt, n_dim), indicating an unstructured collection of points.number_of_threadsint | None =None— The number of parallel threads to use. If not given it will use the smaller of the total number of cores on the system and 120.
wavefield_output_to_xarray()
wavefield_output_to_xarray()def wavefield_output_to_xarray(
wo: WavefieldOutput,
points: tuple[npt.NDArray] | npt.NDArray | typing.Sequence[npt.ArrayLike],
enclosing_elements: tuple[np.ndarray, np.ndarray] | tuple[()] = (),
mode: str | None = None,
verbose: bool | None = None,
number_of_threads: int | None = None,
) -> xr.DataArray: ...Evaluate wavefield output at a set of user-defined points.
This function allows for the evaluation of a wavefield output file as generated by Salvus compute onto an arbitrary series of points. Both structured and unstructured point specifications are supported; please see the argument documentation below for more information.
woWavefieldOutput — The wavefield output object; generally initialized directly from a SalvusCompute HDF5 volumetric output file.pointstuple[npt.NDArray] | npt.NDArray | typing.Sequence[npt.ArrayLike] — A list of spatial points to interpolate onto. If a list of arrays is passed, it will be assumed that these arrays describe a structured grid in len(points) dimensions. If a single numpy array is passed, it will be assumed that these points represent an unstructured collection of points.enclosing_elementstuple[np.ndarray, np.ndarray] | tuple[()] =()— A tuple of the enclosing element indices and reference coordinates, as returned bywavefield_output_enclosing_elements, can be passed in order to skip the potentially expensive enclosing element search if such values already exist. If an empty tuple is passed, the requisite quantities will be computed within this function.modestr | None =None— Deprecated and ignored. The search and the interpolation are both performed by a single parallel routine, so there is no longer anything to choose between.verbosebool | None =None— Deprecated and ignored. There is no longer a Python-level loop to report progress on.number_of_threadsint | None =None— The number of parallel threads to use. If not given it will use the smaller of the total number of cores on the system and 120.
xarray_to_vtk_image_data()
xarray_to_vtk_image_data()def xarray_to_vtk_image_data(
filename_prefix: pathlib.Path | str,
da: xr.DataArray,
filename_indexing: tuple[int, str] | None = None,
) -> None: ...Write an xarray DataArray to a series of VTK image data files.
The resulting files can be opened as a sequence in Paraview to efficiently render time-dependent structured data. render time-dependent structured data. The suffix for VTK image data files is ‘.vti’
This function requires the VTK Python bindings to be installed (vtk.org).
filename_prefixpathlib.Path | str — A full path, including a filename prefix, describing where the VTK files should be written.daxr.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).filename_indexingtuple[int, str] | None =None— A tuple of (offset, format) to use when computing the filenames. If not provided, filenames will start at 0 and sequential names will be front-padded with an appropriate number of zeros so as all time step outputs will be lexicographically ordered.
xarray_to_vtk_rectilinear_grid()
xarray_to_vtk_rectilinear_grid()def xarray_to_vtk_rectilinear_grid(
filename_prefix: pathlib.Path | str,
da: xr.DataArray,
filename_indexing: tuple[int, str] | None = None,
) -> None: ...Write an xarray DataArray to a series of VTK rectilinear grid files.
The resulting files can be opened as a sequence in Paraview to efficiently render time-dependent structured data. The suffix for VTK rectilinear grid files is ‘.vtr’
This function requires the VTK Python bindings to be installed (vtk.org).
filename_prefixpathlib.Path | str — A full path, including a filename prefix, describing where the VTK files should be written.daxr.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).filename_indexingtuple[int, str] | None =None— A tuple of (offset, format) to use when computing the filenames. If not provided, filenames will start at 0 and sequential names will be front-padded with an appropriate number of zeros so as all time step outputs will be lexicographically ordered.
Classes
WavefieldOutput
WavefieldOutputclass WavefieldOutput(builtins.object):
def __init__(
self,
conn: np.ndarray,
crds: np.ndarray,
data: np.ndarray,
start_time: float,
sampling_rate: float,
) -> None: ...Encapsulation of Salvus’ volumetric wavefield output.
Meant to mirror the important parts of a volumetric .h5 output file stored on disk as output by SalvusCompute during a simulation.
connnp.ndarray — The connectivity array.crdsnp.ndarray — The coordinate array.datanp.ndarray — The wavefield output data.start_timefloat — The start time of the encapsulated data (in seconds).sampling_ratefloat — The sampling rate of the encapsulated data (in hertz).
n_pnts_per_elem int
n_pnts_per_elem intGet the number of points per element (without padding).
n_sub_elem int
n_sub_elem intGet the number of sub elements (for visualization).
n_ts float
n_ts floatGet the number of time steps stored.
ndim int
ndim intGet the dimension of the stored wavefield.
nelem int
nelem intGet the number of elements.
sampling_interval float
sampling_interval floatGet the sampling interval of the stored wavefield.
shape_order int
shape_order intGet the polynomial order of the stored wavefield.
from_file()
from_file()def from_file(
filename: pathlib.Path | str,
field: str,
output_type: str,
time_steps: slice = slice(None, None, None),
) -> WavefieldOutput: ...Initialize a WavefieldOutput object from a file.
Meant to be the common way this class is initialized, as all relevant components will be read automatically from the specified file.
filenamepathlib.Path | str — The output file to read from.fieldstr — The field to read.output_typestr — The output type of the field (surface or volume).time_stepsslice =slice(None, None, None)— The time steps indices to read expressed as a python slice object.
from_time_reduced_file()
from_time_reduced_file()def from_time_reduced_file(
filename: pathlib.Path | str, dataset: str
) -> WavefieldOutput: ...Initialize a WavefieldOutput object from a time-reduced output file.
Note that a reduction is not a time series. The returned object
carries a single, degenerate time sample; its start_time and
sampling_rate are placeholders and carry no meaning. Use
list_time_reduced_datasets to discover the available dataset names.
filenamepathlib.Path | str — The time-reduced output file to read from.datasetstr — The name of the reduction to read.
drop_dimension()
drop_dimension()def drop_dimension(self, dim: int) -> WavefieldOutput: ...Drop a dimension from the output’s coordinates.
This function is useful when one wants to plot a 2-D representation of a 3-D surface. Such a use-case is, however, not valid in all circumstances, as degenerate coordinates may be produced as mesh edges, coincident slices, etc. If this case is detected, an exception will be thrown.
dimint — The dimension to drop. Must be an integer in the range(0, n_dim).
get_element_centroid()
get_element_centroid()def get_element_centroid(self) -> np.ndarray: ...Get the centroid of each element.
get_element_nodes()
get_element_nodes()def get_element_nodes(self) -> np.ndarray: ...Get the nodal locations of each element.
sizes()
sizes()def sizes(
filename: pathlib.Path | str, field: str, output_type: str
) -> tuple[int, ...]: ...Get the sizes on disk of a wavefield data array.
filenamepathlib.Path | str — The path to the HDF5 file.fieldstr — The field to query.output_typestr — The output type (volume or surface).