<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  rcwamap.xml          RCWA documentation          Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- ##  $Id: rcwamap.xml,v 1.166 2006/09/29 09:42:47 stefan Exp $     ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

<Chapter Label="ch:RcwaMappings">
<Heading>Residue Class-Wise Affine Mappings</Heading>

This chapter gives the basic definitions, describes how to enter residue
class-wise affine mappings and how to compute with them. The functionality
of this package which is dedicated to residue class-wise affine groups
is described in detail in the next chapter. The reader is encouraged to
look there already after having read the first few pages of this
chapter, and to look up definitions as he needs to.

<!-- #################################################################### -->

<Section Label="sec:basicdefinitions">
<Heading>Basic definitions</Heading>

<Index Key="rcwa mapping" Subkey="definition">rcwa mapping</Index>
<Index Key="rcwa group" Subkey="definition">rcwa group</Index>

Residue class-wise affine groups, or for short <E>rcwa</E> groups, are
permutation groups whose elements are bijective residue class-wise affine
mappings. <P/>

A mapping <M>f: \Z \rightarrow \Z</M> is called <E>residue class-wise
affine</E>, or for short an <E>rcwa</E> mapping, if there is a positive
integer&nbsp;<M>m</M> such that the restrictions of&nbsp;<M>f</M> to the
residue classes <M>r(m) \in \Z/m\Z</M> are all affine, i.e. given&nbsp;by
<Alt Only="LaTeX">
  <Display>
    f|_{r(m)}: \ r(m) \rightarrow \Z, \ \ \
    n \ \mapsto \ \frac{a_{r(m)} \cdot n + b_{r(m)}}{c_{r(m)}}
  </Display>
</Alt>
<Alt Only="Text,HTML"><Verb>
                                        a_r(m) * n + b_r(m)
           f|_r(m):  r(m) -> Z,  n |->  -------------------
                                              c_r(m)
</Verb></Alt>
for certain coefficients <M>a_{r(m)}, b_{r(m)}, c_{r(m)} \in \Z</M>.

<Index Key="modulus" Subkey="definition">modulus</Index>
<Index Key="rcwa mapping" Subkey="modulus">rcwa mapping</Index>
<Index Key="multiplier" Subkey="definition">multiplier</Index>
<Index Key="rcwa mapping" Subkey="multiplier">rcwa mapping</Index>
<Index Key="divisor" Subkey="definition">divisor</Index>
<Index Key="rcwa mapping" Subkey="divisor">rcwa mapping</Index>

The smallest possible <M>m</M> is called the <E>modulus</E>
of&nbsp;<M>f</M>. It is understood that all fractions are reduced,
i.e. that <M>\gcd( a_{r(m)}, b_{r(m)}, c_{r(m)} ) = 1</M>, and that
<M>c_{r(m)} &gt; 0</M>. The lcm of the coefficients <M>a_{r(m)}</M>
is called the <E>multiplier</E> of&nbsp;<M>f</M>, and the lcm of the
coefficients <M>c_{r(m)}</M> is called the <E>divisor</E>
of&nbsp;<M>f</M>. <P/>

It is easy to see that the residue class-wise affine mappings form
a monoid under composition, and that the residue class-wise affine
permutations form a countable subgroup of Sym(<M>\Z</M>).
We denote the latter group by RCWA(<M>\Z</M>). <P/>

<Index Key="tame" Subkey="rcwa mapping">tame</Index>
<Index Key="tame" Subkey="rcwa group">tame</Index>
<Index Key="wild" Subkey="rcwa mapping">wild</Index>
<Index Key="wild" Subkey="rcwa group">wild</Index>
<Index Key="rcwa mapping" Subkey="tame">rcwa mapping</Index>
<Index Key="rcwa group" Subkey="tame">rcwa group</Index>
<Index Key="rcwa mapping" Subkey="wild">rcwa mapping</Index>
<Index Key="rcwa group" Subkey="wild">rcwa group</Index>

An rcwa mapping is called <E>tame</E> if the set of moduli of its powers
is bounded, or equivalently if it permutes a partition of&nbsp;<M>\Z</M>
into finitely many residue classes on all of which it is affine.
An rcwa group is called <E>tame</E> if there is a common such partition
for all of its elements, or equivalently if the set of moduli of its
elements is bounded. Rcwa mappings and -groups which are not tame
are called <E>wild</E>. Tame rcwa mappings and -groups are something which
one could call the <Q>trivial cases</Q> or <Q>basic building blocks</Q>,
while wild rcwa groups are the objects of primary interest. <P/>

The definitions of residue class-wise affine mappings and -groups can be
generalized in an obvious way to suitable rings other than&nbsp;<M>\Z</M>.
In fact, this package provides at least rudimentary support for residue
class-wise affine groups over semilocalizations of&nbsp;<M>\Z</M> and over
univariate polynomial rings over finite fields.

</Section>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<!-- #################################################################### -->

<Section Label="sec:EnteringRcwaMappings">
<Heading>Entering residue class-wise affine mappings</Heading>

Entering an rcwa mapping of&nbsp;<M>\Z</M> into &RCWA; requires specifying
the modulus&nbsp;<M>m</M> and the coefficients <M>a_{r(m)}</M>,
<M>b_{r(m)}</M> and&nbsp;<M>c_{r(m)}</M> for <M>r(m)</M> running over the
residue classes (mod&nbsp;<M>m</M>). <P/>

This can be done easiest by <C>RcwaMapping( <A>coeffs</A> )</C>, where
<A>coeffs</A> is a list of <M>m</M> coefficient triples
<C>coeffs[</C><M>r+1</M><C>]&nbsp;= [</C><M>a_{r(m)}</M>, <M>b_{r(m)}</M>,
<M>c_{r(m)}</M><C>]</C>, with <M>r</M> running from 0 to&nbsp;<M>m-1</M>.
<P/>

If some coefficient <M>c_{r(m)}</M> is zero or if images of some integers
under the mapping to be defined would not be integers, an error message is
printed and a break loop is entered. For example, the coefficient triple
<C>[1,4,3]</C> is not allowed at the first position.
The reason for this is that not all integers congruent to
<M>1 \cdot 0 + 4 = 4</M>&nbsp;mod&nbsp;<M>m</M>
are divisible by&nbsp;3. <P/>

For the general constructor for rcwa mappings,
see <Ref Meth="RcwaMapping" Label = "coeffs"/>.

<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]); # The Collatz mapping.
<rcwa mapping of Z with modulus 2>
gap> [ IsSurjective(T), IsInjective(T) ];
[ true, false ]
gap> SetName(T,"T"); Display(T);

Surjective rcwa mapping of Z with modulus 2

                n mod 2                |                 n^T
---------------------------------------+--------------------------------------
  0                                    | n/2
  1                                    | (3n + 1)/2

gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]); SetName(a,"a");
<rcwa mapping of Z with modulus 3>
gap> IsBijective(a);
true
gap> Display(a); # This is Collatz' permutation:

Bijective rcwa mapping of Z with modulus 3

                n mod 3                |                 n^a
---------------------------------------+--------------------------------------
  0                                    | 2n/3
  1                                    | (4n - 1)/3
  2                                    | (4n + 1)/3

gap> Support(a);
Z \ [ -1, 0, 1 ]
gap> Cycle(a,44);
[ 44, 59, 79, 105, 70, 93, 62, 83, 111, 74, 99, 66 ]
]]>
</Example>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Alt Only="LaTeX">\noindent</Alt>
There is computational evidence for the conjecture that any residue
class-wise affine permutation of&nbsp;<M>\Z</M> can be factored into members
of the following three series of rcwa mappings of particularly simple
structure (cp. <Ref Attr="FactorizationIntoCSCRCT" Label="g"/>):

<ManSection>
  <Func Name="ClassShift" Arg="r, m" Label="r, m"/>
  <Func Name="ClassShift" Arg="ResidueClass(r,m)" Label="r(m)"/>
  <Returns> The class shift <M>\nu_{r(m)}</M>. </Returns>
  <Description>
    The <E>class shift</E> <M>\nu_{r(m)}</M> is the rcwa mapping
    of&nbsp;<M>\Z</M> which maps <M>n \in r(m)</M> to <M>n + m</M>
    and which fixes <M>\Z&nbsp;\setminus r(m)</M> pointwise.
    Enclosing the argument list in list brackets is permitted.
<Example>
<![CDATA[
gap> Display(ClassShift(5,12));    

Tame bijective rcwa mapping of Z with modulus 12, of order infinity

               n mod 12                |          n^ClassShift(5,12)
---------------------------------------+--------------------------------------
   0  1  2  3  4  6  7  8  9 10 11     | n
   5                                   | n + 12

]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="ClassReflection" Arg="r, m" Label="r, m"/>
  <Func Name="ClassReflection" Arg="ResidueClass(r,m)" Label="r(m)"/>
  <Returns> The class reflection <M>\varsigma_{r(m)}</M>. </Returns>
  <Description>
    The <E>class reflection</E> <M>\varsigma_{r(m)}</M> is the rcwa mapping
    of&nbsp;<M>\Z</M> which maps <M>n \in r(m)</M> to <M>-n + 2r</M>
    and which fixes <M>\Z&nbsp;\setminus&nbsp;r(m)</M> pointwise.
    Enclosing the argument list in list brackets is permitted.
<Example>
<![CDATA[
gap> Display(ClassReflection(5,9));

Bijective rcwa mapping of Z with modulus 9, of order 2

                n mod 9                |        n^ClassReflection(5,9)
---------------------------------------+--------------------------------------
  0 1 2 3 4 6 7 8                      | n
  5                                    | -n + 10

]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<ManSection>
  <Func Name="ClassTransposition"
        Arg="r1, m1, r2, m2"
        Label="r1, m1, r2, m2"/>
  <Func Name="ClassTransposition"
        Arg="ResidueClass(r1,m1),ResidueClass(r2,m2)"
        Label="r1(m1), r2(m2)"/>
  <Returns>
    The class transposition <M>\tau_{r_1(m_1),r_2(m_2)}</M>.
  </Returns>
  <Description>
    Given two disjoint residue classes <M>r_1(m_1)</M> and <M>r_2(m_2)</M>
    of the integers, the <E>class transposition</E>
    <M>\tau_{r_1(m_1),r_2(m_2)}</M> <M>\in</M> RCWA(<M>\Z</M>) is defined by
    <Alt Only="LaTeX">
    <Display>
      <![CDATA[
      \tau_{r_1(m_1),r_2(m_2)}: \ \ \ n \ \longmapsto \
      \begin{cases}
        (m_2 n + m_1 r_2 - m_2 r_1)/m_1 & \text{if} \ n \in r_1(m_1), \\
        (m_1 n + m_2 r_1 - m_1 r_2)/m_2 & \text{if} \ n \in r_2(m_2), \\
        n                               & \text{otherwise},
      \end{cases}
      ]]>
    </Display>
    </Alt>
    <Alt Only="Text,HTML"><Verb>
              /
             | (m_2 n + m_1 r_2 - m_2 r_1)/m_1 if n in r_1(m_1),
      n |-> &lt;  (m_1 n + m_2 r_1 - m_1 r_2)/m_2 if n in r_2(m_2),
             | otherwise,
              \
    </Verb></Alt>
    where it is understood that <M>0 \leq r_1 &lt; m_1</M> and that
    <M>0 \leq r_2 &lt; m_2</M>. The class transposition
    <M>\tau_{r_1(m_1),r_2(m_2)}</M> is an involution which interchanges
    the residue classes <M>r_1(m_1)</M> and <M>r_2(m_2)</M> and which fixes
    the complement of their union pointwise. <P/>

    Enclosing the argument list in list brackets is permitted.
    The residue classes <M>r_1(m_1)</M> and <M>r_2(m_2)</M> are stored
    as an attribute <C>TransposedClasses</C>.
<Example>
<![CDATA[
gap> Display(ClassTransposition(1,2,8,10));

Bijective rcwa mapping of Z with modulus 10, of order 2

               n mod 10                |    n^ClassTransposition(1,2,8,10)
---------------------------------------+--------------------------------------
   0  2  4  6                          | n
   1  3  5  7  9                       | 5n + 3
   8                                   | (n - 3)/5

]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\noindent</Alt>
The set of all class transpositions generates the simple group
mentioned in the preface. <P/>

The permutations of the following kind play an important role in factoring
bijective rcwa mappings into class shifts, class reflections and class
transpositions (cp. <Ref Attr="FactorizationIntoCSCRCT" Label="g"/>):

<ManSection>
  <Func Name="PrimeSwitch" Arg="p" Label="p"/>
  <Func Name="PrimeSwitch" Arg="p, k" Label="p, k"/>
  <Returns>
    In the one-argument form the <E>prime switch</E>
    <M>\sigma_p := \tau_{0(8),1(2p)} \cdot \tau_{4(8),-1(2p)} \cdot
    \tau_{0(4),1(2p)} \cdot \tau_{2(4),-1(2p)} \cdot \tau_{2(2p),1(4p)}
    \cdot \tau_{4(2p),2p+1(4p)}</M>, and in the two-argument form
    the restriction of <M>\sigma_p</M> by <M>n \mapsto kn</M>.
  </Returns>
  <Description>
    For an odd prime <M>p</M>, the <E>prime switch</E> <M>\sigma_p</M>
    is a bijective rcwa mapping of <M>\Z</M> with modulus&nbsp;<M>4p</M>,
    multiplier&nbsp;<M>p</M> and divisor&nbsp;2.
<Example>
<![CDATA[
gap> Factorization(PrimeSwitch(3));
[ ClassTransposition(1,6,0,8), ClassTransposition(5,6,4,8), 
  ClassTransposition(0,4,1,6), ClassTransposition(2,4,5,6), 
  ClassTransposition(2,6,1,12), ClassTransposition(4,6,7,12) ]
]]>
</Example>
  </Description>
</ManSection>

There are properties <C>IsClassShift</C>, <C>IsClassReflection</C>,
<C>IsClassTransposition</C> and <C>IsPrimeSwitch</C> which indicate
whether a given rcwa mapping belongs to the corresponding series. <P/>

In the sequel, a description of the general-purpose constructor for rcwa
mappings is given. This might look a bit technical on a first glance,
but knowing all possible ways of entering an rcwa mapping is by no means
necessary for understanding this manual or for using this package.

<ManSection>
  <Meth Name="RcwaMapping" Arg="R, m, coeffs"
        Label="R, m, coeffs"/>
  <Meth Name="RcwaMapping" Arg="R, coeffs"
        Label="R, coeffs"/>
  <Meth Name="RcwaMapping" Arg="coeffs"
        Label="coeffs"/>
  <Meth Name="RcwaMapping" Arg="perm, range"
        Label="perm, range"/>
  <Meth Name="RcwaMapping" Arg="m, values"
        Label="m, values"/>
  <Meth Name="RcwaMapping" Arg="pi, coeffs"
        Label="pi, coeffs"/>
  <Meth Name="RcwaMapping" Arg="q, m, coeffs"
        Label="q, m, coeffs"/>
  <Meth Name="RcwaMapping" Arg="P1, P2"
        Label="P1, P2"/>
  <Meth Name="RcwaMapping" Arg="cycles"
        Label="cycles"/>
  <Returns> An rcwa mapping. </Returns>
  <Description>
    In all cases the argument&nbsp;<A>R</A> is the underlying ring,
    <A>m</A> is the modulus and <A>coeffs</A> is the coefficient list.
    A coefficient list for an rcwa mapping with modulus <M>m</M> consists of
    <M>|R/mR|</M> coefficient triples
    <C>[</C><M>a_{r(m)}</M>, <M>b_{r(m)}</M>, <M>c_{r(m)}</M><C>]</C>.
    Their ordering is determined by the ordering of the representatives of
    the residue classes (mod&nbsp;<M>m</M>) in the sorted list returned by
    <C>AllResidues(<A>R</A>, <A>m</A>)</C>. In case <M>R = \mathbb{Z}</M>
    this means that the coefficient triple for the residue class <M>0(m)</M>
    comes first and is followed by the one for <M>1(m)</M>, the one for
    <M>2(m)</M> and so on. In case one or several of the arguments <A>R</A>,
    <A>m</A> and <A>coeffs</A> are omitted or replaced by other arguments,
    the former are either derived from the latter or default values are
    taken. The meaning of the other arguments is defined in the detailed
    description of the particular methods given in the sequel.

    The above methods return the rcwa mapping
    <List>
      <Mark>(a)</Mark>
      <Item>
        of <A>R</A> with modulus <A>modulus</A> and coefficients
        <A>coeffs</A>, resp.
      </Item>
      <Mark>(b)</Mark>
      <Item>
        of <A>R</A> = <M>\mathbb{Z}</M> or <A>R</A> =
        <M>\mathbb{Z}_{(\pi)}</M> with modulus <C>Length(<A>coeffs</A>)</C>
        and coefficients <A>coeffs</A>, resp.
      </Item>
      <Mark>(c)</Mark>
      <Item>
        of <A>R</A> = <M>\mathbb{Z}</M> with modulus
        <C>Length(<A>coeffs</A>)</C> and coefficients <A>coeffs</A>, resp.
      </Item>
      <Mark>(d)</Mark>
      <Item>
        of <A>R</A> = <M>\mathbb{Z}</M>, acting on any set
        <C><A>range</A>+k*Length(<A>range</A>)</C> like the
        permutation <A>perm</A> on <A>range</A>, resp.
      </Item>
      <Mark>(e)</Mark>
      <Item>
        of <A>R</A> = <M>\mathbb{Z}</M> with modulus <A>modulus</A> and
        values prescribed by the list <A>val</A>, which consists of
        2<M>\cdot</M><A>modulus</A> pairs giving preimage and image for
        2 points per residue class (mod <A>modulus</A>), resp.
      </Item>
      <Mark>(f)</Mark>
      <Item>
        of <A>R</A> = <M>\Z_{(\pi)}</M> with modulus
        <C>Length(<A>coeffs</A>)</C> and coefficients <A>coeffs</A>
        (the set of primes <M>\pi</M> denoting the underlying ring is
        passed as argument <A>pi</A>), resp.
      </Item>
      <Mark>(g)</Mark>
      <Item>
        of <A>R</A> = GF(<A>q</A>)[<A>x</A>] with modulus
        <A>modulus</A> and coefficients <A>coeffs</A>, resp.
      </Item>
      <Mark>(h)</Mark>
      <Item>
        a bijective rcwa mapping which induces a bijection between
        the partitions <A>P1</A> and <A>P2</A> of&nbsp;<A>R</A> into residue
        classes and which is affine on the elements of <A>P1</A>, resp.
      </Item>
      <Mark>(i)</Mark>
      <Item>
        a bijective rcwa mapping with <Q>residue class cycles</Q> as given
        by <A>cycles</A>. The latter is a list of lists of pairwise disjoint
        residue classes which the mapping should permute cyclically, each.
      </Item>
    </List>
    The methods for the operation <C>RcwaMapping</C> perform a number of
    argument checks, which can be skipped by using <C>RcwaMappingNC</C>
    instead.

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Example>
<![CDATA[
gap> x := Indeterminate(GF(2),1);; SetName(x,"x");
gap> R := PolynomialRing(GF(2),1);
GF(2)[x]
gap> RcwaMapping(R,x+1,[[1,0,x+One(R)],[x+One(R),0,1]]*One(R));      # (a)
<rcwa mapping of GF(2)[x] with modulus x+Z(2)^0>
gap> RcwaMapping(Z_pi(2),[[1/3,0,1]]);                               # (b)
Rcwa mapping of Z_( 2 ): n -> 1/3 n
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);                   # (c)
<rcwa mapping of Z with modulus 3>
gap> RcwaMapping((1,2,3),[1..4]);                                    # (d)
<bijective rcwa mapping of Z with modulus 4, of order 3>
gap> T = RcwaMapping(2,[[1,2],[2,1],[3,5],[4,2]]);                   # (e)
true
gap> RcwaMapping([2],[[1/3,0,1]]);                                   # (f)
Rcwa mapping of Z_( 2 ): n -> 1/3 n
gap> RcwaMapping(2,x+1,[[1,0,x+One(R)],[x+One(R),0,1]]*One(R));      # (g)
<rcwa mapping of GF(2)[x] with modulus x+Z(2)^0>
gap> a = RcwaMapping(List([[0,3],[1,3],[2,3]],ResidueClass),
>                    List([[0,2],[1,4],[3,4]],ResidueClass));        # (h)
true
gap> RcwaMapping([List([[0,2],[1,4],[3,8],[7,16]],ResidueClass)]);   # (i)
<bijective rcwa mapping of Z with modulus 16, of order 4>
gap> Cycle(last,ResidueClass(0,2));
[ 0(2), 1(4), 3(8), 7(16) ]
]]>
</Example>
  </Description>
</ManSection>

<Index Key="View" Subkey="f"><C>View</C></Index>
<Index Key="Display" Subkey="f"><C>Display</C></Index>
<Index Key="Print" Subkey="f"><C>Print</C></Index>
<Index Key="String" Subkey="f"><C>String</C></Index>

<Alt Only="LaTeX">\noindent</Alt>
In most cases the output of the <C>View</C> method does not describe an
rcwa mapping completely. In these cases the output is enclosed in
brackets. There are methods installed for <C>Display</C>, <C>Print</C>
and <C>String</C>.  The <C>Print</C>ed representation of an rcwa mapping
is &GAP; - readable if and only if the <C>Print</C>ed representation of
the elements of the underlying ring is so. There is also a method for
<C>LaTeX</C>:

<ManSection>
  <Meth Name="LaTeXObj" Arg="f" Label="f"/>
  <Meth Name="LaTeX" Arg="f" Label="f"/>
  <Returns>
    A &LaTeX; representation of the rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    The output makes use of the &LaTeX; macro package
    <Package>amsmath</Package>.
    If the option <A>Factorization</A> is set, a factorization of <A>f</A>
    into class shifts, class reflections, class transpositions and prime
    switches is printed (cp. <Ref Attr="FactorizationIntoCSCRCT"
    Label="g"/>).
    For rcwa mappings with modulus greater than&nbsp;1, an indentation by
    <A>Indentation</A> characters can be specified by setting this option
    value accordingly.
<Example>
<![CDATA[
gap> Print(LaTeXObj(T));
n \ \longmapsto \
\begin{cases}
  \frac{n}{2}      & \text{if} \ n \in 0(2), \\
  \frac{3n + 1}{2} & \text{if} \ n \in 1(2).
\end{cases}
]]>
</Example>
<Example>
<![CDATA[
gap> Print(LaTeXObj(Comm(a,ClassShift(0,4)):Factorization));
      &\nu_{4(8)} \cdot \nu_{0(8)}^{-1}
 \cdot \tau_{0(8),4(8)} \cdot \tau_{5(16),11(16)}
 \cdot \tau_{4(8),11(16)}
]]>
</Example>
  </Description>
</ManSection>

<Index Key="LaTeXAndXDVI" Subkey="f"><C>LaTeXAndXDVI</C></Index>
There is an operation <C>LaTeXAndXDVI</C> which displays an rcwa mapping
in an <Package>xdvi</Package> window.
This works as follows: The string returned by the <C>LaTeXObj</C> - method
described above is inserted into a &LaTeX; template file. This file is
&LaTeX;'ed, and the result is shown with <Package>xdvi</Package>.
Calling <C>Display</C> with option <A>xdvi</A> has the same effect.
The operation <C>LaTeXAndXDVI</C> is only available on UNIX systems,
and requires suitable installations of &LaTeX; and <Package>xdvi</Package>.

</Section>

<!-- #################################################################### -->

<Section Label="sec:BasicFunctionalityForRcwaMappings">
<Heading>Basic functionality for rcwa mappings</Heading>

<Index Key="rcwa mapping" Subkey="arithmetic operations">rcwa mapping</Index>
<Index Key="Order" Subkey="g"><C>Order</C></Index>
<Index Key="IsTame" Subkey="f"><C>IsTame</C></Index> <P/>

Checking whether two rcwa mappings are equal is cheap.
Rcwa mappings can be multiplied, thus there is a method for <C>*</C>.
Bijective rcwa mappings can also be inverted, thus there is a method for
<C>Inverse</C>. The latter method is usually accessed by raising a mapping
to some power with negative exponent. Multiplying, inverting and computing
powers of tame rcwa mappings is cheap. Computing powers of wild mappings
is usually expensive -- runtime and memory requirements normally grow
approximately exponentially with the exponent. How expensive multiplying
a couple of wild mappings is, varies very much. In any case, the amount of
memory required for storing an rcwa mapping is proportional to its modulus.
Whether a given mapping is tame or wild can be determined by the operation
<C>IsTame</C>. There are methods for <C>Order</C>, which can not only
compute a finite order, but can also detect infinite order.

<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);;          # The Collatz mapping.
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
gap> List([-4..4],k->Modulus(a^k));
[ 256, 64, 16, 4, 1, 3, 9, 27, 81 ]
gap> IsTame(T) or IsTame(a);
false
gap> IsTame(ClassShift(0,1)) and IsTame(ClassTransposition(0,2,1,2));
true
gap> T^2*a*T*a^-3;
<rcwa mapping of Z with modulus 768>
gap> (ClassShift(1,3)*ClassReflection(2,7))^1000000;
<bijective rcwa mapping of Z with modulus 21>
]]>
</Example>

<Index Key="IsInjective" Subkey="f"><C>IsInjective</C></Index>
<Index Key="IsSurjective" Subkey="f"><C>IsSurjective</C></Index>
<Index Key="IsBijective" Subkey="f"><C>IsBijective</C></Index>
<Index Key="Image" Subkey="f"><C>Image</C></Index>

There are methods installed for <C>IsInjective</C>, <C>IsSurjective</C>,
<C>IsBijective</C> and <C>Image</C>.

<Example>
<![CDATA[
gap> [ IsInjective(T), IsSurjective(T), IsBijective(a) ];
[ false, true, true ]
gap> Image(RcwaMapping([[2,0,1]]));
0(2)
]]>
</Example>

<Index Key="rcwa mapping" Subkey="images under">rcwa mapping</Index>

Images of elements, of finite sets of elements and of unions of finitely
many residue classes of the source of an rcwa mapping can be computed with
<C>&circum;</C>, the same symbol as used for exponentiation and conjugation.
The same works for partitions of the source into a finite number of
residue classes.

<Example>
<![CDATA[
gap> 15^T;
23
gap> ResidueClass(1,2)^T;
2(3)
gap> List([[0,3],[1,3],[2,3]],ResidueClass)^a;
[ 0(2), 1(4), 3(4) ]
]]>
</Example>

<Index Key="PreImageElm" Subkey="f"><C>PreImageElm</C></Index>
<Index Key="PreImagesElm" Subkey="f"><C>PreImagesElm</C></Index>
<Index Key="PreImage" Subkey="f"><C>PreImage</C></Index>

For computing preimages of elements under rcwa mappings,
there are methods for <C>PreImageElm</C> and <C>PreImagesElm</C>.
The preimage of a finite set of ring elements or of a union of finitely
many residue classes under an rcwa mapping can be computed using
<C>PreImage</C>.

<Example>
<![CDATA[
gap> PreImagesElm(T,8);
[ 5, 16 ]
gap> PreImage(T,ResidueClass(Integers,3,2));
Z \ 0(6) U 2(6)
gap> M := [1];; l := [1];;
gap> while Length(M) < 10000 do M := PreImage(T,M); Add(l,Length(M)); od; l;
[ 1, 1, 2, 2, 4, 5, 8, 10, 14, 18, 26, 36, 50, 67, 89, 117, 157, 208, 277, 
  367, 488, 649, 869, 1154, 1534, 2039, 2721, 3629, 4843, 6458, 8608, 11472 ]
]]>
</Example>

<Index Key="Support" Subkey="g"><C>Support</C></Index>
<Index Key="MovedPoints" Subkey="g"><C>MovedPoints</C></Index>
<Index Key="RestrictedPerm" Subkey="g"><C>RestrictedPerm</C></Index>

There is a method for the operation <C>Support</C> for computing the
support of a bijective rcwa mapping. A synonym for <C>Support</C> is
<C>MovedPoints</C>. There is also a method for <C>RestrictedPerm</C>
for computing the restriction of a bijective rcwa mapping to a union
of residue classes which it fixes setwisely.

<Example>
<![CDATA[
gap> List([a,a^2],Support);
[ Z \ [ -1, 0, 1 ], Z \ [ -3, -2, -1, 0, 1, 2, 3 ] ]
gap> RestrictedPerm(ClassShift(0,2)*ClassReflection(1,2),ResidueClass(0,2));
<rcwa mapping of Z with modulus 2>
gap> last = ClassShift(0,2);
true
]]>
</Example>

Rcwa mappings can be added and subtracted pointwise. However, please note
that the set of rcwa mappings of a ring does not form a ring under
<C>+</C> and <C>*</C>. <P/>

<Example>
<![CDATA[
gap> b := ClassShift(0,3) * a;;
gap> [ Image((a + b)), Image((a - b)) ];
[ 2(4), [ -2, 0 ] ]
]]>
</Example>

<Index Key="Modulus" Subkey="f"><C>Modulus</C></Index>
<Index Key="Mod" Subkey="f"><C>Mod</C></Index>
<Index Key="Coefficients" Subkey="f"><C>Coefficients</C></Index>

There are operations <C>Modulus</C> (abbreviated <C>Mod</C>) and
<C>Coefficients</C> for extracting the modulus resp. the coefficient list
of a given rcwa mapping. The meaning of the return values is as described
in the previous section.
General documentation for most operations mentioned in this section can
be found in the &GAP; reference manual. For rcwa mappings of rings other
than <M>\mathbb{Z}</M>, not for all operations applicable methods are
available. <P/>

</Section>

<!-- #################################################################### -->

<Section Label="sec:FactoringRcwaMappings">
<Heading>Factoring rcwa mappings</Heading>

Factoring group elements into elements of some <Q>nice</Q> set of generators
is often helpful. The following can be seen as an attempt towards getting
a satisfactory solution of this problem for the group RCWA(<M>\Z</M>):

<ManSection>
  <Attr Name="FactorizationIntoCSCRCT" Arg="g" Label="g"/>
  <Meth Name="Factorization" Arg="g" Label="g"/>
  <Returns>
    A factorization of the bijective rcwa mapping&nbsp;<A>g</A> into
    class shifts, class reflections and class transpositions, provided
    that such a factorization exists and the method finds it.
  </Returns>
  <Description>
    The method may return <C>fail</C>, stop with an error message or run
    into an infinite loop. If it returns a result, this result is always
    correct. <P/>

    By default, prime switches are taken as one factor. 
    If the option <A>ExpandPrimeSwitches</A> is set, they are each
    decomposed into the 6 class transpositions given in
    the definition (see <Ref Func="PrimeSwitch" Label="p"/>).
    By default, the factoring process begins with splitting off factors
    from the right. This can be changed by setting the option
    <A>Direction</A> to <C>"from the left"</C>. By default, a reasonably
    coarse respected partition of the integral mapping occuring
    in the final stage of the algorithm is computed.
    This can be suppressed by setting the option <A>ShortenPartition</A>
    equal to <C>false</C>.
    By default, at the end it is checked whether the product of the
    determined factors indeed equals <A>g</A>. This check can be
    suppressed by setting the option <A>NC</A>.<P/>
    
    The problem of obtaining a factorization as described is algorithmically
    difficult, and this factorization routine is currently perhaps the most
    sophisticated part of the &RCWA; package. Information about the
    progress of the factorization process can be obtained by setting
    the info level of the Info class <Ref InfoClass="InfoRCWA"/> to&nbsp;2.
<Example>
<![CDATA[
gap> Factorization(Comm(ClassShift(0,3)*ClassReflection(1,2),ClassShift(0,2)));
[ ClassReflection(2,3), ClassShift(2,6)^-1, ClassTransposition(0,6,2,6), 
  ClassTransposition(0,6,5,6) ]
]]>
</Example>
  </Description>
</ManSection>

For purposes of demonstrating the capabilities of the factorization routine,
in Section&nbsp;<Ref Label="sec:FactoringTheCollatzPermutation"/>
Collatz' permutation is factored. Lothar Collatz has investigated this
permutation in&nbsp;1932. Its cycle structure is unknown so far. <P/>

Class transpositions can be written as products of any given number <M>k</M>
of class transpositions, as long as the underlying ring has a residue class
ring of cardinality&nbsp;<M>k</M>. Such a decomposition can be obtained by
<C>SplittedClassTransposition(<A>ct</A>,<A>k</A>)</C>. <P/>
<Index Key="SplittedClassTransposition" Subkey="G">
  <C>SplittedClassTransposition</C>
</Index>

Obtaining a factorization of a bijective rcwa mapping into class shifts,
class reflections and class transpositions is particularly difficult if
multiplier and divisor are coprime. A prototype of permutations which have
this property has been introduced in a different context
in&nbsp;<Cite Key="Keller99"/>: 

<ManSection>
  <Func Name="mKnot" Arg="m" Label = "m"/>
  <Returns>
    The permutation <M>g_m</M> as introduced in&nbsp;<Cite Key="Keller99"/>.
  </Returns>
  <Description>
    The argument <A>m</A> must be an odd integer&nbsp;<M>\geq&nbsp;3</M>.
<Example>
<![CDATA[
gap> Display(mKnot(5));

Wild bijective rcwa mapping of Z with modulus 5

                n mod 5                |              n^mKnot(5)
---------------------------------------+--------------------------------------
  0                                    | 6n/5
  1                                    | (4n + 1)/5
  2                                    | (6n - 2)/5
  3                                    | (4n + 3)/5
  4                                    | (6n - 4)/5

]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\noindent</Alt>
In his article, Timothy P. Keller shows that a permutation of this type
cannot have infinitely many cycles of any given finite length.

</Section>

<!-- #################################################################### -->

<Section Label="sec:DeterminantAndSign">
<Heading>Determinant and sign</Heading>

<ManSection>
  <Meth Name="Determinant" Arg="g" Label="g"/>
  <Meth Name="Determinant" Arg="g, S" Label="g, S"/>
  <Returns>
    The determinant of the bijective rcwa mapping&nbsp;<A>g</A>.
  </Returns>
  <Description>
    The <E>determinant</E> of an affine mapping <M>n \mapsto (an+b)/c</M>
    whose source is a residue class <M>r(m)</M> is defined by <M>b/|a|m</M>.
    This definition is extended additively to determinants of rcwa mappings
    and their restrictions to unions of residue classes. <P/>

    Using the notation from the definition of an rcwa mapping,
    the <E>determinant</E> det(<M>\sigma</M>) of an rcwa mapping
    <M>\sigma</M> is given by
    <Alt Not="LaTeX">
      (see LaTeX version of the manual).
    </Alt> 
    <Alt Only="LaTeX">
      <Display>
        \frac{1}{m}
        \left( \sum_{r(m) \in R/mR} \frac{b_{r(m)}}{|a_{r(m)}|} \right).
      </Display>
    </Alt>
    The determinant mapping is an epimorphism from the group of all
    class-wise order-preserving bijective rcwa mappings of <M>\Z</M>
    to <M>(\Z,+)</M>, see&nbsp;<Cite Key="Kohl05"/>, Theorem&nbsp;2.11.9.
    <P/>

    If a residue class union&nbsp;<A>S</A> is given as an additional
    argument, the method returns the determinant of the restriction
    of <A>g</A> to&nbsp;<A>S</A>.
<Example>
<![CDATA[
gap> List([ClassTransposition(0,4,5,12),ClassShift(3,7)],Determinant);
[ 0, 1 ]
gap> Determinant(ClassTransposition(0,4,5,12)*ClassShift(3,7)^100);   
100
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Sign" Arg="g" Label="g"/>
  <Returns>
    The sign of the bijective rcwa mapping&nbsp;<A>g</A>.
  </Returns>
  <Description>
    Using the notation from the definition of an rcwa mapping,
    the <E>sign</E> of a bijective rcwa mapping&nbsp;<M>\sigma</M>
    of&nbsp;<M>\Z</M> is defined by
    <Alt Not="LaTeX">
      (see LaTeX version of the manual).
    </Alt> 
    <Alt Only="LaTeX">
      <Display>
        (-1)^{\displaystyle{{\rm det}(\sigma) + \frac{1}{m}
        \left(
          \sum_{r(m): \ a_{r(m)} &lt; 0} (m - 2r)
        \right)}}.
      </Display>
    </Alt>
    The sign mapping is an epimorphism from RCWA(<M>\Z</M>) to the group
    <M>\Z^\times</M> of units of&nbsp;<M>\Z</M>,
    see&nbsp;<Cite Key="Kohl05"/>, Theorem&nbsp;2.12.8.
    Therefore the kernel of the sign mapping is a normal subgroup
    of RCWA(<M>\Z</M>) of index&nbsp;2.
<Example>
<![CDATA[
gap> List([ClassTransposition(3,4,2,6),ClassShift(0,3),ClassReflection(2,5)],Sign);
[ 1, -1, -1 ]
gap> Sign (ClassTransposition(3,4,2,6)*ClassShift(0,3)*ClassReflection(2,5));
1
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:PropertiesDerivedFromCoefficients">
<Heading>Attributes and properties derived from the coefficients</Heading>

<Index Key="Multiplier" Subkey="f"><C>Multiplier</C></Index>
<Index Key="Mult" Subkey="f"><C>Mult</C></Index>
<Index Key="Divisor" Subkey="f"><C>Divisor</C></Index>
<Index Key="Div" Subkey="f"><C>Div</C></Index>
<Index Key="PrimeSet" Subkey="f"><C>PrimeSet</C></Index>
<Index Key="integral" Subkey="definition">integral</Index>
<Index Key="rcwa mapping" Subkey="integral">rcwa mapping</Index>
<Index Key="IsIntegral" Subkey="f"><C>IsIntegral</C></Index>
<Index Key="balanced" Subkey="definition"><C>balanced</C></Index>
<Index Key="rcwa mapping" Subkey="balanced">rcwa mapping</Index>
<Index Key="IsBalanced" Subkey="f"><C>IsBalanced</C></Index>
<Index Key="rcwa mapping"
       Subkey="class-wise order-preserving">rcwa mapping</Index>
<Index Key="IsClassWiseOrderPreserving" Subkey="f">
  <C>IsClassWiseOrderPreserving</C>
</Index>

A number of basic attributes and properties of an rcwa mapping are derived
immediately from the coefficients of its affine partial mappings. This holds
for example for the multiplier and the divisor. These two values are stored
as attributes <C>Multiplier</C> and <C>Divisor</C>, or in short <C>Mult</C>
resp. <C>Div</C>. The <E>prime set</E> of an rcwa mapping is the set of
prime divisors of the product of its modulus and its multiplier.
It is stored as an attribute <C>PrimeSet</C>.
An rcwa mapping is called <E>integral</E> if its divisor equals&nbsp;1.
An rcwa mapping is called <E>balanced</E> if its multiplier and divisor
have the same prime divisors. An integral mapping has the property
<C>IsIntegral</C> and a balanced mapping has the property <C>IsBalanced</C>.
An rcwa mapping of the ring of integers or of one of its semilocalizations
is called <E>class-wise order-preserving</E> if and only if all coefficients
<M>a_{r(m)}</M> in the numerators of the affine partial mappings are
positive. The corresponding property is <C>IsClassWiseOrderPreserving</C>.

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Example>
<![CDATA[
gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
gap> IsBijective(u);; Display(u);

Bijective rcwa mapping of Z with modulus 5

                n mod 5                |                 n^f
---------------------------------------+--------------------------------------
  0                                    | 3n/5
  1                                    | (9n + 1)/5
  2                                    | (3n - 1)/5
  3                                    | (9n - 2)/5
  4                                    | (9n + 4)/5

gap> Multiplier(u);
9
gap> Divisor(u);
5
gap> PrimeSet(u);
[ 3, 5 ]
gap> IsIntegral(u) or IsBalanced(u);
false
gap> IsClassWiseOrderPreserving(u);
true
]]>
</Example>

</Section>

<!-- #################################################################### -->

<Section Label="sec:AffinePartialMappings">
<Heading>Functionality related to the affine partial mappings</Heading>

<ManSection>
  <Attr Name="LargestSourcesOfAffineMappings" Arg="f" Label="f"/>
  <Returns>
    The coarsest partition of <C>Source(<A>f</A>)</C> on whose
    elements the rcwa mapping&nbsp;<A>f</A> is affine.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> LargestSourcesOfAffineMappings(ClassShift(3,7));
[ Z \ 3(7), 3(7) ]
gap> LargestSourcesOfAffineMappings(ClassReflection(0,1));
[ Integers ]
gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
gap> List( [ u, u^-1 ], LargestSourcesOfAffineMappings );
[ [ 0(5), 1(5), 2(5), 3(5), 4(5) ], [ 0(3), 1(3), 2(9), 5(9), 8(9) ] ]
gap> kappa := ClassTransposition(2,4,3,4) * ClassTransposition(4,6,8,12)
>           * ClassTransposition(3,4,4,6);; SetName(kappa,"kappa");
gap> LargestSourcesOfAffineMappings(kappa);
[ 2(4), 1(4) U 0(12), 3(12) U 7(12), 4(12), 8(12), 11(12) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="Multpk" Arg="f, p, k" Label="f, p, k"/>
  <Returns>
    The union of the residue classes <M>r(m)</M> such that
    <M>p^k||a_{r(m)}</M> if <M>k \geq 0</M>, and the union of the residue
    classes <M>r(m)</M> such that <M>p^k||c_{r(m)}</M> if <M>k \leq 0</M>.
    In this context, <M>m</M> denotes the modulus and <M>a_{r(m)}</M>
    and <M>c_{r(m)}</M> denote the coefficients of&nbsp;<A>f</A> as
    introduced in the definition of an rcwa mapping.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> [ Multpk(T,2,-1), Multpk(T,3,1) ];
[ Integers, 1(2) ]
gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
gap> [ Multpk(u,3,0), Multpk(u,3,1), Multpk(u,3,2), Multpk(u,5,-1) ];
[ [  ], 0(5) U 2(5), Z \ 0(5) U 2(5), Integers ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="FixedPointsOfAffinePartialMappings" Arg="f" Label="f"/>
  <Returns>
    A list of the sets of fixed points of the affine partial mappings of
    the rcwa mapping&nbsp;<A>f</A> in the quotient field of its source.
  </Returns>
  <Description>
    The returned list contains entries for the restrictions
    of&nbsp;<A>f</A> to all residue classes modulo <C>Mod(<A>f</A>)</C>.
    A list entry can either be an empty set, the source of&nbsp;<A>f</A>
    or a set of cardinality&nbsp;1. The ordering of the entries corresponds
    to the ordering of the residues in
    <C>AllResidues(Source(<A>f</A>),<A>m</A>)</C>.
<Example>
<![CDATA[
gap> FixedPointsOfAffinePartialMappings(ClassShift(0,2));
[ [  ], Rationals ]
gap> List([1..3],k->FixedPointsOfAffinePartialMappings(T^k));
[ [ [ 0 ], [ -1 ] ], [ [ 0 ], [ 1 ], [ 2 ], [ -1 ] ], 
  [ [ 0 ], [ -7 ], [ 2/5 ], [ -5 ], [ 4/5 ], [ 1/5 ], [ -10 ], [ -1 ] ] ]
]]>
</Example>
  </Description>
</ManSection>

<Index Key="SetOnWhichMappingIsClassWise" Subkey="OrderPreserving">
  <C>SetOnWhichMappingIsClassWise</C>
</Index>
<Index Key="SetOnWhichMappingIsClassWise" Subkey="Constant">
  <C>SetOnWhichMappingIsClassWise</C>
</Index>
<Index Key="SetOnWhichMappingIsClassWise" Subkey="OrderReversing">
  <C>SetOnWhichMappingIsClassWise</C>
</Index>

There are attributes <C>SetOnWhichMappingIsClassWise</C>
(<C>-OrderPreserving</C>, <C>-Constant</C>, <C>-OrderReversing</C>) which
store the union of the residue classes (mod&nbsp;<C>Mod(<A>f</A>)</C>) on
which an rcwa mapping&nbsp;<A>f</A> of&nbsp;<M>\Z</M> or of
a semilocalization thereof is class-wise order-preserving, class-wise
constant resp. class-wise order-reversing.

<Example>
<![CDATA[
gap> List([ClassTransposition(1,2,0,4),ClassShift(2,3),ClassReflection(2,5)],
>          SetOnWhichMappingIsClassWiseOrderPreserving );
[ Integers, Integers, Z \ 2(5) ]
gap> SetOnWhichMappingIsClassWiseConstant(RcwaMapping([[2,0,1],[0,4,1]]));
1(2)
gap> SetOnWhichMappingIsClassWiseOrderReversing(ClassReflection(13,17));
13(17)
]]>
</Example>

</Section>

<!-- #################################################################### -->

<Section Label="sec:TransGraphMat">
<Heading>Transition graphs and transition matrices</Heading>

<ManSection>
  <Oper Name="TransitionGraph" Arg="f, m" Label="f, m"/>
  <Returns>
    The transition graph of the rcwa mapping&nbsp;<A>f</A>
    for modulus&nbsp;<A>m</A>.
  </Returns>
  <Description>
    <Index Key="rcwa mapping" Subkey="transition graph">rcwa mapping</Index>
    <Alt Only="LaTeX">\noindent</Alt>
    The <E>transition graph</E> <M>\Gamma_{f,m}</M> of&nbsp;<M>f</M> for
    modulus&nbsp;<M>m</M> is defined as follows:
    <Enum>
      <Item>
        The vertices are the residue classes (mod&nbsp;<M>m</M>).
      </Item>
      <Item>
        There is an edge from <M>r_1(m)</M> to <M>r_2(m)</M> if and only if
        there is some <M>n \in r_1(m)</M> such that
        <M>n^f \in r_2(m)</M>.
      </Item>
    </Enum>
    The assignment of the residue classes (mod&nbsp;<M>m</M>) to the
    vertices of the graph corresponds to the ordering of the residues in
    <C>AllResidues(Source(<A>f</A>),<A>m</A>)</C>.
    The result is returned in the format used by the package
    <Package>GRAPE</Package>.
<Example>
<![CDATA[
gap> TransitionGraph(ClassShift(0,1),6);
rec( isGraph := true, order := 6, group := Group(()), 
  schreierVector := [ -1, -2, -3, -4, -5, -6 ], 
  adjacencies := [ [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 1 ] ], 
  representatives := [ 1, 2, 3, 4, 5, 6 ], names := [ 1, 2, 3, 4, 5, 6 ] )
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="OrbitsModulo" Arg="f, m" Label="f, m"/>
  <Returns>
    The partition of <C>AllResidues(Source(<A>f</A>),<A>m</A>)</C>
    corresponding to the weakly connected components of the transition
    graph of the rcwa mapping&nbsp;<A>f</A> for modulus&nbsp;<A>m</A>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> OrbitsModulo(ClassTransposition(0,2,1,4),8);
[ [ 0, 1, 4 ], [ 2, 5, 6 ], [ 3 ], [ 7 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name ="FactorizationOnConnectedComponents"
        Arg = "f, m" Label="f, m"/>
  <Returns>
    The set of restrictions of the rcwa mapping&nbsp;<A>f</A> to the
    weakly connected components of its transition graph <M>\Gamma_{f,m}</M>.
  </Returns>
  <Description>
    The product of the returned mappings is&nbsp;<A>f</A>.
    They have pairwise disjoint supports, hence any two of them commute.
<Example>
<![CDATA[
gap> sigma :=   ClassTransposition(1,4,2,4)  * ClassTransposition(1,4,3,4)
>             * ClassTransposition(3,9,6,18) * ClassTransposition(1,6,3,9);;
gap> List(FactorizationOnConnectedComponents(sigma,36),Support);
[ 33(36) U 34(36) U 35(36), 9(36) U 10(36) U 11(36), 
  <union of 23 residue classes (mod 36)> \ [ -6, 3 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="TransitionMatrix" Arg="f, m" Label="f, m"/>
  <Returns>
    The transition matrix of the rcwa mapping&nbsp;<A>f</A> for
    modulus&nbsp;<A>m</A>.
  </Returns>
  <Description>
    Let <M>M</M> be this matrix. Then for any two residue classes <M>r_1(m),
    r_2(m) \in R/mR</M>, the entry <M>M_{r_1(m),r_2(m)}</M> is defined by
    <Alt Only="LaTeX">
      <Display>
        <![CDATA[
          M_{r_1(m),r_2(m)} \ := \ \displaystyle{\frac{|R/mR|}{|R/\hat{m}R|}}
          \cdot \left|\left\{r(\hat{m}) \in R/\hat{m}R | \ r \in r_1(m)
          \wedge r^f \in r_2(m)\right\}\right|,
        ]]>
      </Display>
      where <M>\hat{m}</M> is the product of <A>m</A> and the square of the
      modulus of&nbsp;<A>f</A>.
    </Alt>
    <Alt Not="LaTeX">
      (See LaTeX version of the manual.)
    </Alt>
    The assignment of the residue classes (mod&nbsp;<A>m</A>) to the rows and
    columns of the matrix corresponds to the ordering of the residues in
    <C>AllResidues(Source(<A>f</A>),<A>m</A>)</C>. <P/>

    The transition matrix is a weighted adjacency matrix of the corresponding
    transition graph <C>TransitionGraph(<A>f</A>,<A>m</A>)</C>.
    The sums of the rows of a transition matrix are always equal to&nbsp;1.
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> Display(TransitionMatrix(T^3,3));
[ [  1/8,  1/4,  5/8 ],
  [    0,  1/4,  3/4 ],
  [    0,  3/8,  5/8 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Sources" Arg="f"  Label = "f"/>
  <Returns>
    A list of unions of residue classes modulo the modulus&nbsp;<M>m</M>
    of the rcwa mapping&nbsp;<A>f</A>, as described below.
  </Returns>
  <Description>
    The returned list contains an entry for any strongly
    connected component of the transition graph of&nbsp;<A>f</A> for
    modulus&nbsp;<C>Mod(<A>f</A>)</C> which has only outgoing edges.
    The list entry corresponding to such a component
    is the union of the vertices belonging to it.
<Example>
<![CDATA[
gap> Sources(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));
[ 0(4) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Sinks" Arg="f"  Label = "f"/>
  <Returns>
    (See <Ref Attr="Sources" Label="f"/>, with <Q>outgoing</Q> replaced
    by <Q>ingoing</Q>.)
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> Sinks(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));  
[ 1(4) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Loops" Arg="f"  Label = "f"/>
  <Returns>
    The list of non-isolated vertices of the transition graph of the
    rcwa mapping&nbsp;<A>f</A> for modulus <C>Mod(<A>f</A>)</C>
    which carry a loop.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> Loops(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));
[ 0(4), 1(4) ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:Trajectories">
<Heading>Trajectories</Heading>

<ManSection>
  <Meth Name="Trajectory" Arg="f, n, length" Label="f, n, length"/>
  <Meth Name="Trajectory" Arg="f, n, length, m" Label="f, n, length, m"/>
  <Meth Name="Trajectory" Arg="f, n, terminal" Label="f, n, terminal"/>
  <Meth Name="Trajectory" Arg="f, n, terminal, m" Label="f, n, terminal, m"/>
  <Returns>
    The first <A>length</A> iterates in the trajectory of the
    rcwa mapping&nbsp;<A>f</A> starting at&nbsp;<A>n</A>, resp. the
    initial part of the trajectory of the rcwa mapping&nbsp;<A>f</A>
    starting at&nbsp;<A>n</A> which ends at the first occurence of an
    iterate in the set <A>terminal</A>. If the argument <A>m</A> is given,
    the iterates are reduced (mod&nbsp;<A>m</A>).
  </Returns>
  <Description>
    To save memory when computing long trajectories containing huge
    iterates, the reduction (mod&nbsp;<A>m</A>) is done each time before
    storing an iterate.
    In place of the ring element&nbsp;<A>n</A>, the methods also accept
    a finite set of ring elements or a union of residue classes.
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> Trajectory(T,27,16); Trajectory(T,27,25,5);
[ 27, 41, 62, 31, 47, 71, 107, 161, 242, 121, 182, 91, 137, 206, 103, 155 ]
[ 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 3, 0, 3, 0, 0, 3, 0, 3, 0, 0, 3 ]
gap> Trajectory(T,15,[1]); Trajectory(T,15,[1],2);
[ 15, 23, 35, 53, 80, 40, 20, 10, 5, 8, 4, 2, 1 ]
[ 1, 1, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1 ]
gap> Trajectory(T,ResidueClass(Integers,3,0),Integers);
[ 0(3), 0(3) U 5(9), 0(3) U 5(9) U 7(9) U 8(27), 
  <union of 20 residue classes (mod 27)>, <union of 73 residue classes (mod 
    81)>, Z \ 10(81) U 37(81), Integers ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Meth Name="Trajectory" Arg="f, n, length, whichcoeffs"
                          Label="f, n, length, whichcoeffs"/>
  <Meth Name="Trajectory" Arg="f, n, terminal, whichcoeffs"
                          Label="f, n, terminal, whichcoeffs"/>
  <Returns>
    Either the list <C>c</C> of triples of coprime coefficients such that
    for any&nbsp;<C>k</C> it holds that
    <C><A>n</A>&circum;(<A>f</A>&circum;(k-1)) =
    (c[k][1]*<A>n</A> + c[k][2])/c[k][3]</C> or the last entry of that list,
    depending on whether <A>whichcoeffs</A> is <C>"AllCoeffs"</C> or
    <C>"LastCoeffs"</C>.
  </Returns>
  <Description>
    The meanings of the arguments <A>length</A> and <A>terminal</A> are
    the same as in the methods for the operation <C>Trajectory</C>
    described above. In general, computing only the last coefficient triple
    (<A>whichcoeffs</A> = <C>"LastCoeffs"</C>) needs considerably less
    memory than computing the entire list.
<Example>
<![CDATA[
gap> Trajectory(T,27,[1],"LastCoeffs");
[ 36472996377170786403, 195820718533800070543, 1180591620717411303424 ]
gap> (last[1]*27+last[2])/last[3];
1
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="IncreasingOn" Arg="f" Label="f"/>
  <Attr Name="DecreasingOn" Arg="f" Label="f"/>
  <Returns>
    The union of all residue classes <M>r(m)</M> such that
    <M>|R/a_{r(m)}R| &gt; |R/c_{r(m)}R|</M> resp.
    <M>|R/a_{r(m)}R| &lt; |R/c_{r(m)}R|</M>, where <M>R</M> denotes the
    source, <M>m</M> the modulus and <M>a_{r(m)}</M>, <M>b_{r(m)}</M>
    and <M>c_{r(m)}</M> the coefficients of&nbsp;<A>f</A> as
    introduced in the definition of an rcwa mapping.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> List([1..3],k->IncreasingOn(T^k));
[ 1(2), 3(4), 3(4) U 1(8) U 6(8) ]
gap> List([1..3],k->DecreasingOn(T^k));
[ 0(2), Z \ 3(4), 0(4) U 2(8) U 5(8) ]
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
gap> List([-2..2],k->IncreasingOn(a^k));
[ Z \ 1(8) U 7(8), 0(2), [  ], Z \ 0(3), 1(9) U 4(9) U 5(9) U 8(9) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="GluckTaylorInvariant" Arg="a" Label="a"/>
  <Returns>
    The invariant introduced in&nbsp;<Cite Key="GluckTaylor02"/>. This is
    <M>(\sum_{i=1}^l a_i \cdot a_{i \mod l + 1})/(\sum_{i=1}^l a_i^2)</M>,
    where <M>l</M> denotes the length of&nbsp;<A>a</A>.
  </Returns>
  <Description>
    The argument <A>a</A> must be a list of integers.
    In&nbsp;<Cite Key="GluckTaylor02"/> it is shown that if <A>a</A>
    is a trajectory of the `original' Collatz mapping <M>n</M>
    <M>\mapsto</M> (<M>n/2</M> if <M>n</M> even, <M>3n+1</M> if
    <M>n</M> odd) starting at an odd integer <M>\geq 3</M> and ending
    at&nbsp;1, then the invariant lies in the interval <M>]9/13,5/7[</M>.
<Example>
<![CDATA[
gap> C := RcwaMapping([[1,0,2],[3,1,1]]);;
gap> List([3,5..49],n->Float(GluckTaylorInvariant(Trajectory(C,n,[1]))));
[ 0.701053, 0.696721, 0.708528, 0.707684, 0.706635, 0.695636, 0.711769,
  0.699714, 0.707409, 0.693833, 0.710432, 0.706294, 0.714242, 0.699935,
  0.714242, 0.705383, 0.706591, 0.698198, 0.712222, 0.714242, 0.709048,
  0.69612, 0.714241, 0.701076 ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:Localizations">
<Heading>
  Localizations of rcwa mappings of the integers
</Heading>

<ManSection>
  <Func Name="LocalizedRcwaMapping"     Arg="f, p"  Label = "f, p"/>
  <Func Name="SemilocalizedRcwaMapping" Arg="f, pi" Label = "f, pi"/>
  <Returns>
    The rcwa mapping of <M>\Z_{(p)}</M> resp. <M>\Z_{(\pi)}</M> with the
    same coefficients as the rcwa mapping <A>f</A> of&nbsp;<M>\Z</M>.
  </Returns>
  <Description>
    The argument <A>p</A> resp. <A>pi</A> must be a prime resp. a set
    of primes, and the argument&nbsp;<A>f</A> must be an rcwa mapping
    of&nbsp;<M>\Z</M> whose modulus is a power of&nbsp;<A>p</A>, resp.
    whose modulus has only prime divisors which lie in&nbsp;<A>pi</A>.
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> Cycle(LocalizedRcwaMapping(T,2),131/13);
[ 131/13, 203/13, 311/13, 473/13, 716/13, 358/13, 179/13, 275/13, 419/13, 
  635/13, 959/13, 1445/13, 2174/13, 1087/13, 1637/13, 2462/13, 1231/13, 
  1853/13, 2786/13, 1393/13, 2096/13, 1048/13, 524/13, 262/13 ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:ExtractingRoots">
<Heading>
  Extracting roots of rcwa mappings
</Heading>

<ManSection>
  <Meth Name="Root" Arg="f, k" Label = "f, k"/>
  <Returns>
    An rcwa mapping <C>g</C> such that <C>g&circum;<A>k</A>=<A>f</A></C>,
    provided that such a mapping exists and that there is a method available
    which can determine it.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> Root(ClassTransposition(0,2,1,2),100);
<bijective rcwa mapping of Z with modulus 8>
gap> last^100 = ClassTransposition(0,2,1,2);
true
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:NonBijectiveMappings">
<Heading>
  Special functions for non-bijective mappings
</Heading>

<ManSection>
  <Attr Name="RightInverse" Arg="f" Label = "f"/>
  <Returns>
    A right inverse of the injective rcwa mapping&nbsp;<A>f</A>,
    i.e. a mapping <M>g</M> such that <A>f</A><M>g</M>&nbsp;=&nbsp;1.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> twice := RcwaMapping([[2,0,1]]);
Rcwa mapping of Z: n -> 2n
gap> twice * RightInverse(twice);
IdentityMapping( Integers )
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="CommonRightInverse" Arg="l, r" Label="l, r"/>
  <Returns>
    A mapping <M>d</M> such that <A>l</A><M>d</M> = <A>r</A><M>d</M> = 1.
  </Returns>
  <Description>
    The mappings <A>l</A> and <A>r</A> must be injective, and their images
    must form a partition of their source.
<Example>
<![CDATA[
gap> twice := RcwaMapping([[2,0,1]]); twiceplus1 := RcwaMapping([[2,1,1]]);
Rcwa mapping of Z: n -> 2n
Rcwa mapping of Z: n -> 2n + 1
gap> Display(CommonRightInverse(twice,twiceplus1));

Rcwa mapping of Z with modulus 2

                n mod 2                |                 n^f
---------------------------------------+--------------------------------------
  0                                    | n/2
  1                                    | (n - 1)/2

]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="ImageDensity" Arg="f" Label="f"/>
  <Returns>
    The <E>image density</E> of the rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    In the notation introduced in the definition of an rcwa mapping,
    the <E>image density</E> of an rcwa mapping&nbsp;<M>f</M> is defined by
    <Alt Not="LaTeX">1/m</Alt><Alt Only="LaTeX"><M>\frac{1}{m}</M></Alt>
    <M>\sum_{r(m) \in R/mR} |R/c_{r(m)}R|/|R/a_{r(m)}R|</M>.
    The image density of an injective rcwa mapping is <M>\leq 1</M>, and
    the image density of a surjective rcwa mapping is <M>\geq 1</M>
    (this can be seen easily). Thus in particular the image density of
    a bijective rcwa mapping is&nbsp;1.
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> List( [ T, ClassShift(0,1), RcwaMapping([[2,0,1]]) ], ImageDensity );
[ 4/3, 1, 1/2 ]
]]>
</Example>
  </Description>
</ManSection>

<Index Key="InjectiveAsMappingFrom" Subkey="f">
  <C>InjectiveAsMappingFrom</C>
</Index>

Given an rcwa mapping <C>f</C>, the function <C>InjectiveAsMappingFrom</C>
returns a set <C>S</C> such that the restriction of <C>f</C> to&nbsp;<C>S</C>
is injective, and such that the image of <C>S</C> under&nbsp;<C>f</C> is the
entire image of&nbsp;<C>f</C>.

<Example>
<![CDATA[
gap> InjectiveAsMappingFrom(T);
0(2)
]]>
</Example>

</Section>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<!-- #################################################################### -->

<Section Label="sec:ProbabilisticGuesses">
<Heading>
  Probabilistic guesses on the behaviour of trajectories
</Heading>

This section describes some functionality for getting <Q>educated guesses</Q>
on the overall behaviour of the trajectories of a given rcwa mapping.
Its contents have deliberately been separated from the documentation of the
non-probabilistic functionality related to trajectories of rcwa mappings.

<ManSection>
  <Oper Name="LikelyContractionCentre"
        Arg="f, maxn, bound" Label="f, maxn, bound"/>
  <Returns> A list of ring elements (see below). </Returns>
  <Description>
    This operation tries to compute the <E>contraction centre</E> of the
    rcwa mapping <A>f</A>. Assuming its existence this is the unique finite
    subset <M>S_0</M> of the source of&nbsp;<A>f</A> on which <A>f</A>
    induces a permutation and which intersects nontrivially with any
    trajectory of&nbsp;<A>f</A>. The mapping&nbsp;<A>f</A> is assumed
    to be <E>contracting</E>, i.e. to have such a contraction centre.
    As in general contraction centres are likely not computable, the methods
    for this operation are probabilistic and may return wrong results.
    The argument <A>maxn</A> is a bound on the starting
    value and <A>bound</A> is a bound on the elements of the trajectories
    to be searched.
    If the limit <A>bound</A> is exceeded, an Info message on Info
    level&nbsp;3 of <C>InfoRCWA</C> is given.
<Example>
<![CDATA[
gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
gap> S0 := LikelyContractionCentre(T,100,1000);
#I  Warning: `LikelyContractionCentre' is highly probabilistic.
The returned result can only be regarded as a rough guess.
See ?LikelyContractionCentre for information on how to improve this guess.
[ -136, -91, -82, -68, -61, -55, -41, -37, -34, -25, -17, -10, -7, -5, -1, 0, 
  1, 2 ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="GuessedDivergence" Arg="f" Label="f"/>
  <Returns>
    A floating point value which is intended to be a rough guess on how fast
    the trajectories of the rcwa mapping&nbsp;<A>f</A> diverge (return value
    greater than&nbsp;1) or converge (return value smaller than&nbsp;1).
  </Returns>
  <Description>
    Nothing particular is guaranteed.
<Example>
<![CDATA[
gap> GuessedDivergence(T);                                       
#I  Warning: GuessedDivergence: no particular return value is guaranteed.
0.866025
]]>
</Example>
  </Description>
</ManSection>

</Section>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<!-- #################################################################### -->

<Section Label="sec:CategoriesOfRcwaMappings">
<Heading>The categories and families of rcwa mappings</Heading>

<ManSection>
  <Filt Name="IsRcwaMapping" Arg="f" Label="f"/>
  <Filt Name="IsRcwaMappingOfZ" Arg="f" Label="f"/>
  <Filt Name="IsRcwaMappingOfZ_pi" Arg="f" Label="f"/>
  <Filt Name="IsRcwaMappingOfGFqx" Arg="f" Label="f"/>
  <Returns>
    <C>true</C> if <A>f</A> is an rcwa mapping resp.
    an rcwa mapping of the ring of integers resp.
    an rcwa mapping of a semilocalization of the ring of integers resp.
    an rcwa mapping of a polynomial ring in one variable over a finite field,
    and <C>false</C> otherwise.
  </Returns>
  <Description>
    Often the same methods can be used for rcwa mappings of the ring of
    integers and of its semilocalizations. For this reason there is
    a category <C>IsRcwaMappingOfZOrZ&uscore;pi</C> which is the union of
    <C>IsRcwaMappingOfZ</C> and <C>IsRcwaMappingOfZ&uscore;pi</C>.
    <Index Key="IsRcwaMappingOfZOrZ_pi" Subkey="f">
      <C>IsRcwaMappingOfZOrZ&uscore;pi</C>
    </Index>
    The internal representation of rcwa mappings is called
    <C>IsRcwaMappingStandardRep</C>.
    <Index Key="IsRcwaMappingStandardRep">
      <C>IsRcwaMappingStandardRep</C>
    </Index>
  </Description>
</ManSection>

<ManSection>
  <Func Name="RcwaMappingsFamily" Arg="R" Label="R"/>
  <Returns>
    The family of rcwa mappings of the ring&nbsp;<A>R</A>.
  </Returns>
</ManSection>

</Section>

<!-- #################################################################### -->

</Chapter>

<!-- #################################################################### -->
