This file contains information for the user about the new
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.



Before using the procedures, do (LOAD hseries).


There are two main uses for the Hilbert series facilities: Stand alone
and within the Hilbert series 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)^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)^q = (a_nt^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.


 A principal use of Hilbert series calculation is with the Hilbert
series interrupt strategy (which is based on ideas by Ralf Froeberg;
<insert reference to him and possibly other independents>). 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:

  - If f(d) is NIL, then GROEBNERKERNEL follows "procedures as
    usual" for the current degree d (with no non-ordinary
    constraints on the calculations).

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

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

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

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

	(COND ((GREATERP HSDEG 10) T)
	      ((LESSP HSDEG 3) SKIPCDEG)
	      (T (PLUS HSDEG 2)))

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:

 Nota bene: The Hilbert series limitations may be set or
unset at any time; but they will affect the Groebner basis
calculation only when the Hilbert series limitation strategy
minor mode is chosen. See MINHILBSTRATEGY and
SETINTERRUPTSTRATEGY.


(CALCPOLRINGHSERIES varno) : EXPR
 Initialises HILBERTNUMERATOR and 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.

(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) Groebner basis is stored in GBasis.

(CLEARHSERIESMINIMA) : EXPR
 Restore the default (NIL) setting of the Hilbert series
limitation.

(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) Groebner basis. The format is a
(printable) list of flagged monomials (FMon's), as described in
the introduction to the source file hseries.sl.

(GETHSERIESMINIMA) : EXPR
 Extract the full information about the pre-stored Hilbert
series limitation, in a printable format acceptable as input to
SETHSERIESMINIMA.

(GETHSERIESMINIMUM tdeg) : EXPR
 Extract the information about the pre-stored Hilbert series
limitation for degree tdeg, as an integer or as one of the
constants NIL, T, and SKIPCDEG. (tdeg must be a non-negative
integer; else, rather weird errors may occur.)

(SETHSERIESMINIMA ...) : 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, ... (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:  (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))
have the same effects. (Note that in lisp, (2) and (2 . NIL)
are considered as identical.)


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


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

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

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


