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)[source]

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:

ddg.geometry.Quadric

static metric_to_cayley_klein_distance(d: float) → float[source]

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[source]

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

d = arccosh(sqrt(K))

Parameters:

Kfloat

Returns:

dfloat

Raises:

ValueError: If K < 1

moebius()[source]: Corresponding projective model of Moebius geometry (Hemisphere model).

to_moebius(object_, embedded=False)[source]: Alias for projective_to_hemisphere()

from_moebius(object_, embedded=False)[source]: Alias for hemisphere_to_projective()

poincare()[source]: Corresponding Poincare disk model of hyperbolic geometry.

to_poincare(object_, embedded=False)[source]: Alias for projective_to_poincare()

from_poincare(object_, embedded=False)[source]: Alias for poincare_to_projective()

half_space()[source]: Corresponding half space model of hyperbolic geometry.

to_half_space(object_, embedded=False)[source]: Alias for projective_to_half_space()

from_half_space(object_, embedded=False)[source]: Alias for half_space_to_projective()

geodesic(p1, p2)[source]

Return geodesic connecting two points.

Parameters:

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

Returns:

ddg.geometry.Subspace

perpendicular_subspace(subspace, contained_subspace)[source]

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_subspaceddg.geometry.Subspace

Returns:

Sddg.geometry.Subspace

common_perpendicular(subspace1, subspace2) → Subspace[source]

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, subspace2ddg.geometry.Subspace

Returns:

Sddg.geometry.Subspace

d_point_hyperplane(point, subspace) → float[source]

Perpendicular distance of a point to a hyperplane.

Parameters:

pointddg.geometry.Point
subspaceddg.geometry.Subspace

Returns:

float

d_hyperplanes(subspace1, subspace2) → float[source]

Perpendicular distance between two parallel hyperplanes.

Parameters:

subspace1, subspace2ddg.geometry.Subspace

Returns:

float

angle(subspace1, subspace2) → float[source]

Angle between two hyperplanes.

Parameters:

subspace1, subspace2ddg.geometry.Subspace

Returns:

float

sphere_through_points(*points)[source]

Find the unique k-sphere through given points.

The sphere can be a MetricCayleyKleinSphere (actual sphere in the hyperbolic metric), a CayleyKleinSphere (distance curve), a GeneralizedCayleyKleinSphere (horosphere) or it degenerate to a subspace.

Points on the absolute may also be given, in which case the result will be a distance curve or a horosphere.

Generically, n points define an (n-2)-sphere.

Parameters:

*pointsiterable of type ddg.geometry.Point: The points for which to find the sphere.

Returns:

ddg.geometry.spheres.MetricCayleyKleinSphere,
ddg.geometry.spheres.CayleyKleinSphereLike,
ddg.geometry.spheres.GeneralizedCayleyKleinSphere or
ddg.geometry.Subspace

Raises:

ValueError

If the points are not contained in a sphere.
If a given point is not an element of the according geometry.

See also

ddg.geometry.euclidean_models.ProjectiveModel.orthogonal_sphere
ddg.geometry.elliptic_models.ProjectiveModel.orthogonal_sphere

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:

centerddg.geometry.Point or numpy.ndarray of shape (n+1,)
radiusfloat: Cayley-Klein radius
subspaceddg.geometry.Subspace or list of numpy.ndarray of shape (k,)
(default=None)

Returns:

ddg.geometry.spheres.CayleyKleinSphere

d(v, w) → float

Cayley-Klein metric

Parameters:

v, wnumpy.ndarray or ddg.geometry.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:

centerddg.geometry.Point or numpy.ndarray of shape (n+1,)
radiusfloat: Generalized radius
subspaceddg.geometry.Subspace or list of numpy.ndarray of shape (k,)
(default=None)

Returns:

ddg.geometry.spheres.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:

centerddg.geometry.Point or numpy.ndarray of shape (n+1,)
radiusfloat: Radius in terms of the Cayley-Klein Metric self.d.
subspaceddg.geometry.Subspace or array_like of shape (m,n) (default=None)

Returns:

ddg.geometry.spheres.MetricCayleyKleinSphere

class ddg.geometry.hyperbolic_models.PoincareDiskModel(dimension)[source]

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)[source]

Metric in the Poincaré disk model.

Parameters:

v, wddg.geometry.Point or array_like of shape (n,)

Returns:

float

class ddg.geometry.hyperbolic_models.HalfSpaceModel(dimension)[source]

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)[source]

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, wddg.geometry.Point 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:

ddg.geometry.Subspace

class ddg.geometry.hyperbolic_models.HemisphereModel(dimension)[source]

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:

ddg.geometry.Point

d(v, w)[source]

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, wddg.geometry.Point or array_like of shape (n,)

Returns:

float

property absolute

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

Returns:

ddg.geometry.Quadric

property ambient_dimension

angle(s1, s2)

Angle between two Möbius spheres.

Parameters:

s1, s2ddg.geometry.Quadric: Möbius spheres.

Returns:

float

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:

centerddg.geometry.Point or numpy.ndarray of shape (n+1,)
radiusfloat: Cayley-Klein radius
subspaceddg.geometry.Subspace or list of numpy.ndarray of shape (k,)
(default=None)

Returns:

ddg.geometry.spheres.CayleyKleinSphere

elliptic(): Corresponding projective model of elliptic geometry.

property elliptic_point

property elliptic_subspace

euclidean(): Corresponding projective model of Euclidean geometry.

property euclidean_point

property euclidean_subspace

from_elliptic(object_, embedded=False): Alias for elliptic_models.projective_to_moebius()

from_euclidean(object_, embedded=False): Alias for euclidean_models.projective_to_moebius()

from_hyperbolic(object_, embedded=False): Alias for hyperbolic_models.projective_to_hemisphere()

from_hyperbolic_half_space(object_, embedded=False): Alias for hyperbolic_models.half_space_to_hemisphere()

from_hyperbolic_poincare(object_, embedded=False): Alias for hyperbolic_models.poincare_to_projective()

from_lie(object_, embedded=False)

from_paraboloid(object_): Alias for paraboloid_to_projective_and_back()

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

Create a generalized Cayley-Klein sphere.

Parameters:

centerddg.geometry.Point or numpy.ndarray of shape (n+1,)
radiusfloat: Generalized radius
subspaceddg.geometry.Subspace or list of numpy.ndarray of shape (k,)
(default=None)

Returns:

ddg.geometry.spheres.GeneralizedCayleyKleinSphere

hyperbolic(): Corresponding projective model of hyperbolic geometry.

hyperbolic_half_space(): Corresponding Poincare disk model of hyperbolic geometry.

hyperbolic_poincare(): Corresponding Poincare disk model of hyperbolic geometry.

property hyperbolic_point

property hyperbolic_subspace

inner_product(v, w): Alias for self.absolute.inner_product.

lie(): Corresponding projective model of Lie geometry.

paraboloid(): Corresponding paraboloid model of Möbius geometry.

pole_of_sphere(sphere)

Return pole corresponding to sphere.

Parameters:

sphereddg.geometry.Quadric

Returns:

ddg.geometry.Subspace

sphere_from_pole(subspace) → Quadric

Get a Möbius sphere from its pole.

Returns intersection of Q and Q.polarize(subspace), where Q is the Möbius quadric.

Parameters:

subspaceddg.geometry.Subspace

Returns:

ddg.geometry.Quadric

to_elliptic(object_, embedded=False): Alias for elliptic_models.moebius_to_projective()

to_euclidean(object_, embedded=False): Alias for euclidean_models.moebius_to_projective()

to_hyperbolic(object_, embedded=False): Alias for hyperbolic_models.hemisphere_to_projective()

to_hyperbolic_half_space(object_, embedded=False): Alias for hyperbolic_models.hemisphere_to_half_space()

to_hyperbolic_poincare(object_, embedded=False): Alias for hyperbolic_models.projective_to_poincare()

to_lie(object_, embedded=False)

to_paraboloid(object_): Alias for paraboloid_to_projective_and_back()

ddg.geometry.hyperbolic_models.projective_to_poincare(object_, embedded=False)[source]

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)[source]

Convert from Poincaré disk model to projective model.

Just the composition

Poincaré -> Möbius -> Projective

ddg.geometry.hyperbolic_models.projective_to_hemisphere(object_)[source]

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)[source]

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.

If a quadric is given which is contained in the Möbius quadric, the result will be converted to a corresponding Caley-Klein sphere.

Parameters:

object_ddg.geometry.Quadric or ddg.geometry.Point
embeddedbool (default=False): Whether to return the object in the equatorial plane or in n-dim. ambient space.

Returns:

ddg.geometry.Quadric,
ddg.geometry.Point,
ddg.geometry.Subspace,
ddg.geometry.spheres.MetricCayleyKleinSphere,
ddg.geometry.spheres.CayleyKleinSphere or
ddg.geometry.spheres.GeneralizedCayleyKleinSphere

ddg.geometry.hyperbolic_models.hemisphere_to_poincare(object_, embedded=False)[source]

Hemisphere to Poincaré disk model conversion.

Alias for moebius_models.projective_to_euclidean()

ddg.geometry.hyperbolic_models.poincare_to_hemisphere(object_, embedded=False)[source]

Poincaré disk to hemisphere model conversion.

Alias for moebius_models.euclidean_to_projective()

ddg.geometry.hyperbolic_models.hemisphere_to_half_space(object_, embedded=False)[source]

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_ddg.geometry.Point or ddg.geometry.Quadric
embeddedbool (default=False): Whether to return the object in the equatorial plane or in n-dim. ambient space.

Returns:

ddg.geometry.Point or ddg.geometry.spheres.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)[source]

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_ddg.geometry.Subspace or ddg.geometry.spheres.SphereLike
embeddedbool (default=False): If False, embeds into the the plane {x1 = 0} before projecting.

Returns:

ddg.geometry.Subspace or ddg.geometry.Quadric

Warning

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