D. Semilinear expressions
  
  
  D.1 Semilinear Sets
  
  A  semilinear  set,  is  a finite union of linear sets, i.e., of sets of the
  form  a+b_1Bbb  N+  cdots  +b_pBbb  N,  with  a, b_1, ..., b_pin Bbb N^n. We
  consider  also  sets  of  the form a+b_1Bbb Z+ cdots +b_pBbb Z, with a, b_1,
  ...,  b_pin  Bbb Z^n, i.e., cosets of subgroups of Bbb Z^n. We call them Bbb
  Z-linear.   Finite   unions  of  Bbb  Z-linear  sets  are  then  called  Bbb
  Z-semilinear.  An  expression of the form a+b_1N+ cdots +b_pN , with a, b_1,
  ...,  b_pin  Bbb  N^n,  is said to be a linear expression. Let us call n its
  arity,  a  its  base  point  and  b_1,  ...,  b_p  its  vectors.  (Analogous
  definitions  may  be  given  for Bbb Z-linear sets.) Linear and Bbb Z-linear
  sets may be given using the functions that follow.
  
  D.1-1 NLinear
  
  > NLinear( arity, base\_point, vectors ) ___________________________function
  
  Returns a linear set. The meaning of the arguments should already be clear.
  
  ---------------------------  Example  ----------------------------
    gap> LN := NLinear(2,[0,1],[[1,2],[5,2]]);
    [ 0, 1 ] + [ 1, 2 ] N  + [ 5, 2 ] N 
  ------------------------------------------------------------------
  
  D.1-2 ZLinear
  
  > ZLinear( arity, base\_point, vectors ) ___________________________function
  
  Returns  a  Bbb Z-linear set. The meaning of the arguments should already be
  clear.
  
  ---------------------------  Example  ----------------------------
    gap> LZ := ZLinear(2,[0,1],[[1,2],[5,2]]);
    [ 0, 1 ] + [ 1, 2 ] Z  + [ 0, 8 ] Z 
  ------------------------------------------------------------------
  
  In  the  case  of  a Bbb Z-linear set the expression returned represents the
  same  linear  set  than  the expression given, but the vectors have changed:
  they  are  the  nonzero rows of a matrix in Hermite Normal Form. Notice that
  a+b_1Bbb  Z+ cdots +b_pBbb Z, with a, b_1, ..., b_pin Bbb Z^n, is a coset of
  the subgroup of Bbb Z^n generated by the vectors b_1, ..., b_pin Bbb Z^n. In
  general,  when we give an expression for such a coset to \GAP\ an expression
  involving  a  basis  for the subgroup consisting of the nonzero vectors of a
  matrix in HNF is returned.
  
  
  D.2 Operations with semilinear sets
  
  We  may compute expressions for the product, union and star (i.e., submonoid
  generated  by)  of  semilinear  and  Bbb  Z-semilinear  sets. In some cases,
  specially for Bbb Z-semilinear expressions, simpler expressions representing
  the  same  set  are  returned.  Of  course,  these operations may be used to
  construct more complex expressions.
  
  For  linear  or  semilinear expressions we have the following functions that
  return  respectively  semilinear  expressions  for  the union and sum of the
  languages  given  by  the semilinear expressions r and s and the star of the
  language given by the semilinear expression r.
  
  D.2-1 UnionNSemilinear
  
  > UnionNSemilinear( r, s ) _________________________________________function
  D.2-2 SumNSemilinear
  
  > SumNSemilinear( r, s ) ___________________________________________function
  D.2-3 StarNSemilinear
  
  > StarNSemilinear( r ) _____________________________________________function
  
  Some examples involving linear expressions:
  
  ---------------------------  Example  ----------------------------
    gap> s1 := NLinear(2,[0,3],[[1,2],[5,2]]);          
    [ 0, 3 ] + [ 1, 2 ] N  + [ 5, 2 ] N 
    gap> s2 := NLinear(2,[1,1],[[3,2],[0,3]]);          
    [ 1, 1 ] + [ 3, 2 ] N  + [ 0, 3 ] N 
    gap> UnionNSemilinear(s1,s2);                       
    [ [ 0, 3 ] + [ 1, 2 ] N  + [ 5, 2 ] N , [ 1, 1 ] + [ 3, 2 ] N  + [ 0, 3 ] N  ]
    gap> StarNSemilinear(s1);                           
    [ [ 0, 0 ], [ 0, 3 ] + [ 0, 3 ] N  + [ 1, 2 ] N  + [ 5, 2 ] N  ]
    gap> SumNSemilinear(s1,s2);                         
    [ [ 1, 4 ] + [ 0, 3 ] N  + [ 1, 2 ] N  + [ 3, 2 ] N  + [ 5, 2 ] N  ]
  ------------------------------------------------------------------
  
  The  analogous  functions  for Bbb Z-linear and Bbb Z-semilinear expressions
  follow:
  
  D.2-4 UnionZSemilinear
  
  > UnionZSemilinear( r, s ) _________________________________________function
  D.2-5 SumZSemilinear
  
  > SumZSemilinear( r, s ) ___________________________________________function
  D.2-6 StarZSemilinear
  
  > StarZSemilinear( r ) _____________________________________________function
  
  Now, some examples involving Bbb Z-linear expressions
  
  ---------------------------  Example  ----------------------------
    gap> z1 := ZLinear(2,[0,3],[[1,2],[5,2]]);
    [ 0, 3 ] + [ 1, 2 ] Z  + [ 0, 8 ] Z 
    gap> z2 := ZLinear(2,[1,1],[[3,2],[0,3]]);
    [ 1, 1 ] + [ 3, 2 ] Z  + [ 0, 3 ] Z 
    gap> UnionZSemilinear(z1,z2);
    [ [ 0, 3 ] + [ 1, 2 ] Z  + [ 0, 8 ] Z , [ 1, 1 ] + [ 3, 2 ] Z  + [ 0, 3 ] Z  ]
    gap> SumZSemilinear(z1,z2);
    [ [ 0, 0 ] + [ 1, 0 ] Z  + [ 0, 1 ] Z  ]
    gap> StarZSemilinear(z2);
    [ [ 0, 0 ] + [ 1, 0 ] Z  + [ 0, 1 ] Z  ]
  ------------------------------------------------------------------
  
  Let  S  be  a  subgroup  of Bbb Z^n. An element xin Bbb Z^n belongs to a Bbb
  Z-semilinear  set  z+S if and only if the subgroup generated by x-z and S is
  equal to S. This test may be done computing basis for the subgroups < x-z,S>
  and S consisting of the nonzero vectors of a matrix in HNF and testing their
  equality.  Recall that an integer matrix B is row equivalent over Bbb Z to a
  unique matrix A in Hermite normal form. (See, for example, [S94] .)
  
  D.2-7 BelongsZLinear
  
  > BelongsZLinear( x, L ) ___________________________________________function
  
  Tests if x belongs to the Bbb Z-linear set L
  
  ---------------------------  Example  ----------------------------
    gap> BelongsZLinear([5,27],z2);
    false
  ------------------------------------------------------------------
  
  D.2-8 BelongsZSemilinear
  
  > BelongsZSemilinear( x, L ) _______________________________________function
  
  Tests if x belongs to the Bbb Z-semilinear set L
  
  ---------------------------  Example  ----------------------------
    gap>  BelongsZSemilinear([5,29],UnionZSemilinear(z1,z2));
    true
  ------------------------------------------------------------------