polymerist.maths.combinatorics.permutations
===========================================

.. py:module:: polymerist.maths.combinatorics.permutations

.. autoapi-nested-parse::

   Utilites for representing pure permutations, cycles, and permutation groups



Attributes
----------

.. autoapisummary::

   polymerist.maths.combinatorics.permutations.T


Classes
-------

.. autoapisummary::

   polymerist.maths.combinatorics.permutations.Cycle
   polymerist.maths.combinatorics.permutations.Permutation


Module Contents
---------------

.. py:data:: T

.. py:class:: Cycle

   Bases: :py:obj:`tuple`


   For representing a cyclic collection of objects


   .. py:method:: starting_from_index(index: int) -> Cycle

      Return a Cycle which is in the same order as self but begins at the given index



   .. py:method:: copy() -> Cycle


   .. py:property:: mapping
      :type: dict[T, T]


      A mapping of each item in the cycle to the following item


   .. py:method:: max_elem_in_cycles(cycles: Iterable[Cycle]) -> int
      :staticmethod:


      Returns the largest element across a collection of Cycles



   .. py:method:: cycles_are_disjoint(cycles: Iterable[Cycle]) -> bool
      :staticmethod:


      Check if a cycle decomposition is disjoint



   .. py:method:: cycles_produce_partition(cycles: Iterable[Cycle]) -> bool
      :staticmethod:


      Check if a cycle decomposition forms a partition of some set of integers



   .. py:method:: cycle_type(cycles: Iterable[Cycle]) -> dict[int, int]
      :staticmethod:


      Returns a dict of cycle lengths and the number of cycle in the permutation with that length



   .. py:method:: cycle_index_sym(cycle_type: dict[int, int], var_sym: str = 'x', mul_sym: str = '*', exp_sym: str = '^') -> str
      :staticmethod:


      Represent a single cycle type in symbolic variable form
      Can optionally supply custom symbols for variable (single-char only), multiplication sign, and exponentiation sign



.. py:class:: Permutation(*elems: Sequence[int])

   For representing a permutation


   .. py:attribute:: elems
      :type:  Sequence[int]
      :value: []



   .. py:property:: degree
      :type: int



   .. py:property:: element_set
      :type: set[int]



   .. py:method:: from_degree(degree: int, random: bool = False) -> Permutation
      :classmethod:


      Construct a permutation of the given degree. Is just the identity by default, but can be made random with the "random" flag



   .. py:method:: identity(degree: int) -> Permutation
      :classmethod:


      Construct the Identity permutation of a given degree



   .. py:property:: natural_order
      :type: list[int]



   .. py:property:: as_identity
      :type: Permutation


      The identity permutation with the same degree as the current permutation


   .. py:property:: inverse
      :type: Permutation


      The permutation which, when composed with this permutation from either the left or the right, yields the identity permutation


   .. py:property:: reverse
      :type: Permutation


      The reversed-order of a permutation


   .. py:method:: copy() -> Permutation

      Create a copy of the current Permutation



   .. py:method:: image(coll: Iterable[T]) -> Iterable[T]

      The image of an ordered collection under the defined permutation



   .. py:attribute:: compose


   .. py:property:: order
      :type: int


      Smallest power of a permutation which generates the identity permutation


   .. py:method:: from_matrix(matrix: numpy.ndarray) -> Permutation
      :classmethod:


      Create a permutation from a permutation matrix



   .. py:method:: to_matrix() -> numpy.ndarray

      Obtain permutation matrix representation



   .. py:property:: matrix
      :type: numpy.ndarray



   .. py:method:: from_word(word: str, delimiter: str = '') -> Permutation
      :classmethod:


      Create a permutation from a string with a total ordering



   .. py:method:: to_word() -> str


   .. py:method:: from_cycle(cycle: Cycle, degree: Optional[int] = None) -> None
      :classmethod:


      Create a permutation from an ordering of elements in a single cycle. Missing elements are inferred to be fixed points



   .. py:method:: from_cycles(cycles: list[Cycle]) -> Permutation
      :classmethod:


      Stitch together Permutation from disjoint cycle representation



   .. py:method:: as_cycle() -> Cycle

      Reinterpret permutation a defining a cyclic order



   .. py:method:: to_cycles(canonicalize: bool = True) -> list[Cycle]

      Produce cycle decompositon of permutation. NOT TO BE CONFUSED WITH Permutation.as_cycles()!
      By default, returns in canonical order (i.e. each cycle is presented with the least element first)



   .. py:property:: cycles
      :type: list[Cycle]


      Cycle decompositon of permutation in the order that elements appear (i.e. NOT in canonical order)


   .. py:property:: cycles_canonical
      :type: list[Cycle]


      Cycle decompositon of permutation in canonical order (largest element) first in each cycle and)


   .. py:property:: cycle_type
      :type: dict[int, int]


      Returns a dict of cycle lengths and the number of cycle in the permutation with that length


   .. py:method:: from_lehmer(lehmer_code: Sequence[int]) -> Permutation
      :classmethod:


      Stitch together permutation from an inversion vector



   .. py:method:: to_lehmer_code() -> list[int]

      Construct the left lehmer code for a permutation
      Each position in the code gives the number of inversions to the right of the permutation element at the corresponding position



   .. py:property:: lehmer_code
      :type: list[int]



   .. py:property:: num_inversions
      :type: int


      Get total number of "out-of-order" elements in the permutation


   .. py:property:: sign
      :type: int


      The parity of the number of inversion of a permutation


   .. py:attribute:: parity


   .. py:property:: is_even
      :type: bool



   .. py:property:: is_odd
      :type: bool



   .. py:property:: ascents
      :type: list[int]


      The positions of elements which are followed by a greater element


   .. py:property:: num_ascents
      :type: int


      The number of elements which are followed by a greater element


   .. py:property:: descents
      :type: list[int]


      The positions of elements which are followed by a lesser element


   .. py:property:: num_descents
      :type: int


      The number of elements which are followed by a lesser element


   .. py:property:: support
      :type: list[int]


      The positions of elemnts which do not map to themselves


   .. py:property:: support_size
      :type: int


      The number of elements in the permutation which do not map to themselves


   .. py:method:: cycle_index(perm_group: Iterable[Permutation], variable: str = 'x', add_sym: str = ' + ', mul_sym: str = '*', exp_sym: str = '^') -> str
      :staticmethod:


      Construct a string of the cycle index of a permutation group



   .. py:method:: symmetric_group(order: int) -> Generator[Permutation, None, None]
      :classmethod:


      Generate all permutations of a given order



   .. py:method:: alternating_group(order: int) -> Generator[Permutation, None, None]
      :classmethod:


      Generate all even permutations of a given order



   .. py:method:: cyclic_group(order: int, _base_perm: Optional[Permutation] = None) -> Generator[Permutation, None, None]
      :classmethod:


      Generate all cyclic shifts of a given permutation of a given order



   .. py:method:: dihedral_group(order: int) -> Generator[Permutation, None, None]
      :classmethod:


      Generate all permutations of vertex-numbered regular polygon