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

classmethod InitialConditions.create_ics(directory: str | Path, *models, particle_files: dict[str, str | Path] = None, **kwargs)[source]#

Create a new initial conditions (IC) directory with optional particle datasets.

This is a convenience constructor for building an InitialConditions instance from scratch. It will:

  1. Create (or overwrite) the target IC directory on disk.

  2. Process and validate the provided models via _process_models, copying or moving model files into the IC directory.

  3. Optionally process particle dataset files via _process_particle_files if particle_files is provided.

  4. Generate the IC_CONFIG.yaml file containing metadata and model configuration.

Parameters:

  • directory (str or Path) – Path to the directory where the new initial conditions will be created. If the directory already exists and is non-empty, overwrite=True must be provided in kwargs to remove its contents before creation.

  • *models (tuple) –

    One or more model specifications to include in the initial conditions. Each model specification should be a tuple of the form:

    (name, model, position, velocity[, orientation][, spin])

    Where:

    • name : str Unique name/identifier for the model.

    • model : str, ~pathlib.Path or ~pisces.models.core.base.BaseModel Path to a model file on disk or an already loaded BaseModel instance.

    • position : sequence or ~unyt.array.unyt_array Position vector of length ndim with length units (default: meters).

    • velocity : sequence or ~unyt.array.unyt_array Velocity vector of length ndim with velocity units (default: km/s).

    • orientation : optional, sequence or array Orientation vector (shape: (ndim,)) or rotation matrix (shape: (ndim, ndim)). If omitted, the identity is used.

    • spin : optional, float Scalar spin value (unitless). Defaults to 0.0.

  • particle_files (dict of {str: (str or Path)}, optional) – Mapping from model name to path to a particle dataset file. Only processed if provided. Files will be copied or moved into the IC directory with the naming scheme <model_name>_p.hdf5.

  • **kwargs –

    Additional keyword arguments forwarded to _process_models and _process_particle_files. Common options include:

    • file_processing_mode : {“copy”, “move”} Whether to copy (default) or move files into the IC directory.

    • overwrite : bool If True, existing files or directories will be overwritten.

Returns:

An initialized InitialConditions instance for the newly created directory.

Return type:

InitialConditions

Raises:

  • FileExistsError – If directory exists and is non-empty, and overwrite is not True.

  • FileNotFoundError – If any provided model or particle file does not exist.

  • ValueError – If model definitions are invalid or missing required parameters.