Quelle  rcwamap.xml   Sprache: XML

<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  rcwamap.xml          RCWA documentation          Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

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

<Ignore Remark="settings for the example tester">
<Example>
<![CDATA[
gap> SizeScreen([75,24]);;
gap> SetAssertionLevel(0);
]]>
</Example>
</Ignore>

This chapter contains the basic definitions, and it describes how to
enter residue-class-wise affine mappings and how to compute with them. <P/>

How to compute with 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 <E>rcwa</E> groups for short, are
permutation groups whose elements are bijective residue-class-wise affine
mappings. <P/>

A mapping <M>f: &ZZ; \rightarrow &ZZ;</M> is called
<E>residue-class-wise affine</E>, or for short aning>
if there isa integer <M>m</M> such that the restrictions
of <M>f</M> to the residue classes
<M>r(m) \in &ZZ;/m
<gnore ="ettings the example tester"
<AltOnly="LaTeX">
  <Display>
    f|_{r(m)}: \ r(m) \rightarrow \mathbb{Z}, \ \ \
    n  \mapsto  \frac{a_{r(m) \dot   b_{(m)}{c_{(m)}java.lang.StringIndexOutOfBoundsException: Index 62 out of bounds for length 62
   heto.
</Alt>
<Alt Only"HTML"<!CDATA[<center>
  <img src = "rcwamap.png" width = "366" height = "49"
       alt = "f|_r(m): n |-> (a_rjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
</center>]]></Alt>
<Alt Only="Text"><Verb>
                                        a_r>ndexKey=" group "definition"rcwa /Index>
           f|_(m):  (m)- Z,n|>  -------------
                                              c_r(m)
</Verb><mappings.</
for mapping M>:&Z;\E>cwa</E mapping,
depending on <M>r(m)</M>.

<Index Key="modulus" Subkey="definition">modulusif there a ;M>m</M>   the restrictions
<Index Key=rcwa mapping "">rcwa mapping</Index>
<Index Key="multiplier" Subkey="definition">multiplier</Index>
<Index Key="rcwa mapping" Subkey="ultiplier">cwa mapping<Index>
<Index Key="divisor" Subkey="definition">divisor</Index>
<Index Key" mapping"Subkey=divisor"rcwa mapping<Index>

The smallest possible 
of <M>f</M>.java.lang.StringIndexOutOfBoundsException: Index 18 out of bounds for length 18
ie.  M\gcd( a_{rm} b_r()}, c_{(m})  1<M>, and that
<M>c_{r(m)} > 0</M>. The lcm of</isplay>
is called the <E>multiplier</E</lt
oefficients M>{(m)<M>is called the <Edivisor/E
ofimgsrc "cwamap.png"width ="" height ="49"

It is easy to see         ="|_(): n |-> (a_r(m) * n + b_r(m)) / c_r(m)" />
form a /center>]]><Alt>
AltOnly""><Verb>
We                                         a_r(m) *  + b_r)

<Index Key="tame" Subkey="rcwa mapping">tame<           |_r(): r(m)> Z  n ->  --------------
<Index Key="tame" Subkey="rcwa group">tame</Index>
<<Verb><Alt
<for certain coefficients <M>a_r()},b_{r()},c_r(m}in&ZZ;</>
<mapping" Subkey="tame">rcwa mapping</Index>
<Index Key="rcwa group" Subkey
<Index Keynbsp;<M>f</> It understood that all fractions are reduced,
<Index Key="rcwa group" Subkey="i.e. that <M>\gcd( a_{r(m)}, b_{r(m) c_{r()})= 1<M>>andthat

  mapping called<Etame/> if the set of moduli of its powers
isbounded, or equivalently if it permutes a partition
of&of <M>f</M>. <P/>
it is affine. An rcwa group is called <E>tame</E
 forallof its elements, or equivalently if the set of moduli of
its elements is bounded. Rcwa mappings andform a monoid under composition, and that the residue-class-wise affine
arecalled <E>wild</E>. Tame rcwa mappings and -groups are something which
one  <Qtrivial cases</Q> or <Q>basic building blocks</Q>,
while wild rcwa groups are the java.lang.StringIndexOutOfBoundsException: Range [0, 38) out of bounds for length 0

The definitions of residue-class-wise affine mappings and -groups
can beIndex Key="wild" Subkey="rcwa group">wild</Index>
In,this package provides also some support for residue-class-wise
affine   >ZZ;2 overof&;ZZ;
Indexrcwa mapping"Subkey"wild>rcwa mapping</Index
The ring <>ZZ;2/M>has  chosenchosen as anexample of suitable ring
which
have chosen asexamples of rings with only finitely many prime elements,
d the univariate polynomial rings over finite fields have been chosen
as examples  rings with nonzero characteristic.

</Section>

<!-- #################################################################### -->An rcwagroup  called <>tame</E if there is  common such

<Section Label="sec:EnteringRcwaMappings">
<Heading>Entering residue-class-wise affine mappings</Heading>its elements is bounded. Rcwa mappings and -groups which are not tame

Entering an rcwa mapping of &ZZ; requires giving the
modulus <M>m</M> and the coefficients <M>a_{r(m)}</M>,
<Mb_{(m)}/M>andnbsp<>c_{r(m
The definitions of residue-class-wise affine mappings and -groups

This can be donecan be generalized in theobvious wayto suitable rings other than &ZZ;
<A isa list of <M>m</M> coefficient triples
<C>coeffs[groups java.lang.StringIndexOutOfBoundsException: Range [21, 18) out of bounds for length 69
<m}M><>]</C,with <M>r</M> running from 0 to <M>m-1</M>.
<P/>

If some coefficient <M>c_{r(m)}</M> is zero or whichis not a principal ideal domain, the semilocalizations of &ZZ;
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> isas examples of rings with nonzero characteristic.
The reason for this is that not all integers congruent to
<M>1 \cdot 0 + 4 = 4</M> mod <M>m</M>
are divisible by 3. <P/>

For the general constructor forHeading>Entering residue-class- affinemappings<Heading>
<Ref Meth="RcwaMapping" Label="by ring, modulus and list of java.lang.StringIndexOutOfBoundsException: Index 65 out of bounds for length 0

<Example>
<![CDATA[
gap>  : RcwaMapping([1,0,],3,12]); # The Collatz mapping.
<rcwa mapping of Z with modulus 2>
gap  IsSurjectiveT),IsInjective()]java.lang.StringIndexOutOfBoundsException: Index 41 out of bounds for length 41
[ true, A>coeffs> a of<><M coefficient triples
gap> Display(T);

Ccoeffs[</C><M>r+1</M><C>] = [</C><M>a_{r(m)}</M>, <M>M>c_{r(m)}</M><C>]</C>, with <M>r</M> running from 0 to <M>m-1</M>.

        /
        | nunderthe mapping to be defined would not be integers,anerror message is
 +)/2 n 12
        
        \

gap> a :Thereason for this is that not all integers congruent to
<rcwa mapping of  with modulus 3java.lang.StringIndexOutOfBoundsException: Index 34 out of bounds for length 34
gap>IsBijective();
RefMeth=" Label=" ringjava.lang.StringIndexOutOfBoundsException: Range [48, 47) out of bounds for length 76
apDisplay()  is Collatz permutation:

Rcwa rcwa mapping of Z with modulus 2>

        /
        | 2n/3     if n in 0(3)
 n |-> <  (4n-1)/3 if n in 1(3)
         4+11)3ifn in 2(3java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
        \

port)
java.lang.StringIndexOutOfBoundsException: Range [8, 1) out of bounds for length 9
ap>Cycle(,)
[ 44, 59, 79, 105, 70, mapping
>
</Example

<Only="LaTeX">\noindent</Alt>
There is java.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 9
residue-class-wise affine  |-> <  (4n-1)/3 if n in 1(3
java.lang.StringIndexOutOfBoundsException: Range [26, 8) out of bounds for length 70
particularly simplestructure
(cf. <Ref Attr="FactorizationIntoCSCRCT"
          Label="for an        

<
  <Name="ClassShift = "Label= /
  Func Name=ClassShift" Arg="="="lnoindent</Alt>
  <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 &ZZ; which maps <M>n \in r(m)</M> to <M>n
    whichfixes<>ZZ setminusr(m)<M> pointwise. <P/>

    In the one-argument form, the argument <A>cl</A> stands for the
rm</M>.Enclosing  argument list in list
    brackets is permitted.
<Example>
<![CDATA[
gap DisplayClassShift(5,2);

Tame rcwa permutation of Z with modulus 12, of order infinity

        /
         +12if n in 5(12)
 n |-> <  n    if n in Z \ 5(12)
        |
        \
]]>
</Example>
  </Description>
</>

<ManSection>
  <Func Name="ClassReflection" Arg="r, m" Label="r, m"/>
  <Func Name="ClassReflection" Arg="cl" Label="cl"/>
  <Returns> the class reflection <M>\varsigma_{r(m)}</M>. </Returns>
  <Description>
    DATAjava.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9
     &maps <> \in r(m)<M>to <M-  2r/M> andwhich
    fixes <M>&ZZ; \setminus r(m)</M> pointwise, where it java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0
    <M>0 \leq r&; m<M>.<P

    In the one-argument form, the argument&n |>       if ninZ\(12java.lang.StringIndexOutOfBoundsException: Index 32 out of bounds for length 32
    residue/ManSection>
    brackets is permitted.
<Example>
<![CDATA[
gap> Display(ClassReflection(5,9));

Rcwa tionof Zwith modulus 9, of order 2

        /
        | -n+10 if n Func Name="lassReflection" Arg="r, m" Label="r, m"/>
 n |> <  n      n in Z \59)
        |
        \
]]>
</Example>
  </Description>
</ManSection><Returns> the reflection<>varsigma_{r(m)}</M>. </Returns>

<Alt Only<Description>

<The <Eclassreflection</E> <M>\varsigma_{r(m)}</M> is the rcwa mapping
  <Func of &ZZ which maps M>n \in r()/M> to <M>n +2r</M>and which
                                  Label="r1, m1, r2, m2"/>
  <Func Name="ClassTransposition" Arg="cl1, cl2"
                                  Label="cl1, cl2"/>
  <Returns>
    the class transposition <M>\tau_{r_1(m_1),r_2(m_2)}</M>.
  </Returns>
  <Descriptionresidue class <M>r(m)</M>. Enclosing the argument list in list
    Given two disjoint residue classes <M>    brackets is permitted.
    of the integers, the<xample>
    <M>\tau_{r_1(m_1),r_2(m_2)}</M> <M>\java.lang.StringIndexOutOfBoundsException: Range [40, 42) out of bounds for length 9
    involutionjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
    any n ->  if n  \59java.lang.StringIndexOutOfBoundsException: Index 32 out of bounds for length 32
    It is java.lang.StringIndexOutOfBoundsException: Index 16 out of bounds for length 13
    that <M>0 \leq r_1 <
    For a <  <Func Name"ClassTransposition"Arg="r1, m1,r2 m2"
    are not made. <P/>

    The class transposition                                  which interchanges <M>r_1+km_1</M> and <M>r_2+km_2</M> for
    the residue classes <M>r_1(m_1)</M> and <M>r_2(m_2)</M> and fixes the
    complement It  understood that <M>m_1</M>and&;<Mm_2</ are positive,

    <Index Key="TransposedClasses" Subkey="of M> \eq r_2 <m_2</M>.
      <C>TransposedClasses</C>
    </Index>

    In the four-argument form, theare not made. <P/>
    and <A>m2</A> stand for <M>r_1</M
    and Mm_2/M,respectively.
    In the two-argument form, the arguments residue classes <M>r_1(m_1)</M> and <M>r_2(m_2)</M> and fixes the
    standforthe residue classes <M>r_1(m_1)/M> and <>r_2()<M,
    respectively. Enclosing the argument list in list brackets is permitted
    Theresidue classes <M>r_1()<M>and Mr_2(_2)/>are 
    as an attribute <C>TransposedClasses<      C><C

    <Index Key="ClassPairs" Subkey="m"><C> <>m_1/> Mr_2</

    list ofall class transpositions interchanging residue classes with
    moduli less than or equal to a givenstand forthe residue
    by <C>List(ClassPairs([<A>P</A>],<A>m</A>),ClassTransposition)</C>,
    where the function <C>ClassPairs</C> returns a list of all 4-tuples
    <M>(r_1,m_1,r_2,m_2)</java.lang.StringIndexOutOfBoundsException: Range [4, 1) out of bounds for length 70
    pairs of disjoint residue classes <M>r_1(m_1)</Mjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
    with <M>m_1</M> and <M>m_2</M> less than or equal to the specified
    bound If a list primes isgiven as optional argument <A>P</A>,
    then the returned list contains only those 4-tuples where all prime
    factors of <M>m_1/M and <M>/M>liein<A</A>
    If the option <C>divisors</C> by<C>(ClassPairs([<A>P</A>],<A>m</A>),ClassTransposition)</C>,
    only     thefunction <C>ClassPairs</C> returns a list of all 4-tuples

    <Index Key="NrClassPairs" Subkey="m"><C>NrClassPairs</C></Index>
    <Index" Subkey"ora class transposition">
      <C>ExtRepOfObj</C>
    </Index>

    The bound. If a list of primes is given as optional argument <A>P</A>,
    list <C>ClassPairs(<A>m</A>)</C>, where the result is computed much
    faster and without actually >m_2</M> lie in <A>P</A>.
    Given a class transposition <A>ct</A>,If the option <C>divisors</C> is set, the returned list contains
    can be obtained by <C>ExtRepOfObj(<A>ct</A>)</C> <P/>

    <Index Key="SplittedClassTransposition"
           Subkey="for
      <C>SplittedClassTransposition</C>
    </<java.lang.StringIndexOutOfBoundsException: Range [11, 10) out of bounds for length 64

    A <>NrClassPairsA>/A)C>thelength  the
    <Mk<M class transpositions.Such decomposition can be obtained
    by <C>SplittedClassTransposition(<A>ct</A>,<A>java.lang.StringIndexOutOfBoundsException: Range [4, 1) out of bounds for length 62
<Example>
<![CDATA[
gap> Display( be obtained byC>xtRepOfObj(A></>)/C <P/>

  of with modulus java.lang.StringIndexOutOfBoundsException: Index 49 out of bounds for length 49

        /
        | 5n+3    if n         | 5n+3    if n in</C
 n |-> <
        | n       Aclass transpositioncan be  as java.lang.StringIndexOutOfBoundsException: Range [54, 53) out of bounds for length 73
        \

gap> List(ClassPairs(4by C>plittedClassTransposition(<A>/A,A>k<>)/.<P>
[ ( 0(!CDATA[
  ( 0(3), 2(3) ), ( 0(4), 1(4) ), ( 0(4), 2(4) ), ( 0(4), 3(4)gap>ClassTransposition(1,,,10)CycleNotation=false)
  12)2() ),( (),2(3) )  1() 2() )
  ( 1(4), 3(4) ), ( 2(4), 3(4) ) ]
gap> NrClassPairs(100);
3528138
gap> SplittedClassTransposition(\
[ ( 0(6), 1(12) ), ( 2(6), 5(12) ), ( 4(6), 9(12) ) ]
</xample
  </Description>
</ManSection( 0() (3)),( 04) 1(4)) ( 0(), 2()),(0() 3()),

<Alt Only="LaTeX">\noindent4))]
transpositionsof thering ofintegersgenerates java.lang.StringIndexOutOfBoundsException: Range [73, 74) out of bounds for length 73
simplegroup CT(&ZZ;) mentioned in Chapter <Ref Label="ch:AboutRCWA"/>.
This [ ( 0(6, 112 ) (2(,5(),(4(6,9())]]>
Label="the group generated by all class transpositions of a ring"/>.
The set of all generalized class </Description
generates a simpleManSection>

Class shiftsAlt Only="aTeX>\noindent</java.lang.StringIndexOutOfBoundsException: Index 33 out of bounds for length 33
<M>R</M> other than &ZZ; are defined in an entirely analogous
way -- all one needs to do is to replace &ZZ; by <M>R</M>
and to read <M>lt<M> and Mleq/M in the sense oftheordering 
by &GAP;.
They  alsobeentered basically as described above -- just prepend
the desired ring <M>R</M> to="hegroup generated by all class transpositions of a ring"/>.
<Q set of all generalized  transpositions of&bsp;ZZ
Reference Manual) is chosen if that optional first argument is omitted. <P/>

On java.lang.StringIndexOutOfBoundsException: Index 8 out of bounds for length 0
rcwa permutations whichgeneralizes class reflections:

<ManSection>
  <Func Name="ClassRotation" Arg="r, m, u" Label="r, <>R</M> other than &ZZ; are defined in an entirely analogous
  <Func Name="ClassRotation" Arg="cl, u" Label="cl, u"/>
  <Returnsandto  M>lt<M and M>leq/M> in thesense of the ordering used
  <Description>
    by &GAP;
    ring <M>R</M>,Theycan be  basically as described above - just prepend
    is java.lang.StringIndexOutOfBoundsException: Range [23, 10) out of bounds for length 74
      java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 54
    rotationsgeneralizeclass    
    <M>\rho_{rReferenceManual)ischosen if thatoptional firstargument omitted.</>

    <ex Key"RotationFactor" Subkey=of a class rotation">
      <C>RotationFactor</C>
    </Index>

    In the two-argument form, java.lang.StringIndexOutOfBoundsException: Index 32 out of bounds for length 12
       residue class Mrm</M. Enclosing the argument list in list
    brackets is permitted. The Func Name="ClassRotation" Arg="cl, u" Label="cl, u"/
    <>RotationFactor<C.
<Example>
<![CDATA[
lassRotationResidueClass(_pi(2)21),13);

Tame rcwa permutation of Z_( 2 ) with modulus 2, of order infinity

        /
        | 1/3 n + 2/3 if n in 1(2)
 n|-<  n           if n in 0()
        |
        \

gap> x := Indeterminate(GFand which fixes <M>R \setminus r(m)</M> pointwise.
gap> R := PolynomialRing(GF(8),1);;
gap> >\rho_{rm)-1} =\varsigma_{r(m)}</M>. <P/>
ClassRotation( 1(x), Z(2^3) )
1(x)<ndex Key="RotationFactor" Subkey="of a class rotation">
gap Display(cr)java.lang.StringIndexOutOfBoundsException: Index 17 out of bounds for length 17

 permutationof

        /
        | Z(2^3)*P + Z(2^3)^3 if P in 1(x)
 P |-> <  P                   otherwise
        |
        \
]]>
</Example>
  </Description>
</ManSection>

<Index Key= isjava.lang.StringIndexOutOfBoundsException: Range [26, 25) out of bounds for length 74
  <CExample
</Index>
<Index Key="IsClassReflection" Subkey="for an gap> Display(ClassRotation(ResidueClass(Z_pi(2),2,1),1/3));
  <C>IsClassReflection</C>
</Index>
<Index Key="IsClassRotation" Subkey="for java.lang.StringIndexOutOfBoundsException: Index 43 out of bounds for length 0
  <C>IsClassRotation</C>
</Index>
<Index Key="| 1/3 n + 2/3 if2)
  <>IsClassTransposition</>
</Index>
<Index Key="IsGeneralizedClassTransposition" Subkey\
  gap> x: Indeterminate(GF(8),1);; SetName(x,"x");
</Index>

<>IsClassShiftC> <>IsClassReflection/C>,
<C>IsClassRotation</C>,gap> cr  (,,Z8)One(R);Supportcr
<CIsGeneralizedClassTransposition</C> are properties which indicate
whether a given rcwa mapping belongs to the corresponding series. <P/>

In the sequel we describe 
mappings. The constructor may look a bit java.lang.StringIndexOutOfBoundsException: Index 49 out of bounds for length 0
but knowing all possible ways java.lang.StringIndexOutOfBoundsException: Range [0, 32) out of bounds for length 0
necessary for understanding this manual or for using this package.

<ManSection>
  <Heading> RcwaMapping (the general constructor) </Heading>
  <Meth Name="RcwaMapping" Arg="R, m, coeffs"
        Label="by ring, modulus and list of coefficients"/>
  <Meth Name="RcwaMapping" Arg="R, coeffs"
      Label"by ring and list of coefficients"/>
  <Meth Name="RcwaMapping" Arg="coeffs"
        Label="by java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 9
  <Meth Name="RcwaMapping" Arg="perm, range"
        Label"y permutation ">
  <MethIndex
        ="by  and list of values"/
  <Meth Name=""Arg=pi coeffs
        java.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 8
  <NameRcwaMapping=q,m,coeffs"
        Label="by finite field size, modulus and list of coefficients"/>
  <Meth Name="RcwaMapping" Arg< " ="or an rcwa"
        Label="by two partitions of a ring into residue classes"/>
  < "sGeneralizedClassTransposition" Subkey="for an rcwa mapping">
        Label="by residue class cycles"/>
  <Meth Name="RcwaMapping" Arg="expressionIndex>
        Label="y arithmetical expression"/>
  <Returns> an rcwa mapping. </Returns>
  <Description>
    In all nbsp;<>R</> is the underlying ring,
    <A>m</A> is the modulus and <A>coeffs</A> is the coefficient list.
    A < modulus <M>m</M>
    consists of <M>|R/mR|</M> coefficient triples
    <>, <M>b_{()}</M> <>c_{r()}<M><C>]</C.
    Their ordering is determined by
     residue classes (&bsp<M>m</>)in the sorted list returnedby
    <C>AllResidues(AR<A>, <Am</A)/C>. In case <>R=&ZZ;<Mjava.lang.StringIndexOutOfBoundsException: Index 67 out of bounds for length 67
    this means that the coefficient triple for the residue class <M>0(m)</M>
    java.lang.StringIndexOutOfBoundsException: Range [46, 9) out of bounds for length 71
    <M>2(mjava.lang.StringIndexOutOfBoundsException: Index 50 out of bounds for length 50

    If one or several of the argumentsjava.lang.StringIndexOutOfBoundsException: Index 44 out of bounds for length 44
    <A>coeffs</A        ="  andlist of values">
    are either derived from the latter or default values are chosen.
    The meaning of the <Meth Name="RcwaMapping"=i coeffs"
    description   particular methods given in the sequel.

    The <Meth Name=RcwaMapping"Arg=q cjava.lang.StringIndexOutOfBoundsException: Index 45 out of bounds for length 45
    <List>
      <Mark>(a)</Mark>
      Item>
        of <A>R</A> withrtitions of a ring into residue classes"/>
      </Item>
      <Mark>(b)/java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 22
      <Item>
        ; or <>R/A>= <M>&ZZ;_(\pi)</>  modulus
        <C>Length(<A>coeffs</A>)</C> and coefficients <A>coeffs</A>,
      </Item>
      <Mark>(c)</Mark>
      <Item>
        of <A>R</A> = &ZZ; with modulus <C>Length(<A>coeffs</A>)</C> and
        coefficients <A>coeffs</A>,
      
      <Mark>(d)</Mark>
      Itemjava.lang.StringIndexOutOfBoundsException: Index 12 out of bounds for length 12
        of <A>R</A> = &ZZ;, permuting any set
        C>A>/>(Arange/>)/>like<>perm/java.lang.StringIndexOutOfBoundsException: Index 67 out of bounds for length 67
         residueclasses (&<m<M>)in sorted returnedby
      <//tem>
      <Mark>(e)/Mark>
      <Item>
        of <A>R</A> = &ZZ; with modulus <A>m</A> and values given by a list
        <<A>val</A> of 2pairs <></>reimageC <C>imageC]C 
        residue class (mod <A>java.lang.StringIndexOutOfBoundsException: Range [54, 31) out of bounds for length 71
      </Item>
      <Mark>(f)</Mark>
      <Item>
        <>(m)</M>   on P>
        <C>Length(<A>coeffs</A>If one several of the arguments<>RR<A>,<Am<A>and
        (the set of primes <Mare  derived from latteror   are chosen.
        is passed as argument <A>pi</A>),
      </Item
      <Mark>(g)</Mark>
      <Item>
        of <A>R</A> = java.lang.StringIndexOutOfBoundsException: Index 24 out of bounds for length 0
        coefficients <A>coeffs<<Mark><Mark>
      </Item>
      <Mark>(h)</Mark>
      <Item>
        an rcwa permutation which induces a bijection between
        thepartitions AP1<A <A>/A> ofnbsp;AR/> into residue
        classes and Mark>(b)</Mark
      </Item>
      <ark()java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 22
      <Item>
        an<Item>
        by a list <A>cycles</A> of lists of pairwise disjoint residue classes,Mark(c<Mark>
        ach of which it permutes cyclically, or
      </Item>
      <Mark>(j)</Mark>
      coefficients <A>oeffs<A>
        the rcwa permutation of &ZZ; given by the
        arithmetical expression <expression</A> -- a string consisting of
        class transpositions (e.g. <C>"(0(2),1(4      <Item>
        residue classes e.g. <C>(0(),(8)34)5(8))"</C>), class 
        (e.g.<C>"((6))"<C>,classreflections (e.. <>"cr3(4))"<C),
        arithmetical operators (<C>"*"</C>, <C>"/"</C> and <C>"&circum;"</C>
        and brackets (<C>"("</C>, <C>")"</C>),
      </Item>
    </List>
    respectively.
    The <Item
    argument checks, of <A>R</A> = &ZZwith modulus <A>m</A> and values given by a list
    instead.
<Example<A>val</>  2 pairs<[/java.lang.StringIndexOutOfBoundsException: Range [38, 37) out of bounds for length 72
<![CDATA[
gap> R : ((2)1);;x:=);SetNamex"";
gap/
<rcwa mapping java.lang.StringIndexOutOfBoundsException: Range [7, 1) out of bounds for length 22
(2,[/,,]]);                              
java.lang.StringIndexOutOfBoundsException: Range [6, 3) out of bounds for length 12
gap : RcwaMapping([2,,],4-1,3,[4,1,] # (cjava.lang.StringIndexOutOfBoundsException: Index 73 out of bounds for length 73
<rcwa mapping of Z with modulus 3>
gap> RcwaMapping((1,2,3)/Item
( 1(4), 2(4), 3(4) <Item>
gap> T = RcwaMapping(2,[[1,2],[2,1],[3,5],[he partitions AP1/A and A>P2</> ofnbsp<AR<A into residue
true
gap> RcwaMapping([2],[[1/3,0,1]]);                                  # (f)
Rcwa mapping of Z_( 2 ): n       Mark>(i</Mark>
gap> RcwaMapping(2,x+1,[[1,0,x+One(an rcwa permutation with <Q>residue class cycles</Q> given
<rcwa mapping of GF(2)[x] with modulus x+1>
gap>        by a list <A>cycles</A> of lists of pairwise disjoint residue classes,
>                    ,4]],ResidueClass);       # (h)
true
gap> RcwaMapping( <Item
( 0(2), 1(4), 3(8), 7(16) Mark>(j)</Mark>
gapCycle(last,ResidueClass(0,))
[ 0(2), 1(4), 3(8), 7(16) ]
gap        # (j)
<rcwa permutation of Z with modulus 72>
gap> g = ((0,4,,)  ClassReflection(0,6))^2/
>         ClassShift(2,8);
true
]]>
</Example>
  <Description>
</ManSection>

Rcwa mappings of &ZZ; can be <Q>translated</Q> to rcwa mappings
of  semilocalization <>&ZZ;_{(\pi)</ of &ZZ;:

<ManSection>
  <Func Name=LocalizedRcwaMapping"
        Arg="f, p" Label="for an rcwa mapping of Z and a prime"/>
  Func Name=SemilocalizedRcwaMapping"
        Arg="f, pi" Label="for an rcwa mapping of Z and a set of primes"/>
  <Returns>
     rcwa mapping of <>ZZ;_p)</>respectively
    {\)</>with samecoefficients as the rcwa mapping
    <A>f</A> of &ZZ;.
  </Returns>
  ion
    The argument <A>p</A
    respectively. The argument <A>f</A> must be an rcwa mapping
    of &ZZ; whose modulus gap> R : PolynomialRingGF),1);x := (F(),); SetName(,"x";
    or whose modulus has only prime divisors which lie gap>RcwaMapping(,x,[,,+R)][+One)0,]*R (a
    respectively.
<Example>
<![CDATA[
Rcwa ofof (2 : >1/ n
gap Cycle(T2,/)
[ 131/13, 203/13, 311/<java.lang.StringIndexOutOfBoundsException: Range [14, 13) out of bounds for length 34
  41913,13 95913, 1445/13 217413 108713 1637/13,/, 
  1231/13, 1853/13, 2786/13, 1393/13, 2096/13, 1048/13, 524/13, 262/13 ]
]]>
</Example>
  </Description>
</ManSection>

<java.lang.StringIndexOutOfBoundsException: Range [10, 6) out of bounds for length 66
<Index Key="Display" Subkey="for an rcwa mapping"><C>DisplayRcwa  of Z_( 2 : n- 1/ n
<Index ="Print" Subkey=for an rcwa mapping>>/CIndex
xKey=String =an  mapping"><C>>String</C></Index>

<Alt Only="LaTeX">\noindent</Alt>
Rcwa mappings can be <C>View</C>ed, <C>Display</C>gap a= List([0,3][,3,[,3]]ResidueClass),
written to a <C>String</C>. The output of the <C>View</C> method is kept
reasonablyshort. In most cases it does notdescribe an rcwa mapping
completely. In these cases the output is enclosed in brackets.
There are options <C>CycleNotation</C>, <C>AsClassMapping</C>,
<C>PrintNotation</C> and <C>AbridgedNotation</C> to take influence on
how certain rcwa mappings are shown. These options 02) 14) 38) 716)
set to <C>true</C> or setgap> Cycle(,ResidueClass(0,2);
If  option C>CycleNotation</C> is set, it is tried harder to write
down an rcwa permutation of &ZZ; of finite order as a product of disjoint
residue class cycles, if this is possible.
If the option <C>AsClassMapping</C> is set, <C>Display</C> shows
which java.lang.StringIndexOutOfBoundsException: Range [21, 13) out of bounds for length 73
and marks any loops.
Theoption<C>PrintNotation</C> influences the output in favour of
&GAP; - readability, and the option <C>AbridgedNotation</C> can be used to
abridge longer names like <C>ClassShift</C>, <C>ClassReflection</C> etc..
By default, the output of java.lang.StringIndexOutOfBoundsException: Range [0, 29) out of bounds for length 4
java.lang.StringIndexOutOfBoundsException: Range [16, 9) out of bounds for length 71
an rcwa mapping is &GAP; - readable if and only>
representation of the elements of the underlying ring is so. <P/>

<Index"LaTeXStringRcwaMapping" Subkey=foranrcwamapping">
  <C>LaTeXStringRcwaMapping</C>
</Index>

There is also an operation <C>LaTeXStringRcwaMapping<java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
as ",  Labelfor an rcwa mapping of Z and a prime"/>
&LaTeX; string. TheFunc Name="emilocalizedRcwaMapping
<>. If  option <>Factorization<A is set
and the argument is bijective, a factorization into class shifts,
reflections java.lang.StringIndexOutOfBoundsException: Range [25, 24) out of bounds for length 69
(
Label=or an rcwa permutation of Z/)
For rcwa mappings with modulus greater  of&bsp<><A,
<AIndentation</A> characters can be obtained by setting this option
value accordingly.

<Example>
<![CDATA[
gap> Print(LaTeXStringRcwaMapping(T));
n \ \mapsto \
\egin{cases}
  n/2      & \text{if} \ n \in 0(2), \\
  (3n+1)/2 & \text{if} \ n \in 1(2).
\end{cases}
]]>
</Example>

<gap>T : RcwaMapping[,02],3,,2]);#The  mapping.
  <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<>LaTeXStringRcwaMapping</C>
is inserted into a &LaTeX; template file. This file is &/13, 635/13, 959/13, 1445/13, 2174/13, 1087/13, 1637
result is shown with <Package>xdvi</Package>.
Calling <C>Display</C> with option <A>xdvi</A]>
The operation C>aTeXAndXDVI</C> isonly available on UNIX systems,
and requires suitable installations of &LaTeX; and <Package>java.lang.StringIndexOutOfBoundsException: Index 62 out of bounds for length 16

</ection>

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

<Section Label="sec:BasicArithmeticForRcwaMappings">
<Heading>Basic arithmetic for residue-class-wise affine mappings</Heading>

<Index Key="rcwa mapping" Subkey="arithmetic operations">rcwa mapping</Index>
<Index Key="Order" Subkey="of an rcwa permutation"><C>Order</C></Index>
<Index Key="IsTame" Subkey="for an rcwa mapping"><C>IsTame</C></Index> <P/>

Testingrcwa mappings for equality requires only comparing their
coefficient lists, hence is cheap.
Rcwa mappings  be multiplied, thus there is a method for <C>*</C>.
Rcwa permutations can also be inverted, thus there
<Inverse<C.Thelatter method is mappings can be <C>View</C>ed, <C>Display<
to a power with negative exponent. Multiplying,  options <C>CycleNotation</C>, <C>AsClassMapping</C>,
powers of tame rcwa mappings is <C>PrintNotation</C> and <C>AbridgedN</C> totake  on
java.lang.StringIndexOutOfBoundsException: Range [25, 2) out of bounds for length 70
 withthe exponent  expensive multiplying
a couple of wild mappings is, varies very much. In any case, the amount  theC isset, is  harder to write
java.lang.StringIndexOutOfBoundsException: Range [27, 6) out of bounds for length 75
a givenmapping is tame or wild can be determined by the operation
<C>If the<>
compute a finite order, residueclasses  whichby the affinepartialmappings

<Example>
<![CDATA[
gap> T := RcwaMappingGAP;-readability, and the option <C>AbridgedNotation</C> can be used to
gap> a := RcwaMapping[2,,3,4-13,[,13]);;#Collatz'permutation.
gap> List([-4..4],k of methods for CDisplay</C> and <C>Print</C>
[ 256, 64, 16, 4, 1, 3, 9, 27, 81 ]
gap> IsTame(T) or IsTame(a);
false
gap> IsTame(ClassShift(0,1)) and representation the elements of the  ring is . </
true
gap> T^2*a*T*a^-3;
< of  withmodulus768
gap> (ClassShift(1/Index>
<rcwa permutation of Z with modulus 21>
]]>
</Example>

<Index Key="IsInjective" Subkey="for an rcwa mapping">
  <C>IsInjective</C>
</Index
<Index Key="IsSurjective" Subkey="for <Package>amsmath</Package>. If the optioFactorization</A> is set
  <C>IsSurjective</>
</Index>
<Index Key="IsBijective" Subkey="for an rcwa mapping">
  <C>IsBijective</C>
<Index>
<Index Key="Image" Subkey="of an rcwa mapping">
  <C>Image</C>
</Index>

eare methods installed for <C>IsInjective</C>, <C>IsSurjective</C>,
<C>IsBijectiveA characters canbe obtained by setting this option

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

<Index Key=</xample>

Images Key="Subkey="java.lang.StringIndexOutOfBoundsException: Range [40, 37) out of bounds for length 55
many residue operationC><C>which displaysanrcwa 
<C>&circum;</C>, the samejava.lang.StringIndexOutOfBoundsException: Range [3, 2) out of bounds for length 37
The  forpartitionsofthe source into afinite number of
residue classes.

<Example>
<![DATA[
gap> 15^T;
23
gap> ResidueClass(1,2)^T;
java.lang.StringIndexOutOfBoundsException: Index 42 out of bounds for length 4
> List([03][1,3][2,],esidueClass)^a;
[ 0(2), 1(4), 3(4) ]
]]>
</Example>

<Index Key="PreImageElm" Subkey="of a ring element under an rcwa java.lang.StringIndexOutOfBoundsException: Index 68 out of bounds for length 10
  <C>/C
</Index>
<Index Key="PreImagesElm" Subkey="of a ring element under an
  <C>PreImagesElm</C>
</Index>
<Index Key="PreImage"
       =ofa set ringelementsunder rcwa
  
<>
<Index Index Key=Order" Subkey= anan rcwapermutation"OrderC<Index
       Subkey=ofa class unionunder an rcwa mapping">
  <C>PreImage</C>
</Index>

For computing preimages of elements under rcwa mappings,
there are methods mappings  be multiplied, thus there isamethod for <*<C>.
The  of finiteset  ring elementsor ofaunion offinitely
many residue classes under an rcwa mappingcan beby
<CPreImage</C>.

<Example>
<![CDATA[
gap> PreImagesElm(T,8);
[ ,16  
gap> PreImage(T,ResidueClass(Integers,3,2))approximatelyexponentiallywiththe .How expensive multiplying
Z  0(6)U2()
gap> M := [1];; l := [1];;
gap> while Length() <5000  do = PreImage(T,; Add(,Length(M) ; l;
,, 2, ,5, 8, 10, 14 18, 26,36,50 67,89 ,157,208, 
  277, 367, 488, 649, 869, 1154, 1534, 2039, 2721, 3629, 4843, 6458 ]
]]>
</java.lang.StringIndexOutOfBoundsException: Range [10, 9) out of bounds for length 10

<Index Key="Support" Subkey="of an rcwa mapping">
  <C>Support</C>
</Index>
<Index Key="MovedPoints" Subkey="of an rcwa mapping">
  <C>MovedPoints</C>
</Index>
<Index Key="RestrictedPerm"
       Subkey=f an rcwaand a residue class union">
  <C>RestrictedPerm</C>
</
<Index Key="DensityOfSupport"
       Subkey="anrcwa mapping"java.lang.StringIndexOutOfBoundsException: Index 35 out of bounds for length 35
  <C>DensityOfSupport</C>
</Index>
<Index Key="DensityOfSetOfFixedPoints"
       Subkey="=fanrcwa mapping"java.lang.StringIndexOutOfBoundsException: Index 54 out of bounds for length 54
  <C""Subkey=for an rcwa mapping>
</Index>

There is a method for the operationC>IsSurjective/>
 of anrcwa mapping. A synonym for <C>Support</C> is
<C>MovedPoints</C>. The natural density of the support of an rcwa mapping
of &ZZ; can be computed efficiently with the operation <C>DensityOfSupport</C>.
Likewise, the natural density of the set of fixed points of an rcwa mapping
of &ZZ; can be computed efficiently with the operation
<C>DensityOfSetOfFixedPoints</C>.
There is also a method for <C>RestrictedPerm</C>
for computing the restriction of an rcwa permutation to 
of residue classes which it   C>IsBijective>

<Example
<![CDATACImage</C>
gap> List([
[ Z \ [ -1, 0, 1 ], Z java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
gap> RestrictedPerm(ClassShift(0,2)*ClassReflection(1,2),
>                   ResidueClass(0,2));
<rcwa mapping of Z with modulus 2>
ap>last =ClassShift(0);
true
]>
</Example>

Rcwa mappings can be added and subtracted pointwise. However, please note
that the set of java.lang.StringIndexOutOfBoundsException: Index 19 out of bounds for length 4
<C>+</C/Example>

<Example>
<![CDATA[
gap><ndex "cwa mapping"Subkey="images ">rcwa mapping</
gap> [ Image((a + b)Images of elements of finitesets ofelements and  unions  finitely
[ 2(4), [many residue classes of the source of an rcwa mapping can be computed with
]]>
<>

<Index works for partitions of the source into a finitenumber 
<Index Key="Modresidueclasses.
<Index Key="Coefficients" Subkey="of an rcwa mapping">
  <C>Coefficients</C>
</Index>
<Index Key="rcwa mapping" Subkey="<![CDATA[
<Index Key="rcwa group" Subkey="coercion">rcwa group</Index>

Thereare operations<>Modulus/>(bbreviated C>Mod</C> and
<C>Coefficients</C> for retrieving the modulus and the coefficient list
fan rcwa mapping.The meaning return values is described
in Section&bsp;Ref Label"ec:EnteringRcwaMappings"/.</

eneraldocumentationfor most operations mentioned in this section can
be found in the &GAP; reference manualjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
than &ZZ;, not for all operationsC>/>
available./Index

As in general a subring relation <M>R_1<R_2</M> does <E>not</E> give
rise to a natural embedding of java.lang.StringIndexOutOfBoundsException: Range [1, 35) out of bounds for length 8
there is no coercion between rcwa mappings or rcwa groups Subkey="of a set of ring elements under an rcwa mapping
rings.

</Section>

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

<Section Label":ttributesAndPropertiesOfRcwaMappings
<Heading>
  -wise affine 
</Heading>

<Index Key="class-wise translating" Subkey="definition">
java.lang.StringIndexOutOfBoundsException: Index 35 out of bounds for length 24
</Index>
<Index Key="
<Index Key="balanced" Subkey="definition">java.lang.StringIndexOutOfBoundsException: Index 49 out of bounds for length 9
<Index Key="sign-preserving" java.lang.StringIndexOutOfBoundsException: Range [0, 35) out of bounds for length 15
<Index Key="maximal shift" Subkey="definition">maximal shift<gap>while M<5000 , 4, 5, 8, 10, 14, 18, 26, 36, 50, 67, 89, 117, 157, 208, 

<Index Key="rcwa mapping" Subkey="prime set">rcwa mapping</Index>
<IndexKey=r mapping" Subkey=maximal shift"rcwa mapping<Index>
<Index Key="rcwa mapping" Subkey="class]>
  rcwa mapping
</Index>
<Index Key="rcwa mapping" Subkey="integral">rcwa mapping</Index>
<Index Key="rcwa Index Key="Support Subkey="of an rcwa mapping">
<Index Key="rcwa mapping"
       Subkey="class-wise order-preserving">
  rcwa mapping
</Index>
<Index Key Key="ovedPoints" Subkey"ofan mapping">

<Index Key="Multiplier" Subkey="of an rcwa mapping"><C>Multiplier</C></Index>
<Index Key="Mult" Subkey="for an rcwa mapping"><C>/Index
<Index Key="Divisor" Subkey="of an rcwa mappings      Subkey="or rcwapermutationand a residue class union">
<Index Key="Div" Subkey="for an rcwa mapping"><C>Div</C>RestrictedPerm/C>
<Index Key="PrimeSet" Subkey="of an rcwa</Index>
<Index Key="MaximalShift" Subkey="of an rcwa mapping of Z">
  <C>MaximalShift</C>
</Index>

<Index Key="IsClassWiseTranslating" Subkey="for an rcwa mapping">
  <C>IsClassWiseTranslating</C>
</Index>
<Index Key="IsIntegral" Subkey="for an rcwa mapping">
  <C>IsIntegral<C>
</Index>
<Index Key="IsBalanced" Subkey="for an rcwa mapping">
  <C>java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0
</Index>
<Index Key="IsClassWiseOrderPreserving" Subkey="for an rcwa mapping">
derPreserving/>
</Index>
<Index Key"IsSignPreserving Subkey="for an rcwa mapping">
  <C>IsSignPreserving</C>
</Index>

A number of basic attributes and properties Likewise, the natural density of the set of fixeddensityof the set of fixed points of an rcwa mapping
java.lang.StringIndexOutOfBoundsException: Range [33, 11) out of bounds for length 76
for  and the divisor.These two values are stored
as attributes <C>Multiplier</C> and residueclasseswhich it fixes setwise.
and <C>Div</C>. The <E>prime set</E> of an rcwa mapping is the set 
prime divisors of the product of its modulus and its multiplier.
It is stored as an attribute <C>PrimeSet</Cgap> List[a,^],Support)
The Emaximal shift</E> of an rcwa mapping of &ZZ; is the maximum of
the absolute > RestrictedPermClassShift02)ClassReflection(1,2),
introduced in Section                    ResidueClass(0,2));
It is stored as an attribute <C>rcwa mapping of  with modulus 2>
An rcwa mapping is called <E>class-wise translating</E> if all of
partial mappings are translations, java.lang.StringIndexOutOfBoundsException: Index 37 out of bounds for length 4
divisor equals 1 and it is called <E>balanced</E> if its multiplier
and its divisor have the same prime divisors. A class-wise translating
java.lang.StringIndexOutOfBoundsException: Range [60, 7) out of bounds for length 75
has the property <C>IsIntegral</C> and a balanced mapping has the property
<C></C>
An rcwa mapping of the ring of integers or of one ofC></C>and>*/C>.</>
is called <E>class-wise order-preserving</E> if and only <xample>
<M>a_{r(m)}</M> (cf. Section <Ref Label="sec:basicdefinitions"/>)<[CDATA[
in the numerators of the affine partial mappings are positive.
The corresponding property is <C>IsClassWiseOrderPreserving</C>.
An rcwa mapping of &ZZ; is called <E>sign
it does not map nonnegative integers to negative integers or vice versa.
The corresponding property is <C>IsSignPreserving</C>. All elements of the
simple group CT(&ZZ;) generated by the set of all class transpositions are
sign-preserving.

<Example>
<![CDATAIndex Key="Modulus" Subkey="of an rcwa mapping"><C>Modulus</C></Index>
gap<ndex Key="Mod" Subkey="for an rcwa mapping"><C>Mod</C></Index>
gap> IsBijective(u);; Display(u);

java.lang.StringIndexOutOfBoundsException: Range [5, 4) out of bounds for length 36

        /
        | 3n/5     if nIndex=rcwa  =coercion>java.lang.StringIndexOutOfBoundsException: Range [47, 46) out of bounds for length 60
        |(n1)5ifn in15java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
 -   3-1/   in2()
        | (9n-2)inSection < Label="EnteringRcwaMappings"> <P>
        | (9n+4)/5 if n in 4(5)
        \

gap> (u)
9
gap Divisor();
5
gap> PrimeSet(u);
[3,5 ]
gap> IsIntegral(u)  to a natural embeddingRCWA(M></M> into RCWAMR_2</M),
false
gap> IsClassWiseOrderPreserving(u) andthereis  coercion between rcwa mappings or rcwa groups over different
true
]]>
</Example>

There are a couple of further attributes and Section>
affine partial mappings of <!-- ########################

<ManSection>
  <argestSourcesOfAffineMappings"
        Arg="f" Label="for an rcwa mapping"/>
  <Returns>
     coarsest partition of<C>Source(<A><A)/C>on whose
    elements the rcwa mapping A></A  affine.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> LargestSourcesOfAffineMappings(ClassShift(3,7));
[ Z \ 3(7), 3(7) ]
gap> LargestSourcesOfAffineMappings(ClassReflection(0,1));
[ Integers ]
ap> =RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
gap> List( [ u, u^-1 ], LargestSourcesOfAffineMappings Keymaximal"efinition"maximal shift/java.lang.StringIndexOutOfBoundsException: Index 68 out of bounds for length 68
[ [ 0(5), 1(5), 2(5), 3(5), 4(5) ], [ 0(3), 1(3), 2<ndex Key="rcwa "Subkey="maximal shift"rcwa <Index>
gap> kappa := ClassTransposition(2,
>* ClassTransposition(3,,,6;
<rcwa permutation of Z with modulus 12>
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>
  <Attr Name="FixedPointsOfAffinePartialMappings"
        Arg="" Label=foranrcwa mapping"/>
  <Returns>
    IndexKey="iv" Subkey="for an rcwa mapping"><C>Div</C></Index>
    the rcwa mapping <A>f</A> in the <Index Key="MaximalShift" Subkey="of an rcwa mappi
  <Returns
  <Description>
    The returned list contains entries for 
     residue classes modulo <CMod(Af/A)/C>
    A list entry java.lang.StringIndexOutOfBoundsException: Range [0, 20) out of bounds for length 19
    ora set of cardinality 1. The ordering of the entries corresponds
    to the ordering of the residues in
    <C>AllResidues(Source(Af</A>,Am/A)/C>java.lang.StringIndexOutOfBoundsException: Index 50 out of bounds for length 50
<Example>
<![CDATA[
gap> FixedPointsOfAffinePartialMappings(ClassShift(0,2));
[ [  ], Rationals ]
gap> List([1..3],k->FixedPointsOfAffinePartialMappingsIndexKey=IsSignPreserving" Subkey="for an rcwa mapping">
[ [ [ 0 ], [ -1 ] ], [ [ 0 ], [ 1 ], [ 2 ], [ - java.lang.StringIndexOutOfBoundsException: Range [24, 21) out of bounds for length 25
  [ [ 0 ], [ -7 ], [ 2oefficientsofits affine partial mappings. This holds
]]>
</xample
  </Description>
</ManSection>

<ManSection>
  <per Name="ultpk Arg="f, p, k"
        Label="for an rcwa mapping, a prime and an exponent"/>
  <Returns>
    the union of the It is stored as an attributePrimeSet</C>.
    <M>p^||{rm)}/M> if <> \geq 0/M> and the union of the residue
    classes <rm)</M>suchthat <M>p^k||c_r()}/M if <M>k \leq 0<M>
    java.lang.StringIndexOutOfBoundsException: Range [10, 6) out of bounds for length 71
    <M>a_{r(m)}</M> and <M>c_{r(m)}</M> denote the coefficients
    of&;Af/A as introduced in
    Section <Ref Label="sec:An rcwa mapping is called <E>class-wise translating</E> if all of its affine
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> T := RcwaMapping([1,02][,12]);  The Collatz mapping.
gap> [ Multpk(T,2,-1), Multpk(T,3,1) ];
[ Integers, 1(2) ]
waMapping([[3,,],[9,1,],3,1,],9,2,,[9,,5];;
gap> [ Multpk(u,3,0), Multpk(u,3,1),  the property <C>IsIntegral</C> and a balanced <CIsIntegral</C> and a balanced mapping has the property
[ [  ], 0(5) U 2(5), Z \ 0(5) U 2(5), Integers ]
]]>
</Example>
  </Description>
<ManSection

<Index Key="lassWiseOrderPreservingOn">
  <C>ClassWiseOrderPreservingOn</C>
<x>
<Index Key="ClassWiseConstantOn">
  <C>ClassWiseConstantOn</C>
</Index
<Index Key="ClassWiseOrderReversingOn"> map java.lang.StringIndexOutOfBoundsException: Range [28, 27) out of bounds for length 72
  <C>ClassWiseOrderReversingOn</C>
</Index>

There are attributes <C>java.lang.StringIndexOutOfBoundsException: Index 42 out of bounds for length 16
<C>ClassWiseConstantOn</C> and <C>ClassWiseOrderReversingOn<Example
java.lang.StringIndexOutOfBoundsException: Range [8, 5) out of bounds for length 73
which an rcwa mappinggap :([,05,915,[,1,,9-2,],9,,5]];;
java.lang.StringIndexOutOfBoundsException: Range [29, 7) out of bounds for length 73
order-reversing, respectively

<Example>
<![CDATA[
gap> Listjava.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9
>          ClassReflection(2,5)],ClassWiseOrderPreservingOn);
[ Integers, Integers, Z \ 2(5) ]
]]>
</Example>

<Indexgap> Multiplier(u)
<Index Key="ShiftsDownOn">9

Also there are attributes <C
which store the union of the residue classes
(mod <C>Mod(<A>f</A>)mod <C>Mod(<A>f</A>)</C>java.lang.StringIndexOutOfBoundsException: Index 30 out of bounds for length 17
of &ZZ; induces affine mappings 
<M>c > 0</M>, respectively, <M>c < 0</M>. <P/>

Finally, there are epimorphisms from the subgroup of RCWA(&ZZ;)
formed by all class-wise order-preserving elements ving(u);
and from RCWA(&ZZ;) itself to the cyclic group of order 2,
respectively:

<ManSection>
  <Meth Name="Determinant" Arg="f" Label="There are a couple of further attributes and operations related to the
  <Returns>
    the determinant of the rcwa mapping <A>f</A> of &ZZ;.
  </Returns>
  <Description>
    The <  <Attr Na"LargestSourcesOfAffineMappings"
    whose java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 11
rcwa mappingsjava.lang.StringIndexOutOfBoundsException: Index 76 out of bounds for length 76
    <P/>

    Let <M>f</M> be an rcwa mappingDescription>
    <M>m</M> denote its modulus. Using the notation!CDATA[
    <M>f|_{r(m)}: n \mapsto (a_{r(m)} \cdot n>LargestSourcesOfAffineMappings(ClassShift(3,7));
    for the affine partial mappings, the <E>determinant
    of <M>f</M> is given by
    <Alt Only="LaTeX">
      <Display>
        \[ Integers 
      </Display>
    </>
    <Alt Only="HTML"><![CDATA[<center>
      <  =  =177height="58"
           alt = "sum_{r(m) in Z/[0(5,15) 2(5), 35), ()] [ 0(3) 13, 29,59) 89 ]]
                  b_{r(m)}/(|a_{r(m)}| \cdot m)."/>
    </center>]]>/Alt>
    <Alt Only="Text"><Verb>
                          -----
                           \           b_r(m)
                            >----------
                           /       |a_{r(m)}| * m
                          -----
                      r)in Z/Z.
    </Verb></Alt> 
    The determinant mapping is an epimorphism from the group of all
    class-wise order-preserving rcwa permutations of &ZZ;
    to (&ZZ;,+), java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 13
<Example>
<![CDATA[
gap> List([ClassTransposition"f" Label="for an rcwa mapping"/>
<java.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 11
 (ClassTransposition(,,,12*ClassShift37)^100)   
100
]]>
</Example>
  </Description>
</ManSection>

<anSection>
  <Attr Name="Sign" Arg="g" Label="of an rcwa permutation of Z"/>
  <Returns>
    the sign of the rcwa permutation <A>g</A>     set of cardinality;1 The ordering of the entries corresponds
  </Returns>
  <cription
    Let <M>\sigma<C>(Source(A><A>,<A>m</A)<C.
    <xample>
    <M>\sigma|_{r(m)}: n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{java.lang.StringIndexOutOfBoundsException: Range [1, 67) out of bounds for length 9
    for the affine partial mappings, the <E>sign</E> of <M>\sigma</M>
    is defined by
    <Alt Only="LaTeX">
      <Display>
        (-1)^{\displaystyle{   0 ],  7] [ /5 ] [-5 ],[ /5 ],[1/ ],[-10], [-1] ]]
            + \sum_{r(m): \ a_]]>
      </Display>
    </Alt>
    <Alt
      <img =Multpk"Arg",p,k"
           alt = "(- Label=f an rcwa mapping,aprime and an exponent">
                      + sum_{r(m): \ a_{r(m)}    classes<>(such that
    /center>]></Alt>
    <Alt Only="Text"><Verb>
                                    
                                     \       m - 2r
                      det(sigma     >      -----java.lang.StringIndexOutOfBoundsException: Index 52 out of bounds for length 52
                                               m
                                    -----
                                 ()&; 0
              java.lang.StringIndexOutOfBoundsException: Range [15, 14) out of bounds for length 15
    </Verb<[CDATA[
    The sign mapping is an epimorphism from RCWA(&ZZ;) to the group
    <M>&ZZ;^\times</M> of units of &ZZ;, see <Cite java.lang.StringIndexOutOfBoundsException: Index 64 out of bounds for length 39
    Theorem 2.12.8. Therefore the kernel of the sign mapping is a normal
    subgroup of RCWA(&ZZ;) >u :([0,5][,,5][,1,5],[,2,][,,5])
    a subgroup of this kernel.
<Example>
<![CDATA[
gap> List([ClassTransposition(3,4,2,6),
>          ClassShift(0,3),ClassReflection(2,5)],Sign);
[ 1, -1, -1 ]
]]>
</Example>
  </escription>
</ManSection>

</Section>

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

<Section Label="sec:FactoringRcwaMappings">
<Heading>Factoring residue-class-wise affine java.lang.StringIndexOutOfBoundsException: Index 51 out of bounds for length 16

Factoring group elements into the members of someIndex =ClassWiseOrderPreservingOn">
generators is often helpful. In this section we describe an operation which
attempts to solve this problem for the group java.lang.StringIndexOutOfBoundsException: Index 48 out of bounds for length 8
Elements of finitely generated rcwa groups can
<Q>as /IndexIndex>
Label="for an epi. from a free group to an rcwa group"/>.

<ManSection>
  <Oper Name=<C>ClassWiseOrderReversingOn</C>
  <java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 8
     list of3 rcwa  <M>a</M,<M>b/M>and <><M whose
    product equals <A>g</A>, where <M>a</M> fixes the nonnegative integers
    setwise,Mb/M> is integral and class-wise order-preserving and
    <M>c</M> is integral.
  </Returns>
  <Description>
    Assuming the hypothesis that CTthereofclass-order,class-wiseconstantor classwise
    permutations of &ZZExample>
    <M>a</M> is always an element of CT(&ZZ;).
<Example>
<![CDATA[
 g =ClassTransposition0,,1,6)ClassShift(,)ClassReflection2,3;
<rcwa permutation of Z with modulus 180>
gap> facts := CTCSCRSplit(g);
[ <rcwa permutation of Z with modulus 60>, ClassShiftExample>
  ClassReflection( 2(3) ) ]
gap>Product(facts)= g;
true
gap> List(facts,IsSignPreservingIndex Key"ShiftsDownOn"<C>ShiftsDownOnC<Indexjava.lang.StringIndexOutOfBoundsException: Index 53 out of bounds for length 53
[ true, false, false utes <CShiftsUpOn</C> and <C>ShiftsDownOn</C>
gap> List(facts,IsIntegral);
[ false, true, true ]
gap>,)
[ true, true, false ]
]]>
</Example>
  </Description>
</>

<ManSection>
  <Attr Name="FactorizationIntoCSCRCT"
        Arg="g" Label="for an rcwa permutation of Z"/>
  <MethName="Factorization" Arg="g" Label="for an rcwa permutation of Z"/>
  <Returns>
        factorization of the permutation;Ag/> of ZZ;
    into java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 13
    that a  existsand the method finds it.
  </Returns>
  <Description>
    The method may return <C>fail</C    determinantof  rcwa mapping Af</A> of &ZZ;java.lang.StringIndexOutOfBoundsException: Index 67 out of bounds for length 67
    into an infinite loop. If  <>determinant/>of an affine mapping <M> mapsto (n+)/c/>
    correct.

     problem of obtaining a  as   
    difficult, and this factorization routine <P/>
    sophisticated part of the &    Let <M>f</M> be an rcwa mappingM be  rcwamapping of  , and 
    progress of the factorization process can be obtained by setting the
    info level of the Info class <Ref InfoClass="InfoRCWA"/> to 2. <P/>

    By default, prime switches (<M>\rightarrow</M>
    <Ref Func="for the affine partial mappings, the <E>determinant</E> det(<M>f</M>)
    If the option <   of <>f<M>  by
    decomposed <AltOnly="LaTeX>

    By \rm \n\athbb{}m\mathbb{}b_{rm}m)|\cdot )java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 77
    from the right.>![CDATA[<center>
    <A>Direction<img src="et.ng"width=""=58"

     default reasonablycoarse respected partition of the integral
    mapping occurring in the final stage of the algorithm is computed.
     bysettingthe<A>
    equal to <C>false</                          ---

    By default, at the end it is checked whether the product of java.lang.StringIndexOutOfBoundsException: Range [28, 1) out of bounds for length 48
    determined factors indeed equals <--
    suppressed the option <A>NC</A>.
<Example>
<![CDATA[
gap> Factorization(Comm(ClassShift(0,3)*ClassReflection(1,2),
>
[ ClassReflection( 2(3) ), ClassShift( 2(6) )^-1, (  lass- order-preserving rcwa  of &ZZ;
  (0(), 56)) ]
]]>
</Example>
  </Description>
<ManSection>

For purposes of demonstrating the capabilities of the factorization routine,
in Section <Ref Label="sec:FactoringTheCollatzPermutation"/>
Collatz' permutation is java.lang.StringIndexOutOfBoundsException: Index 29 out of bounds for length 16
permutation in 1932<anSection>

The permutations of the following<eturns
factoring rcwa the sign of the rcwa permutation <A>g</A> of &ZZ;.
class reflections and class transpositions:

<ManSection>
  MethName="rimeSwitch" Arg="p"Label="p"/java.lang.StringIndexOutOfBoundsException: Index 46 out of bounds for length 46
  MethName"PrimeSwitch"Arg="p, k" Label="p, k"/>
  <Meth Name="PrimeSwitch" Arg="p, r, m" Label="p, r, m"/>
  <Meth ="PrimeSwitch" Arg=", cl" Label="p, cl"/>
java.lang.StringIndexOutOfBoundsException: Range [11, 12) out of bounds for length 11
    in>
    <
    \tau_/>
    \cdot \tau_{4(<java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 77
    the restriction of <M>\sigma_p</M> <Heading>Factoring residue-class-wise aff>
    and inthethird and fourth form the E>>
(m2)r_2m}\cdot
    \tau_java.lang.StringIndexOutOfBoundsException: Range [9, 8) out of bounds for length 56
        thelattercase, <>l<A>is the residue class
    <>rm)/>,theresiduer_1/>is <1( m )/> 
    </>is definedbytheequalityMrm \java.lang.StringIndexOutOfBoundsException: Range [59, 58) out of bounds for length 75
  </Returns>
  <Description>
     <M>sigma_p/>
    an rcwa permutation of &ZZ; withReturns>
    multipliern;M><M   .
    The prime product equals><A,where Ma/>fixesthe nonnegative integers
    multiplier ></M>anddivisor&bsp;,and  classwhere
ication M>/M>occurs isjust<Mr)/>java.lang.StringIndexOutOfBoundsException: Index 62 out of bounds for length 62
    The key the hypothesis that(ZZ;  the group of rcwa
asstranspositions  and 
    <M<M>   element &)

    Prime switches can gap>: (0416*ClassShift(2,*
    rcwa mappings by their &GAP; java.lang.StringIndexOutOfBoundsException: Index 40 out of bounds for length 29
    <ndexKey=IsPrimeSwitch =for an  mapping>
       <C>IsPrimeSwitch</C>
    </Index>
<xample>
<![CDATA[
gap> Display([ true, false, false

Wild rcwa permutation of Zgap f,sClassWiseOrderPreserving;

        /
        | (3n+4)/2 if n in 2(4)
        | n-1      if n in 5(6) U [true, true, false ]
        | n+1      if n in 1(6)
 n |-> <
        | n-3      if n in 4(12)
         n        n in3()
        |
        \

gap> Display(PrimeSwitch(3):factorization of the rcwa permutationAg<>&;ZZjava.lang.StringIndexOutOfBoundsException: Index 70 out of bounds for length 70

Wild rcwa permutation of Z with modulus 12

  0(12) -> 0(6)  loop
   1(6) -> 2(6)
   2()- 5(6
   3(6) -> 3(6)  id P>
12)- 112)
   5(6) -> 4(6)
  8(12) -> 7(12)

gap> progressof thefactorization processcanbeobtained by setting the
[ 4(8)) (04,1()) (2() 6 ,
  ( 2(6), 1(12) ), ( 4(6)Bydefault  switchesMr<M
gap> Display(PrimeSwitch(5,3,4));

  decomposedinto 6   given  thedefinition P>

        
        | n+1      right  can bechanged setting option
f n  ()
 n |-> <  (n-1)/2 if n in 1(4) \ 1(20)
        | n-1     if n in 1(20)
        |
            java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

 MultpkP(,,)51)
3()
gap> PrimeSwitch(5,3,4) = PrimeSwitch(5,ResidueClass(3,4)suppressed  theoption <NC/>
true
gap> Factorization(PrimeSwitch(5,3,4))*(,)java.lang.StringIndexOutOfBoundsException: Index 61 out of bounds for length 61
[ ( 0(2), 1(4) ), ( 1(4[(23 ,  26 )^1,(06), 26),
]]>
/>
  </Description>
</ManSection>

Obtaining a factorization of an rcwa permutation into in Section Ref"ecFactoringTheCollatzPermutation
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 <factoring rcwa permutations of &ZZ; into class shifts,

<ManSection>
  <Func Name="mKnot"<eth Name"rimeSwitch ""Label=p">
  <
    the permutation <M>  <Meth Name="PrimeSwitch",r  =p ,m"
  <Returns>
  <Returns
     argument<>mA>must  an oddinteger than 1java.lang.StringIndexOutOfBoundsException: Index 69 out of bounds for length 69
<Example>
<![CDATA[
gap> Display(mKnot(5));

Wild rcwa permutation of Z with modulus 5

        /
               |6n/     if n in05java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
        | (4n+1)/5 if n in 1(5)
 n |-> <  (6n-2)/5 if n in 2(5)
        | (4n+3)/5 if n in 3(5)
        | (6n-4)/5 if n in 4(5)
        \
]]>
</>
  </Description>
java.lang.StringIndexOutOfBoundsException: Index 45 out of bounds for length 13

<Alt Only="LaTeX">\  /eturnsjava.lang.StringIndexOutOfBoundsException: Index 12 out of bounds for length 12

cannot

</Section>

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

<Sectiongap PrimeSwitch(534)= PrimeSwitch(,ResidueClass(3,4))
<Heading
  Extracting  (rimeSwitch(53,4)java.lang.StringIndexOutOfBoundsException: Index 39 out of bounds for length 39
</Heading>

<ManSection>
  
        Arg="f, k" Label="k-th root of an rcwa mapping"/are coprime.A prototype ofpermutations which have
  <Returns>
    an introduced in a different context
    provided that such a mapping exists and that there is a method available&bsp;Cite Key="Keller99"/>: 
    which can determine it.
  </Returns>
  <Description>
    Currently, extracting roots is implemented for rcwa permutations
    of finite order.
<>
<![CDATA[
gap> Root(ClassTransposition(0,2,1,2),100);
( 08), 28) 48), 6(, 18,3(,5(),7( )
gap> Display(last:CycleNotation:=false);

Tame rcwa permutation ofZwith modulus 8

        /
        | n+   inin  \6(  (
 n |-> <  n-5 if n in 6(8)
        | n-7 if n in 7(8)
        \

gap> last
true
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label (-)5if nin(5java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
<Heading>
  Special functions for non-bijective mappings
<Heading>

<ManSection>
 "ightInverse"Arg="rcwa mapping">
  
    a right inverse of the injective rcwa mapping <A>f</A>,
    i.e. a mapping <M>g<M> such that Af/A<M>g</M>nbsp; 1java.lang.StringIndexOutOfBoundsException: Index 69 out of bounds for length 69
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> twice := 2*java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 12
Rcwa mapping of Z: n -> 2n
gap> twice * RightInverse(twice);
IdentityMapping( Integers )
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="CommonRightInverse" Arg="l, r"
        Label="of two injective rcwa mappings"/>
  <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 := 2*IdentityRcwaMappingOfZ; twiceplus1 := twice+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/2     if n in 0(2)
 n |-> <  (n-1)/2 if n in 1(2)
        |
        \
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="ImageDensity" Arg="f" Label="of an rcwa mapping"/>
  <Returns>
    the <E>image density</E> of the rcwa mapping <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 <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 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="for an rcwa mapping">
  <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 <C>S</C>
is injective, and such that the image of <C>S</C> under <C>f</C> is the
entire image of <C>f</C>.

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

</Section>

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

<Section Label="sec:Trajectories">
<Heading>
  On trajectories and cycles of residue-class-wise affine mappings
</Heading>

&RCWA; provides various methods to compute trajectories of rcwa mappings:

<ManSection>
  <Heading> Trajectory (methods for rcwa mappings) </Heading>
  <Meth Name="Trajectory" Arg="f, n, length"
        Label="for rcwa mapping, starting point, length"/>
  <Meth Name="Trajectory" Arg="f, n, length, m"
        Label="for rcwa mapping, starting point, length, modulus"/>
  <Meth Name="Trajectory" Arg="f, n, terminal"
        Label="for rcwa mapping, starting point, set of end points"/>
  <Meth Name="Trajectory" Arg="f, n, terminal, m"
        Label="for rcwa mapping, starting point, set of end points, modulus"/>
  <Returns>
    the first <A>length</A> iterates in the trajectory of the
    rcwa mapping <A>f</A> starting at <A>n</A>, respectively the
    initial part of the trajectory of the rcwa mapping <A>f</A>
    starting at <A>n</A> which ends at the first occurrence of an
    iterate in the set <A>terminal</A>. If the argument <A>m</A> is given,
    the iterates are reduced (mod <A>m</A>).
  </Returns>
  <Description>
    To save memory when computing long trajectories containing huge
    iterates, the reduction (mod <A>m</A>) is done each time before
    storing an iterate.
    In place of the ring element <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,15); Trajectory(T,27,20,5);
[ 27, 41, 62, 31, 47, 71, 107, 161, 242, 121, 182, 91, 137, 206, 103 ]
[ 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 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) (6 classes)>, 
  <union of 73 residue classes (mod 81)>, Z \ 10(81) U 37(81), Integers ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Heading>
    Trajectory (methods for rcwa mappings -- <Q>accumulated coefficients</Q>)
  </Heading>
  <Meth Name="Trajectory" Arg="f, n, length, whichcoeffs"
        Label="for rcwa mapping, starting point, length, coeff.-spec."/>
  <Meth Name="Trajectory" Arg="f, n, terminal, whichcoeffs"
        Label="for rcwa mapping, starting point, set of end points, coeff.-spec."/>
  <Returns>
    either the list <C>c</C> of triples of coprime coefficients such that
    for any <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>

When dealing with problems like the <M>3n+1</M>-Conjecture or when
determining the degree of transitivity of the natural action of an rcwa group
on its underlying ring, an important task is to determine the residue classes
whose elements get larger or smaller when applying a given rcwa mapping:

<ManSection>
  <Heading> IncreasingOn & DecreasingOn (for an rcwa mapping) </Heading>
  <Attr Name="IncreasingOn" Arg="f" Label="for an rcwa mapping"/>
  <Attr Name="DecreasingOn" Arg="f" Label="for an rcwa mapping"/>
  <Returns>
    the union of all residue classes <M>r(m)</M> such that
    <M>|R/a_{r(m)}R| > |R/c_{r(m)}R|</M> or
    <M>|R/a_{r(m)}R| < |R/c_{r(m)}R|</M>, respectively, where <M>R</M>
    denotes the source, <M>m</M> denotes the modulus and <M>a_{r(m)}</M>,
    <M>b_{r(m)}</M> and <M>c_{r(m)}</M> denote the coefficients
    of <A>f</A> as introduced in
    Section <Ref Label="sec:basicdefinitions"/>.
  </Returns>
  <Description>
    If the argument is an rcwa mapping of &ZZ; in sparse representation,
    an option <C>classes</C> is interpreted; if set, the step of forming
    the union of the residue classes in question is omitted, and the
    list of residue classes is returned instead of their union.
    This may save time and memory if the modulus is large.
<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>

We assign certain directed graphs to rcwa mappings, which encode the order
in which trajectories may traverse the residue classes modulo some modulus:

<ManSection>
  <Oper Name="TransitionGraph"
        Arg="f, m" Label="for an rcwa mapping and a modulus"/>
  <Returns>
    the transition graph of the rcwa mapping <A>f</A>
    for modulus <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 <M>f</M> for
    modulus <M>m</M> is defined as follows:
    <Enum>
      <Item>
        The vertices are the residue classes (mod <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 <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> <Cite Key="GRAPE"/>.
  </Description>
</ManSection>

There are a couple of operations and attributes which are based
on these graphs:

<ManSection>
  <Oper Name="OrbitsModulo"
        Arg="f, m" Label="for an rcwa mapping and a modulus"/>
  <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 <A>f</A> for modulus <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="for an rcwa mapping and a modulus"/>
  <Returns>
    the set of restrictions of the rcwa mapping <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 <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="for an rcwa mapping and a modulus"/>
  <Returns>
    the transition matrix of the rcwa mapping <A>f</A> for
    modulus <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>
    </Alt>
    <Alt Only="HTML"><![CDATA[<center>
      <img src = "transmat.png" width = "599" height = "47"
           alt = "(see the PDF version of the manual),"/>
    </center>]]></Alt>
    <Alt Only="Text">
      (see the PDF- or HTML version of the manual),
    </Alt>
    where <M>\hat{m}</M> is the product of <A>m</A> and the square of the
    modulus of <A>f</A>.
    The assignment of the residue classes (mod <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 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>
  <Heading> Sources & Sinks (of an rcwa mapping) </Heading>
  <Attr Name="Sources" Arg="f" Label="of an rcwa mapping"/>
  <Attr Name="Sinks" Arg="f" Label="of an rcwa mapping"/>
  <Returns>
    a list of unions of residue classes modulo the modulus <M>m</M>
    of the rcwa mapping <A>f</A>, as described below.
  </Returns>
  <Description>
    The returned list contains an entry for any strongly
    connected component of the transition graph of <A>f</A> for
    modulus <C>Mod(<A>f</A>)</C> which has only outgoing edges
    (<Q>source</Q>) or which has only ingoing edges (<Q>sink</Q>),
    respectively. The list entry corresponding to such a component
    is the union of the vertices belonging to it.
<Example>
<![CDATA[
gap> g := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4);;
gap> Sources(g); Sinks(g);
[ 0(4) ]
[ 1(4) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="Loops" Arg="f" Label="of an rcwa mapping"/>
  <Returns>
    if <A>f</A> is bijective, the list of non-isolated vertices of the
    transition graph of <A>f</A> for modulus <C>Mod(<A>f</A>)</C>
    which carry a loop. In general, the list of vertices of that transition
    graph which carry a loop, but which <A>f</A> does not fix setwise.
  </Returns>
  <Description>
    The returned list may also include supersets of the named
    residue classes instead if <A>f</A> is affine even on these.
<Example>
<![CDATA[
gap> Loops(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));
[ 0(4), 1(4) ]
]]>
</Example>
  </Description>
</ManSection>

There is a nice invariant of trajectories of the Collatz mapping:

<ManSection>
  <Func Name="GluckTaylorInvariant" Arg="a" Label="of a trajectory"/>
  <Returns>
    the invariant defined in <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 <A>a</A>.
  </Returns>
  <Description>
    The argument <A>a</A> must be a list of integers.
    In <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 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>

Quite often one can make certain <Q>educated guesses</Q> on the overall
behaviour of the trajectories of a given rcwa mapping. For example it is
reasonably straightforward to make the conjecture that all trajectories of
the Collatz mapping eventually enter the finite set <M>\{-136, -91, -82, -68,
-61, -55, -41, -37, -34, -25, -17, -10, -7, -5, -1, 0, 1, 2 \}</M>, or that
<Q>on average</Q> the next number in a trajectory of the Collatz mapping is
smaller than the preceding one by a factor of <M>\sqrt{3}/2</M>. However it
is clear that such guesses can be wrong, and that they therefore cannot be
used to prove anything. Nevertheless they can sometimes be useful:

<ManSection>
  <Oper Name="LikelyContractionCentre"
        Arg="f, maxn, bound" Label="of an rcwa mapping"/>
  <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 <A>f</A> on which <A>f</A>
    induces a permutation and which intersects non-trivially with any
    trajectory of <A>f</A>. The mapping <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 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 more information.
[ -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="of an rcwa mapping"/>
  <Returns>
    a floating point value which is intended to be a rough guess on how fast
    the trajectories of the rcwa mapping <A>f</A> diverge (return value
    greater than 1) or converge (return value smaller than 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>

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

<Section Label="sec:SparseRepresentationOfRcwaMappings">
<Heading>
  Saving memory -- the sparse representation of rcwa mappings
</Heading>

<Index Key="rcwa mapping" Subkey="sparse representation">
  rcwa mapping
</Index>
<Index Key="RcwaMapping"
       Subkey="by list of coefficients, sparse representation">
  <C>RcwaMapping</C>
</Index>

It is quite common that an rcwa mapping with large modulus
has only few distinct affine partial mappings. In this case the
<Q>standard</Q> representation which stores a coefficient triple for each
residue class modulo the modulus is unsuitable. For this reason there is
a second representation of rcwa mappings, the <Q>sparse</Q> representation.
Depending on the rcwa mappings involved, using this representation may
speed up computations and reduce memory requirements by orders of
magnitude. For rcwa mappings with almost as many distinct affine partial
mappings as there are residue classes modulo the modulus, using sparse
representation makes computations slower and more memory-consuming.
Presently, the sparse representation is only available for rcwa mappings
of &ZZ;. <P/>

The sparse representation of an rcwa mapping consists of the modulus and
a list of 5-tuples <M>(r,m,a_{r(m)},b_{r(m)},c_{r(m)})</M> of integers.
Any such 5-tuple specifies the coefficients of the restriction
<M>n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}</M> of the mapping
to a residue class <M>r(m)</M>. The <M>r(m)</M> are chosen to form the
coarsest possible partition of &ZZ; into residue classes such that the
restriction of the mapping to any of them is affine. Also the list of
coefficient tuples is sorted, all <M>c_{r(m)}</M> are positive and
<M>\gcd(c_{r(m)},\gcd(a_{r(m)},b_{r(m)})) = 1</M>. This way the coefficient
list of an rcwa mapping of &ZZ; is unique. <P/>

Changing the representation of rcwa mappings does not change their
behaviour with respect to <Q><C>=</C></Q> and <Q><C><</C></Q> 
The product of two rcwa mappings in sparse representation is in sparse
representation again, just like the product of two rcwa mappings in
standard representation is in standard representation. Also, inverses
are in the same representation. The product of two rcwa mappings in
different representation may be in any of the representations of the
factors.

<ManSection>
  <Oper Name="SparseRepresentation" Arg="f" Label="of an rcwa mapping"/>
  <Oper Name="SparseRep" Arg="f" Label="of an rcwa mapping"/>
  <Oper Name="StandardRepresentation" Arg="f" Label="of an rcwa mapping"/>
  <Oper Name="StandardRep" Arg="f" Label="of an rcwa mapping"/>
  <Returns>
    the rcwa mapping <A>f</A> in sparse, respectively, standard
    representation.
  </Returns>
  <Description>
    Appropriate attribute values and properties are copied over
    to the rcwa mapping in the <Q>new</Q> representation. 
<Example>
<![CDATA[
gap> a := ClassTransposition(1,2,4,6);
( 1(2), 4(6) )
gap> b := ClassTransposition(1,3,2,6);
( 1(3), 2(6) )
gap> c := ClassTransposition(2,3,4,6);
( 2(3), 4(6) )
gap> g := (b*a*c)^2*a;
<rcwa permutation of Z with modulus 288>
gap> h := SparseRep(g);
<rcwa permutation of Z with modulus 288 and 21 affine parts>
gap> g = h;
true
gap> Coefficients(h);
[ [ 0, 6, 1, 0, 1 ], [ 1, 3, 16, -1, 3 ], [ 2, 96, 9, 14, 16 ], 
  [ 3, 24, 9, 5, 4 ], [ 5, 24, 3, 1, 4 ], [ 8, 36, 2, -7, 9 ], 
  [ 9, 48, 27, 29, 8 ], [ 11, 24, 9, 5, 4 ], [ 14, 48, 27, 38, 8 ], 
  [ 15, 24, 27, 19, 4 ], [ 17, 48, 9, 7, 8 ], [ 20, 72, 3, 4, 4 ], 
  [ 21, 24, 1, -3, 6 ], [ 23, 24, 27, 19, 4 ], [ 26, 48, 3, 2, 8 ], 
  [ 32, 36, 4, -11, 9 ], [ 33, 48, 9, 7, 8 ], [ 38, 48, 9, 10, 8 ], 
  [ 41, 48, 27, 29, 8 ], [ 50, 96, 27, 58, 16 ], [ 56, 72, 1, 0, 4 ] ]
gap> h^2;
<rcwa permutation of Z with modulus 13824 and 71 affine parts>
gap> h^3;
<rcwa permutation of Z with modulus 663552 and 201 affine parts>
]]>
</Example>
    Memory consumption may differ a lot between sparse- and standard
    representation:
<Log>
gap> MemoryUsage(h^3);               # on a 64-bit machine
18254
gap> MemoryUsage(StandardRep(h^3));  # on a 64-bit machine
42467894
</Log>
  </Description>
</ManSection>

</Section>

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

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

<ManSection>
  <Filt Name="IsRcwaMapping" Arg="f"/>
  <Filt Name="IsRcwaMappingOfZ" Arg="f"/>
  <Filt Name="IsRcwaMappingOfZ_pi" Arg="f"/>
  <Filt Name="IsRcwaMappingOfGFqx" Arg="f"/>
  <Returns>
    <C>true</C> if <A>f</A> is an rcwa mapping,
    an rcwa mapping of the ring of integers,
    an rcwa mapping of a semilocalization of the ring of integers or
    an rcwa mapping of a polynomial ring in one variable over a finite field,
    respectively, 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">
      <C>IsRcwaMappingOfZOrZ&uscore;pi</C>
    </Index>
    The internal representation of rcwa mappings is called
    <C>IsRcwaMappingStandardRep</C>.
    <Index Key="IsRcwaMappingStandardRep">
      <C>IsRcwaMappingStandardRep</C>
    </Index>
    There are methods available for <C>ExtRepOfObj</C> and
    <C>ObjByExtRep</C>.
    <Index Key="ExtRepOfObj"><C>ExtRepOfObj</C></Index>
    <Index Key="ObjByExtRep"><C>ObjByExtRep</C></Index>
  </Description>
</ManSection>

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

</Section>

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

</Chapter>

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