pisces.particles.utils.inspect_fields

pisces.particles.utils.inspect_fields(path: str | Path) → dict[str, list[tuple[str, tuple[int, ...]]]]

Inspect the available fields for each particle species in a dataset without fully loading it.

This function opens the HDF5 particle file, iterates over its top-level groups (each representing a particle species), skips any groups marked with the NOT_PARTICLE_GROUP attribute set to a truthy value, and collects the names and per-particle shapes of all datasets in each group.

The “per-particle shape” is defined as dataset.shape[1:]—the shape of each individual particle’s data entry (excluding the leading dimension which counts particles).

Parameters:

path (str or Path) – Path to the HDF5 particle file.

Returns:

Mapping of particle species names to a list of (field_name, element_shape) tuples, where element_shape is the shape of one particle’s data.

Return type:

dict[str, list[tuple[str, tuple[int, ]]]]

Raises:

FileNotFoundError – If the file does not exist or is not a regular file.