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

classmethod InitialConditionsCartesian.create_ics(directory: str | Path, *models: dict, file_processing_mode: str = 'copy', **kwargs)#

Create a new initial conditions (IC) directory and return an InitialConditions instance.

This is the main entry point for building an IC set from scratch. It performs all required filesystem setup, model validation, and configuration writing.

Workflow

  1. Directory setup:

    • Create the target directory if it does not exist.

    • If it exists and is non-empty, overwrite=True is required in kwargs to clear it safely.

  2. Model processing:

    • Each model definition (dict) is validated via _validate_input_model().

    • Files are copied or moved into the IC directory via _process_model().

  3. Configuration file:

    • Metadata and processed model information are assembled.

    • A YAML file IC_CONFIG.yaml is written for later reload.

Parameters:

  • directory (str or Path) – Target directory for the IC set. Must be empty unless overwrite=True is provided. All of the model files and any connected files will be copied / moved into this directory so that it becomes the centralized location for the IC set.

  • *models (dict) –

    Model definitions. The expected keys in each model may vary from subclass to subclass, but at a minimum we expect:

    • "model_name" : str The unique name/identifier for this model.

    • "model"str, Path, or BaseModel

      The model specification, either as a path to a model file

    • "position" : unyt_array with length units The position of the model in the simulation volume.

    • "velocity" : unyt_array with length/time units The bulk velocity of the model in the simulation volume.

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

    How to handle the provided model files:

    • "copy" – Copy the files into the IC directory (originals remain intact).

    • "move" – Move the files into the IC directory (originals are removed).

  • **kwargs – Additional keyword arguments which are subclass dependent.

Returns:

A fully initialized instance pointing to the new directory.

Return type:

InitialConditions

Raises:

  • FileExistsError – If the directory exists and is non-empty, and overwrite is False.

  • FileNotFoundError – If a referenced model file does not exist.

  • ValueError – If a model definition is missing required keys or is otherwise invalid.

Notes

  • This method is not intended to be overridden by subclasses. Instead, override the following hooks to customize behavior:

    • _validate_input_model()

    • _process_model()

    • _process_metadata()

  • The returned instance is ready for immediate use in frontend converters (e.g., Gadget, AREPO).