pisces.particles.gadget.GadgetLikeParticleDataset.build_particle_dataset#

classmethod GadgetLikeParticleDataset.build_particle_dataset(path: str | Path, number_of_particles: Sequence, box_size: unyt_quantity, *, ntypes: int = 6, unit_system: UnitSystem = None, overwrite: bool = False, fields: dict = None) → GadgetLikeParticleDataset[source]#

Create a new Gadget-like particle dataset on disk.

This public factory method initializes a new HDF5 file containing the header, particle groups, and required fields in the Gadget/AREPO format. It is the main entry point for generating initial condition files or empty snapshot skeletons.

Parameters:

  • path (str or pathlib.Path) – Destination path for the new HDF5 file. If the file already exists and overwrite is False, a FileExistsError is raised.

  • number_of_particles (sequence of int) – The number of particles of each type to include in the particle dataset. This should be a sequence (e.g., list or tuple) of length ntypes, each element of which is a non-negative integer. If a particle type has zero particles, its group will not be created.

  • box_size (unyt.unyt_quantity) – The physical size of the simulation box. Must carry length units.

  • ntypes (int, default 6) – Number of particle types to include. Gadget-like codes use six by default (0=gas, 1=DM, 2=disk, 3=bulge, 4=stars, 5=BH).

  • unit_system (unyt.UnitSystem, optional) – Unit system for tagging dataset attributes. If not provided, the class default is used.

  • overwrite (bool, default False) – If True, overwrite any existing file at path. If False, raise FileExistsError if the file exists.

  • fields (dict, optional) – Extra particle fields to populate. Keys must be of the form "PartTypeX.FieldName" where X is the particle type index. Values must be unyt.array.unyt_array or numpy.ndarray with the correct leading dimension.

Returns:

A dataset object representing the newly created HDF5 file.

Return type:

GadgetLikeParticleDataset

Raises:

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

  • ValueError – If the number of particles does not match ntypes or if a field shape is inconsistent with its particle group.

  • TypeError – If unit_system is not a unyt.UnitSystem instance.

Notes

  • This overload describes the base API. Subclasses may add further keyword arguments for physics-specific fields (e.g. MHD, cooling).

  • At minimum, each populated particle type will include the required datasets: Coordinates, Velocities, ParticleIDs, and Masses. Gas cells (PartType0) also include Density and InternalEnergy.