<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  permutat.msk                GAP documentation            Martin Schönert -->
<!-- %A                                                           Alexander Hulpke -->
<!-- %% -->
<!-- %A  @(#)<M>Id: permutat.msk,v 1.15 2002/04/15 10:02:33 sal Exp </M> -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<Chapter Label="Permutations">
<Heading>Permutations</Heading>

&GAP; offers a data type <E>permutation</E> to describe the elements
of permutation groups.
<P/>
The points on which permutations in &GAP; act are the positive
integers up to a certain architecture dependent limit,
and the image of a point <M>i</M> under a permutation <M>p</M> is written
<M>i^p</M>, which is expressed as <M>i</M><C>^</C><M>p</M> in &GAP;.
(This action is also implemented by the function <Ref Func="OnPoints"/>.)
If <M>i</M><C>^</C><M>p</M> is different from <M>i</M>,
we say that <M>i</M> is <E>moved</E> by&nbsp;<M>p</M>,
otherwise it is <E>fixed</E>.
Permutations in &GAP; are  entered and displayed in cycle notation,
such as <C>(1,2,3)(4,5)</C>.
<P/>
The preimage of the point <M>i</M> under the permutation <M>p</M> can be
computed as <M>i</M><C>/</C><M>p</M>, see <Ref Var="PERM_INVERSE_THRESHOLD"/>.
<P/>
For arithmetic operations for permutations and their precedence,
see&nbsp;<Ref Sect="Arithmetic Operations for Elements"/>.
<P/>
In the names of the &GAP; functions that deal with permutations,
the word <Q>Permutation</Q> is usually abbreviated to <Q>Perm</Q>,
to save typing.
For example,
the category test function for permutations is <Ref Filt="IsPerm"/>.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:IsPerm">
<Heading>IsPerm (Filter)</Heading>

<#Include Label="[1]{permutat}">
<#Include Label="IsPerm">
<#Include Label="IsPermCollection">
<#Include Label="PermutationsFamily">
<#Include Label="PERM_INVERSE_THRESHOLD">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Comparison of Permutations">
<Heading>Comparison of Permutations</Heading>

<ManSection>
<Meth Name="\=" Arg='p1, p2' Label="for permutations"/>
<Meth Name="\&lt;" Arg='p1, p2' Label="for permutations"/>

<Description>
<Index Subkey="for permutations">equality test</Index>
<Index Subkey="for permutations">precedence test</Index>
Two permutations are equal if they move the same points and all these points
have the same images under both permutations.
<P/>
The permutation <A>p1</A> is smaller than <A>p2</A>
if <A>p1</A> <M>\neq</M> <A>p2</A>
and <M>i^{{<A>p1</A>}} &lt; i^{{<A>p2</A>}}</M>,
where <M>i</M> is the smallest point with
<M>i^{{<A>p1</A>}} \neq i^{{<A>p2</A>}}</M>.
Therefore the identity permutation is the smallest permutation,
see also Section&nbsp;<Ref Sect="Comparison Operations for Elements"/>.
<P/>
Permutations can be compared with certain other &GAP; objects,
see&nbsp;<Ref Sect="Comparisons"/> for the details.
<P/>
<Example><![CDATA[
gap> (1,2,3) = (2,3,1);
true
gap> (1,2,3) * (2,3,4) = (1,3)(2,4);
true
gap> (1,2,3) < (1,3,2);      # 1^(1,2,3) = 2 < 3 = 1^(1,3,2)
true
gap> (1,3,2,4) < (1,3,4,2);  # 2^(1,3,2,4) = 4 > 1 = 2^(1,3,4,2)
false
]]></Example>
</Description>
</ManSection>

<#Include Label="DistancePerms">
<#Include Label="SmallestGeneratorPerm">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Moved Points of Permutations">
<Heading>Moved Points of Permutations</Heading>

<#Include Label="SmallestMovedPoint">
<#Include Label="LargestMovedPoint">
<#Include Label="MovedPoints">
<#Include Label="NrMovedPoints">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Sign and Cycle Structure">
<Heading>Sign and Cycle Structure</Heading>

<#Include Label="SignPerm">
<#Include Label="CycleStructurePerm">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Permutations">
<Heading>Creating Permutations</Heading>

<#Include Label="ListPerm">
<#Include Label="PermList">
<#Include Label="MappingPermListList">
<#Include Label="RestrictedPerm">
<#Include Label="CycleFromList">

<ManSection>
  <Attr Name="AsPermutation" Arg="f"/>
  <Returns>A permutation or <K>fail</K>.</Returns>
  <Description>
    Partial permutations and transformations which define permutations
    (mathematically) can be converted into &GAP; permutations using
    <C>AsPermutation</C>; see Chapters <Ref Chap="Transformations"/> and 
    <Ref Chap="Partial permutations"/> for more details about transformations
    and partial permutations.

    <List>
      <Mark>for partial permutations</Mark>
      <Item>
        If the partial permutation <A>f</A> is a permutation of its image, then
        <C>AsPermutation</C> returns this permutation.  If <A>f</A> does not
        permute its image, then <K>fail</K> is returned. <P/>
      </Item>
    
      <Mark>for transformations</Mark>
      <Item>
        A transformation is a permutation if and only if its rank equals its
        degree. If a transformation in &GAP; is a permutation, then
        <C>AsPermutation</C> returns this permutation.  If <A>f</A> is not a
        permutation, then <K>fail</K> is returned. 
      </Item>
    </List>

    The function 
    <Ref Func="Permutation" Label="for a group, an action domain, etc."/> can
    also be used to convert partial permutations and transformations into
    permutations where appropriate.
    <Example>
gap> f:=PartialPerm( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ],
> [ 2, 7, 9, 4, 1, 10, 5, 6, 3, 8 ] );
(1,2,7,5)(3,9)(4)(6,10,8)
gap> AsPermutation(f);
(1,2,7,5)(3,9)(6,10,8)
gap> f:= PartialPerm( [ 1, 2, 3, 4, 5, 7, 8 ], [ 5, 3, 8, 1, 9, 4, 10 ] );
[2,3,8,10][7,4,1,5,9]
gap> AsPermutation(f);
fail
gap> f:=Transformation( [ 5, 8, 3, 5, 8, 6, 2, 2, 7, 8 ] );;
gap> AsPermutation(f);
fail  
gap> f:=Transformation( [ 1, 3, 6, 6, 2, 10, 2, 3, 10, 5 ] );;
gap> AsPermutation(f);
fail
gap> f:=Transformation( [ 2, 7, 9, 4, 1, 10, 5, 6, 3, 8 ] );
Transformation( [ 2, 7, 9, 4, 1, 10, 5, 6, 3, 8 ] )
gap> AsPermutation(f);
(1,2,7,5)(3,9)(6,10,8)</Example>
    </Description>
  </ManSection>

</Section>
</Chapter>


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

