% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

\newcommand{\GAP}{\textsf{GAP}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{The \textsf{Crime} Package\mbox{}}}\\[1cm]
\hypersetup{pdftitle=The \textsf{Crime} Package}
\markright{\scriptsize \mbox{}\hfill The \textsf{Crime} Package \hfill\mbox{}}
{Version 1.3\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Marcus Bishop  \mbox{}}}\\
\hypersetup{pdfauthor=Marcus Bishop  }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Marcus Bishop  } --- Email: \href{mailto://marcus.bishop@gmail.com} {\texttt{marcus.bishop@gmail.com}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2006, 2007 Marcus Bishop 

 Crime is free software which is distributed under the GNU Public Licence,
version 2, and may be redistributed under the GNU Public Licence, version 2 or
later (at your preference). See the file COPYING for detailed information \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 2 ]}
 This project would not have been possible without Jon Carlson. Jon devised the
algorithms used by \texttt{ProjectiveResolution}, \texttt{CohomologyGenerators}, and \texttt{CohomologyRelators}, having already implemented them in \textsf{Magma}, and shared these programs with me. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 3 ]}}

\tableofcontents
\newpage

 
\chapter{\textcolor{Chapter }{Installation and Loading}}\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X86C437C47F3988E8}{}
{
 Like other \textsf{GAP} packages, you download and unpack this package into \textsf{GAP}'s \texttt{pkg} directory. For example, if you were using some Unix derivative and \textsf{GAP} were installed in the directory \texttt{/usr/local/gap4r4}, then you would do the following. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  $ cd /usr/local/gap4r4/pkg
  $ su
  % wget http://math.uic.edu/~marcus/Crime/crime-1.3.tar.gz
  % tar xvzvf crime-1.3.tar.gz 
  
\end{Verbatim}
 In this situation, users would load the package with the \texttt{LoadPackage} command. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  $ gap
  gap> LoadPackage("crime");
  
\end{Verbatim}
 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 \texttt{/tmp}, and load the package as follows. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  $ mkdir /tmp/pkg
  $ cd /tmp/pkg
  $ wget http://math.uic.edu/~marcus/Crime/crime-1.3.tar.gz
  $ tar xvzvf crime-1.3.tar.gz 
  $ gap -l ';/tmp'
  gap> LoadPackage("crime");
\end{Verbatim}
 Finally, it would be a good idea to run the test file to confirm that all the
functions work. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ReadPackage("crime","tst/test.g");
\end{Verbatim}
 You can count yourself lucky if \textsf{GAP} doesn't complain about anything. There is also a longer running test file for
those having ample free time described in Appendix \ref{test}. }

 
\chapter{\textcolor{Chapter }{Usage}}\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X86A9B6F87E619FFF}{}
{
 Unless otherwise specified, all the functions described below taking an
argument \texttt{n} do whatever the manual says they do up to homological degree \texttt{n}. These functions are idempotent in the sense that called a second time with
the same argument \texttt{n}, they do nothing, but called with a bigger \texttt{n}, they continue computing from where the previous calculations left off. 
\section{\textcolor{Chapter }{Cohomology Objects}}\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X85BF21B17BF76907}{}
{
  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 \texttt{CObject}, which is created with the following command. 

\subsection{\textcolor{Chapter }{CohomologyObject}}
\logpage{[ 2, 1, 1 ]}\nobreak
\hyperdef{L}{X8716E7657F9683B7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyObject({\slshape G, M})\index{CohomologyObject@\texttt{CohomologyObject}}
\label{CohomologyObject}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyObject({\slshape G})\index{CohomologyObject@\texttt{CohomologyObject}}
\label{CohomologyObject}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a \texttt{CObject}.



 This function creates a \texttt{CObject} having components the $p$-group $G$ and the \textsf{MeatAxe} module $M$, which should be a $kG$-module with $G$ the same group and $k$ a field of characteristic $p$. Note that \textsf{MeatAxe} modules record $k$ but not $G$, which is why this operation requires the user to specify $G$ but not $k$. 

 Fortunately, most users don't need to know anything about \textsf{MeatAxe} modules, being interested primarily in the case where $k=\mathbb{F}_p$,  and $M=k$, the trivial $kG$-module. In this situation, the second invocation creates a cohomology object
having components the $p$-group $G$ and the trivial \textsf{MeatAxe} $kG$-module $k=\mathbb{F}_p$.  }

 

 We emphasize that in the first invocation, $k$ can be any field of characteristic $p$ and \texttt{M} can be any \textsf{MeatAxe} module over $kG$, and that \texttt{ProjectiveResolution} works when \texttt{M} is an arbitrary \textsf{MeatAxe} module, but that all the functions dealing with the ring-structure of $H^\ast\left(G,k\right)$  require that \texttt{M} be the trivial module. 

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{\textcolor{Chapter }{Minimal Projective Resolutions}}\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X7FEB30657DDEFE44}{}
{
 Given a $p$-group $G$, a field $k$ of characteristic $p$, and a $kG$-module $M$, the function below computes the first $n$ terms of the minimal projective resolution of $M$  
\[ P_n\rightarrow\cdots\rightarrow P_2\rightarrow P_1 \rightarrow P_0\rightarrow
M\rightarrow 0 \]
 where $P_i=\left(kG\right)^{\oplus b_i}$   for certain numbers $b_i$, the \emph{Betti numbers} of the resolution. The minimal $kG$-projective resolution of $M$ is unique up to chain isomorphism. Because of the minimality of $P_\ast$, the groups  $\mathrm{Ext}^i_{kG}\left(M,N\right)$  are simply  $\mathrm{Hom}_{kG}\left(P_i,N\right)$,  and if $M$ and $N$ are both the trivial $kG$-module $k$, then  $H^i\left(G,k\right)=\mathrm{Ext}^i_{kG} \left(k,k\right)=k^{b_i}$.  

\subsection{\textcolor{Chapter }{ProjectiveResolution}}
\logpage{[ 2, 2, 1 ]}\nobreak
\hyperdef{L}{X8273999C7B352F22}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ProjectiveResolution({\slshape C, n})\index{ProjectiveResolution@\texttt{ProjectiveResolution}}
\label{ProjectiveResolution}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list containing the Betti numbers $b_0, b_1,\ldots, b_n$.



 Given a cohomology object \texttt{C} having components $G$ and $M$, this function computes the first \texttt{n}$+1$ terms of the minimal projective resolution $P_\ast$ of $M$ of the form  $P_i=\left(kG\right)^{\oplus b_i}$ for $0\leq i\leq n$,  and returns the numbers $b_i$ as a list. }

 

\subsection{\textcolor{Chapter }{BoundaryMap}}
\logpage{[ 2, 2, 2 ]}\nobreak
\hyperdef{L}{X7AF313D387F6BA22}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BoundaryMap({\slshape C, n})\index{BoundaryMap@\texttt{BoundaryMap}}
\label{BoundaryMap}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the \texttt{n}th boundary map.



 Given the cohomology object \texttt{C}, this function computes a projective resolution to degree \texttt{n} if it hasn't been computed already, and returns the \texttt{n}th boundary map. 

The map returned is a  $b_n\times b_{n-1}\left|G\right|$  matrix, having in the $i$th row the image of the element $1_G$ from the $i$th direct summand of $P_n$. 

See the file \texttt{doc/example.*} for an example of the usage and interpretation of the result of this function. }

 }

 
\section{\textcolor{Chapter }{Cohomology Generators and Relators}}\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X78C37B2E7D297FC5}{}
{
 See \cite{carlson} for the details of the calculation of cohomology products using composition of
chain maps. See also the file \texttt{doc/explanation.*} for an explanation of the implementation. 

\subsection{\textcolor{Chapter }{CohomologyGenerators}}
\logpage{[ 2, 3, 1 ]}\nobreak
\hyperdef{L}{X81F141187B0EC653}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyGenerators({\slshape C, n})\index{CohomologyGenerators@\texttt{CohomologyGenerators}}
\label{CohomologyGenerators}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list containing the degrees of the elements of a set of generators of the
cohomology ring.



 Given a cohomology object \texttt{C} having group component $G$ and module component the trivial $kG$-module, this function computes a set of generators of  $H^\ast\left(G,k\right)$  having degree \texttt{n} or less, and stores them in \texttt{C}. The function returns a list of the degrees of these generators. }

 The actual cohomology generators are represented by maps $P_n \rightarrow k$ and are stored in \texttt{C} as matrices. Only their degrees are returned. 

\subsection{\textcolor{Chapter }{CohomologyRelators}}
\logpage{[ 2, 3, 2 ]}\nobreak
\hyperdef{L}{X812BE8E983DC20BC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyRelators({\slshape C, n})\index{CohomologyRelators@\texttt{CohomologyRelators}}
\label{CohomologyRelators}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list of generators and a list of relators.



 Given a cohomology object \texttt{C} having group component $G$ and module component $k$, this function computes a set of generators of the ideal of relators in  $H^\ast\left(G,k\right),$  all having multidegree $n$ or less. 

More specifically, the function returns two lists, the first list containing
the variables \texttt{z}, \texttt{y}, \texttt{x}, $\ldots$ corresponding to the generators of  $H^\ast\left(G,k\right)$  if there are fewer than 12 generators and containing the variables \texttt{x{\textunderscore}1}, \texttt{x{\textunderscore}2}, \texttt{x{\textunderscore}3}, $\ldots$ otherwise. The second list is a list of polynomials in the variables from the
first list. 

These two lists should be interpreted as follows. A degree \texttt{n} approximation of the cohomology ring  $H^\ast\left(G,k\right)$  is given by the polynomial ring over $k$ in the non-commuting variables from the first list, (having degrees given by
the list returned by \texttt{CohomologyGenerators} in section \ref{CohomologyGenerators} ) and subject to the relators in the second list. See section \ref{whathappens} for more details still. }

 For example, consider the following commands. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> C:=CohomologyObject(DihedralGroup(8));
  <object>
  gap> CohomologyGenerators(C,10);
  [ 1, 1, 2 ]
  gap> CohomologyRelators(C,10);
  [ [ z, y, x ], [ z*y+y^2 ] ]
  
\end{Verbatim}
 This tells us that for $G=D_8$, the cohomology ring  $H^\ast\left(G,k\right)$  is the graded-commutative polynomial ring in the variables $z$, $y$, and $x$ of degrees 1, 1, and 2, subject to the relation $zy+y^2$. But since  $H^\ast\left(G,k\right)$  is commutative, $k$ being of characteristic 2, we have  $H^\ast\left(G,k\right)=k\left[z,y,x\right] \left/\left(zy+y^2\right)\right.$.  This result can be further improved by taking $z=z+y$, giving  $H^\ast\left(G,k\right)=k\left[z,y,x\right] \left/\left(zy\right)\right.$.  

Observe that in this case, we knew in advance that there was a set of
generators for $H^\ast\left(G,k\right)$  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 section \ref{whathappens} for details. 

While this isn't likely to occur, we point out that if there are 12 or more
generators and some of the indeterminates \texttt{x{\textunderscore}1}, \texttt{x{\textunderscore}2}, \texttt{x{\textunderscore}3}, $\ldots$ have already been named, say by a previous call to \texttt{CohomologyRelators}, then these variables will retain their old names. If this is confusing, you
could restart \textsf{GAP} and do it again. 

Finally, \texttt{CohomologyRelators} is \emph{not} 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. }

 
\section{\textcolor{Chapter }{Tests for Completion}}\label{completion}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X87C9251687CD4247}{}
{
 A test or series of tests for completion of the calculation will hopefully be
implemented soon. See \cite{carlson} for the details. }

 
\section{\textcolor{Chapter }{Cohomology Rings}}\label{ring}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X80B6849C835B7F19}{}
{
 Whereas the operations in sections \ref{CohomologyGenerators} and \ref{CohomologyRelators} calculate a presentation for the cohomology ring, the operation below creates
the ring in \textsf{GAP} as a structure constant algebra. 

See \cite{carlson} for the details of the calculation of cohomology products using composition of
chain maps. See also the file \texttt{doc/explanation.*} for an explanation of the implementation. 

\subsection{\textcolor{Chapter }{CohomologyRing}}
\logpage{[ 2, 5, 1 ]}\nobreak
\hyperdef{L}{X7B77337486380998}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyRing({\slshape C, n})\index{CohomologyRing@\texttt{CohomologyRing}}
\label{CohomologyRing}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CohomologyRing({\slshape G, n})\index{CohomologyRing@\texttt{CohomologyRing}}
\label{CohomologyRing}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the cohomology ring of $G$.



 Given a cohomology object \texttt{C} with group component $G$ and module component the trivial $kG$-module, this function returns the degree \texttt{n} truncation of the cohomology ring $H^\ast\left(G,k\right).$  See \ref{whathappens} for what this means exactly. The object returned is a structure constant
algebra. 

Users interested only in working with the cohomology ring of a group as a \textsf{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 \texttt{G} immediately, throwing away all intermediate calculations. 

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

Observe also that calling \texttt{CohomologyRing} a second time with a bigger \texttt{n} does \emph{not} 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. }

 Recall that $H^\ast\left(G,k\right)$  is a graded structure constant algebra, the components being the cohomology
groups $H^i\left(G,k\right)$.  The following functions were intended to be used for cohomology rings, but in
principle, they work for any graded structure constant algebra. 

\subsection{\textcolor{Chapter }{IsHomogeneous}}
\logpage{[ 2, 5, 2 ]}\nobreak
\hyperdef{L}{X7D8EA4528082A74D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsHomogeneous({\slshape e})\index{IsHomogeneous@\texttt{IsHomogeneous}}
\label{IsHomogeneous}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}.



 Given an element \texttt{e} of a cohomology ring $H^\ast\left(G,k\right)$,  this operation determines whether or not \texttt{e} is homogeneous, that is, whether \texttt{e} is contained in $H^i\left(G,k\right)$  for some \texttt{i}. }

 

\subsection{\textcolor{Chapter }{Degree}}
\logpage{[ 2, 5, 3 ]}\nobreak
\hyperdef{L}{X826A861E7E7D944E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Degree({\slshape e})\index{Degree@\texttt{Degree}}
\label{Degree}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
the degree of \texttt{e}.



 This function returns the degree of the possibly non-homogeneous element \texttt{e} of a cohomology ring $H^\ast\left(G,k\right)$.  Specifically, if  $H^\ast\left(G,k\right)=A_0\oplus A_1\oplus A_2\oplus\cdots$  where $A_i=H^i\left(G,k\right)$,  then this function returns the minimum $n$ such that \texttt{e} is in  $A_0\oplus A_1\oplus\cdots\oplus A_n$.  }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  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 
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{LocateGeneratorsInCohomologyRing}}
\logpage{[ 2, 5, 4 ]}\nobreak
\hyperdef{L}{X813A8E4C7D4C9FBD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LocateGeneratorsInCohomologyRing({\slshape C})\index{LocateGeneratorsInCohomologyRing@\texttt{LocateGeneratorsInCohomologyRing}}
\label{LocateGeneratorsInCohomologyRing}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list containing the cohomology generators.



 Having already called \texttt{CohomologyRing} (see \ref{CohomologyRing}), this function returns a list of elements of the cohomology ring which
together with the identity element generate the cohomology ring. 

This function is a wrapper for \texttt{CohomologyGenerators} (see \ref{CohomologyGenerators}). It points out which elements of the cohomology ring correspond with the
generators found by \texttt{CohomologyGenerators}. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  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
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{What Happens if \texttt{n} Isn't Big Enough?}}\label{whathappens}
\logpage{[ 2, 6, 0 ]}
\hyperdef{L}{X7E21853583D6D86D}{}
{
  Since $P_\ast$ is a \emph{minimal} projective resolution, we have  $H^i\left(G,k\right) = \mathrm{Hom}_{kG}\left(P_i,k\right)$  where $P_i = \left(kG\right)^{b_i}$ so that $H^i\left(G,k\right)$ has a natural basis consisting of the maps sending the element $1_G$ of the $j$th direct summand of $P_i$ to $1_k$ and all other direct summands to $0$, for  $1\le j\le b_i$,  where $b_i$ is the $kG$-rank of $P_i$. 

The command \texttt{CohomologyRing(C,n)} forms the vector space whose basis is the concatenation of the natural bases
of $H^i\left(G,k\right)$ for  $1\le i\le n$  and computes all products of basis elements $x$ and $y$ for which $\deg x+\deg y \leq n$. Thinking of $H^\ast\left(G,k\right)$  in terms of it's multiplication table, this means that the function computes
the upper left-hand corner of the multiplication table. If $\deg x + \deg y > n$, the product $xy$ is taken to be zero. Therefore, the ring returned by \texttt{CohomologyRing} is  $H^\ast\left(G,k\right)\left/J_{>n}\right.$  where $J_{>n}$  is the ideal of all elements of degree $>n$. 

The ring determined by \texttt{CohomologyGenerators} and \texttt{CohomologyRelators} is somewhat different. \texttt{CohomologyGenerators} proceeds inductively, taking all natural basis elements of $H^1\left(G,k\right)$ as generators, and for  $1<i\le n$,  taking all natural basis elements of $H^i\left(G,k\right)$ which are \emph{not} products of lower-degree elements as generators. Therefore, unless you know
that there is an $n$ for which there exists a generating set of  $H^\ast\left(G,k\right)$  consisting of elements of degree $n$ or less, then you are \emph{not} guaranteed that the elements returned by the \texttt{CohomologyGenerators} generate  $H^\ast\left(G,k\right)$  as a ring. The knowledge of such an $n$ is the subject of section \ref{completion}. 

Similarly, \texttt{CohomologyRelators} proceeds inductively until degree $n$, returning a list of polynomials which generate the ideal of relators of
multidegree $n$ or less. Again, you have to already know how big $n$ should be. 

The result of the preceding information is that there is a homomorphism  $f:k\left.\left\langle x_1,x_2,\dots x_m \right\rangle\right./I \to
H^\ast\left(G,k\right)$,  where $k\left\langle x_1,x_2,\ldots x_m \right\rangle$ is the graded polynomial ring over $k$ in the non-commuting variables $x_1,x_2,\ldots,x_m$, having degrees the numbers in the list returned by \texttt{CohomologyGenerators}, and $I$ is the ideal in $k\left\langle x_1,x_2,\ldots, x_m \right\rangle$ generated by the elements returned by \texttt{CohomologyRelators(C,n)}. 

Therefore, if there is a generator of degree greater than $n$, then $f$ won't be surjective. Similarly, if there is a relator of multidegree greater
than $n$ which is not a consequence of lower degree relators, then $f$ won't be injective. See section \ref{completion} for a discussion on how big $n$ needs to be to ensure that $f$ be an isomorphism. }

 
\section{\textcolor{Chapter }{Induced Maps}}\logpage{[ 2, 7, 0 ]}
\hyperdef{L}{X837261007B39795C}{}
{
 Let $f: H \rightarrow G$ be a group homomorphism. Then $f$ induces a homomorphism on cohomology  $H^\ast\left(G,k\right) \to H^\ast\left(H,k\right)$  which is returned by the following function. 

\subsection{\textcolor{Chapter }{InducedHomomorphismOnCohomology}}
\logpage{[ 2, 7, 1 ]}\nobreak
\hyperdef{L}{X8608BD148307390B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InducedHomomorphismOnCohomology({\slshape C, D, f, n})\index{InducedHomomorphismOnCohomology@\texttt{InducedHomomorphismOnCohomology}}
\label{InducedHomomorphismOnCohomology}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the induced homomorphism on cohomology.



 This function returns the induced homomorphism  $H^\ast\left(G,k\right) \to H^\ast\left(H,k\right)$,  where the groups $H$ and $G$ are the components of the cohomology objects \texttt{C} and \texttt{D} and $f: H \rightarrow G$ is a group homomorphism. If the cohomology rings have not yet been calculated,
they will be computed to degree $n$, and in this case, they can then be accessed by calling \texttt{CohomologyRing} (see \ref{CohomologyRing}). }

 

\subsection{\textcolor{Chapter }{Inclusion}}
\logpage{[ 2, 7, 2 ]}\nobreak
\hyperdef{L}{X87D180E2801B1EA8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Inclusion({\slshape H, G})\index{Inclusion@\texttt{Inclusion}}
\label{Inclusion}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the inclusion $H\rightarrow G$



This function returns the group homomorphism $H\rightarrow G$ when $H$ is a subgroup of $G$. The returned map can be used as the \texttt{f} argument of \texttt{InducedHomomorphismOnCohomology}, in which case the induced homomorphism is the restriction map  $\mathrm{Res}^G_H:H^\ast\left(G,k\right) \to H^\ast\left(H,k\right)$.  }

 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. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Massey Products}}\logpage{[ 2, 8, 0 ]}
\hyperdef{L}{X7B541EB97BAB36D7}{}
{
 See \cite{kraines} for the definitions and \cite{borge} for the details of the calculation using the Yoneda cocomplex. See also the
file \texttt{doc/explanation.*} for an explanation of the implementation. 

\subsection{\textcolor{Chapter }{MasseyProduct}}
\logpage{[ 2, 8, 1 ]}\nobreak
\hyperdef{L}{X7E3023CE86641F9E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MasseyProduct({\slshape x1, x2, ..., xn})\index{MasseyProduct@\texttt{MasseyProduct}}
\label{MasseyProduct}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the Massey product  $\left\langle x_1,x_2,\dots,x_n\right\rangle$.  



 Given elements  $x_1,x_2,\dots,x_n$  of the ring returned by \texttt{CohomologyRing} (see \ref{ring}), this function computes the $n$-fold Massey product  $\left\langle x_1,x_2,\ldots,x_n\right\rangle$  provided that the lower-degree Massey products  $\left\langle x_i,x_{i+1},\ldots,x_n\right\rangle$  vanish for all $1 \leq i < j \leq n$, and returns \texttt{fail} otherwise. }

 As an example, recall that the cohomology rings of the cyclic groups $C_3$ and $C_9$ of sizes 3 and 9 over $k=\mathbb{F}_3$  are both given by  $k\left\langle z, y\right\rangle\left/\left(z^2\right)\right.$,  so they are isomorphic as rings. However, the following example shows that  $\left\langle z,z,z\right\rangle$  is non-zero in $H^\ast\left(C_3,k\right)$  but is zero in $H^\ast\left(C_9,k\right)$.  
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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
  
\end{Verbatim}
 }

 }

 

\appendix


\chapter{\textcolor{Chapter }{Some Benchmarks}}\label{benchmarks}
\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X82113B3184F76F58}{}
{
 Some of the key subroutines have been improved in version 1.3 of \textsf{Crime}, resulting in a significant speedup of many basic calculations. 

The numbers in the following table compare the runtimes of the 1.1 and 1.3
versions of the functions listed in the column headers on all the groups of
size 16. All functions were executed on a 2.4 GHz AMD64 processor with 12 GB
of RAM. The number in the first column of every row is the Small Group Library
number of the group used in that row, so the group used in row \texttt{n} is \texttt{SmallGroup(16,n)}. The upper number in each box is the runtime for the 1.1 version, whereas the
lower number is the runtime for the 1.3 version. \begin{center}
\begin{tabular}{c|c|c|c}Group&
\texttt{ProjectiveResolution}&
\texttt{CohomologyGenerators}&
\texttt{CohomologyRelators}\\
\hline
1&
0:00:00.424&
0:00:00.040&
0:00:00.092\\
&
0:00:00.380&
0:00:00.016&
0:00:00.012\\
\hline
2&
0:00:00.436&
0:00:01.472&
0:00:05.848\\
&
0:00:00.072&
0:00:00.116&
0:00:00.396\\
\hline
3&
0:00:02.752&
0:00:11.469&
0:00:42.887\\
&
0:00:00.352&
0:00:01.192&
0:00:01.944\\
\hline
4&
0:00:00.480&
0:00:01.456&
0:00:06.320\\
&
0:00:00.068&
0:00:00.116&
0:00:00.316\\
\hline
5&
0:00:00.480&
0:00:01.136&
0:00:06.045\\
&
0:00:00.080&
0:00:00.096&
0:00:00.296\\
\hline
6&
0:00:00.204&
0:00:00.724&
0:00:01.892\\
&
0:00:00.036&
0:00:00.072&
0:00:00.116\\
\hline
7&
0:00:00.504&
0:00:01.156&
0:00:06.140\\
&
0:00:00.088&
0:00:00.100&
0:00:00.344\\
\hline
8&
0:00:00.192&
0:00:00.704&
0:00:01.800\\
&
0:00:00.036&
0:00:00.064&
0:00:00.120\\
\hline
9&
0:00:00.060&
0:00:00.100&
0:00:00.284\\
&
0:00:00.020&
0:00:00.012&
0:00:00.028\\
\hline
10&
0:00:10.161&
0:00:34.326&
0:03:07.104\\
&
0:00:01.524&
0:00:04.252&
0:00:08.089\\
\hline
11&
0:00:10.397&
0:00:32.354&
0:03:07.355\\
&
0:00:01.716&
0:00:04.584&
0:00:08.021\\
\hline
12&
0:00:01.184&
0:00:04.613&
0:00:20.789\\
&
0:00:00.192&
0:00:00.544&
0:00:00.984\\
\hline
13&
0:00:01.152&
0:00:04.496&
0:00:20.990\\
&
0:00:00.196&
0:00:00.472&
0:00:01.072\\
\hline
14&
0:03:26.817&
0:07:37.960&
0:56:39.273\\
&
0:00:41.919&
0:02:07.399&
0:01:54.752\\
\end{tabular}\\[2mm]
\end{center}

 }


\chapter{\textcolor{Chapter }{Leisure and Recreation: Cohomology Rings of all Groups of Size 16}}\label{test}
\logpage{[ "B", 0, 0 ]}
\hyperdef{L}{X7BC2C62E7A8CC2B9}{}
{
 Below is the output of the test file \texttt{tst/batch.g}. The file runs through all groups of size $n$, which is initially set to $16$, calls \texttt{ProjectiveResolution}, \texttt{CohomologyGenerators}, and \texttt{CohomologyRelators} for each group, and prints the results, as well as the runtimes for each
operation, to a file like the one shown below. The runtimes in this example
have been deleted, having been presented in Appendix \ref{benchmarks}. The example below was computed on a 2.4 GHz AMD64 processor with 12 GB of
RAM. See the file \texttt{tst/README} for suggestions on dealing with other users when running long-running batch
processes. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  SmallGroup(16,1)
  Betti Numbers: [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
  Generators in degrees: [ 1, 2 ]
  Relators: [ [ z, y ], [ z^2 ] ]
  
  SmallGroup(16,2)
  Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
  Generators in degrees: [ 1, 1, 2, 2 ]
  Relators: [ [ z, y, x, w ], [ z^2, y^2 ] ]
  
  SmallGroup(16,3)
  Betti Numbers: [ 1, 2, 4, 6, 9, 12, 16, 20, 25, 30, 36 ]
  Generators in degrees: [ 1, 1, 2, 2, 2 ]
  Relators: [ [ z, y, x, w, v ], [ z^2, z*y, z*x, y^2*v+x^2 ] ]
  
  SmallGroup(16,4)
  Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
  Generators in degrees: [ 1, 1, 2, 2 ]
  Relators: [ [ z, y, x, w ], [ z^2, z*y+y^2, y^3 ] ]
  
  SmallGroup(16,5)
  Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
  Generators in degrees: [ 1, 1, 2 ]
  Relators: [ [ z, y, x ], [ z^2 ] ]
  
  SmallGroup(16,6)
  Betti Numbers: [ 1, 2, 2, 2, 3, 4, 4, 4, 5, 6, 6 ]
  Generators in degrees: [ 1, 1, 3, 4 ]
  Relators: [ [ z, y, x, w ], [ z^2, z*y^2, z*x, x^2 ] ]
  
  SmallGroup(16,7)
  Betti Numbers: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ]
  Generators in degrees: [ 1, 1, 2 ]
  Relators: [ [ z, y, x ], [ z*y ] ]
  
  SmallGroup(16,8)
  Betti Numbers: [ 1, 2, 2, 2, 3, 4, 4, 4, 5, 6, 6 ]
  Generators in degrees: [ 1, 1, 3, 4 ]
  Relators: [ [ z, y, x, w ], [ z*y, z^3, z*x, y^2*w+x^2 ] ]
  
  SmallGroup(16,9)
  Betti Numbers: [ 1, 2, 2, 1, 1, 2, 2, 1, 1, 2, 2 ]
  Generators in degrees: [ 1, 1, 4 ]
  Relators: [ [ z, y, x ], [ z*y, z^3+y^3, y^4 ] ]
  
  SmallGroup(16,10)
  Betti Numbers: [ 1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66 ]
  Generators in degrees: [ 1, 1, 1, 2 ]
  Relators: [ [ z, y, x, w ], [ z^2 ] ]
  
  SmallGroup(16,11)
  Betti Numbers: [ 1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66 ]
  Generators in degrees: [ 1, 1, 1, 2 ]
  Relators: [ [ z, y, x, w ], [ z*y ] ]
  
  SmallGroup(16,12)
  Betti Numbers: [ 1, 3, 5, 6, 7, 9, 11, 12, 13, 15, 17 ]
  Generators in degrees: [ 1, 1, 1, 4 ]
  Relators: [ [ z, y, x, w ], [ z^2+z*y+y^2, y^3 ] ]
  
  SmallGroup(16,13)
  Betti Numbers: [ 1, 3, 5, 6, 7, 9, 11, 12, 13, 15, 17 ]
  Generators in degrees: [ 1, 1, 1, 4 ]
  Relators: [ [ z, y, x, w ], [ z*y+x^2, z*x^2+y*x^2, y^2*x^2+x^4 ] ]
  
  SmallGroup(16,14)
  Betti Numbers: [ 1, 4, 10, 20, 35, 56, 84, 120, 165, 220, 286 ]
  Generators in degrees: [ 1, 1, 1, 1 ]
  Relators: [ [ z, y, x, w ], [  ] ]
  
\end{Verbatim}
 }

\def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{plain}
\bibliography{crimebib.xml}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}