ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_distUnifSphere Module Reference

This module contains classes and procedures for computing various statistical quantities related to the Uniform Spherical distribution. More...

Data Types

type  distUnifSphere_type
 This is the derived type for signifying distributions that are of type MultiVariate Uniform Spherical as defined in the description of pm_distUnifSphere. More...
 
interface  getUnifSphereLogPDF
 Generate and return the natural logarithm of the Probability Density Function (PDF) of the uniform distribution on an \(n\)-sphere embedded in an \(\ndim\)-dimensional space.
More...
 
interface  getUnifSphereRand
 Generate and return a (collection) of random vector(s) of size ndim uniformly distributed on the surface of an \(n\)-sphere, optionally with the specified input mean(1:ndim) and optionally affine-transformed to a non-uniform distribution on the surface of an \((n+1)\)-ellipsoid represented by the Cholesky Factorization of its Gramian matrix. More...
 
interface  setUnifSphereRand
 Return a (collection) of random vector(s) of size ndim uniformly distributed on the surface of an \(n\)-sphere, optionally with the specified input mean(1:ndim) and optionally affine-transformed to a non-uniform distribution on the surface of an \((n+1)\)-ellipsoid represented by the Cholesky Factorization of its Gramian matrix. More...
 

Variables

character(*, SK), parameter MODULE_NAME = "@pm_distUnifSphere"
 

Detailed Description

This module contains classes and procedures for computing various statistical quantities related to the Uniform Spherical distribution.

Specifically, this module contains routines for computing the following quantities of the uniform distribution of points on the surface of a an arbitrary n-dimensional sphere:

  1. the Probability Density Function (PDF)
  2. the Random Number Generation from the distribution (RNG)

n-sphere

An \(n\)-sphere or a hypersphere is a topological space that is homeomorphic to a standard \(n\)-sphere, which is the set of points in \((n + 1)\)-dimensional Euclidean space that are situated at a constant distance \(r\) from a fixed point, called the center.
It is the generalization of an ordinary sphere in the ordinary three-dimensional space.
The radius of a sphere is the constant distance of its points to the center.
When the sphere has unit radius, it is usual to call it the unit \(n\)-sphere or simply the \(n\)-sphere for brevity.
In terms of the standard norm, the \(n\)-sphere is defined as,

\begin{equation} S^{n} = \left\{x\in\mathbb{R}^{n+1}:\left\|x\right\|=1\right\} ~, \end{equation}

and an n-sphere of radius \(r\) can be defined as

\begin{equation} S^{n}(r)=\left\{x\in \mathbb {R} ^{n+1}:\left\|x\right\|=r\right\} ~. \end{equation}

The dimension of \(n\)-sphere is \(n\), and must not be confused with the dimension \((n + 1)\) of the Euclidean space in which it is naturally embedded.
An \(n\)-sphere is the surface or boundary of an \((n + 1)\)-dimensional ball.
In particular:

  1. The pair of points at the ends of a (one-dimensional) line segment is a 0-sphere.
  2. A circle, which is the one-dimensional circumference of a (two-dimensional) ball, is a 1-sphere.
  3. The two-dimensional surface of a three-dimensional ball is a 2-sphere, commonly called a sphere.
  4. The three-dimensional boundary of a (four-dimensional) 4-ball is a 3-sphere.
  5. The \((n – 1)\)-dimensional boundary of a ( \(n\)-dimensional) \(\ndim\)-ball is an \((n – 1)\)-sphere.

Probability Density Function (PDF)

The PDF of an \(n\)-sphere can be readily computed as the inverse of the surface area of the sphere, which has the closed form,

\begin{equation} S_{n-1} = {\frac {n\pi^{\frac{n}{2}}}{\Gamma\left({\frac{n}{2}} + 1\right)}} r^{n-1} = {\frac{2\pi^{\frac{n}{2}}}{\Gamma\left({\frac{n}{2}}\right)}} r^{n-1} = n\frac{V_{n}}{r}~. \end{equation}

for the \((n−1)\)-dimensional surface of the sphere \(S_{n−1}\) of radius \(r\), where \(V_{n + 1}\) is the volume of the corresponding \(n\)-ball.
Unlike the volume and the surface area of an \(n\)-sphere, the computation of the surface area of an arbitrary hyper-ellipsoid is very much involved.
See, for example, the discussion here for more information.

Random Number Generation

The RNG generic interfaces within this module generate uniformly-distributed random vectors on the surface an \(n\)-sphere using a generalization of the proposed approach of Marsaglia (1972) for choosing a point from the surface of a sphere.

  1. Define \(\ndim = n + 1\) as the dimension of the space within which the \(n\)-sphere is embedded.
  2. Generate a normalized (unit) \(\ndim\)-dimensional Multivariate Normal random vector,

    \begin{equation} \unit{r} = \frac{1}{\sqrt{\sum_{i=1}^\ndim g_i^2}} \sum_{j=1}^{\ndim} g_j \unit{r}_j ~, \end{equation}

    where \(\unit{r}_j\) are the unit vectors representing the orthogonal basis the of \(\ndim\)-space.
    This unit vector \(\unit{r}\) has uniform random orientation and distribution on the surface of an \(n\)-sphere of unit radius centered at the origin of the coordinate system.
  3. Optionally, this random uniform surface point can be further transformed to the surface of an \(\ndim\)-ellipsoid via an affine transformation.
    However, the transformation of an \(\ndim\)-ball to an \(\ndim\)-ellipsoid does not preserve the uniformity of the random points on the ellipsoid surface.
    In other words, the resulting random points on the surface of the \(\ndim\)-ellipsoid are not uniformly distributed.
    Instead, the random points will be clustered toward the sharp corners of the \(\ndim\)-ellipsoid, i.e., along the directions with the largest eigenvalues.
    To transform the uniform \(n\)-sphere to the a non-uniform distribution on the surface of an \(\ndim\)-ellipsoid:
    1. First compute the Cholesky decomposition of the representative Gramian matrix \(\gramian\) of the ellipsoid,

      \begin{equation} \gramian = \mat{L}\mat{L}^H ~, \end{equation}

      where \(\mat{L}\) is the left triangular matrix resulting from the Cholesky factorization, and \(\mat{L}^T\) is its Hermitian transpose.
    2. Then the vector,

      \begin{equation} \bs{r}_\ell = \mat{L} ~ \bs{r}_\sphere + \mu_\ell ~, \end{equation}

      is non-uniformly distributed on the surface of ellipsoid \(\ell\) centered at the original \(n\)-sphere.
      The actual distribution of the resulting points on the ellipsoidal surface is a complicated function of the curvature of ellipsoidal surface at different points.
      Unlike the case of uniformly-distributed points within a hyper-ellipsoid, there is straightforward solution for generating uniform points on the surface an arbitrary dimensional hyper-ellipsoid.
      The exact equations and numerical integrations for computing the surface curvature of a hyper-ellipsoid are, for example, discussed here.
See also
pm_distUnif
pm_distNorm
pm_distMultiNorm
pm_distUnifSphere
pm_distUnifEll
pm_distUnifPar
Marsaglia G., et al. (1972), Choosing a point from the surface of a sphere. The Annals of Mathematical Statistics 43(2):645-646.
Test:
test_pm_distUnifSphere


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, April 23, 2017, 1:36 AM, Institute for Computational Engineering and Sciences (ICES), University of Texas at Austin

Variable Documentation

◆ MODULE_NAME

character(*, SK), parameter pm_distUnifSphere::MODULE_NAME = "@pm_distUnifSphere"

Definition at line 134 of file pm_distUnifSphere.F90.