Source code for pyretis.core.velocity

# Copyright (c) 2026, PyRETIS Development Team.
# Distributed under the LGPLv2.1+ License. See LICENSE for more info.
"""Helpers for velocity generation settings.

The single user-facing selector for shooting style is the sign of
``sigma_v``:

* negative values (the default ``-1``) select aimless shooting;
* zero or positive values select soft velocity perturbations whose
  per-particle width is ``sigma_v`` (a scalar or a per-particle array).

The legacy ``aimless`` boolean is stripped from parsed settings (see
:py:func:`pyretis.inout.settings._remove_legacy_tis_settings`); helpers
in this module therefore only look at ``sigma_v``.
"""
import numpy as np


def is_aimless_velocity_setting(settings):
    """Return True when velocity settings select aimless shooting.

    Parameters
    ----------
    settings : dict
        Mapping containing a ``sigma_v`` key. A missing key is treated
        as the default ``-1`` (aimless), matching the input-file
        default in :py:data:`pyretis.inout.settings.SECTIONS`.

    """
    sigma_v = settings.get('sigma_v', -1)
    return bool(np.all(np.asarray(sigma_v) < 0.0))


def make_velocity_settings(tis_settings):
    """Build per-engine velocity-modification settings.

    If ``tis_settings`` carries a pre-computed imass-scaled width
    (``_sigma_v_scaled``, populated by
    :py:meth:`PathSimulation.__init__`), that array is forwarded;
    otherwise the raw ``sigma_v`` is used.
    """
    sigma_v = tis_settings.get('_sigma_v_scaled',
                               tis_settings.get('sigma_v', -1))
    return {
        'sigma_v': sigma_v,
        'momentum': tis_settings.get('zero_momentum', False),
        'rescale': tis_settings.get('rescale_energy', False),
    }