\Chapter{List of HAP functions }

The following is a list of the functions available in the {\sf HAP} package. The html manual (avaiable in the directory pkg/Hap/www) gives full details.

\bigskip
\bigskip

\>AddWords(v,w)

Inputs two words v,w in a free ZG-module and returns their sum v+w. If the characteristic of Z is greater than 0 then the next function should be more efficient.

\>AddWordsModP(v,w,p)

Inputs two words v,w in a free ZG-module and the characteristic p of Z. It returns the sum v+w. If p=0 the previous function might be fractionally quicker.

\>AlgebraicReduction(w)
\>AlgebraicReduction(w,p)

Inputs a word w in a free ZG-module and returns a reduced version of the word in which all pairs of mutually inverse letters have been cancelled. The reduction is performed in a free abelian group unless the characteristic p of Z is entered.

\>CocycleCondition(R,n)

Inputs a resolution $R$ and an integer n>0. It returns an integer matrix $M$
with the following property. Suppose d=R.dimension(n). 
An integer vector $f=[f_1, \ldots, f_d]$ then represents a $ZG$-homomorphism 
$R_n\rightarrow Z_q$ which sends the i-th generator of $R_n$
to the integer $f_i$ in the trivial $ZG$-module $Z_q$ (where possibly q=0). 
The homomorphism $f$ is a cocycle if and only if $M^tf=0$ mod q. 

\>Cohomology(X)

Inputs either a cochain complex $X=C$ or a cochain map $X=(C\rightarrow D)$
over the integers Z. At present only characteristic 0 is implemented.

If $X=C$ then the torsion coefficients of $H_n(C)$ are retuned.

If $X=(C\rightarrow D)$
then the induced homomorphism $H_n(C)\rightarrow H_n(D)$
is returned as a homomorphism of finitely presented groups. 

\>CoxeterDiagramComponents(D)

Inputs a Coxeter diagram $D$ and returns a list $[D_1, \ldots, D_d]$
of the maximal connected subgraphs $D_i$.

\>CoxeterDiagramDegree(D,v)

Inputs a Coxeter diagram D and vertex v. It returns the degree of v (i.e. the number of edges incident with v).

\>CoxeterDiagramFpArtinGroup(D)

Inputs a Coxeter diagram D and returns the corresponding finitely presented Artin group.

\>CoxeterDiagramFpCoxeterGroup(D)

Inputs a Coxeter diagram D and returns the corresponding finitely presented Coxeter group.

\>CoxeterDiagramIsSpherical(D)

Inputs a Coxeter diagram D and returns ``true'' if the associated Coxeter groups is finite, and returns ``false'' otherwise.

\>CoxeterDiagramMatrix(D)

Inputs a Coxeter diagram D and returns a matrix representation of it. The matrix is given as a function DiagramMatrix(D)(i,j) where i,j can range over the vertices.

\>CoxeterSubDiagram(D,V)

Inputs a Coxeter diagram D and a subset V of its vertices. It returns the full sub-diagram of D with vertex set V.

\>CoxeterDiagramVertices(D)

Inputs a Coxeter diagram D and returns its set of vertices.

\>Epicentre(G,N)
\>Epicentre(G)

Inputs a finite group $G$ and normal subgroup $N$ and returns a subgroup 
$Z^{*}(G,N)$ of the centre of $N$. The group $Z^{*}(G,N)$ is trivial if and only 
if there is a crossed module $d:E\rightarrow G$ with $N=Image(d)$ and with 
$Ker(d)$ equal to the subgroup of $E$ consisting of those elements on which 
$G$ acts trivially.

If no value for $N$ is entered then it is assumed that $N=G$. In this case the 
group $Z^{*}(G,G)$ is trivial if and only if $G$ is isomorphic to a quotient 
$G=E/Z(E)$ of some group $E$ by the centre of $E$.  (There are probably quicker ways to compute $Z^{*}(G,G)$ . )

\>EvaluateProperty(X,``name'')

Inputs a record X (such as a ZG-resolution or chain map) and a string ``name'' (such as ``characteristic'' or ``type''). It searches X.property for the  pair [``name'',value] and returns value. If X.property does not exist, or if [``name'',value] does not exist, it returns fail.

\>EvenSubgroup(G)

Inputs a group G and returns a subgroup G+. The subgroup is that generated by all products xy where x and y range over the generating set for G stored by GAP. The subgroup is probably only meaningful when G is an Artin or Coxeter group.

\>EquivariantChainMap(R,S,f)

Inputs a $ZG$-resolution $R$, a $ZG'$-resolution $S$ with $G'$ finite, and a 
group homomorphism $f : G \rightarrow G'$. It outputs a record M with the following components:

M.source is the resolution $R$.
        
M.target is the resolution $S$.
	    
M.mapping(w,n) is a function which gives the image in $S_n$, under a chain map induced by $f$, of a word w in $R_n$. (Here  $R_n$ and $S_n$ are the n-th 
modules in the resolutions $R$ and $S$.)
	        
F.properties is a list of pairs such as [``type'', ``equivariantChainMap''].

The resolution $S$ must have a contracting homotopy. 

\>GroupHomology(X,n)
\>GroupHomology(X,n,p)

Inputs a positive integer n and either a finite group X=G or a Coxeter diagram X=D representing an infinite Artin group G.  It returns the torsion coefficients of the integral homology $H_n(G,Z)$.

There is an optional third argument which, when set equal to a prime p, causes the function to return the rank of the mod p homology $H_n(G,Zp)$.

This function is a composite of more basic functions, and makes choices for a number of parameters. For a particular group you would almost certainly be better using the more basic functions and making the choices yourself!

\>HAPcopyright()

This function provides details of HAP'S GNU public copyright licence.

\>Homology(X,n)

Inputs either a chain complex $X=C$ or a chain map $X=(C\rightarrow D)$.

If $X=C$ then the torsion coefficients of $H_n(C)$ are retuned.

If $X=(C\rightarrow D)$ then the induced homomorphism $H_n(C)\rightarrow H_n(D)$ is returned as a homomorphism of finitely presented groups.

\>HomToIntegers(X)

Inputs either a $ZG$-resolution $X=R$, or an equivariant chain map 
$X = (F:R\rightarrow S)$. It returns the cochain complex or cochain map obtained by applying $Hom_{ZG}( _ , Z)$ where Z is the trivial module of integers (characteristic 0).

\>HomToIntegralModule(R,f)

Inputs a $ZG$-resolution $R$ and a group homomorphism $f:G\rightarrow GL_n(Z)$
to the group of $n\times n$ invertible integer matrices. Here Z must have 
characteristic 0. It returns the cochain complex obtained by applying 
$Hom_{ZG}( _ , A)$ where $A$ is the $ZG$-module $Z_n$ with $G$ action via $f$. 

\>IntegralRingGenerators(R,n)

Inputs at least n+1 terms of a $ZG$-resolution and integer n>0. It returns a 
minimal list of cohomology classes in $H^n(G,Z)$ which, together with all cup 
products of lower degree classes, generate the group $H^n(G,Z)$ .

(Let $a_i$ be the i-th canonical generator of the d-generator abelian group 
$H^n(G,Z)$. The cohomology class $n_1a_1 + \ldots +n_da_d$ is represented by 
the integer vector $u=(n_1, \ldots, n_d)$. )

\>IntegralCupProduct(R,u,v,p,q)
\>IntegralCupProduct(R,u,v,p,q,P,Q,N)

Inputs a $ZG$-resolution $R$, a vector $u$ representing an element in 
$H^p(G,Z)$, a vector $v$ representing an element in $H^q(G,Z)$ and the two 
integers $p,q > 0$. It returns a vector $w$ representing the cup product 
$u\cdot v$ in $H^{p+q}(G,Z)$. This product is associative and 
$u\cdot v = (-1)pqv\cdot u$ .  It provides $H^{*}(G,Z)$ with the structure of an 
anti-commutative graded ring. The cup product is currently implemented for 
characteristic 0 only.

The resolution $R$ needs a contracting homotopy.

To save the function from having to calculate the abelian groups $H^n(G,Z)$
additional input variables can be used in the form 
{\sf IntegralCupProduct(R,u,v,p,q,P,Q,N)} , where

P is the output of the command {\sf CR_CocyclesAndCoboundaries(R,p,true)}

Q is the output of the command {\sf CR_CocyclesAndCoboundaries(R,q,true)}

N is the output of the command {\sf CR_CocyclesAndCoboundaries(R,p+q,true)} .
	    
\>IsAspherical(F,R)

Inputs a free group $F$ and a set $R$ of words in $F$. It performs a test on 
the 2-dimensional CW-space $K$ associated to this presentation for the group 
$G=F/<R>^F$. 

The function returns ``true'' if $K$ has trivial second homotopy group. In this case it prints: Presentation is aspherical.

Otherwise it returns ``fail'' and prints: ``Presentation is NOT piece-wise Euclidean non-positively curved''. (In this case $K$ may or may not have trivial second homotopy group. But it is NOT possible to impose a metric on K which restricts to a Euclidean metric on each 2-cell.)

The function uses Polymake software. 

\>MultiplyWord(n,w)

Inputs a word $w$ and integer $n$. It returns the scalar multiple $n\cdot w$ .

\>Negate([i,j])

Inputs a pair [i,j] of integers and returns [-i,j].

\>NegateWord(w)

Inputs a word $w$ in a free $ZG$-module and returns the negated word $-w$.

\>NonabelianExteriorProduct(G,N)

Inputs a finite group $G$ and normal subgroup $N$. It returns a record $E$
with the following components:

E.homomorphism is a group homomorphism $\mu\colon G\wedge N \rightarrow G$
rom the nonabelian exterior product $G\wedge N$ to $G$. The kernel of $\mu$
is the relative Schur multiplier.

E.pairing(x,y) is a function which inputs an element $x$ in $G$ and an element 
$y$ in $N$ and returns  $x \wedge y$ in the exterior product $G\wedge N$ .

This function should work for reasonably small nilpotent groups or extremely small non-nilpotent groups.

\>NonabelianTensorSquare(G)

Inputs a finite group G and returns a record T with the following components.

T.homomorphism is a group homomorphism $\mu\colon G\otimes G\rightarrow G$ 
from the nonabelian tensor square of $G$ to $G$. The kernel of $\mu$ is 
isomorphic to the third homotopy group of the suspension $SK(G,1)$ of  an 
Eilenberg-Mac Lane space.

T.pairing(x,y) is a function which inputs two elements $x, y$ in $G$ and returns the tensor $x \otimes y$ in the tensor square $G \otimes G$ .

This function should work for reasonably small nilpotent groups or extremely small non-nilpotent groups.

\>PermToMatrixGroup(G,n)

Inputs a permutation group $G$ and its degree $n$. Returns a bijective homomorphism $f:G\rightarrow M$ where $M$ is a group of permutation matrices.

\>PolytopalComplex(G,v)
\>PolytopalComplex(G,v)

Inputs a permutation group or matrix group G of degree n and a rational vector 
v of length n. In both cases there is a natural action of G on v. Let 
P(G,v) be the convex polytope arising as the convex hull of the Euclidean 
points in the orbit of v under the action of G. The cellular chain complex 
$C_{*}=C_{*}(P(G,v))$ is an exact sequence of (not necessarily free) ZG-modules. 
The function returns a record R with components:

R.dimension(k) is a function which returns the number of G-orbits of the 
k-dimensional faces in  P(G,v).  If each k-face has trivial stabilizer 
subgroup in G then $C_{k}$ is a free ZG-module of rank R.dimension(k).

R.stabilizer(k,n) is a function which returns the stabilizer subgroup for a face in the n-th orbit of k-faces.

If all faces of dimension less than k+1 have trivial stabilizer group then the first k 
terms of $C_{*}$ constitute part of a free  ZG-resolution. The boundary map is 
described by the function R.boundary(k,n) . 
(If some faces have non-trivial stabilizer group then $C_{*}$ is not free and no attempt is made to determine signs for the boundary map.)

R.elements, R.group, R.properties are as in a ZG-resolution.

If an optional third input variable n is used, then only the first n terms of 
the resolution $C_{*}$ will be computed.

The function uses Polymake software. 

\>PolytopalGenerators(G,v)

Inputs a permutation group or matrix group G of degree n and a rational vector 
v of length n. In both cases there is a natural action of G on v, and the 
vector v must be chosen so that it has trivial stabilizer subgroup in G. Let 
P(G,v) be the convex polytope arising as the convex hull of the Euclidean 
points in the orbit of v under the action of G. The function returns a record P with components:

P.generators is a list of all those elements g in G such that g·v has an edge 
in common with v. The list is a generating set for G.

P.vector is the vector v.

P.hasseDiagram is the Hasse diagram of the cone at v.

The function uses Polymake software.
The function is joint work with Seamus Kelly.


\>PresentationOfResolution(R)

Inputs at least two terms of a reduced ZG-resolution R and returns a record P with components

P.freeGroup is a free group F

P.relators is a list S of words in F

where G is isomorphic to F modulo the normal closure of S. This presentation for G corresponds to the 2-skeleton of the classifying CW-space from which R was constructed. The resolution R requires no contracting homotopy.

\>PrimePartDerivedFunctor(G,R,F,n)

Inputs a finite group $G$, a positive integer n, at least n+1 terms of a 
$ZP$-resolution for a Sylow subgroup $P \le G$ and a ``mathematically suitable'' 
covariant additive functor $F$ such as {\sf TensorWithIntegers} . It returns 
the abelian invariants of the p-component of the  homology $H_n(F(R))$ .

Warning: All calculations are assumed to be in characteristic 0. The function should not be used if the coefficient module is over the field of p elements.

``Mathematically suitable'' means that the Cartan-Eilenberg double coset formula must hold.

\>PrintZGword(w,elts)

Inputs a word w in a free ZG-module and a (possibly partial but sufficient) listing elts of the elements of G. The function prints the word w to the screen in the form
$$r_1E_1 + \ldots + r_nE_n$$
where $r_i$ are elements in the group ring ZG, and $E_i$ denotes the i-th free generator of the module. 

\>RelativeSchurMultiplierG,N)

Inputs a finite group $G$ and normal subgroup $N$. It returns the homology 
group $H_2(G,N,Z)$ that fits into the exact sequence 

$$H_3(G,Z) \rightarrow H_3(G/N,Z) \rightarrow H_2(G,N,Z) \rightarrow H_2(G,Z)
\rightarrow H_2(G/N,Z)$$

This function should work for reasonably small nilpotent groups G or extremely small non-nilpotent groups.

\>ResolutionAbelianGroup(L,n)
\>ResolutionAbelianGroup(G,n)

Inputs a list $L:=[m_1,m_2, \ldots, m_d]$ of nonnegative integers, and a 
positive integer n. It returns n terms of a ZG-resolution for the abelian group $G=Z_{L[1]}\oplus Z_{L[2]}\oplus \cdots \oplus Z_{L[d]}$ .

The first argument can also be the abelian group $G$ itself.

\>ResolutionArtinGroup(D,n)

Inputs a Coxeter diagram D and an integer  n>1.  It returns n terms of a free ZG-resolution R where G is the Artin monoid associated to D.  It is conjectured that R is also a free resolution for the Artin group G. The conjecture is known to hold in certain cases.

G=R.group is infinite and returned as a finitely presented group. The list R.elts is a partial listing of the elements of G which grows as R is used. Initially R.elts is empty and then, any time the boundary of a resolution generator is called, R.elts is updated to include elements of G involved in the boundary.

The contracting homotopy on R has not yet been implemented!

\>ResolutionAsphericalPresentation(F,R,n)
	
Inputs a free group F, a set R of words in F which constitute an aspherical presentation for a group G, and a positive integer n.  (Asphericity can be a difficult property to verify. The function IsAspherical(F,R) could be of help.)

The function returns n terms of a free ZG-resolution R which has generators in dimensions $\le 2$ only. No contracting homotopy on R will be returned.

\>ResolutionDirectProduct(R,S)

Inputs a $ZG$-resolution $R$ and $ZH$-resolution $S$. It outputs a 
$ZD$-resolution for the direct product $D=G\times H$. 

\>ResolutionFiniteExtension(gensE,gensG,R,n)
\>ResolutionFiniteExtension(gensE,gensG,R,n,true)
\>ResolutionFiniteExtension(gensE,gensG,R,n,false,S)

Inputs: a set gensE of generators for a finite group E; a set gensG equal to the image of gensE in a quotient group G of E; a ZG-resolution R up to dimension at least n; a positive  integer n. It uses the TwistedTensorProduct( construction to return n terms of a ZE-resolution.

The function has an optional fourth argument which, when set equal to true, invokes tietze reductions in the construction of a resolution for the kernel of 
$E\rightarrow G$.

If a ZN-resolution S is available, where N is the kernel of the quotient 
$E\rightarrow G$, then this can be incorporated into the computations using an optional fifth argument.

The contracting homotopy on the ZE-resolution has not yet been implemented!

\>ResolutionFiniteGroup(gens,n)
\>ResolutionFiniteGroup(gens,n,true)
\>ResolutionFiniteGroup(gens,n,false,p)

Inputs a set gens of generators for a finite group G and a positive integer n. It outputs n terms of a ZG-resolution.

The function has an optional third argument which, when set equal to  true, invokes tietze reductions in the construction of the resolution.

The function has an optional fourth argument which, when set equal to a prime p, records the fact that the resolution will only be used for mod p calculations. This could speed up subsequent constructions. 

\>ResolutionFiniteSubgroup(R,K)
\>ResolutionFiniteSubgroup(R,gensG,gensK)

Inputs a ZG-resolution for a finite group G and a subgroup K of index G:K. It returns a free ZK-resolution whose ZK-rank is G:K times the ZG-rank in each dimension.

Generating sets gensG, gensK for G and K can also be input to the function (though the method does not depend on a choice of generators).

This ZK-resolution has more than one generator in dimension 0. So {\sf 
PresentationOfResolution() } should not be applied to it!

\>ResolutionNormalSeries(L,n)
\>ResolutionNormalSeries(L,n,true)
\>ResolutionNormalSeries(L,n,false,p)

Inputs a positive integer n and a list $L = [L_1 , \ldots, L_k]$ of normal 
subgroups $L_i$ of a finite group $G$ satisfying $G = L1\ge L_2 \ldots \ge L_k$. Alternatively, $L = [gensL_1, \ldots gensL_k]$ can be a list of generating 
sets for the $L_i$ (and these  particular generators will be used in the 
construction of resolutions). It returns a $Z(G/L_k)$-resolution by repeatedly 
using the function {\sf ResolutionOfFiniteExtension( )}. Typically $L_k=1$
in which case a $ZG$-resolution is returned.

The function has an optional third argument which, if set equal to ``true'', invokes tietze reductions in the construction of resolutions.

The function has an optional fourth argument which, if set equal to p>0, produces a resolution which is only valid for mod p calculations.

The contracting homotopy on the $ZG$-resolution has not yet been implemented!


\>ResolutionPrimePowerGroup(G,n)

Inputs a $p$-group $G$ and integer $n\ge 1$. It uses GAP's standard linear algebra functions over the field $Z_p$ to construct a $ZG$-resolution for mod $p$
calculations only. The resolution is probably minimal - meaning that the number of generators of $R_n$ equals the rank of $H_n(G,Z_p)$. However, the implementation takes a ``short cut'' and so I don't think minimality can be guaranteed.

The contracting homotopy on the $ZG$-resolution has not yet been implemented!

\>ResolutionSmallFpGroup(G,n)
\>ResolutionSmallFpGroup(G,n,p)

Inputs a small finitely presented group G and an integer n>0. It returns n terms of a ZG-resolution which, in dimensions 1 and 2, corresponds to the given presentation for G. The method returns no contracting homotopy for the resolution.

The function has an optional fourth argument which, when set equal to a prime p, records the fact that the resolution will only be used for mod p calculations. This could speed up subsequent constructions.

This function was written by Irina Kholodna.

\>ResolutionSubgroup(R,K)

Inputs a ZG-resolution for an (infinite) group G and a subgroup K of finite index G:K. It returns a free ZK-resolution whose ZK-rank is G:K times the ZG-rank in each dimension.

If G is finite then the function ResolutionFiniteSubgroup(R,G,K) will probably work better. In particular, resolutions from this function probably won't work with the function EquivariantChainMap(.

This ZK-resolution has more than one generator in dimension 0. So {\sf
PresentationOfResolution()} should not be applied to it!

\>StandardCocycle(R,f,n)
\>StandardCocycle(R,f,n,q)

Inputs a $ZG$-resolution $R$ (with contracting homotopy), a positive integer 
$n$ and an integer vector $f$ representing an n-cocycle $R_n\rightarrow Z_q$
where $G$ acts trivially on $Z_q$. It is assumed $q=0$ unless a value for 
$q$ is entered. The command returns a function $F(g_1, \ldots, g_n)$ which is the standard cocycle  $G_n\rightarrow Z_q$ corresponding to $f$. At present the command is implemented only for n=2 or 3.

\>Syzygy(R,g)

Inputs a $ZG$-resolution $R$ (with contracting homotopy) and a list 
$g = [g[1], \ldots, g[n]]$ of elements in G. It returns a word $w$ in $R_n$. 
The word $w$ is the image of the n-simplex in the standard bar resolution 
corresponding to the n-tuple $g$. This function can be used to construct explicit standard n-cocycles. (Currently implemented only for $n\le 3$.)

\>TensorWithIntegers(X)

Inputs either a $ZG$-resolution $X =R$, or an equivariant chain map 
$X = (F:R\rightarrow S)$. It returns the chain complex or chain map obtained by tensoring with the trivial module of integers (characteristic 0).

\>TensorWithIntegersModP(X,p)

Inputs either a $ZG$-resolution $X=R$, or an equivariant chain map 
$X = (F:R\rightarrow S)$, and a prime p. It returns the chain complex or chain map obtained by tensoring with the trivial module of integers modulo p.

\>ThirdHomotopyGroupOfSuspensionB(G)

Inputs a finite group G and returns the abelian invariants of the third homotopy group of the suspension SB(G) of the Eilenberg-Mac Lane space  K(G,1). This function should work for reasonably small nilpotent groups or extremely small non-nilpotent groups.

\>TietzeReduction(S,w)

Inputs a set $S$ of words in a free $ZG$-module, and a word $w$ in the module. The function returns a word w' such that $\{S,w'\}$ generates the same abelian group 
as 
$\{S,w\}$. The word $w'$ is possibly shorter (and certainly no longer) than $w$. This function needs to be improved!

\>TorsionGeneratorsAbelianGroup(G)

Inputs an abelian group $G$ and returns a generating set 
$[x_1, \ldots,x_n]$ where no pair of generators have coprime orders.

\>TwistedTensorProduct(R,S,EhomG,GmapE,NhomE,NEhomN,EltsE,Mult,InvE)

Inputs a $ZG$-resolution $R$, a $ZN$-resolution $S$, and other data relating to a short exact sequence $1\rightarrow N\rightarrow E\rightarrow G\rightarrow 1$. 
It uses a perturbation technique of CTC Wall to construct a $ZE$-resolution $F$.
Both $G$ and $N$ could be infinite. The ``length'' of $F$ is equal to the minimum of the ``length''s of $R$ and $S$. The resolution $R$ needs no contracting homotopy if no such homotopy is requied for $F$.

The contracting homotopy on $F$ has not yet been implemented!

\>VectorStabilizer(G,v)

Inputs a permutation group or matrix group G of degree n and a rational vector of degree n. In both cases there is a natural action of G on v and the function returns the group of elements in G that fix v. 
