## `Hap Programming` – An experimental framework for objectifying the data structures of Hap

( development version of <#Include SYSTEM "today.ver"> )
Marc Röder marc.roeder(at)nuigalway.ie

This extension does not change the behaviour of Hap and is fully backwards-compatible. It is not a part of Hap and there is no guarantee that it will at any point be supported by Hap. Use at your own risk.

      Marc Röder, Department of Mathematics, NUI Galway, Irleland

This work was supported by Marie Curie Grant No. MTKD-CT-2006-042685
&copyright; 2007 Marc Röder.

This package is distributed under the terms of the GNU General Public License version 2 or later (at your convenience). See the file LICENSE.txt or http://www.gnu.org/copyleft/gpl.html

Resolutions in Hap

This document is only concerned with the representation of resolutions in Hap. Note that it is not a part of Hap. The framework provided here is just an extension of Hap data types used in HAPcryst and HAPprime.

From now on, let G be a group and \dots \to M_n\to M_{n-1}\to\dots\to M_1\to M_0\to Z be a resolution with free ZG modules M_i.

The elements of the modules M_i can be represented in different ways. This is what makes different representations for resolutions desirable. First, we will look at the standard representation (HapResolutionRep) as it is defined in Hap. After that, we will present another representation for infinite groups. Note that all non-standard representations must be sub-representations of the standard representation to ensure compatibility with Hap.

The Standard Representation HapResolutionRep

For every M_i we fix a basis and number its elements. Furthermore, it is assumed that we have a (partial) enumeration of the group of a resolution. In practice this is done by generating a lookup table on the fly.

In standard representation, the elements of the modules M_k are represented by lists -"words"- of pairs of integers. A letter [i,g] of such a word consists of the number of a basis element i or -i for its additive inverse and a number g representing a group element.

A HapResolution in HapResolutionRep representation is a component object with the components

group
, a group of arbitrary type.
elts
, a (partial) list of (possibly duplicate) elements in G. This list provides the "enumeration" of the group. Note that there are functions in Hap which assume that elts[1] is the identity element of G.
appendToElts(g)
a function that appends the group element g to .elts. This is not documented in Hap 1.8.6 but seems to be required for infinite groups. This requirement might vanish in some later version of Hap [G. Ellis, private communication].
dimension(k)
, a function which returns the ZG-rank of the Module M_k
boundary(k,j)
, a function which returns the image in M_{k-1} of the jth free generator of M_k. Note that negative j are valid as input as well. In this case the additive inverse of the boundary of the jth generator is returned
homotopy(k,[i,g])
a function which returns the image in M_{k+1}, under a contracting homotopy M_k \to M_{k+1}, of the element [[i,g]] in M_k. The value of this might be fail. However, currently (version 1.8.4) some Hap functions assume that homotopy is a function without testing.
properties
, a list of pairs ["name","value"] "name" is a string and value is anything (boolean, number, string...). Every HapResolution (regardless of representation) has to have ["type","resolution"], ["length",length] where length is the length of the resolution and ["characteristic",char]. Currently (Hap 1.8.6), length must not be infinity. The values of these properties can be tested using the Hap function EvaluateProperty(resolution,propertyname).

Note that making HapResolutions immutable will make the .elts component immutable. As this lookup table might change during calculations, we do not recommend using immutable resolutions (in any representation).
The HapLargeGroupResolutionRep Representation

In this sub-representation of the standard representation, the module elements in this resolution are lists of groupring elements. So the lookup table .elts is not used as long as no conversion to standard representation takes place. In addition to the components of a HapResolution, a resolution in large group representation has the following components:

boundary2(resolution,term,gen)
, a function that returns the boundary of the genth generator of the termth module.
groupring
the group ring of the resolution resolution.
dimension2(resolution,term)
a function that returns the dimension of the termth module of the resolution resolution.
The effort of having two versions of boundary and dimension is necessary to keep the structure compatible with the usual Hap resolution.
Accessing and Manipulating Resolutions
Representation-Independent Access Methods

All methods listed below take a HapResolution in any representation. If the other arguments are compatible with the representation of the resolution, the returned value will be in the form defined by this representation. If the other arguments are in a different representation, &GAP;s method selection is used via TryNextMethod() to find an applicable method (a suitable representation).

The idea behind this is that the results of computations have the same form as the input. And as all representations are sub-representations of the HapResolutionRep representation, input which is compatible with the HapResolutionRep representation is always valid.

Every new representation must support the functions of this section.

filter
Finds the sub-representation of HapResolutionRep for which letter is a valid letter of the termth module of resolution. Note that resolution automatically is in some sub-representation of HapResolutionRep.This is mainly meant for debugging.
filter
Finds the sub-representation of HapResolutionRep for which word is a valid word of the termth module of resolution. Note that resolution automatically is in some sub-representation of HapResolutionRep. This is mainly meant for debugging.
positive integer
This returns the position of the group element g in the enumeration of the group of resolution. The NC version does not check if g really is an element of the group of resolution.
boolean
Returns true if the nth element of the group of resolution is known.
group element or fail
Returns nth element of the group of resolution. If the nth element is not known, fail is returned.
positive integer or group element, depending on the type of x and y
If x and y are given in standard representation (i.e. as integers), this returns the position of the product of the group elements represented by the positive integers x and x.

If x and y are given in any other representation, the returned group element will also be represented in this way.
A letter
Multiplies the letter letter with the group element g and returns the result. If resolution is in standard representation, g has to be an integer and letter has to be a pair of integer. If resolution is in any other representation, letter and g can be in a form compatible with that representation or in the standard form (in the latter case, the returned value will also have standard form).
A word
Multiplies the word word with the group element g and returns the result. If resolution is in standard representation, g has to be an integer and word has to be a list of pairs of integers. If resolution is in any other representation, word and g can be in a form compatible with that representation or in the standard form (in the latter case, the returned value will also have standard form).
free ZG word (in the same representation as letter)
Calculates the boundary of the letter (word of length 1) letter of the termth module of resolution.

The returned value is a word of the term-1st module and comes in the same representation as letter.
free ZG word (in the same representation as letter)
Calculates the boundary of the word word of the termth module of resolution.

The returned value is a word of the term-1st module and comes in the same representation as word.
Converting Between Representations

Four methods are provided to convert letters and words from standard representation to any other representation and back again.

letter in the representation of resolution
Converts the letter letter in standard representation to the representation of resolution. The NC version does not check whether letter really is a letter in standard representation.
word in the representation of resolution
Converts the word word in standard representation to the representation of resolution. The NC version does not check whether word is a valid word in standard representation.
letter in standard representation
Converts the letter letter in the representation of resolution to the standard representation. The NC version does not check whether letter is a valid letter of resolution.
word in standard representation
Converts the word word in the representation of resolution to the standard representation. The NC version does not check whether word is a valid word of resolution.
Special Methods for HapResolutionRep

Some methods explicitely require the input to be in the standard representation (HapResolutionRep). Two of these test if a word/letter is really in standard representation, the other ones are non-check versions of the universal methods.

boolean
Checks if letter is an valid letter (word of length 1) in standard representation of the termth module of resolution.
boolean
Check if word is a valid word in large standard representation of the termth module in resolution.
positive integer
Given positive integers x and y, this returns the position of the product of the group elements represented by the positive integers x and x. This assumes that all input is in standard representation and does not check the input.
A letter in standard representation
Multiplies the letter letter with the group element represented by the positive integer g and returns the result. The input is assumed to be in HapResolutionRep and is not checked.
A letter in standard representation
Multiplies the word word with the group element represented by the positive integer g and returns the result. The input is assumed to be in HapResolutionRep and is not checked.
free ZG word in standard representation
Calculates the boundary of the letter (word of length 1) letter of the termth module of resolution. The input is assumed to be in standard representation and not checked.
free ZG word in standard representation
Calculates the boundary of the word word of the termth module of resolution. The input is assumed to be in standard representation and not checked.
<#Include SYSTEM "./resolutionAccess_GroupRing.xml">

Contracting Homotopies
<#Include SYSTEM "./contraction.xml">