Struct Spherical 

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

Point on the surface of a sphere.

Spherical<N> is a point on a unit $(N-1)$-sphere embedded in $N$-dimensional Euclidean space. Explicitly, the $N$-sphere is defined by the set of $(N+1)$-dimensional points whose components satisfy

x_1^2 + x_2^2 + \cdots + x_{N+1}^2 = 1.0

Note that the radius is fixed to be 1.0. The curvature of Spherical simulations can be tuned by changing the length scale of bodies and interactions. For example, rescaling all distances by $r\rightarrow r/\ell$ has the same effect as running simulations with radius $R=1/\ell$ or Gauss curvature $K = \ell^2$.

Implementations

impl<const N: usize> Spherical<N>

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

Get the coordinates of the point

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

Get the point of the sphere

pub fn from_cartesian_coordinates(point: Cartesian<N>) -> Spherical<N>

Construct a Sphere given a Cartesian vector and a radius.

Panics

Panics when the point is not sufficiently close to the sphere’s surface.

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

Implements a stereographic projection from the $N$-sphere to an $n$-dimensional subspace by projecting through the $(0,\cdots, 0,1)$ axis.

Example

use hoomd_manifold::Spherical;
use hoomd_vector::Cartesian;

let x = Cartesian::from([0.5_f64.sqrt(), 0.0, -(0.5_f64.sqrt())]);
let projection =
    Spherical::from_cartesian_coordinates(x).stereographic_projection();
assert_eq!(
    [1.0 / (2.0_f64.sqrt() + 1.0), 0.0],
    [projection[0], projection[1]]
);

impl Spherical<3>

pub fn from_polar_coordinates(theta: f64, phi: f64) -> Spherical<3>

Create a 2-sphere from spherical coordinates

impl Spherical<4>

pub fn from_polar_coordinates( theta: f64, phi_1: f64, phi_2: f64, ) -> Spherical<4>

Create a point on a 3-sphere from spherical coordinates. Note that this uses the convention

\begin{pmatrix}
\sin\theta \cos\phi_1
\\ \sin\theta \sin\phi_1 \cos\phi_2
\\ \sin\theta \sin\phi_1 \sin\phi_2
\\ \cos\theta
\end{pmatrix}

where $\theta$ and $\phi_1$ both run over the range $0$ to $\pi$ and $\phi_2$ runs from $0$ to $2\pi$.

pub fn from_versor(versor: Versor) -> Spherical<4>

Create a point on a unit-radius 3-sphere from a unit quaternion.

pub fn to_versor(&self) -> Versor

Create a versor which maps $(1,0,0,0)$ to the target Spherical<4> point.

Example

use approxim::assert_relative_eq;
use hoomd_manifold::Spherical;
use hoomd_vector::{Cartesian, Quaternion, Versor};
use std::f64::consts::PI;

let radius = 1.0;
let x = Spherical::<4>::from_polar_coordinates(
    PI / 4.0,
    PI / 8.0,
    5.0 * PI / 4.0,
);
let x_versor = x.to_versor();
let pole_versor = Quaternion::from([1.0, 0.0, 0.0, 0.0])
    .to_versor()
    .expect("not a null vector");
let transformation =
    (*x_versor.get() * *pole_versor.get() * *x_versor.get())
        .to_versor()
        .expect("Hard-coded example is valid");
let mapped_pole = Spherical::<4>::from_versor(transformation);

assert_relative_eq!(
    mapped_pole.coordinates()[0],
    x.coordinates()[0],
    epsilon = 1e-12
);
assert_relative_eq!(
    mapped_pole.coordinates()[1],
    x.coordinates()[1],
    epsilon = 1e-12
);
assert_relative_eq!(
    mapped_pole.coordinates()[2],
    x.coordinates()[2],
    epsilon = 1e-12
);
assert_relative_eq!(
    mapped_pole.coordinates()[3],
    x.coordinates()[3],
    epsilon = 1e-12
);

Trait Implementations

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

type Epsilon = <Cartesian<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 Spherical<N>

fn clone(&self) -> Spherical<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 Spherical<N>

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

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

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Distribution<Spherical<3>> for SphericalDisk<3>

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

Translates 3-dimensional cartesian vector named “point” along the surface of a sphere by maximum distance of r.

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 Distribution<Spherical<4>> for SphericalDisk<4>

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

Translates 3-dimensional cartesian vector named “point” along the surface of a sphere by maximum distance of r.

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 Spherical<3>

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

The distance between two Spherical<3> points.

Explicitly, the metric for two points $\vec{u}$ and $\vec{v}$ on a 2-sphere with unit radius is given by

d_{S_2}(\vec{u}, \vec{v}) = \arccos\left[u_1v_1 + u_2v_2 + u_3v_3\right]

This choice of metric furnishes a representation of 2-dimensional spherical 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 Spherical<4>

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

The distance between two Spherical<4> points.

Explicitly, the metric for two points $\vec{u}$ and $\vec{v}$ on a 3-sphere with unit radius is given by

d_{S_3}(\vec{u}, \vec{v}) = \arccos\left[u_1v_1 + u_2v_2 + u_3v_3 + u_4v_4\right]

This choice of metric furnishes a representation of 3-dimensional spherical 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<const N: usize> PartialEq for Spherical<N>

fn eq(&self, other: &Spherical<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 Spherical<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 Spherical<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 Spherical<N>

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