# -*- coding: utf-8 -*-
r"""
Interface to Hyperbolic Models

This module provides a convenient interface for interacting with models
of hyperbolic space as well as their points, geodesics, and isometries.

The primary point of this module is to allow the code that implements
hyperbolic space to be sufficiently decoupled while still providing a
convenient user experience.

The interfaces are by default given abbreviated names.  For example,
UHP (upper half plane model), PD (Poincaré disk model), KM (Klein disk
model), and HM (hyperboloid model).

.. NOTE::

    All of the current models of 2 dimensional hyperbolic space
    use the upper half plane model for their computations.  This can
    lead to some problems, such as long coordinate strings for symbolic
    points.  For example, the vector ``(1, 0, sqrt(2))`` defines a point
    in the hyperboloid model.  Performing mapping this point to the upper
    half plane and performing computations there may return with vector
    whose components are unsimplified strings have several ``sqrt(2)``'s.
    Presently, this drawback is outweighted by the rapidity with which new
    models can be implemented.

AUTHORS:

- Greg Laun (2013): Initial version.
- Rania Amer, Jean-Philippe Burelle, Bill Goldman, Zach Groton,
  Jeremy Lent, Leila Vaden, Derrick Wigglesworth (2011): many of the
  methods spread across the files.

EXAMPLES::

    sage: HyperbolicPlane().UHP().get_point(2 + I)
    Point in UHP I + 2

    sage: HyperbolicPlane().PD().get_point(1/2 + I/2)
    Point in PD 1/2*I + 1/2
"""
#***********************************************************************
#
#       Copyright (C) 2013 Greg Laun <glaun@math.umd.edu>
#
#
#
#  Distributed under the terms of the GNU General Public License (GPL)
#  as published by the Free Software Foundation; either version 2 of
#  the License, or (at your option) any later version.
#                  http://www.gnu.org/licenses/
#***********************************************************************
from __future__ import division

from sage.structure.unique_representation import UniqueRepresentation
from sage.structure.parent import Parent
from sage.misc.abstract_method import abstract_method
from sage.categories.sets_cat import Sets
from sage.categories.realizations import Realizations, Category_realization_of_parent
from sage.geometry.hyperbolic_space.hyperbolic_model import (
        HyperbolicModelUHP, HyperbolicModelPD,
        HyperbolicModelHM, HyperbolicModelKM)


def HyperbolicSpace(n):
    """
    Return ``n`` dimensional hyperbolic space.

    EXAMPLES::

        sage: from sage.geometry.hyperbolic_space.hyperbolic_interface import HyperbolicSpace
        sage: HyperbolicSpace(2)
        Hyperbolic plane
    """
    if n == 2:
        return HyperbolicPlane()
    raise NotImplementedError("currently only implemented in dimension 2")


class HyperbolicPlane(Parent, UniqueRepresentation):
    """
    The hyperbolic plane `\mathbb{H}^2`.

    Here are the models currently implemented:

    - ``UHP`` -- upper half plane
    - ``PD`` -- Poincaré disk
    - ``KM`` -- Klein disk
    - ``HM`` -- hyperboloid model
    """
    def __init__(self):
        """
        Initialize ``self``.

        EXAMPLES::

            sage: H = HyperbolicPlane()
            sage: TestSuite(H).run()
        """
        Parent.__init__(self, category=Sets().Metric().WithRealizations())
        self.a_realization() # We create a realization so at least one is known

    def _repr_(self):
        """
        Return a string representation of ``self``.

        EXAMPLES::

            sage: HyperbolicPlane()
            Hyperbolic plane
        """
        return "Hyperbolic plane"

    def a_realization(self):
        """
        Return a realization of ``self``.

        EXAMPLES::

            sage: H = HyperbolicPlane()
            sage: H.a_realization()
            Hyperbolic plane in the Upper Half Plane Model
        """
        return self.UHP()

    UHP = HyperbolicModelUHP
    UpperHalfPlane = UHP

    PD = HyperbolicModelPD
    PoincareDisk = PD

    KM = HyperbolicModelKM
    KleinDisk = KM

    HM = HyperbolicModelHM
    Hyperboloid = HM


class HyperbolicModels(Category_realization_of_parent):
    r"""
    The category of hyperbolic models of hyperbolic space.
    """
    def __init__(self, base):
        r"""
        Initialize the hyperbolic models of hyperbolic space.

        INPUT:

        - ``base`` -- a hyperbolic space

        TESTS::

            sage: from sage.geometry.hyperbolic_space.hyperbolic_interface import HyperbolicModels
            sage: H = HyperbolicPlane()
            sage: models = HyperbolicModels(H)
            sage: H.UHP() in models
            True
        """
        Category_realization_of_parent.__init__(self, base)

    def _repr_(self):
        r"""
        Return the representation of ``self``.

        EXAMPLES::

            sage: from sage.geometry.hyperbolic_space.hyperbolic_interface import HyperbolicModels
            sage: H = HyperbolicPlane()
            sage: HyperbolicModels(H)
            Category of hyperbolic models of Hyperbolic plane
        """
        return "Category of hyperbolic models of {}".format(self.base())

    def super_categories(self):
        r"""
        The super categories of ``self``.

        EXAMPLES::

            sage: from sage.geometry.hyperbolic_space.hyperbolic_interface import HyperbolicModels
            sage: H = HyperbolicPlane()
            sage: models = HyperbolicModels(H)
            sage: models.super_categories()
            [Category of metric spaces,
             Category of realizations of Hyperbolic plane]
        """
        return [Sets().Metric(), Realizations(self.base())]

    class ParentMethods:
        def _an_element_(self):
            """
            Return an element of ``self``.

            EXAMPLES::

                sage: H = HyperbolicPlane()
                sage: H.UHP().an_element()
                Point in UHP I
                sage: H.PD().an_element()
                Point in PD 0
                sage: H.KM().an_element()
                Point in KM (0, 0)
                sage: H.HM().an_element()
                Point in HM (0, 0, 1)
            """
            from sage.rings.integer_ring import ZZ
            return self(self.realization_of().PD().get_point(ZZ.zero()))
