  
  [1m[4m[31m3. Unions of Residue Classes[0m
  
  
  [1m[4m[31m3.1 Entering residue classes and unions thereof[0m
  
  [1m[4m[31m3.1-1 ResidueClass[0m
  
  [1m[34m> ResidueClass( [0m[22m[34mR, m, r[0m[1m[34m ) __________________________________________[0mfunction
  [1m[34m> ResidueClass( [0m[22m[34mm, r[0m[1m[34m ) _____________________________________________[0mfunction
  [1m[34m> ResidueClass( [0m[22m[34mr, m[0m[1m[34m ) _____________________________________________[0mfunction
  [1mReturns:[0m  In  the  three-argument  form  the  residue  class  [22m[34mr[0m mod [22m[34mm[0m of the
            ring [22m[34mR[0m,  and in the two-argument form the residue class [22m[34mr[0m mod [22m[34mm[0m of
            the integers.
  
  In  the two-argument case, [22m[34mr[0m and [22m[34mm[0m must not be negative, and [22m[34mr[0m is assumed to
  lie  in  the  range  [22m[32m[0..[22m[34mm[0m-1][0m. The latter is used to decide which of the two
  arguments is the modulus [22m[34mm[0m, and which is the residue [22m[34mr[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> A := ResidueClass(2,3);[0m
    [22m[35mThe residue class 2(3) of Z[0m
    [22m[35mgap> B := ResidueClass(Z_pi([2,5]),2,1);[0m
    [22m[35mThe residue class 1(2) of Z_( 2, 5 )[0m
    [22m[35mgap> R := PolynomialRing(GF(7),1);; x := Indeterminate(GF(7),1);; SetName(x,"x");[0m
    [22m[35mgap> C := ResidueClass(R,x+One(R),3*One(R));[0m
    [22m[35mThe residue class Z(7) ( mod x+Z(7)^0 ) of GF(7)[x][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.1-2 ResidueClassUnion[0m
  
  [1m[34m> ResidueClassUnion( [0m[22m[34mR, m, r[0m[1m[34m ) _____________________________________[0mfunction
  [1m[34m> ResidueClassUnion( [0m[22m[34mR, m, r, included, excluded[0m[1m[34m ) _________________[0mfunction
  [1mReturns:[0m  The  union of the residue classes [22m[34mr[0m[i] mod [22m[34mm[0m of the ring [22m[34mR[0m, plus /
            minus finite sets [22m[34mincluded[0m and [22m[34mexcluded[0m of ring elements.
  
  If  the  arguments  [22m[34mincluded[0m  and  [22m[34mexcluded[0m  are given, they must be sets of
  elements of [22m[34mR[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> D := ResidueClassUnion(Integers,6,[2,4]);[0m
    [22m[35mUnion of the residue classes 2(6) and 4(6) of Z[0m
    [22m[35mgap> F := ResidueClassUnion(Integers,5,[1,2],[3,8],[-4,1]);[0m
    [22m[35m(Union of the residue classes 1(5) and 2(5) of Z) U [ 3, 8 ] \ [ -4, 1 ][0m
    [22m[35mgap> G := ResidueClassUnion(R,x,[One(R),5*One(R),6*One(R)],[Zero(R)],[One(R)]);[0m
    [22m[35m<union of 3 residue classes (mod x) of GF(7)[x]> U [ 0*Z(7) ] \ [ Z(7)^0 ][0m
    [22m[35mgap> H := ResidueClassUnion(Z_pi([2,3]),8,[3,5]);[0m
    [22m[35m<union of 2 residue classes (mod 8) of Z_( 2, 3 )>[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.1-3 AllResidueClassesModulo[0m
  
  [1m[34m> AllResidueClassesModulo( [0m[22m[34mR, m[0m[1m[34m ) __________________________________[0mfunction
  [1m[34m> AllResidueClassesModulo( [0m[22m[34mm[0m[1m[34m ) _____________________________________[0mfunction
  [1mReturns:[0m  A sorted list of all residue classes (mod [22m[34mm[0m) of the ring [22m[34mR[0m.
  
  If the argument [22m[34mR[0m is omitted it defaults to the default ring of [22m[34mm[0m -- cp. the
  documentation of [22m[32mDefaultRing[0m in the [1mGAP[0m reference manual.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> AllResidueClassesModulo(3);[0m
    [22m[35m[ The residue class 0(3) of Z, The residue class 1(3) of Z, [0m
    [22m[35m  The residue class 2(3) of Z ][0m
    [22m[35mgap> AllResidueClassesModulo(Z_pi(2),4);[0m
    [22m[35m[ The residue class 0(4) of Z_( 2 ), The residue class 1(4) of Z_( 2 ), [0m
    [22m[35m  The residue class 2(4) of Z_( 2 ), The residue class 3(4) of Z_( 2 ) ][0m
    [22m[35mgap> AllResidueClassesModulo(R,x);[0m
    [22m[35m[ The residue class 0*Z(7) ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class Z(7)^0 ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class Z(7) ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class Z(7)^2 ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class -Z(7)^0 ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class Z(7)^4 ( mod x ) of GF(7)[x], [0m
    [22m[35m  The residue class Z(7)^5 ( mod x ) of GF(7)[x] ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  A  transversal  for  the set of residue classes (mod m) can be obtained with
  the following function:
  
  [1m[4m[31m3.1-4 AllResidues[0m
  
  [1m[34m> AllResidues( [0m[22m[34mR, m[0m[1m[34m ) ______________________________________________[0mfunction
  [1mReturns:[0m  A sorted list of all residues modulo [22m[34mm[0m in the ring [22m[34mR[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> AllResidues(Integers,6);[0m
    [22m[35m[ 0 .. 5 ][0m
    [22m[35mgap> AllResidues(Z_pi([3,5,7]),700);[0m
    [22m[35m[ 0 .. 174 ][0m
    [22m[35mgap> x := Indeterminate(GF(2),1);; SetName(x,"x");;[0m
    [22m[35mgap> R := PolynomialRing(GF(2),1); e := One(R);; z := Zero(R);;[0m
    [22m[35mGF(2)[x][0m
    [22m[35mgap> AllResidues(R,x^4+x^2);[0m
    [22m[35m[ 0*Z(2), Z(2)^0, x, x+Z(2)^0, x^2, x^2+Z(2)^0, x^2+x, x^2+x+Z(2)^0, x^3, [0m
    [22m[35m  x^3+Z(2)^0, x^3+x, x^3+x+Z(2)^0, x^3+x^2, x^3+x^2+Z(2)^0, x^3+x^2+x, [0m
    [22m[35m  x^3+x^2+x+Z(2)^0 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  For extracting the components of a residue class union as given as arguments
  in  [1m[34mResidueClassUnion[0m  ([1m3.1-2[0m),  there  are  operations  [22m[32mModulus[0m,  [22m[32mResidues[0m,
  [22m[32mIncludedElements[0m and [22m[32mExcludedElements[0m.
  
  
  [1m[4m[31m3.2 Methods for unions of residue classes[0m
  
  There  are  methods  for  [22m[32mPrint[0m,  [22m[32mString[0m and [22m[32mDisplay[0m which are applicable to
  unions  of  residue  classes.  There is a method for [22m[32min[0m to test whether some
  ring element lies in a given union of residue classes.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> 20 in A;[0m
    [22m[35mtrue[0m
    [22m[35mgap> 1/3 in B;[0m
    [22m[35mtrue[0m
    [22m[35mgap> x in G;[0m
    [22m[35mfalse[0m
    [22m[35mgap> Perform( [ C, F, H ], function( U ) Print(U,"\n"); end );[0m
    [22m[35mResidueClassUnion( GF(7)[x], x+Z(7)^0, [ Z(7) ] )[0m
    [22m[35mResidueClassUnion( Integers, 5, [ 1, 2 ], [ 3, 8 ], [ -4, 1 ] )[0m
    [22m[35mResidueClassUnion( Z_( 2, 3 ), 8, [ 3, 5 ] )[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  There  is  a method for [22m[32mIsSubset[0m available for unions of residue classes. As
  described  in  detail  in  the  sequel,  there  are  methods  for  computing
  set-theoretic  unions,  intersections  and  differences of unions of residue
  classes:
  
  [1m[4m[31m3.2-1 Union[0m
  
  [1m[34m> Union( [0m[22m[34mU1, U2[0m[1m[34m ) ____________________________________________________[0mmethod
  [1m[34m> Union( [0m[22m[34mU, S[0m[1m[34m ) ______________________________________________________[0mmethod
  [1mReturns:[0m  The  union  of  two  residue  class  unions [22m[34mU1[0m and [22m[34mU2[0m resp. of the
            residue class union [22m[34mU[0m and the finite set [22m[34mS[0m of elements of the ring
            [22m[34mU[0m is defined over.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> I := ResidueClassUnion(Integers,6,[1,5]);[0m
    [22m[35mUnion of the residue classes 1(6) and 5(6) of Z[0m
    [22m[35mgap> J := ResidueClassUnion(Integers,5,[1,2,3,4]);[0m
    [22m[35mUnion of the residue classes 1(5), 2(5), 3(5) and 4(5) of Z[0m
    [22m[35mgap> K := Union(I,J);[0m
    [22m[35m<union of 26 residue classes (mod 30) of Z>[0m
    [22m[35mgap> Residues(K);[0m
    [22m[35m[ 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 16, 17, 18, 19, 21, 22, 23, 24, [0m
    [22m[35m  25, 26, 27, 28, 29 ][0m
    [22m[35mgap> Union(K,[0]);[0m
    [22m[35m<union of 26 residue classes (mod 30) of Z> U [ 0 ][0m
    [22m[35mgap> Union(D,I);[0m
    [22m[35mUnion of the residue classes 1(3) and 2(3) of Z[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.2-2 Intersection[0m
  
  [1m[34m> Intersection( [0m[22m[34mU1, U2[0m[1m[34m ) _____________________________________________[0mmethod
  [1m[34m> Intersection( [0m[22m[34mU, S[0m[1m[34m ) _______________________________________________[0mmethod
  [1mReturns:[0m  The  intersection  of  two residue class unions [22m[34mU1[0m and [22m[34mU2[0m resp. of
            the  residue class union [22m[34mU[0m and the finite set [22m[34mS[0m of elements of the
            ring [22m[34mU[0m is defined over.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> L := Intersection(I,J);[0m
    [22m[35m<union of 8 residue classes (mod 30) of Z>[0m
    [22m[35mgap> Display(L);[0m
    [22m[35m[0m
    [22m[35mThe union of the residue classes r ( mod 30 ) of Z for r =[0m
    [22m[35m[0m
    [22m[35m  1  7 11 13 17 19 23 29[0m
    [22m[35m[0m
    [22m[35mgap> cl := List([1..25],i->ResidueClass(Integers,Primes[i],i));;[0m
    [22m[35mgap> cl_int := Intersection(cl);[0m
    [22m[35mThe residue class 941584379775558526136539054851975983([0m
    [22m[35m2305567963945518424753102147331756070) of Z[0m
    [22m[35mgap> List(Primes{[1..25]},p->Representative(cl_int) mod p);[0m
    [22m[35m[ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, [0m
    [22m[35m  22, 23, 24, 25 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.2-3 Difference[0m
  
  [1m[34m> Difference( [0m[22m[34mU1, U2[0m[1m[34m ) _______________________________________________[0mmethod
  [1m[34m> Difference( [0m[22m[34mU, S[0m[1m[34m ) _________________________________________________[0mmethod
  [1mReturns:[0m  The  difference of two residue class unions [22m[34mU1[0m and [22m[34mU2[0m resp. of the
            residue class union [22m[34mU[0m and the finite set [22m[34mS[0m of elements of the ring
            [22m[34mU[0m is defined over.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> M := Difference(I,J);[0m
    [22m[35mUnion of the residue classes 5(30) and 25(30) of Z[0m
    [22m[35mgap> N := Difference(J,I);[0m
    [22m[35m<union of 16 residue classes (mod 30) of Z>[0m
    [22m[35mgap> Display(N);[0m
    [22m[35m[0m
    [22m[35mThe union of the residue classes r ( mod 30 ) of Z for r =[0m
    [22m[35m[0m
    [22m[35m  2  3  4  6  8  9 12 14 16 18 21 22 24 26 27 28[0m
    [22m[35m[0m
    [22m[35mgap> Difference(Integers,[1,2,3]);[0m
    [22m[35mZ \ [ 1, 2, 3 ][0m
    [22m[35mgap> Difference(Z_pi([2,3,7]),[1/5,1/55]);[0m
    [22m[35mZ_( 2, 3, 7 ) \ [ 1/55, 1/5 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  If  the underlying ring has a residue class ring of some cardinality t, then
  a residue class can be written as a disjoint union of t residue classes with
  equal moduli:
  
  [1m[4m[31m3.2-4 SplittedClass[0m
  
  [1m[34m> SplittedClass( [0m[22m[34mcl, t[0m[1m[34m ) __________________________________________[0moperation
  [1mReturns:[0m  A  partition  of  the residue class [22m[34mcl[0m into [22m[34mt[0m residue classes with
            equal  moduli,  provided  that  such a partition exists. Otherwise
            [22m[32mfail[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> SplittedClass(ResidueClass(2,3),5);[0m
    [22m[35m[ The residue class 2(15) of Z, The residue class 5(15) of Z, [0m
    [22m[35m  The residue class 8(15) of Z, The residue class 11(15) of Z, [0m
    [22m[35m  The residue class 14(15) of Z ][0m
    [22m[35mgap> SplittedClass(ResidueClass(Z_pi([2,3]),3,2),2);[0m
    [22m[35m[ The residue class 2(6) of Z_( 2, 3 ), The residue class 5(6) of Z_( 2, 3 ) ][0m
    [22m[35mgap> SplittedClass(ResidueClass(Z_pi([2,3]),3,2),5);[0m
    [22m[35mfail[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Sometimes  one wants to know a partition of a given union of residue classes
  into  "few"  residue  classes. Ensuring to get always a partition of minimal
  possible  length seems to be algorithmically difficult. The following yields
  usually "reasonably short" partitions:
  
  [1m[4m[31m3.2-5 AsUnionOfFewClasses[0m
  
  [1m[34m> AsUnionOfFewClasses( [0m[22m[34mU[0m[1m[34m ) ________________________________________[0moperation
  [1mReturns:[0m  A set of disjoint residue classes whose union is [22m[34mU[0m.
  
  As  the  name of the operation suggests, it is taken care that the number of
  residue  classes  in the returned list is kept "reasonably small". It is not
  necessarily   minimal.   No   care   is   taken   of   [22m[32mIncludedElements[0m  and
  [22m[32mExcludedElements[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> AsUnionOfFewClasses(K);[0m
    [22m[35m[ The residue class 1(5) of Z, The residue class 2(5) of Z, [0m
    [22m[35m  The residue class 3(5) of Z, The residue class 4(5) of Z, [0m
    [22m[35m  The residue class 5(30) of Z, The residue class 25(30) of Z ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  One  can  add  /  subtract  a  constant to / from all elements of a union of
  residue classes, and one can multiply or divide the elements by a constant:
  
  [1m[4m[31m3.2-6 \+[0m
  
  [1m[34m> \+( [0m[22m[34mU, x[0m[1m[34m ) _________________________________________________________[0mmethod
  [1m[34m> \+( [0m[22m[34mx, U[0m[1m[34m ) _________________________________________________________[0mmethod
  [1mReturns:[0m  The set of sums u + x, u in U.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> Display(L+1);[0m
    [22m[35m[0m
    [22m[35mThe union of the residue classes r ( mod 30 ) of Z for r =[0m
    [22m[35m[0m
    [22m[35m  0  2  8 12 14 18 20 24[0m
    [22m[35m[0m
    [22m[35mgap> L+30 = L;[0m
    [22m[35mtrue[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.2-7 \-[0m
  
  [1m[34m> \-( [0m[22m[34mU, x[0m[1m[34m ) _________________________________________________________[0mmethod
  [1m[34m> \-( [0m[22m[34mx, U[0m[1m[34m ) _________________________________________________________[0mmethod
  [1m[34m> \-( [0m[22m[34mU[0m[1m[34m ) ____________________________________________________________[0mmethod
  [1mReturns:[0m  The  set of differences u - x, u in U resp. the set of differences
            x  -  u,  u  in  U  resp.  the set of the additive inverses of the
            elements of U.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> F-7;[0m
    [22m[35m(Union of the residue classes 0(5) and 4(5) of Z) U [ -4, 1 ] \ [ -11, -6 ][0m
    [22m[35mgap> -L = L;[0m
    [22m[35mtrue[0m
    [22m[35mgap> -C;[0m
    [22m[35mThe residue class Z(7)^4 ( mod x+Z(7)^0 ) of GF(7)[x][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.2-8 \*[0m
  
  [1m[34m> \*( [0m[22m[34mU, x[0m[1m[34m ) _________________________________________________________[0mmethod
  [1m[34m> \*( [0m[22m[34mx, U[0m[1m[34m ) _________________________________________________________[0mmethod
  [1mReturns:[0m  The set of products x * u, u in U.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> D*17;[0m
    [22m[35mUnion of the residue classes 34(102) and 68(102) of Z[0m
    [22m[35mgap> 2*Difference(Integers,[1,2,3]);[0m
    [22m[35m(The residue class 0(2) of Z) \ [ 2, 4, 6 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.2-9 \/[0m
  
  [1m[34m> \/( [0m[22m[34mU, x[0m[1m[34m ) _________________________________________________________[0mmethod
  [1mReturns:[0m  The set of quotients u/x, u in U.
  
  If the result would be not a subset of the underlying ring, the method gives
  up.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> D/2;[0m
    [22m[35mUnion of the residue classes 1(3) and 2(3) of Z[0m
    [22m[35mgap> M/5;[0m
    [22m[35mUnion of the residue classes 1(6) and 5(6) of Z[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The  natural  density  of  a  residue  class  r(m) of a ring R is defined by
  1/|R/mR|,  and  the  natural  density  of a union U of finitely many residue
  classes  is  defined  as  the  sum  of  the  densities  of the elements of a
  partition of U into finitely many residue classes:
  
  [1m[4m[31m3.2-10 Density[0m
  
  [1m[34m> Density( [0m[22m[34mU[0m[1m[34m ) ____________________________________________________[0moperation
  [1mReturns:[0m  The natural density of [22m[34mU[0m as a subset of the underlying ring.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> Density(G); G;[0m
    [22m[35m3/7[0m
    [22m[35m<union of 3 residue classes (mod x) of GF(7)[x]> U [ 0*Z(7) ] \ [ Z(7)^0 ][0m
    [22m[35mgap> ResidueClassUnion(Integers,12,[3,5,9]);[0m
    [22m[35mUnion of the residue classes 3(6) and 5(12) of Z[0m
    [22m[35mgap> List([last,2*last],Density);[0m
    [22m[35m[ 1/4, 1/8 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  For  looping  over  unions  of  residue  classes  of the integers, there are
  methods for the operations [22m[32mIterator[0m and [22m[32mNextIterator[0m.
  
  
  [1m[4m[31m3.3 The categories and families of unions of residue classes[0m
  
  [1m[4m[31m3.3-1 IsUnionOfResidueClasses[0m
  
  [1m[34m> IsUnionOfResidueClasses( [0m[22m[34mU[0m[1m[34m ) _______________________________________[0mfilter
  [1m[34m> IsUnionOfResidueClassesOfZ( [0m[22m[34mU[0m[1m[34m ) ____________________________________[0mfilter
  [1m[34m> IsUnionOfResidueClassesOfZ_pi( [0m[22m[34mU[0m[1m[34m ) _________________________________[0mfilter
  [1m[34m> IsUnionOfResidueClassesOfGFqx( [0m[22m[34mU[0m[1m[34m ) _________________________________[0mfilter
  [1mReturns:[0m  [22m[32mtrue[0m  if [22m[34mU[0m is a union of residue classes, resp. a union of residue
            classes  of the ring of integers, resp. a union of residue classes
            of  a  semilocalization  of the ring of integers, resp. a union of
            residue classes of a polynomial ring in one variable over a finite
            field, and [22m[32mfalse[0m otherwise.
  
  [1m[4m[31m3.3-2 ResidueClassUnionsFamily[0m
  
  [1m[34m> ResidueClassUnionsFamily( [0m[22m[34mR[0m[1m[34m ) ____________________________________[0mfunction
  [1m[34m> ResidueClassUnionsFamily( [0m[22m[34mR, fixedreps[0m[1m[34m ) _________________________[0mfunction
  [1mReturns:[0m  The family of unions of residue classes resp. the family of unions
            of  residue  classes  with  fixed  representatives  of the ring [22m[34mR[0m,
            depending on whether [22m[34mfixedreps[0m is present and [22m[32mtrue[0m.
  
  The  ring  [22m[34mR[0m can be accessed as [22m[32mUnderlyingRing(ResidueClassUnionsFamily([22m[34mR[0m))[0m.
  Unions  of  residue  classes with fixed representatives are described in the
  next chapter.
  
