<?xml version="2.0" encoding="ISO-8859-1"?>
<!DOCTYPE Book SYSTEM "gapdoc.dtd">
<Book Name="crime">

<TitlePage>
<Title>The <Package>Crime</Package> Package</Title>
<Version>Version 1.1</Version>
<Author>Marcus Bishop
  <Email>marcus.bishop@gmail.com</Email>
</Author>
<Copyright> &copyright; 2006 Marcus Bishop <P/>
    We adopt the copyright regulations of &GAP; as detailed in the
    copyright notice in the &GAP; manual. </Copyright>
<Acknowledgements>
This project would not have been possible without Jon Carlson.
Jon devised the algorithms used by <K>ProjectiveResolution</K>,
<K>CohomologyGenerators</K>, and <K>CohomologyRelators</K>,
having already implemented them in <Package>Magma</Package>
and sharing these programs with me.
</Acknowledgements>

</TitlePage>

<TableOfContents/>
<Body>
<Chapter> <Heading>Installation and Loading</Heading>
Like other &GAP; packages, you download and unpack 
this package into &GAP;'s <K>pkg</K> directory. 
For example, if you were using some Unix derivative 
and &GAP; were installed in the directory 
<K>/usr/local/gap4r4</K>, then you would
do the following.
<Example>
<![CDATA[
$ cd /usr/local/gap4r4/pkg
$ su
% wget 'http://math.uic.edu/~marcus/Crime/crime-1.1.tar.gz'
% tar xvzvf crime-1.1.tar.gz 
]]>
</Example>
In this situation, users would then load the package
with the <K>LoadPackage</K> command.
<Example>
<![CDATA[
$ gap
gap> LoadPackage("crime");
]]>
</Example>

Users not having root access, using
someone else's computer, or having bad
relationships with their network administrators,
could install the package into their home 
directories or into some other writable
directory such as <K>/tmp</K> as follows.
<Example>
<![CDATA[
$ mkdir /tmp/pkg
$ cd /tmp/pkg
$ wget 'http://math.uic.edu/~marcus/Crime/crime-1.1.tar.gz'
$ tar xvzvf crime-1.1.tar.gz 
$ gap -l ';/tmp'
gap> LoadPackage("crime");
]]></Example>

Finally, it would be a good idea to run the test file
to confirm that all the functions work.
<Example>
<![CDATA[
gap> ReadPackage("crime","tst/test.g");
]]></Example>
You can count yourself lucky if &GAP; doesn't complain
about anything. There is also a longer running test
file for those having ample free time
described in Chapter <Ref Chap="test"/>.

</Chapter>

<Chapter> <Heading>Usage</Heading>

All the functions described below taking an argument <K>n</K>
except <K>CohomologyRing</K>, <K>CohomologyRelators</K>
and <K>InducedHomomorphismOnCohomology</K> do whatever the 
manual says they do until some stage <K>n</K>, where
<K>n</K> is normally the homological degree.
These functions are idempotent in the sense that
called a second time with the same argument <K>n</K>, they
do nothing, but called with a bigger <K>n</K>,
they continue computing from where the previous
calculations left off.

<Section> <Heading>Cohomology Objects</Heading>

The 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 <K>CObject</K>, which is created with the 
following command.

<ManSection>
<Oper Name="CohomologyObject" Arg="G,M" 
Comm="Makes cohomology object"/>
<Oper Name="CohomologyObject" Arg="G"
Comm="Makes cohomology object"/>
<Returns>a cohomology object.</Returns>
<Description>
This function creates a cohomology object having components
the <M>p</M>-group <M>G</M>
and the &MeatAxe; <M>kG</M>-module <M>M</M>.

The second invocation creates a cohomology 
object having components
the <M>p</M>-group <M>G</M> and
the trivial &MeatAxe; <M>kG</M>-module
where <M>k</M> is the field 
<Alt Only="LaTeX"><M>\mathbb{F}_p</M>.</Alt>
<Alt Not="LaTeX"><M>GF(p)</M>.</Alt>
</Description></ManSection>

<P/>We emphasize that in the first invocation,
<K>M</K> can be any &MeatAxe; module
over <M>kG</M> where
<M>k</M> is any field of characteristic
<M>p</M>.
But since the case
<Alt Only="LaTeX"><M>k=\mathbb{F}_p</M>,</Alt>
<Alt Not="LaTeX"><M>k=GF(p)</M>,</Alt> and
<M>M=k</M> is probably the most common, the
second invocation is provided for convenience.
At the present, <K>ProjectiveResolution</K>
works when <K>M</K> is an arbitrary &MeatAxe; module, 
but all the functions dealing with the ring-structure of 
<Alt Only="LaTeX"><M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX"><M>H*(G,k)</M></Alt>
require that <K>M</K> be the trivial module.

<P/>The cohomology object is used to store, in addition
to the items mentioned above,
the boundary maps, the Betti numbers, the multiplication
table, etc.
</Section>

<Section><Heading>Minimal Projective Resolutions</Heading>

Given a <M>p</M>-group <M>G</M>, a field
<M>k</M> of characteristic <M>p</M> and
a <M>kG</M>-module <M>M</M>,
the function below computes the first few 
terms of the minimal projective resolution
of <M>M</M>
<Alt Only="LaTeX">
<Display> P_n\rightarrow\cdots\rightarrow P_2\rightarrow P_1
\rightarrow P_0\rightarrow M\rightarrow 0 </Display>
where <M>P_i=\left(kG\right)^{\oplus b_i}</M> 
</Alt>
<Alt Not="LaTeX">
<Display> P_n -> ... P_2 -> P_1 -> P_0 -> M -> 0</Display>
where <M>P_i</M> is the direct sum <M>(kG)^(b_i)</M> 
</Alt>
for certain numbers <M>b_i</M>, 
the <E>Betti numbers</E> of the resolution.
The minimal <M>kG</M>-projective resolution of <M>M</M>
is unique up to chain isomorphism.
Then the groups 
<Alt Only="LaTeX">
<M>\mathrm{Ext}^n_{kG}\left(M,N\right)</M></Alt>
<Alt Not="LaTeX"><M>Ext^n(M,N)</M></Alt>
are simply 
<Alt Only="LaTeX">
<M>\mathrm{Hom}_{kG}\left(P_n,N\right)</M>,</Alt>
<Alt Not="LaTeX"><M>Hom(P_n,N)</M>,</Alt>
and if <M>M=N=k</M> is the trivial <M>kG</M>-module, then
<Alt Only="LaTeX">
<M>H^n\left(G,k\right)=\mathrm{Ext}^n_{kG}
\left(k,k\right)=k^{b_n}</M>.</Alt>
<Alt Not="LaTeX">
<M>H^n(G,k)=Ext^n(k,k)=k^(b_n)</M>.</Alt>

<ManSection><Oper Name="ProjectiveResolution" Arg="C,n"
Comm="Computes a minimal projective resolution"/>
<Returns>a list containing the Betti numbers 
<M>b_0, b_1,\ldots, b_n</M>.</Returns>

<Description>
Given a cohomology object <K>C</K> having
components <M>G</M>, <M>k</M>, and <M>M</M>,
this function computes the first <K>n</K><M>+1</M> terms 
of the minimal projective resolution <M>P_\ast</M>
of <M>M</M> of the form
<Alt Only="LaTeX">
<M>P_i=\left(kG\right)^{\oplus b_i}</M> 
for <M>0\leq i\leq n</M>,</Alt>
<Alt Not="LaTeX">
<M>P_i=(kG)^(b_i)</M>
for <M>i=0,1,...,n</M>,</Alt> 
and returns the numbers <M>b_i</M> as a list.
</Description></ManSection>

<ManSection><Oper Name="BoundaryMap" Arg="C,n"
Comm="Returns the nth boundary map"/>
<Returns>the <K>n</K>th boundary map.</Returns>
<Description>
Given the cohomology object <K>C</K>, this function
computes a projective resolution to degree <K>n</K> 
if it hasn't been computed already,
and returns the <K>n</K>th boundary map.

<P/>The map returned is a
<Alt Only="LaTeX">
<M>b_n\times\left(b_{n-1}\left|G\right|\right)</M></Alt>
<Alt Not="LaTeX">
<M>b_n x \left(b_\left(n-1\right)\left|G\right|\right)</M></Alt>
matrix, having in the <M>i</M>th row the image of the element
<M>1_G</M> from the <M>i</M>th direct summand of
<M>P_n</M>.

<P/>See the file <K>doc/example.*</K> for an example
of the usage and interpretation of the result of
this function.
</Description></ManSection>

</Section>

<Section><Heading>Cohomology Generators and Relators</Heading>

<ManSection><Oper Name="CohomologyGenerators" Arg="C,n"
Comm="Calculates generators of the cohomology ring"/>
<Returns>a list containing the degrees of 
the generators of the cohomology ring.</Returns>
<Description>
Given a cohomology object <K>C</K> having components <M>G</M>,
<M>k</M>, and <M>M</M>, this function computes the generators of 
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M> 
</Alt>
of degree less than or equal to <K>n</K>, and stores them in <K>C</K>.
The function returns a list of the degrees of these generators.
</Description></ManSection>

The actual cohomology generators are represented by
maps <M>P_n \rightarrow k</M> and are stored in <K>C</K>
as matrices. Only their degrees are returned.

<ManSection><Oper Name="CohomologyRelators" Arg="C,n"
Comm="Calculates the relators of the cohomology ring"/>
<Returns>a list of generators and a list of relators.</Returns>
<Description>
Given a cohomology object <K>C</K> having components <M>G</M>,
<M>k</M>, and <M>M</M>, this function computes a set of
generators of the ideal of relators in 
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right),</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k),</M> 
</Alt>
all having multidegree less than or equal to <M>n</M>.
Read on for what this means exactly.

<P/>The function returns two lists, the first list containing
the variables <K>z</K>, <K>y</K>, <K>x</K>, <M>\ldots</M>
corresponding to the generators of
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M></Alt>
<Alt Not="LaTeX">
<M>H*(G,k)</M></Alt>
if there are fewer than 12 generators and containing the 
variables <K>x&uscore;1</K>, <K>x&uscore;2</K>,  <K>x&uscore;3</K>,
<M>\ldots</M>
otherwise. The second list is a list of polynomials
in the variables from the first list.

<P/>These two lists should be interpreted as follows. 
A degree-<K>n</K> approximation of the cohomology ring
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M> </Alt>
is given by the polynomial ring over <M>k</M> in the 
non-commuting variables from the first list,
(having degrees given by the list returned by
 <K>CohomologyGenerators</K> above) 
and subject to the relators in the second list. 
See <Ref Sect="whathappens"/> for more details still.
</Description></ManSection>

For example, the following commands 
<Example>
<![CDATA[
gap> C:=CohomologyObject(DihedralGroup(8));
<object>
gap> CohomologyGenerators(C,10);
[ 1, 1, 2 ]
gap> CohomologyRelators(C,10);
[ [ z, y, x ], [ z*y+y^2 ] ]
]]>
</Example>
tell us that for <M>G=D_8</M>, the cohomology ring
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M> 
</Alt>
is the graded-commutative polynomial ring in the variables
<M>z</M>, <M>y</M>, and <M>x</M> of degrees 1, 1, and 2,
subject to the relation
<M>zy+y^2</M>. But since
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M> 
</Alt>
<E>is</E> commutative, <M>k</M> being of
characteristic 2, we have
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)=k\left[z,y,x\right]
\left/\left(zy+y^2\right)\right.</M>.
</Alt><Alt Not="LaTeX">
<M>H*(G,k)=k[z,y,x]/(zy+y^2)</M>.
</Alt>
This result can be further improved by
taking <M>z=z+y</M>, giving
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)=k\left[z,y,x\right]
\left/\left(zy\right)\right.</M>.
</Alt><Alt Not="LaTeX">
<M>H*(G,k)=k[z,y,x]/(zy)</M>.
</Alt>

<P/>Observe that in this case, we knew in advance
that there was a set of generators for
<Alt Only="LaTeX"><M>H^\ast\left(G,k\right)</M></Alt>
<Alt Not="LaTeX"><M>H*(G,k)</M></Alt> 
all having degree less than 10, and that there was
a set of generators of the ideal of relators
all having multidegree less than 10. See
see <Ref Sect="whathappens"/> for details.

<P/>While this isn't likely to occur, we point
out that if there are 12 or more generators 
and some of the indeterminates
<K>x&uscore;1</K>, <K>x&uscore;2</K>,  <K>x&uscore;3</K>,
<M>\ldots</M> have already been named, say by a previous
call to <K>CohomologyRelators</K>, then these variables
will retain their old names. If this is confusing,
restart &GAP; and do it again.
</Section>

<Section Label="completion"><Heading>Tests for Completion</Heading>
A test or series of tests for completion
of the calculation will hopefully
be implemented soon.
See <Cite Key="carlson"/> for the details.
</Section>

<Section Label="ring"><Heading>Cohomology Rings</Heading>
See <Cite Key="carlson"/> for the details of the calculation
of cohomology products using composition of chain maps.
See also the file <K>doc/explanation.*</K>
for an explanation of the implementation.

<ManSection>
<Oper Name="CohomologyRing" Arg="C,n"
Comm="Calculates the cohomology ring"/>
<Oper Name="CohomologyRing" Arg="G,n"
Comm="Calculates the cohomology ring"/>
<Returns>the cohomology ring of <M>G</M>.</Returns>
<Description>
Given a cohomology object <K>C</K> 
having module component the trivial <M>kG</M>-module 
and possibly having a projective resolution
already computed, this function returns 
the degree-<K>n</K> truncation of the cohomology ring 
<Alt Only="LaTeX"><M>H^\ast\left(G,k\right).</M></Alt>
<Alt Not="LaTeX"><M>H*(G,k)</M>.</Alt> 
See <Ref Sect="whathappens"/> for what this
means exactly.

The object returned is a structure constant algebra.

<P/>Users interested only in working with
the cohomology ring of a group as a &GAP;
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 <K>G</K>
immediately, throwing away all intermediate calculations.

<P/>Observe that the object returned is a degree
<K>n</K> truncation of the infinite-dimensional
cohomology ring. A consequence of this is that
multiplying two elements whose product
has degree greater than <K>n</K> results in zero,
whether or not the product is really zero.

<P/>Observe also that calling <K>CohomologyRing</K> 
a second time with a bigger <K>n</K> does 
<E>not</E> 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.
</Description></ManSection>

<ManSection>
<Oper Name="IsHomogeneous" Arg="e"
Comm="Determines whether e is homogeneous"/>
<Returns><K>true</K> or <K>false</K>.</Returns>
<Description>
Given an element <K>e</K> of some cohomology
ring <M>A</M>, this operation determines 
whether or not <K>e</K> is homogeneous, 
that is, whether or not <K>e</K>
is contained in some <K>hom&uscore;component</K> of <M>A</M>.
</Description></ManSection>

<ManSection>
<Meth Name="Degree" Arg="e"
Comm="Determines the degree of e"/>
<Returns>the degree of <K>e</K>.</Returns>
<Description>
This function is intended to return the degree of the 
possibly non-homogeneous element <K>e</K> of some 
cohomology ring <M>A</M>,
but in principle, works for any element
of any graded <K>SCAlgebra</K>.
Specifically, if 
<Alt Only="LaTeX">
<M>A=A_0\oplus A_1\oplus A_2\oplus\cdots</M>
</Alt><Alt Not="LaTeX">
<M>A = A_0 + A_1 + A_2 + \ldots</M>
</Alt>
where <M>A_i</M> are the <K>hom&uscore;components</K>
of <M>A</M>, then this function returns the
minimum <M>n</M> such that <K>e</K> is in
<Alt Only="LaTeX">
<M>A_0\oplus A_1\oplus\cdots\oplus A_n</M>.
</Alt><Alt Not="LaTeX">
<M>A_0 + A_1 + \ldots + A_n</M>.
</Alt>
</Description></ManSection>

<Example><![CDATA[
gap> A:=CohomologyRing(DihedralGroup(8),10);
<algebra of dimension 66 over GF(2)>
gap> b:=Basis(A);
CanonicalBasis( <algebra of dimension 66 over GF(2)> )
gap> x:=b[2]+b[4];
v.2+v.4
gap> IsHomogeneous(x);
false
gap> Degree(x);
2 
]]></Example>

<ManSection>
<Func Name="LocateGeneratorsInCohomologyRing" Arg="C"
Comm="Locates the cohomology generators"/>
<Returns>a list containing the cohomology generators.</Returns>
<Description>
Having already called <K>CohomologyRing</K> 
(see <Ref Subsect="CohomologyRing"/>),
this function returns a list of elements of
the cohomology ring which together with the
identity element generate the cohomology ring.

<P/>This function is a wrapper for <K>CohomologyGenerators</K>
(see <Ref Subsect="CohomologyGenerators"/>),
indicating which elements of the cohomology
ring correspond with the generators found
by <K>CohomologyGenerators</K>.
</Description>
</ManSection>

<Example><![CDATA[
gap> C:=CohomologyObject(SmallGroup(8,4));
<object>
gap> A:=CohomologyRing(C,10);
<algebra of dimension 17 over GF(2)>
gap> L:=LocateGeneratorsInCohomologyRing(C);
[ v.2, v.3, v.7 ]
gap> A=Subalgebra(A,Concatenation(L,[One(A)]));
true
]]></Example>
</Section>

<Section Label="whathappens">
<Heading>What Happens if <K>n</K> Isn't
Big Enough?</Heading>
Since <M>P_\ast</M> is a <E>minimal</E> resolution,
the cohomology group
<M>H^i\left(G,k\right)</M> is the dual
of <M>P_n</M>, so that <M>H^i\left(G,k\right)</M>
has a natural basis consisting of the maps
sending the element <M>1_G</M> of the <M>j</M>th
direct summand of <M>P_i</M> to <M>1_k</M>
and all other direct summands to <M>0_k</M> for 
<Alt Only="LaTeX">
<M>1\le j\le b_i</M>.</Alt>
<Alt Not="LaTeX">
<M>j=1,2,\ldots,b_i</M>.</Alt>

<P/>The command <K>CohomologyRing(C,n)</K> concatenates
these bases for 
<Alt Only="LaTeX">
<M>1\le i\le n</M></Alt>
<Alt Not="LaTeX">
<M>i=1,2,\ldots,n</M></Alt>
and computes all products of basis elements <M>x</M> and <M>y</M>
for which <M>\deg x+\deg y \leq n</M>.
Thinking of 
<Alt Only="LaTeX"><M>H^\ast\left(G,k\right)</M></Alt>
<Alt Not="LaTeX"><M>H*(G,k)</M></Alt> 
in terms of it's multiplication table, then this means that
the function computes the upper left-hand corner
of the multiplication table.
If <M>\deg x + \deg y > n</M>
then the product <M>xy</M> is taken to be zero.
Therefore, the ring returned by <K>CohomologyGenerators</K> is
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)\left/J_{&tgt;n}\right.</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)/J</M></Alt>
where <Alt Only="LaTeX"><M>J_{>n}</M></Alt>
<Alt Not="LaTeX"><M>J</M></Alt>
is the ideal of all elements of degree <M>>n</M>.

<P/>The ring determined by <K>CohomologyGenerators</K>
and <K>CohomologyRelators</K> is somewhat different.
<K>CohomologyGenerators</K> proceeds inductively,
taking all standard basis elements of 
<M>H^1\left(G,k\right)</M> as generators, and for
<Alt Only="LaTeX">
<M>1&tlt;i\le n</M>,</Alt> 
<Alt Not="LaTeX">
<M>i=2\ldots n</M>,</Alt> 
taking all standard basis elements
of <M>H^i\left(G,k\right)</M> which are <E>not</E>
products of lower-degree elements as generators.
Therefore, unless you have some reason to believe
that there exists a generating set for 
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M></Alt> 
consisting of elements of degree <M>\leq n</M>,
then you are <E>not</E> guaranteed
that the elements returned by the
<K>CohomologyGenerators</K> generate
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>H*(G,k)</M></Alt> 
as a ring.

<P/>Similarly, <K>CohomologyRelators</K> proceeds inductively
until degree <M>n</M>, returning a list of polynomials 
of multidegree <M>\leq n</M>.

<P/>The impact of the preceeding information is
that there is a homomorphism
<Alt Only="LaTeX">
<M>f:k\left.\left\langle x_1,x_2,\dots x_m \right\rangle\right./I
\to H^\ast\left(G,k\right)</M> 
</Alt><Alt Not="LaTeX">
<M>k\left\langle x_1,x_2,\ldots, x_m \right\rangle/ I \to H*(G,k)</M></Alt>
where <M>x_1,x_2,\ldots,x_m</M> represent 
the elements returned by <K>CohomologyGenerators(C,n)</K>,
<M>k\left\langle x_1,x_2,\ldots x_m \right\rangle</M>
is the polynomial ring over <M>k</M> in 
the non-commuting variables <M>x_1,x_2,\ldots,x_m</M>,
and <M>I</M> is the ideal in
<M>k\left\langle x_1,x_2,\ldots, x_m \right\rangle</M>
generated by the elements returned by
<K>CohomologyRelators(C,n)</K>.

<P/>Therefore, if there is a 
generator of degree <M>>n</M>,
then <M>f</M> won't be surjective.
If there is a relator of multidegree
<M>>n</M> which is not a consequence
of lower degree relators, then <M>f</M>
won't be injective.

See <Ref Sect="completion"/> for how
big <M>n</M> needs to be to ensure that
<M>f</M> be an isomorphism.

</Section>

<Section><Heading>Induced Maps</Heading>
Let <M>f: H \rightarrow G</M> be a group homomorphism.
Then <M>f</M> induces a homomorphism on cohomology 
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)
\to H^\ast\left(H,k\right)</M>
</Alt><Alt Not="LaTeX">
<M>H\ast(G,k) \rightarrow H\ast(H,k)</M></Alt>
which is returned by the following function.

<ManSection>
<Func Name="InducedHomomorphismOnCohomology" Arg="C,D,f,n"
Comm="Computes the induced homomorphism on cohomology"/>
<Returns>the induced homomorphism on cohomology rings.</Returns>
<Description>
This function returns the induced homomorphism on cohomology
<Alt Only="LaTeX">
<M>H^\ast\left(G,k\right)
\to H^\ast\left(H,k\right)</M>
</Alt><Alt Not="LaTeX">
<M>H\ast(G,k) \rightarrow H\ast(H,k)</M></Alt>
where the groups <M>H</M> and <M>G</M> are the components
of the cohomology objects <K>C</K> and <K>D</K>
and <M>f: H \rightarrow G</M> is a group homomorphism.
If the cohomology rings have not yet been
calculated, they will be computed to degree <M>n</M>,
and in this case, they can then be accessed 
by calling <K>CohomologyRing</K> (see <Ref Subsect="CohomologyRing"/>). 
</Description></ManSection>

<ManSection>
<Func Name="Inclusion" Arg="H,G" Comm="Returns the inclusion"/>
<Returns>the inclusion <M>H\rightarrow G</M></Returns>
<Description>This function returns the group homomorphism
<M>H\rightarrow G</M> when <M>H</M> is a subgroup
of <M>G</M>. The returned map can be used as the
<K>f</K> argument of <K>InducedHomomorphismOnCohomology</K>,
in which case the induced homomorphism is the
restriction map
<Alt Only="LaTeX">
<M>\mathrm{Res}^G_H:H^\ast\left(G,k\right)
\to H^\ast\left(H,k\right)</M>.
</Alt><Alt Not="LaTeX">
<M>Res: H\ast(G,k) \rightarrow H\ast(H,k)</M>.</Alt>
</Description></ManSection>

The 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.

<Example>
<![CDATA[
gap> G:=DihedralGroup(8);H:=Subgroup(G,[G.2]);
<pc group of size 8 with 3 generators>
Group([ f2 ])
gap> C:=CohomologyObject(H);D:=CohomologyObject(G);
<object>
<object>
gap> i:=Inclusion(H,G);
[ f2 ] -> [ f2 ]
gap> Res:=InducedHomomorphismOnCohomology(C,D,i,10);;
gap> A:=CohomologyRing(D,10);
<algebra of dimension 66 over GF(2)>
gap> LocateGeneratorsInCohomologyRing(D);
[ v.2, v.3, v.6 ]
gap> A.1^Res; A.2^Res; A.3^Res; A.6^Res;
v.1
0*v.1
v.2
v.3
]]>
</Example>

</Section>
<Section><Heading>Massey Products</Heading>
See <Cite Key="kraines"/> for the definitions
and <Cite Key="borge"/> for the details of the
calculation using the Yoneda cocomplex.
See also the file <K>doc/explanation.*</K>
for an explanation of the implementation.
<ManSection>
<Func Name="MasseyProduct" Arg="x1, x2, ... , xn"
Comm="Computes the Massey product &tlt;L&tgt;"/>
<Returns>the Massey product 
<Alt Only="LaTeX"> <M>\left\langle
x_1,x_2,\dots,x_n\right\rangle</M>.</Alt>
<Alt Not="LaTeX"> <M>\left\langle x1, x2, ... , xn\right\rangle</M>.</Alt>
</Returns>
<Description> Given elements
<Alt Only="LaTeX"> <M>x_1,x_2,\dots,x_n</M></Alt>
<Alt Not="LaTeX"> <M>x1, x2, \ldots , xn</M></Alt>
of a cohomology ring returned by
<K>CohomologyRing</K> (see <Ref Sect="ring"/>), 
this function computes the <M>n</M>-fold Massey product
<Alt Only="LaTeX">
<M>\left\langle x_1,x_2,\ldots,x_n\right\rangle</M></Alt>
<Alt Not="LaTeX">
<M>\left\langle&nbsp;x1, x2, \ldots , xn&nbsp;\right\rangle</M></Alt>
provided that the lower-degree Massey products
<M>\left\langle&nbsp;x_i ,x_{{i+1}}, \ldots , x_j&nbsp;\right\rangle</M> vanish
for all <M>1 \leq i &lt; j \leq n</M>, and returns <K>fail</K> otherwise.
</Description>
</ManSection>

As an example, recall that the cohomology rings of the cyclic
groups <M>C_3</M> and <M>C_9</M> of size 3 and 9 over
<Alt Only="LaTeX"><M>k=\mathbb{F}_3</M></Alt>
<Alt Not="LaTeX"><M>k=GF(3)</M></Alt> 
are both given by
<Alt Only="LaTeX">
<M>k\left\langle z, y\right\rangle\left/\left(z^2\right)\right.</M>,
</Alt><Alt Not="LaTeX">
<M>k\left\langle&nbsp;z,y&nbsp;\right\rangle/\left(z^2\right)</M>,</Alt>
that is, they are isomorphic as rings. However, the following
example shows that
<M>\left\langle&nbsp;z, z, z&nbsp;\right\rangle</M>
is non-zero in 
<Alt Only="LaTeX"><M>H^\ast\left(C_3,k\right)</M></Alt>
<Alt Not="LaTeX"><M>H*(C_3,k)</M></Alt> 
but is zero in
<Alt Only="LaTeX"><M>H^\ast\left(C_9,k\right)</M>.</Alt>
<Alt Not="LaTeX"><M>H*(C_9,k)</M>.</Alt>
<Example>
<![CDATA[
gap> A:=CohomologyRing(CyclicGroup(3),10);
<algebra of dimension 11 over GF(3)>
gap> z:=Basis(A)[2];
v.2
gap> MasseyProduct(z,z);
0*v.1
gap> MasseyProduct(z,z,z);
v.3
gap> A:=CohomologyRing(CyclicGroup(9),10);
<algebra of dimension 11 over GF(3)>
gap> z:=Basis(A)[2];
v.2
gap> MasseyProduct(z,z);
0*v.1
gap> MasseyProduct(z,z,z);
0*v.1
gap> MasseyProduct(z,z,z,z,z,z,z,z,z);
v.3
]]>
</Example>
</Section>
</Chapter>


<Chapter Label="test"><Heading>Leisure and Recreation: Cohomology Rings
of all Groups of Size 16</Heading>
Below is the output of the test file 
<K>tst/batch.g</K>. The file runs through
all groups of size <M>n</M>, which
is initially set to <M>16</M>, and runs
<K>ProjectiveResolution</K>, <K>CohomologyGenerators</K>
and <K>CohomologyRelators</K> for each group, 
and prints the results as well as 
the timings for each operation to a file. The output
below was computed on a 3.06 GHz Intel processor
with 3.71 GB of RAM. The projective resolutions are calculated
initially to degree <M>10</M> and the generators and
relators to degree <M>6</M>, due to the fact that
I already knew all the generators and relators
to be of degree less than 6, see
<URL>http://www.math.uga.edu/~lvalero/cohointro.html</URL>.
See also the file <K>tst/README</K> for suggestions
on dealing with other users when running long-running batch processes.
<Example>
<![CDATA[
SmallGroup(16,1)
Betti Numbers: [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
Time:  0:00:05.864
Generators in degrees: [ 1, 2 ]
Time:  0:00:00.086
Relators: [ [ z, y ], [ z^2 ] ]
Time:  0:00:00.245

SmallGroup(16,2)
Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
Time:  0:00:00.931
Generators in degrees: [ 1, 1, 2, 2 ]
Time:  0:00:02.874
Relators: [ [ z, y, x, w ], [ z^2, y^2 ] ]
Time:  0:00:12.227

SmallGroup(16,3)
Betti Numbers: [ 1, 2, 4, 6, 9, 12, 16, 20, 25, 30, 36 ]
Time:  0:00:05.292
Generators in degrees: [ 1, 1, 2, 2, 2 ]
Time:  0:00:21.770
Relators: [ [ z, y, x, w, v ], [ z^2, z*y, z*x, y^2*v+x^2 ] ]
Time:  0:01:26.166

SmallGroup(16,4)
Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
Time:  0:00:01.047
Generators in degrees: [ 1, 1, 2, 2 ]
Time:  0:00:03.253
Relators: [ [ z, y, x, w ], [ z^2, z*y+y^2, y^3 ] ]
Time:  0:00:14.294

SmallGroup(16,5)
Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
Time:  0:00:01.065
Generators in degrees: [ 1, 1, 2 ]
Time:  0:00:02.493
Relators: [ [ z, y, x ], [ z^2 ] ]
Time:  0:00:13.573

SmallGroup(16,6)
Betti Numbers: [ 1, 2, 2, 2, 3, 4, 4, 4, 5, 6, 6 ]
Time:  0:00:00.446
Generators in degrees: [ 1, 1, 3, 4 ]
Time:  0:00:01.566
Relators: [ [ z, y, x, w ], [ z^2, z*y^2, z*x, x^2 ] ]
Time:  0:00:04.132

SmallGroup(16,7)
Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
Time:  0:00:01.076
Generators in degrees: [ 1, 1, 2 ]
Time:  0:00:02.495
Relators: [ [ z, y, x ], [ z*y ] ]
Time:  0:00:13.862

SmallGroup(16,8)
Betti Numbers: [ 1, 2, 2, 2, 3, 4, 4, 4, 5, 6, 6 ]
Time:  0:00:00.465
Generators in degrees: [ 1, 1, 3, 4 ]
Time:  0:00:01.570
Relators: [ [ z, y, x, w ], [ z*y, z^3, z*x, y^2*w+x^2 ] ]
Time:  0:00:04.350

SmallGroup(16,9)
Betti Numbers: [ 1, 2, 2, 1, 1, 2, 2, 1, 1, 2, 2 ]
Time:  0:00:00.140
Generators in degrees: [ 1, 1, 4 ]
Time:  0:00:00.255
Relators: [ [ z, y, x ], [ z*y, z^3+y^3, y^4 ] ]
Time:  0:00:00.718

SmallGroup(16,10)
Betti Numbers: [ 1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66 ]
Time:  0:00:20.139
Generators in degrees: [ 1, 1, 1, 2 ]
Time:  0:01:04.158
Relators: [ [ z, y, x, w ], [ z^2 ] ]
Time:  0:06:27.688

SmallGroup(16,11)
Betti Numbers: [ 1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66 ]
Time:  0:00:20.428
Generators in degrees: [ 1, 1, 1, 2 ]
Time:  0:01:04.678
Relators: [ [ z, y, x, w ], [ z*y ] ]
Time:  0:06:33.808

SmallGroup(16,12)
Betti Numbers: [ 1, 3, 5, 6, 7, 9, 11, 12, 13, 15, 17 ]
Time:  0:00:02.438
Generators in degrees: [ 1, 1, 1, 4 ]
Time:  0:00:08.927
Relators: [ [ z, y, x, w ], [ z^2+z*y+y^2, y^3 ] ]
Time:  0:00:44.464

SmallGroup(16,13)
Betti Numbers: [ 1, 3, 5, 6, 7, 9, 11, 12, 13, 15, 17 ]
Time:  0:00:02.389
Generators in degrees: [ 1, 1, 1, 4 ]
Time:  0:00:09.247
Relators: [ [ z, y, x, w ], [ z*y+x^2, z*x^2+y*x^2, y^2*x^2+x^4 ] ]
Time:  0:00:44.323

SmallGroup(16,14)
Betti Numbers: [ 1, 4, 10, 20, 35, 56, 84, 120, 165, 220, 286 ]
Time:  0:07:00.973
Generators in degrees: [ 1, 1, 1, 1 ]
Time:  0:15:40.874
Relators: [ [ z, y, x, w ], [  ] ]
Time:  1:54:28.052

Total time:  2:38:14.841
]]>
</Example>
</Chapter>
</Body>
<Bibliography Databases="crime" Style="plain"/>
<TheIndex/>
</Book>
