Struct Versor 

pub struct Versor(/* private fields */);

A unit Quaternion that represents a 3D rotation.

Versor represents a 3D rotation with a unit quaternion. Rotation follows the Hamilton convention.

Constructing a Versor:

The default Versor is the identity:

use hoomd_vector::Versor;

let v = Versor::default();
assert_eq!(*v.get(), [1.0, 0.0, 0.0, 0.0].into());

Create a Versor that rotates by an angle about an axis:

use hoomd_vector::Versor;
use std::f64::consts::PI;

let v = Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, PI / 2.0);
assert_eq!(
    *v.get(),
    [(PI / 4.0).cos(), 0.0, (PI / 4.0).sin(), 0.0].into()
);

Create a Versor by normalizing a Quaternion:

use hoomd_vector::{Quaternion, Versor};

let q = Quaternion::from([3.0, 0.0, 0.0, 4.0]);
let v = q.to_versor()?;
assert_eq!(*v.get(), [3.0 / 5.0, 0.0, 0.0, 4.0 / 5.0].into());

Create a random Versor:

use hoomd_vector::Versor;
use rand::{RngExt, SeedableRng, rngs::StdRng};

let mut rng = StdRng::seed_from_u64(1);
let v: Versor = rng.random();

Operations using Versor

Rotate a Cartesian<3> by a Versor:

use approxim::assert_relative_eq;
use hoomd_vector::{Cartesian, Rotate, Rotation, Versor};
use std::f64::consts::PI;

let a = Cartesian::from([-1.0, 0.0, 0.0]);
let v = Versor::from_axis_angle([0.0, 0.0, 1.0].try_into()?, PI / 2.0);
let b = v.rotate(&a);
assert_relative_eq!(b, [0.0, -1.0, 0.0].into());

Combine two rotations together:

use hoomd_vector::{Rotation, Versor};
use std::f64::consts::PI;

let a = Versor::from_axis_angle([1.0, 0.0, 1.0].try_into()?, PI / 2.0);
let b = Versor::from_axis_angle([0.0, 0.0, 1.0].try_into()?, PI / 4.0);
let c = a.combine(&b);

Implementations

impl Versor

pub fn from_axis_angle(axis: Unit<Cartesian<3>>, angle: f64) -> Self

Create a Versor that rotates by an angle (in radians) counterclockwise about an axis.

Example

use hoomd_vector::Versor;
use std::f64::consts::PI;

let v = Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, PI / 2.0);
assert_eq!(
    *v.get(),
    [(PI / 4.0).cos(), 0.0, (PI / 4.0).sin(), 0.0].into()
);

pub fn normalized(self) -> Self

Normalize the versor.

Nominally, all Versor instances retain a unit norm. Due to limited floating point precision, this assumption may not hold after repeated operations. Normalize versors when needed to correct this issue.

Example

use hoomd_vector::Versor;
use std::f64::consts::PI;

let a = Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, PI / 2.0);
let b = a.normalized();

pub fn get(&self) -> &Quaternion

Get the unit quaternion.

pub fn arc_distance(&self, other: &Self) -> f64

A metric quantifying the angle (in radians) of the spherical arc separating two Versors.

$d : \mathbb{H} \times \mathbb{H} \to \mathbb{R}^+, \quad d(q_0, q_1) = \arccos(|q_0 \cdot q_1|)$

This value always lies in the range $[0, \pi]$, and is symmetric: while there are multiple arcs separating a pair of quaternions, this metric always chooses the shortest.

pub fn half_euclidean_norm_squared(&self, other: &Self) -> f64

A fast metric on Versors representing elements of SO(3).

$d : \mathbb{H} \times \mathbb{H} \to \mathbb{R}^+, \quad d(q_0, q_1) = 1 - |q_0 \cdot q_1 |$

This has less geometric meaning than the arc_distance metric. However, it is much faster while still obeying the triangle inequality and the axiom $d(q_0, q_1) = d(q_1, q_0)$. This metric always lies in the range $[0, 1]$, and is symmetric such that $d(q, q)$ = $d(q, -q)$.

Trait Implementations

impl AbsDiffEq for Versor

type Epsilon = <Quaternion as AbsDiffEq>::Epsilon

Used for specifying relative comparisons.

fn default_epsilon() -> Self::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool

A test for equality that uses the absolute difference to compute the approximimate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl Clone for Versor

fn clone(&self) -> Versor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Versor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Versor

fn default() -> Self

Create an identity rotation.

Example

use hoomd_vector::Versor;

let v = Versor::default();

impl<'de> Deserialize<'de> for Versor

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Versor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Format a Versor as [{s}, [{v[0]}, {v[1]}, {v[2]}]].

impl Distribution<Versor> for StandardUniform

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Versor

Sample a random Versor from the uniform distribution over all rotations.

Example

use hoomd_vector::Versor;
use rand::{RngExt, SeedableRng, rngs::StdRng};

let mut rng = StdRng::seed_from_u64(1);
let v: Versor = rng.random();

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Map sampled values to type S

impl From<Versor> for RotationMatrix<3>

fn from(versor: Versor) -> RotationMatrix<3>

Construct a rotation matrix equivalent to this versor’s rotation.

When rotating many vectors by the same Versor, improve performance by converting to a matrix first and applying that matrix to the vectors.

Example

use approxim::assert_relative_eq;
use hoomd_vector::{Cartesian, Rotate, RotationMatrix, Versor};
use std::f64::consts::PI;

let a = Cartesian::from([-1.0, 0.0, 0.0]);
let v = Versor::from_axis_angle([0.0, 0.0, 1.0].try_into()?, PI / 2.0);

let matrix = RotationMatrix::from(v);
let b = matrix.rotate(&a);
assert_relative_eq!(b, [0.0, -1.0, 0.0].into());

impl PartialEq for Versor

fn eq(&self, other: &Versor) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RelativeEq for Versor

fn default_max_relative() -> Self::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Self, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl Rotate<Cartesian<3>> for Versor

fn rotate(&self, vector: &Cartesian<3>) -> Cartesian<3>

Rotate a Cartesian<3> by a Versor

\mathbf{q} \vec{a} \mathbf{q}^*

Example

use approxim::assert_relative_eq;
use hoomd_vector::{Cartesian, Rotate, Rotation, Versor};
use std::f64::consts::PI;

let a = Cartesian::from([-1.0, 0.0, 0.0]);
let v = Versor::from_axis_angle([0.0, 0.0, 1.0].try_into()?, PI / 2.0);
let b = v.rotate(&a);
assert_relative_eq!(b, [0.0, -1.0, 0.0].into());

type Matrix = RotationMatrix<3>

Type of the related rotation matrix

impl Rotation for Versor

fn combine(&self, other: &Self) -> Self

Combine two rotations.

The resulting versor is obtained by quaternion multiplication.

\mathbf{q}_{ab} = \mathbf{q}_a \mathbf{q}_b

Example

use hoomd_vector::{Rotation, Versor};

let q_a = Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, 1.5);
let q_b = Versor::from_axis_angle([1.0, 0.0, 0.0].try_into()?, 0.125);
let q_ab = q_a.combine(&q_b);

fn identity() -> Self

Create the identity Versor: [1, [0, 0, 0]]

Example

use hoomd_vector::{Rotation, Versor};

let identity = Versor::identity();

fn inverted(self) -> Self

Create a Versor that performs the inverse rotation of the given versor.

\mathbf{q}^*

Example

use hoomd_vector::{Rotation, Versor};

let v = Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, 1.5);
let v_star = v.inverted();

impl Serialize for Versor

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Versor

impl StructuralPartialEq for Versor