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

Transformations
===============

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

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

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

.. py:class:: Transf

      Instances of this class implement transformations.

      A transformation :math:`f` is just a 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 transformation is stored
      as an array of the images :math:`\{(0)f,(1)f,\ldots,(n−1)f\}`.

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

          Equality comparison.

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

          :param that: the transformation for comparison.
          :type that: Transf

          :returns: A ``bool``.

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

            :returns: A ``bool``.

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

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

            :param that: the transformation to multiply with.
            :type that: Transf

            :returns: A :py:class:`Transf`.

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

            Returns the degree.

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

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

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

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

            :Parameters: None

            :return: A :py:class:`Transf`.

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

            Construct and validate.

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

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

            :return: A newly constructed transformation.
            :rtype: Transf

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

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

            Returns the identity transformation on the given number of
            points.

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

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

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

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

            :param x: a transformation.
            :type x: Transf
            :param y: a transformation.
            :type y: Transf

            :return: (None)

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

            Returns the number of distinct image values.

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

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

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

            Returns an iterator pointing at the first image value.

            :Parameters: None
            :return: An iterator.