pisces.particles.gadget.AREPOParticleDataset.build_particle_dataset#

classmethod AREPOParticleDataset.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, double_precision: bool = True, coordinates_in_double_precision: bool = True, long_ids: bool = True, enable_mhd: bool = False, enable_cooling: bool = False, passive_scalars: int = 0) → AREPOParticleDataset[source]#

Create a new HDF5 particle dataset in AREPO IC format.

This is the primary factory method for generating particle datasets that can be used as initial conditions in simulation codes. It writes a complete, self-contained HDF5 file containing the particle fields required by AREPO (and optional fields depending on physics modules).

Parameters:

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

  • number_of_particles (sequence of int) – Number of particles for each particle type. The length must match ntypes. For example, [1000, 2000, 0, 0, 500, 0] specifies 1000 gas cells, 2000 dark matter particles, 500 stars, and no others.

  • box_size (unyt.unyt_quantity) – Physical size of the simulation box (must have length units). This is written into the dataset metadata and header.

  • ntypes (int, default 6) – Number of particle types to include. Gadget/AREPO use 6 by default (0=gas, 1=DM, 2=disk, 3=bulge, 4=stars, 5=BHs), but this may be larger in customized builds.

  • unit_system (unyt.UnitSystem, optional) – Unit system for tagging dataset attributes (e.g., cgs or astrophysical). If omitted, a default astrophysical unit system is used.

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

  • fields (dict[str, unyt.unyt_array], optional) –

    Optional dictionary of fields to write into the dataset at creation. Keys must be of the form "<particle_type>.<field_name>", and each value must be a unyt.array.unyt_array instance with the correct shape and units for the specified field.

    Field may also be added, removed, and manipulated after creation. This option simply permits populating fields at creation time.

  • double_precision (bool, default True) – Enable double precision initial conditions. This flag is equivalent to AREPO’s INPUT_IN_DOUBLEPRECISION compile-time option. If True, all floating-point fields are stored as double precision floats as defined by the local system. If False, single precision (float32) is used.

  • coordinates_in_double_precision (bool, default True) – If True, Coordinates are stored in double precision. If False, they are stored as float32. Useful when positions need higher accuracy than velocities or internal energy. This corresponds to the AREPO flag INPUT_COORDINATES_IN_DOUBLEPRECISION.

  • long_ids (bool, default True) – If True, ParticleIDs are stored as 64-bit unsigned integers. If False, 32-bit IDs are used. 64-bit IDs are required for runs with >4 billion particles. This corresponds to the AREPO flag LONGIDS.

  • enable_mhd (bool, default False) – If True, adds MagneticField (3-component vector) to gas particles (PartType0). Required if running with MHD enabled.

  • enable_cooling (bool, default False) – If True, adds ElectronAbundance scalar field to gas particles. This initializes the ionization fraction for cooling modules. Defaults to zero if not supplied.

  • passive_scalars (int, default 0) – If >0, adds a PassiveScalars field with the given number of components for gas particles. These are advected tracers that do not affect dynamics unless used by custom physics modules.

Returns:

The newly created particle dataset object pointing to the file at path.

Return type:

AREPOParticleDataset

Raises:

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

  • ValueError – If particle counts are inconsistent with field shapes or box size.

  • TypeError – If provided fields are not unyt.unyt_array instances.