<Chapter Label="Transformations">
<Heading>Transformations</Heading>

This chapter describes the functions in &GAP; for transformations.
<P/>

A <E>transformation</E> in &GAP; is simply a function from the positive
integers to the positive integers.  Transformations are to semigroup
theory what permutations are to group theory, in the sense that every
semigroup can be realised as a semigroup of transformations. In &GAP;
transformation semigroups are always finite, and so only finite
semigroups can be realised in this way.
<P/>

A transformation in &GAP; acts on the positive integers (up to some
architecture dependent limit) on the right. The image of a point
<C>i</C> under a transformation <C>f</C> is expressed as <C>i ^ f</C> in
&GAP;.  This action is also implemented by the function <Ref
  Func="OnPoints"/>.  If <C>i ^ f</C> is different from <C>i</C>, then
<C>i</C> is <E>moved</E> by <E>f</E> and otherwise it is <E>fixed</E> by
<C>f</C>.  Transformations in &GAP; are created using the operations
described in Section <Ref Sect="sect:CreatingTransformations"/>.
<P/>

The <E>degree</E> of a transformation <C>f</C> is usually defined as the
largest positive integer where <C>f</C> is defined.  In previous
versions of &GAP;, transformations were only defined on positive
integers less than their degree, it was only possible to multiply
transformations of equal degree, and a transformation did not act on any
point exceeding its degree.  Starting with version 4.7 of &GAP;,
transformations behave more like permutations, in that they fix
unspecified points and it is possible to multiply arbitrary
transformations; see Chapter <Ref Chap="Permutations"/>.  The definition
of the degree of a transformation <C>f</C> in the current version of
&GAP; is the largest value <C>n</C> such that <C>n ^ f &lt;> n</C> or
<C>i ^ f = n</C> for some <C>i &lt;> n</C>. Equivalently, the degree of
a transformation is the least value <C>n</C> such that
<C>[ n + 1, n + 2, ... ]</C> is fixed pointwise by <C>f</C>.
<P/>

The transformations of a given degree belong to the full transformation
semigroup of that degree; see <Ref Func="FullTransformationSemigroup"/>.
Transformation semigroups are hence subsemigroups of the full
transformation semigroup.
<P/>

It is possible to use transformations in &GAP; without reference to the
degree, much as it is possible to use permutations in this way.
However, for backwards compatibility, and because it is sometimes
useful, it is possible to access the degree of a transformation using
<Ref Func="DegreeOfTransformation"/>. Certain attributes of
transformations are also calculated with respect to the degree, such as
the rank, image set, or kernel (these values can also be calculated with
respect to any positive integer). So, it is possible to ignore the
degree of a transformation if you prefer to think of transformations as
acting on the positive integers in a similar way to permutations. For
example, this approach is used in the <Package>FR</Package> package. It
is also possible to think of transformations as only acting on the
positive integers not exceeding their degree. For example, this was the
approach formerly used in &GAP; and it is also useful in the
<Package>Semigroups</Package> package.
<P/>

Transformations are displayed, by default, using the list
<C>[ 1 ^ f .. n ^ f ]</C> where <C>n</C> is the degree of <C>f</C>.
This behaviour differs from that of versions of &GAP; earlier than 4.7.
See Section <Ref Sect="sect:DisplayingTransformations"/> for more information.
<P/>

The <E>rank</E> of a transformation on the positive integers up to
<C>n</C> is the number of distinct points in <C>[ 1 ^ f .. n ^ f ]</C>.
The <E>kernel</E> of a transformation <C>f</C> on <C>[ 1 .. n ]</C> is
the equivalence relation on <C>[ 1 .. n ]</C> consisting of those pairs
<C>(i, j)</C> of positive integers such that  <C>i ^ f = j ^ f</C>.  The
kernel of a transformation is represented in two ways: as a partition of
<C>[ 1 .. n ]</C> or as the image list of a transformation <C>g</C> such
that the kernel of <C>g</C> on <C>[ 1 .. n ]</C> equals the kernel of
<C>f</C> and <C>j ^ g = i</C> for all <C>j</C> in <C>i</C>th class. The
latter is referred to as the <E>flat kernel</E> of <C>f</C>. For any
given transformation <C>f</C> and value <C>n</C>, there is a unique
transformation <C>g</C> with this property.
<P/>

A <E>functional digraph</E> is a directed graph where every vertex has
out-degree <M>1</M>.  A transformation <A>f</A> can be thought of as a
functional digraph with vertices the positive integers and edges from
<C>i</C> to <C>i ^ f</C> for every <C>i</C>. A <E>component</E> of a
transformation is defined as a component of the corresponding functional
digraph.  More specifically, <C>i</C> and <C>j</C> are in the same
component if and only if there are <M>i = v_0, v_1, \ldots, v_n = j</M>
such that either <M>v_{k+1}=v_{k}^f</M> or <M>v_{k}=v_{k+1}^f</M> for
all <M>k</M>.  A <E>cycle</E> of a transformation is defined as a cycle
(or strongly connected component) of the corresponding functional
digraph.  More specifically, <C>i</C> belongs to a cycle of <A>f</A> if
there are <M>i=v_0, v_1, \ldots, v_n=i</M> such that either
<M>v_{k+1}=v_{k}^f</M> or <M>v_{k}=v_{k+1}^f</M> for all <M>k</M>.
<P/>

Internally, &GAP; stores a transformation <C>f</C> as a list consisting
of the images <C>i ^ f</C> for all values of <C>i</C> less than a value
which is at least the degree of <C>f</C> and which is determined at the
time of the creation of <C>f</C>. When the degree of a transformation
<C>f</C> is at most 65536, the images of points under <C>f</C> are
stored as 16-bit integers, the kernel and image set are subobjects of
<C>f</C> which are plain lists of &GAP; integers.  When the degree of
<C>f</C> is greater than 65536, the images of points under <C>f</C> are
stored as 32-bit integers; the kernel and image set are stored in the
same way as before.  A transformation belongs to <C>IsTrans2Rep</C> if
it is stored using 16-bit integers and to <C>IsTrans4Rep</C> if it is
stored using 32-bit integers.
<P/>

<Section>
    <Heading>The family and categories of transformations</Heading>
  <ManSection>
    <Filt Name="IsTransformation" Arg="obj" Type="Category"/>
    <Description>
    Every transformation in &GAP; belongs to the category
    <C>IsTransformation</C>. Basic operations for transformations are
    <Ref Oper="ImageListOfTransformation"/>,
    <Ref Attr="ImageSetOfTransformation"/>,
    <Ref Attr="KernelOfTransformation"/>,
    <Ref Attr="FlatKernelOfTransformation"/>,
    <Ref Attr="RankOfTransformation"
      Label="for a transformation and a list"/>,
    <Ref Func="DegreeOfTransformation"/>,
    multiplication of two transformations via <K>*</K>, and
    exponentiation with the first argument a positive integer <C>i</C>
    and second argument a transformation <C>f</C> where the result is
    the image <C>i ^ f</C> of the point <C>i</C> under <C>f</C>.
    </Description>
  </ManSection>

  <ManSection>
    <Filt Name="IsTransformationCollection" Arg="obj" Type="Category"/>
    <Description>
     Every collection of transformations belongs to the category
     <C>IsTransformationCollection</C>. For example, transformation
     semigroups belong to <C>IsTransformationCollection</C>.
    </Description>
  </ManSection>

  <ManSection>
    <Fam Name="TransformationFamily"/>
    <Description>
      The family of all transformations is <C>TransformationFamily</C>.
    </Description>
  </ManSection>
</Section>

<!-- *************************************************************** -->

<Section Label="sect:CreatingTransformations">
  <Heading>Creating transformations</Heading>

  There are several ways of creating transformations in &GAP;, which are
  described in this section.

  <!-- *************************************************************** -->

  <ManSection>
    <Oper Name="Transformation" Arg="list" Label="for an image list"/>
    <Oper Name="Transformation" Arg="list, func"
      Label="for a list and function"/>
    <Oper Name="TransformationList" Arg="list" Label="for an image list"/>
    <Returns>A transformation.</Returns>
    <Description>
      <C>TransformationList</C> returns the transformation <C>f</C> such
      that <C>i ^ <A>f</A> = <A>list</A>[i]</C> if <C>i</C> is between
      <C>1</C> and the length of <A>list</A> and <C>i ^ <A>f</A> = i</C>
      if <C>i</C> is larger than the length of <A>list</A>. An error will
      occur in <C>TransformationList</C> if <A>list</A> is not dense, if
      <A>list</A> contains an element which is not a positive integer,
      or if <A>list</A> contains an integer not in
      <C>[ 1 .. Length( <A>list</A> ) ]</C>.
      <P/>

      <C>TransformationList</C> is the analogue in the context of
      transformations of <Ref Func="PermList"/>. <C>Transformation</C>
      is a synonym of <C>TransformationList</C> when the argument is a
      list.
      <P/>

      When the arguments are a list of positive integers <A>list</A> and
      a function <A>func</A>, <C>Transformation</C> returns the
      transformation <C>f</C> such that
      <C><A>list</A>[i] ^ f = <A>func</A>( <A>list</A>[i] )</C> if
      <C>i</C> is in the range <C>[ 1 .. Length( <A>list</A> ) ]</C> and
      <C>f</C> fixes all other points.

      <Example><![CDATA[
gap> SetUserPreference( "NotationForTransformations", "input" );
gap> f := Transformation( [ 11, 10, 2, 11, 4, 4, 7, 6, 9, 10, 1, 11 ] );
Transformation( [ 11, 10, 2, 11, 4, 4, 7, 6, 9, 10, 1, 11 ] )
gap> f := TransformationList( [ 2, 3, 3, 1 ] );
Transformation( [ 2, 3, 3, 1 ] )
gap> SetUserPreference( "NotationForTransformations", "fr" );
gap> f := Transformation( [ 10, 11 ], x -> x ^ 2 );
<transformation: 1,2,3,4,5,6,7,8,9,100,121>
gap> SetUserPreference( "NotationForTransformations", "input" );
]]></Example>
    </Description>
  </ManSection>

  <!-- *************************************************************** -->

  <ManSection>
    <Oper Name="Transformation" Arg="src, dst"
      Label="for a source and destination"/>
    <Oper Name="TransformationListList" Arg="src, dst"
      Label="for a source and destination"/>
    <Returns>A transformation.</Returns>
    <Description>
      If <A>src</A> and <A>dst</A> are lists of positive integers of the
      same length, such that <A>src</A> contains no  element  twice,
      then <C>TransformationListList( <A>src</A>, <A>dst</A> )</C> returns
      a transformation  <C>f</C>  such  that
      <C>src[i] ^ <A>f</A> = dst[i]</C>. The transformation <A>f</A>
      fixes all points larger than the maximum of the entries in
      <A>src</A> and <A>dst</A>.
      <P/>

      <C>TransformationListList</C> is the analogue in the context of
      transformations of <Ref Func="MappingPermListList"/>.
      <C>Transformation</C> is a synonym of
      <C>TransformationListList</C> when its arguments are two lists of
      positive integers.
    <Example><![CDATA[
gap> Transformation( [ 10, 11 ],[ 11, 12 ] );
Transformation( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 12 ] )
gap> TransformationListList( [ 1, 2, 3 ], [ 4, 5, 6 ] );
Transformation( [ 4, 5, 6, 4, 5, 6 ] )
]]></Example>
    </Description>
  </ManSection>

  <!-- *************************************************************** -->

  <ManSection>
    <Oper Name="TransformationByImageAndKernel" Arg="im, ker"
      Label="for an image and kernel"/>
    <Returns>A transformation or <K>fail</K>.</Returns>
    <Description>
      This operation returns the transformation <C>f</C> where <C>i ^ f
        = <A>im</A>[<A>ker</A>[i]]</C> for <C>i</C> in the range
      <C>[ 1 .. Length( <A>ker</A> ) ]</C>. This transformation has flat
      kernel equal to <A>ker</A> and image set equal to
      <C>Set( <A>im</A> )</C>.
      <P/>

      The argument <A>im</A> should be a duplicate free list of
      positive integers and <A>ker</A> should be the flat kernel of a
      transformation with rank equal to the length of <A>im</A>. If the
      arguments do not fulfil these conditions, then <K>fail</K> is
      returned.

      <Example><![CDATA[
gap> TransformationByImageAndKernel( [ 8, 1, 3, 4 ],
>                                    [ 1, 2, 3, 1, 2, 1, 2, 4 ] );
Transformation( [ 8, 1, 3, 8, 1, 8, 1, 4 ] )
gap> TransformationByImageAndKernel( [ 1, 3, 8, 4 ],
>                                    [ 1, 2, 3, 1, 2, 1, 2, 4 ] );
Transformation( [ 1, 3, 8, 1, 3, 1, 3, 4 ] )
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Oper Name="Idempotent" Arg="im, ker"/>
    <Returns>A transformation or <K>fail</K>.</Returns>
    <Description>
      <Ref Oper="Idempotent"/> returns the idempotent transformation
      with image set <A>im</A> and flat kernel <A>ker</A> if such a
      transformation exists and <K>fail</K> if it does not.
      More specifically, a transformation is returned when the argument
      <A>im</A> is a set of positive integers and <A>ker</A> is the flat
      kernel of a transformation with rank equal to the length of
      <A>im</A> and where <A>im</A> has one element in every class of
      the kernel corresponding to <A>ker</A>.
      <P/>

      Note that this is function does not always return the same
      transformation as <C>TransformationByImageAndKernel</C> with the
      same arguments.

      <Example><![CDATA[
gap> Idempotent( [ 2, 4, 6, 7, 8, 10, 11 ],
>                [ 1, 2, 1, 3, 3, 4, 5, 1, 6, 6, 7, 5 ] );
Transformation( [ 8, 2, 8, 4, 4, 6, 7, 8, 10, 10, 11, 7 ] )
gap> TransformationByImageAndKernel( [ 2, 4, 6, 7, 8, 10, 11 ],
>                      [ 1, 2, 1, 3, 3, 4, 5, 1, 6, 6, 7, 5 ] );
Transformation( [ 2, 4, 2, 6, 6, 7, 8, 2, 10, 10, 11, 8 ] )
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Oper Name="TransformationOp" Arg="obj, list[, func]"/>
    <Oper Name="TransformationOpNC" Arg="obj, list[, func]"/>
    <Returns>A transformation or <K>fail</K>.</Returns>
    <Description>
      <Ref Oper="TransformationOp"/> returns the transformation that
      corresponds to the action of the object <A>obj</A> on the domain
      or list <A>list</A> via the function <A>func</A>. If the optional
      third argument <A>func</A> is not specified, then the action <Ref
        Func="OnPoints"/> is used by default.  Note that the returned
      transformation refers to the positions in <A>list</A> even if
      <A>list</A> itself consists of integers.
      <P/>

      This function is the analogue in the context of transformations of
      <Ref Func="Permutation"
        Label = "for a group, an action domain, etc."/>.
      <P/>

      If <A>obj</A> does not map elements of <A>list</A> into
      <A>list</A>, then <K>fail</K> is returned.
      <P/>

      <Ref Oper="TransformationOpNC"/> does not check that <A>obj</A>
      maps elements of <A>list</A> to elements of <A>list</A> or that a
      transformation is defined by the action of <A>obj</A> on
      <A>list</A> via <A>func</A>.  This function should be used only
      with caution, and in situations where it is guaranteed that the
      arguments have the required properties.

      <Example><![CDATA[
gap> f := Transformation( [ 10, 2, 3, 10, 5, 10, 7, 2, 5, 6 ] );;
gap> TransformationOp( f, [ 2, 3 ] );
IdentityTransformation
gap> TransformationOp( f, [ 1, 2, 3 ] );
fail
gap> S := SemigroupByMultiplicationTable( [ [ 1, 1, 1 ],
>                                           [ 1, 1, 1 ],
>                                           [ 1, 1, 2 ] ] );;
gap> TransformationOp( Elements( S )[1], S, OnRight );
Transformation( [ 1, 1, 1 ] )
gap> TransformationOp( Elements( S )[3], S, OnRight );
Transformation( [ 1, 1, 2 ] )
]]></Example>
    </Description>
  </ManSection>

  <ManSection>
    <Oper Name="TransformationNumber" Arg="m, n"/>
    <Oper Name="NumberTransformation" Arg="f[, n]"/>
    <Returns>A transformation or a number.</Returns>
    <Description>
      These functions implement a bijection from the transformations with
      degree at most <A>n</A> to the numbers
      <C>[ 1 .. <A>n</A> ^ <A>n</A> ]</C>.
      <P/>

      More precisely, if <A>m</A> and <A>n</A> are positive integers
      such that <A>m</A> is at most <C><A>n</A> ^ <A>n</A></C>, then
      <C>TransformationNumber</C> returns the <A>m</A>th transformation
      with degree at most <A>n</A>.
      <P/>

      If <A>f</A> is a transformation and <A>n</A> is a positive
      integer, which is greater than or equal to the degree of <A>f</A>,
      then <C>NumberTransformation</C> returns the number in <C>[ 1 ..
        <A>n</A> ^ <A>n</A> ]</C> that corresponds to <A>f</A>. If the
      optional second argument <A>n</A> is not specified, then the
      degree of <A>f</A> is used by default.
      <Example><![CDATA[
gap> f := Transformation( [ 3, 3, 5, 3, 3 ] );;
gap> NumberTransformation( f, 5 );
1613
gap> NumberTransformation( f, 10 );
2242256790
gap> TransformationNumber( 2242256790, 10 );
Transformation( [ 3, 3, 5, 3, 3 ] )
gap> TransformationNumber( 1613, 5 );
Transformation( [ 3, 3, 5, 3, 3 ] )]]></Example>
    </Description>
  </ManSection>


<!-- *************************************************************** -->

  <ManSection><Heading>RandomTransformation</Heading>
    <Oper Name="RandomTransformation" Arg="n"/>
    <Returns>A random transformation.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then
      <C>RandomTransformation</C> returns a random transformation with
      degree at most <A>n</A>.
      <Log>
gap> RandomTransformation( 6 );
Transformation( [ 2, 1, 2, 1, 1, 2 ] )</Log>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

 <ManSection>
   <Var Name="IdentityTransformation"/>
   <Description>
     This variable is bound to the identity transformation,
     which has degree <C>0</C>.
     <Example><![CDATA[
gap> IdentityTransformation;
IdentityTransformation
]]></Example>
   </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Oper Name="ConstantTransformation" Arg="m, n"/>
    <Returns>A transformation.</Returns>
    <Description>
      This function returns a constant transformation <C>f</C> such that
      <C>i ^ f = <A>n</A></C> for all <C>i</C> less than or equal to
      <A>m</A>, when <A>n</A> and <A>m</A> are positive integers.
    <Example><![CDATA[
gap> ConstantTransformation( 5, 1 );
Transformation( [ 1, 1, 1, 1, 1 ] )
gap> ConstantTransformation( 6, 4 );
Transformation( [ 4, 4, 4, 4, 4, 4 ] )
]]></Example>
    </Description>
  </ManSection>
</Section>

<!-- *************************************************************** -->

<Section Label="sect:ChangingRepTransformations">
  <Heading>Changing the representation of a transformation</Heading>
  It is possible that a transformation in &GAP; can be represented as
  another type of object, or that another type of &GAP; object can be
  represented as a transformation.
  <P/>

  The operations <Ref Attr="AsPermutation"/> and <Ref Meth="AsPartialPerm"
  Label="for a transformation and a positive integer"/> can be used to
  convert transformations into permutations or partial permutations,
  where appropriate.  In this section we describe functions for
  converting other types of objects into transformations.

  <ManSection>
  <Attr Name="AsTransformation" Arg="f[, n]"/>
  <Returns>A transformation.</Returns>
  <Description>
  <C>AsTransformation</C>
  returns the permutation, transformation, partial permutation or binary
  relation <A>f</A> as a transformation.

  <List>

    <Mark>for permutations</Mark>
    <Item>
      If <A>f</A> is a permutation and <A>n</A> is a non-negative
      integer, then <C>AsTransformation( <A>f</A>, <A>n</A> )</C>
      returns the transformation <C>g</C> such that <C>i ^ g = i ^ f</C>
      for all <C>i</C> in the range <C>[ 1 .. <A>n</A> ]</C>.
      <P/>

      If no non-negative integer <A>n</A> is specified, then the largest
      moved point of <A>f</A> is used as the value for <A>n</A>; see
      <Ref Attr="LargestMovedPoint" Label="for a permutation"/>.
    </Item>

    <Mark>for transformations</Mark>
    <Item>
      If <A>f</A> is a transformation and <A>n</A> is a non-negative
      integer less than the degree of <A>f</A> such that <A>f</A> is a
      transformation of <C>[ 1 .. <A>n</A> ]</C>, then
      <C>AsTransformation</C> returns the restriction of <A>f</A> to
      <C>[ 1 .. <A>n</A> ]</C>.
      <P/>

      If <A>f</A> is a transformation and <A>n</A> is not specified or
      is greater than or equal to the degree of <A>f</A>, then
      <A>f</A> is returned.
    </Item>

    <Mark>for partial permutations</Mark>
    <Item>
      A partial permutation <A>f</A> can be converted into a
      transformation <C>g</C> as follows. The degree <C>m</C> of
      <C>g</C> is equal to the maximum of <A>n</A>, the largest moved
      point of <A>f</A> plus <C>1</C>, and the largest image of a moved
      point plus <C>1</C>.  The transformation <C>g</C> agrees with
      <A>f</A> on the domain of <A>f</A> and maps the points in
      <C>[ 1 .. m ]</C>, which are not in the domain of <A>f</A> to
      <C>n</C>, i.e.  <C>i ^ g = i ^ <A>f</A></C> for all <C>i</C> in the
      domain of <A>f</A>, <C>i ^ g = n</C> for all <C>i</C> in
      <C>[ 1 .. n ]</C>, and <C>i ^ g = i</C> for all <C>i</C> greater
      than <A>n</A>.  <C>AsTransformation( <A>f</A> )</C> returns the
      transformation <C>g</C> defined in the previous sentences. <P/>

      If the optional argument <A>n</A> is not present, then the default
      value of the maximum of the largest moved point and the largest
      image of a moved point of <A>f</A> plus <C>1</C> is used.
    </Item>

    <Mark>for binary relations</Mark>
    <Item>
      In the case that <A>f</A> is a binary relation, which defines
      a transformation, <C>AsTransformation</C> returns that
      transformation.
    </Item>
  </List>
  <Example><![CDATA[
gap> f := Transformation( [ 3, 5, 3, 4, 1, 2 ] );;
gap> AsTransformation( f, 5 );
Transformation( [ 3, 5, 3, 4, 1 ] )
gap> AsTransformation( f, 10 );
Transformation( [ 3, 5, 3, 4, 1, 2 ] )
gap> AsTransformation( (1,3)(2,4) );
Transformation( [ 3, 4, 1, 2 ] )
gap> AsTransformation( (1,3)(2,4), 10 );
Transformation( [ 3, 4, 1, 2 ] )
gap> f := PartialPerm( [ 1, 2, 3, 4, 5, 6 ], [ 6, 7, 1, 4, 3, 2 ] );
[5,3,1,6,2,7](4)
gap> AsTransformation( f, 11 );
Transformation( [ 6, 7, 1, 4, 3, 2, 11, 11, 11, 11, 11 ] )
gap> AsPartialPerm( last, DomainOfPartialPerm( f ) );
[5,3,1,6,2,7](4)
gap> AsTransformation( f, 14 );
Transformation( [ 6, 7, 1, 4, 3, 2, 14, 14, 14, 14, 14, 14, 14, 14 ] )
gap> AsPartialPerm( last, DomainOfPartialPerm( f ) );
[5,3,1,6,2,7](4)
gap> AsTransformation( f );
Transformation( [ 6, 7, 1, 4, 3, 2, 8, 8 ] )
gap> AsTransformation( Transformation( [ 1, 1, 2 ] ), 0 );
IdentityTransformation
]]></Example>
  </Description>
  </ManSection>

  <ManSection>
  <Func Name="RestrictedTransformation" Arg="f, list"/>
  <Returns>A transformation.</Returns>
  <Description>
    <C>RestrictedTransformation</C> returns the new transformation
    <C>g</C> such that <C> i ^ g = i ^ <A>f</A></C> for all <C>i</C> in
    <A>list</A> and such that <C>i ^ g = i</C> for all <C>i</C> not in
    <A>list</A>.
    <P/>

    <Example><![CDATA[
gap> f := Transformation( [ 2, 10, 5, 9, 10, 9, 6, 3, 8, 4, 6, 5 ] );;
gap> RestrictedTransformation( f, [ 1, 2, 3, 10, 11, 12 ] );
Transformation( [ 2, 10, 5, 4, 5, 6, 7, 8, 9, 4, 6, 5 ] )]]></Example>
  </Description>
</ManSection>

  <ManSection>
  <Func Name="PermutationOfImage" Arg="f"/>
  <Returns>A permutation or <K>fail</K>.</Returns>
  <Description>
    If the transformation <A>f</A> is a permutation of the points in its
    image, then <C>PermutationOfImage</C> returns this permutation. If
    <A>f</A> does not permute its image, then <K>fail</K> is returned.
    <P/>

    If <A>f</A> happens to be a permutation, then
    <C>PermutationOfImage</C> with argument <A>f</A> returns the same
    value as <C>AsPermutation</C> with argument <A>f</A>.

  <Example><![CDATA[
gap> f := Transformation( [ 5, 8, 3, 5, 8, 6, 2, 2, 7, 8 ] );;
gap> PermutationOfImage( f );
fail
gap> f := Transformation( [ 8, 2, 10, 2, 4, 4, 7, 6, 9, 10 ] );;
gap> PermutationOfImage( f );
fail
gap> f := Transformation( [ 1, 3, 6, 6, 2, 10, 2, 3, 10, 5 ] );;
gap> PermutationOfImage( f );
(2,3,6,10,5)
gap> f := Transformation( [ 5, 2, 8, 4, 1, 8, 10, 3, 5, 7 ] );;
gap> PermutationOfImage( f );
(1,5)(3,8)(7,10)
]]></Example>
  </Description>
  </ManSection>
</Section>

<!-- *************************************************************** -->
<!-- *************************************************************** -->

<Section Label="sect:OperatorsTransformations">
  <Heading>Operators for transformations</Heading>

<ManSection>
  <Meth Name="\^" Arg="i, f" Label="for a positive integer and a transformation"/>
  <Description>
      <C><A>i</A> ^ <A>f</A></C>
      returns the image of the positive integer <A>i</A> under the
      transformation <A>f</A>.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="\^" Arg="f, g" Label="for a transformation and a permutation"/>
  <Description>
      <C><A>f</A> ^ <A>g</A></C>
      returns <C><A>g</A> ^ -1 * <A>f</A> * <A>g</A></C> when
      <A>f</A> is a transformation and <A>g</A> is a permutation
      <Ref Oper="\^"/>.
      This operation requires essentially the same number of steps as
      multiplying a transformation by a permutation, which is
      approximately one third of the number required to first invert
      <A>g</A>, take the product with <A>f</A>, and then the product
      with <A>g</A>.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="\*" Arg="f, g" Label="for transformations"/>
  <Description>
      <C><A>f</A> * <A>g</A></C>
      returns the composition of <A>f</A> and <A>g</A> when <A>f</A> and
      <A>g</A> are transformations or permutations. The product of a
      permutation and a transformation is returned as a transformation.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="\/" Arg="f, g" Label="for a transformation and a permutation"/>
  <Description>
      <C><A>f</A> / <A>g</A></C>
      returns <C><A>f</A> * <A>g</A> ^ -1</C> when <A>f</A> is a
      transformation and <A>g</A> is a permutation.  This operation
      requires essentially the same number of steps as multiplying a
      transformation by a permutation, which is approximately half the
      number required to first invert <A>g</A> and then take the product
      with <A>f</A>.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="LeftQuotient" Arg="g, f" Label="for a permutation and transformation"/>
  <Description>
      returns <C><A>g</A> ^ -1 * <A>f</A></C> when <A>f</A> is a
      transformation and <A>g</A> is a permutation. This operation uses
      essentially the same number of steps as multiplying a
      transformation by a permutation, which is approximately half the
      number required to first invert <A>g</A> and then take the product
      with <A>f</A>.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="\&lt;" Arg="i, f" Label="for transformations"/>
  <Description>
      <Index Subkey="for transformations">smaller</Index>
      <C><A>f</A> &lt; <A>g</A></C>
      returns <K>true</K> if the image list of <A>f</A> is
      lexicographically less than the image list of <A>g</A> and
      <K>false</K> if it is not.
  </Description>
</ManSection>

<ManSection>
  <Meth Name="\=" Arg="f, g" Label="for transformations"/>
  <Description>
      <Index Subkey="for transformations">equality</Index>
      <C><A>f</A> = <A>g</A></C>
      returns <K>true</K> if the transformation <A>f</A> equals the
      transformation <A>g</A> and returns <K>false</K> if it does not.
  </Description>
</ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Oper Name="PermLeftQuoTransformation" Arg="f, g"/>
    <Func Name="PermLeftQuoTransformationNC" Arg="f, g"/>
    <Returns>A permutation.</Returns>
    <Description>
      Returns the permutation on the image set of <A>f</A> induced by
      <C><A>f</A> ^ -1 * <A>g</A></C> when the transformations <A>f</A>
      and <A>g</A> have equal kernel and image set.
      <P/>

      <C>PermLeftQuoTransformation</C> verifies that <A>f</A> and
      <A>g</A> have equal kernels and image sets, and returns an error
      if they do not.  <C>PermLeftQuoTransformationNC</C> does no
      checks.
      <Example><![CDATA[
gap> f := Transformation( [ 5, 6, 7, 1, 4, 3, 2, 7 ] );;
gap> g := Transformation( [ 5, 7, 1, 6, 4, 3, 2, 1 ] );;
gap> PermLeftQuoTransformation( f, g );
(1,6,7)
gap> PermLeftQuoTransformation( g, f );
(1,7,6)
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

  <ManSection>
    <Func Name="IsInjectiveListTrans" Arg="list, obj"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      The argument <A>obj</A> should be a transformation or the list of
      images of a transformation and <A>list</A> should be a list of
      positive integers. <C>IsInjectiveListTrans</C> checks if
      <A>obj</A> is injective on <A>list</A>.
      <P/>

      More precisely, if <A>obj</A> is a transformation, then we define
      <C>f := <A>obj</A></C> and if <A>obj</A> is the image list of a
      transformation we define <C>f := Transformation( <A>obj</A> )</C>.
      <C>IsInjectiveListTrans</C> returns <K>true</K> if <C>f</C> is
      injective on <A>list</A> and <K>false</K> if it is not. If
      <A>list</A> is not duplicate free, then <K>false</K> is returned.
      <P/>
      <Example><![CDATA[
gap> f := Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] );;
gap> IsInjectiveListTrans( [ 1, 5 ], f );
true
gap> IsInjectiveListTrans( [ 5, 1 ], f );
true
gap> IsInjectiveListTrans( [ 5, 1, 5, 1, 1, ], f );
false
gap> IsInjectiveListTrans( [ 5, 1, 2, 3 ], [ 1, 2, 3, 4, 5 ] );
true
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Oper Name="ComponentTransformationInt" Arg="f, n" />
  <Returns>A list of positive integers.</Returns>
  <Description>
    If <A>f</A> is a transformation and <A>n</A> is a positive integer,
    then <C>ComponentTransformationInt</C> returns those elements
    <C>i</C> such that <C><A>n</A> ^ <A>f</A> ^ j = i</C> for some
    positive integer <C>j</C>, i.e. the elements of the component of
    <A>f</A> containing <A>n</A> that can be obtained by applying powers
    of <A>f</A> to <A>n</A>.
<Example><![CDATA[
gap> f := Transformation( [ 6, 2, 8, 4, 7, 5, 8, 3, 5, 8 ] );;
gap> ComponentTransformationInt( f, 1 );
[ 1, 6, 5, 7, 8, 3 ]
gap> ComponentTransformationInt( f, 12 );
[ 12 ]
gap> ComponentTransformationInt( f, 5 );
[ 5, 7, 8, 3 ]
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

  <ManSection>
    <Oper Name="PreImagesOfTransformation" Arg="f, n"/>
    <Returns>A set of positive integers.</Returns>
    <Description>
      Returns the preimages of the positive integer <A>n</A> under the
      transformation <A>f</A>, i.e. the positive integers <C>i</C> such
      that <C>i ^ <A>f</A> = n</C>.

      <Example><![CDATA[
gap> f := Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] );;
gap> PreImagesOfTransformation( f, 1 );
[ 8, 9 ]
gap> PreImagesOfTransformation( f, 3 );
[  ]
gap> PreImagesOfTransformation( f, 100 );
[ 100 ]
]]></Example>
</Description>
</ManSection>

</Section>

<!-- *************************************************************** -->

<Section Label="sect:AttributesTransformations">
  <Heading>Attributes for transformations</Heading>
  In this section we describe the functions available in &GAP; for finding
  various properties and attributes of transformations.

  <ManSection>
    <Func Name="DegreeOfTransformation" Arg="f"/>
    <Attr Name="DegreeOfTransformationCollection" Arg="coll"/>
    <Returns>A positive integer.</Returns>
    <Description>
      The <E>degree</E> of a transformation <A>f</A> is the largest
      value such that <C>n ^ <A>f</A> &lt;> n</C> or
      <C>i ^ <A>f</A> = n</C> for some <C>i &lt;> n</C>.  Equivalently,
      the degree of a transformation is the least value <C>n</C> such
      that <C>[ n + 1, n + 2, ... ]</C> is fixed pointwise by <A>f</A>.
      <P/>

      The degree of a collection of transformations <A>coll</A> is
      the maximum degree of any transformation in <A>coll</A>.
      <Example><![CDATA[
gap> DegreeOfTransformation( IdentityTransformation );
0
gap> DegreeOfTransformationCollection(
> [ Transformation( [ 1, 3, 4, 1 ] ),
>   Transformation( [ 3, 1, 1, 3, 4 ] ),
>   Transformation( [ 2, 4, 1, 2 ] ) ] );
5
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Oper Name="ImageListOfTransformation" Arg="f[, n]"/>
    <Oper Name="ListTransformation" Arg="f[, n]"/>
    <Returns>The list of images of a transformation.</Returns>
    <Description>
      Returns the list of images of <C>[ 1 .. <A>n</A> ]</C> under the
      transformation <A>f</A>, which is
      <C>[ 1 ^ <A>f</A> .. <A>n</A> ^ <A>f</A> ]</C>.  If the optional
      second argument <A>n</A> is not present, then the degree of
      <A>f</A> is used by default.
      <P/>

      This is the analogue for transformations of <Ref Func="ListPerm"/>
      for permutations.
      <Example><![CDATA[
gap> f := Transformation( [ 2 ,3, 4, 2, 4 ] );;
gap> ImageListOfTransformation( f );
[ 2, 3, 4, 2, 4 ]
gap> ImageListOfTransformation( f, 10 );
[ 2, 3, 4, 2, 4, 6, 7, 8, 9, 10 ]
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Attr Name="ImageSetOfTransformation" Arg="f[, n]"/>
    <Returns>The set of images of the transformation.</Returns>
    <Description>
      Returns the set of points in the list of images of
      <C>[ 1 .. <A>n</A> ]</C> under <A>f</A>, i.e. the sorted list of
      images with duplicates removed.  If the optional second argument
      <A>n</A> is not given, then the degree of <A>f</A> is used.
      <P/>

      <Example><![CDATA[
gap> f := Transformation( [ 5, 6, 7, 1, 4, 3, 2, 7 ] );;
gap> ImageSetOfTransformation( f );
[ 1, 2, 3, 4, 5, 6, 7 ]
gap> ImageSetOfTransformation( f, 10 );
[ 1, 2, 3, 4, 5, 6, 7, 9, 10 ]
]]></Example>
</Description>
</ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Attr Name="RankOfTransformation" Arg="f[, n]"
      Label="for a transformation and a positive integer"/>
    <Attr Name="RankOfTransformation" Arg="f[, list]"
      Label="for a transformation and a list"/>
    <Returns>The rank of a transformation.</Returns>
    <Description>
      When the arguments are a transformation <A>f</A> and a positive
      integer <A>n</A>, <C>RankOfTransformation</C> returns the size of
      the set of images of the transformation <A>f</A> in the range
      <C>[ 1 .. <A>n</A> ]</C>.  If the optional second argument
      <A>n</A> is not specified, then the degree of <A>f</A> is used.
      <P/>

      When the arguments are a transformation <A>f</A> and a list
      <A>list</A> of positive integers, this function returns the size
      of the set of images of the transformation <A>f</A> on
      <A>list</A>.

      <Example><![CDATA[
gap> f := Transformation( [ 8, 5, 8, 2, 2, 8, 4, 7, 3, 1 ] );;
gap> ImageSetOfTransformation( f );
[ 1, 2, 3, 4, 5, 7, 8 ]
gap> RankOfTransformation( f );
7
gap> RankOfTransformation( f, 100 );
97
gap> RankOfTransformation( f, [ 2, 5, 8 ] );
3
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Attr Name="MovedPoints" Arg="f" Label="for a transformation"/>
    <Attr Name="MovedPoints" Arg="coll"
      Label="for a transformation coll"/>
    <Returns>A set of positive integers.</Returns>
    <Description>
      When the argument is a transformation, <C>MovedPoints</C> returns
      the set of positive integers <C>i</C> such that
      <C>i ^ <A>f</A> &lt;> i</C>.
      <P/>

      <C>MovedPoints</C> returns the set of points moved by some element of
      the collection of transformations <A>coll</A>.
      <Example><![CDATA[
gap> f := Transformation( [ 6, 10, 1, 4, 6, 5, 1, 2, 3, 3 ] );;
gap> MovedPoints( f );
[ 1, 2, 3, 5, 6, 7, 8, 9, 10 ]
gap> f := IdentityTransformation;
IdentityTransformation
gap> MovedPoints( f );
[  ]
]]></Example>
    </Description>
  </ManSection>

<!-- *************************************************************** -->

  <ManSection>
    <Attr Name="NrMovedPoints" Arg="f" Label="for a transformation"/>
    <Attr Name="NrMovedPoints" Arg="coll"
      Label="for a transformation coll"/>
    <Returns>A positive integer.</Returns>
    <Description>
      When the argument is a transformation,<C>NrMovedPoints</C> returns
      the number of positive integers <C>i</C> such that
      <C>i ^ <A>f</A> &lt;> i</C>.
      <P/>

      <C>MovedPoints</C> returns the number of points which are moved by at
      least one element of the collection of transformations <A>coll</A>.
      <Example><![CDATA[
gap> f := Transformation( [ 7, 1, 4, 3, 2, 7, 7, 6, 6, 5 ] );;
gap> NrMovedPoints( f );
9
gap> NrMovedPoints( IdentityTransformation );
0
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="SmallestMovedPoint" Arg="f" Label="for a transformation"/>
  <Meth Name="SmallestMovedPoint" Arg="coll" Label="for a transformation coll"/>
  <Returns>A positive integer or <K>infinity</K>.</Returns>
  <Description>
    <C>SmallestMovedPoint</C> returns the smallest  positive integer
    <C>i</C> such that <C>i ^ <A>f</A> &lt;> i</C> if such an <C>i</C>
    exists.  If <A>f</A> is the identity transformation, then
    <K>infinity</K> is returned.
    <P/>

    If the argument is a collection of transformations <A>coll</A>, then
    the smallest point which is moved by at least one element of
    <A>coll</A> is returned, if such a point exists.  If <A>coll</A>
    only contains identity transformations, then
    <C>SmallestMovedPoint</C> returns <K>infinity</K>.
    <Example><![CDATA[
gap> S := FullTransformationSemigroup( 5 );
<full transformation monoid of degree 5>
gap> SmallestMovedPoint( S );
1
gap> S := Semigroup( IdentityTransformation );
<trivial transformation group of degree 0 with 1 generator>
gap> SmallestMovedPoint( S );
infinity
gap> f := Transformation( [ 1, 2, 3, 6, 6, 6 ] );;
gap> SmallestMovedPoint( f );
4
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="LargestMovedPoint" Arg="f"
    Label="for a transformation"/>
  <Meth Name="LargestMovedPoint" Arg="coll"
    Label="for a transformation coll"/>
  <Returns>A positive integer.</Returns>
  <Description>
    <C>LargestMovedPoint</C> returns the largest positive integers
    <C>i</C> such that <C>i ^ <A>f</A> &lt;> i</C> if such an <C>i</C>
    exists.  If <A>f</A> is the identity transformation, then <C>0</C>
    is returned.
    <P/>

    If the argument is a collection of transformations <A>coll</A>, then the
    largest point which is moved by at least one element of <A>coll</A> is
    returned, if such a point exists.  If <A>coll</A> only contains identity
    transformations, then <C>LargestMovedPoint</C> returns <C>0</C>.

    <Example><![CDATA[
gap> S := FullTransformationSemigroup( 5 );
<full transformation monoid of degree 5>
gap> LargestMovedPoint( S );
5
gap> S := Semigroup( IdentityTransformation );
<trivial transformation group of degree 0 with 1 generator>
gap> LargestMovedPoint( S );
0
gap> f := Transformation( [ 1, 2, 3, 6, 6, 6 ] );;
gap> LargestMovedPoint( f );
5
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="SmallestImageOfMovedPoint" Arg="f"
    Label="for a transformation"/>
  <Meth Name="SmallestImageOfMovedPoint" Arg="coll"
    Label="for a transformation coll"/>
  <Returns>A positive integer or <K>infinity</K>.</Returns>
  <Description>
    <C>SmallestImageOfMovedPoint</C> returns the smallest positive
    integer <C>i ^ <A>f</A></C> such that <C>i ^ <A>f</A> &lt;> i</C> if
    such an <C>i</C> exists.  If <A>f</A> is the identity
    transformation, then <K>infinity</K> is returned.<P/>

    If the argument is a collection of transformations <A>coll</A>, then
    the smallest integer which is the image a point moved by at least
    one element of <A>coll</A> is returned, if such a point exists.  If
    <A>coll</A> only contains identity transformations, then
    <C>SmallestImageOfMovedPoint</C> returns <K>infinity</K>.

    <Example><![CDATA[
gap> S := FullTransformationSemigroup( 5 );
<full transformation monoid of degree 5>
gap> SmallestImageOfMovedPoint( S );
1
gap> S := Semigroup( IdentityTransformation );
<trivial transformation group of degree 0 with 1 generator>
gap> SmallestImageOfMovedPoint( S );
infinity
gap> f := Transformation( [ 1, 2, 3, 6, 6, 6 ] );;
gap> SmallestImageOfMovedPoint( f );
6
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="LargestImageOfMovedPoint" Arg="f"
    Label="for a transformation"/>
  <Meth Name="LargestImageOfMovedPoint" Arg="coll"
    Label="for a transformation coll"/>
  <Returns>A positive integer.</Returns>
  <Description>
    <C>LargestImageOfMovedPoint</C> returns the largest positive integer
    <C>i ^ <A>f</A></C> such that <C>i ^ <A>f</A> &lt;> i</C> if such an
    <C>i</C> exists.  If <A>f</A> is the identity transformation, then
    <C>0</C> is returned.
    <P/>

    If the argument is a collection of transformations <A>coll</A>, then
    the largest integer which is the image a point moved by at least one
    element of <A>coll</A> is returned, if such a point exists.  If
    <A>coll</A> only contains identity transformations, then
    <C>LargestImageOfMovedPoint</C> returns <C>0</C>.
    <Example><![CDATA[
gap> S := FullTransformationSemigroup( 5 );
<full transformation monoid of degree 5>
gap> LargestImageOfMovedPoint( S );
5
gap> S := Semigroup( IdentityTransformation );;
gap> LargestImageOfMovedPoint( S );
0
gap> f := Transformation( [ 1, 2, 3, 6, 6, 6 ] );;
gap> LargestImageOfMovedPoint( f );
6
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

  <ManSection>
    <Attr Name="FlatKernelOfTransformation" Arg="f[, n]"/>
    <Returns>The flat kernel of a transformation.</Returns>
    <Description>
      If the kernel classes of the transformation <A>f</A> on
      <C>[ 1 .. <A>n</A> ]</C> are <M>K_1, \dots, K_r</M>, then
      <C>FlatKernelOfTransformation</C> returns a list <C>L</C> such
      that <C>L[i] = j</C> for all <C>i</C> in <M>K_j</M>.  For a given
      transformation and positive integer <A>n</A>, there is a unique
      such list.
      <P/>

      If the optional second argument <A>n</A> is not present, then the
      degree of <A>f</A> is used by default.
      <Example><![CDATA[
gap> f := Transformation( [ 10, 3, 7, 10, 1, 5, 9, 2, 6, 10 ] );;
gap> FlatKernelOfTransformation( f );
[ 1, 2, 3, 1, 4, 5, 6, 7, 8, 1 ]
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

  <ManSection>
    <Attr Name="KernelOfTransformation" Arg="f[, n, bool]"/>
    <Returns>The kernel of a transformation.</Returns>
    <Description>
      When the arguments are a transformation <A>f</A>, a positive
      integer <A>n</A>, and <K>true</K>, <C>KernelOfTransformation</C>
      returns the kernel of the transformation <A>f</A> on
      <C>[ 1 .. <A>n</A> ]</C> as a set of sets of positive integers. If
      the argument <A>bool</A> is <K>false</K>, then only the
      non-singleton classes are returned. <P/>

      The second and third arguments are optional, the default values
      are the degree of <A>f</A> and <K>true</K>.
      <Example><![CDATA[
gap> f := Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 11, 1, 12, 5 ] );;
gap> KernelOfTransformation( f );
[ [ 1, 4 ], [ 2, 5 ], [ 3 ], [ 6, 7 ], [ 8, 10 ], [ 9 ], [ 11 ],
  [ 12 ] ]
gap> KernelOfTransformation( f, 5 );
[ [ 1, 4 ], [ 2, 5 ], [ 3 ] ]
gap> KernelOfTransformation( f, 5, false );
[ [ 1, 4 ], [ 2, 5 ] ]
gap> KernelOfTransformation( f, 15 );
[ [ 1, 4 ], [ 2, 5 ], [ 3 ], [ 6, 7 ], [ 8, 10 ], [ 9 ], [ 11 ],
  [ 12 ], [ 13 ], [ 14 ], [ 15 ] ]
gap> KernelOfTransformation( f, false );
[ [ 1, 4 ], [ 2, 5 ], [ 6, 7 ], [ 8, 10 ] ]
]]></Example>
  </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Func Name="InverseOfTransformation" Arg="f"/>
  <Returns>A transformation.</Returns>
  <Description>
    <C>InverseOfTransformation</C> returns a semigroup inverse of the
    transformation <A>f</A> in the full transformation semigroup. An
    <E>inverse</E> of <A>f</A> is any transformation <C>g</C> such that
    <C><A>f</A> * g * <A>f</A> = <A>f</A></C> and
    <C>g * <A>f</A> * g = g</C>.  Every transformation has at least one
    inverse.
    <Example><![CDATA[
gap> f := Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] );;
gap> g := InverseOfTransformation( f );
Transformation( [ 8, 1, 1, 1, 10, 2, 3, 1, 6, 1 ] )
gap> f * g * f;
Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] )
gap> g * f * g;
Transformation( [ 8, 1, 1, 1, 10, 2, 3, 1, 6, 1 ] )
]]></Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Inverse" Arg="f" Label="for a transformation"/>
  <Returns>A transformation.</Returns>
  <Description>
    If the transformation <A>f</A> is a bijection, then <C>Inverse</C> or
    <C><A>f</A> ^ -1</C> returns the inverse of <A>f</A>.
    If <A>f</A> is not a bijection, then <K>fail</K> is returned.
    <Example><![CDATA[
gap> Transformation( [ 3, 8, 12, 1, 11, 9, 9, 4, 10, 5, 10, 6 ] ) ^ -1;
fail
gap> Transformation( [ 2, 3, 1 ] ) ^ -1;
Transformation( [ 3, 1, 2 ] )
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

  <ManSection>
    <Func Name="IndexPeriodOfTransformation" Arg="f"/>
    <Returns>A pair of positive integers.</Returns>
    <Description>
      Returns the least positive integers <C>m</C> and <C>r</C> such
      that <C><A>f</A> ^ (m + r) = <A>f</A> ^ m</C>, which are  known as
      the <E>index</E> and <E>period</E> of the transformation <A>f</A>.
      <Example><![CDATA[
gap> f := Transformation( [ 3, 4, 4, 6, 1, 3, 3, 7, 1 ] );;
gap> IndexPeriodOfTransformation( f );
[ 2, 3 ]
gap> f ^ 2 = f ^ 5;
true
gap> IndexPeriodOfTransformation( IdentityTransformation );
[ 1, 1 ]
gap> IndexPeriodOfTransformation( Transformation( [ 1, 2, 1 ] ) );
[ 1, 1 ]
gap> IndexPeriodOfTransformation( Transformation( [ 1, 2, 3 ] ) );
[ 1, 1 ]
gap> IndexPeriodOfTransformation( Transformation( [ 1, 3, 2 ] ) );
[ 1, 2 ]
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="SmallestIdempotentPower" Arg="f"
    Label="for a transformation"/>
  <Returns>A positive integer.</Returns>
  <Description>
      This function returns the least positive integer <C>n</C> such
      that the transformation <C><A>f</A> ^ n</C> is an idempotent.  The
      smallest idempotent power of <A>f</A> is the least multiple of the
      period of <A>f</A> that is greater than or equal to the index of
      <A>f</A>; see <Ref Func="IndexPeriodOfTransformation"/>.

      <Example><![CDATA[
gap> f := Transformation( [ 6, 7, 4, 1, 7, 4, 6, 1, 3, 4 ] );;
gap> SmallestIdempotentPower( f );
3
gap> f := Transformation( [ 6, 6, 6, 2, 7, 1, 5, 3, 10, 6 ] );;
gap> SmallestIdempotentPower( f );
2
]]></Example>
    </Description>
  </ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="ComponentsOfTransformation" Arg="f" />
  <Returns>A list of lists of positive integers.</Returns>
  <Description>
    <C>ComponentsOfTransformation</C> returns a list of the components
    of the transformation <A>f</A>.  Each component is a subset of
    <C>[ 1 .. DegreeOfTransformation( f ) ]</C>, and the union of the
    components is <C>[ 1 .. DegreeOfTransformation( f ) ]</C>.

    <Example><![CDATA[
gap> f := Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] );
Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] )
gap> ComponentsOfTransformation( f );
[ [ 1, 6, 4, 9 ], [ 2, 12, 3, 11, 5, 7, 10 ], [ 8 ] ]
gap> f := AsTransformation( (1,8,2,4,11,5,10)(3,7)(9,12) );
Transformation( [ 8, 4, 7, 11, 10, 6, 3, 2, 12, 1, 5, 9 ] )
gap> ComponentsOfTransformation( f );
[ [ 1, 8, 2, 4, 11, 5, 10 ], [ 3, 7 ], [ 6 ], [ 9, 12 ] ]]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="NrComponentsOfTransformation" Arg="f" />
  <Returns>A positive integer.</Returns>
  <Description>
    <C>NrComponentsOfTransformation</C> returns the number of components
    of the transformation <A>f</A> on the range
    <C>[ 1 .. DegreeOfTransformation( <A>f</A> ) ]</C>.

    <Example><![CDATA[
gap> f := Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] );
Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] )
gap> NrComponentsOfTransformation( f );
3
gap> f := AsTransformation( (1,8,2,4,11,5,10)(3,7)(9,12) );
Transformation( [ 8, 4, 7, 11, 10, 6, 3, 2, 12, 1, 5, 9 ] )
gap> NrComponentsOfTransformation( f );
4
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="ComponentRepsOfTransformation" Arg="f" />
  <Returns>A list of lists of positive integers.</Returns>
  <Description>
    <C>ComponentRepsOfTransformation</C> returns the representatives, in
    the following sense, of the components of the transformation
    <A>f</A>.  For every <C>i</C> in
    <C>[ 1 .. DegreeOfTransformation( f ) ]</C> there exists a
    representative <C>j</C> and a positive integer <C>k</C> such that
    <C>i ^ (<A>f</A> ^ k) = j</C>. The representatives returned by
    <C>ComponentRepsOfTransformation</C> are partitioned according to
    the component they belong to.  <C>ComponentRepsOfTransformation</C>
    returns the least number of representatives.
    <Example><![CDATA[
gap> f := Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] );
Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] )
gap> ComponentRepsOfTransformation( f );
[ [ 3, 10 ], [ 9 ], [ 8 ] ]
gap> f := AsTransformation( (1,8,2,4,11,5,10)(3,7)(9,12) );
Transformation( [ 8, 4, 7, 11, 10, 6, 3, 2, 12, 1, 5, 9 ] )
gap> ComponentRepsOfTransformation( f );
[ [ 1 ], [ 3 ], [ 6 ], [ 9 ] ]
]]></Example>
  </Description>
</ManSection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="CyclesOfTransformation" Arg="f[, list]" />
  <Returns>A list of lists of positive integers.</Returns>
  <Description>
    When the arguments of this function are a transformation <A>f</A>
    and a list <A>list</A>, it returns a list of the cycles of the
    components of <A>f</A> containing any element of <A>list</A>.<P/>

    If the optional second argument is not present, then the range
    <C>[ 1 .. DegreeOfTransformation( <A>f</A> ) ]</C> is used as the
    default value for <A>list</A>.
    <Example><![CDATA[
gap> f := Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] );
Transformation( [ 6, 12, 11, 1, 7, 6, 2, 8, 4, 7, 5, 12 ] )
gap> CyclesOfTransformation( f );
[ [ 6 ], [ 12 ], [ 8 ] ]
gap> CyclesOfTransformation( f, [ 1, 2, 4 ] );
[ [ 6 ], [ 12 ] ]
gap> CyclesOfTransformation( f, [ 1 .. 17 ] );
[ [ 6 ], [ 12 ], [ 8 ], [ 13 ], [ 14 ], [ 15 ], [ 16 ], [ 17 ] ]
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Oper Name="CycleTransformationInt" Arg="f, n" />
  <Returns>A list of positive integers.</Returns>
  <Description>
    If <A>f</A> is a transformation and <A>n</A> is a positive
    integer, then <C>CycleTransformationInt</C> returns the cycle of the
    component of <A>f</A> containing <A>n</A>.
    <Example><![CDATA[
gap> f := Transformation( [ 6, 2, 8, 4, 7, 5, 8, 3, 5, 8 ] );;
gap> CycleTransformationInt( f, 1 );
[ 8, 3 ]
gap> CycleTransformationInt( f, 12 );
[ 12 ]
gap> CycleTransformationInt( f, 5 );
[ 8, 3 ]
]]></Example>
  </Description>
</ManSection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<ManSection>
  <Attr Name="LeftOne" Arg="f" Label="for a transformation"/>
  <Attr Name="RightOne" Arg="f" Label="for a transformation"/>
  <Returns>A transformation.</Returns>
  <Description>
    <C>LeftOne</C> returns an idempotent transformation <C>e</C> such that
    the kernel (with respect to the degree of <A>f</A>) of <C>e</C>
    equals the kernel of the transformation <A>f</A> and
    <C>e * <A>f</A> = f</C>.
    <P/>

    <C>RightOne</C> returns an idempotent transformation <C>e</C> such
    that the image set (with respect to the degree of <A>f</A>) of
    <C>e</C> equals the image set of <A>f</A> and
    <C><A>f</A> * e = f</C>.

    <Example><![CDATA[
gap> f := Transformation( [ 11, 10, 2, 11, 4, 4, 7, 6, 9, 10, 1, 11 ] );;
gap> e := RightOne( f );
Transformation( [ 1, 2, 2, 4, 4, 6, 7, 7, 9, 10, 11, 11 ] )
gap> IsIdempotent( e );
true
gap> f * e = f;
true
gap> e := LeftOne( f );
Transformation( [ 1, 2, 3, 1, 5, 5, 7, 8, 9, 2, 11, 1 ] )
gap> e * f = f;
true
gap> IsIdempotent( e );
true
]]></Example>
  </Description>
</ManSection>

  <ManSection>
    <Oper Name="TrimTransformation" Arg="f[, n]"/>
    <Returns>Nothing.</Returns>
    <Description>
      It can happen that the internal representation of a transformation
      uses more memory than necessary. For example, this can happen when
      composing transformations where it is possible that the resulting
      transformation <A>f</A> belongs to <C>IsTrans4Rep</C> and
      stores its images as 32-bit integers, while none of its moved
      points exceeds 65536. The purpose of <C>TrimTransformation</C> is
      to change the internal representation of such an <A>f</A> to
      remove the trailing fixed points in the internal representation of
      <A>f</A>.
      <P/>

      If the optional second argument <A>n</A> is provided, then the
      internal representation of <A>f</A> is reduced to the images of
      the first <A>n</A> positive integers. Please note that it must be
      the case that <C>i ^ <A>f</A> &lt;= n</C> for all <C>i</C> in the
      range <C>[ 1 .. <A>n</A> ]</C> otherwise the resulting object will
      not define a transformation.
      <P/>

      If the optional second argument is not included, then the
      degree of <A>f</A> is used by default.
      <P/>

      The transformation <A>f</A> is changed in-place, and
      nothing is returned by this function.

      <Log><![CDATA[
gap> f := Transformation( [ 1 .. 2 ^ 16 ], x -> x + 1 );
<transformation on 65537 pts with rank 65536>
gap> g := Transformation( [ 1 .. 2 ^ 16 + 1 ],
> function( x )
>   if x = 1 or x = 65537 then
>     return x;
>   else
>     return x - 1;
>   fi;
> end );
<transformation on 65536 pts with rank 65535>
gap> h := g * f;
Transformation( [ 2, 2 ] )
gap> DegreeOfTransformation( h ); IsTrans4Rep( h ); MemoryUsage( h );
65537
true
262188
gap> TrimTransformation( h ); h;
Transformation( [ 2, 2 ] )
gap> DegreeOfTransformation( h ); IsTrans4Rep( h ); MemoryUsage( h );
2
false
44
]]></Log>
    </Description>
  </ManSection>
</Section>

<!-- *************************************************************** -->

<Section Label="sect:DisplayingTransformations">
  <Heading>Displaying transformations</Heading>
    It is possible to change the way that &GAP; displays transformations
    using the user preferences <C>TransformationDisplayLimit</C> and
    <C>NotationForTransformations</C>; see Section <Ref
      Func="UserPreference"/> for more information about user
    preferences.
    <P/>

    If <C>f</C> is a transformation where the degree <C>n</C> of
    <C>f</C> exceeds the value of the user preference
    <C>TransformationDisplayLimit</C>, then <C>f</C> is displayed as:
    <Log>&lt;transformation on n pts with rank r></Log> where <C>r</C>
    is the rank of <C>f</C> relative to <C>n</C>.  The idea is to
    abbreviate the display of transformations defined on many points.
    The default value for the <C>TransformationDisplayLimit</C> is
    <C>100</C>.
    <P/>

    If the degree of <C>f</C> does not exceed the value of
    <C>TransformationDisplayLimit</C>, then how <C>f</C> is displayed
    depends on the value of the user preference
    <C>NotationForTransformations</C>.
    <P/>

    There are two possible values for <C>NotationForTransformations</C>:

    <List>

      <Mark>input</Mark>
      <Item>
        With this option a transformation <A>f</A> is displayed in as:
        <C>Transformation( ImageListOfTransformation( <A>f</A>, n ) )</C>
        where <C>n</C> is the degree of <A>f</A>. The only exception is
        the identity transformation, which is displayed as:
        <C>IdentityTransformation</C>.
      </Item>

      <Mark>fr</Mark>
      <Item>With this option a transformation <A>f</A> is displayed in as:
        <C>&lt;transformation: ImageListOfTransformation( <A>f</A>, n )></C>
        where <C>n</C> is the largest moved point of <A>f</A>. The only
        exception is the identity transformation, which is displayed as:
        <C>&lt;identity transformation></C>.
      </Item>

    </List>
    <Log><![CDATA[
gap> SetUserPreference( "TransformationDisplayLimit", 12 );
gap> f := Transformation( [ 3, 8, 12, 1, 11, 9, 9, 4, 10, 5, 10, 6 ] );
<transformation on 12 pts with rank 10>
gap> SetUserPreference( "TransformationDisplayLimit", 100 );
gap> f;
Transformation( [ 3, 8, 12, 1, 11, 9, 9, 4, 10, 5, 10, 6 ] )
gap> SetUserPreference( "NotationForTransformations", "fr" );
gap> f;
<transformation: 3,8,12,1,11,9,9,4,10,5,10,6>
]]></Log>
</Section>

<!-- *************************************************************** -->

<Section Label="Making transformation semigroups">
<Heading>Semigroups of transformations</Heading>

As mentioned at the start of the chapter, every semigroup is isomorphic
to a semigroup of transformations, and in this section we describe the
functions in &GAP; specific to transformation semigroups. For more
information about semigroups in general see Chapter <Ref
  Chap="Semigroups"/>.
<P/>

The <Package>Semigroups</Package> package contains many additional
functions and methods for computing with semigroups of transformations.
In particular, <Package>Semigroups</Package> contains more efficient
methods than those available in the &GAP; library (and in many cases
more efficient than any other software) for creating semigroups of
transformations, calculating their Green's classes, size, elements,
group of units, minimal ideal, small generating sets, testing
membership, finding the inverses of a regular element, factorizing
elements over the generators, and more.

Since a transformation semigroup is also a transformation collection,
there are special methods for
<Ref Attr="MovedPoints" Label="for a transformation coll"/>,
<Ref Attr="NrMovedPoints" Label="for a transformation coll"/>,
<Ref Meth="LargestMovedPoint" Label="for a transformation coll"/>,
<Ref Meth="SmallestMovedPoint" Label="for a transformation coll"/>,
<Ref Meth="LargestImageOfMovedPoint" Label="for a transformation coll"/>,
and
<Ref Meth="SmallestImageOfMovedPoint" Label="for a transformation coll"/>,
when applied to a transformation semigroup.

<!-- *************************************************************** -->

<ManSection>
<Filt Name="IsTransformationSemigroup" Arg="obj" Type="Synonym"/>
<Filt Name="IsTransformationMonoid" Arg="obj" Type="Synonym"/>
<Returns><K>true</K> or <K>false</K>.</Returns>
<Description>
A <E>transformation semigroup</E> is simply a semigroup consisting of
transformations. An object <A>obj</A> is a transformation semigroup in
&GAP; if it satisfies <Ref Filt="IsSemigroup"/> and <Ref
  Filt="IsTransformationCollection"/>.
<P/>

A  <E>transformation monoid</E> is a monoid consisting of
transformations.  An object <A>obj</A> is a transformation monoid in
&GAP; if it satisfies <Ref Filt="IsMonoid"/> and <Ref
  Filt="IsTransformationCollection"/>.
<P/>

Note that it is possible for a transformation semigroup to have a
multiplicative neutral element (i.e. an identity element) but not to
satisfy <C>IsTransformationMonoid</C>. For example,
    <Example><![CDATA[
gap> f := Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] );;
gap> S := Semigroup( f, One( f ) );
<commutative transformation monoid of degree 10 with 1 generator>
gap> IsMonoid( S );
true
gap> IsTransformationMonoid( S );
true
gap> S := Semigroup(
> Transformation( [ 3, 8, 1, 4, 5, 6, 7, 1, 10, 10 ] ),
> Transformation( [ 1, 2, 3, 4, 5, 6, 7, 8, 10, 10 ] ) );
<transformation semigroup of degree 10 with 2 generators>
gap> One( S );
fail
gap> MultiplicativeNeutralElement( S );
Transformation( [ 1, 2, 3, 4, 5, 6, 7, 8, 10, 10 ] )
gap> IsMonoid( S );
false
]]></Example>
In this example <C>S</C> cannot be converted into a monoid using
<Ref Oper="AsMonoid"/> since the <Ref Attr="One"/> of any element in
<C>S</C> differs from the multiplicative neutral element.
<P/>

For more details see <Ref Filt="IsMagmaWithOne"/>.
</Description>
</ManSection>

<ManSection>
<Attr Name="DegreeOfTransformationSemigroup" Arg="S"/>
<Returns>A non-negative integer.</Returns>
<Description>
  The <E>degree</E> of a transformation semigroup <A>S</A> is just the
  maximum of the degrees of the elements of <A>S</A>.

  <Example><![CDATA[
gap> S := Semigroup(
> Transformation( [ 3, 8, 1, 4, 5, 6, 7, 1, 10, 10, 11 ] ),
> Transformation( [ 1, 2, 3, 4, 5, 6, 7, 8, 1, 1, 11 ] ) );
<transformation semigroup of degree 10 with 2 generators>
gap> DegreeOfTransformationSemigroup( S );
10
]]></Example>
</Description>
</ManSection>

<!-- *************************************************************** -->

<ManSection>
<Func Name="FullTransformationSemigroup" Arg="n"/>
<Func Name="FullTransformationMonoid" Arg="n"/>
<Returns>The full transformation semigroup of degree <A>n</A>.</Returns>
<Description>
  If <A>n</A> is a positive integer, then
  <C>FullTransformationSemigroup</C> returns the monoid consisting of
  all transformations with degree at most <A>n</A>, called the
  <E>full transformation semigroup</E>.
  <P/>

  The full transformation semigroup is regular, has
  <C><A>n</A> ^ <A>n</A></C> elements, and is generated by any set
  containing transformations that generate the symmetric group on
  <A>n</A> points and any transformation of rank <C><A>n</A> - 1</C>.
  <P/>

  <C>FulTransformationMonoid</C> is a synonym for
  <C>FullTransformationSemigroup</C>.

  <Example><![CDATA[
gap> FullTransformationSemigroup( 1234 );
<full transformation monoid of degree 1234>
]]></Example>
</Description>
</ManSection>

<!-- *************************************************************** -->

<ManSection>
<Prop Name="IsFullTransformationSemigroup" Arg="S"/>
<Prop Name="IsFullTransformationMonoid" Arg="S"/>
<Returns><K>true</K> or <K>false</K>.</Returns>
<Description>
  If the transformation semigroup <A>S</A> of degree <C>n</C> contains
  every transformation of degree at most <C>n</C>, then
  <C>IsFullTransformationSemigroup</C> returns <K>true</K> and otherwise
  it returns <K>false</K>.
  <P/>

  <C>IsFullTransformationMonoid</C> is a synonym of
  <C>IsFullTransformationSemigroup</C>. It is common in the literature
  for the full transformation monoid to be referred to as the full
  transformation semigroup.

  <Example><![CDATA[
gap> S := Semigroup( AsTransformation( (1,3,4,2), 5 ),
>                    AsTransformation( (1,3,5), 5 ),
>                    Transformation( [ 1, 1, 2, 3, 4 ] ) );
<transformation semigroup of degree 5 with 3 generators>
gap> IsFullTransformationSemigroup( S );
true
gap> S;
<full transformation monoid of degree 5>
gap> IsFullTransformationMonoid( S );
true
gap> S := FullTransformationSemigroup( 5 );;
gap> IsFullTransformationSemigroup( S );
true
]]></Example>
</Description>
</ManSection>

<!-- *************************************************************** -->

<ManSection>
<Attr Name="IsomorphismTransformationSemigroup" Arg="S"/>
<Attr Name="IsomorphismTransformationMonoid" Arg="S"/>
<Returns>An isomorphism to a transformation semigroup or monoid.</Returns>
<Description>
  Returns an isomorphism from the finite semigroup <A>S</A> to a
  transformation semigroup. For most types of objects in &GAP; the
  degree of this transformation semigroup will be equal to the size of
  <A>S</A> plus <C>1</C>.
  <P/>

  Let <C><A>S</A> ^ 1</C> denote the monoid obtained from <A>S</A> by
  adjoining an identity element. Then  <A>S</A> acts faithfully on
  <C><A>S</A> ^ 1</C> by right multiplication, i.e.  every element of
  <A>S</A> describes a transformation on <C>1, .. , |S| + 1</C>. The
  isomorphism from <A>S</A> to the transformation semigroup described in
  this way is called the <E>right regular representation</E> of
  <A>S</A>.  In most cases, <C>IsomorphismTransformationSemigroup</C>
  will return the right regular representation of <A>S</A>.
  <P/>

  As exceptions, if <A>S</A> is a permutation group or a partial perm
  semigroup, then the elements of <A>S</A> act naturally and faithfully
  by transformations on the values from <C>1</C> to the largest moved
  point of <A>S</A>.
  <P/>

  If <A>S</A> is a finitely presented semigroup, then the Todd-Coxeter
  approach will be attempted.<P/>

  <C>IsomorphismTransformationMonoid</C> differs from
  <C>IsomorphismTransformationSemigroup</C>
  only in that its range is a transformation monoid, and not only a
  semigroup, when the semigroup <A>S</A> is a monoid.

  <Log><![CDATA[
gap> S := Semigroup( [ [ [ Z(3), 0*Z(3) ], [ 0*Z(3), Z(3) ^ 0 ] ],
>  [ [ Z(3), Z(3)^0 ], [ Z(3), 0*Z(3) ] ],
>  [ [ Z(3)^0, 0*Z(3) ], [ 0*Z(3), 0*Z(3) ] ] ] );;
gap> Size( S );
81
gap> IsomorphismTransformationSemigroup( S );;
gap> S := SymmetricInverseSemigroup( 4 );
<symmetric inverse monoid of degree 4>
gap> IsomorphismTransformationMonoid( S );
MappingByFunction( <symmetric inverse monoid of degree 4>,
<transformation monoid of degree 5 with 4 generators>
 , function( x ) ... end, <Operation "AsPartialPerm"> )
gap> G := Group( (1,2,3) );
Group([ (1,2,3) ])
gap> IsomorphismTransformationMonoid( G );
MappingByFunction( Group([ (1,2,3) ]), <commutative transformation
 monoid of degree 3 with 1 generator>
 , function( x ) ... end, function( x ) ... end )]]></Log>
</Description>
</ManSection>

<ManSection>
<Attr Name="AntiIsomorphismTransformationSemigroup" Arg="S"/>
<Returns>An anti-isomorphism.</Returns>
<Description>
  If <A>S</A> is a semigroup, then
  <C>AntiIsomorphismTransformationSemigroup</C> returns an anti-isomorphism
  from <A>S</A> to a transformation semigroup. At present, the degree of the
  resulting transformation semigroup equals the size of <A>S</A> plus
  <M>1</M>, and, consequently, this function is of limited use. <P/>

    <Example><![CDATA[
gap> S := Semigroup( Transformation( [ 5, 5, 1, 1, 3 ] ),
>                    Transformation( [ 2, 4, 1, 5, 5 ] ) );
<transformation semigroup of degree 5 with 2 generators>
gap> Size( S );
172
gap> AntiIsomorphismTransformationSemigroup( S );
MappingByFunction( <transformation semigroup of size 172, degree 5
 with 2 generators>, <transformation semigroup of degree 173 with 2
 generators>, function( x ) ... end, function( x ) ... end )
]]></Example>
    </Description>
  </ManSection>
</Section>
</Chapter>