ddg.geometry.spheres module

Module for more abstract sphere interfaces and classes.

For users: Spheres should be created using factory methods of geometries. For example:

>>> import ddg
>>> euc = ddg.geometry.euclidean(3)
>>> sph = euc.sphere([0, 1, 0, 1], 1.3)

class ddg.geometry.spheres.SphereLike[source]

Bases: Embeddable

Most general sphere interface.

Notes

Implements the in, == and <= relations, defined as set membership “∈”, set equality and set containment “⊆” respectively.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

geometry: Any: Geometry the sphere and in paricular the radius is interpreted in.

dimension: int

Dimension of the sphere.

If the sphere is not a manifold, this is the maximal dimension of a manifold contained in the sphere.

abstract is_hypersphere()[source]

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

abstract is_circle()[source]

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

abstract at_infinity()

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

abstract embed(subspace=None)

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

abstract unembed(subspace=None)

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

ambient_dimension: int

class ddg.geometry.spheres.CayleyKleinSphereLike[source]

Bases: SphereLike, QuadricConvertible

ABC for Cayley-Klein spheres, generalized Cayley-Klein spheres and Metric Cayley-Klein spheres.

absolute: Quadric: Absolute quadric. Always contained in subspace.

abstract metric_radius()[source]

Radius in terms of Cayley-Klein metric.

This method will fail if the given radius does not correspond to a metric radius.

Returns:

float

abstract cayley_klein_radius()[source]

Cayley-Klein radius.

This method will fail for horospheres.

Returns:

float

See also

CayleyKleinSphere

abstract generalized_radius()[source]

Generalized radius.

Returns:

float

See also

GeneralizedCayleyKleinSphere

abstract at_infinity()

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

abstract embed(subspace=None)

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

abstract is_circle()

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

abstract is_hypersphere()

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

abstract quadric()

Return object as quadric.

Returns:

Quadric

abstract unembed(subspace=None)

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

geometry: Any: Geometry the sphere and in paricular the radius is interpreted in.

dimension: int

Dimension of the sphere.

If the sphere is not a manifold, this is the maximal dimension of a manifold contained in the sphere.

ambient_dimension: int

class ddg.geometry.spheres.QuadricSphere(center, radius, geometry_bridge, subspace=None, atol=None, rtol=None)[source]

Bases: SphereLike, QuadricConvertible

Implementation of SphereLike for spheres that are also quadrics.

For users: Please refer to SphereLike. Do not try to instantiate this directly.

Parameters:

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

radiusfloat

geometry_bridge_QuadricSphereGeometryBridge

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

If given as an array, the subspace will be the span of the rows/elements.

If None is given, uses whole space with standard basis.

atol, rtolfloat (default=None)

Raises:

ValueError

If ambient dimension of subspace and center don’t match.
If center is not contained in subspace.

See also

SphereLike

Notes

Everything is implemented by converting to a quadric, then using the corresponding quadric functionality.

Geometry-specific functionality that can not be generalized is delegated to a stored QuadricSphereGeometryBridge object.

Attributes:

centerPoint
radiusfloat
subspaceSubspace

Methods

quadric()

Return object as quadric.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

property ambient_dimension

property dimension

property geometry

quadric()[source]

Return object as quadric.

Returns:

Quadric

is_hypersphere()[source]

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

is_circle()[source]

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

at_infinity()[source]

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

embed(subspace=None)[source]

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

unembed(subspace=None)[source]

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

class ddg.geometry.spheres.CayleyKleinSphere(center, radius, absolute, geometry=None, subspace=None, atol=None, rtol=None)[source]

Bases: _CayleyKleinSphereIntermediate

Cayley-Klein sphere.

The radius is not given in terms of a metric, but in terms of the Cayley-Klein “distance” induced by the absolute.

More precisely: This “sphere” is the set of all points x where

b(x, c) ** 2 - r * b(c, c) * b(x, x) = 0

where c is center.point, r is the radius and b is absolute.inner_product.` This formulation allows for points on the absolute to be included.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,): center given as Point or in homogeneous coordinates.
radiusfloat
absoluteQuadric
geometryMetricCayleyKleinGeometry (default=None): This geometry, if provided, will be used to convert between Cayley-Klein radius and metric radius.
subspaceSubspace or list of numpy.ndarray of shape (n+1,) (default=None): If given as list, the elements of the list will be interpreted as points in homogeneous coordinates spanning the subspace.
atol, rtolfloat (default=None)

See also

SphereLike, CayleyKleinSphereLike

Attributes:

centerPoint
radiusfloat: Cayley-Klein radius.
subspaceSubspace

Methods

`quadric`()	Return object as quadric.
`metric_radius`()	Radius in terms of Cayley-Klein metric.
`cayley_klein_radius`()	Cayley-Klein radius.
`generalized_radius`()	Generalized radius.

metric_radius()[source]

Radius in terms of Cayley-Klein metric.

This method will fail if the given radius does not correspond to a metric radius.

Returns:

float

Raises:

AttributeError: If no geometry to convert between metric and Cayley-Klein distance was provided.

cayley_klein_radius()[source]

Cayley-Klein radius.

This method will fail for horospheres.

Returns:

float

See also

CayleyKleinSphere

generalized_radius()[source]

Generalized radius.

Returns:

float

See also

GeneralizedCayleyKleinSphere

property absolute

The absolute quadric.

Returns:

Quadric

property ambient_dimension

at_infinity()

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

property dimension

embed(subspace=None)

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

property geometry

is_circle()

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

is_hypersphere()

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

quadric()

Return object as quadric.

Returns:

Quadric

unembed(subspace=None)

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

class ddg.geometry.spheres.MetricCayleyKleinSphere(center, radius, absolute, geometry, subspace=None, atol=None, rtol=None)[source]

Bases: _CayleyKleinSphereIntermediate

Cayley-Klein sphere with radius given in terms of metric.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,): center given as Point or in homogeneous coordinates.
radiusfloat
absoluteQuadric
geometryMetricCayleyKleinGeometry: This geometry will be used to convert between Cayley-Klein radius and metric radius.
subspaceSubspace or list of numpy.ndarray of shape (n+1,) (default=None): If given as list, the elements of the list will be interpreted as points in homogeneous coordinates spanning the subspace.
atol, rtolfloat (default=None)

See also

SphereLike, CayleyKleinSphereLike

Attributes:

centerPoint
radiusfloat: Radius in terms of Cayley-Klein metric.
subspaceSubspace

Methods

`quadric`()	Return object as quadric.
`metric_radius`()	Radius in terms of Cayley-Klein metric.
`cayley_klein_radius`()	Cayley-Klein radius.
`generalized_radius`()	Generalized radius.

metric_radius()[source]

Radius in terms of Cayley-Klein metric.

This method will fail if the given radius does not correspond to a metric radius.

Returns:

float

property absolute

The absolute quadric.

Returns:

Quadric

property ambient_dimension

at_infinity()

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

cayley_klein_radius()[source]

Cayley-Klein radius.

This method will fail for horospheres.

Returns:

float

See also

CayleyKleinSphere

property dimension

embed(subspace=None)

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

property geometry

is_circle()

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

is_hypersphere()

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

quadric()

Return object as quadric.

Returns:

Quadric

unembed(subspace=None)

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

generalized_radius()[source]

Generalized radius.

Returns:

float

See also

GeneralizedCayleyKleinSphere

class ddg.geometry.spheres.GeneralizedCayleyKleinSphere(center, radius, absolute, geometry=None, subspace=None, atol=None, rtol=None)[source]

Bases: _CayleyKleinSphereIntermediate

Generalized Cayley-Klein sphere

The radius is given neither in terms of a metric nor a Cayley-Klein distance. This “sphere” is the set of all points x where

b(x, c) ** 2 - r * b(x, x) = 0

where c is center.point, r is the radius and b is absolute.inner_product. This definition allows for horospheres, i.e. spheres with a center that lies on the absolute quadric, at the expense of depending on the representative of center.

Parameters:

centerPoint or numpy.ndarray of shape (n+1,): center given as Point or in homogeneous coordinates.
radiusfloat
absoluteQuadric
geometryMetricCayleyKleinGeometry (default=None): This geometry, if provided, will be used to convert between Cayley-Klein radius and metric radius.
subspaceSubspace or list of numpy.ndarray of shape (n+1,) (default=None): If given as list, the elements of the list will be interpreted as points in homogeneous coordinates spanning the subspace.
atol, rtolfloat (default=None)

See also

SphereLike, CayleyKleinSphereLike

Attributes:

centerPoint
radiusfloat: Generalized radius.
subspaceSubspace

Methods

`quadric`()	Return object as quadric.
`metric_radius`()	Radius in terms of Cayley-Klein metric.
`cayley_klein_radius`()	Cayley-Klein radius.
`generalized_radius`()	Generalized radius.

property absolute

The absolute quadric.

Returns:

Quadric

property ambient_dimension

at_infinity()

Whether the object is contained in the hyperplane at infinity.

Returns:

bool

property dimension

embed(subspace=None)

The embedded object.

We can embed a subset X of n-dimensional projective space into m-dimensional space (where m >= n) by choosing an n-dimensional subspace S in RP^m together with a basis B. We then interpret the original homogeneous coordinates as coordinates w.r.t. this basis B.

More concretely: If M is the matrix of S, we define

X.embed(S) := { [M @ x] | [x] in X }.

X.embed(S) must be the same kind of object as X, for example if X is a euclidean sphere, the basis M must be chosen so that X.embed(S) is also a euclidean sphere.

Parameters:

subspaceSubspace (default=None)

Subspace in m-dimensional ambient space whose dimension is the ambient dimension of self (where m >= n). The homogeneous coordinates of points are used as cordinates w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n+1 = 0} in (n+1)-dimensional space, where n is the ambient dimension of self. The basis is the standard basis with the second to last basis vector missing.

Returns:

type(self): Object in m-dimensional ambient space contained in subspace.

Raises:

ValueError: If embedding w.r.t. the given basis would result in an object of a different type.

property geometry

is_circle()

Whether the sphere is a circle (i.e. 1-dimensional)

Returns:

bool

is_hypersphere()

Whether the sphere is a hypersphere (i.e. of maximal dimension).

Returns:

bool

quadric()

Return object as quadric.

Returns:

Quadric

unembed(subspace=None)

Inverse of embed.

Parameters:

subspaceSubspace (default=None)

k-dim. subspace to treat as the new ambient space. coordinates of points will be computed w.r.t. the given basis of subspace.

The default is the coordinate hyperplane {x_n = 0} which will fail if the object is not contained in this subspace.

Returns:

type(self): Object in k-dim. ambient space.

Raises:

ValueError

If object is not contained in subspace.
If coordinate computation would result in an object of a different type.

center: Point: Center of the sphere.

radius: float: Most often given in terms of a metric, the radius can mean different things depending on the interpretation in a certain geometry.

subspace: Subspace: A subspace containing center that will be intersected with the sphere.

metric_radius()[source]

Radius in terms of Cayley-Klein metric.

This method will fail if the given radius does not correspond to a metric radius.

Returns:

float

Raises:

AttributeError: If no geometry to convert between metric and Cayley-Klein distance was provided.

cayley_klein_radius()[source]

Cayley-Klein radius.

This method will fail for horospheres.

Returns:

float

Raises:

ValueError: If center is contained in absolute, so the Cayley-Klein radius can not be computed.

See also

CayleyKleinSphere

generalized_radius()[source]

Generalized radius.

Returns:

float

See also

GeneralizedCayleyKleinSphere