Struct Hyperbolic 

pub struct Hyperbolic<const N: usize> { /* private fields */ }

Point on the top sheet of a two-sheeted hyperboloid.

Hyperbolic implements an embedding of the top sheet of an $(N-1)$-dimensional two-sheeted hyperboloid in $N$-dimensional Minkowski space. This surface has constant negative curvature and therefore serves as a model of $(N-1)$-dimensional hyperbolic space.

Explicitly, for N-dimensional Minkowski space with metric $\eta = \operatorname{diag}(+,\cdots,+,-)$, the hyperboloid with skirt width $R$ is defined by the set of points with components satisfying

x_1^2 +\cdots x_{N-1}^2 - x_{N}^2 = -R^2

Where the “top sheet” is defined by the $x_N>0$ solutions. In Minkowski space, the hyperboloid has a natural interpretation as the set of points with the same spacetime interval

\Delta s^2 = \vec{x}^T \eta \vec{x} = x_1^2 +\cdots x_{N-1}^2 - x_{N}^2

Note that the skirt width is fixed at $R=1.0$. In simulation, the global curvature may be tuned by changing the length scale of interactions. For example, rescaling distances by $r \rightarrow r/\ell$ has the same effect as running simulations with skirt length $R = 1/\ell$ or Gauss curvature $K = -\ell^2$.

Hyperbolic implements a Metric that computes the distance of the geodesic passing between two points on a hyperboloid with some given skirt width.

Two points on the hyperboloid with skirt width $R = 1.0$:

use hoomd_manifold::{Hyperbolic, Minkowski};
use hoomd_vector::Metric;

let x = Hyperbolic::from_minkowski_coordinates([0.0, 0.0, 1.0].into());

let y = Hyperbolic::from_minkowski_coordinates(
    [0.0, 1.0, (2.0_f64).sqrt()].into(),
);

assert_eq!(((2.0_f64).sqrt()).acosh(), x.distance(&y));

Remark on Numeric Stability

The hyperboloid model of hyperbolic space performs best when points are located nearby the cusp (i.e., Minkowski coordinates $(0,0,1)$). Because of the way trial moves are validated, Monte Carlo simulations become numerically unstable when any bodies are far away from the cusp. Ideally, simulations should keep bodies within a distance of $\approx 8.0$ from the cusp. All of the boundary conditions implemented for Hyperbolic satisfy this condition and perform well in MC simulations.

Nevertheless, it is often necessary to run larger simulations. Hyperbolic methods will still run simulations with bodies located far away from the cusp, but with a reduced numerical tolerance. Note also that using too small of a maximum translation step size is inherently unstable. Simulations will still run if the specified maximum step size is too small, but Hyperbolic methods would no longer guarantee that translation moves are not translated more than the specified maximum.

A rough method selecting maximum step sizes: If $r_{max}$ is the distance between the cusp and the most distant body, avoid setting the maximum step size to be smaller than $10^{\left(\frac{1}{2}\log_{10}\left[\cosh^2(r_{max})/2\right]-6\right)}$. For example, if the farthest body has Minkowski coordinates $(10^5, 10^5, \sqrt{2\cdot 10^{10} + 1})$, then $r_{max} = 12.5526$ and therefore step sizes smaller than $0.1$ are unstable.

Implementations

impl<const N: usize> Hyperbolic<N>

pub fn coordinates(&self) -> &[f64; N]

Get the coordinates of the point on the hyperboloid.

pub fn point(&self) -> &Minkowski<N>

Get the Minkowski point of the hyperboloid.

pub fn from_minkowski_coordinates(point: Minkowski<N>) -> Hyperbolic<N>

Create a Hyperbolic point from a Minkowski vector.

Example

use hoomd_manifold::{Hyperbolic, Minkowski};
use hoomd_vector::Metric;

let x = Hyperbolic::from_minkowski_coordinates([0.0, 0.0, 1.0].into());

impl Hyperbolic<3>

pub fn from_polar_coordinates(v: f64, theta: f64) -> Hyperbolic<3>

Create a point on the surface of a three-dimensional hyperboloid from the polar representation.

impl Hyperbolic<4>

pub fn from_polar_coordinates(v: f64, theta: f64, phi: f64) -> Hyperbolic<4>

Create a point on the surface of a four-dimensional hyperboloid from the spherical representation.

impl<const N: usize> Hyperbolic<N>

pub fn distance_from_cusp(&self) -> f64

Compute the distance from a point to the cusp.

Computes the length of the geodesic passing between the cusp $(0,\cdots,0,\rho)$ and a given point on the hyperboloid.

Example

use approxim::assert_relative_eq;
use hoomd_manifold::{Hyperbolic, Minkowski};
use hoomd_vector::Vector;

let v: f64 = 4.2;
let x = Hyperbolic::from_minkowski_coordinates(
    [v.sinh(), 0.0, v.cosh()].into(),
);
assert_relative_eq!(v, x.distance_from_cusp(), epsilon = 1e-12);

pub fn to_poincare(&self) -> Vec<f64>

Projects points on the hyperboloid onto the Poincaré disk/ball.

Example

use approxim::assert_relative_eq;
use hoomd_manifold::{Hyperbolic, Minkowski};
use hoomd_vector::Vector;

let v: f64 = 1.098612;
let x = Hyperbolic::from_minkowski_coordinates(
    [v.sinh(), 0.0, v.cosh()].into(),
);
let projection = x.to_poincare();
assert_relative_eq!(
    v.sinh() / (v.cosh() + 1.0),
    projection[0],
    epsilon = 1e-12
);
assert_relative_eq!(0.0, projection[1], epsilon = 1e-12);

Trait Implementations

impl<const N: usize> AbsDiffEq for Hyperbolic<N>

type Epsilon = <Minkowski<N> 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<const N: usize> Clone for Hyperbolic<N>

fn clone(&self) -> Hyperbolic<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Hyperbolic<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for Hyperbolic<N>

fn default() -> Self

Construct a default point on a hyperboloid.

The default Hyperbolic<N> point is on the cusp of a hyperboloid with skirt width of 1.0 (i.e., the point $(0.0, \cdots, 0.0, 1.0)$).

impl<'de, const N: usize> Deserialize<'de> for Hyperbolic<N>

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Distribution<Hyperbolic<3>> for HyperbolicDisk

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

Sample a random point in the hyperbolic disk.

The implementation translates Minkowski 3-vector point along the Hyperbolic by maximum distance of disk_radius. Note that because SO(2,1) is non-Abelian, the point must be transformed to the cusp before a trial move is applied (and then the point is transformed back). This ensures that the max distance translated by the trial move does not exceed disk_radius.

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 Metric for Hyperbolic<3>

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

The distance between two Hyperbolic<3> points.

Explicitly, the metric for two points $\vec{u}$ and $\vec{v}$ on a hyperboloid

d_{H_2}(\vec{u}, \vec{v}) = \operatorname{arccosh}\left[u_3v_3 - u_1v_1 - u_2v_2\right]

This choice of metric furnishes a representation of 2-dimensional hyperbolic space with Gaussian curvature $K = -1$.

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

Compute the squared distance between two vectors belonging to a metric space.

fn n_dimensions(&self) -> usize

Return the number of dimensions in this vector space.

impl Metric for Hyperbolic<4>

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

The distance between two Hyperbolic<4> points.

Explicitly, the metric for two points $\vec{u}$ and $\vec{v}$ on a hyperboloid is given by

d_{H_3}(\vec{u}, \vec{v}) = \operatorname{arccosh}\left[u_4v_4 - u_1v_1 - u_2v_2 - u_3v_3\right]

This choice of metric furnishes a representation of 3-dimensional hyperbolic space with with Gaussian curvature $K = -1$.

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

Compute the squared distance between two vectors belonging to a metric space.

fn n_dimensions(&self) -> usize

Return the number of dimensions in this vector space.

impl<const N: usize> PartialEq for Hyperbolic<N>

fn eq(&self, other: &Hyperbolic<N>) -> 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<const N: usize> RelativeEq for Hyperbolic<N>

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<const N: usize> Serialize for Hyperbolic<N>

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<const N: usize> Copy for Hyperbolic<N>

impl<const N: usize> StructuralPartialEq for Hyperbolic<N>