Source code for geomstats.geometry.lie_algebra

"""Module providing an implementation of MatrixLieAlgebras.

There are two main forms of representation for elements of a MatrixLieAlgebra
implemented here. The first one is as a matrix, as elements of R^(n x n).
The second is by choosing a base and remembering the coefficients of an element
in that base. This base will be provided in child classes
(e.g. SkewSymmetricMatrices).

Lead author: Stefan Heyder.
"""

import abc

import geomstats.backend as gs
import geomstats.errors
from geomstats.geometry.base import MatrixVectorSpace
from geomstats.geometry.matrices import Matrices

from ._bch_coefficients import BCH_COEFFICIENTS




class MatrixLieAlgebra(MatrixVectorSpace, abc.ABC):
    """Class implementing matrix Lie algebra related functions.

    Parameters
    ----------
    representation_dim : int
        Amount of rows and columns in the matrix representation of the
        Lie algebra.
    """

    # TODO: check again need for representation_dim

    def __init__(self, representation_dim, **kwargs):
        geomstats.errors.check_integer(representation_dim, "representation_dim")
        super().__init__(shape=(representation_dim, representation_dim), **kwargs)
        self.representation_dim = representation_dim

    bracket = Matrices.bracket



    def baker_campbell_hausdorff(self, matrix_a, matrix_b, order=2):
        """Calculate the Baker-Campbell-Hausdorff approximation of given order.

        The implementation is based on [CM2009a]_ with the pre-computed
        constants taken from [CM2009b]_. Our coefficients are truncated to
        enable us to calculate BCH up to order 15.

        This represents Z = log(exp(X)exp(Y)) as an infinite linear combination
        of the form Z = sum z_i e_i where z_i are rational numbers and e_i are
        iterated Lie brackets starting with e_1 = X, e_2 = Y, each e_i is given
        by some i',i'': e_i = [e_i', e_i''].

        Parameters
        ----------
        matrix_a : array-like, shape=[..., *point_shape]
        matrix_b : array-like, shape=[..., *point_shape]
            Matrices.
        order : int
            The order to which the approximation is calculated. Note that this
            is NOT the same as using only e_i with i < order.
            Optional, default 2.

        References
        ----------
        .. [CM2009a] F. Casas and A. Murua. An efficient algorithm for
            computing the Baker–Campbell–Hausdorff series and some of its
            applications. Journal of Mathematical Physics 50, 2009
        .. [CM2009b] http://www.ehu.eus/ccwmuura/research/bchHall20.dat
        """
        if order > 15:
            raise NotImplementedError("BCH is not implemented for order > 15.")

        number_of_hom_degree = gs.array(
            [2, 1, 2, 3, 6, 9, 18, 30, 56, 99, 186, 335, 630, 1161, 2182]
        )
        n_terms = gs.sum(number_of_hom_degree[:order])

        el = [matrix_a, matrix_b]
        result = matrix_a + matrix_b

        for i in gs.arange(2, n_terms):
            i_p = BCH_COEFFICIENTS[i, 1] - 1
            i_pp = BCH_COEFFICIENTS[i, 2] - 1

            el.append(self.bracket(el[i_p], el[i_pp]))
            result += (
                float(BCH_COEFFICIENTS[i, 3]) / float(BCH_COEFFICIENTS[i, 4]) * el[i]
            )
        return result