rcwamono.xml

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

<Chapter Label="ch:RcwaMonoids">
<Heading>Residue-Class-Wise Affine Monoids</Heading>

<Ignore Remark="set screen width to 75, for the example tester">
<Example>
<![CDATA[
gap> SizeScreen([75,24]);;
]]>
</Example>
</Ignore>

In this short chapter, we describe how to compute with residue-class-wise
affine monoids.

<Index Key="rcwa monoid" Subkey="definition">rcwa monoid</Index>

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

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

<Section Label="sec:ContructingRcwaMonoids">
<Heading>Constructing residue-class-wise affine monoids</Heading>

<Index Key="Monoid"><C>Monoid</C></Index>
<Index Key="MonoidByGenerators"><C>MonoidByGenerators</C></Index>

As any other monoids in &GAP;, residue-class-wise affine monoids can be
constructed by <C>Monoid</C> or <C>MonoidByGenerators</C>.

<Example>
<![CDATA[
gap> M := Monoid(RcwaMapping([[ 0,1,1],[1,1,1]]),
>                RcwaMapping([[-1,3,1],[0,2,1]]));
<rcwa monoid over Z with 2 generators>
gap> Size(M);
11
gap> Display(MultiplicationTable(M));
[ [   1,   2,   3,   4,   5,   6,   7,   8,   9,  10,  11 ], 
  [   2,   8,   5,  11,   8,   3,  10,   5,   2,   8,   5 ], 
  [   3,  10,  11,   5,   5,   5,   8,   8,   8,   2,   3 ], 
  [   4,   9,   6,   8,   8,   8,   5,   5,   5,   7,   4 ], 
  [   5,   8,   5,   8,   8,   8,   5,   5,   5,   8,   5 ], 
  [   6,   7,   4,   8,   8,   8,   5,   5,   5,   9,   6 ], 
  [   7,   5,   8,   6,   5,   4,   9,   8,   7,   5,   8 ], 
  [   8,   5,   8,   5,   5,   5,   8,   8,   8,   5,   8 ], 
  [   9,   5,   8,   4,   5,   6,   7,   8,   9,   5,   8 ], 
  [  10,   8,   5,   3,   8,  11,   2,   5,  10,   8,   5 ], 
  [  11,   2,   3,   5,   5,   5,   8,   8,   8,  10,  11 ] ]
]]>
</Example>

<Index Key="View" Subkey="for an rcwa monoid"><C>View</C></Index>
<Index Key="Display" Subkey="for an rcwa monoid"><C>Display</C></Index>
<Index Key="Print" Subkey="for an rcwa monoid"><C>Print</C></Index>
<Index Key="String" Subkey="for an rcwa monoid"><C>String</C></Index>

There are methods for the operations <C>View</C>, <C>Display</C>,
<C>Print</C> and <C>String</C> which are applicable to rcwa monoids.
All rcwa monoids over a ring <M>R</M> are submonoids of Rcwa(<M>R</M>).
The monoid Rcwa(<M>R</M>) itself is not finitely generated, thus cannot
be constructed as described above. It is handled as a special case:

<ManSection>
  <Func Name="Rcwa" Arg="R"
        Label="the monoid formed by all rcwa mappings of a ring"/>
  <Returns>
    the monoid Rcwa(<A>R</A>) of all residue-class-wise affine
    mappings of the ring&nbsp;<A>R</A>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> RcwaZ := Rcwa(Integers);
Rcwa(Z)
gap> IsSubset(RcwaZ,M);
true
]]>
</Example>
  </Description>
</ManSection>

<Index Key="Restriction"
       Subkey="for an rcwa monoid, by an injective rcwa mapping">
  <C>Restriction</C>
</Index>
<Index Key="Induction"
       Subkey="for an rcwa monoid, by an injective rcwa mapping">
  <C>Induction</C>
</Index>

In our methods to construct rcwa groups, two kinds of mappings played
a crucial role, namely the restriction monomorphisms (cf.&nbsp;<Ref
Oper="Restriction" Label="of an rcwa group, by an injective rcwa mapping"/>)
and the induction epimorphisms (cf.&nbsp;<Ref Oper="Induction"
Label="of an rcwa group, by an injective rcwa mapping"/>).
The restriction monomorphisms extend in a natural way to the monoids
Rcwa(<M>R</M>), and the induction epimorphisms have corresponding
generalizations, also. Therefore the operations <C>Restriction</C>
and <C>Induction</C> can be applied to rcwa monoids as well:

<Example>
<![CDATA[
gap> M2 := Restriction(M,2*One(Rcwa(Integers)));
<rcwa monoid over Z with 2 generators, of size 11>
gap> Support(M2);
0(2)
gap> Action(M2,ResidueClass(1,2));
Trivial rcwa group over Z
gap> Induction(M2,2*One(Rcwa(Integers))) = M;
true
]]>
</Example>

</Section>

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

<Section Label="sec:ComputingWithRcwaMonoids">
<Heading>Computing with residue-class-wise affine monoids</Heading>

<Index Key="Size" Subkey="for an rcwa monoid"><C>Size</C></Index>
<Index Key="rcwa monoids" Subkey="membership test">
  <C>rcwa monoids</C>
</Index>
<Index Key="IsSubset" Subkey="for two rcwa monoids"><C>IsSubset</C></Index>

There is a method for <C>Size</C> which computes the order of an rcwa monoid.
Further there is a method for <C>in</C> which checks whether a given
rcwa mapping lies in a given rcwa monoid (membership test), and there
is a method for <C>IsSubset</C> which checks for a submonoid relation. <P/>

<Index Key="Support" Subkey="of an rcwa monoid"><C>Support</C></Index>
<Index Key="Modulus" Subkey="of an rcwa monoid"><C>Modulus</C></Index>
<Index Key="IsTame" Subkey="for an rcwa monoid"><C>IsTame</C></Index>
<Index Key="PrimeSet" Subkey="of an rcwa monoid"><C>PrimeSet</C></Index>
<Index Key="IsIntegral" Subkey="for an rcwa monoid"><C>IsIntegral</C></Index>
<Index Key="IsClassWiseOrderPreserving" Subkey="for an rcwa monoid">
  <C>IsClassWiseOrderPreserving</C>
</Index>
<Index Key="IsSignPreserving" Subkey="for an rcwa monoid">
  <C>IsSignPreserving</C>
</Index>

There are also methods for <C>Support</C>, <C>Modulus</C>, <C>IsTame</C>,
<C>PrimeSet</C>, <C>IsIntegral</C>, <C>IsClassWiseOrderPreserving</C> and
<C>IsSignPreserving</C> available for rcwa monoids. <P/>

<Index Key="rcwa monoid" Subkey="modulus">rcwa monoid</Index>
<Index Key="rcwa monoid" Subkey="tame">rcwa monoid</Index>
<Index Key="rcwa monoid" Subkey="wild">rcwa monoid</Index>
<Index Key="rcwa monoid" Subkey="prime set">rcwa monoid</Index>
<Index Key="rcwa monoid" Subkey="integral">rcwa monoid</Index>
<Index Key="rcwa monoid" Subkey="class-wise order-preserving">
  rcwa monoid
</Index>
<Index Key="rcwa monoid" Subkey="sign-preserving">rcwa monoid</Index>

The <E>support</E> of an rcwa monoid is the union of the supports of
its elements. The <E>modulus</E> of an rcwa monoid is the lcm of the
moduli of its elements in case such an lcm exists and 0 otherwise.
An rcwa monoid is called <E>tame</E> if its modulus is nonzero, and
<E>wild</E> otherwise. The <E>prime set</E> of an rcwa monoid is the
union of the prime sets of its elements. An rcwa monoid is called
<E>integral</E>, <E>class-wise order-preserving</E> or <E>sign-preserving</E>
if all of its elements are so.

<Example>
<![CDATA[
gap> f1 := RcwaMapping([[-1, 1, 1],[ 0,-1, 1]]);;
gap> f2 := RcwaMapping([[ 1,-1, 1],[-1,-2, 1],[-1, 2, 1]]);; 
gap> f3 := RcwaMapping([[ 1, 0, 1],[-1, 0, 1]]);; 
gap> N := Monoid(f1,f2,f3);;
gap> Size(N);
366
gap> List([Monoid(f1,f2),Monoid(f1,f3),Monoid(f2,f3)],Size);
[ 96, 6, 66 ]
gap> f1*f2*f3 in N;
true
gap> IsSubset(N,M);
false
gap> IsSubset(N,Monoid(f1*f2,f3*f2));
true
gap> Support(N);
Integers
gap> Modulus(N);
6
gap> IsTame(N) and IsIntegral(N);
true
gap> IsClassWiseOrderPreserving(N) or IsSignPreserving(N);
false
gap> Collected(List(AsList(N),Image)); # The images of the elements of N.
[ [ Integers, 2 ], [ 1(2), 2 ], [ Z \ 1(3), 32 ], [ 0(6), 44 ], 
  [ 0(6) U 1(6), 4 ], [ Z \ 4(6) U 5(6), 32 ], [ 0(6) U 2(6), 4 ], 
  [ 0(6) U 5(6), 4 ], [ 1(6), 44 ], [ 1(6) U [ -1 ], 2 ], 
  [ 1(6) U 3(6), 4 ], [ 1(6) U 5(6), 40 ], [ 2(6), 44 ], 
  [ 2(6) U 3(6), 4 ], [ 3(6), 44 ], [ 3(6) U 5(6), 4 ], [ 5(6), 44 ], 
  [ 5(6) U [ 1 ], 2 ], [ [ -5 ], 1 ], [ [ -4 ], 1 ], [ [ -3 ], 1 ], 
  [ [ -1 ], 1 ], [ [ 0 ], 1 ], [ [ 1 ], 1 ], [ [ 2 ], 1 ], [ [ 3 ], 1 ], 
  [ [ 5 ], 1 ], [ [ 6 ], 1 ] ]
]]>
</Example>

Finite forward orbits under the action of an rcwa monoid can be found
by the operation <C>ShortOrbits</C>:

<ManSection>
  <Meth Name="ShortOrbits" Arg="M, S, maxlng"
        Label="for rcwa monoid, set of points and bound on length"/>
  <Returns>
    a list of finite forward orbits of the rcwa monoid&nbsp;<A>M</A>
    of length at most&nbsp;<A>maxlng</A> which start at points in
    the set&nbsp;<A>S</A>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> ShortOrbits(M,[-5..5],20);
[ [ -5, -4, 1, 2, 7, 8 ], [ -3, -2, 1, 2, 5, 6 ], [ -1, 0, 1, 2, 3, 4 ] ]
gap> Print(Action(M,last[1]),"\n");
Monoid( [ Transformation( [ 2, 3, 4, 3, 6, 3 ] ), 
  Transformation( [ 4, 5, 4, 3, 4, 1 ] ) ] )
gap> orbs := ShortOrbits(N,[0..10],100);
[ [ -5, -4, -3, -1, 0, 1, 2, 3, 5, 6 ], 
  [ -11, -10, -9, -7, -6, -5, -4, -3, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 
      11, 12 ], 
  [ -17, -16, -15, -13, -12, -11, -10, -9, -7, -6, -5, -4, -3, -1, 0, 1, 
      2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18 ] ]
gap> quots := List(orbs,orb->Action(N,orb));;
gap> List(quots,Size);
[ 268, 332, 366 ]
]]>
</Example>
  </Description>
</ManSection>

Balls of given radius around an element of an rcwa monoid can be computed
by the operation <C>Ball</C>. This operation can also be used for computing
forward orbits or subsets of such under the action of an rcwa monoid:

<ManSection>
  <Heading>
    Ball (for monoid, element and radius or monoid, point, radius and action)
  </Heading>
  <Meth Name ="Ball"
        Arg="M, f, r" Label="for monoid, element and radius"/>
  <Meth Name ="Ball"
        Arg="M, p, r, action" Label="for monoid, point, radius and action"/>
  <Returns>
    the ball of radius&nbsp;<A>r</A> around the element&nbsp;<A>f</A> in
    the monoid&nbsp;<A>M</A>, respectively
    the ball of radius&nbsp;<A>r</A> around the point&nbsp;<A>p</A> under
    the action&nbsp;<A>action</A> of the monoid&nbsp;<A>M</A>.
  </Returns>
  <Description>
    All balls are understood with respect to <C>GeneratorsOfMonoid(<A>M</A>)</C>.
    As membership tests can be expensive, the first-mentioned method does not
    check whether <A>f</A> is indeed an element of&nbsp;<A>M</A>.
    The methods require that point- / element comparisons are cheap.
    They are not only applicable to rcwa monoids.
    If the option <A>Spheres</A> is set, the ball is split up and
    returned as a list of spheres.
<Example>
<![CDATA[
gap> List([0..12],k->Length(Ball(N,One(N),k)));
[ 1, 4, 11, 26, 53, 99, 163, 228, 285, 329, 354, 364, 366 ]
gap> Ball(N,[0..3],2,OnTuples);
[ [ -3, 3, 3, 3 ], [ -1, -3, 0, 2 ], [ -1, -1, -1, -1 ], 
  [ -1, -1, 1, -1 ], [ -1, 1, 1, 1 ], [ -1, 3, 0, -4 ], [ 0, -1, 2, -3 ], 
  [ 0, 1, 2, 3 ], [ 1, -1, -1, -1 ], [ 1, 3, 0, 2 ], [ 3, -4, -1, 0 ] ]
gap> l := 2*IdentityRcwaMappingOfZ; r := l+1;
Rcwa mapping of Z: n -> 2n
Rcwa mapping of Z: n -> 2n + 1
gap> Ball(Monoid(l,r),1,4,OnPoints:Spheres);
[ [ 1 ], [ 2, 3 ], [ 4, 5, 6, 7 ], [ 8, 9, 10, 11, 12, 13, 14, 15 ], 
  [ 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ] ]
]]>
</Example>
  </Description>
</ManSection>

<Alt Only="HTML">&nbsp;</Alt>

</Section>

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

</Chapter>

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