.. 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

Partial perms
=============

This page contains the documentation for functionality in
``libsemigroups_pybind11`` for partial perms.

Partial perms on up to ``4294967296`` points are available in
``libsemigroups_pybind11`` using the function :py:class:`PPerm`.
:py:class:`PPerm` 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 partial perm with fewer points requiring less
space per point.  If ``libsemigroups`` has been compiled with ``HPCombi``
enabled, then the objects returned by :py:class:`PPerm` use the SSE and AVX
instruction sets are used for very fast manipulation.

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

.. py:class:: PPerm

      Instances of this class implement partial perms.

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

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

          Equality comparison.

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

          :param that: the partial perm for comparison.
          :type that: PPerm

          :returns: A ``bool``.

      .. py:method:: __getitem__(self: PPerm, 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: PPerm, that: PPerm) -> 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 partial perm for comparison.
            :type that: PPerm

            :returns: A ``bool``.

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

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

            :param that: the partial perm to multiply with.
            :type that: PPerm

            :returns: A :py:class:`PPerm`.

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

            Returns the degree.

            Returns the number of points that the partial perm is defined
            on.

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

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

            Returns the identity partial perm on :py:meth:`degree` points.

            :Parameters: None

            :return: A :py:class:`PPerm`.

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

            Construct and validate.

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

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

            :return: A newly constructed partial perm.
            :rtype: PPerm

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

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

            Returns the identity partial perm on the given number of
            points.

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

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

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

            Multiply two partial perms and store the product in ``self``.

            :param x: a partial perm.
            :type x: PPerm
            :param y: a partial perm.
            :type y: PPerm

            :return: (None)

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

            Returns the number of distinct image values.

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

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

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

            Returns an iterator pointing at the first image value.

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

            Returns the inverse.

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

      .. py:staticmethod:: make(dom: List[int], ran: List[int], M: int) -> PPerm
            :noindex:

            Construct from domain, range, and degree, and validate.

            :Parameters: - **dom** (List[int]) - the domain
                         - **ran** (List[int]) - the range
                         - **M** (int) - the degree

            :return: A newly constructed :py:class:`PPerm`.

      .. py:method:: inverse(self: PPerm, that: PPerm) -> None
            :noindex:

            Replace contents of a partial perm with the inverse of another.

            :Parameters: **that** (PPerm) - the partial perm to invert.

            :Returns: (None)

      .. py:method:: left_one(self: PPerm) -> PPerm

            Returns the left one of ``self``.

            :Parameters: None.
            :return: A ``PPerm``.

      .. py:method:: right_one(self: PPerm) -> PPerm

            Returns the right one of this.

            :Parameters: None.
            :return: A ``PPerm``.

      .. py:method:: undef(self: PPerm) -> int

            Returns the integer value used to represent undefined.

            :Parameters: None.

            :Returns: An ``int``.