<!DOCTYPE Book SYSTEM "gapdoc.dtd"> <Book Name="GBNP"> <TitlePage>
<Title>Documentation on the <Package>GBNP</Package> package</Title>
<Version>Version $VERSION</Version> 
<Author>Arjeh M. Cohen <Email>A.M.Cohen@tue.nl</Email></Author>
<Author>Jan Willem Knopper <Email>J.W.Knopper@tue.nl</Email></Author>
<Date>$DATE</Date> 
<Address>TU/e,<Br/> POB
513, 5600 MB Eindhoven, the Netherlands </Address> <Abstract> We provide
algorithms, written in the <Package>GAP</Package> 4 programming language, for
computing Gröbner bases of non-commutative polynomials, and some variations,
such as a weighted and truncated version and a tracing facility. In addition,
there are algorithms for analyzing the quotient 
of a non-commutative polynomial algebra by
a 2-sided ideal generated by a set of polynomials whose Gröbner basis has been
determined and for computing quotient modules of free modules over quotient
algebras.  
<P/> The notion of algorithm is interpreted loosely: in general one
cannot expect a non-commutative Gröbner basis algorithm to terminate, 
as it would imply solvability of
the word problem for finitely presented (semi)groups. <P/>
This documentation gives a short description of the mathematical content,
explains the functions of the package, and provides more than twenty worked
out examples.
</Abstract>

<Acknowledgements>
<List>
<Item>The package is based on an earlier version by Rosane Ushirobira.</Item>
<Item>The bulk of the package is written by 
Arjeh M. Cohen and Dié A.H. Gijsbers.</Item>
<Item>The theory is mainly taken from literature by Teo Mora <Cite Key="TCS::Mora1994:131"/> and
	Edward L. Green <Cite Key="Green1997"/>.</Item>
<Item>From Version 0.8.3 on the package has three additional files
	(<File>fincheck.g</File>, <File>tree.g</File> <File>graphs.g</File>)
	with routines for finding the Hilbert function and testing
	finite dimensionality when given a Gröbner basis by Chris Krook <Cite
		Key="Krook2003"/>, based on work by Victor Ufnarovski <Cite
		Key="MR91d:16053"/>.</Item>
<Item>From Version 0.9 on the package is enriched with support for fields implemented
in GAP and
additional prefix rules for quotient modules, 
as well as some speed improvements by Jan
	Willem Knopper.
Knopper has also formatted the documentation in GAPDoc 
<Cite Key="GAPDoc"/>.
</Item>
<Item>From Version 1.0 on the package is extended with NMO (for Noncommutative
Monomial Orderings) by Randall Cone.
This enables the GBNP user
to choose a wider selection of monomial orderings than
the standard one built into GBNP itself.
Documentation on NMO can be found in the NMO manual
<Cite Key="NMODoc"/>.
</Item>
</List>
&nbsp; <!-- needed to prevent LaTeX from erroring -->
</Acknowledgements></TitlePage>
<TableOfContents/>
<Body>
<Chapter><Heading>Introduction</Heading>
This package, named GBNP for Gröbner Bases for Non-commutative Polynomials,
is intended for computing in (associative) non-commutative algebras
with a finite presentation. Starting from a free algebra <M>A</M>
on a finite number
of generating variables, the reader can specify a finite set <M>G</M> of 
polynomials in these variables,
in order to study the quotient algebra of <M>A</M> by
the (2-sided) ideal of <M>A</M> generated by <M>G</M>.
<P/>

This documentation gives a short description of the mathematical content in
Chapter <Ref Chap="Description"/>, explains the functions of the package in
Chapter <Ref Chap="Functions"/>, and provides more than twenty four worked out
examples in Appendix <Ref Chap="Examples"/>.
It is available as an HTML document at
<URL>$URLBASE/</URL>
and as an pdf document at
<URL>$URLBASE/manual.pdf</URL>.


<Section><Heading>Installation</Heading>	
To install GBNP, first download it from 
<URL>$URLBASE/GBNP-$VERSION.tar.gz</URL>, then unpack
<F>GBNP-$VERSION.tar.gz</F> in the <C>pkg</C> subdirectory of
your <Package>GAP</Package> installation (or in the <C>pkg</C> subdirectory of
any other <Package>GAP</Package> root directory, for example one added with the
<C>-l</C> argument) with the following command: 
<Code>tar -xvzf GBNP-$VERSION.tar.gz</Code>.
<P/>
GBNP is then loaded with the GAP command
<Listing>
gap> LoadPackage( "GBNP" ); 
</Listing>
<P/>
Those who want to download this documentation can find it at
<URL>$URLBASE/GBNPdoc-$VERSION.tar.gz</URL>
and extract it with 
<Code>tar -xvzf GBNPdoc-$VERSION.tar.gz</Code>.
It is also included in the package.
</Section>

<Section Label="intro"><Heading>Using the package</Heading>	
If you wish to compute a Gröbner basis, create a list of NPs
(non-commutative polynomials in NP format), as described in
Section <Ref Sect="NP"/>.  This can be
done either directly or by use of the transition functions described in Section
<Ref Sect="TransitionFunctions"/>. 
To run the standard algorithm use the functions from Section <Ref
	Sect="grobner"/>. With these functions, you can try and find a Gröbner
basis. The word try is included
because
the algorithm for computing Gröbner bases is not guaranteed to terminate.
Printing issues for polynomials in NP format are discussed in Section
<Ref Sect="printing"/>. 

If the Gröbner basis is found and the dimension of 
the quotient algebra <M>Q</M> (see Section
<Ref Sect="QuotientAlgs"/>)
is finite,
you can find a basis of monomials for 
<M>Q</M> with the
functions in Section <Ref Sect="QA"/>.  For a 
more advanced analysis of <M>Q</M>,
such as a proof of finite or infinite dimensionality, or for determining its
growth or its partial Hilbert series, use the functions from Section <Ref
	Sect="finiteness"/> <!-- <File>fincheck.g</File> -->.
<P/>
There are three variants of the Gröbner basis algorithm, the truncated 
version, the trace version, and the module version.
In the (weighted) homogeneous case (described in Section <Ref
Sect="trunc"/>), the truncated version, given by
the functions described in Section <Ref Sect="truncfun"/>,
<!-- in <File>trunc.g</File> -->
computes  the part of a Gröbner basis up to an indicated weight.
The trace version
(described in Section <Ref Sect="trace"/>),
given by the functions described in Section <Ref
	Sect="tracefun"/>, <!-- <File>trace.g</File> -->
computes an expression of the polynomials of
the Gröbner basis found in terms of the original generators.
The module version
(described in Sections <Ref Sect="NPM"/>, <Ref Sect="PrefixRels"/>,
and  <Ref Sect="GBR"/>),
given by the functions described in Section <Ref
	Sect="NPMs"/>, <!-- <File>trace.g</File> -->
computes a Gröbner basis for a submodule of a free <M>Q</M>-module of finite 
rank.

<P/>
Read the example files in Chapter <Ref Chap="Examples"/> for inspiration.
The source of the files can be perused for auxiliary
functions, which are often used in the main functions
but not deemed necessary for a first time user.
</Section>

<Section><Heading>Further documentation</Heading>
	The reports <Cite Key="CohenGijsbersEtAl2007"/>, <Cite
		Key="Krook2003"/>, and  <Cite	Key="Knopper2004"/>
 can be downloaded from the web at these
	addresses:
	<P/>
	The report <Q>Non-commutative polynomial computations</Q>, by Arjeh
	M. Cohen (with support of Dié Gijsbers, Jan Willem Knopper, and Chris Krook)
can be downloaded from
	<URL>$URLBASE/gbnp.pdf</URL>.
	<P/>
	The report <Q>Dimensionality of quotient algebras</Q>, by Chris
	Krook can be downloaded from
	<URL>$URLBASE/dqa.pdf</URL>.
	<P/>
	The report <Q>GBNP and vector enumeration</Q>, by Jan Willem Knopper
         can be downloaded from
	<URL>$URLBASE/knopper.pdf</URL>.

</Section>
</Chapter>
<Chapter Label="Description"><Heading>Description</Heading>

<Section Label="NP"><Heading>Non-commutative Polynomials (NPs)</Heading>
	The main datatype of the GBNP package is a list of non-commutative
	polynomials (NPs). 
	The data type for a <Emph>non-commutative polynomial</Emph>,
referred to as its NP format,
 is a list of two lists:
<List>
	<Item>The first list is a list <C>m</C> of monomials.</Item>
	<Item>The second list is a list <C>c</C> of coefficients of these
		monomials.</Item>
</List>
The two lists have the same length. The polynomial represented
by the ordered pair <C>[m,c]</C> is 
<M>\sum_i c_i m_i</M>.
<P/>
A monomial is a list of positive integers. They are interpreted as the
indices of the variables.  So, if <C>k = [1,2,3,2,1]</C> and the variables are
<M>x</M>,<M>y</M>,<M>z</M> (in this order), then <C>k</C> represents the
monomial <M>xyzyx</M>.
By the way, the name of the variables has no meaning. There are various ways to
print these but the default is 
<M>a</M>,<M>b</M>,<M>c</M>,<M>\ldots</M> (see
below).
<P/>
The zero polynomial is represented by <C>[[],[]]</C>.
The polynomial 1 is represented by <C>[[[]],[1]]</C>.
<P/>
The algorithms work for the algebra
<M>\mathbb F\langle\langle x_1,x_2,\ldots,x_t\rangle\rangle</M> of
non-commutative polynomials
in <A>t</A> variables over the field <M>\mathbb F</M>. 
Accordingly, the list <C>c</C> should contain elements of 
<M>\mathbb F</M>. It is not always easy to recover 
<M>\mathbb F</M> from the list <C>c</C>. The GAP functions
<C>One</C> and <C>Zero</C> can be of some help.
<!---JWK comments on this??? -->
<P/>
In order to facilitate viewing the polynomials, we provide the function
<Ref Func="PrintNP" Style="Text"/>. For instance
<Listing>PrintNP([[[1,2],[2,1]],[3,-1]]);</Listing> yields
<Listing>3ab - ba</Listing> Indeed, we have the names: <C>a</C>, <C>b</C>, <C>c</C>,
<M>\ldots</M>  for <M>x_1</M>, <M>x_2</M>, <M>x_3</M>, <M>\ldots</M>,
except that everything beyond <M>l</M> (the 12-th letter) is called <M>x</M>.
This can be easily changed by calling the function <C>GBNP.ConfigPrint</C>,
which can be found in Section <Ref Sect="printing"/><!-- the file
<File>printing.g</File> -->.
<P/>
The function <Ref Func="PrintNPList" Style="Text"/> is available for printing a list of NPs
(=non-commutative polynomials).
<P/>
In order to facilitate testing whether two data structures represent
the same NP, we use the convention that polynomials are
<Q>clean</Q>. This means that they look as if they are output of the
function <Ref Func="CleanNP" Style="Text"/>.  In other words:
<List>
	<Item>each monomial occurs at most once in the list of monomials,</Item>
	<Item>no monomials occur whose coefficients are zero,</Item>
	<Item>the monomials are ordered (total degree first, then
		lexicographically) from big to small.</Item>
</List>
An advantage of the ordering is that the leading monomial of an NP <C>p</C> is
just <C>p[1][1]</C> and that its leading coefficient is <C>p[2][1]</C>.
Users who want to work with other orderings can use the functions
defined in the NMO extension <Cite Key="NMODoc"/> to GBNP.
</Section>

<Section Label="NPM"><Heading>Non-commutative Polynomials for Modules (NPMs)</Heading>
In Section <Ref Sect="NP"/> the NP format for elements of a free algebra
<M>A</M> 
of non-commutative polynomials in a fixed number of variables is described.
This format can be adjusted slightly to allow the use of a free right module
<M>A^n</M> of finite rank <M>n</M> over <M>A</M>. 
The internal format of an element of the
module is similar to that of a non-commutative polynomial. 
The only change is that each monomial will start with
a negative number. The absolute value of this number is the index of
the standard basis vector of the free module.
<P/>
For example in the free 
<M>\mathbb F\langle\langle x_1, x_2,\ldots, x_t\rangle\rangle</M>-module 
of rank 3,
the expression 
<C>[[[-1]],[1]]</C> 
	represents <M>[1,0,0]</M> and
<C>[[[-1,1,2],[-1,2,1],[-3,2,2,2]],[6,-7,9]]</C>
represents
<M>[6x_1x_2-7x_2x_1,0,9x_2^3]</M>.
The zero vector is the represented in the same way as its NP format counterpart
in <Ref Sect="NP"/> and the only one without a negative entry:
<C>[[],[]]</C>.
We refer to this format as the NPM format.
<P/>
Elements of modules are printed as vectors. 
See
Section <Ref Sect="NPMs"/>
on how to use modules.
Examples <Ref Sect="Example20"/>, <Ref Sect="Example21"/>,
and <Ref Sect="Example04"/>
are also recommended.

</Section>

<Section><Heading>Core functions</Heading> 

The core function is <Ref Func="SGrobner" Style="Text"/> (which is short for
Strong Gröbner, as we use the Strong Normal Form, discussed in Section <Ref
Func="StrongNormalFormNPM" Style="Text"/>, most of the time).
It takes a list of NPs in a free algebra <M>A</M> and
prepares two lists for treatment in a loop:
<List>
	<Item> First the list itself, called <C>G</C>. Before entering the
		loop, <C>G</C> is cleaned, ordered, and its elements are made
		monic, that is, multiplied by a scalar so that the leading
		coefficient becomes one. The ordering is done by comparison
		of leading monomials. The ordering on leading monomials is
		length lexicographic. For other orderings, the functions of
		the NMO extension can be used; see <Cite Key="NMODoc"/>.
        </Item>
	<Item>Second the list of all normal forms with respect to <C>G</C> of S-polynomials
		of elements of <C>G</C>. This list is called <C>D</C>.
For a Gröbner basis,
the S-polynomials of polynomials in <C>D</C> (possibly with an
element of <C>G</C>) need to be computed. 
If <C>D</C> is empty then <C>G</C> is a
Gröbner basis.</Item>
</List>
Then, the function calls the routine <C>GBNP.SGrobnerLoop</C> on the arguments
<C>G</C>, <C>D</C> which are changed in an attempt to modify <C>G</C> while
still preserving the following two properties.
<Enum>
	<Item><C>G</C> generates the same two-sided ideal <M>I</M> in <M>A</M>
 as before.</Item>
	<Item><C>D</C> contains all normal forms with respect to <C>G</C> of S-polynomials
		of elements from <C>G</C> that need to reduce to zero for the
		basis to be a Gröbner basis.<!-- XXX does this need rephrasing
		? --></Item> </Enum>
The importance of this feature is that, in case of huge computations,
the user may store <C>G</C> and <C>D</C> at almost any time and resume the
computation by reloading <C>G</C> and <C>D</C> and calling the loop function
<C>GBNP.SGrobnerLoop</C> whenever convenient. The only technical detail to
handle is that the last element of the list <C>G</C> should be copied into the
<C>D</C> list.<!-- XXX This is not still true, 'almost any time' is the
problem. It should be possible to make a function which restores G and D at
all time. This is on the todo listXXX -->
The loop itself performs a step towards making <C>G</C> more like a 
Gröbner basis of <M>I</M>. As in the commutative case, the progress can be
indicated by use of an ordering on the set of leading monomials of the
elements of <C>G</C>. 
<P/>

In contrast to the commutative case, however, this ordering is not well
founded, and there is no a priori guarantee that the loop will be exited after
a finite number of iterations.  The loop ends when the list <C>D</C> is empty,
in which case the work is essentially done: after some internal cleaning and a
bit of further rewriting, the computation is over.

<P/>
There is also a <Ref Func="Grobner" Style="Text"/> function. It uses (at some places) the Normal
Form instead of the Strong Normal Form algorithm. In most of our
applications, this usually led to slower performance, so we are not
very keen to use it.
<P/>

In many of our own applications, the full polynomial ring modulo the two-sided
ideal <M>I</M> generated by <C>G</C> is a finite-dimensional quotient
algebra. In such cases, one would like to know the dimension (whence the
function <Ref Func="DimQA" Style="Text"/>, QA for Quotient Algebra), find a
basis (whence the function <Ref Func="BaseQA" Style="Text"/>), or just the
monomials up to a certain degree that are not divisible by a leading term of
<C>G</C> (whence the function <C>GBNP.NondivMons</C>).  Actually by use of
<Ref Func="MulQA" Style="Text"/>, you can even multiply elements of the
quotient algebra.  In case it is unknown whether the quotient algebra is
finite or infinite, one can use the functions <Ref Func="FinCheckQA"
Style="Text"/> and <Ref Func="DetermineGrowthQA" Style="Text"/>. 
When the quotient algebra is
infinite dimensional you may want to determine its partial Hilbert
Series. This can be done with the function <Ref Func="HilbertSeriesQA"
Style="Text"/>.  </Section>

<Section><Heading>About the implementation</Heading>
Rather than storing all obstructions, the Gröbner basis algorithm computes the
(Strong) Normal Form of obstructions from <C>G</C> and puts them into <C>D</C>
whenever nonzero. At the beginning of the loop, we take the first element of
the
<C>D</C> list and prepare it for addition to <C>G</C>.  We are then concerned with
two goals: 
<Enum>
	<Item>to restore the invariant properties,</Item>
	<Item>to clean up G (that is, reduce it to a more succinct, shorter
		set).</Item>
</Enum>
This is mainly done by means of additional S-polynomial and Normal Form
computations.

<P/> As for data management, we have chosen to work with lists in situ, that
is, not to copy the list but rather perform all operations on one and the same
list. To this end we use operations like <C>RemoveElmList</C> and <C>Add</C>,
see <Ref BookName="Reference" Label="Add"/>. The idea here is to economize on
space for large computations.  We do not use in situ operations everywhere,
but have concentrated on the potentially biggest lists: <C>G</C> and <C>D</C>.
<P/>


For checking whether a monomial can be reduced, an internal
tree structure is used.  </Section> 

<Section Label="trace"><Heading>Tracing
variant</Heading> When computing with small examples, it may be handy to
provide the elements of the Gröbner basis with a way of expressing them as
elements in <C>I</C>, that is, as combinations of elements of the input. This
can be done, not only for elements of <C>G</C>, but for any element, by the
functions in the file <F>trace.g</F>. This file calls the file
<F>nparith.g</F> for arithmetic keeping track of the expressions of
polynomials as combinations of elements from the original basis.  With respect
to a given input basis <C>B</C>, a polynomial <C>p</C> in the traced version
is a record, called the traced polynomial, with two fields. 

One field, denoted <C>p.pol</C>, is the usual polynomial in
NP format. The other, denoted <C>p.trace</C>, is a list of elements indexed by
<C>B</C>. Each element of <C>p.trace</C> is a list whose elements are
four-tuples <C>[ml,i,mr,c]</C> where <C>ml</C> and <C>mr</C> are monomials,
<C>i</C> is an index of an element of <C>B</C> and <C>c</C> is a scalar. The
interpretation of this data structure is that <C>p.pol</C> can be written as
the sum over all four-tuples <C>[ml,i,mr,c]</C> of <M>c*ml*B_i*mr</M>.
Functions for printing these expressions in a human understandable way are
described in Section <Ref Sect="tracefun"/>.
</Section>

<Section Label="trunc"><Heading>Truncation variant</Heading> For computations
with large and/or infinite examples, it may be convenient to truncate
everything above a certain degree. In fact, we encountered various examples
where the polynomials are (weighted) homogeneous and then it makes perfect
sense to truncate the polynomials, that is, to disregard everything above a
certain degree. For then the Grobner basis, if it exists, will be also be
homogeneous and the part consisting of all of its polynomials of degree less
than a given degree <M>d</M> is equal to the Grobner basis of the join of the
original list of polynomials with all monomials of degree <M>d+1</M>.  Here an
NP polynomial in <M>n</M> variables is called homogeneous of degree <M>d</M>
with respect to <M>v</M>, a vector with non-negative integers of length
<M>n</M>, if, for each of its monomials <M>[t_1,...,t_k]</M>, the sum over all
<M>v_{t_i}</M> is equal to <M>d</M>.  The most classical choice for <M>v</M>
is the all-one vector in which case one often speaks of homogeneous without
mentioning the all-one vector.
If two polynomials are homogeneous with respect
to <M>v</M>, then so are their S-polynomials.
If <M>K</M> is a list of homogeneous polynomials with respect to
<M>v</M>, then the normal form with respect to <M>K</M>
of any homogeneous polynomial of degree <M>d</M>
with respect
to
<M>v</M> is again homogeneous 
of degree <M>d</M> with respect to <M>v</M>. 
In particular, the Gröbner basis of a list of 
polynomials that are homogeneous with respect to
<M>v</M>, consists of homogeneous polynomials, and those input polynomials
contributing to polynomials in the Gröbner basis of degree at most <M>d</M>
have degree at most <M>d</M> themselves. These facts
enable the computation of the truncated Gröbner basis.

The functions of this variant can be found in Section <Ref Sect="truncfun"/>.
</Section>

<Section Label="PrefixRels"><Heading>Module variant</Heading>
<!--Gröbner basis record, which is explained in <Ref Sect="GBR"/>.-->

Suppose we are given a finite set <M>G</M> of polynomials in
a free non-commutative algebra <M>A</M> generated
by, say <M>t</M> indeterminates,
and a positive integer <M>s</M>.
Denote by <M>I</M> the two-sided ideal of <M>A</M> generated by <M>G</M>.
We can work with
the free right <M>A/I</M> module <M>(A/I)^s</M>. See Section <Ref Sect="NPM"/>
on how to represent vectors of <M>(A/I)^s</M> by elements of the free module
<M>A^s</M>.  Given a subset <M>W</M> of <M>A^s</M>, whose elements are called
prefix relations, let <M>W'</M> be the submodule generated by the image of
<M>W</M> in <M>(A/I)^s</M>.  The function <Ref Func="SGrobnerModule"
Style="Text"/> is meant to determine the quotient module
<M>(A/I)^s/W'</M>. If the algorithm terminates, it delivers a 
Gröbner basis for <M>I</M> as well as a suitable set of generators
for <M>W'</M>, with Gröbner like properties.
This implies that <Ref
Func="StrongNormalFormNPM" Style="Text"/>, a strong normal form computation,
can be used
to find the canonical representative in <M>A^s</M> of an element in
<M>(A/I)^s/W'</M>.  Theoretic details can be found in 
<Cite Key="CohenGijsbersEtAl2007"/>.
If <M>(A/I)^s/W'</M> is a finite-dimensional vector space over the
coefficient field of <M>A</M>, then a basis can be found by use of
<Ref Func="BaseQM"
Style="Text"/> and its dimension can be computed by use of
<Ref Func="DimQM"
Style="Text"/>.

</Section>

<Section Label="GBR"><Heading>Gröbner basis records</Heading>
	The function <Ref Func="SGrobnerModule" Style="Text"/> calculates a
	Gröbner basis consisting of some two-sided relations in the algebra and
	some prefix or module relations in the vector space. These are returned
	in a record <C>GBR</C>. The two-sided relations can be found under the
	name <C>GBR.ts</C> and the prefix relations under the name <C>GBR.p</C>.
	Some other information is stored in this record as well.
	<P/>
The prefix conditions are in NPM format (see <Ref
		Sect="NPM"/>) and the two-sided relations are in NP format.
</Section>

<Section Label="QuotientAlgs"><Heading>Quotient algebras</Heading> Once a Gröbner basis of a list
<M>G</M> of polynomials in NP format, defining elements of a free algebra
<M>A</M>, is computed, the quotient algebra <M>QA</M> of <M>A</M> by the
two-sided ideal generated by <M>G</M> (or, which amounts to the same, the
Gröbner basis) can be analyzed.  A number of functions are available to
determine whether <M>QA</M> is finite dimensional or not.
<P/>
Elements of
<M>QA</M> are represented by elements of <M>A</M>. Two elements are equal if
and only if their strong normal forms coincide; see
<Ref Func="StrongNormalFormNP" Style="Text"/>.
The multiplication is take care of by <Ref Func="MulQA" Style="Text"/>,
which is little more than the strong normal form of the product of two
polynomials in NP format representing elements of <M>QA</M>.

<P/>
If  <M>QA</M> is finite dimensional, a basis of it over the field
can be found by <Ref Func="BaseQA" Style="Text"/>.
The size of the base, in other words, the dimension of
<M>QA</M>, can be computed with <Ref Func="DimQA" Style="Text"/>.
Right multiplication by an element of
<M>QA</M> is a linear transformation. The matrix of this linear
transformation with respect to the base,
in case the element belongs to the base, can be computed by
<Ref Func="MatrixQA" Style="Text"/> or, for all basis elements,
<Ref Func="MatricesQA" Style="Text"/>.

<P/> A list of leading terms of the Gröbner basis <M>G</M> can be constructed
with <Ref Func="LMonsNP" Style="Text"/>.  The dimension of <M>QA</M> only
depends on this list and is computationally easier to work with than <M>G</M>.
Most functions designed to analyze dimensionality work with a monomial ideal
generated by a strong Gröbner basis, which in this case means that no element
divides any other element.

<P/>
The function <Ref Func="FinCheckQA" Style="Text"/> determines whether 
<M>QA</M> is finite or infinite dimensional. More generally, the growth
of <M>QA</M> can be determined by means of the function <Ref
Func="DetermineGrowthQA" Style="Text"/>, which either returns the information 
that <M>QA</M>
is finite dimensional, or 
that <M>QA</M> has polynomial growth, in which case it
gives bounds for the degree of polynomial growth, or that <M>QA</M>
has exponential growth. Finally, with the function <Ref Func="HilbertSeriesQA"
Style="Text"/> one can compute coefficients of the Hilbert series.  

<P/> The purpose of the functions <Ref Func="FinCheckQA" Style="Text"/>
and <Ref
Func="DetermineGrowthQA" Style="Text"/> are closely related. The former is
faster, while the latter provides more information, as
illustrated from the following table.  

<P/> 
<Table Align="|l|l|l|"> 
<HorLine/> 
<Row>
   <Item>&nbsp;</Item> 
   <Item><C>FinCheckQA</C></Item>
  <Item><C>DetermineGrowthQA</C></Item>  
</Row> 
<HorLine/> 
<Row>
  <Item>finite</Item> 
  <Item><C>true</C></Item>
  <Item><C>0</C></Item> 
</Row> 
<Row> 
   <Item>polynomial growth</Item>
   <Item><C>false</C></Item> 
   <Item><C>d</C> or <C>[d1,d2]</C></Item>  
</Row> 
<Row><Item>exponential growth</Item> 
     <Item><C>false</C></Item> 
     <Item><C>"exponential growth"</C></Item> 
</Row><HorLine/> 
<Caption>dimensionality functions; <C>d</C> stands for degree,
<C>[d1,d2]</C> for an interval containing the degree</Caption> </Table> The function <Ref
Func="DetermineGrowthQA" Style="Text"/> may find the exact
degree of polynomial growth (if at hand). If this is the case, that degree
is returned. It may also happen that only an
interval <C>[d1,d2]</C> is returned in which the dimension
lies. To force an exact answer, its third argument should be <C>true</C>. <P/>

With the function <Ref Func="PreprocessAnalysisQA" Style="Text"/>, the computations done
by these 3 functions can be sped up. Note however that by applying
preprocessing of the data, the set of monomials in the ideal basis is changed
and corresponds no longer to the same quotient algebra (but to a quotient
algebra with the same growth).  

</Section>
</Chapter>



<Chapter Label="Functions">
	<Heading>Functions</Heading>
	<Section Label="TransitionFunctions"><Heading>Converting polynomials
			into different formats</Heading>
		<#Include Label="GP2NP">
		<#Include Label="GP2NPList">   
		<#Include Label="NP2GP">
		<#Include Label="NP2GPList">
	</Section>
	<Section Label="printing"><Heading>Printing polynomials in NP format</Heading>
		<#Include Label="PrintNP">
		<#Include Label="GBNP.ConfigPrint">
		<#Include Label="PrintNPList">
	</Section>
	<Section><Heading>Calculating with polynomials in NP format</Heading>
		<#Include Label="NumAlgGensNP">
		<#Include Label="NumAlgGensNPList">
		<#Include Label="NumModGensNP">
		<#Include Label="NumModGensNPList">
		<#Include Label="AddNP">
		<#Include Label="BimulNP">
		<#Include Label="CleanNP">
		<#Include Label="GtNP">
		<#Include Label="LtNP">
		<#Include Label="LMonsNP"> <!-- here ?? -->
		<#Include Label="MkMonicNP">
		<#Include Label="MulNP">
	</Section>
	<Section Label="grobner"><Heading>Gröbner functions, standard variant</Heading>
		<#Include Label="Grobner"> <!-- remove ?? -->
		<#Include Label="SGrobner">
		<#Include Label="IsGrobnerBasis">
		<#Include Label="IsStrongGrobnerBasis">
		<#Include Label="IsGrobnerPair">
		<#Include Label="MakeGrobnerPair">
	</Section>
	<Section Label="QA"><Heading>Finite-dimensional quotient
		algebras</Heading>
		<#Include Label="BaseQA">
		<#Include Label="DimQA">
		<#Include Label="MatrixQA">
<!--		<#Include Label="MatrixQAC"> -->
		<#Include Label="MatricesQA">
<!--		<#Include Label="MatricesQAC"> -->
		<#Include Label="MulQA">
		<#Include Label="StrongNormalFormNP">
	</Section>
	<Section Label="finiteness"><Heading>Finiteness and Hilbert series</Heading>

		<#Include Label="DetermineGrowthQA">
<!--		<#Include Label="DetermineGrowthObs"> -->
		<#Include Label="FinCheckQA">
		<!--<#Include Label="GraphOfNormalWords">
		<#Include Label="GraphOfChains">
		<#Include Label="HilbertSeriesG">-->
		<#Include Label="HilbertSeriesQA">
		<#Include Label="PreprocessAnalysisQA">
	</Section>
	<Section Label="tracefun"><Heading>Functions of the
			trace variant</Heading>
		<#Include Label="EvalTrace">
		<#Include Label="PrintTraceList">
		<#Include Label="PrintTracePol">
		<#Include Label="PrintNPListTrace">
		<#Include Label="SGrobnerTrace">
		<#Include Label="StrongNormalFormTraceDiff">
	</Section>

	<Section Label="truncfun"><Heading>Functions of the truncated variant</Heading>
		<Subsection><Heading>Examples</Heading>
			More about these functions can be found in <Ref
				Sect="Example11"/>
		</Subsection>
		<#Include Label="SGrobnerTrunc">
		<#Include Label="CheckHomogeneousNPs">
		<#Include Label="BaseQATrunc">
		<#Include Label="DimsQATrunc">
		<#Include Label="FreqsQATrunc">
	</Section>

	<Section Label="NPMs"><Heading>Functions of the module variant</Heading>
		<#Include Label="SGrobnerModule">
		<#Include Label="BaseQM">
		<#Include Label="DimQM">
		<#Include Label="MulQM">
		<#Include Label="StrongNormalFormNPM">
	</Section>
</Chapter> 



<Chapter Label="Info"><Heading>Info Level</Heading>

<Section><Heading>Introduction</Heading>
Many functions of the GBNP package can produce additional output. Such
output might be useful for long calculations, to see where the calculation is
or to gain more information about the calculation itself. 
<P/>
<Package>GAP</Package> provides the tools to be able to tune the output of the
functions. All of the functions of this package use the <C>InfoClass</C> <Ref
	InfoClass="InfoGBNP" Style="Text"/>
and some use
the <C>InfoClass</C> <Ref
	InfoClass="InfoGBNPTime" Style="Text"/>. As usual with GAP when
this is left at 0, the functions will hardly print
 additional information. It can be set
to 1 or 2 with <C>SetInfoLevel</C> (more about this function can be found at <Ref BookName="Reference" Label="SetInfoLevel"/>). A brief
explanation about each infolevel will be given in the next sections.
</Section>

<Section><Heading>InfoGBNP</Heading>
<ManSection>
	<InfoClass Name="InfoGBNP" Comm="InfoClass for this package"/>
	<Description>
		The <C>InfoClass</C> for this package is used in almost all
		functions. To change this level to 1 (some information) or 2
		(more information, also information from calculation loops) use
		the function <C>SetInfoLevel</C>.
	</Description>
</ManSection>
<Subsection><Heading>What will be printed at level 0</Heading>
	At level 0 no information is printed beyond what functions themselves 
        command to be printed.
	These include functions like <Ref Func="PrintNP" Style="Text"/>, <Ref
		Func="PrintNPList" Style="Text"/>, 
	<Ref Func="PrintTraceList" Style="Text"/> and
	<Ref Func="PrintNPListTrace" Style="Text"/>, but it also includes the
	function <Ref Func="DetermineGrowthQA" Style="Text"/>, which only prints
	one or two lines and <Ref Func="DimsQATrunc" Style="Text"/> which
	produces information about a truncated Gröbner basis.
</Subsection>
<Subsection><Heading>What will be printed at level 1</Heading>
	The infolevel can be set to 1 with the following command:
<Listing>
SetInfoLevel(InfoGBNP,1);
</Listing>
At level 1 a large set of functions will produce a bit of output. Most of this
information reports on the phase of the algorithm the calculations
are in or some simple statistics about the input or output.
</Subsection>
<Subsection><Heading>What will be printed at level 2</Heading>
	The infolevel can be set to 2 with the following command.
<Listing>
SetInfoLevel(InfoGBNP,2);
</Listing>
At level 2 a large set of functions will produce a lot of output. This mostly 
concerns
information on loops in the calculations. Timing information will be
printed as well.
</Subsection>
<!--Subsection><Heading>What will be printed at level 3</Heading>
	The infolevel can be set to 3 with the following command:
<Listing>
SetInfoLevel(InfoGBNP,3);
</Listing>
At the moment there is nothing more that will be printed at level 3, but it is
possible that this level (and possibly higher levels) will be used for debug
purposes in the future.
</Subsection-->
</Section>

<Section><Heading>InfoGBNPTime</Heading>
<ManSection>
	<InfoClass Name="InfoGBNPTime" Comm="InfoClass for timing information"/>
	<Description>
		The <C>InfoClass</C> for timing is used in producing
		information about the runtime of the algorithm in certain
		possibly lengthy calculations.
		<P/>
		To change this level to 1 (Gröbner functions give information)
		or 2 (more information, also information from other functions,
		which might not always take a long time and from inside loops)
		use the function <C>SetInfoLevel</C>. 
	</Description>
</ManSection>
<Subsection><Heading>What will be printed at level 0</Heading>
	No timing information will be printed at level 0. This can be desirable
	for small examples or when producing test output, for use with
	<C>ReadTest</C>.
</Subsection>
<Subsection><Heading>What will be printed at level 1</Heading>
	The infolevel can be set to 1 with the following command:
<Listing>
SetInfoLevel(InfoGBNPTime,1);
</Listing>
	At level one there will be time information printed by the functions
	from different variants of the Gröbner basis algorithm: 
	<Ref Func="Grobner" Style="Text"/>, <Ref Func="SGrobner" Style="Text"/>,
	<Ref Func="SGrobnerTrace" Style="Text"/>, and <Ref Func="SGrobnerTrunc"
		Style="Text"/>.
</Subsection>
<Subsection><Heading>What will be printed at level 2</Heading>
	The infolevel can be set to 2 with the following command:
<Listing>
SetInfoLevel(InfoGBNPTime,2);
</Listing>
	At level two there will also be some information printed from a loop
	from within <Ref Func="SGrobnerTrunc" Style="Text"/>.
<!-- and certain other
	functions will start to produce timing output. At the moment the only
	function that does this is <Ref Func="DimQA" Style="Text"/>.
-->
</Subsection>
<!--Subsection><Heading>What will be printed at level 3</Heading>
	The infolevel can be set to 3 with the following command:
<Listing>
SetInfoLevel(InfoGBNPTime,3);
</Listing>
	At the moment no extra timing information will be printed at level 3 or
	higher. 
</Subsection-->
</Section>
</Chapter>
</Body>

<Appendix Label="Examples"><Heading>Examples</Heading>
<Section Label="ExamplesIntroduction"><Heading>Introduction</Heading>
In this chapter all available commented examples can be found.
Those without comments are in the directory
		<F>gbnp/examples</F>.
		<#Include Label="timing">
<List>
<Item><Ref Sect="Example01"/> <Ref Sect="Example01"  Style="Text"/></Item>
<Item><Ref Sect="Example02"/> <Ref Sect="Example02"  Style="Text"/></Item>
<Item><Ref Sect="Example11"/> <Ref Sect="Example11"  Style="Text"/></Item>
<Item><Ref Sect="Example03"/> <Ref Sect="Example03"  Style="Text"/></Item>
<Item><Ref Sect="Example05"/> <Ref Sect="Example05"  Style="Text"/></Item>
<Item><Ref Sect="Example06"/> <Ref Sect="Example06"  Style="Text"/></Item>
<Item><Ref Sect="Example07"/> <Ref Sect="Example07"  Style="Text"/></Item>
<Item><Ref Sect="Example08"/> <Ref Sect="Example08"  Style="Text"/></Item>
<Item><Ref Sect="Example10"/> <Ref Sect="Example10"  Style="Text"/></Item>
<Item><Ref Sect="Example09"/> <Ref Sect="Example09"  Style="Text"/></Item>
<Item><Ref Sect="Example13"/> <Ref Sect="Example13"  Style="Text"/>
<P/>
This extends Example <Ref Sect="Example03"/>.
</Item>
<Item><Ref Sect="Example14"/> <Ref Sect="Example14"  Style="Text"/>
<P/>
This extends two earlier examples <Ref Sect="Example03"/> and  <Ref
Sect="Example13"/>.
</Item>
<Item><Ref Sect="Example15"/> <Ref Sect="Example15"  Style="Text"/></Item>
<Item><Ref Sect="Example16"/> <Ref Sect="Example16"  Style="Text"/>
<P/>
This extends Example <Ref Sect="Example06"/>.
</Item>
<Item><Ref Sect="Example17"/> <Ref Sect="Example17"  Style="Text"/></Item>
<Item><Ref Sect="Example18"/> <Ref Sect="Example18"  Style="Text"/> 
<!-- Permutation module of dim 4 of the dihedral gp of order 8-->
</Item>
<Item><Ref Sect="Example19"/> <Ref Sect="Example19"  Style="Text"/>
<!-- Module example, permutation module of
		dimension 4 of the dihedral group of order 8, with the all ones
	vector fixed--> 
<P/>
This extends Example <Ref Sect="Example18"/>.
</Item>
<Item><Ref Sect="Example20"/> <Ref Sect="Example20"  Style="Text"/>
<P/>
This example also extends  Example <Ref
			Sect="Example18"/>.
</Item>
<Item><Ref Sect="Example04"/> <Ref Sect="Example04"  Style="Text"/></Item>
<Item><Ref Sect="Example21"/> <Ref Sect="Example21"  Style="Text"/></Item>
<Item><Ref Sect="Example22"/> <Ref Sect="Example22"  Style="Text"/>
<!--Module example: Hecke Algebra of type
     A<M>_3</M> <B>over</B> GF(3), obtaining a 4-dimensional representation
-->
</Item>
<Item><Ref Sect="Example23"/> <Ref Sect="Example23"  Style="Text"/></Item>
<Item><Ref Sect="Example12"/> <Ref Sect="Example12"  Style="Text"/></Item>
<Item><Ref Sect="Example24"/> <Ref Sect="Example24"  Style="Text"/></Item>
<Item><Ref Sect="Example25"/> <Ref Sect="Example25"  Style="Text"/></Item>
<Item><Ref Sect="ExampleColagen"/> <Ref Sect="ExampleColagen"  Style="Text"/></Item>
</List>
</Section>
	<#Include Label="Example01">
	<#Include Label="Example02">
	<#Include Label="Example11">
	<#Include Label="Example03">
	<#Include Label="Example05">
	<#Include Label="Example06">
	<#Include Label="Example07">
	<#Include Label="Example08">
	<#Include Label="Example10">
	<#Include Label="Example09">
	<#Include Label="Example13">
	<#Include Label="Example14">
	<#Include Label="Example15">
	<#Include Label="Example16">
	<#Include Label="Example17">
	<#Include Label="Example18">
	<#Include Label="Example19">
	<#Include Label="Example20">
	<#Include Label="Example04">
	<#Include Label="Example21">
	<#Include Label="Example22">
	<#Include Label="Example23">
	<#Include Label="Example12">
	<#Include Label="Example24">
	<#Include Label="Example25">
	<#Include Label="ExampleColagen">
</Appendix>
<Bibliography Databases="gbnp_doc" Style="plainurl"/>
<!-- -->
<TheIndex/>
</Book>
