ddg.geometry.hyperbolic_models module

Hyperbolic geometry module.

Contains model classes and functions for conversion between the models.

class ddg.geometry.hyperbolic_models.ProjectiveModel(dimension)

Bases: MetricCayleyKleinGeometry

Projective model of hyperbolic geometry, aka Klein model.

Model space

The model space can be thought of as the inside of the unit ball. More precisely, it is the set

{ [x] : b(x, x) < 0 }

where b is the standard Lorentz scalar product represented by the matrix diag([1,...,1, -1]).

Representation of objects

• Hyperbolic subspaces are represented by subspace objects

• Spheres, distance curves and horospheres are sphere objects.

Note that a hyperbolic subspace is a subspace intersected with the model space, but we use the whole subspace to represent it.

Parameters:

dimensionint

Notes

This class supports comparison with ==. Two geometries are equal if and only if they have the same type and dimension.

This class also supports the in operator to check whether a point is in the model space.

Attributes:

dimensionint

property absolute: Quadric

The absolute quadric with matrix diag([1,...,1, -1]).

Returns:

Quadric

static metric_to_cayley_klein_distance(d: float) → float

Return Metric distance converted to Cayley-Klein “distance”:

K = cosh(d) ** 2

Parameters:

dfloat

Returns:

Kfloat

static cayley_klein_distance_to_metric(K: float) → float

Return Metric distance converted to Cayley-Klein “distance”:

d = arccosh(sqrt(K))

Parameters:

Kfloat

Returns:

dfloat

Raises:

ValueError

If K < 1

geodesic(p1, p2)

Return geodesic connecting two points.

Parameters:

p1, p2Point or array_like of shape (self.dimension + 1,)

Returns:

Subspace

perpendicular_subspace(subspace, contained_subspace)

Get a subspace that is perpendicular to another subspace.

More precisely: The function returns the largest subspace S such that the orthogonal projection of S onto subspace is equal to the orthogonal projection of contained_subspace onto subspace.

Common special case: If subspace is a hyperplane and contained_subspace is a point, this is the line that is orthogonal to the hyperplane and contains a specified point.

This is computed as the join of contained_subspace and the polar subspace of subspace.

Parameters:

subspace, contained_subspaceSubspace

Returns:

SSubspace

common_perpendicular(subspace1, subspace2) → Subspace

Subspace that is orthogonal to two given non-intersecting subspaces.

Common special case: The line that is perpendicular to two parallel hyperplanes.

This is computed as the join of the polarized subspaces. If the two subspaces intersect, this join will lie outside of the unit sphere.

Parameters:

subspace1, subspace2Subspace

Returns:

SSubspace

d_point_hyperplane(point, subspace) → float

Perpendicular distance of a point to a hyperplane.

Parameters:

pointPoint

subspaceSubspace

Returns:

float

d_hyperplanes(subspace1, subspace2) → float

Perpendicular distance between two parallel hyperplanes.

Parameters:

subspace1, subspace2Subspace

Returns:

float

angle(subspace1, subspace2) → float

Angle between two hyperplanes.

Parameters:

subspace1, subspace2Subspace

Returns:

float

property ambient_dimension

cayley_klein_distance(v, w)

Alias for self.absolute.cayley_klein_distance.

cayley_klein_sphere(center, radius, subspace=None, atol=None, rtol=None)

Create a Cayley-Klein sphere.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,)

radiusfloat

Cayley-Klein radius

subspaceSubspace or list of numpy.ndarray of shape (k,) (default=None)

Returns:

CayleyKleinSphere

d(v, w) → float

Cayley-Klein metric

Parameters:

v, wnumpy.ndarray or Point

Homogeneous coordinate vectors or Point instances. Both points must be either inside or outside the absolute quadric.

Returns:

float

generalized_cayley_klein_sphere(center, radius, subspace=None, atol=None, rtol=None)

Create a generalized Cayley-Klein sphere.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,)

radiusfloat

Generalized radius

subspaceSubspace or list of numpy.ndarray of shape (k,) (default=None)

Returns:

GeneralizedCayleyKleinSphere

inner_product(v, w)

Alias for self.absolute.inner_product.

sphere(center, radius, subspace=None, atol=None, rtol=None)

Create a sphere with metric radius.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,)

radiusfloat

Radius in terms of the Cayley-Klein Metric self.d.

subspaceSubspace or array_like of shape (m,n) (default=None)

Returns:

MetricCayleyKleinSphere

class ddg.geometry.hyperbolic_models.PoincareDiskModel(dimension)

Bases: MetricGeometry

Poincaré disk model.

Model space

The model space is the open unit ball in R^n.

Representation of objects

Geometric objects are represented by their Euclidean equivalents, mainly spheres. Note:

• If an object is the intersection of the unit ball with a larger object, we use the whole object to represent it. For example, geodesics are circular arcs, but we represent them by the whole circle.

• Because we use Euclidean spheres to represent hyperbolic spheres which are the same viewed as sets, the center of a sphere will not actually match the center with respect to the hyperbolic metric. The hyperbolic center can be obtained by representing the sphere in a different model and converting the center to this model.

Parameters:

dimensionint

Notes

This class supports comparison with ==. Two geometries are equal if and only if they have the same type, and dimension.

This class also supports the in operator to check whether a point is in the model space.

Attributes:

dimensionint

d(v, w)

Metric in the Poincaré disk model.

Parameters:

v, wPoint or array_like of shape (n,)

Returns:

float

class ddg.geometry.hyperbolic_models.HalfSpaceModel(dimension)

Bases: MetricGeometry

Poincaré Half-space model.

Model space

The model space is the half-space {xn > 0} in R^n, where n is the dimension.

Representation of objects

Objects are represented by their Euclidean counterparts:

• Subspaces, including other objects like horospheres that look like subspaces, are represented by subspaces.

• Objects that look like spheres are represented by Euclidean spheres. This means that the center of the spheres will not match the actual hyperbolic center.

Note that we represent intersections of the upper half-space with an object obj by the whole obj. For example, geodesics are semicircles, but we represent them by the whole circle.

Parameters:

dimensionint

Notes

This class supports comparison with ==. Two geometries are equal if and only if they have the same type, and dimension.

This class also supports the in operator to check whether a point is in the model space.

Attributes:

dimensionint

d(v, w)

Metric in Poincaré half-space model.

Defined by:

arccosh(1 + |v-w|^2 / (2 * v[n] * w[n])),

where n is the dimension.

Parameters:

v, wPoint or array_like of shape(n,)

Returns:

float

Raises:

ValueError

If the points are in different half-spaces.

Notes

Source: Wikipedia

property absolute

The model embedded in (n+1)-space.

Returns the hyperplane {x0 = 0}. The model is the upper half of this hyperplane.

This plane is projected to the Möbius quadric to convert between the models.

Returns:

Subspace

class ddg.geometry.hyperbolic_models.HemisphereModel(dimension)

Bases: _ProjectiveSubgeometry

Hemisphere model of hyperbolic space.

Also known as the Möbius model because this is a subgeometry of Möbius geometry. It is also a transformed version of the hyperboloid model.

Model space

The model space is the upper open hemisphere of the unit sphere. More precisely:

{ [x] in Quadric(diag([1,...,1, -1])) : dehomogenize([x])[-1] > 0 }.

Representation of objects

All geometric objects (except for points) are represented by Möbius spheres, i.e. Quadric objects contained in the Möbius quadric. Note that of course the actual objects are quadrics intersected with the upper hemisphere, but we use the whole quadric to represent them.

Parameters:

dimensionint

Notes

This class supports comparison with ==. Two geometries are equal if and only if they have the same type, and dimension.

This class also supports the in operator to check whether a point is in the model space.

Attributes:

dimensionint

property fixed_point

Point outside the Möbius quadric used for computation of the metric.

This is the point with representative [0,…,0, 1, 0].

Returns:

Point

d(v, w)

Hyperbolic metric in Möbius model

Given by the formula

<x, y> / (<x, p> <y, p>) = -2 * sinh^2(d([x],[y]) / 2)

Where p is self.fixed_point.point.

Parameters:

v, wPoint or array_like of shape (n,)

Returns:

float

property ambient_dimension

cayley_klein_distance(v, w)

Alias for self.absolute.cayley_klein_distance.

cayley_klein_sphere(center, radius, subspace=None, atol=None, rtol=None)

Create a Cayley-Klein sphere.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,)

radiusfloat

Cayley-Klein radius

subspaceSubspace or list of numpy.ndarray of shape (k,) (default=None)

Returns:

CayleyKleinSphere

generalized_cayley_klein_sphere(center, radius, subspace=None, atol=None, rtol=None)

Create a generalized Cayley-Klein sphere.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,)

radiusfloat

Generalized radius

subspaceSubspace or list of numpy.ndarray of shape (k,) (default=None)

Returns:

GeneralizedCayleyKleinSphere

inner_product(v, w)

Alias for self.absolute.inner_product.

absolute: Quadric

The absolute quadric.

ddg.geometry.hyperbolic_models.projective_to_poincare(object_, embedded=False)

Convert from projective model to Poincaré disk model.

Just the composition

Projective -> Möbius -> Poincaré

ddg.geometry.hyperbolic_models.poincare_to_projective(object_, embedded=False)

Convert from Poincaré disk model to projective model.

Just the composition

Poincaré -> Möbius -> Projective

ddg.geometry.hyperbolic_models.projective_to_hemisphere(object_)

ddg.geometry.hyperbolic_models.projective_to_hemisphere(subspace: Subspace, embedded=False)

ddg.geometry.hyperbolic_models.projective_to_hemisphere(point: Point, embedded=False)

ddg.geometry.hyperbolic_models.projective_to_hemisphere(sphere: SphereLike, embedded=False)

Projective to hemisphere model conversion.hyperconv

This is a dispatcher, see type-specific functions for details.

ddg.geometry.hyperbolic_models.hemisphere_to_projective(object_, embedded=False)

Convert from Möbius/hemisphere model to projective model.

Works by centrally projecting from the Möbius quadric to the equatorial plane (the polar plane of [e_n+1]) via [e_n+1] and computing coordinates.

Parameters:

object_Quadric or Point

embeddedbool (default=False)

Whether to return the object in the equatorial plane or in n-dim. ambient space.

Returns:

Quadric, Point or Subspace

ddg.geometry.hyperbolic_models.hemisphere_to_poincare(object_, embedded=False)

Hemisphere to Poincaré disk model conversion.

Alias for moebius_models.projective_to_euclidean()

ddg.geometry.hyperbolic_models.poincare_to_hemisphere(object_, embedded=False)

Poincaré disk to hemisphere model conversion.

Alias for moebius_models.euclidean_to_projective()

ddg.geometry.hyperbolic_models.hemisphere_to_half_space(object_, embedded=False)

Convert from Möbius/hemisphere model to Poincaré Half-plane model.

This function stereographically projects from the point [1, 0,…,0, 1] on the Möbius quadric to the hyperplane {x1 = 0}, then computes coordinates.

Parameters:

object_Point or Quadric

embeddedbool (default=False)

Whether to return the object in the equatorial plane or in n-dim. ambient space.

Returns:

Point or SphereLike

Warning

No choice is made whether the upper or lower half-space is used. Make sure your object resides in the correct hemisphere.

ddg.geometry.hyperbolic_models.half_space_to_hemisphere(object_, embedded=False)

Convert from Poincaré-Half plane model to Möbius/hemisphere model.

This function optionally embeds into the plane {x1 = 0}, then stereographically projects from that plane to the Möbius quadric via the point [1, 0,…,0, 1].

Parameters:

object_Subspace or SphereLike

embeddedbool (default=False)

If False, embeds into the the plane {x1 = 0} before projecting.

Returns:

Subspace or Quadric

Warning

No choice is made whether the upper or lower hemisphere is used. Make sure your object resides in the correct half-space.