Mondaic
This API reference is not for the latest stable Salvus version.

salvus.toolbox.helpers.wavefield_output

Functions for manipulating SalvusCompute’s wavefield output.

Functions

wavefield_output_enclosing_elements()

def wavefield_output_enclosing_elements(
    wo: salvus.toolbox.helpers.wavefield_output.WavefieldOutput,
    points: Union[Tuple[numpy.ndarray], numpy.ndarray],
) -> Tuple[numpy.ndarray, numpy.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 salvus.toolbox.helpers.wavefield_output.WavefieldOutput — The wavefield output object.
  • points Union[Tuple[numpy.ndarray], numpy.ndarray] — 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[numpy.ndarray, numpy.ndarray] — A tuple of (element indices, interpolation coefficients) for each point.

wavefield_output_to_xarray()

def wavefield_output_to_xarray(
    wo: salvus.toolbox.helpers.wavefield_output.WavefieldOutput,
    points: Union[Tuple[numpy.ndarray], numpy.ndarray],
    enclosing_elements: Union[
        Tuple[numpy.ndarray, numpy.ndarray], Tuple[()]
    ] = (),
    mode: str = "batch",
    verbose: bool = True,
) -> xarray.core.dataarray.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 salvus.toolbox.helpers.wavefield_output.WavefieldOutput — The wavefield output object; generally initialized directly from a SalvusCompute HDF5 volumetric output file.
  • points Union[Tuple[numpy.ndarray], numpy.ndarray] — 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 Union[Tuple[numpy.ndarray, numpy.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 xarray.core.dataarray.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: Union[str, pathlib.Path],
    da: xarray.core.dataarray.DataArray,
    filename_indexing: Optional[Tuple[int, str]] = 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 Union[str, pathlib.Path] — A full path, including a filename prefix, describing where the VTK files should be written.
  • da xarray.core.dataarray.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).
  • filename_indexing Optional[Tuple[int, str]] — 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: Union[str, pathlib.Path],
    da: xarray.core.dataarray.DataArray,
    filename_indexing: Optional[Tuple[int, str]] = 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 Union[str, pathlib.Path] — A full path, including a filename prefix, describing where the VTK files should be written.
  • da xarray.core.dataarray.DataArray — The DataArray to write. Must have dimensions (“x”, “y”, and “t”) (2-D) or (“x”, “y”, “z”, “t”) (3-D).
  • filename_indexing Optional[Tuple[int, str]] — 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: numpy.ndarray,
        crds: numpy.ndarray,
        data: numpy.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 numpy.ndarray — The connectivity array.
  • crds numpy.ndarray — The coordinate array.
  • data numpy.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: Union[str, pathlib.Path],
    field: str,
    output_type: str,
    time_steps: builtins.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 Union[str, pathlib.Path] — 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 builtins.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) -> numpy.ndarray:
    ...

Get the centroid of each element.

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

Get the nodal locations of each element.

Returns numpy.ndarray
sizes()
def sizes(
    filename: Union[str, pathlib.Path], field: str, output_type: str
) -> Tuple[int, ...]:
    ...

Get the sizes on disk of a wavefield data array.

Parameters
  • filename Union[str, pathlib.Path] — 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.