pisces.models.core.base.BaseModel.add_field#

BaseModel.add_field(name: str, element_shape: tuple[int, ...] = (), units: str | Unit = None, data: unyt_array | ndarray = None, overwrite: bool = False, **kwargs)[source]#

Add a new physical field to the model.

Fields represent physical quantities (e.g., density, temperature, velocity) defined on the model’s spatial grid. This method creates a new field with optional initialization from user-provided data.

Parameters:

  • name (str) – Name of the field (e.g., "density").

  • element_shape (tuple of int, optional) – Extra trailing dimensions for vector/tensor fields (e.g., (3,)). Defaults to ().

  • units (str or unyt.Unit, optional) – Units for the field. If None, the field is unitless.

  • data (unyt_array or numpy.ndarray, optional) – Values to initialize the field. If None, initialized to zeros. Must have shape grid.shape + element_shape.

  • overwrite (bool, optional) – If True, replaces an existing field with the same name. If False, raises KeyError if the field already exists.

Raises:

  • ValueError – If provided data does not match the expected shape.

  • KeyError – If the field already exists and overwrite=False.

Notes

  • The field is written to both memory and the on-disk HDF5 file under /FIELDS/{name}.

  • Unit handling is powered by unyt.

On this page

This Page