Mondaic

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

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.

Parameters
  • number_of_snapshots int — Approximate desired number of wavefield snapshots to output.
  • waveform Waveform — Waveform simulation object from which the mesh, the start and end times, the Courant number, and the simulation order are extracted.
Returns int — Sampling interval required to achieve the approximate number of wavefield snapshots.

wavefield_output_enclosing_elements()

def wavefield_output_enclosing_elements(
    wo: WavefieldOutput,
    points: tuple[npt.NDArray] | npt.NDArray | typing.Sequence[npt.ArrayLike],
) -> tuple[np.ndarray, np.ndarray]: ...

Get the elements and coefficients for evaluation at arbitrary points.

Given a WavefieldOutput object, usually constructed directly from a SalvusCompute output file, this function wraps the calls required to both a) find the elements enclosing each point in an arbitrary list of points, and b) compute interpolation coefficients required for evaluation at said points.

Parameters
  • wo WavefieldOutput — The wavefield output object.
  • points tuple[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.
Returns tuple[np.ndarray, np.ndarray] — A tuple of (element indices, interpolation coefficients) for each point.

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 = "batch",
    verbose: bool = True,
) -> 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.

Parameters
  • wo WavefieldOutput — The wavefield output object; generally initialized directly from a SalvusCompute HDF5 volumetric output file.
  • points tuple[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_elements tuple[np.ndarray, np.ndarray] | tuple[()] — A tuple of the enclosing element indices and interpolation coefficients 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.
  • mode str — Either “sequential” or “batch”. If “sequential”, perform a tensor contraction only along the time axis, and operate element by element. If “batch”, perform a tensor contraction along all axes to perform the interpolation. Batch is generally an optimal approach when the number of points is approximately equal or less to the number of elements; otherwise it may result in unacceptable memory usage. Defaults to “sequential”.
  • verbose bool — Whether to print a progress bar for the enclosing element search and interpolation step.
Returns xr.DataArray — An xarray DataArray containing dimensions (t [time], c [component], x, y, [z]) if structured input is passed, or (t [time], c [component], point) if unstructured input was passed. Points that were not found within any output element are flagged as NANs.

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

Parameters
  • filename_prefix pathlib.Path | str — A full path, including a filename prefix, describing where the VTK files should be written.
  • da xr.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).
  • filename_indexing tuple[int, str] | 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.
Returns None

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

Parameters
  • filename_prefix pathlib.Path | str — A full path, including a filename prefix, describing where the VTK files should be written.
  • da xr.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).
  • filename_indexing tuple[int, str] | 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.
Returns None

Classes

WavefieldOutput

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

Parameters
  • conn np.ndarray — The connectivity array.
  • crds np.ndarray — The coordinate array.
  • data np.ndarray — The wavefield output data.
  • start_time float — The start time of the encapsulated data (in seconds).
  • sampling_rate float — The sampling rate of the encapsulated data (in hertz).
Attributes
n_pnts_per_elem int

Get the number of points per element (without padding).

n_sub_elem int

Get the number of sub elements (for visualization).

n_ts float

Get the number of time steps stored.

ndim int

Get the dimension of the stored wavefield.

nelem int

Get the number of elements.

sampling_interval float

Get the sampling interval of the stored wavefield.

shape_order int

Get the polynomial order of the stored wavefield.

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

Parameters
  • filename pathlib.Path | str — The output file to read from.
  • field str — The field to read.
  • output_type str — The output type of the field (surface or volume).
  • time_steps slice — The time steps indices to read expressed as a python slice object.
Returns WavefieldOutput
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.

Parameters
  • dim int — The dimension to drop. Must be an integer in the range(0, n_dim).
Returns WavefieldOutput — A new WavefieldOutput object with the dimension reduced by 1.
get_element_centroid()
def get_element_centroid(self) -> np.ndarray: ...

Get the centroid of each element.

Returns np.ndarray
get_element_nodes()
def get_element_nodes(self) -> np.ndarray: ...

Get the nodal locations of each element.

Returns np.ndarray
sizes()
def sizes(
    filename: pathlib.Path | str, field: str, output_type: str
) -> tuple[int, ...]: ...

Get the sizes on disk of a wavefield data array.

Parameters
  • filename pathlib.Path | str — The path to the HDF5 file.
  • field str — The field to query.
  • output_type str — The output type (volume or surface).
Returns tuple[int, ...] — A tuple of sizes in each dimension.

Used in tutorials