
%\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 package for Reduce. (You can read
more about this in  section \ref{reduce}).
The aim of this section  is to explain {\bf bergman} as were it 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 must be
homogeneous (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
sub-section \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 investigations of the groups or most of the finite dimension
algebras (such as matrix algebras), everything that contains
nontrivial idempotents.

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 (\index{commutativity} commutative 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 strategy 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. The next section describes ideals definitions.


\subsection{Background}

Most Gr\"obner basis computations are performed within a given
\index{polynomial ring} polynomial ring $R = K \mathopen[ x_1, \ldots ,x_n
\mathclose]$ over a fixed \index{coefficient field} coefficient field~$K$.
We may recall that $R$ consists either of all commutative or of all
non-commutative polynomials in the \index{variable}
variables~$x_1$,~\dots, $x_n$. A polynomial $f \in R$ is a finite sum
$\sum_{i=1}^r c_ip_i$, where the terms or summands $c_ip_i$ are products
of coefficients $c_i \in K$ and (monic) monomials or \index{power product}
power products~$p_i$ (of variables). 

%In the commutative case, (Since the terms `term' and `monomial' are used
%with different meanings.

\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:
\index{getinvars}

{\bf (getinvars)}

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


One important question is if the names ''y'' and ''Y'' represent the same
variable. The answer depend 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 oppsite case in the later versions). 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.  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 capital names.
 (In the later version of Reduce the situation is opposite: the user
 available procedures names are in lowercase characters.)  
 Nevertheless some procedures may turn OFF the flag 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 capitalised:

{\bf (QUIT)}

 Another way to quit is

 {\bf (ON RAISE)}

  {\bf (quit)}

  \item Note, that turning ON this flag you loose access to all
  the procedures and variables with the names, containing small letter,
  such as   SecretProcedure. The idea is that they should be unavailable
  to the usual user, being absolutely internal and private. Nevertheless
  user can sometimes see their names, where small letter are printed after
  exclamations: S!e!c!r!e!tP!r!o!c!e!d!u!r!e. Even the multiplication
  is secret in this mode and looks as !*.
  But normally you need not care about this and turn OFF the
  RAISE flag.


 \end{enumerate}

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




 In the commutative setting {\bf bergman} can perform computations in two different orderings:
 \index{lexicographical ordering}
 lexicographical (DEGLEX) or reverse lexicographical
 \index{reverse lexicographical ordering} (DEGREVLEX). 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 noncommutative DEGLEX. 
 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  DEGREVLEX,
and if the words are equal as the commutative words they are compared
as in noncommutative DEGLEX. 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 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 highest.
  \item in the commutative mode and both eliminating orderings first variable i 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()  \\ 
                &  (commutaive case)\\
                & \index{degleftlexify}  DEGLEFTLEXIFY() \\
                & (noncommutaive case) \\ \hline
         ELIMLEFTLEX & \index{elimorder} ELIMORDER() \\ \hline
         INVELIMLEFTLEX &\index{invelimorder}  INVELIMORDER() \\ 
        \hline
  \end{tabular}
\vspace*{0.4cm}

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


\subsection {Using eliminating ordering}

Despite the fact that {\bf bergman} works with graded algebras only,
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 dehomogenize the result setting $h=1.$

Let us consider an example suggested by  Prof. I.Kantor.
Let $A$ be  the following algebra:
$$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>$$
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{Coefficients: background}
\label{sec: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 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 do not work, as when we
want to calculate Anick resolutions. Hence, \bm\ also has a procedure
NORMALFORM  for calculating the true normal form of a polynomial.



\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} (for ``(Reduce) Standard Forms'').

By default and after the call {\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$, 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$-logaritms'' (i.e.,
representing $a = \gamma^s$ by $s$), whenever convenient.

 The main effect of using the `modular logaritms 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 `logaritm 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{modlogs}
{\bf (modlogs on)}
{\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 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.

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}

 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 $int_*$ 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.

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

\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.

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

\begin{verbatim}


> bergman

7: end;
Entering LISP ... 
Bergman 0.926, 24-Oct-98
1 lisp> (SETWEIGHTS 1  1 2)
nil
2 lisp> (GETWEIGHTS)
(1 1 2)
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{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 $f(x)$ with the
integer coefficients that $f(\alpha)=0.$ 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}

Bergman 0.94, 17-Dec-99
1 lisp> (purelexify)
nil
2 lisp> (off usermode)
nil
4 lisp> (setalgoutmode alg)
nil
5 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
6 lisp> (homogeniseinput)
*** Function `h!O!M!O!Gpm!O!N' has been redefined
nil
7 lisp> (groebnerinit)
nil
8 lisp> (groebnerkernel)
d!O!N!E
9 lisp> (algforminput)
algebraic form input> vars x,y,z,t,f;
algebraic form input> ;
nil
10 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
11 lisp> (quit)

\end{verbatim}

%(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.





\subsection {Strategies}
The last important mode choice that should be mentioned is selecting
the \index{strategy} strategy  of the calculations. Besides selecting of the
algorithm (commutative or non-commutative, Buchberger or staggered)
that you are doing selecting by appropriate procedure, you have
some influence on the intermediate calculation. Choosing
\index{immediatefullreduction}

{\bf (on immediatefullreduction) }

(and this is default) you demand immediate reduction of all the terms
of your 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{Ideals and quotient ring}

To perform Gr\"{o}bner basis computation in the quotient ring  $A=<X|R>$
we need to define a polynomial ring and an ideal $I=(R)$ in it.
\subsection{Input--output modes for the polynomials}
\label{inputform}

There are three basic \index{output format} output formats, named
\index{Lisp form} LISP (default), \index{algebraic form} ALG
(its synonym  is also MAPLE), and
\index{Macaulay form} 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.
 \begin{description}
  \item{{\bf Commutative case}}

 The (output) 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 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 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 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.

%\begin{exm} ------------------To be written--------------------
%\end{exm}  

\item{{\bf Non--commutative case}}

 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 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. E. g., if
the variables are $x,y,$ and $z$ (in this order), then the
\index{Lisp form} LISP form
polynomial $((5\ 1\ 1\ 1\  3\  2\  2))$ will be \index{algebraic form} 
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.


\end{description}

If you want to have output in ALG or \index{Macaulay form} MACAULAY form, you in one way or
another must define the variable names, and you must set the global
variable \index{algoutmode} {\bf algoutmode} to ALG or MACAULAY. The variable names are most
easily given by setinvars within a {\bf algforminput}, as explained below.

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

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

{\bf (lispforminput) }

pol1 pol2 ..... pols

{\bf (lispforminputend)}

\index{lispforminputend}

where pol1, ..., pols are polynomials on 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 EMBDIM to $n$. (EMBDIM
is short for "the embedding dimension".)

In order to perform 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 ALG form.

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 LISP form input,
   but perform {\bf algforminput} vars v1,...,vn; ; (NOTE the double ;),
   in order to enable ALG or MACAULAY output. Of course, if you try
   to {\bf (algforminput)} 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

        (SETQ O!u!tV!a!r!s (QUOTE (!x !y !z)))

   and in the non-commutative case corresponds to

        (SETQ O!u!tV!a!r!s (QUOTE ((1 . !x) (2 . !y) (3 . !z))))  .

        \end{enumerate}
 


\section{Calculating and using series}
\label{sec: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  contains all the explanation 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 finished.
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)}



Let us see an example. The file ``test3.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:

\begin{verbatim}

1 lisp>(ncpbhgroebner "test3.a""test3.gb""test3.pb""test3.hs")
*** I turn on noncommutativity
nil
alg
t
*** Function `!O!L!D!D!E!D' has been redefined
*** Function `DEGREEENDDISPLAY' has been redefined

% 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 test3.gb}:\\

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

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

{\bf test3.pbs}:\\

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


{\bf test3.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
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.


If you prefer the interactive input/output  you can operate in the same manner with
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}




To compute Hilbert series in the commutative case 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}

> bergman

4: end;
Entering LISP ...
Bergman 0.922,  9-Jun-98
1 lisp> (LOAD hseries)
nil
2 lisp> (ALGFORMINPUT)
algebraic form (comm.) input> vars x,y;
algebraic form (comm.) input> x^3, x*y^2-x^2*y;
t
3 lisp> (GROEBNERINIT)
nil
4 lisp> (GROEBNERKERNEL)
d!O!N!E
5 lisp> (CALCRATHILBERTSERIES)
nil
6 lisp> (SETQ p HILBERTNUMERATOR)
((4 . -1) (3 . -1) (2 . 1) (1 . 1) (0 . 1))
7 lisp> (SETQ q  HILBERTDENOMINATOR)
1
8 lisp> (TDEGREEHSERIESOUT 1)
2
9 lisp> (TDEGREEHSERIESOUT 2)
3
10 lisp> (TDEGREEHSERIESOUT 3)
2
11 lisp> (TDEGREEHSERIESOUT 4)
1
12 lisp> (TDEGREEHSERIESOUT 5)
1
13 lisp> (TDEGREEHSERIESOUT 6)
1
14 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}
(SETQ MAXSERDEG 6)
(ALGFORMINPUT)
vars x,y;
x^3, x*y^2-x^2*y;
\end{verbatim}

The corresponding call (after {\bf hseries} loading) containing  a input file and two 
output files - for Groebner 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
\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).

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}

 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,$ calculate a Gr\"{o}bner basis 
 for the
new algebra  $B=<X,t|R_h,tx-xt, x\in X>,$ where $R_h$ stands for the set of
homogenized relations and to dehomogenize 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 problem
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 more  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).






\section{Some bricks to build your own procedures}
\label{sec: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} {\bf Algforminput, groebnerinit, groebnerkernel, groebnerfinish } belong to the top level.
The complete 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
four  procedures that can help you to perform your  own calculations. The reader is already
familiar with 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 following  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 (comm.) 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.  You can use them in your own procedure using
special procedures, created for this (see section \ref{functions} ).

\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).





