Crate hoomd_vector 

Vector and quaternion math.

hoomd_vector implements vector math types and operations used in scientific computations, specifically those used in the HOOMD molecular simulation software suite. Its API is firmly rooted in mathematical principles. Users in other fields may find hoomd_vector useful outside the context of HOOMD.

Vectors

The Vector trait describes any type that is a member of a metric vector space. Write code with a Vector trait bound when you can express the computation with vector arithmetic and a distance metric. Your generic code can then be invoked on vector types with any dimension or representation (e.g. spherical coordinates).

use hoomd_vector::Vector;

fn some_function<V: Vector>(a: &V, b: &V, c: &V) -> f64 {
    (*a + *b).distance(&c)
}

The InnerProduct subtrait of Vector describes any type that is a member of an inner product space. InnerProduct implements vector norms and dot products.

use hoomd_vector::InnerProduct;

fn some_other_function<V: InnerProduct>(a: &V, b: &V) -> f64 {
    a.dot(b) / (a.norm_squared())
}

Require additional trait bounds to perform more specific operations, such as Cross:

use hoomd_vector::{Cross, InnerProduct};

fn triple<V: InnerProduct + Cross>(a: &V, b: &V, c: &V) -> f64 {
    a.dot(&b.cross(c))
}

Use the provided Cartesian type to concretely represent N-dimensional vectors, or when your algorithm requires Cartesian coordinates:

use hoomd_vector::{Cartesian, InnerProduct};

let a = Cartesian::from([1.0, 2.0]);
let b = Cartesian::from([-2.0, 1.0]);

let product = a.dot(&b);
assert_eq!(product, 0.0);

let x = a[0];
let y = a[1];

Quaternions

Quaternions are generalized complex numbers and a convenient way to describe the motion of rotating bodies. The Quaternion type describes a single quaternion and implements the associated algebra.

use hoomd_vector::Quaternion;

let a = Quaternion::from([1.0, -2.0, 6.0, -4.0]);
let b = Quaternion::from([-2.0, 6.0, 4.0, 1.0]);

let norm = a.norm();
assert_eq!(norm, 57.0_f64.sqrt());

let sum = a + b;
assert_eq!(sum, [-1.0, 4.0, 10.0, -3.0].into());

let product = a * b;
assert_eq!(product, [-10.0, 32.0, -30.0, -35.0].into());

A unit quaternion (called a Versor in mathematics) can represent a 3D rotation.

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());

Rotations

A Rotation describes a transformation from one orthonormal basis to another. A type that implements Rotation has an identity. Instances of that type have an inverse and can be combined with other rotations.

Through the Rotate<V> trait, a Rotation can rotate a vector.

As with Vector, you can implement methods that operate on generic types:

use hoomd_vector::{Rotate, Vector};

fn rotate_and_translate<R: Rotate<V>, V: Vector>(r: &R, a: &V, b: &V) -> V {
    r.rotate(a) + *b
}

Angle implements rotations on Cartesian<2> vectors.

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

let v = Cartesian::from([-1.0, 0.0]);
let a = Angle::from(PI / 2.0);
let rotated = a.rotate(&v);
assert_relative_eq!(rotated, [0.0, -1.0].into());

Versor implements rotations on Cartesian<3> vectors.

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());

Convert to a RotationMatrix when you need to rotate many vectors by the same rotation. RotationMatrix::rotate is typically several times faster than Versor::rotate.

Random distributions

hoomd_vector interoperates with rand to generate random vectors and rotations.

The StandardUniform distribution randomly samples rotations uniformly from the set of all vectors or rotations.

• Vectors are uniformly sampled from the [-1,1] hypercube
• Angles are uniformly sampled from the half-open interval [0, 2π)
• Versors are uniformly sampled from the surface of the 3-Sphere, which doubly covers SO(3), the manifold of rotations in three dimensions.

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

let mut rng = StdRng::seed_from_u64(1);
let vector: Cartesian<3> = rng.random();
let angle: Angle = rng.random();
let versor: Versor = rng.random();

The Ball distribution samples vectors from the interior of an n-Ball, the set of all points whose distance from the origin is in [0, 1).

use hoomd_vector::{Cartesian, distribution::Ball};
use rand::{Rng, SeedableRng, distr::Distribution, rngs::StdRng};

let mut rng = StdRng::seed_from_u64(1);
let ball = Ball {
    radius: 3.0.try_into()?,
};
let v: Cartesian<3> = ball.sample(&mut rng);

Complete documentation

hoomd-vector is is a part of hoomd-rs. Read the complete documentation for more information.

Modules

distribution

Random distributions of vectors.

Structs

Angle

Rotation in the plane.

Cartesian

A Vector represented by N f64 coordinates.

Quaternion

Extended complex number.

RotationMatrix

Rotate vectors efficiently.

Unit

A Vector with magnitude 1.0.

Versor

A unit Quaternion that represents a 3D rotation.

Enums

Error

Enumerate possible sources of error in fallible vector math operations.

Traits

Cross

A vector space where the cross product is defined.

InnerProduct

Operate on elements of an inner product space.

Metric

Operates on elements on a metric space.

Rotate

Applies the rotation operation to vectors.

Rotation

Describes the transformation from one orthonormal basis to another.

Vector

Operate on elements of a metric vector space.

Functions

pair_system_to_local

Get the relative position and orientation given pairs of positions and orientations.