pisces.particles.base.ParticleDataset.rotate_particles#

ParticleDataset.rotate_particles(norm: ndarray, angle: float, groups: list[str] = None, fields: tuple[str, ...] = None)[source]#

Rotate vector fields in specified particle groups around a given axis.

This method rotates each specified vector field (e.g., particle_position, particle_velocity) around the axis defined by norm by a given angle. The rotation is applied uniformly across all particles in the specified groups.

The transformation uses the Rodrigues’ rotation formula, which constructs a rotation matrix for an axis–angle pair. For a unit vector \(\hat{n}\) and angle \(\theta\), the formula is:

\[R = I + \sin\theta [\hat{n}]_\times + (1 - \cos\theta) [\hat{n}]_\times^2\]

where \([\hat{n}]_\times\) is the skew-symmetric matrix of the axis vector. For more details, see: Rodrigues Formula.

Parameters:

  • norm (array_like) – A 3-element vector representing the rotation axis. This does not need to be normalized; it will be internally converted to a unit vector.

  • angle (float) – The rotation angle in radians.

  • groups (list of str, optional) – The particle groups to apply the rotation to. If None, all particle groups are used.

  • fields (tuple of str, optional) – The vector fields to rotate. Defaults to (“particle_position”, “particle_velocity”).

Raises:

ValueError – If the axis is not a 3-element vector, or if the angle is invalid.