pisces.particles.base.ParticleDataset.build_particle_dataset#

classmethod ParticleDataset.build_particle_dataset(path: str | Path, *args, fields: dict[str, unyt_array] = None, overwrite: bool = False, **kwargs)[source]#

Create a new ParticleDataset HDF5 file with the given fields.

This method initializes a new HDF5 file, organizes the provided fields into groups based on their dot notation names (e.g., "baryons.particle_mass"), and writes each field to the appropriate group. Each group must have fields with the same number of particles (i.e., matching leading dimension). Global metadata (such as creation date) is also written.

This is the standard factory method for creating new Pisces-compatible particle datasets.

Parameters:

  • path (str or pathlib.Path) – The target path for the new HDF5 file.

  • fields (dict of {str: unyt.array.unyt_array}, optional) – A dictionary mapping dot-notation field names to unyt arrays. If None or empty, a valid file with metadata but no particle data is created.

  • overwrite (bool, optional) – Whether to overwrite the file if it already exists. Defaults to False.

  • *args – Additional positional and keyword arguments passed to the dataset constructor.

  • **kwargs – Additional positional and keyword arguments passed to the dataset constructor.

Returns:

An instance of the newly created dataset.

Return type:

ParticleDataset

Raises:

  • FileExistsError – If the file exists and overwrite is False.

  • IsADirectoryError – If path is a directory.

  • ValueError – If any field name is not in dot notation or group fields mismatch in particle count.