pisces.particles.base.ParticleDataset.reorient_particles#

ParticleDataset.reorient_particles(direction_vector: ndarray, spin: float, groups: list[str] = None, fields: tuple[str, ...] = None)[source]#

Reorient particles given a direction vector and spin angle.

This method aligns the +z axis with the specified direction_vector and then applies a spin rotation about the new axis. The transformation is applied to the specified vector fields (e.g., particle_position, particle_velocity) in the specified particle groups.

The transformation uses a two-step process:

  1. Alignment: Compute the minimal rotation that aligns the +z axis with the

    normalized direction_vector.

  2. Spin: Apply a rotation by spin radians about the new z-axis (aligned with direction_vector).

The final rotation matrix is the composition of the alignment and spin rotations.

Parameters:

  • direction_vector (array_like) – Target direction to become the new +z axis. Need not be unit, but must be nonzero.

  • spin (float) – Spin angle (in radians) applied about the new axis after alignment.

  • groups (list of str, optional) – Particle groups to transform. If None, all groups are used.

  • fields (tuple of str, optional) – Vector fields to transform. Defaults to ("particle_position", "particle_velocity").

Returns:

The 3x3 rotation matrix applied: R = R_spin @ R_align.

Return type:

numpy.ndarray