pisces.extensions.simulation.core.initial_conditions.InitialConditions.add_particles_to_model#

InitialConditions.add_particles_to_model(particle_path: str | Path, model_name: str, file_processing_mode: str = 'copy', overwrite: bool = False)[source]#

Attach a particle dataset file to an existing model in the initial conditions.

This method:

  1. Validates that the target model exists in the configuration.

  2. Checks if the specified particle file exists on disk.

  3. Copies or moves the file into the initial conditions directory, naming it <model_name>_p.hdf5 to avoid collisions.

  4. Updates the configuration to record the particle file path.

  5. Optionally overwrites any previously associated particle file if overwrite=True.

Parameters:

  • particle_path (str or Path) – Path to the particle dataset file to associate with the model.

  • model_name (str) – The name/identifier of the model to which the particles will be added.

  • file_processing_mode ({"copy", "move"}, default "copy") –

    How to handle the provided file:

    • "copy" – Copy the file into the IC directory (original remains intact).

    • "move" – Move the file into the IC directory (original is removed).

  • overwrite (bool, optional) – If True, any existing particle file for this model will be overwritten. If False (default), an error will be raised if a particle file is already associated with the model.

Raises:

  • KeyError – If no model with the given model_name exists in the configuration.

  • FileNotFoundError – If the specified particle_path does not exist.

  • ValueError – If file_processing_mode is not one of "copy" or "move".

  • FileExistsError – If a particle file is already associated with the model and overwrite is False.