Modules

class AngleFunction(HyperbolicFunction):
    r"""Compute the angle between two vectors in the hyperbolic plane.

    The hyperbolic angle function computes the angle between two vectors in the
    hyperbolic plane.

    Examples:
        >>> from umf.functions.hyperbolic.angle import AngleFunction
        >>> vector1 = np.array([1, 0])
        >>> vector2 = np.array([0, 1])
        >>> haf = AngleFunction(vector1, vector2)()
        >>> haf.result
        array(1.57079633)

        >>> # Visualization Example
        >>> import matplotlib.pyplot as plt
        >>> from umf.functions.hyperbolic.angle import AngleFunction
        >>> vector1 = np.array([1, 0])
        >>> vector2 = np.array([0, 1])
        >>> haf = AngleFunction(vector1, vector2)()
        >>> angle = haf.result
        >>> fig, ax = plt.subplots()
        >>> _ = ax.quiver(
        ...     0, 0, vector1[0], vector1[1], angles='xy', scale_units='xy', scale=1,
        ...     color='r', label='Vector 1'
        ... )
        >>> _ = ax.quiver(
        ...     0, 0, vector2[0], vector2[1], angles='xy', scale_units='xy', scale=1,
        ...     color='b', label='Vector 2'
        ... )
        >>> _ = ax.set_xlim(-1.5, 1.5)
        >>> _ = ax.set_ylim(-1.5, 1.5)
        >>> _ = ax.set_aspect('equal')
        >>> _ = ax.legend()
        >>> _ = plt.title(f'Angle: {angle:.2f} radians')
        >>> plt.grid()
        >>> plt.savefig("AngleFunction.png", dpi=300, transparent=True)

    Notes:
        The angle between two vectors $(x_1, y_1)$ and $(x_2, y_2)$ in the hyperbolic
        plane is given by:

        $$
        \theta = \cos^{-1}\left(\frac{x_1 x_2 + y_1 y_2}{\sqrt{x_1^2 + y_1^2}
        \sqrt{x_2^2 + y_2^2}}\right)
        $$

        > Reference: https://en.wikipedia.org/wiki/Hyperbolic_angle

    Args:
        *vectors (UniversalArray): The coordinates of the two vectors in the hyperbolic
            plane.
    """

    def __init__(self, *vectors: UniversalArray) -> None:
        """Initialize the hyperbolic angle function."""
        super().__init__(*vectors)

    @property
    def __eval__(self) -> float:
        """Compute the angle between two vectors in the hyperbolic plane.

        Returns:
            float: The angle between the two vectors in radians.
        """
        x1, y1 = self._x[0]
        x2, y2 = self._x[1]
        dot_product = x1 * x2 + y1 * y2
        norm1 = np.sqrt(x1**2 + y1**2)
        norm2 = np.sqrt(x2**2 + y2**2)
        return np.arccos(dot_product / (norm1 * norm2))

class AreaFunction(HyperbolicFunction):
    r"""Calculate the area of a polygon in the hyperbolic plane.

    The hyperbolic area function calculates the area of a polygon in the hyperbolic
    plane.

    Examples:
        >>> from umf.functions.hyperbolic.area import AreaFunction
        >>> vertices = np.array([(0, 0), (1, 0), (0, 1)])
        >>> haf = AreaFunction(*vertices)()
        >>> haf.result
        array(0.5)

        >>> # Visualization Example
        >>> import matplotlib.pyplot as plt
        >>> from umf.functions.hyperbolic.area import AreaFunction
        >>> vertices = np.array([(0, 0), (1, 0), (0, 1)])
        >>> haf = AreaFunction(*vertices)()
        >>> area = haf.result
        >>> fig, ax = plt.subplots()
        >>> polygon = plt.Polygon(vertices, closed=True, fill=None, edgecolor='r')
        >>> _ = ax.add_patch(polygon)
        >>> _ = ax.set_xlim(-0.5, 1.5)
        >>> _ = ax.set_ylim(-0.5, 1.5)
        >>> _ = ax.set_aspect('equal')
        >>> _ = plt.title(f'Area: {area:.2f}')
        >>> plt.grid()
        >>> plt.savefig("AreaFunction.png", dpi=300, transparent=True)

    Notes:
        The area of a polygon in the hyperbolic plane is given by:

        $$
        A = \frac{1}{2} \left| \sum_{i=1}^{n} (x_i y_{i+1} - x_{i+1} y_i) \right|
        $$

        > Reference: https://en.wikipedia.org/wiki/Hyperbolic_area

    Args:
        *vertices (UniversalArray): The coordinates of the vertices of the polygon in
            the hyperbolic plane.
    """

    def __init__(self, *vertices: UniversalArray) -> None:
        """Initialize the hyperbolic area function."""
        super().__init__(*vertices)

    @property
    def __eval__(self) -> float:
        """Calculate the area of a polygon in the hyperbolic plane.

        Returns:
            float: The area of the polygon in the hyperbolic plane.
        """
        n = len(self._x)
        area = 0.0
        for i in range(n):
            x1, y1 = self._x[i]
            x2, y2 = self._x[(i + 1) % n]
            area += x1 * y2 - x2 * y1
        return 0.5 * np.abs(area)

class DistanceFunction(HyperbolicFunction):
    r"""Calculate the hyperbolic distance between two points in the hyperbolic plane.

    The hyperbolic distance function calculates the distance between two points in the
    hyperbolic plane.

    Examples:
        >>> from umf.functions.hyperbolic.distance import DistanceFunction
        >>> point1 = np.array([0.1, 0.1])
        >>> point2 = np.array([1, 1])
        >>> hdf = DistanceFunction(point1, point2)()
        >>> hdf.result
        array(2.89838887)

        >>> # Visualization Example
        >>> import matplotlib.pyplot as plt
        >>> from umf.functions.hyperbolic.distance import DistanceFunction
        >>> point1 = np.array([0.1, 0.1])
        >>> point2 = np.array([1, 1])
        >>> hdf = DistanceFunction(point1, point2)()
        >>> distance = hdf.result
        >>> fig, ax = plt.subplots()
        >>> _ = ax.plot([point1[0], point2[0]], [point1[1], point2[1]], 'ro-')
        >>> _ = ax.set_xlim(-0.5, 1.5)
        >>> _ = ax.set_ylim(-0.5, 1.5)
        >>> _ = ax.set_aspect('equal')
        >>> _ = plt.title(f'Distance: {distance:.2f}')
        >>> plt.grid()
        >>> plt.savefig("DistanceFunction.png", dpi=300, transparent=True)

    Notes:
        The hyperbolic distance between two points $(x_1, y_1)$ and $(x_2, y_2)$ in the
        hyperbolic plane is given by:

        $$
        d = \cosh^{-1}\left(1 + \frac{(x_2 - x_1)^2 + (y_2 - y_1)^2}{2 y_1 y_2}\right)
        $$

        > Reference: https://en.wikipedia.org/wiki/Hyperbolic_distance

    Args:
        *points (UniversalArray): The coordinates of the two points in the hyperbolic
            plane.
    """

    def __init__(self, *points: UniversalArray) -> None:
        """Initialize the hyperbolic distance function."""
        super().__init__(*points)

    @property
    def __eval__(self) -> float:
        """Calculate the hyperbolic distance between two points in the hyperbolic plane.

        Returns:
            float: The hyperbolic distance between the two points.
        """
        x1, y1 = self._x[0].astype(np.float64)
        x2, y2 = self._x[1].astype(np.float64)
        return np.asarray(
            np.arccosh(1 + ((x2 - x1) ** 2 + (y2 - y1) ** 2) / (2 * y1 * y2))
        )

class GeodesicFunction(HyperbolicFunction):
    r"""Determine the shortest path between two points in the hyperbolic plane.

    The hyperbolic geodesic function determines the shortest path between two points
    in the hyperbolic plane.

    Examples:
        >>> from umf.functions.hyperbolic.geodesic import GeodesicFunction
        >>> point1 = np.array([0.1, 0.1])
        >>> point2 = np.array([1, 1])
        >>> hgf = GeodesicFunction(point1, point2)()
        >>> hgf.result
        array(2.89838887)

        >>> # Visualization Example
        >>> import matplotlib.pyplot as plt
        >>> from umf.functions.hyperbolic.geodesic import GeodesicFunction
        >>> point1 = np.array([0.1, 0.1])
        >>> point2 = np.array([1, 1])
        >>> hgf = GeodesicFunction(point1, point2)()
        >>> distance = hgf.result
        >>> fig, ax = plt.subplots()
        >>> _ = ax.plot([point1[0], point2[0]], [point1[1], point2[1]], 'ro-')
        >>> _ = ax.set_xlim(-0.5, 1.5)
        >>> _ = ax.set_ylim(-0.5, 1.5)
        >>> _ = ax.set_aspect('equal')
        >>> _ = plt.title(f'Distance: {distance:.2f}')
        >>> plt.grid()
        >>> plt.savefig("GeodesicFunction.png", dpi=300, transparent=True)

    Notes:
        The hyperbolic geodesic between two points $(x_1, y_1)$ and $(x_2, y_2)$ in the
        hyperbolic plane is given by:

        $$
        d = \cosh^{-1}\left(1 + \frac{(x_2 - x_1)^2 + (y_2 - y_1)^2}{2 y_1 y_2}\right)
        $$

        > Reference: https://en.wikipedia.org/wiki/Hyperbolic_geodesic

    Args:
        *points (UniversalArray): The coordinates of the two points in the hyperbolic
            plane.
    """

    def __init__(self, *points: UniversalArray) -> None:
        """Initialize the hyperbolic geodesic function."""
        super().__init__(*points)

    @property
    def __eval__(self) -> float:
        """Determine the shortest path between two points in the hyperbolic plane.

        Returns:
            float: The length of the geodesic between the two points.
        """
        x1, y1 = self._x[0]
        x2, y2 = self._x[1]
        return np.arccosh(1 + ((x2 - x1) ** 2 + (y2 - y1) ** 2) / (2 * y1 * y2))

class IsometryFunction(HyperbolicFunction):
    r"""Apply an isometry transformation to a point in the hyperbolic plane.

    The hyperbolic isometry function applies isometries (transformations that preserve
    distances) in the hyperbolic plane.

    Examples:
        >>> from umf.functions.hyperbolic.isometry import IsometryFunction
        >>> point = np.array([1, 1], dtype=float)
        >>> matrix = np.array([[1, 1], [1, 1]], dtype=float)
        >>> hif = IsometryFunction(point, matrix)()
        >>> hif.result
        array([2., 2.])

        >>> # Visualization Example
        >>> import matplotlib.pyplot as plt
        >>> from umf.functions.hyperbolic.isometry import IsometryFunction
        >>> point = np.array([1, 1])
        >>> matrix = np.array([[1, 1], [1, 1]])
        >>> hif = IsometryFunction(point, matrix)()
        >>> transformed_point = hif.result
        >>> fig, ax = plt.subplots()
        >>> _  = ax.quiver(
        ...     0, 0, point[0], point[1], angles='xy', scale_units='xy', scale=1,
        ...     color='r', label='Original Point'
        ... )
        >>> _  = ax.quiver(
        ...     0, 0, transformed_point[0], transformed_point[1], angles='xy',
        ...     scale_units='xy', scale=1, color='b', label='Transformed Point'
        ... )

        >>> _  = ax.set_xlim(-1.5, 2.5)
        >>> _  = ax.set_ylim(-1.5, 2.5)
        >>> ax.set_aspect('equal')
        >>> _  = ax.legend()
        >>> _  = plt.title('Hyperbolic Isometry Transformation')
        >>> plt.grid()
        >>> plt.savefig("IsometryFunction.png", dpi=300, transparent=True)

    Notes:
        An isometry transformation in the hyperbolic plane is represented by a 2x2
        matrix. The transformation is applied to a point $(x, y)$ in the hyperbolic
        plane to obtain a new point $(x', y')$.

        > Reference: https://en.wikipedia.org/wiki/Isometry

    Args:
        *args (UniversalArray): The point (x, y) to be transformed and the 2x2 isometry
            matrix.
    """

    def __init__(self, *args: UniversalArray) -> None:
        """Initialize the hyperbolic isometry function."""
        super().__init__(*args)

    @property
    def __eval__(self) -> np.ndarray:
        """Apply an isometry transformation to a point in the hyperbolic plane.

        Returns:
            np.ndarray: The transformed point (x', y').
        """
        point = self._x[0].astype(np.float64)
        matrix = self._x[1].astype(np.float64)
        return np.dot(matrix, point)