.. _geometries: Geometries ========== The geometry model modules like :py:mod:`~.geometry.hyperbolic_models`, :py:mod:`~.geometry.euclidean_models` etc. define geometries by adding additional structure to a projective space. This can include metrics, angle measurements, etc. Each geometry module has the following contents: - Classes representing models for the geometry. These classes define methods that deal specifically with objects represented in that model. - Functions to convert geometric objects between different models, if there is more than one. For some geometry model classes, there are shortcts, for example: :py:class:`ddg.geometry.euclidean` for :py:class:`ddg.geometry.euclidean_models.ProjectiveModel`. These are the "projective models" (and their duals, if applicable), which make the relation to projective geometry most obvious and are often nice to work with. How exactly objects are represented in a model is documented in the docstrings of the geometry model classes. .. contents:: Table of contents :local: :backlinks: none Example: Euclidean geometry --------------------------- The most familiar geometry is of course Euclidean geometry. We will create two points in the :py:class:`~.euclidean_models.ProjectiveModel` of Euclidean geometry, in which we compute distances as norms of differences in affine coordinates. We will then convert these points to the :py:class:`~.euclidean_models.MoebiusModel`, which is obtained by stereographically projecting to the 3-sphere in 4-space. In this other model, the distance is computed with a different formula, but should match the distance in the projective model. As a geometry that comes with a metric, all models of Euclidean geometry implement the method :py:meth:`~.geometry_model_templates.MetricGeometry.d` that computes the Euclidean distance between objects. All geometries that have a metric work this way, see `Metric geometries`_. .. doctest:: >>> import ddg >>> from ddg.geometry import euclidean_models >>> from ddg.geometry.subspaces import subspace_from_affine_points, Point >>> euc_proj = ddg.geometry.euclidean(3) >>> euc_proj.dimension 3 >>> euc_proj.ambient_dimension 3 >>> p1_euc_proj = subspace_from_affine_points([0, 0, 0]) >>> p2_euc_proj = subspace_from_affine_points([1, 1, 1]) >>> euc_proj.d(p1_euc_proj, p2_euc_proj) 1.732... >>> euc_moeb = euclidean_models.MoebiusModel(3) >>> euc_moeb.dimension 3 >>> euc_moeb.ambient_dimension 4 >>> print(euc_moeb.absolute) quadric in 4D projective space signature: (4, 1) matrix: [[ 1. 0. 0. 0. 0.] [ 0. 1. 0. 0. 0.] [ 0. 0. 1. 0. 0.] [ 0. 0. 0. 1. 0.] [ 0. 0. 0. 0. -1.]] >>> print(euc_moeb.fixed_point) Point in 4D projective space Homogeneous coordinates: [0. 0. 0. 0.5 0.5] >>> p1_euc_moeb = euclidean_models.projective_to_moebius(p1_euc_proj) >>> p2_euc_moeb = euclidean_models.projective_to_moebius(p2_euc_proj) >>> euc_moeb.d(p1_euc_moeb, p2_euc_moeb) 1.732... Note that the attribute ``dimension`` always means the "intuitive" dimension of the geometry. ``ambient_dimension`` is the dimension of the projective space the model lives in. The geometry models also provide a simple way to check whether a point in projective space is actually contained in the model of the geometry. For example, the projective model of Euclidean geometry consists of all points not at infinity: .. doctest:: >>> p1_euc_proj in euc_proj True >>> p_inf = Point([0, 0, 1, 0]) >>> p_inf.at_infinity() True >>> p_inf in euc_proj False Spheres ------- Spheres are created using factory methods of the geometry model classes. Geometries for which spheres are implemented have methods :py:meth:`~.SphereFactory.sphere` that can be used to create them. Geometries defined by quadrics additionally have methods :py:meth:`~.CayleyKleinSphereFactory.cayley_klein_sphere` and :py:meth:`~.CayleyKleinSphereFactory.generalized_cayley_klein_sphere`. .. doctest:: >>> unit_sphere = euc_proj.sphere(p1_euc_proj, 1.0) >>> print(unit_sphere) Sphere in geometry/model: euclidean_models.ProjectiveModel(3) Center: [0. 0. 0. 1.] Radius: 1.0 The different types of geometries --------------------------------- There are three basic types of geometries, implemented as abstract base classes: Metric geometries ~~~~~~~~~~~~~~~~~ :py:class:`~.MetricGeometry`. Geometries of this type just have a dimension and define a metric :py:meth:`~.MetricGeometry.d`. Cayley-Klein geometries ~~~~~~~~~~~~~~~~~~~~~~~ :py:class:`~.CayleyKleinGeometry`. Geometries of this type have a quadric and its induced structure. For example, there is a Cayley-Klein distance, which is defined like this: Let :math:`Q` be a quadric in :math:`\RP^n` called the *absolute quadric* or just *absolute* and let :math:`\langle\cdot,\cdot\rangle` be its associated scalar product. We define the *Cayley-Klein distance* (not a metric!) on :math:`\RP^n \setminus Q` as .. math:: K_Q([x], [y]) \coloneqq \frac{\langle x, y \rangle_Q^2} {\langle x, x \rangle_Q \langle y, y\rangle_Q} The presence of a Cayley-Klein distance means that (generalized) Cayley-Klein spheres can be created in these geometries using the factory methods ``cayley_klein_sphere`` and ``generalized_cayley_klein_sphere``. .. note:: Sometimes in the literature (for example Wikipedia), Cayley-Klein geometries are required to have a metric. We do not require this, because the Cayley-Klein distance and Cayley-Klein spheres still make sense, even without a metric. Metric Cayley-Klein geometries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :py:class:`~.MetricCayleyKleinGeometry`. Geometries of this type are both Metric and Cayley-Klein geometries, as you would expect. A *Cayley-Klein metric* is a metric :math:`d` derived from such a Cayley-Klein distance, namely one that is a function of :math:`K_Q`. In the projective model of hyperbolic geometry for example, the relation is given by the equation .. math:: \cosh^2(d([x],[y])) = K_Q([x],[y]) where :math:`Q` is a quadric of signature :math:`(n,1)` and the metric can be defined for two points which are on the same side of the quadric. You can see that the metric can always be converted to a Cayley-Klein distance, but not vice versa. Which Cayley-Klein distances correspond to metric distances depends on the geometry. In these geometries, both metric spheres (using the method ``sphere``) and Cayley-Klein spheres can be created.