  
  [1X1. Set-Theoretic Unions of Residue Classes[0X
  
  
  [1X1.1 Entering residue classes and set-theoretic unions thereof[0X
  
  [1X1.1-1 ResidueClass[0X
  
  [2X> ResidueClass( [0X[3XR, m, r[0X[2X ) __________________________________________[0Xfunction
  [2X> ResidueClass( [0X[3Xm, r[0X[2X ) _____________________________________________[0Xfunction
  [2X> ResidueClass( [0X[3Xr, m[0X[2X ) _____________________________________________[0Xfunction
  [6XReturns:[0X  In  the  three-argument  form  the  residue  class  [3Xr[0X mod [3Xm[0X of the
            ring [3XR[0X,  and in the two-argument form the residue class [3Xr[0X mod [3Xm[0X of
            the "default ring" (-> [10XDefaultRing[0X in the [5XGAP[0X Reference Manual) of
            the arguments.
  
  In  the  two-argument case, [3Xm[0X is taken to be the larger and [3Xr[0X is taken to be
  the  smaller  of  the arguments. For convenience, it is permitted to enclose
  the argument list in list brackets.
  
  Residue  classes  have  the  property  [10XIsResidueClass[0X. Rings are regarded as
  residue  class  0 (mod 1),  and  therefore  have  this  property.  There are
  operations  [10XModulus[0X and [10XResidue[0X to retrieve the modulus [3Xm[0X resp. residue [3Xr[0X of
  a residue class.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ResidueClass(2,3);[0X
    [4XThe residue class 2(3) of Z[0X
    [4Xgap> ResidueClass(Z_pi([2,5]),2,1);[0X
    [4XThe residue class 1(2) of Z_( 2, 5 )[0X
    [4Xgap> R := PolynomialRing(GF(2),1);;[0X
    [4Xgap> x := Indeterminate(GF(2),1);; SetName(x,"x");[0X
    [4Xgap> ResidueClass(R,x+One(R),Zero(R));[0X
    [4XThe residue class 0*Z(2) ( mod x+Z(2)^0 ) of GF(2)[x][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X1.1-2 ResidueClassUnion[0X
  
  [2X> ResidueClassUnion( [0X[3XR, m, r[0X[2X ) _____________________________________[0Xfunction
  [2X> ResidueClassUnion( [0X[3XR, m, r, included, excluded[0X[2X ) _________________[0Xfunction
  [6XReturns:[0X  The  union of the residue classes [3Xr[0X[i] mod [3Xm[0X of the ring [3XR[0X, plus /
            minus finite sets [3Xincluded[0X and [3Xexcluded[0X of elements of [3XR[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ResidueClassUnion(Integers,5,[1,2],[3,8],[-4,1]);[0X
    [4X(Union of the residue classes 1(5) and 2(5) of Z) U [ 3, 8 ] \ [ -4, 1 ][0X
    [4Xgap> ResidueClassUnion(Z_pi([2,3]),8,[3,5]);[0X
    [4XUnion of the residue classes 3(8) and 5(8) of Z_( 2, 3 )[0X
    [4Xgap> ResidueClassUnion(R,x^2,[One(R),x],[],[One(R)]);[0X
    [4X<union of 2 residue classes (mod x^2) of GF(2)[x]> \ [ Z(2)^0 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  When  talking about a [13Xresidue class union[0X in this chapter, we always mean an
  object as it is returned by this function.
  
  There    are    operations    [10XModulus[0X,    [10XResidues[0X,   [10XIncludedElements[0X   and
  [10XExcludedElements[0X to retrieve the components of a residue class union as they
  have originally been passed as arguments to [2XResidueClassUnion[0X.
  
  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:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ResidueClassUnionViewingFormat("short");[0X
    [4Xgap> ResidueClassUnion(Integers,12,[0,1,4,7,8]);[0X
    [4X0(4) U 1(6)[0X
    [4Xgap> ResidueClassUnionViewingFormat("long");[0X
    [4Xgap> ResidueClassUnion(Integers,12,[0,1,4,7,8]);[0X
    [4XUnion of the residue classes 0(4) and 1(6) of Z[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X1.1-3 AllResidueClassesModulo[0X
  
  [2X> AllResidueClassesModulo( [0X[3XR, m[0X[2X ) __________________________________[0Xfunction
  [2X> AllResidueClassesModulo( [0X[3Xm[0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  A sorted list of all residue classes (mod [3Xm[0X) of the ring [3XR[0X.
  
  If the argument [3XR[0X is omitted it defaults to the default ring of [3Xm[0X -- cf. the
  documentation  of [10XDefaultRing[0X in the [5XGAP[0X reference manual. A transversal for
  the   residue   classes   (mod [3Xm[0X)   can   be   obtained   by  the  operation
  [10XAllResidues([3XR[0X,[3Xm[0X)[0X,  and  their  number  can  be  determined  by the operation
  [10XNumberOfResidues([3XR[0X,[3Xm[0X)[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> AllResidueClassesModulo(Integers,2);[0X
    [4X[ The residue class 0(2) of Z, The residue class 1(2) of Z ][0X
    [4Xgap> AllResidueClassesModulo(Z_pi(2),2);[0X
    [4X[ The residue class 0(2) of Z_( 2 ), The residue class 1(2) of Z_( 2 ) ][0X
    [4Xgap> AllResidueClassesModulo(R,x);[0X
    [4X[ The residue class 0*Z(2) ( mod x ) of GF(2)[x], [0X
    [4X  The residue class Z(2)^0 ( mod x ) of GF(2)[x] ][0X
    [4Xgap> AllResidues(R,x^3);  [0X
    [4X[ 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 ][0X
    [4Xgap> NumberOfResidues(Z_pi([2,3]),360);[0X
    [4X72[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X1.2 Methods for residue class unions[0X
  
  There  are  methods  for  [10XPrint[0X,  [10XString[0X and [10XDisplay[0X which are applicable to
  residue class unions. There is a method for [10Xin[0X which tests whether some ring
  element lies in a given residue class union.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> Print(ResidueClass(1,2),"\n");[0X
    [4XResidueClassUnion( Integers, 2, [ 1 ] )[0X
    [4Xgap> 1 in ResidueClass(1,2);[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  There are methods for [10XUnion[0X, [10XIntersection[0X, [10XDifference[0X and [10XIsSubset[0X available
  for  residue  class unions. They also accept finite subsets of the base ring
  as arguments.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> S := Union(ResidueClass(0,2),ResidueClass(0,3));[0X
    [4XZ \ Union of the residue classes 1(6) and 5(6) of Z[0X
    [4Xgap> Intersection(S,ResidueClass(0,7));[0X
    [4XUnion of the residue classes 0(14) and 21(42) of Z[0X
    [4Xgap> Difference(S,ResidueClass(2,4));[0X
    [4XUnion of the residue classes 0(4) and 3(6) of Z[0X
    [4Xgap> IsSubset(ResidueClass(0,2),ResidueClass(4,8));[0X
    [4Xtrue[0X
    [4Xgap> Union(S,[1..10]);[0X
    [4X(Union of the residue classes 0(2) and 3(6) of Z) U [ 1, 5, 7 ][0X
    [4Xgap> Intersection(S,[1..6]);[0X
    [4X[ 2, 3, 4, 6 ][0X
    [4Xgap> Difference(S,[1..6]);[0X
    [4X(Union of the residue classes 0(2) and 3(6) of Z) \ [ 2, 3, 4, 6 ][0X
    [4Xgap> Difference(Integers,[1..10]);[0X
    [4XZ \ <set of cardinality 10>[0X
    [4Xgap> IsSubset(S,[1..10]);[0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  [1X1.2-1 SplittedClass[0X
  
  [2X> SplittedClass( [0X[3Xcl, t[0X[2X ) __________________________________________[0Xoperation
  [6XReturns:[0X  A  partition  of  the residue class [3Xcl[0X into [3Xt[0X residue classes with
            equal  moduli,  provided  that  such a partition exists. Otherwise
            [10Xfail[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SplittedClass(ResidueClass(1,2),2);[0X
    [4X[ The residue class 1(4) of Z, The residue class 3(4) of Z ][0X
    [4Xgap> SplittedClass(ResidueClass(Z_pi(3),3,0),2);[0X
    [4Xfail[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Often  one  needs  a  partition  of  a  given residue class union into "few"
  residue classes. The following operation takes care of this:
  
  [1X1.2-2 AsUnionOfFewClasses[0X
  
  [2X> AsUnionOfFewClasses( [0X[3XU[0X[2X ) ________________________________________[0Xoperation
  [6XReturns:[0X  A set of disjoint residue classes whose union is equal to [3XU[0X, up to
            the finite sets [10XIncludedElements([3XU[0X)[0X and [10XExcludedElements([3XU[0X)[0X.
  
  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
  guaranteed that it is minimal.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ResidueClassUnionViewingFormat("short");[0X
    [4Xgap> AsUnionOfFewClasses(Difference(Integers,ResidueClass(0,30)));[0X
    [4X[ 1(2), 2(6), 4(6), 6(30), 12(30), 18(30), 24(30) ][0X
    [4Xgap> Union(last);[0X
    [4XZ \ 0(30)[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  One can compute the sets of sums, differences, products and quotients of the
  elements of a residue class union and an element of the base ring:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ResidueClass(0,2) + 1;[0X
    [4X1(2)[0X
    [4Xgap> ResidueClass(0,2) - 2 = ResidueClass(0,2);[0X
    [4Xtrue[0X
    [4Xgap> 3 * ResidueClass(0,2);[0X
    [4X0(6)[0X
    [4Xgap> ResidueClass(0,2)/2;[0X
    [4XIntegers[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X1.2-3 PartitionsIntoResidueClasses[0X
  
  [2X> PartitionsIntoResidueClasses( [0X[3XR, length[0X[2X ) _______________________[0Xoperation
  [6XReturns:[0X  A  sorted list of all partitions of the ring [3XR[0X into [3Xlength[0X residue
            classes.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> PartitionsIntoResidueClasses(Integers,4);[0X
    [4X[ [ 0(2), 1(4), 3(8), 7(8) ], [ 0(2), 3(4), 1(8), 5(8) ], [0X
    [4X  [ 0(2), 1(6), 3(6), 5(6) ], [ 1(2), 0(4), 2(8), 6(8) ], [0X
    [4X  [ 1(2), 2(4), 0(8), 4(8) ], [ 1(2), 0(6), 2(6), 4(6) ], [0X
    [4X  [ 0(3), 1(3), 2(6), 5(6) ], [ 0(3), 2(3), 1(6), 4(6) ], [0X
    [4X  [ 1(3), 2(3), 0(6), 3(6) ], [ 0(4), 1(4), 2(4), 3(4) ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X1.2-4 RandomPartitionIntoResidueClasses[0X
  
  [2X> RandomPartitionIntoResidueClasses( [0X[3XR, length, primes[0X[2X ) __________[0Xoperation
  [6XReturns:[0X  A  "random"  partition  of  the ring [3XR[0X into [3Xlength[0X residue classes
            whose  moduli have only prime factors in [3Xprimes[0X, respectively [10Xfail[0X
            if no such partition exists.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4X[0X
    [4Xgap> RandomPartitionIntoResidueClasses(Integers,30,[2,3,5,7]);[0X
    [4X[ 0(7), 2(7), 5(7), 3(14), 10(14), 1(21), 8(21), 15(21), 18(21), 20(21), [0X
    [4X  6(63), 13(63), 25(63), 27(63), 32(63), 34(63), 46(63), 48(63), 53(63), [0X
    [4X  55(63), 4(126), 67(126), 137(189), 74(567), 200(567), 263(567), [0X
    [4X  389(567), 452(567), 11(1134), 578(1134) ][0X
    [4Xgap> Union(last);[0X
    [4XIntegers[0X
    [4Xgap> Sum(List(last2,Density));[0X
    [4X1[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X1.2-5 Density[0X
  
  [2X> Density( [0X[3XU[0X[2X ) ____________________________________________________[0Xoperation
  [6XReturns:[0X  The natural density of [3XU[0X as a subset of the underlying ring.
  
  The  [13Xnatural  density[0X  of  a  residue  class  r(m) of a ring R is defined by
  1/|R/mR|,  and  the  [13Xnatural  density[0X  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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> Density(ResidueClass(0,2));[0X
    [4X1/2[0X
    [4Xgap> Density(Difference(Integers,ResidueClass(0,5)));[0X
    [4X4/5[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  For looping over residue class unions of the integers, there are methods for
  the operations [10XIterator[0X and [10XNextIterator[0X.
  
  
  [1X1.3 The categories and families of residue class unions[0X
  
  [1X1.3-1 IsResidueClassUnion[0X
  
  [2X> IsResidueClassUnion( [0X[3XU[0X[2X ) ___________________________________________[0Xfilter
  [2X> IsResidueClassUnionOfZ( [0X[3XU[0X[2X ) ________________________________________[0Xfilter
  [2X> IsResidueClassUnionOfZ_pi( [0X[3XU[0X[2X ) _____________________________________[0Xfilter
  [2X> IsResidueClassUnionOfGFqx( [0X[3XU[0X[2X ) _____________________________________[0Xfilter
  [6XReturns:[0X  [10Xtrue[0X  if  [3XU[0X is a residue class union, a residue class union of the
            ring  of  integers, a residue class union of a semilocalization of
            the ring of integers or a residue class union of a polynomial ring
            in  one  variable  over  a  finite  field, respectively, and [10Xfalse[0X
            otherwise.
  
  Often  the  same methods can be used for residue class unions of the ring of
  integers  and of its semilocalizations. For this reason, there is a category
  [10XIsResidueClassUnionOfZorZ_pi[0X  which  is  the union of [10XIsResidueClassUnionOfZ[0X
  and  [10XIsResidueClassUnionOfZ_pi[0X. The internal representation of residue class
  unions   is  called  [10XIsResidueClassUnionResidueListRep[0X.  There  are  methods
  available for [10XExtRepOfObj[0X and [10XObjByExtRep[0X.
  
  [1X1.3-2 ResidueClassUnionsFamily[0X
  
  [2X> ResidueClassUnionsFamily( [0X[3XR[0X[2X ) ____________________________________[0Xfunction
  [2X> ResidueClassUnionsFamily( [0X[3XR, fixedreps[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  The  family  of  residue  class  unions or the family of unions of
            residue   classes   with  fixed  representatives  of  the  ring [3XR[0X,
            depending on whether [3Xfixedreps[0X is present and [10Xtrue[0X or not.
  
  The  ring [3XR[0X can be retrieved as [10XUnderlyingRing(ResidueClassUnionsFamily([3XR[0X))[0X.
  There  is  no  coercion  between  residue  class unions or unions of residue
  classes  with  fixed  representatives  which  belong  to different families.
  Unions  of  residue  classes with fixed representatives are described in the
  next chapter.
  
