Source code for pyzeta.core.symmetries.symmetry_group

"""
Module containing an abstract base for discrete symmetry groups of iterated
function and hyperbolic map systems. Implementations of this interface should
be table driven to allow simple implementations without much additional
boilerplate code.

Authors:\n
- Philipp Schuette\n
"""

from abc import ABC, abstractmethod
from typing import Tuple

from numpy.typing import NDArray

from pyzeta.core.pyzeta_types.general import tVec
from pyzeta.core.pyzeta_types.special import (
    tGroupElement,
    tIrreducibleRepr,
    tLetter,
    tWord,
)




class SymmetryGroup(ABC):
    "Abstract base for discrete groups of symmetries of function systems."

    def __str__(self) -> str:
        "Simple string representation of a discrete symmetry group."
        return "SymmetryGroup(" + str(self.getElements()) + ")"



    def __len__(self) -> int:
        """
        Return the cardinality of the group.

        :return: cardinality (number of elements) of the discrete group
        """
        return len(self.getElements())




    @abstractmethod
    def getElements(self) -> Tuple[tGroupElement, ...]:
        """
        Return the elements of a discrete symmetry group.

        :return: tuple containing the group elements
        """




    @abstractmethod
    def compose(
        self, elem1: tGroupElement, elem2: tGroupElement
    ) -> tGroupElement:
        """
        Calculate the composition (product) `elem1 x elem2` of two group
        elements `elem1` and `elem2`.

        :param elem1: first product component
        :param elem2: second product component
        :return: product of the components
        """




    @abstractmethod
    def applyWord(self, elem: tGroupElement, word: tWord) -> tWord:
        """
        Apply a group element to a symbolic word over the alphabet that the
        symmetry group is acting on.

        :param elem: group element to act with
        :param word: symbolic word to act on
        :return: symbolic word that results from the action
        """




    @abstractmethod
    def applyLetterArray(
        self, elemArray: NDArray[tGroupElement], letterArray: NDArray[tLetter]
    ) -> NDArray[tLetter]:
        """
        Calculate the action of an array of group elements on a parallel array
        of letters from the alphabet that the group acts on.

        :param elemArray: array of group elements to act with
        :param letterArray: array of alphabet letters to act on
        :return: array of alphabet letters resulting from the action
        """




    @abstractmethod
    def elementPower(
        self, baseArray: NDArray[tGroupElement], exponent: int
    ) -> NDArray[tGroupElement]:
        """
        Calculate the element-wise powers of an array of group elements.

        :param baseArray: group elements to exponentiate
        :param exponent: uniform exponent for each array entry
        :return: array of exponentiated group elements
        """




    @abstractmethod
    def conjugate(
        self,
        elem1: tGroupElement,
        elem2: tGroupElement,
    ) -> tGroupElement:
        """
        Calculate the conjugation of `elem1` by `elem2` within the given
        discrete symmetry group, i.e. `elem2 x elem1 x elem2^(-1)`.

        :param elem1: group element to conjugate
        :param elem2: group element to conjugate by
        :return: conjugation by second element applied to first element
        """




    @abstractmethod
    def shiftAction(self, word: tWord, elem: tGroupElement) -> tWord:
        """
        Calculate the shift action on a pair consisting of a symbolic word and
        its closing group element.

        :param word: symbolic word to shift
        :param elem: group element closing the symbolic word
        :return: shifted symbolic word
        """




    @abstractmethod
    def wordPower(
        self, word: tWord, elem: tGroupElement, exponent: int
    ) -> Tuple[tWord, tGroupElement]:
        """
        Calculate an integer power of a pair consisting of a symbolic word and
        its closing group element.

        :param word: symbolic word to exponentiate
        :param elem: group element closing the symbolic word
        :return: pair consisting of the exponentiated word and group element
        """




    @abstractmethod
    def order(self, elem: tGroupElement) -> int:
        """
        Return the order of a given group element, i.e. the cardinality of the
        cyclic subgroup generated by the element.

        :param elem: group element whose order to return
        :return: the order of the element
        """




    @abstractmethod
    def character(
        self, irrRepr: tIrreducibleRepr, elems: NDArray[tGroupElement]
    ) -> tVec:
        """
        Evaluate the group character corresponding to the irreducible
        representation `irrRepr` at the array of group elements `elems`.

        :param irrRepr: irreducible representation whose character to return
        :param elems: array of group elements to evaluate the character on
        :return: vector of character evaluations
        """




    @abstractmethod
    def getDimension(self, irrRepr: tIrreducibleRepr) -> int:
        """
        Return the dimension of the irreducible representation `irrRepr` of the
        given group.

        :param irrRepr: irreducible representation whose dimension to return
        :return: dimension of the given irreducible representation
        """