Mondaic

salvus.mesh.data_structures.salvus_mesh.serialization.hdf5

salvus.mesh.data_structures.salvus_mesh.serialization.hdf5 salvus mesh data_structures salvus_mesh serialization hdf5

Serialization to HDF5 for the Salvus Mesh object and its blocks.

Functions

add_vtkhdf_group()

def add_vtkhdf_group(
    fh: h5py.File,
    transform_fields: bool = False,
    compression: tuple[str, int] | None = None,
) -> None: ...

Add the VTKHDF group to the HDF5 file.

The VTKHDF group adds meta-data (and, if coordinate transforms are required, data) that allow for the visualization of meshes in the new format in ParaView.

Parameters
  • fh h5py.File — The open file handle of the HDF5 file. It is expected that a valid SALVUS group resides in the file, and it is to this file that the visualization data will be written.
  • transform_fields bool — Whether to transform the fields from the GLL basis to an equidistantly-spaced Lagrange basis. Technically, only the latter is supported by ParaView, and as such high-order visualizations will present with artifacts if this is not set to True. However, for low-order meshes (model order 2 or less) this is not necessary, as the GLL basis is already equidistantly spaced. In any case, for standard 1st order visualizations artifacts (if any) should be minimal.
  • compression tuple[str, int] | None — Turn on compression. Pass a tuple of (method, option), e.g. ("gzip", 2). Slows down writing but the resulting files can be much smaller.
Returns None

create_vtk_block()

def create_vtk_block(
    vtk_group: h5py.Group,
    block_group: h5py.Group,
    transform_fields: bool = False,
    compression: tuple[str, int] | None = None,
) -> int: ...

Create a VTKHDF block as a child of another HDF5 group.

As a side effect, creates a VTKHDF block in the HDF5 file.

This minimal implementation stores soft links to the heavy datasets already present in the Salvus block group so that ParaView can find them via the VTKHDF assembly. It is intentionally small and fast.

Parameters
  • vtk_group h5py.Group — VTKHDF HDF5 group.
  • block_group h5py.Group — An HDF5 group for a valid block (SALVUS/block_*).
  • transform_fields bool — Whether to transform the fields from the GLL basis to an equidistantly-spaced Lagrange basis. This is useful for visualization, as the fields are stored in GLL coordinates, which are not equidistantly spaced, whereas ParaView expects them to be equidistantly spaced.
  • compression tuple[str, int] | None — Turn on compression. Pass a tuple of (method, option), e.g. ("gzip", 2). Slows down writing but the resulting files can be much smaller.
Returns int — The block ID of the created VTKHDF block.

read_block()

def read_block(
    source: str | pathlib.Path | h5py.File | h5py.Group, block_id: int
) -> MeshBlock: ...

Read a single Salvus mesh block from an HDF5 file or group.

Note that if a file path is provided, the file will be opened and closed within this function. If an open h5py.File or h5py.Group is provided, it is the caller’s responsibility to manage the file’s lifecycle.

Parameters
  • source str | pathlib.Path | h5py.File | h5py.Group — Path to an HDF5 file, an open h5py.File, or an HDF5 group corresponding to the /SALVUS/block_<id> group.
  • block_id int — The block ID to read.
Returns MeshBlock — The reconstructed MeshBlock object.

read_mesh()

def read_mesh(source: str | pathlib.Path | h5py.File | h5py.Group) -> Mesh: ...

Read a Salvus mesh from an HDF5 file or group.

Note that if a file path is provided, the file will be opened and closed within this function. If an open h5py.File or h5py.Group is provided, it is the caller’s responsibility to manage the file’s lifecycle.

Parameters
  • source str | pathlib.Path | h5py.File | h5py.Group — Path to an HDF5 file, an open h5py.File, or an HDF5 group corresponding to the /SALVUS group.
Returns Mesh — The reconstructed Mesh object.

verify_file_layout()

def verify_file_layout(file_handle: h5py.File) -> None: ...

Validate that an HDF5 file conforms to Salvus mesh layout.

Parameters
  • file_handle h5py.File — Open h5py.File handle expected to contain /SALVUS with required sub-groups and block structure.
Returns None

wrap_reader()

def wrap_reader(
    reader: typing.Callable[[h5py.Group], return_type],
    source: str | pathlib.Path | h5py.File | h5py.Group,
) -> return_type: ...

Wrapper function to read a Salvus mesh property from an HDF5 file or group.

Parameters
  • reader typing.Callable[[h5py.Group], return_type] — A function that takes an h5py.Group corresponding to the /SALVUS group and returns the desired property.
  • source str | pathlib.Path | h5py.File | h5py.Group — Path to an HDF5 file, an open h5py.File, or an HDF5 group corresponding to the /SALVUS group.
Returns return_type — The result of the reader function.

write_block_to_h5()

def write_block_to_h5(
    salvus_group: h5py.Group,
    block: MeshBlock,
    pad_2d_to_3d: bool = True,
    vtk_compatible_dtypes: bool = False,
    geid_encoding: typing.Literal[
        "auto", "full", "run_length_encoding"
    ] = "auto",
    compression: tuple[str, int] | None = None,
) -> None: ...

Write a mesh block to an HDF5 group.

Parameters
  • salvus_group h5py.Group — The mesh’s root group /SALVUS.
  • block MeshBlock — The mesh block to write.
  • pad_2d_to_3d bool — Whether to pad 2-D points to 3 components by appending a zero z-component, to make VTK happy.
  • vtk_compatible_dtypes bool — Whether to convert field dtypes to be VTK compatible (e.g., bool to uint8). Set to True when VTKHDF visualization will be added to avoid duplication.
  • geid_encoding typing.Literal['auto', 'full', 'run_length_encoding'] — The encoding to use for global element IDs. Options are "auto" (default, choose automatically based on mesh size and structure), "full" (store all global element IDs), and "run_length_encoding" (use run-length encoding for global element IDs).
  • compression tuple[str, int] | None — Turn on compression. Pass a tuple of (method, option), e.g. ("gzip", 2). Slows down writing but the resulting files can be much smaller.
Returns None

write_mesh_to_h5()

def write_mesh_to_h5(
    mesh: Mesh,
    filename: str | pathlib.Path,
    overwrite: bool = True,
    add_vtk_data: bool = True,
    geid_encoding: typing.Literal[
        "auto", "full", "run_length_encoding"
    ] = "auto",
    compression: tuple[str, int] | None = None,
) -> None: ...

Write the mesh to an HDF5 file in the new mesh format.

Parameters
  • mesh Mesh — The mesh to write.
  • filename str | pathlib.Path — The name of the HDF5 file to write to. If visualization is desired, the suffix should be .vtkhdf (to allow e.g. ParaView to auto-detect the correct reader).
  • overwrite bool — Whether to overwrite an existing file.
  • add_vtk_data bool — Whether to add the VTKHDF group to the file for visualization in ParaView.
  • geid_encoding typing.Literal['auto', 'full', 'run_length_encoding'] — The encoding to use for global element IDs. Options are "auto" (default, choose automatically based on mesh size and structure), "full" (store all global element IDs), and "run_length_encoding" (use run-length encoding for global element IDs).
  • compression tuple[str, int] | None — Turn on compression. Pass a tuple of (method, option), e.g. ("gzip", 2). Slows down writing but the resulting files can be much smaller.
Returns None