pisces.extensions.simulation.core.initial_conditions.InitialConditions3DCartesian.compute_center_of_mass#

InitialConditions3DCartesian.compute_center_of_mass(models: str | list[str] = 'all', masses: dict[str, unyt_quantity] | None = None)#

Compute the mass-weighted center of mass (COM) position for one or more models in the initial conditions.

The COM is calculated as:

\[\mathbf{R}_{\mathrm{COM}} = \frac{\sum_i m_i \mathbf{r}_i}{\sum_i m_i}\]

where m_i is the total mass of model i and r_i is its position.

Mass values are obtained in the following order:

  1. If masses is provided, use those values (must map model name → scalar mass).

  2. Otherwise, attempt to read total_mass from the model’s metadata via get_model_metadata().

Parameters:

  • models (str or list of str, optional) – Which models to include in the COM calculation. If "all", all models in models are used. Otherwise, provide an explicit list of model names. If a single model name is provided as a string, it will be treated as a list of one model.

  • masses (dict of str, unyt_quantity, optional) – Optional mapping from model name to its total mass. If provided for a given model, this value overrides the total_mass from metadata.

Returns:

The COM position vector with shape (ndim,) and units of length.

Return type:

unyt.array.unyt_array

Raises:

  • KeyError – If any specified model name is not found in the initial conditions.

  • ValueError – If a required mass is missing from both masses and the model metadata.