
%\def\newconcept#1\index{#1}\emph{#1}
\def\bm{{\bf bergman}}
\def\Bm{{\bf Bergman}}
\def\setQ{\mathbf{Q}}
\def\setZ{\mathbf{Z}}
\def\Gbas{Gr\"{o}bner bas}






\section{Introduction}
\label{sec:intr}


In this section we suppose that the user is already familiar with
{\bf bergman} and is able to start and use it in the simplest cases.
The aim of this section is to explain  more detailed how to use
{\bf bergman} and to present all its facilities.



\section{{\bf Bergman}: philosophy and approach}


The philosophy of {\bf bergman} is to give the user a possibility
to use Bergman's Diamond Lemma with a maximum flexibility.
It means that {\bf bergman} is mainly a powerful instrument for
calculating Gr\"{o}bner basis  in several situations: commutative and
non-commutative algebras, modules over them.

Besides that it provides some facilities to calculate
appropriate invariants of the algebras and modules:
Poincar\'{e} and Hilbert series, Anick's resolution and
Betti numbers.

The aim is maximum efficiency with few
restrictions. Note however the  homogeneity setting.  The user need not
care how long the coefficients might be if (s)he wants to work
over rationals, but should also have a possibility
to work over prime characteristic or to include
indeterminates as coefficients.

Nevertheless {\bf bergman} is not a full computer algebra system. 
Rather it is a box,
containing several useful routines, so it takes
some efforts from the user to find them here and to use them
in a correct way.  Additional problems might appear
because of the Lisp--oriented form of the procedures. But
this box is not black: the user can read, modify the procedures
and create its own. Moreover, (s)he can use them together
with Reduce, so from this point of view, {\bf bergman}
can be considered as a Reduce package. (You can read
more about this in  section \ref{reduce}).
The purpose of this chapter  is to explain {\bf bergman} as if it is  a
black box, describing all its main (unmodified) procedures. 


\section{{\bf Bergman}: main restrictions}

{\bf Bergman} has two main restrictions.
First, it is not a
separate program and cannot be used without some underlying Lisp, like 
PSL or CLISP (or Reduce,
which contains PSL). The second and important one,  mentioned
above, is {\it homogeneity}.
All input to the simple top level procedures 
(excepting {\bf rabbit}, see \ref{rabbit}) must be
homogeneous (e.g. by the natural grading, where each variable has degree
one). They do not automatically check homogeneity. The possibility to
use weighted variables extends the class of problems which
can be solved by {\bf bergman}: the degree function need not be a natural
(``standard'') grading.



There are some experimental procedures which under some restrictions test for
homogeneity, homogenise input, and dehomogenise output; see the
subsection \ref{homog} below.

In the commutative case homogeneity is not the  principal restriction.
It is not so difficult to homogenise relations to obtain the
same, in principal, result. But for the non-commutative algebras
this restriction is essential and this is the price for the efficiency.
Unfortunately, it means that it is impossible to use {\bf bergman}
for the homological  investigations of the groups or most of the finite dimension
nontrivial idempotents. Nevertheless, using the rabbit strategy it is possible 
to calculate their Gr\"obner bases. 

Note also that  {\bf bergman} has no  routines for the polynomial
factorisation. So, the applications of {\bf bergman} to the solutions
of the nonlinear systems of equations are sufficiently restricted.



\section{The polynomial ring set up}
\label{modes}

To perform some computations in \bm\ you should  set up the
polynomial ring and its environment. This action includes
%\index{polynomial ring} polynomial ring and its environment. This action includes
selection of the algebra type (commutative \index{commutativity} or
\index{non-commutativity} non-commutative),
the variables, the \index{ordering} ordering, the
%\index{characteristic} characteristic,
type of coefficients, and variable
\index{weights} weights. One can also select the stra\-te\-gy of computation,
and input--output mode. There are some minor mode selections too. For a
complete  description see section \ref{refm}. This section contains an
informal explanation of the most important components in the ring
definition. 


\subsection{Variable names and the flag {\bf raise} }

We start from the variables -- generators of our algebras (modules).
Their names  may be specified
to almost any valid Lisp identifiers. (Some special signs, like $*$ and
$^,$ should not be used unslashified in the identifier names.)
So, not only usual letters such as x,Y may be used, but also
x1,Y45 or even I\_kiss\_you\_a\_1000\_times can be used as a variable.
But do not try $x[1]$ or $Y(2)$ as names!
In any place you may have a look to your current list of variables using
\index{getinvars}
{\bf (getinvars).}

Here is a possible example.

\begin{verbatim}
6 lisp> (getinvars)
(x y z)
\end{verbatim}  
  


One important question is if the names ''y'' and ''Y'' represent the same
variable. The answer depends on the current value of the flag \index{raise}
{\bf raise}. If it is in the state OFF, they are different, otherwise
(if it is in the state ON) ''y''=''Y''.

The meaning of this flag is to translate all the letters to 
capitals (or the opposite case in the later versions). 
Next come several important notes, concerning this flag:
 \begin{enumerate}
 \item From the very beginning the value of this flag is ON. That is
 why you can write {\bf (SIMPLE)} instead of  {\bf (simple)}
\item You may influence whether or not reading of variables and generators
is  case sensitive mode.  Typing \index{setcasesensalgin}

{\bf (setcasesensalgin t)}

you establish the case sensitive mode of algebraic input and by 

{\bf (setcasesensalgin nil)} 

the mode is switched to no-case sensitivity. 

\item Most the procedures, available to user have 
%ufn%
been written in source files using capital names. The procedures, intended
 to be unavailable to the normal user have been written with the names
  containing both small and capital letters,
  such as   SecretProcedure. They will be unavailable because by the default
  flag {\bf raise} is ON. 

In the later versions of Reduce and LISP
the situation is more complicated. Because flag {\bf raise} works in the opposite direction now (decapitalizing instead of capitalizing),
all the procedures written in capitals would be unavailable too. That is why
in those versions a special converter is used to interchange lowercase and capital characters. So, for example, even if in the source files
the procedure is written as {\bf (SIMPLE)} it will have the name
{\bf (simple)} inside the {\bf bergman} and will be available independent of the flag {\bf raise}. The unpleasant effect of this is that such procedures
as SecretProcedure  can appears as sECRETpROCEDURE
or even as  s!E!C!R!E!Tp!R!O!C!E!D!U!R!E, but this ugly names we can see in the case of errors only (when the user is able to recover easy the original name the SecretProcedure).


 More exactly, some procedures may turn OFF the flag {\bf raise} while they
 are working. If a break loop (for example because of mistake)
 happens during their work the value of the flag will be OFF
 and, for example, you will be unable to quit from the program
 writing \index{quit}

{\bf (QUIT)} 

 because in this case the name should be decapitalized:

{\bf (quit)}

 Another way to quit is

 {\bf (on raise)}

  {\bf (QUIT)}

  \item If the user wants (e.g. for the debugging) to have access inside the {\bf bergman} to  
  the procedures and variables with the names, containing both small and capital letters,
  such as   SecretProcedure (s)he needs to switch the flag {\bf raise} OFF
  and use the names, where secret  letters (capital in last version and lowercase in the older versions) are printed after
  exclamations: b!A!D. Even the multiplication in some versions
  is secret and looks as !*.
  But normally you don't need  take care about this. 
%nfu%



 \end{enumerate}

 
\subsection{Ordering} \index{ordering}
\label{ord}




 In the commutative setting {\bf bergman} can perform computations in three different orderings:
 \index{lexicographical ordering}
 lexicographical (DEGLEX) or reverse lexicographical ordering
 \index{reverse lexicographical ordering} (DEGREVLEX, which is the default choice), and  
 \index{matrix  ordering} matrix  ordering. We discuss matrix ordering later in section \ref{matrixordering},
and here we  consider the first two ordering only.
Both of them are graded,
 it means that first we compare length (or weights) of words and only
 after
 that use the lexicographical comparison.

 For example, if $x>y>z$ is
 our ordered alphabet, then  we have
 $$1 <z<y<x< zz<yz<yy<xz<xy<xx<\,.\,.\,.$$
 in the commutative DEGLEX  computation and
  $$1 <z<y<x< zz<yz<xz<yy<xy<xx<\,.\,.\,.$$
 in the commutative DEGREVLEX computation.

By default the DEGLEX ordering is chosen  in the non-commutative {\bf berg\-man}
computation. Keeping the same ordered alphabet with $x>y>z$ we have  
$$1 <z<y<x< zz<zy<zx<yz<yy<yx<xz<xy<xx<zzz\,.\,.\,.$$
 
Besides that there exist two eliminating orderings in the non-commutative mode:
ELIMLEFTLEX and INVELIMLEFTLEX.
In the first one the words are compared first as commutative words in
DEGLEX. If they are equal as commutative words they are compared
as in non-commutative DEGLEX 
%ufn%
.
%(but the order of letters is opposite).
%nfu%

 Keeping the same ordered alphabet with $x>y>z$ we have

$$1 <z<y<x< zz<yz<zy<yy<xz<zx<xy<yx<xx<zzz\,.\,.\,.$$

In the INVELIMLEFTLEX the first comparison is as commutative  DEG\-REVLEX,
and if the words are equal as the commutative words they are compared
as in non-commutative DEGLEX 
%ufn%
.
%(but the order of letters is opposite).
%nfu%

So the order will be:

$$1 <z<y<x< zz<yz<zy<xz<zx<yy<xy<yx<xx<zzz\,.\,.\,.$$

 It is important for the Gr\"{o}bner basis calculations which of the variables is the 
highest (largest). The rule is determined by the order of the variables,
 written after {\bf vars } in one of the top-of-the-top
 procedures and is as follows:
 \begin{itemize}
  \item in the non-commutative  DEGLEX mode the last variable is always the highest;
  \item in the commutative mode and both eliminating orderings first variable is the highest.
%  from the very beginning or after the
%   calling the procedure
% 
%   {\bf (deglexify)} \index{deglexify}
% 
%   \item in the commutative mode  the last variable is  highest after the
%   calling the procedure
% 
%   {\bf (degrevlexify)} \index{degrevlexify}


  \end{itemize}

The following procedures set the  corresponding orderings.

\vspace*{0.4cm}
  \begin{tabular}{|l|l|}
  \hline
  Ordering &  Procedure\\
  \hline
         DEGREVLEX & \index{degrevlexify} REVLEXIFY()  \\ \hline
         DEGLEX &   \index{deglexify}  DEGLEXIFY()  \\ 
                &  (commutative case)\\
                & \index{degleftlexify}  DEGLEFTLEXIFY() \\
                & (non-commutative case) \\ \hline
         ELIMLEFTLEX & \index{elimorder} ELIMORDER() \\ \hline
         INVELIMLEFTLEX &\index{invelimorder}  INVELIMORDER() \\ 
        \hline
         MATRIX &\index{matrix ordering} MATRIXIFY \\
 &  (commutative case)\\
       \hline
  \end{tabular}
\vspace*{0.4cm}

Note that the procedure {\bf deglexify} works only in the
commutative mode, in the non-commutative case DEGLEX ordering
is established by the procedure {\bf degleftlexify}.


\subsection {Using eliminating ordering}

Despite the fact that {\bf bergman} works mainly with graded algebras,
it can be successfully applied to the non-graded case.  The idea is to 
homogenize the
ideal (using an additional commuting homogenizing variable $h$) and to 
perform calculations
in the eliminating ordering and then dehomogenise the result setting $h=1.$

Let us consider an example suggested by  Prof. I.Kantor.
Let $A$ be  the following algebra:

\begin{footnotesize}
$$A= < r,l,q| r^2-q^2+lr-r,
rq-qr+lq-q,
lr-rl,
lq+ql-2q,
rr-rl-2lr+2l^2-r+l>$$
\end{footnotesize}

It was important to find the minimal polynomial for $q.$ 
Here is the solution achieved by  {\bf bergman}:

\begin{footnotesize}
\begin{verbatim}
2 lisp> (noncommify)
nil
3 lisp> (elimorder)
nil
4 lisp> (simple)
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input>  vars r,l,q,h;
algebraic form input>  r*r-q*q+l*r-r*h,r*q-q*r+l*q-q*h,
algebraic form input>  l*r-r*l,l*q+q*l-2*q*h,
algebraic form input>  r*r-r*l-2*l*r+2*l*l-r*h+l*h,
algebraic form input>  r*h-h*r,q*h-h*q,l*h-h*l;

% 2
-h*q+q*h,
   -h*l+l*h,
   q*l+l*q-2*q*h,
   -h*r+r*h,
   -q*r+r*q+l*q-q*h,
   -4*r*l+2*l^2+l*h+q^2,
   4*l*r-2*l^2-l*h-q^2,
   4*r^2-4*r*h+2*l^2+l*h-3*q^2,

% 3
4*r*q*h-4*l^2*q+10*l*q*h-q^3-9*q*h^2,
   4*r*q^2+12*l^3-10*l*q^2-3*l*h^2-3*q^2*h,

% 4
l*q^3-3*l*q*h^2-q^3*h+3*q*h^3,
   -12*l^3*h-4*l^2*q^2+20*l*q^2*h+3*l*h^3-q^4-6*q^2*h^2,
   -4*l^3*q+12*l^2*q*h-11*l*q*h^2+3*q*h^3,
   12*l^4-8*l^2*q^2-3*l^2*h^2-2*l*q^2*h+q^4,

% 5
-48*l^2*q*h^2+96*l*q*h^3-q^5+10*q^3*h^2-57*q*h^4,

% 6
-48*l^2*q^2*h^2+96*l*q^2*h^3-q^6+10*q^4*h^2-57*q^2*h^4,

% 7
-q^7+13*q^5*h^2-39*q^3*h^4+27*q*h^6,

\end{verbatim}
\end{footnotesize}

If we look at the last element of the obtained  Gr\"{o}bner basis and
put $h=1$ we get the desired equation:
$$q^7-13q^5+39q^3-27q=0$$
The secret is in the command  {\bf elimorder}: now if two words are compared,
they are compared first as the commutative words in pure left lexicographical 
ordering and after that (if commutatively they are equal) as usual. That is 
why if the minimal polynomial exists its homogenized variant should belong to 
the   Gr\"{o}bner basis: if the leading monomial is $q^n$ all other terms 
should contain the letters $h$ and $q$ only, $h$ being in the end because it 
commutes with $q.$ To obtain the minimal polynomial for $l$ it is sufficient 
to put $l$ before the homogenizing variable (which should remain the last) 
in the list of the variables, e.g. {\bf  vars}   r,q,l,h;

\subsection{Matrix Ordering}
\label{matrixordering} \index{matrix ordering}
 Using matrix ordering one can get
 all possible orderings in the commutative case.
The idea is the following. Suppose we want to compare two monomials
$x_a=x_1^{a_1}\ldots x_n^{a_n}$ and $x_b=x_1^{b_1}\ldots x_n^{b_n}$.
Let $a=(a_1,\ldots ,a_n)^T$ and $b=(b_1,\ldots ,b_n)^T$ be the corresponding
column-vectors and $M$ be an invertible $n$ by $n$ matrix.
We say that $x_a>x_b$ if the vector $Ma$ is lexicographically larger than 
$Mb.$ For example, if we want to compare $x^2y^3z^3$ and
$x^3y^4z$ we consider $a= (2, 3, 3)^T, b= (3,4,1)^T$. Suppose that we have a matrix ordering defined by the matrix
 $$M=\left( \begin{array}{rcc}
  1& 1  &1\\ 
  -1 &1& 0\\
  1 &0 & 2\\
 \end{array} \right).$$ We have
$$Ma=\left( \begin{array}{rcc}
   1& 1  &1\\ 
  -1 &1& 0\\
  1 &0 & 2\\

 \end{array} \right)\left( \begin{array}{c}
  2 \\
  3 \\
  3\\
 \end{array} \right) =\left( \begin{array}{c}
  8 \\
  1 \\
  8\\
 \end{array} \right); Mb=\left( \begin{array}{rcc}
  1& 1  &1\\ 
 -1 &1& 0\\
  1 &0 & 2\\
 \end{array} \right)\left( \begin{array}{c}
  3 \\
  4 \\
  1\\
 \end{array} \right) =\left( \begin{array}{c}
  8 \\
  1 \\
  5\\
 \end{array} \right) $$
so  $x^2y^3z^3>
x^3y^4z$.
 
Note that the matrices
 $$M=\left( \begin{array}{ccc}
  1 &1& 1\\
  1 &0 & 0\\
  0& 1  &0\\
 \end{array} \right),M=\left( \begin{array}{ccc}
  1 &1& 1\\
  0 &0 & 1\\
  0& 1  &0\\
 \end{array} \right) $$
define orders  DEGLEX and  DEG\-REVLEX, respectively, but
the identity matrix defines pure lexicographical ordering.

 If the variables have weights (see section \ref{weights}) we should naturally modify the vectors.
For example, if the weights for $x,y,z$ were 1, 2, and 3, respectively,
we should use vector $a=(2,6,9)$ for $x_a=x^2y^3z^3.$ 

In {\bf bergman} we can use the matrix order in the commutative mode
using the command  {\bf (matrixify)}. The matrix itself is described
by the command {\bf (setordermatrix M)}, where  {\bf M} is a matrix,
written as a list of vectors (rows). Here is an example of calculations
using matrix order combined with the weights (compare order of monomials in input and output!):


\begin{verbatim}
4 lisp> (setweights 1 2 1)
nil
5 lisp> (setordermatrix  ((1 2 1) (0 -1 1) (3 -2 2)))
nil
6 lisp> (matrixify)
nil
7 lisp> (commify)
nil
8 lisp> (simple)
Now input in-variables and ideal generators in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, and r1, ..., rm the generators.
algebraic form input> vars x,y,z;
algebraic form input> x*y^3+y^3*z,
algebraic form input> 6*x^2*y^2+3*x*y^2*z+y^2*z^2+4*y^3;
SetupGlobals
 ... done
% 6
y^2*z^2+3*x*y^2*z+6*x^2*y^2+4*y^3,

% 7
y^3*z+x*y^3,

% 8
-x^2*y^3-y^4,

Done


\end{verbatim}

\subsection{Coefficients: background}
\label{field}


\index{coefficients} Coefficients handling is an important part of
\bm. Mathematically, the ring of coefficients should be a field~$K$,
the \index{coefficient field}{\bf coefficient field}. In basic \bm, this field must be a
prime field; i.e., either the field $\setQ$ of rational numbers, or the
Galois field $\setZ / (p)$ of residue classes of integers with respect to
a prime number $p$. The \index{characteristic}{\bf characteristic} of $\setQ$ is 0, and
the characteristic of $\setZ / (p)$ is $p$, so that the prime field is
completely determined by its characteristic.


 If you run \bm\ under \index{Reduce mode} Reduce in commutative mode,
then you have further possibilities, as it is described in the next
subsection. In order to employ these, it is necessary to understand
the way bergman treats coefficients.

 In order to simplify the internal representation and thus make
coefficient calculations faster, \bm\ tries to avoid fractions in
coefficients, whenever feasible. This is done by means of the
coefficient domain, associated polynomials, and gcd calculations.

 The \index{coefficient domain} {\it coefficient domain\/}~$A$ should be a
sub-domain of the coefficient field~$K$, such that its field of fractions
is~$K$. (Here {\it domain} signifies integral domain, i.e., unitary
commutative ring without non-trivial zero-divisors.) In the basic
coefficient modes, $A$ is the smallest possible sub-domain of~$K$,
so that $A = \setZ =$~the ring of integers in characteristic~0, but
$A = K = \setZ / (p)$ in positive characteristic.

 Recall that if $f = f(x_1,\ldots,x_n)$ and $g = g(x_1,\ldots,x_n)$ are
elements in $R = K \mathopen[ x_1,\ldots,x_n
\mathclose]$, then $f$ and $g$ are \index{associated
polynomial} {\it associated polynomials\/} if $g = uf$ for some non-zero
$u \in K$. (Then clearly $f = u^{-1}g$; and more generally, `associatedness'
is an equivalence relation on $R$.) Since $K$ is the field of fractions
of~$A$, each $f \in R$ has associated polynomials with all their
coefficients in~$A$. We may e.g.\ write all coefficients of~$f$ as
fractions of elements in~$A$, and let $u$ be the product of all the
denominators; then clearly $uf \in A \mathopen[ x_1,\ldots,x_n
\mathclose]$.

 However, normally this is far from efficient. The
coefficients in this $uf$ often are extremely large (or complex).
For $A = \setZ$, this may be avoided by factoring out the \index{content}
{\it content\/} of $uf$, i.e., the greatest common divisor of all the
coefficients. Thus we get a new associated polynomial, hopefully with
reasonably complex coefficients.

 If $g_i$ is associated to $f_i$ for $i = 1, \ldots, r$, then $f_1,\ldots,
f_r$ and $g_1, \ldots, g_r$ generate the same ideal in $R$. Hence, if
$K = \setQ$ and
all we want is to calculate a \Gbas is, then we may always replace any
appearing polynomial by an associated polynomial in $\setZ \mathopen[
x_1,\ldots,x_n \mathclose]$ of content~1. In practice, it is more efficient
to make such replacements dynamically during the calculation of normal
forms. This is the default content taking strategy of \bm.

There are some situations when such tactics 
%ufn%
does
not work, as when we
want to calculate Anick resolutions. For these cases \bm\ also has a procedure
{\bf normalform}  for calculating the true normal form of a polynomial.
%nfu%



\subsection{Coefficients: choices}

 \index{coefficients}

To select a \index{coefficient field} coefficient field (and a
\index{coefficient domain} coefficient domain) you call \index{setmodulus}
{\bf (setmodulus $p$)} where either $p$ is the desired \index{characteristic} characteristic (0 or
a prime number), or $p$ is {\bf sf} (from ``(Reduce) Standard Forms'').

By default and after the call of {\bf (setmodulus 0)}, the coefficient field
is the field~$\setQ$ of rational numbers, and the coefficient domain is
the ring~$\setZ$ of integers. This means that all input coefficients
and most internal and output coefficients are considered as integers. There are
no restrictions for the length of the integers - only the restrictions of the
memory of your own computer. Nevertheless, when you are sure from the
very beginning that your coefficients (even inside the calculations)
never will be too large (e.g. if the relations have a semigroup form:
$f-g,$ where $f$ and $g$ are words) you can try to achieve more
efficiency using the flag \index{nobignum} {\bf nobignum} - see
the  subsection \ref{flags} for more details.

However, if you want to perform series calculations, you should also
decide whether or not the series coefficients may exceed the `small
integer limit' of your Lisp implementation, before turning on
nobignums.

You cannot use fractions in the input and do not ordinarily get them as output.
%So, the highest term of your Gr\"{o}bner basis  elements may have a coefficient, even
%negative.

Another minor mode choice affecting the characteristic zero (and the {\bf sf})
coefficient mode is the dense or sparse content taking.


\medskip

After the call {\bf{setmodulus}~$p$}, where $p$ is a prime number, the
coefficient field and the coefficient domain both are $\setZ / (p) = GF(p)$,
the unique field with $p$ elements.


%You have also a possibility to select prime characteristic in the both
%variants - with bignums or without them.
%For example

%{\bf (nobignums) }


%{\bf (setmodulus 2) }


% is a reasonable preparation if you plan to work over the field of two
% elements only.
%Nevertheless there is no possibility to work in the field other then
%$F_p$ inside {\bf bergman}. You can do it only under Reduce (see section
%\ref{reduce} for more details).

Note that in the prime characteristic the highest term of any
polynomial in the Gr\"{o}bner basis  has
always the coefficient~1 (in contrast to the zero characteristic case).

In odd prime characteristic with a reasonably small~$p$, {\bf bergman} employs
efficient `small number calculations' only with the coefficients. If you
need to optimise coefficient handling further, please note the
following. With some hardware and software architectures, multiplication
is a much more time consuming operation than are (single) additions and
multiplications. In such cases, you should consider employing the
\index{modulus logarithms method} {\it modulus logarithms method\/}.
Mathematically speaking, it works by finding a generator $\gamma$ for the
cyclic multiplicative group of non-zero elements in $\setZ/(p)$, and by
representing such elements by their ``$\gamma$-logarithms'' (i.e.,
representing $a = \gamma^s$ by $s$), whenever convenient.

 The main effect of using the `modular logarithms mode'
in typical {\bf berg\-man} \Gbas is calculations is that in the most time
consuming combined coefficient operation, of the type
 $$a \cdot b + c \,,$$
one multiplication and one addition is replaced by two additions and
one `logarithm table lookup operation', represented by finding an item
in a Lisp vector (array). In addition, one Lisp remainder operation is
replaced by one comparison and (in average) a half subtraction. The
net effect is to replace one multiplication and one remainder operation
by one addition, a half subtraction, one comparison and one `look-up'.

 The draw-back is that \bm\ must construct or to read the `logarithm
table' and the inverse `exponential table' into memory.

 If you want to employ this, do \index{modlogarithmic}
\begin{center}
%ufn%  
{\bf (setoddprimesmoduli  modlogarithmic)}
%nfu%
\end{center}
{\it before} you do the {\bf setmodulus $p$} for your odd
prime~$p$.

When you do this, \bm\ may or may not succeed in finding a prepared
file for the look-up tables; and if it doesn't find the file, it
may or it may not succeed in creating the tables. In the present
version, it is depending on being able to create the tables file, if
this doesn't exist. Thus, you may run into troubles, e.g.\ if you do
not have write access to the directory for modular logarithm tables
handling. Some ways of overcoming this are discussed in the
next chapter.

%The effect (after calling the {\bf (setmodulus Q) })
%is to create in the subdirectory {\bf domains}  the file with the first
%letter p, following the digits, representing the number Q (e.g. p37
%for Q=37) or using existing one if it was already  created. It
%provides efficient calculations of the products, using so-called
%logarithmic tables.% (see chapter \ref{MATH-APP} for more details.)

You need not this mode in characteristic 2 or 0, and should avoid
it (possibly loosing a bit in time efficiency) if you want to save
memory. By default, modular logarithms are off.


\medskip

%The most general (but difficult) choice is selecting arbitrary
%forms of the coefficients, by
%{\bf setmodulus sf}
%This is possible under Reduce only. % and is described in the subsection \ref{reduce}.

In addition to the few efficient basic coefficient modes available in {\bf berg\-man},
there is a possibility to set up `your own' coefficient field and domain
in an ordinary Reduce way. In this case, \bm\ calls Reduce for each
coefficient operation. The domain elements are represented as Standard
Forms, and the field elements as Standard Quotients. Similarly, the
general Reduce Greatest Common Divisor procedure is employed for taking
contents. Any reduction rules for calculating in Reduce are active,
including Reduce modulus setting, but with the following exception:
At input from Reduce, the variables specified as {\bf bergman} in-variables
are treated by \bm\ variable handling procedures.

 In order to employ this, the user should have a good understanding
both of the mathematics and of Reduce. It is entirely her/his
responsibility to ensure that indeed the given in-coefficients reside
in a mathematically well-defined field, with respect to the given
Reduce rules.

{\bf Example:} In order to calculate with coefficients in the field
$GF(169)(a)$ (where $a$ is transcendent over $GF(169)$), you may note
that $GF(169)$ may be realised as a quadratic extension of its
prime field $GF(13)$, e.g., by means of $\sqrt2$. Thus, you might try

{\bf algebraic;}

{\bf setmod 13;}

{\bf on modular;}

{\bf b\^{}2 := 2;}

and then go on as usual, employing the $i+j*b$ ($i,j \in
\{0,1,\ldots,12\}$) as representatives for the elements in $GF(169)$.




\subsection{Weights handling}
\label{weights}
 There are possibilities to handle some non-naturally graded
situations, i.e., situations where not all variables have degree 1.
Then the \index{weights} weights, i.e., the degrees of the variables, may be set
to arbitrary positive integers. (Thus weight 0 is not allowed.)
The degree of a monomial then will be calculated as the sum of the
weights of its variable factors.

The natural grading corresponds to giving each variable weight 1.
However, using the weighted variables mode could yield considerably
slower calculations than using the natural grading mode. Thus weights
should be set only if some of them deviate from 1.

Restrictions: For computational efficiency reasons, all degrees
appearing during calculations are assumed to be ''inums'', i.e., small
enough to fit into the small numbers representation of your computer.
In the naturally graded situation, this is hardly ever a practical
limitation; but if you give rather high weights to some variables,
you could get into some trouble.

%The weights
%information is saved internally in two structures. The
%weight list is NIL in the naturally graded case, and else contains
%the weights of variable 1, 2, 3, ..., in this order. The weight
%dotted pair list explicitly combines variable numbers and variable
%weights as dotted pairs (1 . weight_1) (2 . weight_2) ..., in this
%order.

There are moreover some inconsistencies in the variable ordering in
this version of {\bf bergman}. Also, series calculation and the Anick
resolution implementation are not yet
compatible with the weighted variables mode.

The weight list  contains the weights of variable 1, 2, 3, \ldots , in
this order.

There are several procedures for weights handling in {\bf bergman}.

\index{setweights} {\bf (setweights $int_1$ $ int_2$  \ldots $int_n$)}\\
Sets the weights to $int_1$, \ldots , $int_n$. The 
%ufn%
$int_i$
%nfu%
must be positive
integers. No weights given restores the naturally graded mode.
% Returns the old weight list.

\index{clearweights} {\bf (clearweights)} \\
Restores the naturally graded mode.  Returns the old weight list.

\index{getweights} {\bf (getweights)} \\
Returns the current  weight list.

%ufn% eto napisano 2 raza
%\index{printweights} {\bf (printweights)} \\
%Returns the current  weight list.
%ufn%


%\index{getweightdps} {\bf (getweightdps)}\\
%Returns the present weight as dotted pair list, where variable
%numbers and variable weights are combined  explicitly:\\
%$(1\ .\ weight_1) (2\ .\ weight_2) $..., in this order.

%Caution: Do not
%manipulate this destructively, as long as the weight has not been
%reset.

\index{printweights} {\bf (printweights)}\\
If weights are set, print these (with spaces between but without
parentheses or line feeds) and return T. Else, print nothing and
return NIL.

\index{setweightstoone} {\bf (setweightstoone)}\\
Put weights $1$ to all variables in the current list of variables.


Example of a Gr\"{o}bner basis computation  in a non-naturally graded
situation:


%ufn% mojet biti 
%ufneshe vcliuchiti primeri  (printweights) i(getweightdps)
% tac cac oni daiut intuitivno neojidannie rezulitati.
%nfu%

\begin{verbatim}
1 lisp> (setweights 2  2 1)
nil
2 lisp> (getweights)
(2 2 1)
3 lisp> (simple)
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input> vars x,y,z;
algebraic form input> x^3, x*z-y*z;
% 3
x*z-y*z,
   
% 6
x^3,
   
% 7
y^3*z,
   
Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), 
     and run a new (SIMPLE).
nil
4 lisp> 


\end{verbatim}


\subsection{Rings exchange}

Normally {\bf bergman} works with one fixed ring only. For some applications
 the user would like to have the access to  several different 
rings (e.g. to compare two different normal forms of the same element).

For this purpose in {\bf bergman} exists a stack of rings. Because only one ring 
is formally available, it is possible to save the current ring in this stack,
perform the computations in a new ring and then restore the old ring from
 the stack. 
Here is the list of available procedures:

\index{pushring} {\bf (pushring)} saves the current ring on the top of  the stack;

\index{popring}{\bf (popring)} takes the ring from the top of the stack and 
makes it current;

\index{switchring} {\bf (switchring)} makes rings exchange: the top ring from the stack 
becomes a current and the current one becomes a top;

\index{ringstacklength} {\bf (ringstacklength)} gives the length of the stack.



Here is an example of the session where we calculate the normal form of
$x^2$ in two different commutative rings:

\begin{verbatim}
1 lisp> (simple)
Now input in-variables and ideal generators
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables,
and r1, ..., rm the generators.
algebraic form input> vars x,y;x^2-y^2;

% 2
x^2-y^2,

Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), and run a new (SIMPLE).
nil
2 lisp> (readtonormalform)
algebraic form input> x^2;

is reduced to
y^2,

nil
3 lisp> (pushring)
1
4 lisp> (clearideal)
5 lisp> (simple)
Now input in-variables and ideal generators
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables,
and r1, ..., rm the generators.
algebraic form input> vars x,y;x^2;
% 2
x^2,

Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), and run a new (SIMPLE).
nil
6 lisp> (readtonormalform)
algebraic form input> x^2;

is reduced to
0,
nil
7 lisp> (switchring)
t
8 lisp> (readtonormalform)
algebraic form input> x^2;

is reduced to
y^2,

nil
9 lisp> (popring)
1
10 lisp> (readtonormalform)
algebraic form input> x^2;

is reduced to
0,
nil

\end{verbatim}

\section{Homogenisation}
\label{homog}

Suppose we would like to find a minimal polynomial for
$\alpha=\sqrt{2}+\sqrt{3}+\sqrt{5},$ i.e. such a polynomial 
%ufn% izmenil f na p - dalishe f ispolizuetsia v drugom smisle.
$p(x)$
with the
integer coefficients that $p(\alpha)=0.$
%nfu%

One possible way to do it is to find a
Gr\"{o}bner basis for the following ring:

$$ A=<x,y,z,t| xx-2,yy-3,zz-5, t-x-y-z>$$

The important thing is the choice of ordering. We want to get the element that
contains the variable $t$ only - it would be desired minimal polynomial. So
the variable $t$ should be the lowest, for example $x>y>z>t.$ Even more -
any power of $t$ should be less than any monomial, containing any variable
different from $t.$ It means that we need pure lexicographical ordering.
In such an ordering (for example pure revlex) we should have the following
Gr\"{o}bner basis$:\\
t^{8} - 40t^{6} + 352t^{4} - 960t^{2} + 576,\\  
576z - 5t^{7} + 194t^{5} - 1520t^{3} + 2544t, \\
96y + t^{7} - 37t^{5} + 244t^{3} - 360t, \\ 
576x - t^{7} + 28t^{5} + 56t^{3} - 960t.$

How to get from the  \bm\  such a result? The problem is that  \bm\  uses 
homogeneous relations only.  The solution is to homogenize the relations, using
a new variable (say $f$):

$$ B=<x,y,z,t,f| x*x-2*f*f,y*y-3*f*f,z*z-5*f*f, t-x-y-z>$$

It means that every monomial that had less degree than highest one (constants
in our case) was completed by corresponding number of factor $f.$ The
relations are now homogeneous and we can calculate the  Gr\"{o}bner basis in
the corresponding ordering. Let us see the session:

\begin{verbatim}
1 lisp> (purelexify)
nil
3 lisp> (setalgoutmode alg)
nil
4 lisp> (algforminput)
algebraic form input> vars x,y,z,t;
algebraic form input> x^2-2, y^2-3, z^2-5, t-x-y-z;
t
5 lisp> (homogeniseinput)
*** Function `h!O!M!O!Gpm!O!N' has been redefined
nil
6 lisp> (groebnerinit)
nil
7 lisp> (groebnerkernel)
d!O!N!E
8 lisp> (algforminput)
algebraic form input> vars x,y,z,t,f;
algebraic form input> ;
nil
9 lisp> (bigoutput)
-x-y-z+t,
   z^2-5*f^2,
   2*y*z-2*y*t-2*z*t+t^2+6*f^2,
   y^2-3*f^2,
   2*y*f^2-3*z*t^2+6*z*f^2+t^3+4*t*f^2,
   y*t^2-7*z*t^2+12*z*f^2+2*t^3+12*t*f^2,
   4*z*t^3-t^4-20*t^2*f^2+24*f^4,
   -80*z*t^2*f^2+96*z*f^4-t^5+60*t^3*f^2+24*t*f^4,
   96*z*t*f^4-t^6+40*t^4*f^2-376*t^2*f^4+480*f^6,
   576*z*f^6-5*t^7+194*t^5*f^2-1520*t^3*f^4+2544*t*f^6,
   -t^8+40*t^6*f^2-352*t^4*f^4+960*t^2*f^6-576*f^8,
   
nil
10 lisp> (quit)

\end{verbatim}
%ufn%
The reader can find some useful comments about the procedures used here
in the section \ref{bricks}. Note that we used {\bf algforminput} twice.
The second one is necessary to create an (external) name for the homogenizing variable, otherwise printing of {\Gbas}is is impossible. The ordering used here
gives  not exactly the same result as pure lexicographical ordering, but
because $t,f$ were the lowest variables we obtained our minimal polynomial.
%nfu%



%(DE HOMOGENP (auginhpol)
%(DE TESTINDATA () 
%(DE PREPAREHOMOGENISATION ()
%(DE PREPAREDEHOMOGENISATION ()
%(DE CLEARHOMOGENISATION ()
%(DE HOMOGENISE (auginhpol)
%(DE HOMOGENISEINPUT ()

%(DE DEGREELISTPUTPOINTERS(deglmonpol)
 

 %Homogenisation/dehomogenisation preparation. %%%%%%%%

% Homogenisation/inhomogenisation is a bit intricate, since the
% internal representation of monomials depends on the number of
% variables (the "embedding dimension", embdim). The homogenisation
% SHOULD HAPPEN IN THE SAME PLACE, ONCE in the run, unless an
% explicit dehomogenisation or a (CLEARIDEAL) has been performed.
% The reason is that else there is a grave risque of mixing in-
% homogeneous polynomials and monomials with homogeneous ones,
% or to use operations assuming the right kind of internal
% representation on the former, when they no longer have it.
% MOST SAFE AND SIMPLE should be only to use HOMOGENISEINPUT
% and DEHOMOGENISEREDUCEGBASIS. However, other top level functions
% may be needed in particular applications.


% The switch HOMOGENISED is normally set on or off by the
% (de-)homogenising routines. Touch it only e.g. to fool the
% system that the data is (not) homogenised, in order to perform
% an extra (de-)homogenisation.


% Checks that the mode settings are appropriate; sets HOMOGENISED;
% Stores away/Throws away the old saved unique monomial information
% (depending on whether SAVEINHOMOGMONS is set or not); changes the
% internal embdim, if set.


\section{Choosing a strategy}

One of the important mode choice that should be mentioned is selecting
the \index{strategy} strategy  of the calculations. Besides selecting of the
algorithm (Buchberger, staggered or ``the jumping rabbit'' (see \ref{rabbit}))
that you are doing by appropriate procedure, you have
some influence on the intermediate calculation. Choosing
\index{immediatefullreduction}

{\bf (setimmediatefullreduction t) }

(and this is default) you demand immediate reduction of all the terms
of Gr\"{o}bner basis  and obtain it in the reduced form.
Sometimes it might be
more efficient to switch OFF this flag. The obtained Gr\"{o}bner basis  may be
not reduced, but calculations might be slightly faster. There is no
clear receipts when it happens - try yourself!


\section{Input--output modes for the polynomials}
\label{inputform}

There are three basic \index{output format} output formats, named
\index{Lisp form} {\it lisp} (default), \index{algebraic form} {\it alg} (synonim - Maple), and
\index{Macaulay form}  {\it macaulay}, corresponding to the formats, used in those 3  languages.
The first two of these also are acceptable 
\index{input format} input formats.
In all input and output, the polynomials are distributed (written with
no parentheses). There is a difference between commutative and
non-commutative case.

\subsection{Commutative case}

 The (output) {\it alg}  representation of the  polynomial is
$$c_1*v_1\verb-^-m_{11}*\,.\,.\,. *v_n\verb-^-m_{1n}+ \,.\,.\,.
+ c_r*v_1\verb-^-m_{r1}* \,.\,.\,. *v_n\verb-^-m_{rn} .$$
Here $v_1, \,.\,.\,., v_n$ stand for the variable names, $m_{ij}$
for the exponents,
and $c_i$ for the coefficients. Highest terms will be printed first.

Occurrences of $*v_i\verb-^-0$ and of $\verb-^-1$ are omitted.
+ is omitted before $-.$
The {\it macaulay} representation is similar, but without $*$ and $\verb-^-$; and the
polynomials then are not separated by commata.
In input, some slight variation is allowed in the {\it alg} format:
 \begin{itemize}
  \item $**$ may be used instead of $\verb-^-$;
 \item Blank space may be inserted everywhere, except within identifiers
   or integers or between two successive $**$ .
 \item Exponents 0 and 1 may occur.
 \item The order of the variables in a monomial is arbitrary.
\end{itemize}


The {\it lisp} representation of the same commutative polynomial in $n$ variables is a
Lisp list of length n+1 lists of integers:
$$((c_1\ m_{11}\ \,.\,.\,. m_{1n}) \,.\,.\,.(c_r\ m_{r1}\ \,.\,.\,. m_{rn}))$$
where the CAR of the i:th list is the coefficient of the i:th monomial,
and the other n integers (which should be non-negative) are the
exponents.  Highest terms will be printed first in the output.

  

\subsection{Non--commutative case}




If you want to have output in {\it alg} or \index{Macaulay form} 
{\it macaulay} form, 
you  must define in one or another way the variable names, and you must 
set the the output mode to {\it alg} or {\it macaulay} using the function
variable \index{setalgoutmode} {\bf setalgoutmode} with corresponding arguments {\it alg} or {\it macaulay}. 
The variable names are most
easily given by {\bf vars} within a {\bf algforminput}, as explained below.
Moreover, many of the top-of-the-top {\bf bergman}'s procedures use algebraic
output mode as default.

 You may add your own algebraic output mode options by means
of\\ \index{addalgoutmode} {\bf addalgoutmode}, as explained below.

One can inspect the current mode by \index{getalgoutmode} {\bf getalgoutmode.}

In order to perform {\it alg} mode input, write


{\bf (algforminput)  }

{\bf vars v1, ...,vn;}

{\bf pol1, ... , pols;}

where v1, ..., vn are the variable names and pol1, ..., pols are
polynomials on {\it alg} form.


In order to perform \index{Lisp form} {\it lisp} mode input, write
\index{lispforminput}

{\bf (lispforminput) }

pol1 pol2 ..... pols

{\bf (lispforminputend)}

\index{lispforminputend}

where pol1, ..., pols are polynomials on {\it lisp} form. If you must specify
the number of variables to a number $n$ (as in the non-commutative case,
if you want to know the Hilbert series), then set {\it embdim} to $n$.
 ({\it embdim}
is short for "the embedding dimension".)

{\it Lisp}  form (homogeneous) polynomial of
degree $d$ is a list of lists of integers of length $d+1:$
$$((c_1\ m_{11}\ \,.\,.\,.  m_{1d}) \,.\,.\,. (c_r\ m_{r1}\ \,.\,.\,. m_{rd}))                 $$
where the CAR of the i:th list is the coefficient of the i:th monomial,
and the other n integers (which should be positive) are the
''indices''
of the variables, i. e., their position if they are ordered by increasing
significance. The corresponding {\it alg} format is
$$c_1*v_{m_{11}}*\,.\,.\,.*v_{m_{1d}}+\,.\,.\,. +c_r*v_{m_{r1}}*\,.\,.\,.*v_{m_{rd}} .$$
In input, identical factors may be collected to exponents.
For example, if
the variables are $x,y,$ and $z$ (in this order), then the
\index{Lisp form}{\it  lisp} form
polynomial $((5\ 1\ 1\ 1\  3\  2\  2))$ will be \index{algebraic form} 
{\it alg} form output as
$5*x*x*x*z*y*y,$
but it may optionally be input as $5*x**3*z*y\verb-^-2.$
Highest terms will be printed first in the output.

To perform output in the desired form apply {\bf setalgoutmode} with the corresponding 
argument ({\it alg},  {\it macaulay} or {\it lisp}.)

Comments:

\begin{enumerate}  \index{algforminput}
 \item Both {\bf algforminput}  parts, i. e., the input variable setting and the
   polynomial listing, are optional. You may thus give {\it lisp} form input,
   but perform {\bf algforminput} vars v1,...,vn; ; (NOTE the double ;),
   in order to enable {\it alg} or {\it macaulay} output. Of course, if you try
   to print polynomials when the variables are not set, you are in
   trouble.
 \item New successful (and non-empty) polynomial inputs replace old ones.
   Likewise, new successful input variable settings replace old ones.
   Running {\bf groebnerkernel} \index{groebnerkernel} (successfully)
   or
   {\bf clearideal}  \index{clearideal} kills the input
   polynomials, but not the variable settings.
 \item The implementation of {\bf algforminput} depends on specific PSL features,
   since the pure Standard Lisp has poor alternative scanning abilities.
   If  {\bf algforminput} should be disabled in some other
   implementation, and if
   you still wish to use algebraic output modes, then you must define
   the variable names in another way, using the internal
   representations. In {\bf bergman 0.9*} and the next versions, the output variable settings
   performed  by

        vars x,y,z;

   in the commutative case corresponds to
%ufn nado naoborot, navernoie: (SETQ !Out!Vars (QUOTE (x y z)))
%esli mi hotim biti posledovatelinimi. Hotia v ishodnice doljno biti imenno
%tac, mne cajetsia luchse vibrati bolee estetichnii variant.
%nfu


        ({\bf setq} O!u!tV!a!r!s ({\bf quote} (!x !y !z)))

   and in the non-commutative case corresponds to

        ({\bf setq} O!u!tV!a!r!s ({\bf quote} ((1 . !x) (2 . !y) (3 . !z))))  .

        \end{enumerate}
 


\section{Calculating and using series}
\label{add} 




\subsection{Hilbert series computation} \label{Hilbertseries}


There is a simple way to calculate the \index{Hilbert series} Hilbert
series in
non-commutative case: using the top level procedure \index{ncpbhgroebner} {\bf ncpbhgroebner.} The
previous chapter  
%ufn% luchse  dati ssilcu
%nfu%
contains all the explanations concerning its calling,
arguments and results. The only problem is that the Hilbert series computation is stopped
in the degree where the computation of the  corresponding Gr\"{o}bner 
basis was fi\-ni\-shed.
If you want to get the next power series coefficients you may continue computation and call two procedures:\\
\index{calctolimit} {\bf (calctolimit degree)}\\
\index{tdegreehseriesout} {\bf (tdegreehseriesout degree)}

\vspace{0.3cm}

Let us see an example. The file ``test.a'' should be the input file:
\begin{verbatim}
(setmaxdeg 10)
(setalgoutmode alg)
(algforminput)
vars x,y;
x*x-2*y*y;
\end{verbatim}


Here is the corresponding session:

%ufn nado vstaviti probeli mejdu imenami,
% inache resuiltat na bergmane catastrofichnii'')
%1 lisp>(ncpbhgroebner "test3.a" "test3.gb" "test3.pb" "test3.hs")
%ufn malencie bucvi seichas 'degreeenddisplay'
%nfu%

\begin{verbatim}

1 lisp>(ncpbhgroebner "test.a" "test.gb" "test.pb" "test.hs")
*** I turn on noncommutativity
nil
alg
t
*** Function `!O!L!D!D!E!D' has been redefined
*** Function `degreeenddisplay' has been redefined
%ufn malencie bucvi seichas 'degreeenddisplay'
% No. of Spolynomials calculated until degree 2: 0
% No. of ReducePol(0) demanded until degree 2: 0
% Time: 238


% No. of Spolynomials calculated until degree 3: 1
% No. of ReducePol(0) demanded until degree 3: 0
% Time: 289


% No. of Spolynomials calculated until degree 4: 2
% No. of ReducePol(0) demanded until degree 4: 0
% Time: 323

*** Function `degreeenddisplay' has been redefined
NIL
2 lisp> (calctolimit(getmaxdeg))
+t^5*(z^4+z^5)
+t^6*(z^5+z^6)
+t^7*(z^6+z^7)
+t^8*(z^7+z^8)
+t^9*(z^8+z^9)
+t^10*(z^9+z^10)
NIL
3 lisp> (tdegreehseriesout(getmaxdeg))
+6*z^5
+7*z^6
+8*z^7
+9*z^8
+10*z^9
+11*z^10
11
4 lisp>

\end{verbatim}


The resulting files are:\\

{\bf test.gb}:\\

\begin{verbatim}
% 2
-2*y^2+x^2,

% 3
-y*x^2+x^2*y,
\end{verbatim}

{\bf test.pbs}:\\

\begin{verbatim}
+t^2*(z^2)
+t^3*(z^2+z^3)
+t^4*(z^3+z^4)
\end{verbatim}


{\bf test.hs}:\\

\begin{verbatim}
+3*z^2
+4*z^3
+5*z^4
\end{verbatim}

As you can see, all calculations by {\bf ncpbhgroebner}
are done up to the degree 4 -- the last degree
%ufn%
in which the Gr\"{o}bner basis were done (though without generating a new element).
%ufn bilo: in the resulting Gr\"{o}bner basis.

Calling\\
{\bf (calctolimit (getmaxdeg))}\\
we obtain the continuation of Poincar\'{e}--Betti series and by\\
{\bf (tdegreehseriesout (getmaxdeg))}\\
the next terms of Hilbert series are displayed (but not saved in the file!)


If you prefer the interactive input/output  you can operate in the same 
manner with
the procedure  \index{simple} {\bf simple} as it is illustrated in the 
following example:



\begin{verbatim}
1 lisp> (noncommify)
NIL
2 lisp> (setmaxdeg 10)
10
3 lisp> (simple)
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form (noncomm.) input> vars x,y;
algebraic form (noncomm.) input> x*x-2*y*y;

+t^2*(z^2)
% 2
-2*y^2+x^2,

+t^3*(z^2+z^3)
% 3
-y*x^2+x^2*y,

+t^4*(z^3+z^4)

Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), 
     and run a new (SIMPLE).
NIL
4 lisp>  (calctolimit(getmaxdeg))
+t^5*(z^4+z^5)
+t^6*(z^5+z^6)
+t^7*(z^6+z^7)
+t^8*(z^7+z^8)
+t^9*(z^8+z^9)
+t^10*(z^9+z^10)
NIL
5 lisp>  (tdegreehseriesout(getmaxdeg)) 
+3*z^2
+4*z^3
+5*z^4
+6*z^5
+7*z^6
+8*z^7
+9*z^8
+10*z^9
+11*z^10
11
6 lisp>

\end{verbatim}
%ufn%
There are two ways
to compute Hilbert series in the commutative case.
The easy one {\bf(hilbert) } we consider at the end of this section.
The more complicated one will be useful to consider if the reader wants
to understand how {\bf bergman } is organized internally. For this method
%nfu%
it is necessary to
involve
several procedures. First of all,
 it is necessary to input the ring ideal variables and
generators calling {\bf algforminput} and following its prompt (if it
was not done before).
You can start Gr\"{o}bner basis calculation by means of two
procedures: \index{groebnerinit} {\bf groebnerinit} and
\index{groebnerkernel} {\bf groebnerkernel.}
Now the system is ready
to compute Hilbert series.

There are two main uses for the Hilbert series facilities: stand alone
and within the Hilbert series \index{interrupt strategy} interrupt strategy minor mode. The
interrupt strategy is very efficient and  more sophisticated, you can
find its explanation below (see sections \ref{limHS},\ref{comHS}).

Let us
deal here with the
first case.  You may get the Hilbert series
as a rational expression
$$\frac {p(t)}{(1-t)^ q},$$  or with
the power series coefficient for some specified $t $ degree(s).
The calculation is performed by procedure
\index{calcrathilbertseries} {\bf calcrathilbertseries.}
To see the result you should note that the global variables
\index{hilbertnumerator} {\bf hilbertnumerator} and
\index{hilbertdenominator} {\bf hilbertdenominator} represent a calculated
$$p(t)/(1-t)^q = (a_{n}t^n + a_{n-1}t^{n-1} + \,.\,.\,. +
a_0)/(1-t)^q $$
by (the Lisp items) $ ((n\  .\    a_n) (n-1\  .\    a_{n-1}) ... (0\  .\  a_0))$ and $
q$,
respectively.

To display the power series coefficients one may use the procedure\\
\index{tdegreehseriesout} {\bf tdegreehseriesout} giving the degree as argument.

Here is an example of Hilbert series computation.

\begin{verbatim}
1 lisp> (algforminput)
algebraic form input> vars x,y; x^3, x*y^2-x^2*y;
t
2 lisp> (groebnerinit)
SetupGlobals
 ... done
nil
3 lisp> (groebnerkernel)
d!O!N!E
4 lisp> (calcrathilbertseries)
nil
5 lisp> (setq p hilbertnumerator)
((4 . -1) (3 . -1) (2 . 1) (1 . 1) (0 . 1))
6 lisp> (setq q hilbertdenominator)
1
7 lisp>  (tdegreehseriesout 1)
2
8 lisp>  (tdegreehseriesout 2)
3
9 lisp>  (tdegreehseriesout 3) 
2
10 lisp> (tdegreehseriesout 4)
1
11 lisp> (tdegreehseriesout 5)
1
12 lisp> (tdegreehseriesout 6)
1
13 lisp> (tdegreehseriesout 7)
1
15 lisp> (groebnerfinish)

\end{verbatim}


The obtained result presented as a rational function is the following:
$$\frac {1+t+t^2 -t^3 - t^4 }{1-t}.$$ The sequence of
{\bf (tdegreehseriesout degree)} displays the corresponding power series
coefficients representing the series: $$ 1+2t+3t^2+2t^3+t^4+t^5+t^6+t^7
+\,.\,.\,. $$



All the functions listed abowe are collected in the procedure 
\index{hilbert} {\bf hilbert} destined to
commutative Hilbert series computation reducing the manipulation to
its call only. 
The previous example might be computed using this procedure:

\begin{verbatim}
1 lisp> (hilbert)
Input the maximal power series degree you want to calculate
1 lisp> 6
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input> vars x,y;
algebraic form input> x^3, x*y^2-x^2*y;
% 3
-x^2*y+x*y^2,
   x^3,

% 4
x*y^3,

Hilbert series numerator:   +1*t^0+1*t^1+1*t^2-1*t^3-1*t^4
Hilbert series denominator:  1-t
Hilbert power series:        1+2t^1+3t^2+2t^3+t^4+t^5+t^6+...
Done
\end{verbatim}

In this example both rational and power series are displayed. To avoid the last one
it is necessary to input the maximal power series degree 0.

To perform the input from a file one should prepare it including the following lines:

\begin{verbatim}
(setmaxdeg 6)
(algforminput)
vars x,y;
x^3, x*y^2-x^2*y;
\end{verbatim}

The corresponding call containing  one input file and two 
output files - for Gr\"{o}bner basis and Hilbert series  - looks like:

\begin{verbatim}
(hilbert ``input_file'' ``output_gb_file'' ``output_hs_file'')
\end{verbatim}



\subsection{Computation of  Gr\"{o}bner basis using known\\ Hilbert series}
\label{limHS}


It rather often happens that we know (at least partly) the Hilbert
 series before we start any computations. {\bf Bergman} proposes an 
efficient optimisation of the Gr\"{o}bner basis calculations in those cases.
 Here we 
learn us  how to translate our knowledge about the Hilbert
 series to {\bf bergman}. Let us consider a classical example.

Suppose that we want to calculate  Gr\"{o}bner basis of the following ideal 
(the corresponding system of equations, when $z=1,$ has a proper 
name ``6-cyclic roots system'')

$$a+b+c+d+e+f,$$

$$ ab+bc+cd+de+ef+fa,$$

$$ abc+bcd+cde+def+efa+fab,$$

$$ abcd+bcde+cdef+defa+efab+fabc,$$

$$ abcde+bcdef+cdefa+defab+efabc+fabcd,$$

$$ abcdef-z^6;$$

It is not so difficult to calculate Gr\"{o}bner basis  of this ideal - it takes (on our computer) about 7.72 sec. From the literature we can find that Hilbert series of the corresponding factor--ring is equal to
\begin{footnotesize}
$$\frac{1 +4t+9t^2+15t^3+20t^4+22t^5+19t^6+
  11t^7+t^8-7t^9-10t^{10}-12t^{11}-10t^{12}-5t^{13}+2t^{15}}{(1-t)^2}=$$
\end{footnotesize}
$$1 +6t+20t^2+49t^3+98t^4+169t^5+ 259t^6+ 360t^7+ 462t^8+ 557t^9+ 642t^{10}+ 715t^{11}+ $$ 
$$ +778t^{12} +836t^{13}+ 894t^{14}+  954t^{15}+ 1014t^{16}+ 1074t^{17}+ 1134t^{18}+ 1194t^{19}+\,.\,.\,.$$

The following session shows how to calculate Gr\"{o}bner basis  in 3.3 sec - more than twice faster!

\begin{verbatim}

1 lisp> (setinterruptstrategy minhilblimits) 
nil
2 lisp> (sethseriesminima 1 6 20 49 98 169 259 360 462 557 642
  715 778 836 894 954 1014 1074 1134 1194)
t
3 lisp> (simple "sixroots" "sixroots.bg")
t
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), 
     and run a new (SIMPLE).
nil
4 lisp> 
\end{verbatim}

Now some comments. In the first line {\bf bergman} is informed  that
the strategy of the computations is changed -- we want {\bf bergman} to stop the calculations in the current degree $d$
 when  the desired coefficient of the Hilbert series is achieved (in this degree). The next line describes coefficients  themselves.

 The idea is evident - we cannot get more nontrivial elements in this degree $d$ (otherwise Hilbert series will be less then it was prescribed). The responsibility of the user is clear too -- if the restrictions would be above the real coeffitient (for example, if we, by mistake, write 269 instead of 259 in the example above) the result of computations may be absolutely wrong.
To avoid such a situation (for example, when we are not sure in the part of the coefficients) one can use {\bf nil} instead of the numbers. This informs
{\bf bergman} that the calculations in this degree goes ``as usual''.

Another even more efficient application of this technique is skipping the
 Gr\"{o}bner basis calculations in those degrees when they were preliminary done before. Suppose that after a 20 hours of calculations we get a  Gr\"{o}bner basis until degree 4 and saved it in a file. The next day we use this file
(after minor changes) as input file but do not want to repeat calculation in the 
degree 4 or less. The solution is the line\\
{\bf (sethseriesminima skipcdeg skipcdeg skipcdeg skipcdeg skipcdeg) }\\
(note that we used 5 {\bf skipcdeg}s, because the first degree is 0).
Don't forget to precede this line by {\bf (setinterruptstrategy minhilblimits).} 

There is another
(more advanced) way of doing it, employing a little Lisp programming
(and that if the degree is - say - 15 instead of 5, then indeed this
may be the point to start entering the more advanced phase). The
actual programming might look like

{\bf (sethseriesminimumdefault (cond ((lessp hsdeg 5) skipcdeg)))}

or like

{\bf (sethseriesminima (default (cond ((lessp hsdeg 5) skipcdeg))))}

The complete information about the possibilities of using the function
{\bf (sethseriesminima)} the user should find in the section \ref{comHS}.

\section{The jumping \index{rabbit} rabbit} \label{rabbit}

 In this section we discuss the possibilities to perform
 non-homogeneous calculations. Let $A= <X|R>$ be an algebra we are
 interesting in and suppose that not all of elements of $R$ are
 homogeneous. One possible way to get a Gr\"{o}bner basis for $A$ is to homogenize
 all the relations using the additional variable $t$ and to calculate a Gr\"{o}bner basis 
 for another  algebra  $B=<X,t|R_h,tx-xt, x\in X>,$ where $R_h$ stands for the set of
homogenized relations. After dehomogenising the obtained Gr\"{o}bner basis for $B$ by
putting
$t=1.$ Though it works theoretically with some orders, which
eliminates $t,$ the problem is that even for the finite dimensional
algebra $A$ a Gr\"{o}bner basis for $B$ is usually  infinite. The reason
is that $B$ is not the same algebra as $C,$ which is obtained from $A$ by
homogenizing all the relations of $A$ (not only the defining relations!) That is why
 a reduced Gr\"{o}bner basis for $B$ contains a lot of elements of the form $ut^k,$
 where
$u=0$ in $C$ but not in $B.$ Therefore
after the dehomogenization 
we get a Gr\"{o}bner basis in $A$ that is far from being reduced. Thus it is practically 
impossible to  use  this approach for computing   the Gr\"{o}bner basis even 
for finite dimensional algebras.

To solve this problem {\bf bergman} suggests a special procedure {\bf rabbit}
which starts from $A,$ homogenizes the relations getting $B$ and then
calculates a reduced Gr\"{o}bner basis for $C$ instead of $B$ (more exactly, a part of
it until  the given degree  {\bf maxdeg}).

The trick is  to cancel all obtained elements of form $ut^k$ 
replacing them by $u.$  This  means  that after finishing
calculations
in some degree $m=\deg u$ and doing calculations in the degree $m+k$
we need to jump back to degree $m$ and restart the calculations
beginning from this degree! That is why the program is named rabbit
and takes  three parameters, which permit jumping to be organized
 in a more or less regular manner. The parameters are {\bf startdeg, jumpstep} and 
{\bf maxdeg}. So,
{\bf (rabbit startdeg jumpstep maxdeg)} is a call of the procedure, which works as follows. 
First it suggests to input generators and relations in usual manner starting from {\bf vars}. 
Second it homogenizes the input and starts to calculate a  Gr\"{o}bner basis degree after 
degree. When the  degree becomes equal to the {\bf startdeg} it
prepares for  jumping. It means that it collects all the elements of   Gr\"{o}bner basis 
which can be canceled by the homogenizing variable. When {\bf  jumpstep}   degrees mostly  are 
done the program checks if something  was collected. If not, the next {\bf  jumpstep} 
degrees should be done before the next checking. If yes, the canceling is performed and the
degree is reduced to the minimum degree of new obtained relations and the process continues 
in the same manner. It stops when {\bf maxdeg} is  achieved or when no new 
Gr\"{o}bner basis elements can be obtained. In  both cases the dehomogenization is 
performed and the result is printed, but in the first case a warning that the  Gr\"{o}bner 
basis may be wrong is displayed. Jumping during the process is always shown, but to 
display the intermediate homogeneous relations the program has to be run in the debug mode.


In the following example a  Gr\"{o}bner basis for  the algebra
$A=<a,b,c|ab=c,bc=a,ca=b> $ is calculated:

%\begin{footnotesize}
\begin{verbatim}
2 lisp> (rabbit 2 2 8)
algebraic form input> vars a,b,c;a*b-c, b*c-a, c*a-b;
SetupGlobals
 ... done
RABBIT: Added step, Maxdegree=4
 Jump number 1

RABBIT: Jump number 2

RABBIT: Jump number 3

RABBIT: Added step, Maxdegree=6
 Jump number 4

GB is completely calculated
Rabbit have finished jumping. GB is 
a*b-c,
   b^2-a^2,
   b*c-a,
   c*a-b,
   -c^2+a^2,
   a^3-c*b,
   -a^2*c+b*a,
   b*a^2-a*c,
   b*a*c-a*c*b,
   -c*b*a+a*c*b,
   
nil
\end{verbatim}
%\end{footnotesize}

We see that the  Gr\"{o}bner basis is calculated completely and there are only 8
nonempty normal words: $a,b,c,a^2,ac,ba,cb,cba.$  One can conclude that
a semigroup with our defining relations is in fact the  quaternion group 
(because it has 8 elements and has those relations).

As a rule it is possible to apply {\bf rabbit} with 0,1,2 or 3 parameters. 
The last case (with 3 integer parameters) corresponds to the example below.
If no parameters are given, then the values of the ``jumping variables'' are set to 0,1 and 20 correspondingly. If there are 1 or 2 parameters they should be file names.
The first (or the only) one is the input file, the second is destined to output.
An input file may look like the following:

\begin{verbatim}

(setrabbit 2 2 8)
(algforminput)
vars a,b,c;
a*b-c, b*c-a, c*a-b;

\end{verbatim} 
 where the first line sets the startdeg, jumpstep and maxdeg to 2,2 and 8 correspondingly applying the procedure \index{setrabbit} {\bf setrabbit}.

\section{Stability and Non-graded Algebras}
\label{stability}
Starting from the version 1.0 there is another, in some cases more efficient
(but not completely tested) possibility to make calculations in the non-graded
algebras. Instead of homogenisation and reducing to the graded case
{\bf bergman} can perform calculations directly. But this demands some changes
in modes. The main problem is that the leading monomials of the obtained
Gr\"obner basis elements are unstable: we do not know if such a monomial will
remain in
the final Gr\"obner basis, because during the calculations we can get a new
leading monomial of smaller degree which may be used to reduce it. This cannot
happen in the graded case, which is why we then may
relay on stability and do calculations more efficiently.

To inform  {\bf bergman} that the calculations are unstable the user has the
procedure \index{setstability} {\bf (setstability s)} with one parameter
{\bf s} which has the
value  {\bf t} if the calculations are stable and  {\bf nil} if not.
 There is a shorter call without parameter: \index{stabilise} {\bf (stabilise)}
and \index{destabilise} {\bf (destabilise)} correspondingly. 






 Other aspects that should be taken into account concern degrees.
 First we probably need one call \index{(setsafelowtermshandling}
{\bf (setsafelowtermshandling)} to save the
possibility to work with linear or constant terms (if we have them in input.
Second we cannot work degree-wise now (e.g. for output), because we normally do not know
if we cannot get the element of the lower degree later. To take care about this
the user should use call \index{setitemwise}  {\bf (setitemwise)}. Naturally the call
\index{setdegreewise} {\bf (setdegreewise)} restore degree-wise output (which is default value of this mode).

Here is an example for non-graded calculations:

%\vspace{1 cm}
\begin{verbatim}
2 lisp> (destabilise)
t
3 lisp> (setsafelowtermshandling)
quick
4 lisp> (setitemwise)
t
5 lisp> (simple)
Now input in-variables and ideal generators in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, and r1, ..., rm the generators.
algebraic form input> vars x,y,z; x*y-z, y*z-1;
SetupGlobals
 ... done
-z^2+x,
   y*z-1,
   x*y-z,
    - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), and run a new (SIMPLE).
nil
6 lisp>  
\end{verbatim}

\section{Some bricks to build your own procedures}
\label{bricks}

In this section we suppose that the user have already tried procedures, described above
and want to write his own, involving Gr\"{o}bner bases
calculations. {\bf Bergman} is an open system,
you have access to its source code, you can use each of its procedures as useful items in your own
 applications. There is a three levels hierarchy of procedures:

\begin{itemize}
\item the top--of--the--top level,
\item the top level,
\item the level of  internal using.
\end{itemize}

\index{simple} {\bf Simple} and \index{ncpbhgroebner} {\bf ncpbhgroebner}, for example,  are top--of--the--top procedures, they
solve completely some concrete problems  -- to compute  Gr\"{o}bner basis and series.
\index{algforminput} \index{groebnerinit} \index{groebnerkernel}
\index{groebnerfinish} But such procedures as {\bf algforminput, groebnerinit, groebnerkernel, groebnerfinish } belong to the top level.
The extended list of the top level procedures you can find in Chapter 3.

Users  are recommended to use the procedures from the first two levels, if they  would like to see
how the last level looks like, they  might  read the source code.


Here we describe
several  procedures that can help you to perform your  own calculations. The reader is already
familiar with part of them and now we want to explain more carefully  their functions. %We refer to the
%Lisp--appendix for more details about Lisp and will use Lisp--syntax
%without detailed explanations.

The first thing that might be necessary is input. If the user  wants algebraic
form of input  (instead of Lisp form) then the procedure {\bf algforminput }
 should be used. You have see, above several examples of its using.
 {\bf Algforminput } scans the
succeeding input for variables list and/or polynomial list in algebraic form. If you type its call
on the screen you get its prompt:


\begin{verbatim}

algebraic form input>

\end{verbatim}

and the system is waiting for the input list.

If you perform the input from a file, you should put in this file 
the line: {\bf (algforminput)} and {\bf vars}\ldots\ after that.



 Gr\"{o}bner basis calculations are organized in such a way that a user is able to include his
own operators inside them. For this purposes they are divided into 3 separate procedures:
\begin{itemize}
\item {\bf  groebnerinit, } \index{groebnerinit} that  initiates numerous internal variables. It should be called {\it after} selecting modes and
doing input.
\item {\bf groebnerkernel. } \index{groebnerkernel} Here the main calculations are performed.
The results of calculations are
saved in several variables and files (see section \ref{globals}).  
You can use them in your own procedures.

\item  {\bf groebnerfinish. } \index{groebnerfinish} This procedure closes all files and restores variables and flags.


\end{itemize}

The user can include his code between those three procedures (see
section \ref{Hilbertseries} as example of such the inclusion).

There exists   another way which demands less knowledge in the
Lisp programming. The user has a possibility to have  some minor influence
on computations or displaying the result using {\bf custstrategy} or 
{\bf custdisplay} mode.
\index{custstrategy }\index{custdisplay}
To do this simply write
\index{setcuststrategy }{\bf (setcuststrategy t)} or 
\index{setcustdisplay} {\bf (setcustdisplay t)} 
changing the corresponding mode 
(see \ref{refm}).

After that the user has a possibility to write (or, better to say, to rewrite)
 several own procedures to change the strategy of the calculations or the
displaying of the result. We refer to the section \ref{cust} for complete list 
of the procedures and here consider only one of them --
\index{degreeenddisplay} {\bf degreeenddisplay}. This top level procedure will be
 called immediately after the ending of the calculations in the current degree 
and exactly here we should ``explain'' to the computer what 
 we would like to have as output.

Of course, the most natural way to do it is to take the existing template
procedure which looks as 

\begin{verbatim}
(DE DEGREEENDDISPLAY () 
 (PROGN 
    (DEGREEOUTPUT) 
    (TERPRI)
    (PRIN2 "% No. of Spolynomials calculated until degree ")
    (PRIN2 (GETCURRENTDEGREE)) (PRIN2 ": ")  
    (PRINT NOOFSPOLCALCS)
    (PRIN2 "% Time: ") (PRINT (TIME))
))
\end{verbatim}

If  you have some difficulties to understand it (e.g. PRIN2 and TERPRI are some of the Lisp
printing procedures) you can find the explanation
 using index at the end of the book. But maybe it will be easier 
when you will see the example below.
  Suppose, we want to print
 the leading monomials instead of the
Gr\"obner basis elements. It is sufficient to replace the procedure
{\bf degreeprintout}, which prints all Gr\"obner basis elements
  by the existing procedure \index{degreelmoutput}
{\bf degreelmoutput} which prints the leading monomials only.

You can write it directly (or better in a separate file, suppose its name
is ``mydisplay''):

\begin{verbatim}
(DE DEGREEENDDISPLAY () 
  (PROGN 
     (DEGREELMOUTPUT) 
     (TERPRI)
     (PRIN2 "% No. of Spolynomials calculated until degree ")
     (PRIN2 (GETCURRENTDEGREE)) (PRIN2 ": ")  
     (PRINT NOOFSPOLCALCS)
     (PRIN2 "% Time: ") (PRINT (TIME))
))
\end{verbatim}

Now we do our usual calculations. We use {\bf dskin} to skip copying the file.

\begin{verbatim}
1 lisp> (setcustdisplay t)
nil
2 lisp> (dskin "mydisplay")
*** Function `degreeenddisplay' has been redefined
degreeenddisplay
nil
3 lisp> (simple)
Now input in-variables and ideal generators
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables,
and r1, ..., rm the generators.
algebraic form input> vars x,y;x*x-y*y,x*y;
SetupGlobals
 ... done
% 2
x*y
x^2


% No. of Spolynomials calculated until degree 2: 0
% Time: 30

% 3
y^3


% No. of Spolynomials calculated until degree 3: 1
% Time: 30

Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), and run a new (SIMPLE).
nil

\end{verbatim}

One can see we get the leading monomials only, as desired, time
and the number of S--polynomials.


\section{Modules over non-commutative algebras}



In the previous sections we have described how to work with the ring 
(more exactly with the algebra over a field $K$)
both in  the commutative and non-commutative cases. In this section we
 restrict ourselves to
non-commutative algebras only and will study modules over such algebras,
 and their homological properties.

Let $A$ be a non-commutative algebra and  $M$ be a right module $M$ over  $A.$
{\bf Bergman} does not consider the module $M$ as a special structure.
Instead {\bf bergman} works with a larger ring, that has  as  a generators set  the 
union of the generators for $A$ and $M$ and as the set of the relations the union
of the relations. This ring mathematically can be considered as the
  $A\otimes T(M),$ where $T(M)$ is the 
tensor algebra $$T(M)=K\oplus M\oplus M\otimes M+ M\otimes M\otimes M+\cdots,$$
and the multiplication is given by 
$$(a\otimes m_1\cdots\otimes m_r)\cdot (a'\otimes n_1\cdots\otimes n_s)=
a\otimes m_1\cdots\otimes m_ra'\otimes n_1\cdots\otimes n_s.$$

It is important to understand  how to extract the information from this extended ring
 to obtain the necessary results about the module $M.$ We use mainly mathematics
and partly some programming tricks to do this.
But we still are working with the ring (though large). Nevertheless the computations
of the Anick resolution are different in different cases and the user will get the
warning about the changing mode from RING to MODULE, or TWOMODULES. All the
procedures we describe below do changes automatically and those modes are important
for Anick calculations only.

The structure of the section is the following. First we describe how to get
Gr\"{o}bner basis and Hilbert series for modules. Then  the Anick resolution will be 
introduced and will be explained how to calculate Betti numbers for algebra
$A$ (i.e. dimensions
$B(i,j)=\dim\mbox{\it Tor}^A_{i,j}(K,K)$
in homological degree $i$ and  degree $j).$  Betti numbers can be printed in two
forms - ordinary $B(i,j)=\cdots$ and so-called Macaulay form, i.e.
in matrix form $C,$ where $C(k,l)=B(l,k+l).$ We do not loose any information because
$B(i,j)=0$ if $j<i.$

Using Anick resolution for the extended ring we will extract
  Anick resolution and Betti numbers for the right module (i.e.
$B(i,j)=\dim\mbox{\it Tor}^A_{i,j}(M,K)$
and will show how to proceed with the  right ideals, two-sided ideals,
factor-algebras (considered as right modules) and how to work with this 
for left modules.

Then we consider the most general case
$B(i,j)=\dim\mbox{\it Tor}^A_{i,j}(M,N)$. Since this employs the computer 
resources maximally, it should not be 
used in the previous cases (although of course this can be done).


At last we will show how to calculate the Hochschild homology of an algebra.


\subsection{Gr\"{o}bner basis for  modules over\\ non-commutative algebras}

To obtain a Gr\"{o}bner basis for a right  module $M$ over a non-commutative algebra $A$
it is sufficient to calculate the Gr\"{o}bner basis for the extended ring.
In other words, one needs to input the union of the set of variables and a set of 
generators for $M$ (considered as a right module)
and all algebra and module relations (in any order). What we get
is the set that is the union of two Gr\"{o}bner bases - one for the algebra and one
for our module. To distinguish them we need only to check the presence of a  module variables.
If an element contains a module variable (it should be on the first place if it was
a right module and on  the last if it was a left module) then the element belongs to 
the module Gr\"{o}bner basis.
Let us consider an example. Suppose we want to calculate a Gr\"{o}bner basis for the
right module $M=$ $<a,b|ax-by>$ over the algebra $A=<x,y|x^2-y^2>.$
We can do it (after the switching to the non-commutative mode),
 for example, with the help of the procedure {\bf simple}
(note the order we used in variable names - we want $x$ be larger than $y$ and
$a$ larger than $b$).


\begin{verbatim}
2 lisp>  (noncommify)
nil
3 lisp> (simple)
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables,
 and r1, ..., rm the generators.
algebraic form (noncomm.) input> vars y,x,b,a;x*x-y*y,a*x-b*y;
+t^2*(2*z^2)
% 2
x*x-y*y,
   a*x-b*y,
 
+t^3*(2*z^2+2*z^3)
% 3
x*y*y-y*y*x,
   a*y*y-b*y*x,
 
+t^4*(2*z^3+2*z^4)
Done
\end{verbatim}

What we get are  two  Gr\"{o}bner bases:
one for the algebra:
$$xx-yy,xy^2-y^2x$$
and another for the module:
$$ax-by,ay^2-byx.$$
Now we can construct a $K-$basis for $M,$ which consists of the normal words,
containing $a$ or $b$ on the first place and only algebra variables after them, i.e.:
$$a,b; ay, bx,by; ayx,bxy,byx,byy; ayxy,bxyx, byxy, byyx,byyy;\cdots$$
and we can even calculate the Hilbert series:
$$H_M(t)=2t+3t^2+4t^3+\cdots= \frac{2t-t^2}{(1-t)^2}.$$
Unfortunately we do not get the correct Hilbert series if we will try to use
the procedure {\bf ncpbhgroebner} - instead we get the Hilbert series for the
extended ring $R.$  But knowing it and the Hilbert series for algebra $A$ one
can obtain the Hilbert series for $M$ using the formula
$$  H_R=H_A\left(\frac{1}{1-H_M}\right).$$
But if the user needs a Hilbert series he can apply a procedure that uses this formula
and is described in the following section.

\subsection{Hilbert series for  modules over\\ non-commutative algebras}



It is possible to calculate both Gr\"{o}bner basis and Hilbert series for 
finitely-presented (right or left) modules.
Gr\"{o}bner bases and Hilbert series computations for  modules are
performed by the top level procedure \index{modulehseries} {\bf modulehseries.} 
It is necessary to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra  and module variables,
 (the algebra  variables should be at the beginning of the list),
\item the  algebra relations (more exactly - ideal generators, because instead of the
relation $r_i=0$ we input $r_i$ itself.)
\item the module relations.
\end{itemize}

The input/output may be performed from the screen or by means of files. 
Depending of 
this the procedure call may contain 0, 2, 3 or 4 parameters.

\begin{center}
{\bf Interactive input/output}.  
\end{center}

It is the simplest way to start the
computations. You should type only: {\bf (modulehseries)}

In this case a dialogue is initiated. The user is asked to input:
\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra  and module variables (the algebra 
  variables  should be at the beginning of the list) and the ideal generators,
\end{itemize}

Receiving this data the Gr\"{o}bner basis for ideal is calculated and user
is asked to input

\begin{itemize}
\item  the module relations.
\end{itemize}

Here is an example of computations over modules:

\begin{verbatim}
2 lisp> (modulehseries)
*** Function `modulehseries' has been redefined
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
2 lisp> 4
Input the number of module generators
2 lisp> 2
Now input ALL ring and module variables but ONLY
the ring ideal generators in algebraic form, thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, 
and r1, ..., rm the generators.
algebraic form (noncomm.) input> vars x,y,a,b;
algebraic form (noncomm.) input> x*x-y*y, x*y;
+t^2*(2*z^2)
% 2
x*y,
   -y^2+x^2,
   
+t^3*(2*z^2+2*z^3)
% 3
x^3,
   y*x^2,
   
+t^4*(6*z^3+2*z^4)
+14*z^2
+48*z^3
+168*z^4
Now input ONLY the module relations, 
thus:    r1, ..., rm;
where  r1, ..., rm are the module relations.
algebraic form (noncomm.) input> a*x-b*y;
+t^2*(3*z^2)
% 2
-b*y+a*x,

+t^3*(3*z^2+3*z^3)
% 3
b*x*x,

+t^4*(9*z^3+3*z^4)
Done
+13*z^2
+40*z^3
+127*z^4

Here is (1-H)^(-1) for the Hilbert series H of the module

 +1
 +2*t^1
 +7*t^2
+22*t^3
+69*t^4
Here is the Hilbert series H of the module
+2*t^1
+3*t^2
+2*t^3
nil
3 lisp>
\end{verbatim}

\begin{center}
{\bf Input from a file -- output on the screen} 
\end{center}

In this case you
should type
the procedure call with two parameters, which
are names of existing files.\\
{\bf (modulehseries $<$file1$>$ $<$file2$>$)}


The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}
\item the number of module generators defined by

{\bf (setq nmodgen number)} \index{nmodgen}

\item the procedure call to process the list of variables presented in
  algebraic form:

{\bf (algforminput)}


\item  the list of the algebra  and module variables (the algebra  variables 
should be at the beginning of the list). To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_n$;\\}

where $v_i$ are the algebra   and module variables, $r_i$ are the ideal 
generators {\bf only}. Note that the items are separated by commas and every list is ended
by semicolon.
\end{itemize}

Besides the above mentioned strings this file may contain flags and
variables setting etc. according to {\bf bergman} common rules
explained above and in the next chapter.

The file $<$file2$>$ should contain:

\begin{itemize}
\item the procedure call to process the list of variables presented in algebraic form:

{\bf (algforminput)}
\item the module relations:

$m_1,...,m_n$;
\end{itemize}

The file ``tesths1'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 16)
(setq nmodgen 2)
(algforminput)
vars z,y,x,b,a;
x*x, x*y+z*x;
\end{verbatim}

and the file ``tesths2'' is an example of $<$file2$>$:

\begin{verbatim}
(algforminput)
a*x*y-b*y*y+14*b*z*z,
a*z*z*z-b*x*z*y;
\end{verbatim}

\begin{center} { {\bf Errors messages}}. \end{center}

If there was only one parameter in the
parameter list it yields  the following message:\\
\newpage
{\bf ***It must be two input files.\\
Input data from keyboard\\}
and the system will turn to the interactive input/output mode.

If some file name is not a name of an existing file it yields the following message:\\
{\bf ***Input file must exist\\
Input data from keyboard\\}
and the system will turn to the interactive input/output mode.


\begin{center}
{\bf Input from the files -- output to one or two files} 
\end{center}

In this case the procedure 
call contains three or four parameters and looks like\\
{\bf (modulehseries $<$file1$>$ $<$file2$>$ $<$file3$>$ $<$file4$>$)}

The first two are input files and should respect all  the rules
mentioned above.
The third parameter is a file to output Gr\"{o}bner basis, the fourth is
destined for Hilbert series output. If the last parameter is absent only the Gr\"{o}bner basis
 will be printed in the file. Independently of the number of parameters, the resulted Gr\"{o}bner
 basis and Hilbert series always are displayed on the screen (in the two last cases the output is 
performed simultaneously in  files and on the screen). If the output file is one of the
existing it will be overwritten without some warning message.

\begin{center} { {\bf Errors messages}}. \end{center}
%{\large {\bf Errors messages}}.

If the name of the third file is incorrect (it is not
a quoted string), it yields the following message:\\
{\bf ***Incorrect output file.\\
 Do you agree to use the file outf\underline{ }mgb as output?\\
Type Yes or No}\\
and the system will be switched to waiting of input.


If your answer is Y (it means "Yes") the following message will be
displayed:\\
{\bf outf\underline{ }mgb is used as output file.\\
  Don't forget to rename it after calculations!}\\
and computing will continue using the file outf\underline{ }mgb as output file to print the 
resulting Gr\"{o}bner basis.

If your answer is N ("Not") the following message will be displayed:\\
{\bf No output file. Program is cancelled}\\
and {\bf bergman} will finish its work.

If the fourth parameter is incorrect an analogous dialogue appears pro\-po\-sing
to use the file outf\underline{ }mhs to output Hilbert series.




\subsection{The Anick resolution and Betti numbers for the tri\-vi\-al module}

\index{Anick resolution} The Anick resolution and \index{Betti numbers}
 the Betti numbers for $K$ as a trivial module
may be computed in the non-commutative
case. Resolution and Betti numbers for an arbitrary right module over
non-commutative ring are described in the  subsection \ref{onemodbetti}.

To perform the calculations it is necessary to apply the procedure 
\index{anick}{\bf anick}

It is necessary to input:
\begin{itemize}
\item the maximal degree of computation,
\item the list of the algebra  variables,
\item the algebra relations.
\end{itemize}

The input/output may be performed from the screen or by means of files. 
Depending of this the procedure call may contain 0, 1 or 2 parameters.

\begin{center}
{\bf Interactive input/output}
\end{center}

  This is the simplest way to start the
computations. You should type only:\\
{\bf (anick)}

In this case a dialog is initiated. The user is asked to input:

\begin{itemize}
\item the maximal degree of computation,
\item the list of the ideal variables and relations.
\end{itemize}



Here is an example of computation:
\begin{verbatim}

2 lisp> (anick)
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
2 lisp> 4

Now input in-variables and ideal generators 
in algebraic form, thus:
     vars v1, ..., vn;
      r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input> vars x,y; x*x+y*y+x*y+y*x;
The Anick resolution initialization...
B(1,1)=2
The Anick resolution initialization done.
+t^2*(z^2)
% 2
y^2+y*x+x*y+x^2,

Calculating the Anick resolution in degree 2...
B(1,1)=2
B(2,2)=1
    0   1   2
  +----------
0 | 1   2   1
1 | -   -
end of Calculations.
+t^3*(z^3)
Calculating the Anick resolution in degree 3...
B(1,1)=2
B(2,2)=1
B(3,3)=1
    0   1   2   3
  +--------------
0 | 1   2   1   1
1 | -   -   -
2 | -   -
end of Calculations.

Groebner basis is finite.
If you want to continue calculations until maximal degree
type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
3 lisp> (calculateanickresolutiontolimit (getmaxdeg))
Calculating the Anick resolution in degree 4...
B(1,1)=2
B(2,2)=1
B(3,3)=1
B(4,4)=1
    0   1   2   3   4
  +------------------
0 | 1   2   1   1   1
1 | -   -   -   -
2 | -   -   -
3 | -   -
end of Calculations.
nil
4 lisp> (anickdisplay)
Printing the results ...
Printing is done.
nil
5 lisp> (quit)
\end{verbatim}


The procedure prints in every degree new  Gr\"{o}bner basis elements
and all Betti numbers both in ordinary and Macaulay form. Sometimes
(when the Gr\"{o}bner basis is finite) it finishes the calculations before
the desired maximal degree is achieved. To continue the calulations
the user can write the suggested line \index{calculateanickresolutiontolimit}

{\bf (calculateanickresolutiontolimit (getmaxdeg))}

(e.g. copying from the prompt). Of course the number {\bf (getmaxdeg)} 
may be replaced by another one.
All the intermediate results, if any,  are printed on the terminal.



%Here should be comments about nil as input

The procedure {\bf (anick)} does not print the resolution itself, though calculates it.
To print the resolution and Betti numbers into a file one should use
the procedure \index{anickdisplay} {\bf (anickdisplay)}. 
It  prints the outcoming resolution in
the file which name is assigned to the variable
\index{anickresolutionoutputfile} {\bf anickresolutionoutputfile}.
 If no file name is assigned the
result by default will be printed in the file  \index{andifres} {\bf andifres.txt}.
Note that the assigment should be done before the call of {\bf (anick)},
for example as

\begin{verbatim}
(setq anickresolutionoutputfile "resolution.txt")
\end{verbatim}

Another important note is that this file is impossible to see before it will be closed.
In our example it was achieved simply by quitting {\bf bergman}.
 You can see the computed
resolution in the resulting file ({\bf andifres.txt} by default)
  in your current directory.

\begin{verbatim}

D(0, x)=1.x
D(0, y)=1.y
D(1, yy)=y.y+y.x+x.y+x.x
D(2, yyy)=yy.y+yy.x
D(3, yyyy)=yyy.y+yyy.x
B(1,1)=2
B(2,2)=1
B(3,3)=1
B(4,4)=1
    0   1   2   3   4
  +------------------
0 | 1   2   1   1   1
1 | -   -   -   -
2 | -   -   -
3 | -   -
\end{verbatim}



 D(1, yy)=y.y+y.x+x.y+x.x means that there exists the only 1-chain -- $yy$ and the
differential $d_1$ acts as
$$ d_1: y^2\otimes 1 \longrightarrow y\otimes y+y\otimes x+ x\otimes y +x\otimes x,$$ 
thus the sign ''.'' means the tensor product
(see more comments about the Anick resolution for example in  \cite{Anick-theory},\cite{Ufn98}).

To have a file input and screen output one 
should type\\

{\bf (anick $<$file1$>$)}

The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}. In fact this line may be omitted. In this case calculations
 will finish when the  Gr\"{o}bner basis will be completely calculated or be 
formally infinite (until there are enough resources).


\item the procedure call to process the list of variables presented in
  algebraic form:

{\bf (algforminput)}

\item  the list of the algebra  variables and the list of the algebra  relations.
 To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_n$;\\}

where $v_i$ are the algebra variables, $r_i$ are the algebra 
relations. Note that the items are separated by commas and every list is ended
by semicolon.
\end{itemize}



The following file``anick'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 4)
(algforminput)
vars x,y,a,b;
x*x-y*y, a*x-b*y;
\end{verbatim}

To have a file input and  file output for Gr\"{o}bner basis  one 
should type\\

{\bf (anick $<$file1$>$ $<$file2$>$)}


where $<$file2$>$ is an output file containing the corresponding 
 Gr\"{o}bner basis. Note that output file does not contain results 
related to the Anick resolution. For this purpose one should define before apply {\bf anick} the corresponding output file by {\bf (setq anickresolutionoutputfile $<$file3$>$)}.


\subsection{Writing own procedures}

The procedures described above and later are sufficient to make different
type of calculations of Betti numbers. Nevertheless the user can find their
output inconvenient or insufficient. To give him a possibility  to create
without problem his own procedure we will describe in this subsection how the
procedure {\bf anick} is organized.

Inside this short procedure the reader can find the following important lines:

{\bf (setringobject)} to switch to the RING mode,\\ 

{\bf (noncommify)}
 to switch to the
non-commutative mode and\\

{\bf (load anick)}
 to load the corresponding binary file.

Those lines are mandatory.


As usual,  doing non-commutative computations it is recommended to
limit  the process with some  maximal degree. Thus
the next procedure could be:\\
{\bf (setmaxdeg degree)}


Two following flags are switched on:
\begin{itemize}
\item {\bf (on calcbetti)} \index{calcbetti} -- turns on the Betti numbers
  calculation  mode. This flag is mandatory.
\item {\bf (on onflybetti)} \index{onflybetti} -- informs the application to calculate Betti
 numbers after each degree of Gr\"{o}bner basis is operated out.
 This allows to view Betti numbers degree by degree  during the
 Gr\"{o}bner basis computations. 
\end{itemize}

Both switches can be set on by the only procedure  
{\bf (onflybetti} {\it value} {\bf )}, where {\it value} should have the value T to switch ON and NIL for OFF.


After that the user can call {\bf simple},
 which performs all the calculations, one can obtain now
not only Gr\"{o}bner basis, but the Anick resolution and Betti numbers
also.
 But (s)he may also replace {\bf simple} 
 by the series of procedures, described in 
section  \ref{bricks}. 

 One useful procedure is
 \index{calculateanickresolutiontolimit} {\bf (calculateanickresolutiontolimit 
n)} which invokes
a method for calculation of the Anick resolution till the given degree
$n.$

All the intermediate results, if any,  are printed on the terminal.
Here is an example of the session which explains how the procedure {\bf anick}
works.

\begin{verbatim}
2 lisp> (setringobject)
nil
3 lisp> (noncommify)
nil
4 lisp> (load anick)
nil
5 lisp> (setmaxdeg 4)
nil
6 lisp> (onflybetti)
nil
7 lisp> (simple)
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input> vars x;x*x;
The Anick resolution initialization...
B(1,1)=1
The Anick resolution initialization done.
+t^2*(z^2)
% 2
x^2,
Calculating the Anick resolution in degree 2...
B(1,1)=1
B(2,2)=1
    0   1   2
  +----------
0 | 1   1   1
1 | -   -
end of Calculations.
+t^3*(z^3)
Calculating the Anick resolution in degree 3...
B(1,1)=1
B(2,2)=1
B(3,3)=1
    0   1   2   3
  +--------------
0 | 1   1   1   1
1 | -   -   -
2 | -   -
end of Calculations.
Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), 
     and run a new (SIMPLE).
nil
8 lisp>

\end{verbatim}




\subsection{The Anick resolution and Betti numbers for a right module}
\label{onemodbetti}

It is possible to calculate Anick resolution and Betti numbers for a graded right 
module over non-commutative algebra. The computation is performed by the top level
 procedure \index{modulebettinumbers} {\bf modulebettinumbers.} 
It is necessary to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra  and module variables
 (the algebra variables should be at the beginning of the list),
\item the algebra relations (more exactly -- the corresponding ideal generators,
but it will be convenient to call them relations 
to avoid in the future ambiguity in the interpretation of the word ``generators'')
\item the module relations.
\end{itemize}

The input/output may be performed from the screen or by means of files. 
Depending of this the procedure call may contain 0, 1 or 2 parameters.

\begin{center}
{\bf Interactive input/output}
\end{center}  

It is the simplest way to start the
computations. You should type only:\\
{\bf (modulebettinumbers)}

In this case a dialogue is initiated. The user is asked to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra and module variables (the algebra 
  variables  should be at the beginning of the list)
 and the algebra and module relations.
\end{itemize}

Here is an example of computations over modules:
\begin{verbatim}
1 lisp> (setq anickresolutionoutputfile  "resolution.txt")
"resolution.txt"
2 lisp> (modulebettinumbers)

*** We turn on the MODULE mode
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
2 lisp> 5
Input the number of the module variables
2 lisp> 1
Now input all ring and then all module variables.
Input  the ring ideal and module relations 
in algebraic form  thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, 
and r1, ..., rm the  relations.
algebraic form input>  vars x,a;x*x,a*x;
The Anick resolution initialization...
B(0,0)=1
The Anick resolution initialization done.
+t^2*(2*z^2)
% 2
x^2,
   a*x,

Calculating the module Anick resolution in degree 2...
B(0,0)=1
B(1,1)=1
    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.
+t^3*(2*z^3)
Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(1,1)=1
B(2,2)=1
    0   1   2   3
  +--------------
0 | 1   1   1
1 | -   -
2 | -
end of Calculations.

Groebner basis is finite.
If you want to continue calculations until the maximal 
degree type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
3 lisp>  (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(1,1)=1
B(2,2)=1
B(3,3)=1
    0   1   2   3   4
  +------------------
0 | 1   1   1   1
1 | -   -   -
2 | -   -
3 | -
end of Calculations.
Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(1,1)=1
B(2,2)=1
B(3,3)=1
B(4,4)=1
    0   1   2   3   4   5
  +----------------------
0 | 1   1   1   1   1
1 | -   -   -   -
2 | -   -   -
3 | -   -
4 | -
end of Calculations.
nil
4 lisp> (anickdisplay)
Printing the results ...
Printing is done.
nil
5 lisp> (quit)
\end{verbatim}
In this example the input is  performed from the screen and, 
correspondingly, the result is displayed on the screen also. The computed 
resolution you can see in the file {\bf resolution.txt} in your current 
directory.
For this example it contains just:
\begin{verbatim}
D(0, a)=1.a
D(1, ax)=a.x
D(2, axx)=ax.x
D(3, axxx)=axx.x
D(4, axxxx)=axxx.x
B(0,0)=1
B(1,1)=1
B(2,2)=1
B(3,3)=1
B(4,4)=1
    0   1   2   3   4   5
  +----------------------
0 | 1   1   1   1   1
1 | -   -   -   -
2 | -   -   -
3 | -   -
4 | -

\end{verbatim}

Note that in the case of  Betti numbers computations the module generators 
are considered as zero degree elements. That is why 
 the maximal degree 
 which  we have got  for Betti numbers is one less than the  maximal degree
 used in the Gr\"{o}bner basis calculations.

To have a file input and screen output one 
should type\\

{\bf (modulebettinumbers $<$file1$>$)}

The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}. In fact this line may be omitted. In this case calculations
 will finish when the  Gr\"{o}bner basis will be completely calculated or be 
formally infinite (until there are enough resources).

\item the number of module generators defined by

{\bf (setq nmodgen number)} \index{nmodgen} 

\item the procedure call to process the list of variables presented in
  algebraic form:

{\bf (algforminput)}

\item  the list of the algebra  and module variables (the algebra  variables should
 be at the beginning of the list) and the list of the algebra and module relations.
 To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_m$;\\}

where $v_i$ are the algebra   and module variables, $r_j$ are the algebra and module 
relations. Note that the items are separated by commas and every list is ended
by semicolon.
\end{itemize}

Besides the above mentioned strings this file may contain flags and
variables setting etc. according to {\bf bergman} common rules
explained above and in the next chapter.\\

The following file``bnmt'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 4)
(setq nmodgen 2)
(algforminput)
vars x,y,a,b;
x*x-y*y, a*x-b*y;
\end{verbatim}

To have a file input and  file output for Gr\"{o}bner basis  one 
should type\\

{\bf (modulebettinumbers $<$file1$>$ $<$file2$>$)}


where $<$file2$>$ is an output file containing the corresponding 
 Gr\"{o}bner basis. Note that output file does not contain results 
related to the Anick resolution.



\subsection{The minimal resolution and Betti numbers for a right module}
\label{minres}
 
There is another alternative to calculate Betti numbers for a graded 
right module using a minimal resolution. As it is well known, it may be constructed with the help of iterating  calculation of module syzigies.
 The corresponding internal procedure {\bf puresyzygies } 
 is described in the next chapter, it demands some knowledge from the user  -- see section \ref{puresyz}. In this section we describe another more convenient procedure  {\bf minr}, which takes 
rings and module generators and relations as input and return  the 
Poincare-Betti series, calculated with the help of the minimal resolution.
The resolution itself is not printed.
  In some cases the minimal resolution  is much more efficient  than Anick resolution, especially when the minimal resolution is finite. But for some cases
Anick resolution gives Betti numbers faster, so it is a good idea to test both.Note that they coincide in the case of monomial algebras. 

So is possible to calculate   Betti numbers for a graded right 
module over non-commutative algebra using the minimal resolution. The computation is performed by the top level
 procedure \index{minr} {\bf minr.} 
It is necessary to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra  and module variables
 (the algebra variables should be at the beginning of the list),
\item the algebra relations,
\item the module relations.
\end{itemize}

The input/output may be performed from the screen or by means of files. 
Depending of this the procedure call may contain 0, 1, 2 or 3 parameters.

\begin{center}
{\bf Interactive input/output}
\end{center}  

It is the simplest way to start the
computations. You should type only:\\
{\bf (minr)}

In this case a dialogue is initiated. The user is asked to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of module variables,
\item the list of the algebra and module variables (the algebra 
  variables  should be at the beginning of the list)
 and the algebra  relations,
\item the module relations.
\end{itemize}

Here is an example of computations:
\begin{verbatim}
2 lisp> (minr)
Input the Maximum Degree you want to calculate
2 lisp> 5
Input the number of module generators
2 lisp> 1
Now input ALL ring and module variables but ONLY
the ring ideal generators in algebraic form, thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, and r1, ..., rm the generators.
algebraic form input> vars x,y,a;x*x+x*y+y*x+y*y;
Now input  module elements:
algebraic form input> a*x,a*y;

*** We turn on the MODULE mode
SetupGlobals
 ... done

Current homological degree=2
Current Poincare-Betti series is
1t+2t^2z+1t^3z^2

Current homological degree=3
Current Poincare-Betti series is
1t+2t^2z+1t^3z^2+1t^4z^3

Current homological degree=4
Current Poincare-Betti series is
1t+2t^2z+1t^3z^2+1t^4z^3+1t^5z^4

Calculated Poincare-Betti series is
1t+2t^2z+1t^3z^2+1t^4z^3+1t^5z^4
nil
3 lisp>  
\end{verbatim}
In this example we calculate the Poincare-Betti series of a trivial module
(where its generator $a$ is assumed to have a degree $1$) over the ring
with one relations. The input was  performed from the screen and, 
correspondingly, the results (both intermediate and final) are displayed on the screen also.

Note that in the case of  Anick resolution module generators 
are considered as zero degree elements. That is why 
    we have got   Betti numbers shifted if we compare outputs
 for the same example.

If $0$ is chosen as maximum degree the calculations will be done until
it will be enough memory (if the Poincare-Betti series is infinite).

To have a file input and screen output one 
should type\\

{\bf (minr $<$file file2 $>$)}

The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}. In fact this line may be omitted. In this case calculations
 will finish when the  Gr\"{o}bner basis will be completely calculated or be 
formally infinite (until there are enough resources). The same result gives
{\bf (setmaxdeg 0)}  

\item the number of module generators defined by

{\bf (setq nmodgen number)} \index{nmodgen} 

\item the procedure call to process the list of variables presented in
  algebraic form:

{\bf (algforminput)}

\item  the list of the algebra  and module variables (the algebra  variables should
 be at the beginning of the list) and the list of the algebra  relations.
 To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_m$;\\}

where $v_i$ are the algebra   and module variables, $r_j$ are the algebra 
relations. Note that the items are separated by commas and every list is ended
by semicolon.
\end{itemize}

Besides the above mentioned strings the first file may contain modes and
variables setting etc. according to {\bf bergman} common rules
explained above and in the next chapter.\\

The file $<$file2$>$  contains the line {\bf (algforminput)} followed by module relations  and ended with the
semicolon. 





The following file``min1'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 8)
(setq nmodgen 1)
(algforminput)
vars x,y,z,a;x*y, y*x+z*z,x*x*z;
\end{verbatim}

\begin{verbatim}
(algforminput)
a*x,a*y,a*z;
\end{verbatim}

To have a file input and  file output for Gr\"{o}bner basis  one 
should type\\

{\bf (minr $<$file1$>$ $<$file2$>$)}

The result will be on the screen:

\begin{verbatim}
2 lisp> (minr "min1" "min2")
nil
1
t
t

*** We turn on the MODULE mode
SetupGlobals
 ... done

Current homological degree=2
Current Poincare-Betti series is
1t+3t^2z+2t^3z^2+1t^4z^2

Current homological degree=3
Current Poincare-Betti series is
1t+3t^2z+2t^3z^2+1t^4z^2+1t^5z^3+2t^6z^3
+1t^7z^3

Current homological degree=4
Current Poincare-Betti series is
1t+3t^2z+2t^3z^2+1t^4z^2+1t^5z^3+2t^6z^3
+1t^7z^3+4t^7z^4+3t^8z^4

Current homological degree=5
Current Poincare-Betti series is
1t+3t^2z+2t^3z^2+1t^4z^2+1t^5z^3+2t^6z^3
+1t^7z^3+4t^7z^4+3t^8z^4+2t^8z^5

Calculated Poincare-Betti series is
1t+3t^2z+2t^3z^2+1t^4z^2+1t^5z^3+2t^6z^3
+1t^7z^3+4t^7z^4+3t^8z^4+2t^8z^5
nil
3 lisp>  
\end{verbatim}

If the user wants output to be in the file he should use the third file:

{\bf (minr $<$file1$>$ $<$file2$>$ $<$fileout$> $)},

where $<$fileout$>$ is an output file.
 Note that output file  will  not contain results 
related to the minimal resolution itself. If the user wants to see the minimal resolution he should modify the procedure {\bf minr} taking away the
commented print commands.








\subsection{The Anick resolution and Betti numbers for right, 
two-sided ideals,
and factor-algebras, considered as  right modules}

Though we have a possibility to calculate Betti numbers for arbitrary
 module, we need to know defining relations for it and it is not always
 convenient. Here we describe another procedure that may be used for
 calculating Betti numbers for an ideal $ I$ in a given
algebra $ A.$ 
 
If I is a right ideal, generated by the set  $S$, then we can consider
a factor-module $ M= A/I$
and get an exact sequence $ I \rightarrow A \rightarrow M.$
 
The  Betti numbers for $ I  $ could be extracted  without 
problem from the Betti numbers for $ M$ (they are only shifted by one), but  the module $ M $ 
is nothing else
than a one-generated module. It means that
 we can use our   procedure {\bf modulebettinumbers} to calculate the  Betti
 numbers.
 
The situation is more complicated if $I$ is a two-sided ideal, generated by
a set $ S.$  In this case $ M$ is nothing else than the factor-algebra, 
and still is one-generated (considered as a right module).
 But now we do not know the defining relations for this module, because
$I $ was two-sided and we do not have generators for $I$ as a right ideal.
 
There is a special procedure {\bf factalgbettinumbers}  that solves this
problem. It calculates Betti numbers for $ M$ using only $S$ (and the  relations for $A$).
It has usual
parameters, described later, but to work with the input for this procedure 
the user should introduce additional variables and relations.
 
We start from the variable list {\bf vars.}  The  user needs the algebra variables,
a copy for every algebra variable,  and one additional variable for the module.
In the list of variables  the single module variable
should be in the middle - after
algebra variables and before their copies.
 
As to the relations, they should contain (in any order)
 all algebra relations,
all ideal generators, multiplied from the left by the module variable.


Some  additional relations of the form
\begin{center}
(copy of variable)*(module\_ variable)-(module\_ variable)*(variable)
\end{center}
for every variable of the algebra are generated automatically by the corresponding 
procedure. 
 
{\bf Example.} Suppose that  the algebra has $ x, y $ as variables and $ x*y $ as
single defining relation. We want to consider a two-sided ideal generated
 by $x$ and to calculate Betti numbers for a corresponding factor-algebra.
 
Suppose that we have selected the names $ X$ and $Y$ for copies of $ x $ and  $y $ 
and  $c $ for
 module variable. Then the input my look like

\begin{verbatim}
vars x,y,c,X,Y; x*y, c*x;
\end{verbatim}

 The computation is performed by the top level procedure \index{factalgbettinumbers} 
{\bf factalgbettinumbers.} It is necessary to input:

\begin{itemize}
\item the maximal degree of Gr\"{o}bner basis computation,
\item the list of the algebra variables,  the  module variable and copies of the algebra variables,
as it is described above.
\item the algebra relations, 
\item the ideal generators, multiplied by the module variable. 
\end{itemize}

The input/output may be performed from the screen or by means of files. Depending of this 
the procedure call may contain 0, 1 or 2 parameters.


\begin{center}
{\bf Interactive input/output}
\end{center}  

It is the simplest way to start the
computations. You should type only: {\bf (factalgbettinumbers)}

In this case a dialog is initiated. The user is asked to input:

\begin{itemize}
\item the maximal degree of computation,
\item the input list of  variables  and  relations.
\end{itemize}



Here is an example of computation:

\begin{verbatim}

1 lisp> (factalgbettinumbers)
*** We turn on the MODULE mode
*** Function `addadditionalrelations' has been redefined
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
1 lisp> 5
Now input all ring variables, a dummy variable (D),
and copies of the ring variables 
(in this order), in this manner:
    vars x1, ..., xn, D, y1, ..., yn;
(where x1,..., xn are the ring varables,
and y1,...,yn their copies)
Then input  the ring ideal relations 
(in ordinary algebraic form);
but the factor algebra relations in the form
     D*r1, ..., D*rm,
where r1, ..., rm are the relations.
algebraic form input>  vars x,y, D, X,Y;
algebraic form input>  x*y,y*x, y*y,D*x*x;
*** Function `addadditionalrelations' has been redefined
The Anick resolution initialization...
B(0,0)=1
The Anick resolution initialization done.
+t^2*(5*z^2)
% 2
x*y,
   y*x,
   y^2,
   X*D-D*x,
   Y*D-D*y,

Calculating the module Anick resolution in degree 2...
B(0,0)=1
    0   1
  +------
0 | 1
end of Calculations.
+t^3*(z^2+5*z^3)
% 3
D*x^2,

Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(1,2)=1
    0   1   2   3
  +--------------
0 | 1   -   -
1 | -   1
2 | -
end of Calculations.
+t^4*(3*z^3+8*z^4)
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(1,2)=1
B(2,3)=1
    0   1   2   3   4
  +------------------
0 | 1   -   -   -
1 | -   1   1
2 | -   -
3 | -
end of Calculations.

Groebner basis is finite.
If you want to continue calculations until the maximal 
degree type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
2 lisp> (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(1,2)=1
B(2,3)=1
B(3,4)=2
    0   1   2   3   4   5
  +----------------------
0 | 1   -   -   -   -
1 | -   1   1   2
2 | -   -   -
3 | -   -
4 | -
end of Calculations.
nil
3 lisp> (anickdisplay)
Printing the results ...
Printing is done.

\end{verbatim}


In this example the input is  performed from the screen and, 
correspondingly, the result is displayed on the screen also. The computed 
resolution you can see in the file {\bf andifres.txt} in your current 
directory.

For this example it contains just:\\

\begin{verbatim}
D(0, D)=1.D
D(1, Dx^2)=D.x^2
D(2, Dx^2y)=Dx^2.y
D(3, Dx^2yx)=Dx^2y.x
D(3, Dx^2yy)=Dx^2y.y
B(0,0)=1
B(1,2)=1
B(2,3)=1
B(3,4)=2
    0   1   2   3   4   5
  +----------------------
0 | 1   -   -   -   -
1 | -   1   1   2
2 | -   -   -
3 | -   -
4 | -

\end{verbatim} 

Note that in the case of  Betti numbers computations the module generators 
are considered as zero degree elements. That is why 
 the maximal degree 
 which  we have got  for Betti numbers is one less than the  maximal degree
 used in the Gr\"{o}bner basis calculations. One can see in the second degree 
of Groebner basis the automatically generated additional realtions $X*D-D*x, Y*D-D*y.$



To have a file input and screen output one 
should type\\

{\bf (factalgbettinumbers $<$file1$>$ )}

The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}


\item the procedure call to process the list of variables presented in algebraic form:

{\bf (algforminput)}

\item the input list of  variables  and  relations. To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_n$;\\}

where $v_i$ are the algebra, module or copy variables, $r_i$ are all the relations. 
Note that the items are separated by commas and every list is ended by semicolon.
\end{itemize}

Besides the above mentioned strings this file may contain flags and
variables setting etc. according to {\bf bergman} common rules
explained above and in the next chapter.

The following file``ftinput'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 8)
(algforminput)
vars  x,y,c,X,Y;
x*y,  c*x;
\end{verbatim}


One can apply {\bf factalgbettinumbers} with two parameters:

{\bf (factalgbettinumbers $<$file1$>$ $<$file2$>$)}

The $<$file2$>$ is an output file containing the corresponding  Gr\"{o}bner basis.

Sometimes,  especially if the  Gr\"{o}bner basis is finite,
 the calculation of the Anick resolution can be stopped
before the desired degree is  achieved. One can see in the example how to continue 
the computing using
the procedure \index{calculateanickresolutiontolimit}
 {\bf (calculateanickresolutiontolimit)}.


The procedure \index{anickdisplay} {\bf (anickdisplay)}  prints the complete resolution
(with the differentials) into
the file. Because no file name was assigned to the variable
\index{anickresolutionoutputfile} {\bf anickresolutionoutputfile} the
result by default was printed into the file  \index{andifres} {\bf andifres.txt}.



\subsection{Working with the left modules}

We have described some procedures for the right modules. The user might expect that
the same procedure can be used for the left modules, but it is not the case
for the procedures calculating resolution and Betti numbers. The reason is that   
the Anick resolution is constructed as an exact sequence of right modules, and this
was essentially used in programming. Of course,  it would be possible to program
the left variant too, but it is much less trivial than one might expect.
There is the only  procedure designed to operate with left modules: 
 \index{leftmodulebettinumbers} {\bf leftmodulebettinumbers}. Let us see an example of
its applying:

\begin{verbatim}
1 lisp>  (leftmodulebettinumbers)
Input the Maximum Degree you want to calculate
1 lisp> 5
Input the number of the module variables
1 lisp> 1
Now input all ring and then all module variables.
Input  the ring ideal and module relations 
in algebraic form  thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, 
and r1, ..., rm the  relations.
algebraic form input> vars x,a; x*x, x*a;
The Anick resolution initialization...
B(0,0)=1
The Anick resolution initialization done.
+t^2*(2*z^2)
% 2
x^2,
   a*x,

Calculating the module Anick resolution in degree 2...
B(0,0)=1
B(1,1)=1
    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.
+t^3*(2*z^3)

Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(1,1)=1
B(2,2)=1
    0   1   2   3
  +--------------
0 | 1   1   1
1 | -   -
2 | -
end of Calculations.

Groebner basis is finite.
If you want to continue calculations until the maximal 
degree type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
2 lisp> (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(1,1)=1
B(2,2)=1
B(3,3)=1
    0   1   2   3   4
  +------------------
0 | 1   1   1   1
1 | -   -   -
2 | -   -
3 | -
end of Calculations.
Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(1,1)=1
B(2,2)=1
B(3,3)=1
B(4,4)=1
    0   1   2   3   4   5
  +----------------------
0 | 1   1   1   1   1
1 | -   -   -   -
2 | -   -   -
3 | -   -
4 | -
end of Calculations.
nil
3 lisp>

\end{verbatim}


As you see the procedure simply calculates in the corresponding right module, using the fact that the Betti numbers are the same.
Unfortunately, there are no more special left module processing procedures in {\bf bergman.}
 Instead the user
should use mathematical approach and replace a left module $N$  over an
algebra $A$ by the right module $M$ over the algebra $A^{op}.$ What one need to do is
only  to rewrite
all words in the defining relations in the inverse order (as you see, it was done automatically above).  For example, if one
have two relations:  $x*y+ y*y $ in the algebra and  $y*x*a+2*y*x*b $
 in the module they should 
be replaced by  $y*x+y*y $ and  $a*x*y+2*b*x*y $ correspondingly.

{\bf Example.} We would like to know if the two-sided ideal $I,$ generated in the algebra
$A=<x,y|xx-xy>$ by the element $x$ has the same Betti numbers considered as a right
or as  a left module. The following session gives us both calculations 
(we start from the right module and after that perform computing for the left module).

\begin{verbatim}
2 lisp>  (factalgbettinumbers)

*** We turn on the MODULE mode
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
2 lisp> 4
Now input all ring variables, a dummy variable (D),
and copies of the ring variables 
(in this order), in this manner:
    vars x1, ..., xn, D, y1, ..., yn;
(where x1,..., xn are the ring varables,
and y1,...,yn their copies
Then input  the ring ideal relations 
(in ordinary algebraic form);
but the factor algebra relations in the form
     D*r1, ..., D*rm,
where r1, ..., rm are the relations.
Finally, input the dummy commutators
   y1*D-D*x1, ..., ym*D-D*ym;
algebraic form input>  vars x,y,c, X,Y;
algebraic form input>  x*x-x*y, c*x;
The Anick resolution initialization...
B(0,0)=1
The Anick resolution initialization done.
+t^2*(4*z^2)
% 2
-x*y+x^2,
   c*x,
   X*c,
   Y*c-c*y,
   
Calculating the module Anick resolution in degree 2...
B(0,0)=1
B(1,1)=1

    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.
+t^3*(z^2+3*z^3)
% 3
c*y*x,
   
Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(1,1)=1
B(1,2)=1
B(2,2)=1
    0   1   2   3
  +--------------
0 | 1   1   1
1 | -   1
2 | -
end of Calculations.
+t^4*(z^2+3*z^3+2*z^4)
% 4
c*y^2*x,
   
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(1,1)=1
B(1,2)=1
B(2,2)=1
B(1,3)=1
B(2,3)=1
    0   1   2   3   4
  +------------------
0 | 1   1   1   -
1 | -   1   1
2 | -   1
3 | -
end of Calculations.

nil
3 lisp>  (clearideal)
Closing the streams.Cleaning the variables
nil
4 lisp> (factalagbettinumbers)
Input the Maximum Degree you want to calculate
4 lisp> 4
Now input all ring variables, a dummy variable (D),
and copies of the ring variables 
(in this order), in this manner:
    vars x1, ..., xn, D, y1, ..., yn;
(where x1,..., xn are the ring varables,
and y1,...,yn their copies
Then input  the ring ideal relations 
(in ordinary algebraic form);
but the factor algebra relations in the form
     D*r1, ..., D*rm,
where r1, ..., rm are the relations.
Finally, input the dummy commutators
   y1*D-D*x1, ..., ym*D-D*ym;
algebraic form input>  vars x,y,c, X,Y;
algebraic form input>  x*x-y*x,c*x;
The Anick resolution initialization...
B(0,0)=1
The Anick resolution initialization done.
+t^2*(4*z^2)
% 2
-y*x+x^2,
   c*x,
   X*c,
   Y*c-c*y,
   
Calculating the module Anick resolution in degree 2...

B(0,0)=1
B(1,1)=1

    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.
+t^3*(2*z^3)
Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(1,1)=1
    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.

Groebner basis is finite.
If you want to continue calculations until the maximal 
degree type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
5 lisp> (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(1,1)=1
    0   1   2
  +----------
0 | 1   1
1 | -
end of Calculations.
nil 
\end{verbatim}

Note that the only difference is  the term $y*x$ instead of $x*y,$ because other terms
($x*x$ and $x$) are symmetric, but the results are quite different. Also note that
in fact we could skip the call of the procedure
 {\bf calculateanickresolutiontolimit}, because we could see that degree 3
was already proceeded and gave a different result.



\subsection{Betti numbers for two modules}

Here we describe a procedure that calculates
the Betti numbers  for the most general situation, when we have two modules:
a right $A$-module $M$ and a left $A$-module $N$ and want to know the dimensions
$B(i,j)=\mbox{\it Tor}^A_{i,j}(M,N)$ in every homological degree $i$ and degree $j$ as
a vector graded space. Note that the procedure takes a lot of resources and it is
 recommended to use the procedures, described above for those special cases where they 
can be applied.


 The computation is performed by the top level
 procedure \index{twomodbettinumbers} {\bf twomodbettinumbers.} 
It is necessary to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of the right module variables,
\item the number of the left module variables,
\item the list of the algebra  and module variables
 (the algebra variables should be at the beginning of the list,
followed by right module variables. 
The left module variables should be at the end of the list.)
\item the algebra and both module relations (in arbitrary order).
\end{itemize}

The input/output may be performed from the screen or by means of files. 
Depending of this the procedure call may contain 0, 1 or 2 parameters.

\begin{center}
{\bf Interactive input/output}
\end{center}

  It is the simplest way to start the
computations. You should type only:\\
{\bf (twomodbettinumbers)}

In this case a dialogue is initiated. The user is asked to input:

\begin{itemize}
\item the maximal degree of computation,
\item the number of the right module variables,
\item the number of the left module variables,
\item the list of the algebra and module variables (the algebra 
  variables  should be at the beginning and
the left module variables should be at the end of the list.)
 and the ideal and module relations.
\end{itemize}



Here is an example of computations over modules:

\begin{verbatim}
1 lisp> (twomodbettinumbers)

*** We turn on the TWOMODULES mode
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
1 lisp> 6
Input the number of the right  module variables
1 lisp> 1
Input the number of the left  module variables
1 lisp> 1
Now input all ring and then all module variables.
Right module variables should be before the left ones.
Input  the ring ideal and module relations 
in algebraic form  thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, 
and r1, ..., rm the  relations.
algebraic form input> vars x,y,r,l;
algebraic form input> r*x, y*l-x*l;
SetupGlobals
 ... done
The Anick resolution initialization (for two modules)...
The Anick resolution initialization done.
+t^2*(2*z^2)
% 2
y*l-x*l,
   r*x,

Calculating the module Anick resolution in degree 2...
B(0,0)=1

    0   1   2
  +----------
0 | 1

end of Calculations.

Groebner basis is finite.
If you want to continue calculations until the maximal 
degree type (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
nil
2 lisp> (CALCULATEANICKRESOLUTIONTOLIMIT (GETMAXDEG))
Calculating the module Anick resolution in degree 3...
B(0,0)=1
    0   1   2
  +----------
0 | 1
end of Calculations.
Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(0,2)=1
    0   1   2   3   4
  +------------------
0 | 1   -   -
1 | -   -
2 | 1
end of Calculations.
Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(0,2)=1
B(0,3)=2
    0   1   2   3   4   5
  +----------------------
0 | 1   -   -   -
1 | -   -   -
2 | 1   -
3 | 2
end of Calculations.
Calculating the module Anick resolution in degree 6...
B(0,0)=1
B(0,2)=1
B(0,3)=2
B(0,4)=4
    0   1   2   3   4   5   6
  +--------------------------
0 | 1   -   -   -   -
1 | -   -   -   -
2 | 1   -   -
3 | 2   -
4 | 4
end of Calculations.
nil
3 lisp>
\end{verbatim}

In our example the algebra is free - there were no algebra relations.
Note that in the case of  Betti numbers computations the module generators 
(both left and right)
are considered as zero degree elements. That is why 
 the maximal degree 
 which  we have got  for Betti numbers is two less than the  maximal degree
 used in the Gr\"{o}bner basis calculations.

In this example the input is  performed from the screen and, correspondingly,
 the result is displayed on the screen also.
To have a file input and screen output one 
should type\\

{\bf (twomodbettinumbers $<$file1$>$)}

The file $<$file1$>$ should contain:

\begin{itemize}
\item the maximal degree of computation defined by

{\bf (setmaxdeg degree)}. In fact this line may be omitted. In this case calculations
 will finish when the  Gr\"{o}bner basis will be completely calculated or be 
formally infinite (until the resources are exhausted).

\item the number of the right module generators defined by

{\bf (setq nrmodgen number)} \index{nrmodgen} 

\item the number of the left module generators defined by

{\bf (setq nlmodgen number)} \index{nlmodgen} 
\item the procedure call to process the list of variables presented in
  algebraic form:

{\bf (algforminput)}

\item  the list of the algebra  and module variables (in the order described above)
 and the list of the ideal and module relations.
 To input them it is necessary to write
(without brackets!):

{\bf vars $v_1, ... , v_n$;\\
$r_1,...,r_n$;\\}

where $v_i$ are the algebra   and module variables, $r_i$ are the ideal and module 
relations. Note that the items are separated by commas and every list is ended
by semicolon.
\end{itemize}

Besides the above mentioned strings this file may contain flags and
variables setting etc. according to {\bf bergman} common rules
explained above and in the next chapter.\\

The following file``twomodtest'' is an example of $<$file1$>$:

\begin{verbatim}
(setmaxdeg 4)
(setq nrmodgen 2)
(setq nlmodgen 2)
(algforminput)
vars  x,y,A1,A2,B1,B2;
x*x+x*y+y*x+y*y,
A1*x*x+A2*y*y,A1*y*y,y*x*B1+x*y*B2,y*y*y*B1;
\end{verbatim}

To have a file input and  file output for the Gr\"{o}bner basis  one 
should type {\bf (twomodbettinumbers $<$file1$>$ $<$file2$>$)}
where $<$file2$>$ is an output file containing the corresponding 
 Gr\"{o}bner basis. Note that output file does not contain results 
related to the Anick resolution.







\subsection{Calculating Hochschild homology of an algebra}

Let $A$ be an algebra over $K,$ $A^{op}$ be the opposite algebra and $A^e=A\otimes A^{op}.$
It is known that in this situation  $A$ is $K-$flat and
its Hochschild homology  $H_n(A)$ can be obtained by the isomorphism
$$H_n(A)=\mbox{\it Tor}^{A^e}_{n}(A,A),$$
where $A$ is considered both as right and left $A^e-$ module.
Because we have a possibility to calculate $\mbox{\it Tor}^{A^e}_{n}(A,A)$ we need only to know
how to get the defining relations for the algebra  $A^e,$ right $A^e-$ module $A$ and
left $A^e-$module $A.$

Besides the original variables $x,y\ldots$ of the algebra $A$ we need copies of them
(for example $X,Y\ldots)$ to generate the algebra $A^{op},$ and two variables (for example,
$r$ and $l$ ) for  the right  $A^e-$ module $A$ and
left $A^e-$module $A.$

Now let us consider the relations. We need, of course, the defining 
relations for $A,$  and the relations for $A^{op},$
which we get from $A$ by reverting all the monomials
 and replacing variables by their copies.

To create  $A^e$ we need only to add the commutativity relations between all variables
and all copies:
$$xX-Xx, xY-Yx, yX-Xy, yY-Yy\cdots$$

And at last the module relations should be appended. For the right module they looks like $rx-rX, ry-rY\cdots$
i.e. module generator, multiplied by the difference $x-X$ between a variable and its copy for
every variable $x.$  Note that as a right $A^e-$module $A$
is isomorphic to the  factor module
$$A^e/(x\otimes 1 - 1\otimes x)A^e+
(y\otimes 1 - 1\otimes y)A^e+\cdots, $$
so the corresponding cyclic right module get the relations 
$rx-rX, ry-rY,\cdots.$  For the left module
we need, of course the symmetric variant: $xl-Xl, yl-Yl\cdots.$

Let us consider an example. Suppose that we want to calculate the 
Hochschild homology of the algebra $A=<x,y|xy=0>.$ The session looks as following:

\begin{verbatim}
2 lisp> (twomodbettinumbers)

*** We turn on the TWOMODULES mode
*** We turn on noncommutativity
Input the Maximum Degree you want to calculate
2 lisp> 5
Input the number of the right  module variables
2 lisp> 1
Input the number of the left  module variables
2 lisp> 1
Now input all ring and then all module variables.
Right module variables should be before the left ones.
Input  the ring ideal and module relations 
in algebraic form  thus:
      vars v1, ..., vn;
       r1, ..., rm;
where v1, ..., vn are all the variables, 
and r1, ..., rm the  relations.
algebraic form input> vars x,y,X,Y,r,l;  
algebraic form input> x*y,Y*X, x*X-X*x, 
algebraic form input> x*Y-Y*x, y*X-X*y, y*Y-Y*y,
algebraic form input> r*x-r*X, r*y-r*Y, x*l-X*l, y*l-Y*l;
The Anick resolution initialization (for two modules)...
The Anick resolution initialization done.
+t^2*(10*z^2)
% 2
x*y,
   -X*x+x*X,
   -X*y+y*X,
   -X*l+x*l,
   -Y*x+x*Y,
   -Y*y+y*Y,
   Y*X,
   -Y*l+y*l,
   -r*X+r*x,
   -r*Y+r*y,

Calculating the module Anick resolution in degree 2...
B(0,0)=1

    0   1   2
  +----------
0 | 1
end of Calculations.
+t^3*(4*z^2+12*z^3)
% 3
r*x*X-r*x^2,
   -r*y*x+r*x*Y,
   r*y*X,
   r*y*Y-r*y^2,

Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(0,1)=2
B(1,1)=2

   0   1   2   3
  +--------------
0 | 1   2
1 | 2
end of Calculations.
+t^4*(4*z^2+11*z^3+6*z^4)
% 4
r*x^2*X-r*x^3,
   -r*y^2*x+r*x*Y^2,
   r*y^2*X,
   r*y^2*Y-r*y^3,

Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(0,1)=2
B(1,1)=2
B(0,2)=2
B(1,2)=2
    0   1   2   3   4
  +------------------
0 | 1   2   -
1 | 2   2
2 | 2
end of Calculations.
+t^5*(4*z^2+11*z^3+6*z^4+z^5)
% 5
r*x^3*X-r*x^4,
   -r*y^3*x+r*x*Y^3,
   r*y^3*X,
   r*y^3*Y-r*y^4,
 
Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(0,1)=2
B(1,1)=2
B(0,2)=2
B(1,2)=2
B(0,3)=2
B(1,3)=2
    0   1   2   3   4   5
  +----------------------
0 | 1   2   -   -
1 | 2   2   -
2 | 2   2
3 | 2
end of Calculations.

\end{verbatim}

Once again, the maximal degree of Betti numbers is two less than maximal degree
we used in Gr\"{obner} basis calculations.

Instead of universal  procedure {\bf twomodbettinumbers} it is possibly to use a more 
convenient one \index{hochschild}{\bf hochschild} designed especially for this purpose. In fact, it 
performs the same  calculations, but the additional relations are generated 
automatically.

The following example (using the same variables and relations as above) illustrates 
its application:

\begin{verbatim}
4 lisp> (hochschild)
*** Function `addadditionalrelations' has been redefined
Input the Maximum Degree you want to calculate
4 lisp> 5


Now input all ring variables, copies of the ring variables,
  and two dummy variable (D1,D2) 
(in this order), in this manner:
    vars x1, ..., xn,  y1, ..., yn, D1, D2;
(where x1,..., xn are the ring varables,
and y1,...,yn their copies)
Then input  the ring ideal relations 
(in ordinary algebraic form);
       r1, ..., rm;

algebraic form input> vars  x,y, X,Y,r,l;
algebraic form input> x*y;
*** Function `addadditionalrelations' has been redefined
The Anick resolution initialization (for two modules)...
The Anick resolution initialization done.
+t^2*(10*z^2)
% 2
x*y,
   -X*x+x*X,
   -X*y+y*X,
   X*l-x*l,
   -Y*x+x*Y,
   -Y*y+y*Y,
   Y*X,
   Y*l-y*l,
   r*X-r*x,
   r*Y-r*y,

Calculating the module Anick resolution in degree 2...
B(0,0)=1
    0   1   2
  +----------
0 | 1
end of Calculations.
+t^3*(4*z^2+12*z^3)
% 3
r*x*X-r*x^2,
   -r*y*x+r*x*Y,
   r*y*X,
   r*y*Y-r*y^2,

Calculating the module Anick resolution in degree 3...
B(0,0)=1
B(0,1)=2
B(1,1)=2
    0   1   2   3
  +--------------
0 | 1   2
1 | 2
end of Calculations.
+t^4*(4*z^2+11*z^3+6*z^4)
% 4
r*x^2*X-r*x^3,
   -r*y^2*x+r*x*Y^2,
   r*y^2*X,
   r*y^2*Y-r*y^3,

Calculating the module Anick resolution in degree 4...
B(0,0)=1
B(0,1)=2
B(1,1)=2
B(0,2)=2
B(1,2)=2
    0   1   2   3   4
  +------------------
0 | 1   2   -
1 | 2   2
2 | 2
end of Calculations.
+t^5*(4*z^2+11*z^3+6*z^4+z^5)
% 5
r*x^3*X-r*x^4,
   -r*y^3*x+r*x*Y^3,
   r*y^3*X,
   r*y^3*Y-r*y^4,

Calculating the module Anick resolution in degree 5...
B(0,0)=1
B(0,1)=2
B(1,1)=2
B(0,2)=2
B(1,2)=2
B(0,3)=2
B(1,3)=2
    0   1   2   3   4   5
  +----------------------
0 | 1   2   -   -
1 | 2   2   -
2 | 2   2
3 | 2
end of Calculations.

nil
5 lisp>
\end{verbatim}

One can see all the automatically generated additional relations in degree 2
of Gr\"{o}bner basis.

\section{Bergman under Reduce} \label{reduce}


\subsection{Working in the Reduce syntax}

Starting {\bf bergman} you are in the algebraic mode of Reduce.
\index{Reduce mode}
It means that
you have the possibility to work in the Reduce syntax, and someone
could prefer it because the notation is  more closed to usual algebraic mode
and to most of Algol--like programming languages. 

There are several important syntactical differences.

For example, you can use infix operators in algebraic formulae and 
write $a+b$ instead of {\it (plus a b)} in Lisp.
You can do also the assignment in prefix form:
the usual command
$$x:=2+3;$$
produces the expected assignment 5 to a variable x.

One can check the result, for example,  by

if $x =5$ then print (x);

There are also {\it while} and {\it repeat} statements, {\it for} and {\it for each} loops and so on. See for details Anthony C.Hearn "Reduce User's Manual".



Note that all the
commands are finished by a semicolon. 

The important
difference is that empty parenthesis are necessary in every
call of a procedure without arguments, for example, to call the
procedure \index{simple} {\bf simple} it is necessary to write {\bf
  simple();} .
If you write {\bf simple;} (without parenthesis)  the
following message will occurred:

***** `simple' is an unbound ID


Being in the Reduce mode one has the full access to Lisp (more exactly to RLisp,
because it is still  the Reduce syntax)
\index{symbolic mode} symbolic
calculations switching the  mode to the symbolic one by means of
{\bf symbolic;} or {\bf lisp;}

To return to the \index{algebraic mode} algebraic mode  it is necessary to type {\bf algebraic;}

To check the current mode one types {\bf eval\underline{ }mode;}.
The current mode will be printed as {\bf algebraic} or {\bf symbolic}.

One can prefix the relevant expression by the appropriate mode. For example,
if the current mode is {\bf algebraic}, then the commands

\begin{verbatim}
symbolic car '(a);
x+y;
\end{verbatim}

will cause the first expression to be evaluated and printed in symbolic mode
and the second in algebraic mode.



Now let us check  a {\bf bergman} session in the Reduce mode.


\begin{verbatim}
> bergman
 4: simple();
Now input in-variables and ideal generators 
in algebraic form, thus:
        vars v1, ..., vn;
        r1, ..., rm;
where v1, ..., vn are the variables, 
and r1, ..., rm the generators.
algebraic form input> vars x,y; x^2-y^2,x*y;
% 2
x*y,
   x^2-y^2,
   
% 3
y^3,
   
Done
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARIDEAL), 
     and run a new (SIMPLE).

nil

5: quit;

Quitting

\end{verbatim}

Note that {\bf quit;} is with the semicolon too.

To switch from the Reduce mode to the standard Lisp mode the user can use the familiar
command {\bf end;}



\subsection{Parametric coefficients}

One of the advantages in using Reduce mode is the possibility to use
arbitrary coefficients that  Reduce allows. For example, it is possible
to use \index{parametric coefficients} parametric coefficients and to work with the generic rings.
The idea is that you allow coefficients and operations be taken from
Reduce,
but the main procedures for Gr\"{o}bner bases calculations are  the
same.


Let us check one example. Suppose that we need a  Gr\"{o}bner basis
for a generic ring
$$A=<x,y\, |\, x^2-a*y^2,x*y>,$$
where $a$ is a parameter (it means that we work over the  field of
fractions $K(a)$).

The session begins with switching to symbolic mode.
The input variables are settled up and the coefficients handling
procedure  \index{setreducesfcoeffs} {\bf setreducesfcoeffs()} is called. After that
we switch to algebraic mode  and start Gr\"{o}bner basis
calculations.

%-------------------------------------
\begin{verbatim}

> bergman

7:  symbolic;

nil

8:  setreducesfcoeffs();

nil

9: setiovars '(x,y);

nil

10:  algebraic;

11: lpol:= {x^2-a*y^2,x*y};

               2    2
lpol := { - a*y  + x ,x*y}

12:  bmgroebner lpol;

           2    2    3
{x*y, - a*y  + x ,a*y }

13:  bye;

\end{verbatim}


 Note, that all mode--changers (including {\bf setiovars}) must be
 run symbolically.
Then {\bf bmgroebner}  \index{bmgroebner} may be called {\it from  algebraic mode}, with a list of
polynomials as (single) argument. Each polynomial should be homogeneous,
and {\it only} contain input variables listed in {\bf setiovars}.
If all is well, {\bf bmgroebner}
returns a reduced Gr\"{o}bner basis (as a list of polynomials).

 Right now, only integer or standard form coefficients are permitted.

 Important! Only commutative version is available: the noncommutative
 version can be called, but right now produces wrong results.


\section{Debugging in {\bf bergman}}\label{debugg}

Unfortunately {\bf bergman} hasn't too many special debugging tools
and in the most cases only the usual Lisp error handling system
can be applied. Let us take an example containing several input errors
and follow the debugging steps trying to correct them. Suppose, you
are preparing
 an input file and the list of polynomials is huge. Of course, it is quite 
easy to make some errors in its typing. Here we have a fragment of
such a list,
it is extracted from a real problem offered  by prof. M.~Popa.

\begin{verbatim}
(setmaxdeg 10)
(algforminput)
vars v,d,r,s,t,e,q,m,b,c,h,g,l,k,p,n,a;
g*q^3+h*p^3-k^2*l^2,
2*a^2*g^2-2*a^2*l^2+2*a^2*m^2-b^2*g^2+2*c^3*h-4*g*n^3+
2*g*p^3+2*k^4,
a^2*b^2*h+3*a^2*g*k^2-2*a^2*q^3-b^2*g*k^2-2*c^3*m^2+
4*e^4*h+2*g*s^4-4*k^2*n^3, 3*a^2*b^2*h+12*a^2*g*k^2-
12*a^2*q^3+2*c^3*g^2-6*c^3*l^2-6*c^3*m^2-2*d^3*g^2+
12*e^4*h+12*g*s^4-12*k^2*n^3-6*k^2*p^3,
-a^4*g^2+4*a^2*k^4+8*a^2*t^4-2*b^4*g^2-4*b^2*g*n^3+
8*c^3*g*k^2-16*e^4*g^2+8*e^4*m^2+8*g*v^5-4*n^6+8*p^6,
a^2*g^3-a^2*g*l^2-a^2*g*m^2-2*a^2*h*k^2+2*a^2*r^3+
2*g^2*p^3+4*k^2*q^3-2*l^2*n^3-2*m^2*p^3,
-2*a^2*g^3+4*a^2*g*l^2+8*a^2*h*k^2-4*a^2*r^3-b^2*g^3+
2*c^3*g*h-10*g^2*p^3-6*g*k^2-8*k^2*q^3+4*l^2*n^3+
8*l^2*p^3+4*m^2*p^3,
-a^2*g*l^2-3*a^2*h*k^2-b^2*h*k^2-2*c^3*g*h+4*g^2*p^3+
4*g*k^4+4*g*t^4-2*h*s^4+2*l^2*n^3-8*l^2*p^3,
-6*a^2*h*k^2-3*b^2*g*l^2-4*c^3*g*h-2*d^3*g*h+6*g^2*p^3+
12*g*k^4+12*g*t^4-6*k^2*q^3-18*l^2*p^3+6*m^2*p^3,
3*a^2*g^3-4*a^2*g*l^2-6*a^2*h*k^2+4*a^2*r^3-2*g^2*n^3+
8*g^2*p^3+4*g*k^4+8*k^2*q^3-4*l^2*n^3-4*l^2*p^3-4*m^2*p^3,
18*a^12-81*a^10*b^2+189*a^8*b^4+108*a^8*e^4-279*a^6*b^6-
108*a^6*b^2*e^4-30*a^6*c^6+96*a^6*c^3*d^3-12*a^6*d^6-
144*a^6*f^6+243*a^4*b^8-324*a^4*b^4*e^4+162*a^4*b^2*c^6-
432*a^4*b^2*c^3*d^3+108*a^4*b^2*d^6+324*a^4*b^2*f^6-
108*a^2*b^10+540*a^2*b^6*e^4-198*a^2*b^4*c^6+
504*a^2*b^4*c^3*d*3-144*a^2*b^4*d^6-432*a^2*b^4*f^6-
648*a^2*b^2*e^8+288*a^2*c^6*e^4-144*a^2*c^3*d^3*e^4-
144*a^2*d^6*e^4-432*a^2*e^4*f^6+18*b^12-216*b^8*e^4+
66*b^6*c^6-168*b^6*c^3*d^3+48*b^6*d^6+144*b^6*f^6+
648*b^4*e^8-720*b^2*c^6*e^4+1008*b^2*c^3*d^3*e^4-
288*b^2*d^6*e^4-864*b^2*e^4*f^6+128*c^12-416*c^9*d^3+
480*c^6*d^6+264*c^6*f^6-224*c^3*d^9-672*c^3*d^3*f^6+
32*d^12+192*d^6*f^6-2592*e^12+288*f^12,
-a^2*b^2*g^2+2*a^2*k^4+4*c^3*g*k^2-4*e^4*g^2+4*p^6;
\end{verbatim}

The first attempt to compute it (working in the Reduce version) failed:

\begin{verbatim}

1 lisp> (simple "tests/inv.err")
10
***** 
dskin of `tests/inv.err' aborted after 1 form(s).
***** Segmentation Violation
2 lisp> 
\end{verbatim}

The yielded error message ''Segmentation Violation'' is not very informative.
One can obtain more information using the possibility of tracing,
offered by Lisp. According to the PSL documentation, ''the error
handler typically calls an interactive break loop, which permits
the user to examine the context of the error and optionally make
some corrections and continue the computation, or to  abort  the
computation.''
 
If we are in {\bf bergman} compiled under PSL the break loop is coming
immediately: 

\begin{verbatim}
1 lisp> (simple "tests/inv.err")
10
***** 
***** Continuable error.
Break loop
2 lisp break (1) > 
\end{verbatim}

Being in the  Reduce version one should switch on the corresponding flag
before the computation:

\begin{verbatim}

1 lisp> (on break)
nil
2 lisp> (simple "tests/inv.err")
10
***** 
Break loop
3 lisp break (1) > 
\end{verbatim}

Now we have similar situations in both cases and can start the
debugging. First of all, we
can use the tracing to locate the erroneous place. So, let us try
some of the break loop commands, for example, {\bf T}:

\begin{verbatim}
1 lisp> (simple "tests/inv.err")
10
***** 
***** Continuable error.
Break loop
2 lisp break (1) > T
Backtrace from top of stack:
backtrace top!-loop!-eval!-and!-print continuableerror
a!L!G!I!Nr!E!A!De!R!Rm!E!S!S!A!G!E 
p!O!La!L!Gr!E!A!D algforminput dskin!-step
unprotected!-dskin!-stream 
dskin!-stream dskin simple top!-loop!-eval!-and!-print
standardlisp 
nil
\end{verbatim}

Looking on this information one can presume, that something is  wrong with
the input, because the {\it continuableerror} was created by
the procedure a!L!G!I!Nr!E!A!De!R!...
followed by p!O!La!L!Gr!E!A!D. Continuing investigation we can use the ``V''
option:

\begin{verbatim}
3 lisp break (1) > V
\end{verbatim}

Omitting a part of output, which seems to be not very understandable,
let us pay attention to the following strings:

\begin{verbatim}
a!L!G!I!Nr!E!A!De!R!Rm!E!S!S!A!G!E -> continuableerror:
p!O!La!L!Gr!E!A!D -> a!L!G!I!Nr!E!A!De!R!Rm!E!S!S!A!G!E:
        18
        f
\end{verbatim}

''18'' is the number of input variables. What is ''f''? One of the input
variables, why it appears here? It seems, that  it is treated in a
special manner, but why? Checking the list of input variables one can
see that it is absent in the
{\bf vars}
list! So, we found one error and should correct it  inserting  the
variable ''f''.

Starting the computation again we obtain, unfortunately, a new continuable 
error and try to repeat the debugging process. Among the information
obtained after the applying of ``V'' option one should pick out the
following strings:

\begin{verbatim}
a!L!G!I!Nr!E!A!De!R!Rm!E!S!S!A!G!E -> continuableerror:
p!O!La!L!Gr!E!A!D -> a!L!G!I!Nr!E!A!De!R!Rm!E!S!S!A!G!E:
        18
        3
        nil
        504
\end{verbatim}

504 is one of the coefficients of the 11th polynomial, this polynomial is the
largest one
and we may expect some troubles here. Searching the input file we find
the monomial with such a coefficient:

\begin{verbatim}
504*a^2*b^4*c^3*d*3
\end{verbatim}

An error occurred because the sign \verb-''^''- on the end of monomial
was mistyped (being replaced by ``*''). 
After its correction we try again: 
 
\begin{verbatim}
1 lisp> (simple "tests/inv.err")
10
t
% 4
q^3*g-l^2*k^2+h*p^3,
   2*c^3*h-b^2*g^2+2*k^4+2*g*p^3-4*g*n^3+2*m^2*a^2+
   2*g^2*a^2-2*l^2*a^2,   
% 5
4*g*k^4+4*g^2*p^3-4*l^2*p^3-2*g^2*n^3+2*m^2*g*a^2+
g^3*a^2-2*g*l^2*a^2-2*h*k^2*a^2,
   -4*g*k^2-4*g^2*p^3+4*l^2*p^3+2*g^2*n^3-2*m^2*g*a^2-
g^3*a^2+2*g*l^2*a^2+2*h*k^2*a^2,
    4*q^3*k^2-2*m^2*p^3+2*g^2*p^3-2*l^2*n^3+2*r^3*a^2-
m^2*g*a^2+g^3*a^2-g*l^2*a^2-2*h*k^2*a^2,
    24*t^4*g-4*d^3*h*g-4*b^2*g^3-6*b^2*g*l^2+6*m^2*p^3-
6*g^2*p^3-4*l^2*p^3-6*l^2*n^3+6*r^3*a^2-11*m^2*g*a^2+
3*g^3*a^2+5*g*l^2*a^2-2*h*k^2*a^2,
    6*s^4*g-2*d^3*g^2+2*c^3*g^2-6*c^3*l^2+3*b^2*g*k^2-
6*k^2*p^3-6*q^3*a^2+3*g*k^2*a^2,
   -12*s^4*h+4*d^3*h*g-2*b^2*g^3+6*b^2*g*l^2-6*b^2*h*k^2-
6*m^2*p^3+6*g^2*p^3-8*l^2*p^3-6*g^2*n^3+18*l^2*n^3-
6*r^3*a^2+5*m^2*g*a^2-5*g*l^2*a^2+2*h*k^2*a^2,
   -6*m^2*c^3+12*e^4*h+2*d^3*g^2-2*c^3*g^2+6*c^3*l^2-
6*b^2*g*k^2+6*k^2*p^3-12*k^2*n^3+3*b^2*h*a^2+6*g*k^2*a^2,
   
***** Segmentation Violation
Break loop
2 lisp break (1) > 
\end{verbatim}


The computation started, but something was wrong. The input data were
successfully read, the computation started ... What happened? One of
the most frequent error is non-homogeneity. To check it we can use,
as previously, the tracing, but there is a special {\bf bergman} function
\index{testindata} {\bf testindata} to help us in debugging.
This function tests the homogeneity of
input polynomials. It should be called immediately after the input 
(before starting the computation), for example:            
\begin {verbatim} 
1 lisp> (dskin "tests/inv.err")
10
t
nil
2 lisp> (testindata)
((4 4) (5 5 nil 5 5 5 5) (6 6) (12))
\end{verbatim}

The function prints the list of monomial's degrees, the value {\bf nil} 
shows that one of the polynomials in degree 5 is not homogeneous.
In our example it is the monomial

\begin{verbatim}
-6*g*k^2
\end{verbatim}
in the 7th polynomial (we skip the question  how to locate it
using Lisp). After its correction we can restart the computations and
are lucky to see the result, which is too large and not so interesting 
to be included here.


One more {\bf bergman} function to help you on debugging is {\bf printsetup} 
which displays some useful information:

\begin{verbatim}

3 lisp> (printsetup)
((objecttype ring (autoaddrelationstate nil nil)) 
(resolutiontype none)
(variablesetup 
      (ringtype commutative) 
      (commutativeorder tdegrevlex) 
      (noncommutativeorder tdegleftlex)
      (variablenumber 18) 
      (invariables (v d r s t e q m f b c h g l k p n a))
      (outvariables (v d r s t e q m f b c h g l k p n a)) 
      (variableweights nil)(homogenisationvariable nil)) 
      (strategy default 
          (mindeg nil) 
          (maxdeg 10) 
          (interruption ordinary)(customised nil))
      (coefficientdomain nil (oddprimesmoduli ordinary))
      (inputformat casesensalgin) 
      (outputformat algexptsprint 
      (immediateassocringpbdisplay nil) 
      (overwrite nil) (customised nil))
      (debugstate (directalertclosing nil) 
      (checkfailuredisplay t) 
      (activetracebreaks nil)) 
(variousflags 
     (degreeprintoutput off) 
     (dynamiclogtables off) 
     (immediatecrit off) 
     (immediatefullreduction on) 
     (immediaterecdefine off) 
     (nobignum off) 
     (standardanickmodes on) 
     (pbseries off) 
     (reductivity on) (savedegree off) 
     (saverecvalues on)))
\end{verbatim}

One can check the values of the polynomial ring set up:

\begin{itemize}
\item  ring type (in our example: {\bf  (ringtype commutative)}),
\item  ordering  (in our example: {\bf (commutativeorder
    tdegrevlex)}),
\item characteristic (in our example: {\bf (coefficientdomain nil
    (odd\-pri\-mes\-moduli ordinary))} corresponds to characteristic 0),
\item number, list of input and output variables, their weights
  {\bf (variable\-weights nil)} in our example means the
  naturally graded list).
\end{itemize}


Besides that we can see the set up of:

\begin{itemize}
\item strategy,
\item resolution type,
\item maximal and minimal degrees,
\item input and output formats (in our example: case sensitive
  algebraic form input and algebraic form output where the exponents
  values are printed explicitly),
\item various flags, their meaning is explained in the manual.
\end{itemize}
  
  
Sometimes one can be in troubles because of the settings incompatibility.
It is necessary to take in account the previous settings in order to avoid
strange situations, when the well known procedure yields some unexpected
results. It might happens, for example, if you have computed the   Gr\"{o}bner basis
in non-commutaive mode, forgot about this setting and start a new {\bf simple}
expecting the commutative calculations and seeing a strange result.

It will surprise you even more 
in the case, when you computed the Anick resolution (which assigns to  the 
resolution type the value ``anick''), call  {\bf clearideal}, setup 
{\bf commify} and start 
{\bf simple} obtaining in an unexpected way an output with Betti numbers!
(which, by the way, are very far from the real ones.
To keep off this situation one should call the function {\bf (setresolutiontype nil)}.)

If you are interested only to know if your mode settings are correct you can apply
the function \index{checksetup} {\bf checksetup}:

\begin{verbatim}
3 lisp> (checksetup (getsetup))
t
\end{verbatim}

The displayed value {\bf t} informs that the settings are OK.
Note there we use also the function \index{getsetup} {\bf getsetup} 
which gives the current setup.

But you are in troubles if you obtain the following  message:
 
\begin{verbatim}
9 lisp> (checksetup (getsetup))

*** Clashes between different mode settings were found.
\end{verbatim}

The pair of functions \index{findmodeclashes} {\bf findmodeclashes} and
\index{findmodeclashes1} {\bf findmodeclashes1} are
destined to give more detailed information. Let us apply one 
of them, namely {\bf findmodeclashes1}:
\index{findmodeclashes1}

\begin{verbatim}
10 lisp> (findmodeclashes1 (getsetup))
((((resolutiontype) eq (car item) (quote anick)) 
(variousflags pbseries) eq (car item) (quote off)) 
(((resolutiontype) eq (car item) (quote anick)) 
(variablesetup ringtype) not (eq (car item) 
(quote noncommutative))))
\end{verbatim}

Perhaps, at the very beginning this information looks slightly confusedly,
however one can understand that the problems are caused by the {\bf resolutiontype}.

\section{Customising bergman}
\label{cust}
   

{\bf Bergman} is an open system, and you may change any or all parts
of it in order to get something more suitable for your purposes.
However, in order to do this in a very general setting, you may
probably have to learn much more than you want about the precise
interactions of different parts of the program. Changing one
procedure is only safe if you are sure exactly what it calls, and
for what purposes it may be called. There is some documentation
of this, in the manual and in the file protocol.txt in the doc
area; but it is not complete, and does not cover most of the
`internal' procedures.

 However, there are a number of ways to influence the behavior
of {\bf  berg\-man} at well defined critical points, by writing your own
procedures, and by activating a corresponding customisation
minor mode. These possibilities exist in such points where we
suspect that the user may be most interested in intervening. If
you think we missed some important points, please let us know!

There are two different modes where the user can do some customisations:
display and strategy.


Recall that to change the display mode to the custom one we call the
procedure {\bf setcustdisplay} and the procedure  {\bf setcuststrategy}
is used to the changing the strategy mode (see section \ref{bricks}
 to find an example). Of course, the corresponding boolean get-procedures 
\index{getcustdisplay} \index{getcuststrategy} 
{\bf getcustdisplay, getcuststrategy} inform {\bf bergman} that 
you are in the customising mode.

 Here is a brief overview over the specific procedures intended
for customisation. We write 
 the function name and a very brief description
of what it does. In most cases, the intervention demands both that
the submode is activated, and that the procedure is actually defined;
sometimes, else some kind of default action is taken.

Many of the procedures perform actions related to "the current degree".
This may be accessed as the value of {\bf (getcurrentdegree)}. 


   \vspace{0.3cm}
\begin{center} {\bf \large DISPLAY Mode customisation}\end{center}

\begin{description}

\index{custdisplayinit} \item [(CUSTDISPLAYINIT)] : EXPR

Called (if it is defined) at initialising Gr\"obner basis calculations.
Then, supplants the default action, which initialises two counters
(NOOFSPOLCALC and NOOFNILREDUCTIONS) to NIL. Intended for similar
purposes.


\index{degreeenddisplay} \item [(DEGREEENDDISPLAY)] : EXPR

Called (if it is defined) whenever calculations of the new Gr\"obner basis
elements of a certain degree are finished. Will supplant both other
degree-wise output, and optional Poincar\'{e}--Betti series calculation. An example
of a DEGREEENDDISPLAY template is given in the section \ref{bricks}.


\index{custclearcdegdisplay} \item [(CUSTCLEARCDEGDISPLAY)] : EXPR

Called (if it is defined), if the `Hilbert series limitation' is active,
and for a particular degree returns the verdict that both the input
and the obstruction monomials of this degree shall be discarded,
without any calculations.

It is called before this abandoning, but does not supplant any action.
May be used e.g. for printing information on how many input polynomials
or obstruction monomials are to be discarded at this degree.


\index{custclearcdegobstrdisplay} \item [(CUSTCLEARCDEGOBSTRDISPLAY)] : EXPR

Called (if it is defined), if the `Hilbert series limitation' is active,
and for a particular degree returns the verdict that only input
polynomials should be processed (and thus all current degree
obstruction monomials should be discarded). Apart from this, as the
preceding procedure.




\index{hseriesmincritdisplay} \item [(HSERIESMINCRITDISPLAY)] : EXPR

Called (if it is defined), if the `Hilbert series limitation' is active,
and causes the rest of the input polynomials and obstruction monomials
of a certain degree to be discarded. since the prescribed number of new
Gr\"obner basis elements (now) have been found. Apart from this, as the
preceding procedures.

\index{nodisplay} \item [(NODISPLAY)] : EXPR 

Empty procedure to do nothing. It is a pre-defined alternative for some of the procedures above.
\end{description}

   \vspace{0.3cm}
\begin{center} {\bf \large STRATEGY Mode customisation}\end{center}
\begin{description}

\index{custnewcdegfix} \item [(CUSTNEWCDEGFIX binno)] : EXPR

If it is defined, it is called and supplants the ordinary action of
the procedure FixNcDeg (defined in two variants in the file strategy.sl).
The result of the procedure decides whether or not to continue
calculations, when a new current degree was found.

Returning NIL signifies "stop"; all other return values signify
"continue".

The input "binno" is one of the integers 1, 2, and 3, which should
be considered as binary strings of length 2 (i.e., as 01, 10, and 11,
respectively). The left bit (right bit) is 1 if and only if there are
input polynomials (obstruction monomials, respectively) of the proposed
new current degree.

The proposed new current degree may be accessed as the value of
{\bf (GETCURRENTDEGREE)} (or of the variable cDeg).


\index{custnewinputgbefind} \item [(CUSTNEWINPUTGBEFIND)] : EXPR

If it is defined, calls and supplants other action, whenever ordinarily
the next input polynomial would be reduced, and the resulting polynomial
in normal form, if non-zero, would be returned as a new Gr\"obner basis
element. The value of the call to {\bf CUSTNEWINPUTGBEFIND} ought to be either
NIL (signifying "this was a reduction to zero"), or a new Gr\"obner basis
element, in Reductand form.

The supplanted action of the procedure FindInputNGbe (defined in monom.sl)
would have included removing an investigated polynomial from the list of
current input polynomials (cInPols).


\index{custcritpairtonewgbe} \item [(CUSTCRITPAIRTONEWGBE)] : EXPR

If it is defined, calls and supplants other action, whenever ordinarily
an S-polynomial would have been formed from the next critical pair, then
would be reduced, and the resulting polynomial in normal form, if non-zero,
would be returned as a new Gr\"obner basis element. The value of the call
to {\bf CUSTCRITPAIRTONEWGBE} ought to be either NIL (signifying "this was a
reduction to zero") or a new Gr\"obner basis element, in Reductand form.

The supplanted action of the procedure FindCritPairNGbe (defined in monom.sl)
would have included removing an investigated critical pair from the list of
currently investigated critical pairs (SP2r).


\index{custenddegreecritpairfind} \item [(CUSTENDDEGREECRITPAIRFIND)] : EXPR

If it is defined, calls and supplants other action, whenever ordinarily
new critical pairs would have been calculated and saved, since all new
Gr\"obner elements of the current degree just were found. If you plan to
employ this, you are recommended to view the definition of the procedure
whose action it supplants, DEnSPairs (defined in monom.sl).

Note, that the return value is without interest; only the side effects
of this procedure matters.

\index{custenddegree} \item [(CUSTENDDEGREE)] : EXPR
\index{custenddegreecritpairfind} \item [(CUSTENDDEGREECRITPAIRFIND)] : EXPR
\index{custitemcritpairfind} \item [ (CUSTITEMCRITPAIRFIND)] : EXPR
 
The corresponding analogous for the cases when end degree  was achieved
or critical pair found (in the degree-wise and item-wise mode correspondingly).
\end{description}


\section{Computations in bergman under shell}
\label{sec:shell}
The aim of this section is to describe an additional feature in {\bf bergman}  -- an interface shell
that simplifies the usage of the system. We start from a brief description of the problems arising
in {\bf bergman}'s interface. Then we show how the shell solves those problems. At last we describe in more details how to use the shell and comment its additional
possibilities and  future development.






\subsection{Problems of interface to {\bf bergman}}\label{sec-interface-problems}

Interfaces for computer algebra systems were investigated and
discussed, e.g., in \cite{CA-interfaces}. See also \cite[p.~150--160]{CA-Handbook}.
\label{loc-interface-problems}

Most modern  computer algebra systems have their own programming language.
E.g., CoCoA has both simple commands, like expression evaluation, assignment,
printing, and structured commands, like conditional operators, for- and while-loops,
function definitions, etc.  More advanced (from the interface point of view)
systems like Mathematica permits to develop mathematical software
looking like the Mathematica itself with windows, buttons,
and hyperlinks. This level is called front-end programming.

Some systems like Maple or Maple-based Scientific
Workplace have so-called document style interface. In this kind of
interface, user prepares a document that includes formulas, calculation
results, and graphics. The result can be typeset. LaTeX is usually used
as intermediate language in such systems. Entering of formulae in such
systems can be made using palettes of symbols and formula patterns.


{\bf Bergman} mainly uses a not very transparent Lisp syntax, and Lisp console for
input and output.

 Looking on the previous examples one can conclude that {\bf bergman} rather friendly
suggests what actions should be executed.



But despite of the detailed suggestions leading us step-by-step during the input and computing process,
we should  take care about too many things: the correct number of module variables,
the order in which variables are written,
the respect of the syntactical rules, especially inserting of the commata and semicolons in the
requested places. Any mistake in the input probably will demand to start input from the very beginning.


Looking on those examples one can conclude also that this type of interface   seems to most users
not being as friendly as we could expect from a developed computer algebra system. Some stress may be
taken off by choosing the Reduce version and its language RLisp, which is more closed to the
syntax adopted by many of the computer algebra systems.

Another problem is presented by Lisp interpreter error messages.\\
{\bf Bergman} hasn't
very developed debugging tools
and often  only the usual Lisp error handling system
can be applied. Assume you skipped an apostrophe  or forgot
that input relations are supposed to be homogeneous. If you mistyped your input
and err in one of the relations, you can see something like:

\begin{verbatim}
dskin of `tests/test1.txt' aborted after 1 form(s).
***** Segmentation Violation
\end{verbatim}

This is not as informative as one could desire.


The last problem we note here is that non-commutative Gr\"obner basis
 may be infinite.
Therefore, we are
to stop calculations, analyze intermediate results, and, possibly, restart
calculations.

Moreover, {\bf bergman} uses only one window for input and output and in the case if one needs
 to return and to see the input he should scroll back through the output lines
(which might be rather voluminous) searching the string beginning with ``vars...''.

Summing up the analysed aspects of {\bf bergman}'s interface we can ascertain the following:
the original interface based on Lisp creates some inconveniences, namely

\begin{itemize}
\item the functional programming style with its
forest of strictly balanced parentheses is rather far from the usual (mathematical) language and
can create difficulties for non-experienced user;
\item  {\bf bergman} doesn't perform the checking of the input information correctness,
in particular, the compatibility
of the different parameters values,  the homogeneity of the input relations (in the proper case) etc.
The last one could be checked only by applying a special function.
\item in many cases the error messages are yielded by Lisp interpreter being not
understandable for a user who is not skilled in Lisp programming;
\item the usage of a single window for interface, where the different zones,
destined to different actions, are mixed, causes some troubles in finding of
the necessary information.
\end{itemize}

\subsection {Shell  overview}

The solution offering a comfortable environment and avoiding the problems mentioned above
is the developing of a new kind of interface, which permits to operate with {\bf bergman} in a
manner closed to the  usual mathematical surroundings. Moreover, it will serve also as a
prospectus for {\bf bergman} giving the possibility to see on the graphical panel the most important
facilities without the reading a manual or applying the corresponding help function.

 The communication  between user and {\bf bergman}
can be implemented in different ways. One of them  we have considered in the
 previous sections is based on  programming in Lisp:
choosing parameters and flags, and applying the corresponding setup procedures.
It is a good way for a user experienced in programming and desiring to
get maximum possible efficiency of {\bf bergman}.

We take also into account different users that need more or
less routine
 calculations in the repeating environment performed
 as easy as possible, preferable without any programming at all.
A friendly interface  may be for such users one of main reasons to prefer
{\bf bergman}  to any other system.

In the very beginning it is impossible to guess what the user wants exactly.
That is why he needs to describe his preferences  and this
is the only  part of a  boring work for him, when he should be patient.
But this should be done
only once and later the system will do exactly he wants without any
essential troubles for the user. According to his preferences, a personalized
profile will be created. It establishes the preferable setup immediately after
starting  {\bf bergman}.  It is possible to have a
number of profiles for each user, depending on the class of problems he is
interested to solve. Moreover, it is possible to make some changes in a profile,
permanent or valid during the current session.

The user can skip some questions: then a standard {\bf bergman}  default
setup values will be used.
Recall, for example, that {\bf bergman}  calculates by default only
the commutative Gr\"obner basis in characteristics zero.

It is presumed that user is familiar with {\bf bergman}  manual, but in fact
one can skip its preliminary reading and use instead the on-line help directly
from the interface in order to obtain some explanations.

Before starting the detailed interface description let us return to one of the previous example
(see section \ref{onemodbetti}) showing
 how to compute Betti numbers for module using a graphical interface called below shell.
To perform the computation it is necessary to select ``Betti numbers'' from the calculation
menu and ``Right module'' from the object menu (all other specifications will be done automatically),
to click the button ``Variables and Relations''
and  to input in
the corresponding place the maximal degree of computations, the ideal and module
variables and relations  (each in its own window). Then the user selects
``Run $|$ Generate and Run'' from the main menu.
The result will be displayed in the separate window.  The calculations can be repeated
editing only that data, which are to be changed.

We describe below the work with {\bf bergman} shell on its current stage
of development. The shell simplifies the access to existing {\bf bergman}
functions, tests data before the calculation, saves data in profiles
(configuration files), and permits repeated calculations with the
same or modified data.

\subsection{Shell description}

The shell consists of the main menu at its top, then the toolbar, and then
three panels (top-left, bottom-left, and right ones). The main menu consists
of items that are used to organize calculations, and the top-left panel contains
drop-down menus and other elements that specifies mathematical parameters of the
solved problem. The bottom-left and right panels display information, or are
used to enter some data (e.g., variables and relations are input from the
right panel). Borders of panels can be moved by mouse, and any panel can
be collapsed or expanded by clicking the corresponding label (little black triangle
on the border).

Main menu items are:
\begin{enumerate}
\item File;
\item Profiles;
\item Sessions;
\item View properties;
\item Preview LISP;
\item Run;
\item Process results;
\item Tools;
\item Options;
\item Windows;
\item Help.
\end{enumerate}

The less obvious items are Profiles and Sessions. A session is a set of
parameters that fully defines the problem to be solved. Session
is implemented as a directory where all data are saved, {\bf bergman} input files are generated,
and {\bf bergman} output files are produced. Sessions serve to return to previous {\bf bergman} calculations,
modify them, and experiment with them.

Informally, sessions give to a mathematician the  possibility  to use the previous experience of
{\bf bergman}'s users (own or others) and to save the current setup for the future calculations.

With sessions, it is possible:
\begin{itemize}
\item select a session and load its data to panels, i.e., switch to the saved problem;
\item create a new session (by selecting $<$new session$>$ from the session drop-down list);
\item save data in the selected session;
\item save data in a different session (save as\dots);
\item delete a session.
\end{itemize}

One can see also the session directory, comment, and statistics of its usage.

\noindent\begin{figure}
\begin{center}
\includegraphics[width=117.5mm,height=53.3mm]{ss1_sess.eps}
\caption{{\bf bergman} shell: sessions panel}\label{fig-sessions-panel}
\end{center}
\end{figure}

When the user wants to create a new session, he/she will be asked which profile
should be used as the base to create this session. A profile is a partial set of data
common for several sessions.
It corresponds to the group of mathematical problems the user investigates during different sessions.
E.g., after the installation the profiles directory contains a profile called ``commutative''
that fixes a single parameter, the commutativity.

All new sessions are created using the current default profile. Inversely, when a new profile is
created, it is based
on the parameters of the current session. To save a session as a profile, the user selects
parameters that are to be fixed, and drops other parameters.

The {\bf calculations menu} on the top-left panel
sets the problem to be solved: what does the user want to calculate?
Two main tasks are Gr\"obner basis and Anick resolution.
For Gr\"{o}bner basis, it is possible to use coefficients of Hilbert series that was calculated
before or found from another considerations. This information permits to shorten calculations.
The corresponding input fields exist on the panel. We can calculate Hilbert series or
Betti numbers (the latter includes Anick resolution). These tasks are more general.
One particular task is Hochschild homology.

The listed five problems are solved for homogeneous relations, i.e., for
graded orderings. The jumping rabbit is used
for non-homogeneous relations.

We included in the panel the graduation menu for future;
now the user can not manipulate it.

\noindent\begin{figure}
\begin{center}
\includegraphics[width=117.8mm,height=67.0mm]{ss2_calc.eps}
\caption{{\bf bergman} shell: calculations menu, variables and relations input areas}\label{fig-calculations-menu-plus}
\end{center}
\end{figure}

The top-left panel contains also the menu for resulting Gr\"obner basis form: algebraic,
Lisp, Macaulay, visual, or LaTeX.

Domain and field coefficients can be selected in the {\bf coefficients field menu.} The following
cases are included:
\begin{itemize}
\item integers of different length (1/2/4 bytes and arbitrary integers,
characteristic 0); the coefficient field
is the field~$\setQ$ of rational numbers, and the coefficient domain is
the ring~$\setZ$ of integers;
\item characteristic 2 (modulo 2); the coefficient field and the coefficient domain both are $\setZ / (2) = GF(2)$;
\item characteristic $p$ (modulo $p$,
$p$ is an odd prime); the coefficient field and the coefficient domain both are $\setZ / (p) = GF(p)$.
\end{itemize}


\noindent\begin{figure}
\begin{center}
\includegraphics[width=41.0mm,height=51.8mm]{ss3_coef.eps}
\caption{{\bf bergman} shell: coefficients menu}\label{fig-coefficients-menu}
\end{center}
\end{figure}


 A possibility to
use Reduce forms as coefficients is not implemented in the current shell version.


The {\bf object menu} permits to select object type (ring, one or two modules).
There are also menu for commutativity and ordering of monomials.
Possible orderings depend on commutativity.
In the commutative mode the user may switch between
\verb| deglex | and \verb| revdeglex.|
In the non-commutative mode only \verb|deglex | and several eliminating orderings
are possible.

\noindent\begin{figure}
\begin{center}
\includegraphics[width=36.1mm,height=27.7mm]{ss4_obje.eps}
\caption{{\bf bergman} shell: object menu}\label{fig-object-menu}
\end{center}
\end{figure}

When the user clicks the {\bf variables and relations button},
input areas for variables, their weights, and relations appear in the right panel.
Input from this panel depends on selected calculation and object type. E.g., if
you will calculate Betti numbers for two modules, you need to differ left module,
ring, and right module variables. In that case, input areas for left module
variables and right module variables are unblocked. Analogously ring and module relations
go to the different input zones. The information from this panel is used (in graded case)
for checking the homogeneity of relations before run.

The {\bf strategy menu} is used to choose the strategy  of the calculations:
 Buchberger's original algorithm or  Staggered one.

As the user selects the ``Run $|$ Generate and Run'' item from the main menu, the shell generates Lisp program and input data,
checks the homogeneity (except for ``the jumping rabbit''). The calculation starts
asynchronously, in a separate thread and in the separate window. In the meantime the user can
work with the same or different profile but he/she can not save profile or run it
until the current run is finished and its log window is closed.

There is a possibility using the {\bf ``Preview LISP''} item from the main menu
to see the input files, generated by {\bf bergman}.
The option is used mostly in debug mode and is intended mainly for {\bf bergman} developers.








 



