pyvista_zstd.append_arrays

pyvista_zstd.append_arrays(filename: Path | str, arrays: dict[str, NDArray], *, level: int | None = None, shuffle: ShuffleSpec = False) → None

Append named arrays to an existing .pv file in place.

Each array is stored as an independently-zstd-compressed field_data block. Previously-written compressed frames are never re-read or re-compressed; only the small index plus the file and dataset metadata frames are rewritten, and the whole update is committed atomically.

Parameters:

filenamepathlib.Path | str

Path to an existing .pv file (written by pyvista_zstd.write() or a previous append_arrays()).

arraysdict[str, numpy.ndarray]

Mapping of name -> array. Names must not already exist as a field array in the file. Arrays are stored verbatim (bit-exact round trip) regardless of dtype/shape.

levelint, optional

zstd compression level for the new blocks. Defaults to the file’s recorded compression_level so appended blocks match the original.

shuffle{“auto”, True, False}, default: False

Optionally apply the reversible byte-shuffle pre-filter to the appended blocks (see pyvista_zstd.write()). Disabled by default; "auto" shuffles a multibyte floating-point array only when a trial compression shows it shrinks the data. When any appended block is shuffled the file is promoted to format version 1; already-written frames are untouched and keep their own per-block encoding.

Raises:

ValueError

A name is already a field array in the file, or the suffix is not one the format uses.

NotImplementedError

The file is a MultiBlock, which has no root dataset to append to.

Notes

The appended blocks become visible as field_data arrays: pyvista_zstd.Reader.read() returns them in grid.field_data and pyvista_zstd.Reader.available_field_arrays lists them. Use read_array() / AppendReader to read one block back without decompressing the rest of the file.