  
  [1m[4m[31m1. Unions of Residue Classes[0m
  
  
  [1m[4m[31m1.1 Entering residue classes and unions thereof[0m
  
  [1m[4m[31m1.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. For convenience, in
  the  two-argument  case it is permitted to enclose the argument list in list
  brackets.
  
  Residue  classes  have  the  property  [22m[32mIsResidueClass[0m. Rings are regarded as
  residue  class  0 (mod 1),  and  therefore  have  this  property.  There are
  operations  [22m[32mModulus[0m and [22m[32mResidue[0m to retrieve the modulus [22m[34mm[0m resp. residue [22m[34mr[0m of
  a residue class.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> ResidueClass(2,3);[0m
    [22m[35mThe residue class 2(3) of Z[0m
    [22m[35mgap> ResidueClass(Z_pi([2,5]),2,1);[0m
    [22m[35mThe residue class 1(2) of Z_( 2, 5 )[0m
    [22m[35mgap> R := PolynomialRing(GF(2),1);;[0m
    [22m[35mgap> x := Indeterminate(GF(2),1);; SetName(x,"x");[0m
    [22m[35mgap> ResidueClass(R,x+One(R),Zero(R));[0m
    [22m[35mThe residue class 0*Z(2) ( mod x+Z(2)^0 ) of GF(2)[x][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.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 elements of [22m[34mR[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> ResidueClassUnion(Integers,6,[2,4]);[0m
    [22m[35mUnion of the residue classes 2(6) and 4(6) of Z[0m
    [22m[35mgap> 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> ResidueClassUnion(Z_pi([2,3]),8,[3,5]);[0m
    [22m[35m<union of 2 residue classes (mod 8) of Z_( 2, 3 )>[0m
    [22m[35mgap> ResidueClassUnion(R,x^2,[One(R),x],[Zero(R)],[One(R)]);[0m
    [22m[35m<union of 2 residue classes (mod x^2) of GF(2)[x]> U [ 0*Z(2) ] \ [ Z(2)^0 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  For  extracting  the  components  of  a  residue  class  union  as passed as
  arguments  to  [1m[34mResidueClassUnion[0m,  there  are  operations [22m[32mModulus[0m, [22m[32mResidues[0m,
  [22m[32mIncludedElements[0m and [22m[32mExcludedElements[0m.
  
  The  user has the choice between a longer and more descriptive and a shorter
  and less bulky output format for residue classes and unions thereof:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> ResidueClassUnionViewingFormat("short");[0m
    [22m[35mgap> ResidueClassUnion(Integers,12,[0,1,4,7,8]);  [0m
    [22m[35m0(4) U 1(6)[0m
    [22m[35mgap> ResidueClassUnionViewingFormat("long");    [0m
    [22m[35mgap> ResidueClassUnion(Integers,12,[0,1,4,7,8]);[0m
    [22m[35mUnion of the residue classes 0(4) and 1(6) of Z[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.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. A transversal for
  the   residue   classes   (mod [22m[34mm[0m)   can   be   obtained   by  the  operation
  [22m[32mAllResidues([22m[34mR[0m,[22m[34mm[0m)[0m,  and  their  number  can  be  determined  by the operation
  [22m[32mNumberOfResidues([22m[34mR[0m,[22m[34mm[0m)[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> AllResidueClassesModulo(Integers,2);[0m
    [22m[35m[ The residue class 0(2) of Z, The residue class 1(2) of Z ][0m
    [22m[35mgap> AllResidueClassesModulo(Z_pi(2),2);[0m
    [22m[35m[ The residue class 0(2) of Z_( 2 ), The residue class 1(2) of Z_( 2 ) ][0m
    [22m[35mgap> AllResidueClassesModulo(R,x);[0m
    [22m[35m[ The residue class 0*Z(2) ( mod x ) of GF(2)[x], [0m
    [22m[35m  The residue class Z(2)^0 ( mod x ) of GF(2)[x] ][0m
    [22m[35mgap> AllResidues(Integers,6);[0m
    [22m[35m[ 0 .. 5 ][0m
    [22m[35mgap> AllResidues(R,x^3);  [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 ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m1.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 which tests whether some
  ring element lies in a given union of residue classes.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> Print(ResidueClass(1,2),"\n");[0m
    [22m[35mResidueClassUnion( Integers, 2, [ 1 ] )[0m
    [22m[35mgap> 1 in ResidueClass(1,2);[0m
    [22m[35mtrue[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  There are methods for [22m[32mUnion[0m, [22m[32mIntersection[0m, [22m[32mDifference[0m and [22m[32mIsSubset[0m available
  for  unions  of residue classes. They also accept finite subsets of the base
  ring as arguments.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> S := Union(ResidueClass(0,2),ResidueClass(0,3));         [0m
    [22m[35mZ \ Union of the residue classes 1(6) and 5(6) of Z[0m
    [22m[35mgap> Intersection(S,ResidueClass(0,7));[0m
    [22m[35mUnion of the residue classes 0(14) and 21(42) of Z[0m
    [22m[35mgap> Difference(S,ResidueClass(2,4));[0m
    [22m[35mUnion of the residue classes 0(4) and 3(6) of Z[0m
    [22m[35mgap> IsSubset(ResidueClass(0,2),ResidueClass(4,8));[0m
    [22m[35mtrue[0m
    [22m[35mgap> Union(S,[1..10]);[0m
    [22m[35m(Union of the residue classes 0(2) and 3(6) of Z) U [ 1, 5, 7 ][0m
    [22m[35mgap> Intersection(S,[1..10]);[0m
    [22m[35m[ 2, 3, 4, 6, 8, 9, 10 ][0m
    [22m[35mgap> Difference(S,[1..10]);[0m
    [22m[35m(Union of the residue classes 0(2) and 3(6) of Z) \ [ 2, 3, 4, 6, 8, 9, 10 ][0m
    [22m[35mgap> Difference(Integers,[1..10]);[0m
    [22m[35mZ \ <set of cardinality 10>[0m
    [22m[35mgap> IsSubset(S,[1..10]);[0m
    [22m[35mfalse[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  If  the  underlying  ring has a residue class ring of a given cardinality t,
  then a residue class can be written as a disjoint union of t residue classes
  with equal moduli:
  
  [1m[4m[31m1.2-1 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(1,2),2);[0m
    [22m[35m[ The residue class 1(4) of Z, The residue class 3(4) of Z ][0m
    [22m[35mgap> SplittedClass(ResidueClass(Z_pi(3),3,0),2);[0m
    [22m[35mfail[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Often  one  needs 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 operation finds
  usually "reasonably short" partitions:
  
  [1m[4m[31m1.2-2 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(Difference(Integers,ResidueClass(0,12)));[0m
    [22m[35m[ The residue class 1(2) of Z, The residue class 2(4) of Z, [0m
    [22m[35m  The residue class 4(12) of Z, The residue class 8(12) of Z ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  One can compute the sets of sums, differences, products and quotients of the
  elements of a union of residue classes and an element of the base ring:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> ResidueClass(0,2) + 1;[0m
    [22m[35mThe residue class 1(2) of Z[0m
    [22m[35mgap> ResidueClass(0,2) - 2 = ResidueClass(0,2); [0m
    [22m[35mtrue[0m
    [22m[35mgap> 3 * ResidueClass(0,2);[0m
    [22m[35mThe residue class 0(6) of Z[0m
    [22m[35mgap> ResidueClass(0,2)/2;[0m
    [22m[35mIntegers[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.2-3 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.
  
  The  [22m[36mnatural  density[0m  of  a  residue  class  r(m) of a ring R is defined by
  1/|R/mR|,  and  the  [22m[36mnatural  density[0m  of a union U of finitely many residue
  classes  is  defined  by  the  sum  of  the  densities  of the elements of a
  partition of U into finitely many residue classes.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> Density(ResidueClass(0,2));[0m
    [22m[35m1/2[0m
    [22m[35mgap> Density(Difference(Integers,ResidueClass(0,5)));[0m
    [22m[35m4/5[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.2-4 RandomPartitionIntoResidueClasses[0m
  
  [1m[34m> RandomPartitionIntoResidueClasses( [0m[22m[34mR, length, primes[0m[1m[34m ) __________[0moperation
  [1mReturns:[0m  A  "random"  partition  of  the ring [22m[34mR[0m into [22m[34mlength[0m residue classes
            whose  moduli  have only prime factors in [22m[34mprimes[0m, resp. [22m[32mfail[0m if no
            such partition exists.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35m[0m
    [22m[35mgap> ResidueClassUnionViewingFormat("short");[0m
    [22m[35mgap> RandomPartitionIntoResidueClasses(Integers,30,[2,3,5,7]);[0m
    [22m[35m[ 2(7), 3(7), 4(7), 5(7), 6(7), 1(35), 8(35), 14(35), 21(35), 22(35), 28(35), [0m
    [22m[35m  29(35), 7(105), 15(105), 42(105), 50(105), 77(105), 85(105), 70(175), [0m
    [22m[35m  105(175), 35(350), 210(350), 0(525), 140(525), 315(525), 350(525), [0m
    [22m[35m  490(525), 175(1575), 700(1575), 1225(1575) ][0m
    [22m[35mgap> Union(last);[0m
    [22m[35mIntegers[0m
    [22m[35mgap> Sum(List(last2,Density));[0m
    [22m[35m1[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[31m1.3 The categories and families of unions of residue classes[0m
  
  [1m[4m[31m1.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.
  
  Often  the  same  methods  can  be  used  for residue classes of the ring of
  integers  and  of its semilocalizations. For this reason there is a category
  [22m[32mIsUnionOfResidueClassesOfZorZ_pi[0m      which      is     the     union     of
  [22m[32mIsUnionOfResidueClassesOfZ[0m  and  [22m[32mIsUnionOfResidueClassesOfZ_pi[0m. The internal
  representation     of     unions    of    residue    classes    is    called
  [22m[32mIsResidueClassUnionSparseRep[0m.
  
  [1m[4m[31m1.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 retrieved as [22m[32mUnderlyingRing(ResidueClassUnionsFamily([22m[34mR[0m))[0m.
  Unions  of  residue  classes with fixed representatives are described in the
  next chapter.
  
