 
\subsection{The list  of  the top level procedures}\label{functions}

 In the description below, an EXPR evals its arguments, while a FEXPR
doesn't. If you want to give an identifier name directly as an argument
to an EXPR, you must quote it (QUOTE name) or 'name; otherwise the Lisp
will try to feed the value of the identifier to the EXPR. On the other
hand, you should NOT quote the arguments to a FEXPR. (Numbers and
strings need never be quoted, since they are evaluated to themselves.)



The general use of {\bf bergman} includes:

 \begin{description}
\index{addalgoutmode} \item [(ADDALGOUTMODE]
  mode-name bop+ bop- ip+ ip- ip* ip$\verb-^-$ eop bol eol): FEXPR

  If mode-name is not a recognised algebraic output mode name (to which
you can set ALGOUTMODE), mode-name is added to the list of such names.
The seven first of the remaining arguments are used in printing
polynomials in this mode; the two last are at present only used in some
specialised series output printing. The mnemonics are:

 bop (eop) = beginning (end) of polynomial,
 
 ip = within a polynomial,
 
 bol (eol) = beginning (end) of list.
 
When a polynomial is output in mode mode-name, first bop+ or bop-
(depending on the sign of the first coefficient) is printed; then
the absolute value of the first coefficient, followed by ip*, if
this absolute value is not 1; et cetera. The polynomial is ended by
eop. (In ALG mode, this has the bad effect of letting a comma
follow also the last polynomial.)

\index{algforminput} \item [(ALGFORMINPUT)]: EXPR

  Scans the succeeding input for variable lists and/or polynomial
input on ALG form; see above.

\index{autoreduceinput} \item [(AUTOREDUCEINPUT)]: EXPR

  This is used in the SAWS module, in order to auto-reduce the input
(after reading in but before starting the Gr\"{o}bner or SAWS basis
calculation). It is unnecessary with the ordinary algorithms. If you
are in SAWS mode and KNOW that your input is auto-reduced anyhow,
you may omit it.

\index{bigarithp} \item [(BIGARITHP)]: EXPR

  ''Big Arithmetics Property''. Should return T if big arithmetics work,
NIL else.

\index{bigoutput} \item [(BIGOUTPUT)]: EXPR

  Causes the printing of the calculated Gr\"{o}bner Basis, in LISP form
if ALGOUTMODE has not been set to ALG, MACAULAY, or a user defined
algebraic output mode. (See also ADDALGOUTMODE.)

\index{calctolimit} \item [(CALCTOLIMIT PositiveInteger)]: EXPR

  Seems to have the same effect as TDEGREECALCULATEPBSERIES seems to
have.%?

\index{calcreductorpriority} \item [(CALCREDUCTORPRIORITY augmon)]: EXPR

  When this procedure is called, the pointer of the input monomial
is set to a new Gr\"{o}bner basis element. The procedure should
return an integer. Such 'priority' integers later may be used in
order to compare Gr\"{o}bner basis elements in order to decide which
one of them to employ in a reduction. A Gr\"{o}bner basis element
with lower 'priority number' is preferred.

By redefining this procedure, the user thus may influence the
reductions of other polynomials, and the choices of what critical
pairs to consider.

(It should be noted, however, that 'priority comparisons' are made
only in some situations.)

\index{clearideal} \item [(CLEARIDEAL)]: EXPR

  This removes MOST remaining memories of former calculations, such
as remaining input, calculated (partial) Gr\"{o}bner basis, and
remaining critical pairs. It does not change the modes, nor the set
input or output variables or embedding dimension.

\index{degreeenddisplay} \item [(DEGREEENDDISPLAY)]: EXPR (User defined option.)

  Since control over output seems to be a very much wished possibility,
the user is given the option of defining his/her own degree-wise
output procedure. This procedure is performed after the calculation
of one degree, if the flag CUSTSHOW is on. It then replaces other
output; but you may call e. g. DEGREEOUTPUT within it.)

There may be an example definition of DEGREEENDDISPLAY provided;
you may see it by (GETD 'DEGREEENDDISPLAY).

\index{degreepbseriesdisplay} \item [(DEGREEPBSERIESDISPLAY)]: EXPR

  Prints the last degree item on DEGREEPBSERIES in an algebraic
format, using the TDEGVARIABLE and HDEGVARIABLE values as names
for the totaldegree and the homological degree variables,
respectively.

\index{degreeoutput} \item [(DEGREEOUTPUT)]: EXPR

  Performs output of the newly calculated Gr\"{o}bner basis elements (of
the current degree). If DEGREEOUTPREPARE has been given a file name
argument, output is directed to that file.

Is automatically called at the end of calculations for each degree,
if DEGREEPRINTOUT is on but CUSTSHOW is off.

\index{degreeoutprepare} \item [(DEGREEOUTPREPARE file-name)]: FEXPR (The argument is optional.)

  Redirects output to be performed degree by degree (by DEGREEOUTPUT
if CUSTSHOW is off), by turning on DEGREEPRINTOUT. If given a
file-name argument, and the file doesn't exist, output by
DEGREEOUTPUT is directed to that file.

\index{enddegreeoutput} \item [(ENDDEGREEOUTPUT)]: EXPR

  Prints ''Done'', and closes the Gr\"{o}bner basis output file (if any)
opened with DEGREEOUTPREPARE.
 Is automatically called at the end of calculation of the entire
Gr\"{o}bner basis, if DEGREEPRINTOUT is on but CUSTSHOW is off.

\index{getcurrentdegree} \item [(GETCURRENTDEGREE)]: EXPR

  Returns the "current degree" (which is ordinarily set within the
Gr\"{o}bner basis routines), the total degree presently or last
under Gr\"{o}bner basis extension consideration. (Initially and
immediately after the CLEAR\-IDEAL, the current degree is NIL.)

\index{groebnerinit} \item [(GROEBNERINIT)]: EXPR

  Initiate various internal global variables, et cetera, before
running GROEBNERKERNEL. It should be called AFTER selecting modes
and performing input.

(The reason why this is not a part of GROEBNERKERNEL, is that for
some specialised applications (like reading in a partial Gr\"{o}bner
basis and continuing calculations from some high degree) one might
want to hand-set these variables.)

\index{groebnerkernel} \item [(GROEBNERKERNEL)]: EXPR

  Perform the main calculations. Should (normally) be preceded by
GROEBNERINIT and succeeded by GROEBNERFINISH.

\index{groebnerfinish} \item [(GROEBNERFINISH)]: EXPR

  Conclude the calculations; close the DEGREEOUTPREPAREd file, if any;
print out the entire basis, if DEGREEOUTPREPARE was not called and
CUSTSHOW is off; set some variables.

(Not a part of GROEBNERKERNEL for reasons similar to those for
GROEBNERINIT.)

\index{lispforminput} \item [(LISPFORMINPUT)]: EXPR

  Scans the succeeding input for polynomial input on LISP form; see
above.

\index{monintern} \item [(MONINTERN LispFormMonomial)]: EXPR

  Changes its argument from a LISP form monomial to a monomial
in the appropriate internal representation, and returns the
changed monomial.

Warning: The output monomial may not be a printable lisp object.

\index{monlispout} \item [(MONLISPOUT InternalFormMonomial)]: EXPR

  Produces a LISP form of its argument, without changing the
argument.

\index{ncpbhded} \item [(NCPBHDED)]: EXPR

  The DEGREEENDDISPLAY alternative definition used by\\ NCPBHGROEBNER.

\index{normalform} \item [(NORMALFORM ratpol)] : EXPR

  Changes its argument to the ratpol representation of the normal form
of its input (with respect to GBasis). Returns NIL if the normal form
is zero, its changed argument else.

\index{polalgout} \item [(POLALGOUT InternalFormPolynomial)]: EXPR

  Prints its argument (an internally represented polynomial), in
algebraic form if the appropriate settings are done, else in LISP
form.

\index{polintern} \item [(POLINTERN LispFormPolynomial)]: EXPR

  Changes its argument from a LISP form polynomial to a polynomial
in the appropriate internal representation, and returns the
changed polynomial if it is non-zero; else it returns NIL.

Warning: The output polynomial may not be a printable lisp object.

\index{puremonprint} \item [(PUREMONPRINT mon)]: EXPR

  Prints its argument (an internally represented monomial), in
algebraic form if the appropriate settings are done, else in LISP
form.

\index{qpolmonmult} \item [(QPOLMONMULT ratpol puremon)] : EXPR

  Returns a ratpol representation of the product of ratpol
and puremon (in this order), without changing its arguments.

\index{redand2lispout} \item [(REDAND2LISPOUT Reductand-Polynomial)]: EXPR

  Produce a LISP form of its argument, without changing the
argument.

REDANDCF!+, REDANDCF!-, REDANDCF!-!-, REDANDCF!*,\\
REDANDCF!/,
REDANDCFREMAINDER, REDANDCFDIVISION

Each of these EXPRs take one or two redandcoeffs as input, and
perform the operations addition, negation ( = ''unary minus''),
subtraction, multiplication, truncated division, taking of remainder
with respect to truncated division, and lastly performing both these
operations at once  returning CONS of the resulting truncated
quotient and the remainder).  The output is a redandcoeff (or a
dotted pair of such), with NIL representing zero in the output; zero
input is not permitted.
(Also see protocol.txt.)

Using these procedures in most cases would be very slow compared
to ordinary operations; thus they should be avoided.

\index{redandmonmult} \item [(REDANDMONMULT augredand puremon)] : EXPR

  Returns the augredand representation of the product of augredand
and puremon (in this order), without changing its arguments.

\index{redor2lispout} \item [(REDOR2LISPOUT Reductor-Polynomial)]: EXPR

  Produce a LISP form of its argument, without changing the
argument.

\index{setcurrentdegree} \item [(SETCURRENTDEGREE int)]: EXPR

  For very special applications only, this procedure provides the
user the possibility to set the internal "current degree" to int,
which must be a non-negative integer or nil. (Cf. GETCURRENTDEGREE.)

 *** WARNING: Changing the current degree in the middle of

 *** calculations, or during succeeding series calculations to higher

 *** degrees, might cause rather weird results.

\index{staggerinit} \item [(STAGGERINIT)]: EXPR

  Used in the SAWS mode for some extra initiations (after GROEBNERINIT,
STAGTYPECHECKER, and AUTOREDUCEINPUT, but before STAGGERKERNEL).

\index{staggerkernel} \item [(STAGGERKERNEL)]: EXPR

  The SAWS mode replacement of GROEBNERKERNEL.

\index{staggerfinish} \item [(STAGGERFINISH)]: EXPR

  The SAWS mode replacement of GROEBNERFINISH.

\index{stagtypechecker} \item [(STAGTYPECHECKER)]: EXPR

  Used in the SAWS mode for some mode settings.

\index{tdegreecalculatepbseries} \item [(TDEGREECALCULATEPBSERIES PositiveInteger)]: EXPR

  Only works if the associated monomial ring Poincare-Betti series has
been calculated, but only to some degree less than PositiveInteger.
It then causes a continued calculation up to and including
PositiveInteger. (It returns NIL; use other ways of seeing the
result.)

\index{tdegreehseriesout} \item [(TDEGREEHSERIESOUT PositiveInteger)]: EXPR

  Returns the Hilbert function (i. e. Hilbert series coefficient)
for PositiveInteger, provided the DOUBLEPOINCARESERIES is
calculated to that degree. (If necessary, induces calculations
of HILBERTSERIES and INVHILBERTSERIES items.)

\end{description}

\subsection{User available flags and variables}\label{flags}

 The flags are turned ON and OFF by the procedures with these names.
The flag names should not be quoted. If you need to access the flag
values, you should use the values of the names, preceded by *.
The value NIL means OFF, and T means ON. You should not change
these values by other means than OFF and ON (even if this mostly
works).

 The variables are set by means of SETQ, which takes two arguments:
the variable name (which should not be quoted) and the value. The
value is evaluated, and thus an intended identifier name value when
given directly should be quoted.

 Examples: You turn the flag FLAG on and off by (ON FLAG) and
(OFF FLAG) respectively. When FLAG is ON, the value of *FLAG is T.
You give the variable VAR the values 10 or SILLY by
(SETQ VAR 10) or (SETQ VAR 'SILLY), respectively.

 You may also use other Standard Lisp procedures, such as SET. If
you are in a Reduce surrounding, you may use Reduce symbolic mode
procedures and syntax. The examples above then might look like

ON FLAG;

OFF FLAG;

VAR:=10;

VAR := 'SILLY;

 For various reasons, the trend will be to move from using Lisp
mode variables and flags in user mode, replacing them with specific
variable and flag change and query procedures, with ordinary
bergman syntax.

  USER AVAILABLE FLAGS (which are set/unset with ON/OFF). If not
  otherwise indicated, it is described the effect of the flag being ON.

  The default is OFF, if not otherwise indicated. Sometimes
  mode-changers will affect some flags.

\begin{description} 
\index{custshow} \item [CUSTSHOW]

  If it is turned on we get several customised display actions:

\begin{itemize}  
\item  GROEBNERKERNEL exhibits output degree by degree, by means of
  the user customised procedure DEGREEENDDISPLAY. (This is intended for
  customisation. There MAY exist an examplifying definition, showing how
  to demand some statistics at each end of degree; if so, you could read
  it with (GETD DEGREEENDDISPLAY).)
\item If furthermore the user has defined CUSTDISPLAYINIT, then this
  procedure (with no argument) replaces the normal displaying initiation
  actions performed when executing GROEBNERINIT. (These normal actions
  are to set NOOFSPOLCALCS and NOOFNILREDUCTIONS to zero.)
\item  If the user has defined CUSTCLEARCDEGDISPLAY, then this procedure
  (with no argument) is called first within a CLEARCDEGREEGKINPUT call.
\item  If the user has defined HSERIESMINCRITDISPLAY and the MINHILBLIMIT
  strategy mode is active, then when this strategy leads to the abortion
  of the rest of the calculations at the current degree (since the last
  possible new Gr\"{o}bner basis element is just found)
  HSERIESMINCRITDISPLAY (with no argument) is called.
\end{itemize}

\index{custstrategy} \item [CUSTSTRATEGY]

  WARNING: Don't turn this ON unless you have familiarised yourself
with the internal programming of bergman!
 If it is turned on and if the user has defined one or several of the
following procedures, calling them supplants the action of the
following procedures:
\begin{itemize}
  
\item  CUSTNEWINPUTGBEFIND supplants the action of FindInputNGbe;
\item  CUSTCRITPAIRTONEWGBE supplants the action of FindCritPairNGbe;
\item  CUSTENDDEGREECRITPAIRFIND supplants the action of DEnSPairs;
\item  CUSTNEWCDEGFIX supplants the action of FixNcDeg.
\end{itemize}

% COMMENTS: FindInputNGbe and FindCritPairNGbe should return non-NIL
%iff a new Gr\"{o}bner basis element is to be saved.
%FixNcDeg should return NIL/SKIPCDEG/otherwise, if (calculations
%should end)/(the current degree should be skipped)/(calculations
%should continue as usual).
%FixNcDeg and thus CUSTNEWCDEGFIX get an integer input, 1/2/3 for
%"At the new current degree there are (input polynomials)/(critical
%pairs)/both".

It is possible to get the 'true' action of the bergman
procedure to be performed, by the 'PROG variable initiation trick'.
Whenever a variable is declared as a PROG variable, it is locally
bound to NIL. Thus e.g. the following bit of Standard Lisp code
\begin{verbatim}
(OFF RAISE)
(DE CUSTENDDEGREECRITPAIRFIND ()
 (PROG  (!*CUSTSTRATEGY)
        <action 1>
        (DEnSPairs)
        <action 2> ))
(ON RAISE)
\end{verbatim}

defines CUSTENDDEGREECRITPAIRFIND in such a way, that when
CUSTSTRATEGY is ON a call to DEnSPairs yields the following effect:
First $<$action 1$>$ is taken, then DEnSPairs is called recursively but
with CUSTSTRATEGY OFF (if $<$action 1$>$ didn't turn it ON), performing
its ordinary action, and last $<$action 2$>$ is taken.


\index{degreeprintoutput} \item [DEGREEPRINTOUTPUT]

  Only influential when the SAWS algorithm is used. Then makes the final
reduced Gr\"{o}bner basis be exhibited degree by degree, with separating
degree annotations, as in `ordinary' degree-wise output. (C.f. SAVEDEGREE.)

\index{dynamiclogtables} \item [DYNAMICLOGTABLES]

  When MODLOGARITHMS is on and (SETMODULUS <prime>) is executed with an
 odd integer as <prime>, and a saved logarithms table file is not found,
 then logarithm tables are constructed. If DYNAMICLOGTABLES is OFF, this
 is done in a subshell, writing a file which is read into the bergman
 session but also saved for future use. If it is ON, then the tables
 should be constructed directly (and ephemarily).
  (THE DYNAMIC LOGTABLES CREATION IS NOT YET IMPLEMENTED.)

\index{homogenised} \item [HOMOGENISED]

  Turned ON/OFF by the (de-)homogenising routines.
Touch it only e.g. to fool the system that the data is or is not
homogenised, in order to perform an extra (de-)homogenisation.

\index{immediatecrit} \item [IMMEDIATECRIT]

  Turned ON/OFF by NONCOMMIFY/COMMIFY.
Try to eliminate critical pairs (employing various criteria) as soon
as a degree is finished, instead of waiting until the degree of the
pair is reached. Should NOT be turned ON in the commutative case!

\index{immediatefullreduction} \item [IMMEDIATEFULLREDUCTION]

  Default: ON.
Immediate full reduction of `old' Gr\"{o}bner basis elements by means of
newfound ones. (This is at variance with many other systems, where a
preliminary Gr\"{o}bner basis element will not be changed once it is
entered.)

\index{immediaterecdefine} \item [IMMEDIATERECDEFINE]

  Intended meaning: When calculating PBseries, define the recursive
 monomial-bound sub-series while these monomials anyhow are considered
 from the critical pair point of view. This option is not fully
 implemented, however, so the flag should NOT be turned ON.

\index{modlogarithms} \item [MODLOGARITHMS]

  Use `logarithm table methods' in (sufficiently small) positive
characteristics. Provided the appropriate table files exist or
a mechanism for automatically producing them is enabled, this
flag is strongly recommended to be turned ON.

\index{monoidal} \item [MONOIDAL]

  Used in some experimental variant to signify that we actually
 work within the monoid of monomials; i.e., that all relations are
 pure binomial. If this work is ever included into the general
 bergman framework, probably it will be in the form of mode
 changing procedures rather than by flag-setting, though.

\index{nobignum} \item [NOBIGNUM]

  Inhibit automatic loading of the bignum package. If you "know" that
no bignums will be needed in your particular run (although it e. g.
is in characteristic zero or the Hilbert series is calculated), you
may turn it ON BEFORE initialisations or mode-changings have invoked
it.

(Note that in your installation the Bignum package may already be
loaded from start, in which case the flag should be on by default.
This is probable, if you run bergman under Reduce.)

\index{obsoletenamesinform} \item [OBSOLETENAMESINFORM]

  Default: ON.
Some procedures have chan\-ged names from older bergman versions. For
backward compatibility, some older names are retained as synonyms
in this version (although they may be thrown away later). (They are
not documented in this manual or elsewhere.) If OBSOLETENAMESINFORM
is ON, then using one of them causes a warning to be printed,
together with an information on the new name, before executing it.

\index{pbseries} \item [PBSERIES]

  Turned ON/OFF by NONCOMMIFY/COMMIFY.
Should NOT be turned ON in the commutative case. Calculate the Poincar\'{e}-Betti series of the associated monomial ring (total degree-wise) (with a
method ONLY WORKING IN THE NON-COMMUTATIVE CASE)! Its effects are
partially superceeded by turning CUSTSHOW ON - take care that your
DEGREEENDDISPLAY calls e. g. TDEGREECALCULATEPBSERIES in this case. The
most important use of this is to get the Hilbert series of the ring.

\index{posleadcoeffs} \item [POSLEADCOEFFS]

  Default: ON.
In the characteristic 0 case, make sure that the final reduced Gr\"{o}bner
basis element leading coefficients are positive. (Turning it OFF saves
very little calculation, but makes the result compatible with results
from older versions of bergman.)

\index{reductivity} \item [REDUCTIVITY]

  Turned ON when the SAWS module is loaded.
Inhibits the `cannibalising' garbage collection of lower degree
monomials, thus making it possible to use the Gr\"{o}bner basis for
calculating normal forms. It may be turned ON for this purpose, or
because the `cannibalism' may have unwanted side effects in the
context. (This still MIGHT happen with some weird non-commutative
inputs; I am not sure. It DEFINITELY could happen if you run the SAWS
algorithm with REDUCTIVITY OFF; DON'T do it!)

\index{saveaccidentalreducibilityinfo} \item [SAVEACCIDENTALREDUCIBILITYINFO]

  Only active within the SAWS mode. If ON, save and re-use information on
whether or not a leading monomial is divisible by another Gbe leading
monomial (disregarding substance).

\index{savedegree} \item [SAVEDEGREE]

  Turned ON/OFF by\\
  DEGREEOUTPREPARE/ENDDEGREEOUTPUT.
Make GROEBNERKERNEL exhibit output degree by degree, by means of the
inbuilt procedure DEGREEOUTPUT. (Is overruled by CUSTSHOW.)
 In general, the final result is output. However, if the SAWS algorithm
is active, it is the preliminary (staggered linear) basis which is
output. In this case, the final reduced Gr\"{o}bner basis is NOT calculated
degree-wise, and so no speed is gained by exhibiting output degree-wise.
If you anyhow wish such output (e. g., for compatibility reasons), you
may turn ON DEGREEPRINTOUTPUT.

%(SAVEINHOMOGMONLIST ?????)

\index{saverecvaluse} \item [SAVERECVALUES]

  Default: ON.
In the Poicar\'e-Betti series algorithm, numerous interdepending integer
series are defined by linear recursion formulae. When the flag is ON,
the calculated values at each degree are saved. This saves (considerable)
time, but sometimes may use considerable space.

\index{trbr} \item [TRBR]

  Only used in debugging.
If ON, calling IfTRBRbreak causes a break.)

\end{description}

\subsection{User available counters}

In most cases they should be initialised  to 0 by SETQ or Reduce assignment.

\begin{description}
\index{noofnilreductions} \item [NOOFNILREDUCTIONS]

  Counts the total number of times the normal form procedure ("ReducePol")
is called with an argument representing the zero polynomial.
(Ordinarily, this happens precisely whenever a new-formed S-polynomial
is zero before reduction.)

\index{noofreprioritations} \item [NOOFREPRIORITATIONS]

  In the SAWS algorithm, counts the number of times `all' the prioritation
values must be changed, in order to enable new (integer!) values between
two old ones.

\index{noofspolcalcs} \item [NOOFSPOLCALCS]

  Counts the number of S-polynomials actually formed. Together with a
counting of the final basis (except the input), this gives a good measure
of the efficiency of the critical pair elimination criteria.

\index{noofstagconecrit} \item [NOOFSTAGCONECRIT]

  Counts the number of applications of a SAWS algorithm elimination
 criterion. On this particular point, I am not sure whether this covers
 up some implementation bug or not.

\end{description}


\subsection{User readable variables}

These variables  should NOT be reset by the user.

The commutative/non-commutative series calculation results are available
as the values of (HILBERTNUMERATOR and HILBERTDENOMINATOR) or
(DOUBLEPBSERIES, HILBERTSERIES,\\
INVHILBERTSERIES, and SIMPLEPBSERIES),
respectively, in a printable LISP format. 



\subsection{User defined variables}

To be set by SETQ (or Reduce assignment)):

\begin{description}

\index{algoutmode} \item [ALGOUTMODE]

  Default: NIL
May be set to LISP, ALG, MACAULAY, or some user defined algebraic
output mode. (See ADDALGOUTMODE for the latter.). Governs the output
polynomial print-out form. (NIL has the same effect as LISP.)
For ALG form (Maple- or Reduce-like) or MACAULAY-like output to be
working, some knowledge of the intended variable names are necessary.
This is normally automatically provided by vars, used in ALGFORMINPUT.

Also see the input/output format section above.

\index{embdim} \item [EMBDIM]

  Default: NIL. Is set automatically by some initialisers.
The (intended) number of variables. (Commutatively, the "embedding
dimension".) If you make lisp-form input in the non-commutative
case, and want to know the Hilbert series, the EMBDIM should be
provided. (If you enumerate variables with the ALGFORMINPUT vars
command, the embedding dimension is deduced automatically.)

\index{hdegvariable} \item [HDEGVARIABLE]

  Default: !t.
 The Poincar\'{e}-Betti series print out homological degree variable
name. (The exclamation mark guarantees a precise printing, with
no case change.)

\index{initprioritystart} \item [INITPRIORITYSTART]

  Default: 0.
\index{initprioriysteplength} \item [INITPRIORITYSTEPLENGTH]

  Default: 32.
\index{reprioritysteplength} \item [REPRIORITYSTEPLENGTH]

  Default: 16.

  In the SAWS algorithm, the priorities are represented by integers. At the
beginning, the `lowest input polynomial' is assigned the priority
INITPRIORITYSTART, the next one INITPRIORITYSTART + INITPRIORITYSTEPLENGTH,
the next one INITPRIORITYSTART + 2*INITPRIORITYSTEPLENGTH, et cetera. New
elements get priorities `between' the old priorities. If this is not
possible, i. e., if a new priority should be chosen between two succeeding
integers, all but the first priority are changed, so that they get evenly
`spaced' with the `distance' REPRIORITYSTEPLENGTH. (The number of times
this happens is counted by NOOFREPRIORITATIONS.)
 The variables should be assigned (''small'') integer values, and (obviously)
you must choose INITPRIORITYSTEPLENGTH $>=1$ and REPRIORITYSTEPLENGTH $>=2$.

\index{maxdeg} \item [MAXDEG]

  Default: NIL.  If set (in which case it should be a positive integer), it provides an
upper bound for critical pair forming et cetera. Thus it makes the Gr\"{o}bner
basis or SAWS algorithm terminate not later than at MAXDEG. There is no
(direct) way to check whether or not the termination was due to the
MAXDEG, or would have occurred anyhow.

\index{tdegvariable} \item [TDEGVARIABLE]

  Default: !z.
 The Hilbert and Poincar\'{e}-Betti series print out total degree variable
name. (The exclamation mark guarantees a precise printing, with
no case change.)

\end{description}

%\subsection{Experimental functions  handling inhomogeneous  input/ouput}


%The bergman standard/Gr\"{o}bner basis calculation procedures  always assume
%their input to be homogeneous. In the non-commutative case, this
%prerequisite cannot be eliminated completely, since finding normal forms
%in a general inhomogeneous algebra is an insoluble problem. In the
%commutative case, on the other hand, we may aaterfoera the inhomogeneous
%case on the homogeneous, by homogenising the input, ...

\section{The commutative Hilbert series procedures} \label{comHS}

This section  contains information for the user about the 
commutative Hilbert series procedures. Since series handling is
in a transitory phase, all this is not yet very fixed, whence
most of it is NOT contained in the manual.

There are two main uses for the \index{Hilbert series} Hilbert series facilities: Stand alone
and within the Hilbert series \index{interrupt strategy} interrupt
  strategy minor mode. In the
former case, you may get the Hilbert series of the residue class
ring modulo a calculated Groebner basis or some user input
monomial ideal, as a rational expression$ p(t)/(1-t) \verb-^-q$, or with
the power series coefficient for some specified t degree(s). In
the latter, you should communicate a Hilbert series limitation to
the programme; it will automatically invoke the appropriate Hilbert
series calculations.

In either case, you may wish to inspect resulting series in situ
(especially as there are few prepared good user interface procedures
for this). You then should note that the global variables
HILBERTNUMERATOR and HILBERTDENOMINATOR represent a calculated
$$ p(t)/(1-t)\verb-^-q = (a_{n}t\verb-^-n + a_{n-1}t \verb-^-(n-1) +
\,.\,.\,. + a_{0})/(1-t) \verb-^-q $$
by (the lisp items)  $ ((n\  .\  a_{n}) (n-1\  .\  a_{n-1})
\,.+,.\,.
(0\  .\  a_{0}))$  and   $ q$,
respectively.


 A principal use of Hilbert series calculation is with the Hilbert
series interrupt strategy (which is based on ideas by Ralf Froeberg). You then
should provide a Hilbert series limitation. The limitation should be
a representation of a function f from the set N = \{0,1,2,...\} to the
union of N and the set \{NIL, T, SKIPCDEG\} of lisp constants. The
default limitation function has the constant value NIL for each
input. You may change the function with the SETHSERIES... procedures,
and you may inspect the current limitation function or part thereof
with the GETHSERIES... procedures, as explained below.

When bergman is in the Hilbert series interrupt strategy minor mode
and is about to start considering a new current degree d within the
GROEBNERKERNEL execution, it extracts the limitation function value
$f(d)$ and proceeds as follows:
\begin{itemize}
\item If $ f(d)$ is NIL, then GROEBNERKERNEL follows "procedures as
    usual" for the current degree d (with no non-ordinary
   constraints on the calculations).
\item If $ f(d)$ is T, then GROEBNERKERNEL is exited without any further
   calculations. (Thus we get an effect similar to a MAXDEG
  setting, but probable with some unnecessary critical pair
  calculation performed on degree d or higher.)
\item   If $f(d)$ is SKIPCDEG, then the current degree d is "skipped":
  critical pairs and input polynomials of degree d are removed,
  as if they (or the corresponding S--polynomials) were found to
  reduce to zero. (A new test is made for the next occurring
  degree.)
\item   If $f(d)$ is a non-negative integer, then calculation at degree
  d continues only until either all input polynomials and
  critical pairs of degree d are processed, or the associated
  quotient ring Hilbert series value for d, i.e., the vector
  space dimension of the degree d component of the residue class
   ring of the current polynomial ring modulo the ideal generated
  by the leading monomials of all (partial) groebner basis
 elements found so far, no longer exceeds $f(d)$; the the
 remaining input polynomials and critical pairs of degree d
 (if any) are skipped (like in the SKIPCDEG case). 
\end{itemize}

An $f(d)$  value either may be specified explicitly, or be calculated
by a default expression. The latter may be a constant (an integer
or one of NIL, T, and SKIPCDEG) or is considered as the definition
part of a lisp EXPR with the single argument HSDEG. An explicitly
specified value takes precedence over a default one. E.g., the
default expression

\begin{verbatim}
        (COND ((GREATERP HSDEG 10) T)
              ((LESSP HSDEG 3) SKIPCDEG)
              (T (PLUS HSDEG 2)))
\end{verbatim}

will make $  f(0) = f(1) = f(2) = SKIPCDEG,$
$  f(3) = 5, \,.\,.\,. , f(10) = 12,$ 
and $  f(d) = T$  for all other legitimate d values, except for those $d$
for which explicit values are given.


 Available high level procedures:
 
\begin{description}
  
\index{calcpolringseries} \item [(CALCPOLRINGHSERIES varno) : EXPR].

 Initialises \index{hilbertnumerator} HILBERTNUMERATOR and
 \index{hilbertdenominator}  HILBERTDENOMINATOR values to
those for the present polynomial rings. Right now, varno isn't
used; instead, the numbers of variables is extracted by means
of GETVARNO.

\index{calcrathilbertseries} \item [(CALCRATHILBERTSERIES) : EXPR].

  Uses the calculated (full or partial) Groebner basis in order to
calculate the Hilbert series for the residue class ring modulo
the ideal generated by the leading monomials of the basis elements.
 Errs if no (partial) Gr\"{o}bner basis is stored in GBasis.

\index{gbasis2hseriesmonid} \item [(GBASIS2HSERIESMONID) : EXPR].

  Creates a special kind of lisp form representation of the
monomial ideal generated by the leading monomials of the
calculated (full or partial) Gr\"{o}bner  basis. The format is a
(printable) list of flagged monomials (FMon's), as described in
the introduction to the source file hseries.sl.

\index{gethseriesminima} \item [(GETHSERIESMINIMA) : EXPR].

  Extracts the full information about the pre-stored Hilbert
series limitation, in a printable format acceptable as input to
SETHSERIESMINIMA.

\index{gethseriesminimum} \item [(GETHSERIESMINIMUM tdeg) : EXPR].

  Extracts the information about the pre--stored Hilbert series
limitation for degree tdeg, as an integer or as one of the
constants NIL, T, and \index{skipdeg} SKIPCDEG. (tdeg must be a non-negative
integer; else, rather weird errors may occur.)

\index{sethseriesminima} \item [(SETHSERIESMINIMA \ldots ) : FEXPR].

  Specify the Hilbert series limitations, as a sequence of
dotted pairs or as a list of limitation constants, in either
case optionally accompanied by a DEFAULT setting. In the
dotted pair variant, each dotted pair antecedent ("CAR part")
should be a non-negative integer or the identifier DEFAULT;
the postcedent ("CDR part") when the CAR is an integer d
should be the limitation for d (i.e., a non-negative integer
or one of the constants NIL, T, and SKIPCDEG), and when
the CAR is DEFAULT it should be of the
SETHSERIESMINIMUMDEFAULT input form. In the sequence case,
the items are considered as CDR parts corresponding to
CAR parts 0, 1, 2, \ldots  (in thgis order); everything after
DEFAULT is considered as the DEFAULT CDR part (whether or
not it is on list form). In either case, the default value
or procedure is changed only if a new DEFAULT is specified.

 Example:
\begin{verbatim}
(SETHSERIESMINIMA T SKIPCDEG NIL 6 7 8 9 DEFAULT 8)

and

(SETHSERIESMINIMA (0 . T) (1 . SKIPCDEG) (2) (3 . 6)
                       (4 . 7) (6 . 9) (DEFAULT . 8))
\end{verbatim}
                       
have the same effects. (Note that in lisp, (2) and (2\  .\  NIL)
are considered as identical.)

\index{sethseriesminimumdefault} \item [(SETHSERIESMINIMUMDEFAULT ...) : FEXPR].

  Specify the Hilbert series limitation default value or
procedure. (Explicitly specified values for specified
degrees are not changed.)


\index{tdegreehseriesout} \item [(TDEGREEHSERIESOUT PositiveInteger): EXPR].

  Returns the Hilbert function (i. e. Hilbert series coefficient)
for PositiveInteger (provided adequate series calculation up to
that degree is done previously).


\end{description}

% -------------------------------------------------------------
%To document in protocol.txt:  HSeriesCommify, ... .

%Recently defined/employed only in the non-commutative mode:
%       DEGREEPBSERIESDISPLAY, PBINIT, TDEGREECALCULATEPBSERIES;
%       !*IMMEDIATERECDEFINE, !*PBSERIES.











































































