\chapter{BERGMAN for the beginners}
\section{Preliminaries}
Here we describe a version of BERGMAN, installed under Reduce and working
in the PSL environment. Although most of the text is valid for other
 installations too.
\section{Starting a BERGMAN session}
On many computers you can start a BERGMAN session by typing {\bf bergman }
When you are successful in starting a BERGMAN session you will see a prompt.
If the installation was under REDUCE, the prompt looks as:

{\bf

4: }

Now you need to switch to the LISP mode. For this you simply  type
{\bf end; } and then press {\bf Return } key. You will see a new LISP-prompt:

{\bf Entering LISP ...

Bergman 0.9,  9-Aug-96

1 lisp$>$ }

Of course, the date can be different - it is the date
when  BERGMAN was compiled on your computer.

Typically BERGMAN will print a prompt such as
{\bf 4 lisp$>$ }
at the beginning of  line you should enter. Whenever you
see a prompt, BERGMAN is waiting for you to enter more
information.

\section{Ending a BERGMAN session}

The command  {\bf (quit) } followed by the {\bf Return } key, ends
  a BERGMAN session.
\begin{exm} \label{exquit} Here you finish the session
\end{exm}

{\bf 10 lisp$>$ (quit) }

\section{ What you need to know about LISP syntax }

The user should realize that BERGMAN is a LISP program and whenever he
starts BERGMAN he works under LISP and in LISP notations. Here we describe
the necessary minimum of LISP syntax to deal with BERGMAN in the simplest
cases.

First of all, all commands should be written in the parenthesis -
see Example \ref{exquit}.

It is important that uppercase and lowercase may be different in LISP (though
not inside BERGMAN)
Normally it is  use only lowercase. Nevertheless in some situations,
arising from
mistakes you leave BERGMAN, but still need to leave LISP. In this case
usual,
{\bf (quit)} not necessary ends the session
and you need  to use {\bf (QUIT)} to do this (and sometimes twice!).
Note also that a typical mistake is to forget one of the right parenthesis or
quotes ({\bf `` }). So maybe a couple of them might be useful to leave
LISP safely.

During the session you can get some kind of messages from LISP.
All of them starts with stars. The message that starts from five stars
$*****$ means an error. Three stars $***$ mean only a warning -
it is possible to continue the work.
\begin{exm} Here we forget to write the parenthesis and are out of BERGMAN.
\end{exm}

{\bf
2 lisp$>$ simple

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

3 lisp$>$
}




\section{BREAK LOOP}

------------------TO BE WRITTEN-------------
 
\begin{exm} Here we have an example of Break loop \end{exm}

 {\bf
Break loop

2 lisp break (1)$>$
}

\section{Simplest calculations in BERGMAN}
 There are several routines specially written to simplify your first
 steps. They did not demands any knowledge of LISP and include
 several simple steps. Here we describe and explain those steps using
 several examples that you can easily copy and modify.
 \subsection{SELECTING ALTERNATIVES}
BERGMAN has now following main alternatives for calculating Gr\"{o}bner basis:
 \begin{itemize}
 \item {ordinary commutative}
\item {staggered commutative}
\item {noncommutative}
\item {right modules}
\end{itemize}

In this section we skip the staggered one and describe the simplest
examples in the remaining. Depending on the problem you dealing with
(commutative or noncommutative, algebras or modules) you can read
one of the following subsections. Another important alternative is selecting
a ground field. Here we suppose that the main field consists of
the rational numbers. You can read more about other alternative in the
subsection \ref{field}.

           \subsection{Commutative algebras}

Let us prepare the following file (suppose that its name is "test1.a"
It really exists in your originally installed version so you need not
create if it was not deleted or changed later):

{\bf
(ALGFORMINPUT)

setinvars x,y;

x$*$x$-$y$*$y, x$*$y;
}

The first line informs BERGMAN that the following is  input data in the
 algebraic form. It means that you need to write multiplication
 symbol $*$ or powers for example $x\wedge 2$ or x$**2$ instead of
 x$*$x but not $xx$
 (the same as in MAPLE). Other possibilities are LISP- or
 MACAULAY-form
 -- read about them in the subsection \ref{inputform}.

 Next two lines are input data themselves. First - variables, they should be
 written between keyword {\bf setinvars} and semicolon. Than the
 defining relations,
 separated by commas and finished by semicolon.

 To start the calculation select the name for output file, for example
 "test1.bg"
 (it should not
 exists!), start BERGMAN, switch to the LISP
 mode and write

 {\bf (simple "test1.a" "test1.bg")}

 (do not forget double quotes!) and then quit.

The following is the full session of our work.

\begin{verbatim}

E:\MATH\BERGMAN>br
Copyright (c) 1990 Ergo Computing, Inc.
Loading:d:\bergman\bergman0.9
System memory size is :3000000

4: end;
Entering LISP ...
Bergman 0.9,  Sat 24-8-1996
1 lisp> (simple "test1.a" "test.bg")
nil
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARALL), and run a new (SIMPLE).
nil
2 lisp> (quit)

Quitting
\end{verbatim}

Here is the resulting file "test1.bg", containing Gr\"{o}bner basis
\begin{verbatim}
% 2
x*y,
   x^2-y^2,

% 3
y^3,

Done


\end{verbatim}
Note that, according to the order of variables, x (the first in the list)
is highest, so xx, xy and yyy are highest monomials (obstructions).
So, only monomials 1, x, y, yy are normal (does not divisible by the
obstructions) and serve as a basis of our algebra. Its
dimension is equal 4  and we have here a multiplication table too.
(All elements of the Gr\"{o}bner basis are equal zero in algebra, so we can
use their highest terms for the reduction of non-normal words)
For example, x$*$x=yy, y$*$yy=yyy, x$*$yy=0.


Calling {\bf simple} without parameters you can introduce the relations
directly from the screen. Here is an example of the session:

\begin{verbatim}
1 lisp> (simple)
Now input in-variables and ideal generators in algebraic form, thus:
     setinvars v1, ..., vn;
      r1, ..., rm;
where v1, ..., vn are the variables, and r1, ..., rm the generators.
algebraic form (comm.) input> setinvars 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 (CLEARALL), and run a new (SIMPLE).
nil
2 lisp>
\end{verbatim}


\subsection{Noncommutative algebras}
Let us prepare the following file (suppose that its name is "test2.a"
It really exists in your originally installed version so you need not
create if it was not deleted or changed later):

{\bf
(NONCOMMIFY)

(SETQ MAXDEGREE 10)

(ALGFORMINPUT)

setinvars x,y;

x$*$x$-$y$*$y,x$*$y;
}

First line switches BERGMAN to the noncommutative mode. By default it
is in the commutative mode in the procedure SIMPLE (that is why we
did not use (COMMIFY) in the test1.a for commutative case.)

Second line was not necessary in this example. It restricts
calculations up to degree 10. Here calculations stops in the degree 3
(as you will see later), but in general Gr\"{o}bner basis might be
infinite so it is recommended to restrict degree of calculations
(although BERGMAN will try to do them until it will be insufficient
memory).

Third line informs BERGMAN that the following is  input data in the
 algebraic form. It means that you need to write multiplication
 symbol $*$ or powers for example $x\wedge 2$ or
 x$**2$ instead of x$*$x but not $xx$
 (the same as in MAPLE). Other possibilities are LISP or MACAULAY -
 form - read about them in the section \ref{inputform}.

 Next two lines are input data themselves. First - variables, they should be
 written between keyword {\bf setinvars} and semicolon. Than the
 defining relations,
 separated by commas and finished by semicolon.

 To start the calculation select the name for output file,
 for example "test2.bg" (it should not
 exists!), for example "test2.bg", start BERGMAN, switch to the LISP
 mode and write

 {\bf (simple "test2.a" "test2.bg")}

 (do not forget double quotes!) and then quit.

The following is the full session of our work.

\begin{verbatim}

E:\MATH\BERGMAN>br
Copyright (c) 1990 Ergo Computing, Inc.
Loading:e:\MATH\BERGMAN\bergman0.9
System memory size is :3000000

4: end;
Entering LISP ...
Bergman 0.9,  Sun 25-8-1996
1 lisp> (simple "test2.a" "test2.bg")
nil
10
nil
+t^2*(2*z^2)
+t^3*(2*z^2+2*z^3)
+t^4*(6*z^3+2*z^4)
 - All is OK (I hope). Now you may (e. g.):
   - kill bergman with (QUIT); or
   - interrupt bergman with ^Z; or
   - clear the memory with (CLEARALL), and run a new (SIMPLE).
nil
2 lisp> (quit)

Quitting
\end{verbatim}

Note that the session itself looks slightly different from commutative
case: the degree 10 and four terms of the monomial Poincar\'{e} series were
printed. And, of course, we have different output (Gr\"{o}bner basis)
too (although generators
and relations looks the same as in the commutative case):

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

% 3
x*x*x,
   y*x*x,

Done

\end{verbatim}

Note that, according to the order of variables, y (the last in the list --
opposite to the defaults in the commutative case)
is highest, so xy, yyx, xxx and yxx are highest monomials (obstructions).
So, only monomials 1, x, y, xx, yx are normal (does not contain
obstructions as subwords) and serve as a basis of our algebra. Its
dimension is equal 5 and we have here a multiplication table too.
(All elements of the Gr\"{o}bner basis are equal zero in algebra, so we can
use their highest terms for the reduction of non-normal words)
For example, x$*$x=xx, y$*$y=xx, x$*$xx=0.

Calling {\bf simple} without parameters you can introduce the relations
directly from the screen. Here is an example of the session:

\begin{verbatim}
2 lisp> (noncommify)
nil
3 lisp>  (simple)
Now input in-variables and ideal generators in algebraic form, thus:
     setinvars v1, ..., vn;
      r1, ..., rm;
where v1, ..., vn are the variables, and r1, ..., rm the generators.
algebraic form (noncomm.) input> setinvars x,y;x^2-y^2,x*y;
+t^2*(2*z^2)
% 2
x*y,
   -y*y+x*x,
   
+t^3*(2*z^2+2*z^3)
% 3
x*x*x,
   y*x*x,
   
+t^4*(6*z^3+2*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 (CLEARALL), and run a new (SIMPLE).
nil

\end{verbatim}

In the following example we use another procedure, working with
noncommutative algebras only and calculating besides the Gr\"{o}bner basis
of the algebra the Hilbert and monomial Poincar\'{e} series.

We use the same input and output file (supposing that the last one
does not exists!) and want to get two new files, one ''test2.hs'' for
the
Hilbert series and ''test2.ps'' for the Poincar\'e series. Procedure
names {\bf ncpbhgroebner} ( from NonCommutative Poincar\'e - Betti series)
and always
have 4 parameters. Here is a session (messages can be different)

\begin{verbatim}
1 lisp> (ncpbhgroebner "test2.a" "test2.bg" "test2.ps" "test2.hs")
*** I turn on noncommutativity
nil
10
nil
*** Function `degreeenddisplay' has been redefined

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

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

% No. of Spolynomials calculated until degree 4: 8
% No. of ReducePol(0) demanded until degree 4: 5
% Time: 833
*** Function `degreeenddisplay' has been redefined
nil
2 lisp>
\end{verbatim}

File "test2.hs" for Hilbert series looks now as

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

(note that known from the very beginning part \verb- 1+2*z- is absent here)
but file "test2.ps" for the monomial Poincar\'{e} series looks as



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

and also does not contain first terms \verb- 1+t*(2*z).-

Note also that both series does not contain terms in the degree more
then 4 - the last degree where BERGMAN have done some calculations.

But you will be especially surprised investigating  "test2.bg."
It looks now as:

\begin{verbatim}
% 2
((1 1 2))
((-1 2 2) (1 1 1))

% 3
((1 1 1 1))
((1 2 1 1))

Done
\end{verbatim}

It means that the result was written in the LISP form. You can try to
understand it (it is the same as before - try to recognize it!) or
read
about this more in the subsection \ref{inputform}, but let us
now change a little the input file and name it "test3.bg."

\begin{verbatim}
(NONCOMMIFY)
(SETQ MAXDEGREE 10)
(SETQ ALGOUTMODE 'MAPLE)
(ALGFORMINPUT)
setinvars x,y;
x*x-y*y,x*y;
\end{verbatim}

The session looks now almost the same (but the message about maple
appeared):

\begin{verbatim}

1 lisp> (ncpbhgroebner "test3.a" "test3.bg" "test3.ps" "test3.hs")
*** I turn on noncommutativity
nil
10
maple
nil
*** Function `degreeenddisplay' has been redefined

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

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

% No. of Spolynomials calculated until degree 4: 8
% No. of ReducePol(0) demanded until degree 4: 5
% Time: 833
*** Function `degreeenddisplay' has been redefined
nil
2 lisp>

\end{verbatim}

But the file "test3.bg" will be now the same as "test2.bg" in the
example with {\bf simple }:

\begin{verbatim}

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


\subsection{modules over noncommutative algebras}


