pisces.particles.base.ParticleDataset.add_particle_field#

ParticleDataset.add_particle_field(group_name: str, field_name: str, data: unyt_array | ndarray, metadata: dict = None, overwrite: bool = False)[source]#

Add a new field (dataset) to an existing particle group.

This method creates and writes a new field to the specified particle group within the dataset. The data can be a numpy.ndarray or a unyt_array. Units (if present) will be stored in the dataset metadata. Additional metadata may also be included via the metadata argument.

Parameters:

  • group_name (str) – The name of the particle group to which the field will be added. This must be a pre-existing group in the particle dataset.

  • field_name (str) – The name of the new field to create (e.g., "particle_mass"). If the field_name is already specified in the group, it will raise an error unless overwrite is True.

  • data (unyt_array or ndarray) – The data to write to the new field. The leading dimension must match the number of particles in the group.

  • metadata (dict, optional) – Optional dictionary of metadata to attach to the dataset. This is generally used by subclasses of the base class to add type specific metadata.

  • overwrite (bool, optional) – Whether to overwrite an existing dataset with the same name. Defaults to False.

Raises:

  • KeyError – If the group does not exist, or if the field exists and overwrite is False.

  • ValueError – If the field’s leading dimension does not match the group’s particle count.