\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) (DEnSPairs) )) (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 ) is executed with an odd integer as , 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.