  
  [1X2 [33X[0;0YUsage[133X[101X
  
  [33X[0;0YUnless  otherwise  specified,  all  the  functions described below taking an
  argument  [9Xn[109X  do whatever the manual says they do up to homological degree [9Xn[109X.
  These  functions  are idempotent in the sense that called a second time with
  the  same  argument  [9Xn[109X,  they  do  nothing, but called with a bigger [9Xn[109X, they
  continue computing from where the previous calculations finished.[133X
  
  
  [1X2.1 [33X[0;0YCohomology Objects[133X[101X
  
  [33X[0;0YThe  computation  of  group  cohomology  involves  several calculations, the
  results of which are reused in later calculations, and are thus collected in
  an object of type [9XCObject[109X, which is created with the following command.[133X
  
  [1X2.1-1 CohomologyObject[101X
  
  [33X[1;0Y[29X[2XCohomologyObject[102X( [3XG[103X, [3XM[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XCohomologyObject[102X( [3XG[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ya [9XCObject[109X.[133X
  
  [33X[0;0YThis  function  creates  a  [9XCObject[109X  having components the [22Xp[122X-group [9XG[109X and the
  [5XMeatAxe[105X  module  [9XM[109X,  which should be a [22XkG[122X-module where [22XG[122X the group [9XG[109X and [22Xk[122X a
  field of characteristic [22Xp[122X. Note that [5XMeatAxe[105X modules know what [22Xk[122X is, but not
  what  [22XG[122X  is,  which is why this operation requires the user to specify [22XG[122X but
  not [22Xk[122X.[133X
  
  [33X[0;0YFortunately,  most  users don't need to know anything about [5XMeatAxe[105X modules,
  being  interested primarily in the case where [22Xk=GF(p)[122X and [22XM=k[122X is the trivial
  [22XkG[122X-module.  In  this  situation,  the second invocation creates a cohomology
  object  having  components  the  [22Xp[122X-group [22XG[122X and the trivial [5XMeatAxe[105X [22XkG[122X-module
  [22Xk=GF(p)[122X.[133X
  
  [33X[0;0YWe  emphasize  that  in  the  first  invocation,  [22Xk[122X  can  be  any  field  of
  characteristic  [22Xp[122X  and  [9XM[109X  can  be  any  [5XMeatAxe[105X  module  over  [22XkG[122X, and that
  [9XProjectiveResolution[109X  works  when [9XM[109X is an arbitrary [5XMeatAxe[105X module, but that
  all  the functions dealing with the ring-structure of [22XH*(G,k)[122X require that [9XM[109X
  be the trivial module.[133X
  
  [33X[0;0YThe  cohomology  object is used to store, in addition to the items mentioned
  above, the boundary maps, the Betti numbers, the multiplication table, etc.[133X
  
  
  [1X2.2 [33X[0;0YMinimal Projective Resolutions[133X[101X
  
  [33X[0;0YGiven  a  [22Xp[122X-group  [22XG[122X,  a field [22Xk[122X of characteristic [22Xp[122X, and a [22XkG[122X-module [22XM[122X, the
  function  below  computes the beginning of the minimal projective resolution
  of [22XM[122X[133X
  
  
  [24X[33X[0;6YP_n -> ... -> P_2 -> P_1 -> P_0 -> M -> 0[133X
  
  [124X
  
  [33X[0;0Ywhere  [22XP_i[122X  is  the direct sum [22X(kG)^(b_i)[122X for certain numbers [22Xb_i[122X, the [13XBetti
  numbers[113X  of  the  resolution.  The  minimal [22XkG[122X-projective resolution of [22XM[122X is
  unique  up  to  chain isomorphism. Because of the minimality of [22XP[122X the groups
  [22XExt^i(M,N)[122X  are  simply  [22XHom(P_i,N)[122X,  and  if  [22XM[122X  and [22XN[122X are both the trivial
  [22XkG[122X-module [22Xk[122X, then [22XH^i(G,k)=Ext^i(k,k)=k^(b_i)[122X.[133X
  
  [1X2.2-1 ProjectiveResolution[101X
  
  [33X[1;0Y[29X[2XProjectiveResolution[102X( [3XC[103X, [3Xn[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ya list containing the Betti numbers [22Xb_0, b_1,..., b_n[122X.[133X
  
  [33X[0;0YGiven  a  cohomology  object  [9XC[109X  having  components  [22XG[122X  and [22XM[122X, this function
  computes  the first [9Xn[109X[22X+1[122X terms of the minimal projective resolution [22XP[122X of [22XM[122X of
  the  form  [22XP_i=(kG)^(b_i)[122X  for  [22Xi=0,1,...,n[122X and returns the numbers [22Xb_i[122X as a
  list.[133X
  
  [1X2.2-2 BoundaryMap[101X
  
  [33X[1;0Y[29X[2XBoundaryMap[102X( [3XC[103X, [3Xn[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ythe [9Xn[109Xth boundary map.[133X
  
  [33X[0;0YGiven   the  cohomology  object  [9XC[109X,  this  function  computes  a  projective
  resolution  to  degree [9Xn[109X if it hasn't been computed already, and returns the
  [9Xn[109Xth boundary map [22XP_n → P_n-1[122X.[133X
  
  [33X[0;0YThe map returned is a [22Xb_n x b_n-1|G|[122X matrix, having in the [22Xi[122Xth row the image
  of the element [22X1_G[122X from the [22Xi[122Xth direct summand of [22XP_n[122X.[133X
  
  [33X[0;0YSee the file [9Xdoc/example.*[109X for an example of the usage and interpretation of
  the result of this function.[133X
  
  
  [1X2.3 [33X[0;0YCohomology Generators and Relators[133X[101X
  
  [33X[0;0YSee  [2]  for  the  details  of the calculation of cohomology products using
  composition  of  chain  maps.  See  also  the  file [9Xdoc/explanation.*[109X for an
  explanation of the implementation.[133X
  
  [1X2.3-1 CohomologyGenerators[101X
  
  [33X[1;0Y[29X[2XCohomologyGenerators[102X( [3XC[103X, [3Xn[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ya  list  containing  the  degrees  of  the  elements  of  a set of
            generators of the cohomology ring.[133X
  
  [33X[0;0YGiven  a  cohomology  object [9XC[109X having group component [22XG[122X and module component
  the trivial [22XkG[122X-module, this function computes a set of generators of [22XH*(G,k)[122X
  having  degree  [9Xn[109X or less, and stores them in [9XC[109X. The function returns a list
  of the degrees of these generators.[133X
  
  [33X[0;0YThe actual cohomology generators are represented by maps [22XP_i → k[122X for [22X0le ile
  n[122X and are stored in [9XC[109X as matrices. Only their degrees are returned.[133X
  
  [1X2.3-2 CohomologyRelators[101X
  
  [33X[1;0Y[29X[2XCohomologyRelators[102X( [3XC[103X, [3Xn[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ya list of generators and a list of relators.[133X
  
  [33X[0;0YGiven a cohomology object [9XC[109X having group component [22XG[122X and module component [22Xk[122X,
  this  function  computes  a  set  of  generators of the ideal of relators in
  [22XH*(G,k),[122X all having degree [22Xn[122X or less.[133X
  
  [33X[0;0YMore specifically, the function returns two lists, the first list containing
  the  variables  [9Xz[109X,  [9Xy[109X,  [9Xx[109X, [22X...[122X corresponding to the generators of [22XH*(G,k)[122X if
  there  are  fewer  than 12 generators and containing the variables [9Xx_1[109X, [9Xx_2[109X,
  [9Xx_3[109X,  [22X...[122X  otherwise.  The  second  list  is  a  list  of polynomials in the
  variables from the first list.[133X
  
  [33X[0;0YThese  two  lists should be interpreted as follows. A degree [9Xn[109X approximation
  of the cohomology ring [22XH*(G,k)[122X is given by the polynomial ring over [22Xk[122X in the
  non-commuting  variables  from  the first list, (having degrees given by the
  list  returned by [9XCohomologyGenerators[109X in section [14X2.3-1[114X ) and subject to the
  relators in the second list. See section [14X2.6[114X for more details still.[133X
  
  [33X[0;0YFor example, consider the following commands.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X[128X[104X
    [4X[25Xgap>[125X [27XC:=CohomologyObject(DihedralGroup(8));[127X[104X
    [4X[28X<object>[128X[104X
    [4X[25Xgap>[125X [27XCohomologyGenerators(C,10);[127X[104X
    [4X[28X[ 1, 1, 2 ][128X[104X
    [4X[25Xgap>[125X [27XCohomologyRelators(C,10);[127X[104X
    [4X[28X[ [ z, y, x ], [ z*y+y^2 ] ][128X[104X
  [4X[32X[104X
  
  [33X[0;0YThis  tells us that for [22XG=D_8[122X and [22Xk=GF(p)[122X the cohomology ring [22XH*(G,k)[122X is the
  graded-commutative polynomial ring in the variables [22Xz[122X, [22Xy[122X, [22Xx[122X of degrees 1, 1,
  2, subject to the relation [22Xzy+y^2[122X. But since [22XH*(G,k)[122X is commutative, [22Xk[122X being
  of  characteristic  2, we have [22XH*(G,k)=k[z,y,x]/(zy+y^2)[122X. This result can be
  further improved by taking [22Xz=z+y[122X, giving [22XH*(G,k)=k[z,y,x]/(zy)[122X.[133X
  
  [33X[0;0YObserve  that  in  this  case,  we  knew  in advance that there was a set of
  generators  for [22XH*(G,k)[122X all having degree less than 10, and that there was a
  set  of  generators of the ideal of relators all having degree less than 10.
  See see section [14X2.6[114X for details.[133X
  
  [33X[0;0YWhile  this isn't likely to occur, we point out that if there are 12 or more
  generators  and  some  of the indeterminates [9Xx_1[109X, [9Xx_2[109X, [9Xx_3[109X, [22X...[122X have already
  been  named,  say  by  a  previous  call  to  [9XCohomologyRelators[109X, then these
  variables  will  retain  their  old  names.  If this is confusing, you could
  restart [5XGAP[105X and do it again.[133X
  
  [33X[0;0YFinally,  [9XCohomologyRelators[109X  is  [13Xnot[113X  idempotent for efficiency reasons, so
  sadly,  if  you don't uncover all the relators the first time, you will have
  to start all over from the beginning.[133X
  
  
  [1X2.4 [33X[0;0YTests for Completion[133X[101X
  
  [33X[0;0YA  test  or series of tests for completion of the calculation will hopefully
  be implemented soon. See [2] for the details.[133X
  
  
  [1X2.5 [33X[0;0YCohomology Rings[133X[101X
  
  [33X[0;0YWhereas  the operations in sections [14X2.3-1[114X and [14X2.3-2[114X calculate a presentation
  for  the  cohomology  ring, the operation below creates the ring in [5XGAP[105X as a
  structure constant algebra.[133X
  
  [33X[0;0YSee  [2]  for  the  details  of the calculation of cohomology products using
  composition  of  chain  maps.  See  also  the  file [9Xdoc/explanation.*[109X for an
  explanation of the implementation.[133X
  
  [1X2.5-1 CohomologyRing[101X
  
  [33X[1;0Y[29X[2XCohomologyRing[102X( [3XC[103X, [3Xn[103X ) [32X operation[133X
  [33X[1;0Y[29X[2XCohomologyRing[102X( [3XG[103X, [3Xn[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Ythe cohomology ring of [22XG[122X.[133X
  
  [33X[0;0YGiven  a cohomology object [9XC[109X with group component [22XG[122X and module component the
  trivial  [22XkG[122X-module,  this  function  returns  the degree [9Xn[109X truncation of the
  cohomology  ring  [22XH*(G,k)[122X.  See  [14X2.6[114X for what this means exactly. The object
  returned is a structure constant algebra.[133X
  
  [33X[0;0YUsers  interested  only  in working with the cohomology ring of a group as a
  [5XGAP[105X  object, and not in calculating generators, relators, induced maps, etc,
  can use the second invocation of this function, which returns the cohomology
  ring   of   the   group   [9XG[109X  immediately,  throwing  away  all  intermediate
  calculations.[133X
  
  [33X[0;0YObserve   that  the  object  returned  is  a  degree  [9Xn[109X  truncation  of  the
  infinite-dimensional   cohomology  ring.  A  consequence  of  this  is  that
  multiplying  two elements whose product has degree greater than [9Xn[109X results in
  zero, whether or not the product is really zero.[133X
  
  [33X[0;0YObserve  also that calling [9XCohomologyRing[109X a second time with a bigger [9Xn[109X does
  [13Xnot[113X  extend the previous ring, but rather, recalculates the entire ring from
  the  beginning.  Extending  the  previous  ring  appears not to be worth the
  effort  for  technical  reasons,  since  almost  everything would need to be
  recalculated again anyway.[133X
  
  [33X[0;0YRecall that [22XH*(G,k)[122X is a graded algebra, the components being the cohomology
  groups  [22XH^i(G,k)[122X.  The  following  functions  were  intended  to be used for
  cohomology  rings,  but  in  principle,  they  work for any graded structure
  constant algebra.[133X
  
  [1X2.5-2 IsHomogeneous[101X
  
  [33X[1;0Y[29X[2XIsHomogeneous[102X( [3Xe[103X ) [32X operation[133X
  [6XReturns:[106X  [33X[0;10Y[9Xtrue[109X or [9Xfalse[109X.[133X
  
  [33X[0;0YGiven  an  element [9Xe[109X of a cohomology ring [22XH*(G,k)[122X, this operation determines
  whether or not [9Xe[109X is homogeneous, that is, whether [9Xe[109X is contained in [22XH^i(G,k)[122X
  for some [9Xi[109X.[133X
  
  [1X2.5-3 Degree[101X
  
  [33X[1;0Y[29X[2XDegree[102X( [3Xe[103X ) [32X method[133X
  [6XReturns:[106X  [33X[0;10Ythe degree of [9Xe[109X.[133X
  
  [33X[0;0YThis  function  returns the degree of the possibly non-homogeneous element [9Xe[109X
  of  a  cohomology ring [22XH*(G,k)[122X. Specifically, if [22XH*(G,k) = A_0 + A_1 + A_2 +
  ...[122X  where [22XA_i = H^i(G,k)[122X then this function returns the minimum [22Xn[122X such that
  [9Xe[109X is in [22XA_0 + A_1 + ... + A_n[122X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XA:=CohomologyRing(DihedralGroup(8),10);[127X[104X
    [4X[28X<algebra of dimension 66 over GF(2)>[128X[104X
    [4X[25Xgap>[125X [27Xb:=Basis(A);[127X[104X
    [4X[28XCanonicalBasis( <algebra of dimension 66 over GF(2)> )[128X[104X
    [4X[25Xgap>[125X [27Xx:=b[2]+b[4];[127X[104X
    [4X[28Xv.2+v.4[128X[104X
    [4X[25Xgap>[125X [27XIsHomogeneous(x);[127X[104X
    [4X[28Xfalse[128X[104X
    [4X[25Xgap>[125X [27XDegree(x);[127X[104X
    [4X[28X2 [128X[104X
  [4X[32X[104X
  
  [1X2.5-4 LocateGeneratorsInCohomologyRing[101X
  
  [33X[1;0Y[29X[2XLocateGeneratorsInCohomologyRing[102X( [3XC[103X ) [32X function[133X
  [6XReturns:[106X  [33X[0;10Ya list containing the cohomology generators.[133X
  
  [33X[0;0YHaving  already  called  [9XCohomologyRing[109X (see [14X2.5-1[114X), this function returns a
  list  of  elements  of  the cohomology ring which together with the identity
  element generate the cohomology ring.[133X
  
  [33X[0;0YThis  function  is a wrapper for [9XCohomologyGenerators[109X (see [14X2.3-1[114X). It points
  out  which  elements  of  the cohomology ring correspond with the generators
  found by [9XCohomologyGenerators[109X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XC:=CohomologyObject(SmallGroup(8,4));[127X[104X
    [4X[28X<object>[128X[104X
    [4X[25Xgap>[125X [27XA:=CohomologyRing(C,10);[127X[104X
    [4X[28X<algebra of dimension 17 over GF(2)>[128X[104X
    [4X[25Xgap>[125X [27XL:=LocateGeneratorsInCohomologyRing(C);[127X[104X
    [4X[28X[ v.2, v.3, v.7 ][128X[104X
    [4X[25Xgap>[125X [27XA=Subalgebra(A,Concatenation(L,[One(A)]));[127X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  
  [1X2.6 [33X[0;0YWhat Happens if [9Xn[109X[101X[1X Isn't Big Enough?[133X[101X
  
  [33X[0;0YSince   [22XP[122X   is   a   [13Xminimal[113X  projective  resolution,  we  have  [22XH^i(G,k)  =
  Hom_{kG}(P_i,k)[122X  where  [22XP_i  = (kG)^b_i[122X so that [22XH^i(G,k)[122X has a natural basis
  consisting  of the maps sending the element [22X1_G[122X of the [22Xj[122Xth direct summand of
  [22XP_i[122X  to [22X1_k[122X and all other direct summands to [22X0[122X, for [22Xj=1,2,...,b_i[122X, where [22Xb_i[122X
  is the [22XkG[122X-rank of [22XP_i[122X.[133X
  
  [33X[0;0YThe  command  [9XCohomologyRing(C,n)[109X  forms the vector space whose basis is the
  concatenation  of the natural bases of [22XH^i(G,k)[122X for [22Xi=1,2,...,n[122X and computes
  all  products  of basis elements [22Xx[122X and [22Xy[122X for which [22Xdeg x+deg y ≤ n[122X. Thinking
  of  [22XH*(G,k)[122X  in  terms  of  it's  multiplication  table, this means that the
  function computes the upper left-hand corner of the multiplication table. If
  [22Xdeg  x  + deg y > n[122X, the product [22Xxy[122X is taken to be zero. Therefore, the ring
  returned by [9XCohomologyRing[109X is [22XH*(G,k)/J[122X where [22XJ[122X is the ideal of all elements
  of degree [22X>n[122X.[133X
  
  [33X[0;0YThe  ring  determined  by  [9XCohomologyGenerators[109X  and  [9XCohomologyRelators[109X  is
  somewhat  different.  [9XCohomologyGenerators[109X  proceeds inductively, taking all
  natural  basis  elements of [22XH^1(G,k)[122X as generators, and for [22Xi=2... n[122X, taking
  all   natural   basis  elements  of  [22XH^i(G,k)[122X  which  are  [13Xnot[113X  products  of
  lower-degree  elements  as generators. Therefore, unless you know that there
  is  an  [22Xn[122X  for  which there exists a generating set of [22XH*(G,k)[122X consisting of
  elements  of degree [22Xn[122X or less, then you are [13Xnot[113X guaranteed that the elements
  returned  by  the  [9XCohomologyGenerators[109X  generate  [22XH*(G,k)[122X  as  a  ring. The
  knowledge of such an [22Xn[122X is the subject of section [14X2.4[114X.[133X
  
  [33X[0;0YSimilarly, [9XCohomologyRelators[109X proceeds inductively until degree [22Xn[122X, returning
  a  list  of  polynomials which generate the ideal of relators of degree [22Xn[122X or
  less. Again, you have to already know how big [22Xn[122X should be.[133X
  
  [33X[0;0YThe  result  of the preceding information is that there is a homomorphism [22Xk⟨
  x_1,x_2,...,  x_m  ⟩/ I -> H*(G,k)[122X, where [22Xk⟨ x_1,x_2,...,x_m ⟩[122X is the graded
  polynomial  ring  over  [22Xk[122X  in  the  non-commuting variables [22Xx_1,x_2,...,x_m[122X,
  having degrees the numbers in the list returned by [9XCohomologyGenerators[109X, and
  [22XI[122X  is  the ideal in [22Xk⟨ x_1,x_2,..., x_m ⟩[122X generated by the elements returned
  by [9XCohomologyRelators(C,n)[109X.[133X
  
  [33X[0;0YTherefore, if there is a generator of degree greater than [22Xn[122X, then [22Xf[122X won't be
  surjective.  Similarly, if there is a relator of degree greater than [22Xn[122X which
  is  not  a  consequence of lower degree relators, then [22Xf[122X won't be injective.
  See  section  [14X2.4[114X for a discussion on how big [22Xn[122X needs to be to ensure that [22Xf[122X
  will be an isomorphism.[133X
  
  
  [1X2.7 [33X[0;0YInduced Maps[133X[101X
  
  [33X[0;0YLet  [22Xf:  H  →  G[122X  be  a group homomorphism. Then [22Xf[122X induces a homomorphism on
  cohomology [22XH∗(G,k) → H∗(H,k)[122X which is returned by the following function.[133X
  
  [1X2.7-1 InducedHomomorphismOnCohomology[101X
  
  [33X[1;0Y[29X[2XInducedHomomorphismOnCohomology[102X( [3XC[103X, [3XD[103X, [3Xf[103X, [3Xn[103X ) [32X function[133X
  [6XReturns:[106X  [33X[0;10Ythe induced homomorphism on cohomology.[133X
  
  [33X[0;0YThis  function  returns the induced homomorphism [22XH∗(G,k) → H∗(H,k)[122X where the
  groups [22XH[122X and [22XG[122X are the components of the cohomology objects [9XC[109X and [9XD[109X and [22Xf: H
  →  G[122X  is  a  group  homomorphism.  If the cohomology rings have not yet been
  calculated,  they  will  be computed to degree [22Xn[122X, and in this case, they can
  then be accessed by calling [9XCohomologyRing[109X (see [14X2.5-1[114X).[133X
  
  [1X2.7-2 SubgroupInclusion[101X
  
  [33X[1;0Y[29X[2XSubgroupInclusion[102X( [3XH[103X, [3XG[103X ) [32X function[133X
  [6XReturns:[106X  [33X[0;10Ythe inclusion [22XH→ G[122X[133X
  
  [33X[0;0YThis function returns the group homomorphism [22XH→ G[122X when [22XH[122X is a subgroup of [22XG[122X.
  The    returned    map    can    be    used    as    the   [9Xf[109X   argument   of
  [9XInducedHomomorphismOnCohomology[109X,  in  which case the induced homomorphism is
  the restriction map [22XRes: H∗(G,k) → H∗(H,k)[122X.[133X
  
  [33X[0;0YThe  following  example calculates the homomorphism on cohomology induced by
  the  inclusion of the cyclic group of size 4 into the dihedral group of size
  8.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X[128X[104X
    [4X[25Xgap>[125X [27XG:=DihedralGroup(8);H:=Subgroup(G,[G.2]);[127X[104X
    [4X[28X<pc group of size 8 with 3 generators>[128X[104X
    [4X[28XGroup([ f2 ])[128X[104X
    [4X[25Xgap>[125X [27XC:=CohomologyObject(H);D:=CohomologyObject(G);[127X[104X
    [4X[28X<object>[128X[104X
    [4X[28X<object>[128X[104X
    [4X[25Xgap>[125X [27Xi:=SubgroupInclusion(H,G);[127X[104X
    [4X[28X[ f2 ] -> [ f2 ][128X[104X
    [4X[25Xgap>[125X [27XRes:=InducedHomomorphismOnCohomology(C,D,i,10);;[127X[104X
    [4X[25Xgap>[125X [27XA:=CohomologyRing(D,10);[127X[104X
    [4X[28X<algebra of dimension 66 over GF(2)>[128X[104X
    [4X[25Xgap>[125X [27XLocateGeneratorsInCohomologyRing(D);[127X[104X
    [4X[28X[ v.2, v.3, v.6 ][128X[104X
    [4X[25Xgap>[125X [27XA.1^Res; A.2^Res; A.3^Res; A.6^Res;[127X[104X
    [4X[28Xv.1[128X[104X
    [4X[28X0*v.1[128X[104X
    [4X[28Xv.2[128X[104X
    [4X[28Xv.3[128X[104X
    [4X[28X[128X[104X
  [4X[32X[104X
  
  
  [1X2.8 [33X[0;0YMassey Products[133X[101X
  
  [33X[0;0YSee [3] for the definitions and [1] for the details of the calculation using
  the Yoneda cocomplex. See also the file [9Xdoc/explanation.*[109X for an explanation
  of the implementation.[133X
  
  [1X2.8-1 MasseyProduct[101X
  
  [33X[1;0Y[29X[2XMasseyProduct[102X( [3Xx1[103X, [3Xx2[103X, [3X...[103X, [3Xxn[103X ) [32X function[133X
  [6XReturns:[106X  [33X[0;10Ythe Massey product [22X⟨ x1, x2, ... , xn⟩[122X.[133X
  
  [33X[0;0YGiven  elements [22Xx1, x2, ... , xn[122X of the ring returned by [9XCohomologyRing[109X (see
  [14X2.5[114X)  this  function computes the [22Xn[122X-fold Massey product [22X⟨ x1, x2, ... , xn ⟩[122X
  provided  that  the  lower-degree  Massey  products [22X⟨ xi, x{i+1}, ... , xj ⟩[122X
  vanish for all [22X1 ≤ i < j ≤ n[122X and returns [9Xfail[109X otherwise.[133X
  
  [33X[0;0YAs an example, recall that the cohomology rings of the cyclic groups [22XC_3[122X and
  [22XC_9[122X  of sizes 3 and 9 over [22Xk=GF(3)[122X are both given by [22Xk⟨ z,y ⟩/(z^2)[122X, so they
  are  isomorphic  as rings. However, the following example shows that [22X⟨ z, z,
  z ⟩[122X is non-zero in [22XH*(C_3,k)[122X but is zero in [22XH*(C_9,k)[122X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X[128X[104X
    [4X[25Xgap>[125X [27XA:=CohomologyRing(CyclicGroup(3),10);[127X[104X
    [4X[28X<algebra of dimension 11 over GF(3)>[128X[104X
    [4X[25Xgap>[125X [27Xz:=Basis(A)[2];[127X[104X
    [4X[28Xv.2[128X[104X
    [4X[25Xgap>[125X [27XMasseyProduct(z,z);[127X[104X
    [4X[28X0*v.1[128X[104X
    [4X[25Xgap>[125X [27XMasseyProduct(z,z,z);[127X[104X
    [4X[28Xv.3[128X[104X
    [4X[25Xgap>[125X [27XA:=CohomologyRing(CyclicGroup(9),10);[127X[104X
    [4X[28X<algebra of dimension 11 over GF(3)>[128X[104X
    [4X[25Xgap>[125X [27Xz:=Basis(A)[2];[127X[104X
    [4X[28Xv.2[128X[104X
    [4X[25Xgap>[125X [27XMasseyProduct(z,z);[127X[104X
    [4X[28X0*v.1[128X[104X
    [4X[25Xgap>[125X [27XMasseyProduct(z,z,z);[127X[104X
    [4X[28X0*v.1[128X[104X
    [4X[25Xgap>[125X [27XMasseyProduct(z,z,z,z,z,z,z,z,z);[127X[104X
    [4X[28Xv.3[128X[104X
    [4X[28X[128X[104X
  [4X[32X[104X
  
