  
  [1X7 Ring homomorphisms[0X
  
  A  ring  homomorphism  is  a linear function f: R -> S that maps between two
  rings  R  and  S  and  which  preserves the operations of multiplication and
  addition:
  
  
       f(a + b) = f(a) + f(b) f(ab) = f(a)f(b) f(1) = 1
  
  
  
  [1X7.1 The [9XHAPRingHomomorphism[1X datatype[0X
  
  The  [9XHAPRingHomomorphism[0m  datatype  represents  a  particular  class of ring
  homomorphisms  (in  fact  usually  ring  isomorphisms), namely those between
  rings  presented as quotient rings of polynomial rings, where the source and
  target rings have the same coefficient ring. They represent the mapping
  
  
       R/I -> S/J
  
  
  where  R  = k[x_1, ..., x_n] and S = k[y_1, ..., x_m] and I and J are ideals
  in R and S respectively.
  
  Such a ring homomorphism may be specified by the following information
  
  --    a polynomial ring R
  
  --    a list of polynomials in R that generate the ideal I
  
  --    a  list  Q = [q_1, ..., q_n] where each q_i in S/J is the image of the
        indeterminate x_i in R under the homomorphism.
  
  The target ideal J is assumed to be the image of I under the homomorphism.
  
  
  [1X7.1-1 Implementation details[0X
  
  Various  different  internal representations are used for ring homomorphisms
  in  [5XHAPprime[0m,  depending on the source and target ring. The user need not be
  concerned  with  the different representations, which correspond to the five
  constructors              [2XHAPRingToSubringHomomorphism[0m              ([14X7.2-1[0m),
  [2XHAPSubringToRingHomomorphism[0m  ([14X7.2-2[0m), [2XHAPRingHomomorphismByIndeterminateMap[0m
  ([14X7.2-3[0m),  [2XHAPRingReductionHomomorphism[0m  ([14X7.2-4[0m)  and [2XHAPZeroRingHomomorphism[0m
  ([14X7.2-5[0m), and which are hopefully largely self-explanatory.
  
  Most of the provided representations of ring homomorphisms use Gröbner bases
  and  polynomial  reduction  to  perform  the mapping. This uses the [5Xsingular[0m
  package [14X'singular: singular: the GAP interface to Singular'[0m which gives good
  speed  and  access  to  improved monomial orderings. This datatype cannot be
  used without the [5Xsingular[0m package.
  
  
  [1X7.1-2 Elimination orderings[0X
  
  Using  Gröbner bases to map from one polynomial ring R to another polynomial
  ring  S  relies on applying a global ordering to the joint ring R cup S. For
  all  polynomials  p  in R and q in S, this ordering must give p > q, so that
  terms   involving  elements  of  R  will  be  replaced  by  those  in  S.  A
  straightforward  solution  is  to  use  a  lexicographic term ordering which
  orders the indeterminates of R before those of S. However, computing Gröbner
  bases  using  a  lexicographic ordering can be much more expensive that with
  other  orderings,  or sometimes even a change of the order of indeterminates
  is enough change the order of the computation. A range of different ordering
  can  be requested by using the [5XGAP[0m options stack [14X'Reference: Options Stack'[0m,
  and  setting  the options [10XEliminationIndexOrder[0m and [10XEliminationBlockOrdering[0m
  as described below.
  
  The  option  [10XEliminationIndexOrder[0m  determines the indeterminate ordering to
  use. Possible values are the following strings:
  
  --    [10X"Forward"[0m (default) Indeterminates are ordered as in the definition of
        R and S: p_1 > p_2 > ... > p_n > q_1 > q_2 > ... > q_m.
  
  --    [10X"Reverse"[0m  Lexicographic  ordering  in  reverse  order  to that in the
        definition  of  R and S: p_n > p_n-1 > ... > p_1 > q_m > q_m-1 > ... >
        q_1.
  
  --    [10X"Shuffle"[0m  Lexicographic  ordering  using  a  random  shuffle  of  the
        indeterminates in R and S.
  
  --    [10X"ShuffleNN"[0m where [10XNN[0m is some non-negative integer. This is the same as
        [10XShuffle[0m,  but  using  the value of [10XNN[0m as the random seed (and hence is
        deterministic).
  
  When  comparing  two  monomials,  the  elimination ordering ensures that the
  parts  of the two monomials involving the indeterminates from R are compared
  first,  and  then in the event of a tie, the part involving those from S are
  compared.   The  option  [10XEliminationBlockOrdering[0m  determines  the  monomial
  ordering to use for each of these two comparisons. This is given as a string
  which  is  the concatenation of the two required orderings. For example, the
  default  ordering  is [10X"LexGrlex"[0m which means lexicographic ordering over the
  indeterminates of R, and graded lexicographic over the indeterminates of S.
  
  --    [10X"Lex"[0m  Lexicographic  ordering,  the  equivalent  of  the [5XGAP[0m ordering
        [2XMonomialLexOrdering[0m ([14XReference: MonomialLexOrdering[0m)).
  
  --    [10X"Grlex"[0m    Graded    lexicographic   ordering,   the   equivalent   of
        [2XMonomialGrlexOrdering[0m ([14XReference: MonomialGrlexOrdering[0m).
  
  --    [10X"Grevlex"[0m  Graded  reverse  lexicographic  ordering, the equivalent of
        [2XMonomialGrevlexOrdering[0m ([14XReference: MonomialGrevlexOrdering[0m).
  
  
  [1X7.2 Construction functions[0X
  
  [1X7.2-1 HAPRingToSubringHomomorphism[0m
  
  [2X> HAPRingToSubringHomomorphism( [0X[3XRring, Rrels, Simages[0X[2X ) ___________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Creates  a  [9XHAPRingHomomorphism[0m  which represents the mapping R/I -> S/J. In
  this  form, [3XRring[0m a polynomial ring R and [3XRrels[0m an ideal I in that ring. The
  image of the indeterminates of [3XR[0m under this mapping are given in [3XSimages[0m and
  generate the ring S, while the relations [3XRrels[0m are mapped to generate J. The
  ring S may be a subring of the full polynomial ring in its indeterminates.
  
  
  [1X7.2-2 HAPSubringToRingHomomorphism[0X
  
  [2X> HAPSubringToRingHomomorphism( [0X[3XRgens, Rrels, Sring[0X[2X ) _____________[0Xoperation
  [2X> HAPSubringToRingHomomorphism( [0X[3XRgens, Sring, Srels[0X[2X ) _____________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Creates  a  [9XHAPRingHomomorphism[0m which represents the mapping R/I -> S/J. The
  ring  R is generated by a set of polynomials [3XRgens[0m (so R may be a subring of
  the  full  polynomial ring in its indeterminates). The images of [3XRgens[0m under
  the  mapping  are  the indeterminates of the polynomial ring given in [3XSring[0m.
  The ideals can be specified either as a set of relations [3XSrels[0m in the target
  ring  S,  or  as a set of relations [3XRrels[0m in the source ring. In this second
  case,  [3XRrels[0m  can  be polynomials in the full polynomial ring, in which case
  the  ideal I is the intersection of the ideal they generate in the full ring
  with  the  subring generated by [3XRgens[0m. In both cases, the specified ideal is
  mapped  with  the  homomorphism  (or  its inverse) to find the corresponding
  ideal in the other ring.
  
  This  ring  homomorphism  uses Gröbner bases to perform the mapping, and the
  time  taken to calculate the basis in this function can be influenced by the
  choice of monomial ordering. See [14X7.1-2[0m for more details.
  
  [1X7.2-3 HAPRingHomomorphismByIndeterminateMap[0m
  
  [2X> HAPRingHomomorphismByIndeterminateMap( [0X[3XR, Rrels, S[0X[2X ) ____________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Creates a [9XHAPRingHomomorphism[0m which represents the map R/I -> S/J which is a
  simple  relabelling of indeterminates: the image of the ith indeterminate of
  [3XR[0m  under  the mapping is taken to be the ith indeterminate of [3XS[0m. The ideal I
  is generated by [3XRrels[0m and are mapped using the homomorphism to generate J.
  
  [1X7.2-4 HAPRingReductionHomomorphism[0m
  
  [2X> HAPRingReductionHomomorphism( [0X[3XR, Rrels[, avoid][0X[2X ) _______________[0Xoperation
  [2X> HAPRingReductionHomomorphism( [0X[3Xphi[, avoid][0X[2X ) ____________________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  For  a polynomial ring [3XR[0m and ideal I generated by [3XRrels[0m, this function finds
  an  isomorphic  ring in fewer indeterminates (or the same number, if this is
  not  possible).  This  new  ring  will avoid the indeterminates of [3XR[0m and any
  further indeterminates listed in [3Xavoid[0m. The function returns the map between
  R/I and the new ring.
  
  In  the  second  form,  this  function  reduces  the target ring of the ring
  homomorphism [3Xphi[0m and returns the map between this and the reduced ring. This
  map will also avoid the indeterminates in the source ring of [3Xphi[0m.
  
  [1X7.2-5 HAPZeroRingHomomorphism[0m
  
  [2X> HAPZeroRingHomomorphism( [0X[3XR, Rrels[0X[2X ) _____________________________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Creates  a  [9XHAPRingHomomorphism[0m  which  maps  from the ring R, with an ideal
  generated by [3XRrels[0m, into the trival ring generated by zero.
  
  [1X7.2-6 InverseRingHomomorphism[0m
  
  [2X> InverseRingHomomorphism( [0X[3Xphi[0X[2X ) __________________________________[0Xattribute
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Returns (as a ring homomorphism) the inverse of the ring homomorphism [3Xphi[0m.
  
  If the inverse homomorphism requires an elimination Gröbner basis to perform
  the mapping (for example when computing the inverse of a [9XHAPRingHomomorphism[0m
  constructed with [2XHAPRingToSubringHomomorphism[0m ([14X7.2-1[0m)) then the ordering can
  be specified using the options stack. See [14X7.1-2[0m for more details.
  
  [1X7.2-7 CompositionRingHomomorphism[0m
  
  [2X> CompositionRingHomomorphism( [0X[3XphiA, phiB[0X[2X ) _______________________[0Xoperation
  [6XReturns:[0X  [9XHAPRingHomomorphism[0m
  
  Returns   the  ring  homomorphism  that  is  the  composition  of  the  ring
  homomorphisms  [3XphiA[0m  and  [3XphiB[0m. The source ring of [3XphiB[0m must be in the image
  ring of [3XphiA[0m.
  
  
  [1X7.3 Data access functions[0X
  
  [1X7.3-1 SourceGenerators[0m
  
  [2X> SourceGenerators( [0X[3Xphi[0X[2X ) _________________________________________[0Xattribute
  [6XReturns:[0X  List
  
  A list of generators for the source ring R/I of the ring homomorphism. [3Xphi[0m.
  
  [1X7.3-2 SourceRelations[0m
  
  [2X> SourceRelations( [0X[3Xphi[0X[2X ) __________________________________________[0Xattribute
  [6XReturns:[0X  List
  
  A  list  of the relations that generate the ideal I of in the source ring of
  the ring homomorphism [3Xphi[0m.
  
  [1X7.3-3 SourcePolynomialRing[0m
  
  [2X> SourcePolynomialRing( [0X[3Xphi[0X[2X ) _____________________________________[0Xattribute
  [6XReturns:[0X  [9XPolynomialRing[0m
  
  Returns  the  polynomial  ring  which  contains  the source ring of the ring
  homomorphism [3Xphi[0m. Polynomials to be mapped by [3Xphi[0m must be in this ring.
  
  [1X7.3-4 ImageGenerators[0m
  
  [2X> ImageGenerators( [0X[3Xphi[0X[2X ) __________________________________________[0Xattribute
  [6XReturns:[0X  List
  
  A list of generators for the image ring S/J of the ring homomorphism [3Xphi[0m.
  
  [1X7.3-5 ImageRelations[0m
  
  [2X> ImageRelations( [0X[3Xphi[0X[2X ) ___________________________________________[0Xattribute
  [6XReturns:[0X  List
  
  A  list  of  the relations that generate the ideal J of in the image ring of
  the ring homomorphism [3Xphi[0m.
  
  [1X7.3-6 ImagePolynomialRing[0m
  
  [2X> ImagePolynomialRing( [0X[3Xphi[0X[2X ) ______________________________________[0Xattribute
  [6XReturns:[0X  [9XPolynomialRing[0m
  
  Returns   the   polynomial  ring  which  contains  the  image  of  the  ring
  homomorphism [3Xphi>[0m. All polynomials mapped by [3Xphi[0m will be in this ring.
  
  
  [1X7.4 General functions[0X
  
  
  [1X7.4-1 ImageOfRingHomomorphism[0X
  
  [2X> ImageOfRingHomomorphism( [0X[3Xphi, poly[0X[2X ) ____________________________[0Xoperation
  [2X> ImageOfRingHomomorphism( [0X[3Xphi, coll[0X[2X ) ____________________________[0Xoperation
  [6XReturns:[0X  Polynomial or list
  
  Returns  the  image  of the polynomial [3Xpoly[0m under the ring homomorphism [3Xphi[0m.
  The   input   must  be  an  element(s)  of  the  source  ring  of  [3Xphi[0m  (see
  [2XSourcePolynomialRing[0m ([14X7.3-3[0m)).
  
  
  [1X7.4-2 PreimageOfRingHomomorphism[0X
  
  [2X> PreimageOfRingHomomorphism( [0X[3Xphi, poly[0X[2X ) _________________________[0Xoperation
  [2X> PreimageOfRingHomomorphism( [0X[3Xphi, coll[0X[2X ) _________________________[0Xoperation
  [6XReturns:[0X  Polynomial or list
  
  Returns the preimage of the polynomial [3Xpoly[0m under the ring homomorphism [3Xphi[0m.
  The   input   must   be  an  element(s)  of  the  image  ring  of  [3Xphi[0m  (see
  [2XImagePolynomialRing[0m    ([14X7.3-6[0m)).    This   function   is   a   synonym   for
  [10XImageOfRingHomomorphism(InverseRingHomomorphism(phi), poly)[0m.
  
  
  [1X7.5 Example: Constructing and using a [9XHAPRingHomomorphism[1X[0X
  
  As  an  initial  example, we shall construct a ring homomorphism phi: k[x_1,
  x_2]  -> k[x_3, x_4] (i.e. ideal) with the mapping x_1 -> x_3 and x_2 -> x_3
  +  x_4.  In  all  these  examples,  we  shall  take k to be the field of two
  elements,  GF(2).  We  demonstrate  that this is an isomorphism by mapping a
  polynomial from the source ring to the target and back again.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> R := PolynomialRing(GF(2), 2);;[0X
    [4Xgap> S := PolynomialRing(GF(2), 2, IndeterminatesOfPolynomialRing(R));;[0X
    [4Xgap> phi := HAPRingToSubringHomomorphism(R, [], [S.1, S.1+S.2]);[0X
    [4X<Ring homomorphism>[0X
    [4Xgap> p := ImageOfRingHomomorphism(phi, R.1^3+R.1*R.2+R.2);[0X
    [4Xx_3^3+x_3^2+x_3*x_4+x_3+x_4[0X
    [4Xgap> PreimageOfRingHomomorphism(phi, p);[0X
    [4Xx_1^3+x_1*x_2+x_2[0X
  [4X------------------------------------------------------------------[0X
  
  Some ring presentations are not in minimal form: there is an isomorphic ring
  in  fewer  indeterminates. The [2XHAPRingReductionHomomorphism[0m ([14X7.2-4[0m) function
  can  find  and  return  an  isomorphism  that maps to this reduced ring. For
  example,  the  ring  k[x_1,  x_2,  x_3]/(x_1^2  + x_2^3, x_2^2 + x_3) has an
  isomorphic  presentation  in  only  two  indeterminates, as this computation
  shows:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> R := PolynomialRing(GF(2), 3);;[0X
    [4Xgap> I := [R.1^2+R.2^3, R.2^2+R.3];[0X
    [4X[ x_2^3+x_1^2, x_2^2+x_3 ][0X
    [4Xgap> phi := HAPRingReductionHomomorphism(R, I);[0X
    [4X<Ring homomorphism>[0X
    [4Xgap> ImagePolynomialRing(phi);[0X
    [4XGF(2)[x_4,x_5][0X
    [4Xgap> ImageRelations(phi);[0X
    [4X[ x_5^3+x_4^2 ][0X
  [4X------------------------------------------------------------------[0X
  
  The source and target of [10XHAPRingHomomorphism[0ms can be quotient rings, and any
  relations  can  be  specified  at  the source of target. When mapping from a
  subring  to  a full ring, the source relations do not necessarily need to be
  specified  in  the source ring, but could instead be given in its containing
  ring.  For example, consider the ring R/I where R = k[x_1, x_2, x_3] and I =
  x_1^3+x_3  and  the  subring  generated  by (x_1, x_2, x_3^2). If we wish to
  specify the homomorphism phi: R/I -> S/J where S = k[x_4, x_5, x_6] with the
  natural map from the generators of R to those of S then we only need specify
  the original ideal I, even though it is not in the subring. The intersection
  between  I  and the subring is found to be x_1^4+x_3^2, and it is this ideal
  that is used in the homomorphism, as this example shows:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> R := PolynomialRing(GF(2), 3);;[0X
    [4Xgap> I := [R.1^2+R.3];[0X
    [4X[ x_1^2+x_3 ][0X
    [4Xgap> S := PolynomialRing(GF(2), 3, IndeterminatesOfPolynomialRing(R));;[0X
    [4Xgap> phi := HAPSubringToRingHomomorphism([R.1, R.2, R.3^2], I, S);[0X
    [4X<Ring homomorphism>[0X
    [4Xgap> Display(phi);[0X
    [4XRing homomorphism[0X
    [4X  x_1 -> x_4[0X
    [4X  x_2 -> x_5[0X
    [4X  x_3^2 -> x_6[0X
    [4Xwith relations[0X
    [4X  [ x_1^2+x_3 ][0X
    [4Xand[0X
    [4X  [ x_4^4+x_6 ][0X
    [4Xgap> Display(InverseRingHomomorphism(phi));[0X
    [4XRing homomorphism[0X
    [4X  x_4 -> x_1[0X
    [4X  x_5 -> x_2[0X
    [4X  x_6 -> x_3^2[0X
    [4Xwith relations[0X
    [4X  [ x_4^4+x_6 ][0X
    [4Xand[0X
    [4X  [ x_1^4+x_3^2 ][0X
  [4X------------------------------------------------------------------[0X
  
  Ring homomorphisms can also be composed with each other. For example, we can
  take  the  [2XHAPSubringToRingHomomorphism[0m  ([14X7.2-2[0m) above and change the target
  indeterminates         by         composing        this        with        a
  [2XHAPRingHomomorphismByIndeterminateMap[0m ([14X7.2-3[0m):
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> R := PolynomialRing(GF(2), 3);;[0X
    [4Xgap> I := [R.1^2+R.3];[0X
    [4X[ x_1^2+x_3 ][0X
    [4Xgap> S := PolynomialRing(GF(2), 3, IndeterminatesOfPolynomialRing(R));;[0X
    [4Xgap> phi := HAPSubringToRingHomomorphism([R.1, R.2, R.3^2], I, S);[0X
    [4X<Ring homomorphism>[0X
    [4Xgap> #[0X
    [4Xgap> T := PolynomialRing(GF(2), 3, [R.1, R.2, R.3, S.1, S.2, S.3]);;[0X
    [4Xgap> phi2 := HAPRingHomomorphismByIndeterminateMap([0X
    [4X>   ImagePolynomialRing(phi), ImageRelations(phi), T);[0X
    [4X<Ring homomorphism>[0X
    [4Xgap> Display(CompositionRingHomomorphism(phi, phi2));[0X
    [4XRing homomorphism[0X
    [4X  x_1 -> x_7[0X
    [4X  x_2 -> x_8[0X
    [4X  x_3^2 -> x_9[0X
    [4Xwith relations[0X
    [4X  [ x_1^2+x_3 ][0X
    [4Xand[0X
    [4X  [ x_7^4+x_9 ][0X
  [4X------------------------------------------------------------------[0X
  
