CodeEntropy.levels.forces module

Force/torque weighting and per-frame second-moment construction.

This module provides utilities for transforming atomic forces into bead-level generalized forces (translation) and torques (rotation), and for assembling per-frame second-moment matrices used downstream in entropy calculations.

class CodeEntropy.levels.forces.ForceTorqueCalculator[source]

Bases: object

Computes weighted generalized forces/torques and per-frame second moments.

This class provides:

  • Mass-weighted generalized translational forces from per-atom forces.

  • Moment-of-inertia-weighted generalized torques from per-atom positions and forces, optionally using an axes_manager for PBC-aware displacements.

  • Per-frame second-moment (outer product) matrices for concatenated bead vectors, used downstream for covariance/entropy calculations.

compute_frame_covariance(force_vecs: Sequence[ndarray], torque_vecs: Sequence[ndarray]) → tuple[ndarray, ndarray][source]

Compute per-frame second-moment matrices for force/torque vectors.

Note

This returns outer(x, x) where x is the concatenation of all bead vectors in the frame.

Parameters:

  • force_vecs – Sequence of per-bead force vectors (3,).

  • torque_vecs – Sequence of per-bead torque vectors (3,).

Returns:

Tuple (F, T) where each is a (3N, 3N) second-moment matrix.

get_weighted_forces(bead: Any, trans_axes: ndarray, highest_level: bool, force_partitioning: float) → ndarray[source]

Compute a mass-weighted translational generalized force.

Parameters:

  • bead – MDAnalysis AtomGroup-like bead with .atoms and .total_mass(). Each atom must provide .force (shape (3,)).

  • trans_axes – Transform matrix for translational forces, shape (3, 3).

  • highest_level – If True, apply force_partitioning scaling.

  • force_partitioning – Scaling factor applied when highest_level is True.

Returns:

Mass-weighted generalized force vector, shape (3,).

Raises:

ValueError – If mass is non-positive or trans_axes shape is invalid.

get_weighted_torques(bead: Any, rot_axes: ndarray, center: ndarray, force_partitioning: float, moment_of_inertia: ndarray, axes_manager: Any | None, box: ndarray | None) → ndarray[source]

Compute a moment-weighted generalized torque.

Parameters:

  • bead – MDAnalysis AtomGroup-like bead with .positions and .forces (N,3).

  • rot_axes – Rotation matrix into bead frame, shape (3,3).

  • center – Reference center for displacement vectors, shape (3,).

  • force_partitioning – Scaling factor applied to forces before torque sum.

  • moment_of_inertia – Principal moments aligned with rot_axes, shape (3,).

  • axes_manager – Optional PBC displacement provider.

  • box – Periodic box passed to axes_manager when used.

Returns:

Weighted torque vector, shape (3,).

Raises:

ValueError – If shapes are invalid.

class CodeEntropy.levels.forces.TorqueInputs(rot_axes: ndarray, center: ndarray, force_partitioning: float, moment_of_inertia: ndarray, axes_manager: Any | None = None, box: ndarray | None = None)[source]

Bases: object

Container for torque computation inputs.

Variables:

  • rot_axes (numpy.ndarray) – Rotation matrix mapping lab-frame vectors into the bead frame, shape (3, 3).

  • center (numpy.ndarray) – Reference center for torque arm vectors, shape (3,).

  • force_partitioning (float) – Scaling factor applied to forces before torque accumulation.

  • moment_of_inertia (numpy.ndarray) – Principal moments (aligned with rot_axes), shape (3,).

  • axes_manager (Any | None) – Optional object that provides: get_vector(center, positions, box) -> displacement vectors (PBC-aware).

  • box (numpy.ndarray | None) – Optional periodic box passed to axes_manager.get_vector.

axes_manager: Any | None = None
box: ndarray | None = None
center: ndarray
force_partitioning: float
moment_of_inertia: ndarray
rot_axes: ndarray