.. Copyright (c) 2021, J. D. Mitchell

   Distributed under the terms of the GPL license version 3.

   The full license is in the file LICENSE, distributed with this software.

   This file was auto-generated from the template in docs/templates/api/transf.rst

   DO NOT EDIT this file directly

Permutations
============

This page contains the documentation for functionality in
``libsemigroups_pybind11`` for permutations.

Permutations on up to ``4294967296`` points are available in
``libsemigroups_pybind11`` using the function :py:class:`Perm`.
:py:class:`Perm` is a function that returns an instance of one of a number of
internal classes. These internal types are optimised for the number of points
in the image of the specified permutation with fewer points requiring less
space per point.  If ``libsemigroups`` has been compiled with ``HPCombi``
enabled, then the objects returned by :py:class:`Perm` use the SSE and AVX
instruction sets are used for very fast manipulation.

While :py:class:`Perm` is not a class the objects returned by
:py:class:`Perm` have identical methods, and so we document
:py:class:`Perm` as if it was a class.

.. py:class:: Perm

      Instances of this class implement permutations.

      A permutation :math:`f` is just a bijective function defined on
      the whole of :math:`\{0,1,\ldots,n−1\}` for some positive integer
      :math:`n` called the *degree* of :math:`f`. A permutation is stored
      as an array of the images :math:`\{(0)f,(1)f,\ldots,(n−1)f\}`.

      .. py:method:: __eq__(self: Perm, that: Perm) -> bool

          Equality comparison.

          Returns ``True`` if ``self`` equals ``that`` by comparing their
          image values.

          :param that: the permutation for comparison.
          :type that: Perm

          :returns: A ``bool``.

      .. py:method:: __getitem__(self: Perm, i: int) -> int

            Returns the image of ``i``.

            :param i: the value whose image is sought.
            :type i: int

            :return: An ``int``.

      .. py:method:: __lt__(self: Perm, that: Perm) -> bool

            Less than comparison.

            Returns ``True`` if the list of images of ``self`` is
            lexicographically less than the list of images of ``that``.

            :param that: the permutation for comparison.
            :type that: Perm

            :returns: A ``bool``.

      .. py:method:: __mul__(self: Perm, that: Perm) -> Perm

            Right multiply ``self`` by ``that``.

            :param that: the permutation to multiply with.
            :type that: Perm

            :returns: A :py:class:`Perm`.

      .. py:method:: degree(self: Perm) -> int

            Returns the degree.

            Returns the number of points that the permutation is defined
            on.

            :Parameters: ``None``
            :return: An ``int``.

      .. py:method:: identity(self: Perm) -> int

            Returns the identity permutation on :py:meth:`degree` points.

            :Parameters: None

            :return: A :py:class:`Perm`.

      .. py:staticmethod:: make(l: List[int]) -> Perm

            Construct and validate.

            Constructs a permutation initialized using list ``l`` as
            follows: the image of the point ``i`` under the permutation is
            ``l[i]``.

            :param l: the list of images.
            :type l: List[int]

            :return: A newly constructed permutation.
            :rtype: Perm

            :raises RuntimeError: if any value in ``l`` exceeds ``len(l)``.

      .. py:staticmethod:: make_identity(M: int) -> Perm

            Returns the identity permutation on the given number of
            points.

            :Parameters: **M** (int) - the degree.

            :Returns: A value of type :py:class:`Perm`.

      .. py:method:: product_inplace(self: Perm, x: Perm, y: Perm) -> None

            Multiply two permutations and store the product in ``self``.

            :param x: a permutation.
            :type x: Perm
            :param y: a permutation.
            :type y: Perm

            :return: (None)

      .. py:method:: rank(self: Perm) -> int

            Returns the number of distinct image values.

            The rank of a permutation is the number of its
            distinct image values.

            :Parameters: None
            :return: An ``int``.

      .. py:method:: images(self: Perm) -> Iterator

            Returns an iterator pointing at the first image value.

            :Parameters: None
            :return: An iterator.
      .. py:method:: inverse(self: Perm) -> Perm

            Returns the inverse.

            :Parameters: None
            :Returns: A :py:class:`Perm`.