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

InitialConditions.compute_center_of_mass_velocity(models: str | list[str] = 'all', masses: dict[str, unyt_quantity] | None = None)[source]#

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

The COM velocity is:

\[\mathbf{V}_{\mathrm{COM}} = \frac{\sum_i m_i \mathbf{v}_i}{\sum_i m_i}\]

where m_i is the total mass of model i and v_i is its velocity vector.

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.

Parameters:

  • models (str or list of str, optional) – Which models to include in the COM velocity calculation. If "all", all models in models are used. If a single model name is given, it will be treated as a list of one.

  • masses (dict of str, unyt_quantity, optional) – Optional mapping from model name to its total mass. Overrides total_mass in metadata if provided.

Returns:

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

Return type:

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.