Struct HyperbolicAngle 

pub struct HyperbolicAngle {
    pub angles: (f64, f64, f64),
}

Combine rotations and boosts in hyperbolic space.

“Hyperbolic rotations” describe elements of the group SO(N,1), which preserve Hyperbolics embedded in Minkowski<N+1>. Transformations include pure spatial rotations as well as “boosts”.

For two-dimensional hyperbolic surfaces, use HyperbolicAngle to implement elements of SO(2,1) which rotate points about the z-axis or boost points along the x- and y-axes. SO(2,1) transformations represent symmetries of two-dimensional hyperbolic space. The algebra so(2,1) is generated by the matrices

K_x = \begin{bmatrix} 0&0&1\\ 0&0&0\\1&0&0 \end{bmatrix} \qquad\qquad
K_y = \begin{bmatrix} 0&0&0\\ 0&0&1\\0&1&0 \end{bmatrix}\qquad\qquad
J_z = \begin{bmatrix} 0&-1&0\\ 1&0&0\\0&0&0 \end{bmatrix}

which satisfy the commutation relations

[J_z,K_x] = K_y \qquad [K_x,K_y] = -J_z \qquad [J_z, K_y] = -K_x

The group elements SO(2,1) can be obtained by exponentiating the generators near identity, i.e.,

G = \exp(aJ_z + b K_x + c K_y)

In particular,

\exp(aJ_z) = \begin{bmatrix}\cos(a)&-\sin(a)&0\\ \sin(a)&\cos(a)&0 \\ 0&0&1\end{bmatrix}
\\ \exp(bK_x) = \begin{bmatrix}\cosh(b)&0&\sinh(b)\\ 0&1&0 \\ \sinh(b)&0&\cosh(b)\end{bmatrix}
\\ \exp(cK_y) = \begin{bmatrix}1&0&0\\ 0&\cosh(c)&\sinh(c) \\ 0&\sinh(c)&\cosh(c)\end{bmatrix}

HyperbolicAngle is a struct of three real numbers $(a,b,c)$ which parameterize the generators in this exponential map. The first value $a$ may be interpreted as a rotation angle, while the latter two numbers $b, c$ may be interpreted as rapidities for boosts along the x- and y- directions, respectively. Use HyperbolicRotationMatrix to generate the matrix from the values defined by HyperbolicAngle.

Rotation about z axis:

use approxim::assert_relative_eq;
use hoomd_manifold::{
    HyperbolicAngle, HyperbolicRotate, HyperbolicRotationMatrix, Minkowski,
};
use std::f64::consts::PI;

let v = Minkowski::from([1.0, 0.0, 1.0]);
let rotation_about_z = HyperbolicAngle::from((PI / 2.0, 0.0_f64, 0.0_f64));
let matrix = HyperbolicRotationMatrix::from(rotation_about_z);
let rotated = matrix.hyperbolic_rotate(&v);
assert_relative_eq!(rotated, [0.0, 1.0, 1.0].into(), epsilon = 1e-12);

Boost in the y direction:

use approxim::assert_relative_eq;
use hoomd_manifold::{
    HyperbolicAngle, HyperbolicRotate, HyperbolicRotationMatrix, Minkowski,
};

let v = Minkowski::from([1.0, 0.0, 1.0]);
let boost_in_y = HyperbolicAngle::from((0.0_f64, 0.0_f64, 0.5_f64));
let matrix = HyperbolicRotationMatrix::from(boost_in_y);
let boosted = matrix.hyperbolic_rotate(&v);
assert_relative_eq!(
    boosted,
    [1.0, (0.5_f64).sinh(), (0.5_f64).cosh()].into(),
    epsilon = 1e-12
);

The default value HyperbolicAngle::Default returns the tuple (0.0,0.0,0.0), which corresponds to the identify transformation.

Fields

angles: (f64, f64, f64)

Get the rotation angle in radians.

Implementations

impl HyperbolicAngle

pub fn to_reduced(self) -> Self

Modulo the second and third components of a HyperbolicAngle by $2 \pi$.

Trait Implementations

impl Clone for HyperbolicAngle

fn clone(&self) -> HyperbolicAngle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HyperbolicAngle

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

Formats the value using the given formatter.

impl Default for HyperbolicAngle

fn default() -> HyperbolicAngle

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for HyperbolicAngle

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for HyperbolicAngle

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

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

impl Distribution<HyperbolicAngle> for StandardUniform

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

Sample a random hyperbolic angle.

Note that the distribution is not truly uniform—the boost magnitude is sampled from a square-root distribution (between zero and one) while the angle is sampled from a uniform distribution between 0 and $2\pi$.

Every point on the Hyperbolic can be generated by a boost in the x-direction followed by a rotation. The Baker-Campbell-Hausdorff Lemma gives an expression for the relationship between subsequent SO(2,1) transformations and the so(2,1) algebra generators. Explicitly,

\exp[\theta J_z]\exp[v K_x] = \exp[(\theta + \frac{1}{12}\theta v^2)J_z + (v-\frac{1}{12}\theta^2v)K_x + \frac{1}{2}\theta v K_y + \text{higher order}]

To avoid clustering around the cusp of the Hyperbolic, the random boost parameter $v$ is sampled from a uniform distribution between 0 and 1 and then passed through a square root function.

Example

use approxim::assert_relative_eq;
use hoomd_manifold::{
    HyperbolicAngle, HyperbolicRotate, HyperbolicRotationMatrix, Minkowski,
};
use hoomd_vector::{Metric, Vector};
use rand::{RngExt, SeedableRng, rngs::StdRng};

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

let matrix = HyperbolicRotationMatrix::from(v);
let origin = Minkowski::from([0.0, 0.0, 1.0]);
let point = matrix.hyperbolic_rotate(&origin);
assert_relative_eq!(
    -1.0,
    point.distance_squared(&Minkowski::<3>::default()),
    epsilon = 1e-12
);

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<(f64, f64, f64)> for HyperbolicAngle

fn from(value: (f64, f64, f64)) -> Self

A tuple of three real numbers (a,b,c) describing the coefficients for the generators (J_z, K_x, K_y) of the algebra so(2,1).

impl From<HyperbolicAngle> for HyperbolicRotationMatrix<3>

fn from(angle_list: HyperbolicAngle) -> HyperbolicRotationMatrix<3>

Create a matrix belonging to SO(2,1) from the generators of the algebra so(2,1).

impl PartialEq for HyperbolicAngle

fn eq(&self, other: &HyperbolicAngle) -> 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 Serialize for HyperbolicAngle

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 HyperbolicAngle

impl StructuralPartialEq for HyperbolicAngle