pisces.particles.base.ParticleDataset.add_particle_type#

ParticleDataset.add_particle_type(name: str, num_particles: int, metadata: dict = None, **kwargs)[source]#

Add a new particle group to the dataset.

This method creates a new HDF5 group representing a particle type (e.g., "baryons", "dark_matter") and assigns the required metadata attribute NUMBER_OF_PARTICLES to the group. Optional metadata can be added via the metadata dictionary or keyword arguments. This method is intended to be general and extensible for use in simulation initialization, preprocessing, or structured data generation.

It is safe to override in subclasses that implement additional constraints or need to attach simulation-specific annotations, provenance, or physical properties to each group.

Parameters:

  • name (str) – The name of the new particle group. This must be unique within the dataset and conform to HDF5 naming rules (alphanumeric, no slashes).

  • num_particles (int) – The number of particles in the new group. This value is stored in the group’s metadata under the NUMBER_OF_PARTICLES key and is required for downstream field shape validation.

  • metadata (dict, optional) – A dictionary of metadata attributes to attach to the group. Keys must be strings and values must be serializable by HDF5 (e.g., int, float, str). These attributes will be written in addition to NUMBER_OF_PARTICLES.

  • **kwargs – Additional metadata attributes provided as keyword arguments. These are merged with metadata and override any overlapping keys. Use this to quickly attach single attributes.

Raises:

ValueError – If a group with the specified name already exists in the dataset.

Notes

  • All metadata is stored as HDF5 attributes on the group object.

  • This method does not allocate any fields or datasets; it only creates the group and metadata.

  • Subclasses may override this method to add simulation-specific metadata keys or validation logic.