Debian Codegraph @

doc/bergman1.0.man/funclist.tex

raw
1
2 \subsection{The list of the top level procedures}\label{functions}
3
4 In the description below, an EXPR evals its arguments, while a FEXPR
5 doesn't. If you want to give an identifier name directly as an argument
6 to an EXPR, you must quote it (QUOTE name) or 'name; otherwise the Lisp
7 will try to feed the value of the identifier to the EXPR. On the other
8 hand, you should NOT quote the arguments to a FEXPR. (Numbers and
9 strings need never be quoted, since they are evaluated to themselves.)
10
11
12
13 The general use of {\bf bergman} includes:
14
15 \begin{description}
16 \index{addalgoutmode} \item [(ADDALGOUTMODE]
17 mode-name bop+ bop- ip+ ip- ip* ip$\verb-^-$ eop bol eol): FEXPR
18
19 If mode-name is not a recognised algebraic output mode name (to which
20 you can set ALGOUTMODE), mode-name is added to the list of such names.
21 The seven first of the remaining arguments are used in printing
22 polynomials in this mode; the two last are at present only used in some
23 specialised series output printing. The mnemonics are:
24
25 bop (eop) = beginning (end) of polynomial,
26
27 ip = within a polynomial,
28
29 bol (eol) = beginning (end) of list.
30
31 When a polynomial is output in mode mode-name, first bop+ or bop-
32 (depending on the sign of the first coefficient) is printed; then
33 the absolute value of the first coefficient, followed by ip*, if
34 this absolute value is not 1; et cetera. The polynomial is ended by
35 eop. (In ALG mode, this has the bad effect of letting a comma
36 follow also the last polynomial.)
37
38 \index{algforminput} \item [(ALGFORMINPUT)]: EXPR
39
40 Scans the succeeding input for variable lists and/or polynomial
41 input on ALG form; see above.
42
43 \index{autoreduceinput} \item [(AUTOREDUCEINPUT)]: EXPR
44
45 This is used in the SAWS module, in order to auto-reduce the input
46 (after reading in but before starting the Gr\"{o}bner or SAWS basis
47 calculation). It is unnecessary with the ordinary algorithms. If you
48 are in SAWS mode and KNOW that your input is auto-reduced anyhow,
49 you may omit it.
50
51 \index{bigarithp} \item [(BIGARITHP)]: EXPR
52
53 ''Big Arithmetics Property''. Should return T if big arithmetics work,
54 NIL else.
55
56 \index{bigoutput} \item [(BIGOUTPUT)]: EXPR
57
58 Causes the printing of the calculated Gr\"{o}bner Basis, in LISP form
59 if ALGOUTMODE has not been set to ALG, MACAULAY, or a user defined
60 algebraic output mode. (See also ADDALGOUTMODE.)
61
62 \index{calctolimit} \item [(CALCTOLIMIT PositiveInteger)]: EXPR
63
64 Seems to have the same effect as TDEGREECALCULATEPBSERIES seems to
65 have.%?
66
67 \index{calcreductorpriority} \item [(CALCREDUCTORPRIORITY augmon)]: EXPR
68
69 When this procedure is called, the pointer of the input monomial
70 is set to a new Gr\"{o}bner basis element. The procedure should
71 return an integer. Such 'priority' integers later may be used in
72 order to compare Gr\"{o}bner basis elements in order to decide which
73 one of them to employ in a reduction. A Gr\"{o}bner basis element
74 with lower 'priority number' is preferred.
75
76 By redefining this procedure, the user thus may influence the
77 reductions of other polynomials, and the choices of what critical
78 pairs to consider.
79
80 (It should be noted, however, that 'priority comparisons' are made
81 only in some situations.)
82
83 \index{clearideal} \item [(CLEARIDEAL)]: EXPR
84
85 This removes MOST remaining memories of former calculations, such
86 as remaining input, calculated (partial) Gr\"{o}bner basis, and
87 remaining critical pairs. It does not change the modes, nor the set
88 input or output variables or embedding dimension.
89
90 \index{degreeenddisplay} \item [(DEGREEENDDISPLAY)]: EXPR (User defined option.)
91
92 Since control over output seems to be a very much wished possibility,
93 the user is given the option of defining his/her own degree-wise
94 output procedure. This procedure is performed after the calculation
95 of one degree, if the flag CUSTSHOW is on. It then replaces other
96 output; but you may call e. g. DEGREEOUTPUT within it.)
97
98 There may be an example definition of DEGREEENDDISPLAY provided;
99 you may see it by (GETD 'DEGREEENDDISPLAY).
100
101 \index{degreepbseriesdisplay} \item [(DEGREEPBSERIESDISPLAY)]: EXPR
102
103 Prints the last degree item on DEGREEPBSERIES in an algebraic
104 format, using the TDEGVARIABLE and HDEGVARIABLE values as names
105 for the totaldegree and the homological degree variables,
106 respectively.
107
108 \index{degreeoutput} \item [(DEGREEOUTPUT)]: EXPR
109
110 Performs output of the newly calculated Gr\"{o}bner basis elements (of
111 the current degree). If DEGREEOUTPREPARE has been given a file name
112 argument, output is directed to that file.
113
114 Is automatically called at the end of calculations for each degree,
115 if DEGREEPRINTOUT is on but CUSTSHOW is off.
116
117 \index{degreeoutprepare} \item [(DEGREEOUTPREPARE file-name)]: FEXPR (The argument is optional.)
118
119 Redirects output to be performed degree by degree (by DEGREEOUTPUT
120 if CUSTSHOW is off), by turning on DEGREEPRINTOUT. If given a
121 file-name argument, and the file doesn't exist, output by
122 DEGREEOUTPUT is directed to that file.
123
124 \index{enddegreeoutput} \item [(ENDDEGREEOUTPUT)]: EXPR
125
126 Prints ''Done'', and closes the Gr\"{o}bner basis output file (if any)
127 opened with DEGREEOUTPREPARE.
128 Is automatically called at the end of calculation of the entire
129 Gr\"{o}bner basis, if DEGREEPRINTOUT is on but CUSTSHOW is off.
130
131 \index{getcurrentdegree} \item [(GETCURRENTDEGREE)]: EXPR
132
133 Returns the "current degree" (which is ordinarily set within the
134 Gr\"{o}bner basis routines), the total degree presently or last
135 under Gr\"{o}bner basis extension consideration. (Initially and
136 immediately after the CLEAR\-IDEAL, the current degree is NIL.)
137
138 \index{groebnerinit} \item [(GROEBNERINIT)]: EXPR
139
140 Initiate various internal global variables, et cetera, before
141 running GROEBNERKERNEL. It should be called AFTER selecting modes
142 and performing input.
143
144 (The reason why this is not a part of GROEBNERKERNEL, is that for
145 some specialised applications (like reading in a partial Gr\"{o}bner
146 basis and continuing calculations from some high degree) one might
147 want to hand-set these variables.)
148
149 \index{groebnerkernel} \item [(GROEBNERKERNEL)]: EXPR
150
151 Perform the main calculations. Should (normally) be preceded by
152 GROEBNERINIT and succeeded by GROEBNERFINISH.
153
154 \index{groebnerfinish} \item [(GROEBNERFINISH)]: EXPR
155
156 Conclude the calculations; close the DEGREEOUTPREPAREd file, if any;
157 print out the entire basis, if DEGREEOUTPREPARE was not called and
158 CUSTSHOW is off; set some variables.
159
160 (Not a part of GROEBNERKERNEL for reasons similar to those for
161 GROEBNERINIT.)
162
163 \index{lispforminput} \item [(LISPFORMINPUT)]: EXPR
164
165 Scans the succeeding input for polynomial input on LISP form; see
166 above.
167
168 \index{monintern} \item [(MONINTERN LispFormMonomial)]: EXPR
169
170 Changes its argument from a LISP form monomial to a monomial
171 in the appropriate internal representation, and returns the
172 changed monomial.
173
174 Warning: The output monomial may not be a printable lisp object.
175
176 \index{monlispout} \item [(MONLISPOUT InternalFormMonomial)]: EXPR
177
178 Produces a LISP form of its argument, without changing the
179 argument.
180
181 \index{ncpbhded} \item [(NCPBHDED)]: EXPR
182
183 The DEGREEENDDISPLAY alternative definition used by\\ NCPBHGROEBNER.
184
185 \index{normalform} \item [(NORMALFORM ratpol)] : EXPR
186
187 Changes its argument to the ratpol representation of the normal form
188 of its input (with respect to GBasis). Returns NIL if the normal form
189 is zero, its changed argument else.
190
191 \index{polalgout} \item [(POLALGOUT InternalFormPolynomial)]: EXPR
192
193 Prints its argument (an internally represented polynomial), in
194 algebraic form if the appropriate settings are done, else in LISP
195 form.
196
197 \index{polintern} \item [(POLINTERN LispFormPolynomial)]: EXPR
198
199 Changes its argument from a LISP form polynomial to a polynomial
200 in the appropriate internal representation, and returns the
201 changed polynomial if it is non-zero; else it returns NIL.
202
203 Warning: The output polynomial may not be a printable lisp object.
204
205 \index{puremonprint} \item [(PUREMONPRINT mon)]: EXPR
206
207 Prints its argument (an internally represented monomial), in
208 algebraic form if the appropriate settings are done, else in LISP
209 form.
210
211 \index{qpolmonmult} \item [(QPOLMONMULT ratpol puremon)] : EXPR
212
213 Returns a ratpol representation of the product of ratpol
214 and puremon (in this order), without changing its arguments.
215
216 \index{redand2lispout} \item [(REDAND2LISPOUT Reductand-Polynomial)]: EXPR
217
218 Produce a LISP form of its argument, without changing the
219 argument.
220
221 REDANDCF!+, REDANDCF!-, REDANDCF!-!-, REDANDCF!*,\\
222 REDANDCF!/,
223 REDANDCFREMAINDER, REDANDCFDIVISION
224
225 Each of these EXPRs take one or two redandcoeffs as input, and
226 perform the operations addition, negation ( = ''unary minus''),
227 subtraction, multiplication, truncated division, taking of remainder
228 with respect to truncated division, and lastly performing both these
229 operations at once returning CONS of the resulting truncated
230 quotient and the remainder). The output is a redandcoeff (or a
231 dotted pair of such), with NIL representing zero in the output; zero
232 input is not permitted.
233 (Also see protocol.txt.)
234
235 Using these procedures in most cases would be very slow compared
236 to ordinary operations; thus they should be avoided.
237
238 \index{redandmonmult} \item [(REDANDMONMULT augredand puremon)] : EXPR
239
240 Returns the augredand representation of the product of augredand
241 and puremon (in this order), without changing its arguments.
242
243 \index{redor2lispout} \item [(REDOR2LISPOUT Reductor-Polynomial)]: EXPR
244
245 Produce a LISP form of its argument, without changing the
246 argument.
247
248 \index{setcurrentdegree} \item [(SETCURRENTDEGREE int)]: EXPR
249
250 For very special applications only, this procedure provides the
251 user the possibility to set the internal "current degree" to int,
252 which must be a non-negative integer or nil. (Cf. GETCURRENTDEGREE.)
253
254 *** WARNING: Changing the current degree in the middle of
255
256 *** calculations, or during succeeding series calculations to higher
257
258 *** degrees, might cause rather weird results.
259
260 \index{staggerinit} \item [(STAGGERINIT)]: EXPR
261
262 Used in the SAWS mode for some extra initiations (after GROEBNERINIT,
263 STAGTYPECHECKER, and AUTOREDUCEINPUT, but before STAGGERKERNEL).
264
265 \index{staggerkernel} \item [(STAGGERKERNEL)]: EXPR
266
267 The SAWS mode replacement of GROEBNERKERNEL.
268
269 \index{staggerfinish} \item [(STAGGERFINISH)]: EXPR
270
271 The SAWS mode replacement of GROEBNERFINISH.
272
273 \index{stagtypechecker} \item [(STAGTYPECHECKER)]: EXPR
274
275 Used in the SAWS mode for some mode settings.
276
277 \index{tdegreecalculatepbseries} \item [(TDEGREECALCULATEPBSERIES PositiveInteger)]: EXPR
278
279 Only works if the associated monomial ring Poincare-Betti series has
280 been calculated, but only to some degree less than PositiveInteger.
281 It then causes a continued calculation up to and including
282 PositiveInteger. (It returns NIL; use other ways of seeing the
283 result.)
284
285 \index{tdegreehseriesout} \item [(TDEGREEHSERIESOUT PositiveInteger)]: EXPR
286
287 Returns the Hilbert function (i. e. Hilbert series coefficient)
288 for PositiveInteger, provided the DOUBLEPOINCARESERIES is
289 calculated to that degree. (If necessary, induces calculations
290 of HILBERTSERIES and INVHILBERTSERIES items.)
291
292 \end{description}
293
294 \subsection{User available flags and variables}\label{flags}
295
296 The flags are turned ON and OFF by the procedures with these names.
297 The flag names should not be quoted. If you need to access the flag
298 values, you should use the values of the names, preceded by *.
299 The value NIL means OFF, and T means ON. You should not change
300 these values by other means than OFF and ON (even if this mostly
301 works).
302
303 The variables are set by means of SETQ, which takes two arguments:
304 the variable name (which should not be quoted) and the value. The
305 value is evaluated, and thus an intended identifier name value when
306 given directly should be quoted.
307
308 Examples: You turn the flag FLAG on and off by (ON FLAG) and
309 (OFF FLAG) respectively. When FLAG is ON, the value of *FLAG is T.
310 You give the variable VAR the values 10 or SILLY by
311 (SETQ VAR 10) or (SETQ VAR 'SILLY), respectively.
312
313 You may also use other Standard Lisp procedures, such as SET. If
314 you are in a Reduce surrounding, you may use Reduce symbolic mode
315 procedures and syntax. The examples above then might look like
316
317 ON FLAG;
318
319 OFF FLAG;
320
321 VAR:=10;
322
323 VAR := 'SILLY;
324
325 For various reasons, the trend will be to move from using Lisp
326 mode variables and flags in user mode, replacing them with specific
327 variable and flag change and query procedures, with ordinary
328 bergman syntax.
329
330 USER AVAILABLE FLAGS (which are set/unset with ON/OFF). If not
331 otherwise indicated, it is described the effect of the flag being ON.
332
333 The default is OFF, if not otherwise indicated. Sometimes
334 mode-changers will affect some flags.
335
336 \begin{description}
337 \index{custshow} \item [CUSTSHOW]
338
339 If it is turned on we get several customised display actions:
340
341 \begin{itemize}
342 \item GROEBNERKERNEL exhibits output degree by degree, by means of
343 the user customised procedure DEGREEENDDISPLAY. (This is intended for
344 customisation. There MAY exist an examplifying definition, showing how
345 to demand some statistics at each end of degree; if so, you could read
346 it with (GETD DEGREEENDDISPLAY).)
347 \item If furthermore the user has defined CUSTDISPLAYINIT, then this
348 procedure (with no argument) replaces the normal displaying initiation
349 actions performed when executing GROEBNERINIT. (These normal actions
350 are to set NOOFSPOLCALCS and NOOFNILREDUCTIONS to zero.)
351 \item If the user has defined CUSTCLEARCDEGDISPLAY, then this procedure
352 (with no argument) is called first within a CLEARCDEGREEGKINPUT call.
353 \item If the user has defined HSERIESMINCRITDISPLAY and the MINHILBLIMIT
354 strategy mode is active, then when this strategy leads to the abortion
355 of the rest of the calculations at the current degree (since the last
356 possible new Gr\"{o}bner basis element is just found)
357 HSERIESMINCRITDISPLAY (with no argument) is called.
358 \end{itemize}
359
360 \index{custstrategy} \item [CUSTSTRATEGY]
361
362 WARNING: Don't turn this ON unless you have familiarised yourself
363 with the internal programming of bergman!
364 If it is turned on and if the user has defined one or several of the
365 following procedures, calling them supplants the action of the
366 following procedures:
367 \begin{itemize}
368
369 \item CUSTNEWINPUTGBEFIND supplants the action of FindInputNGbe;
370 \item CUSTCRITPAIRTONEWGBE supplants the action of FindCritPairNGbe;
371 \item CUSTENDDEGREECRITPAIRFIND supplants the action of DEnSPairs;
372 \item CUSTNEWCDEGFIX supplants the action of FixNcDeg.
373 \end{itemize}
374
375 % COMMENTS: FindInputNGbe and FindCritPairNGbe should return non-NIL
376 %iff a new Gr\"{o}bner basis element is to be saved.
377 %FixNcDeg should return NIL/SKIPCDEG/otherwise, if (calculations
378 %should end)/(the current degree should be skipped)/(calculations
379 %should continue as usual).
380 %FixNcDeg and thus CUSTNEWCDEGFIX get an integer input, 1/2/3 for
381 %"At the new current degree there are (input polynomials)/(critical
382 %pairs)/both".
383
384 It is possible to get the 'true' action of the bergman
385 procedure to be performed, by the 'PROG variable initiation trick'.
386 Whenever a variable is declared as a PROG variable, it is locally
387 bound to NIL. Thus e.g. the following bit of Standard Lisp code
388 \begin{verbatim}
389 (OFF RAISE)
390 (DE CUSTENDDEGREECRITPAIRFIND ()
391 (PROG (!*CUSTSTRATEGY)
392 <action 1>
393 (DEnSPairs)
394 <action 2> ))
395 (ON RAISE)
396 \end{verbatim}
397
398 defines CUSTENDDEGREECRITPAIRFIND in such a way, that when
399 CUSTSTRATEGY is ON a call to DEnSPairs yields the following effect:
400 First $<$action 1$>$ is taken, then DEnSPairs is called recursively but
401 with CUSTSTRATEGY OFF (if $<$action 1$>$ didn't turn it ON), performing
402 its ordinary action, and last $<$action 2$>$ is taken.
403
404
405 \index{degreeprintoutput} \item [DEGREEPRINTOUTPUT]
406
407 Only influential when the SAWS algorithm is used. Then makes the final
408 reduced Gr\"{o}bner basis be exhibited degree by degree, with separating
409 degree annotations, as in `ordinary' degree-wise output. (C.f. SAVEDEGREE.)
410
411 \index{dynamiclogtables} \item [DYNAMICLOGTABLES]
412
413 When MODLOGARITHMS is on and (SETMODULUS <prime>) is executed with an
414 odd integer as <prime>, and a saved logarithms table file is not found,
415 then logarithm tables are constructed. If DYNAMICLOGTABLES is OFF, this
416 is done in a subshell, writing a file which is read into the bergman
417 session but also saved for future use. If it is ON, then the tables
418 should be constructed directly (and ephemarily).
419 (THE DYNAMIC LOGTABLES CREATION IS NOT YET IMPLEMENTED.)
420
421 \index{homogenised} \item [HOMOGENISED]
422
423 Turned ON/OFF by the (de-)homogenising routines.
424 Touch it only e.g. to fool the system that the data is or is not
425 homogenised, in order to perform an extra (de-)homogenisation.
426
427 \index{immediatecrit} \item [IMMEDIATECRIT]
428
429 Turned ON/OFF by NONCOMMIFY/COMMIFY.
430 Try to eliminate critical pairs (employing various criteria) as soon
431 as a degree is finished, instead of waiting until the degree of the
432 pair is reached. Should NOT be turned ON in the commutative case!
433
434 \index{immediatefullreduction} \item [IMMEDIATEFULLREDUCTION]
435
436 Default: ON.
437 Immediate full reduction of `old' Gr\"{o}bner basis elements by means of
438 newfound ones. (This is at variance with many other systems, where a
439 preliminary Gr\"{o}bner basis element will not be changed once it is
440 entered.)
441
442 \index{immediaterecdefine} \item [IMMEDIATERECDEFINE]
443
444 Intended meaning: When calculating PBseries, define the recursive
445 monomial-bound sub-series while these monomials anyhow are considered
446 from the critical pair point of view. This option is not fully
447 implemented, however, so the flag should NOT be turned ON.
448
449 \index{modlogarithms} \item [MODLOGARITHMS]
450
451 Use `logarithm table methods' in (sufficiently small) positive
452 characteristics. Provided the appropriate table files exist or
453 a mechanism for automatically producing them is enabled, this
454 flag is strongly recommended to be turned ON.
455
456 \index{monoidal} \item [MONOIDAL]
457
458 Used in some experimental variant to signify that we actually
459 work within the monoid of monomials; i.e., that all relations are
460 pure binomial. If this work is ever included into the general
461 bergman framework, probably it will be in the form of mode
462 changing procedures rather than by flag-setting, though.
463
464 \index{nobignum} \item [NOBIGNUM]
465
466 Inhibit automatic loading of the bignum package. If you "know" that
467 no bignums will be needed in your particular run (although it e. g.
468 is in characteristic zero or the Hilbert series is calculated), you
469 may turn it ON BEFORE initialisations or mode-changings have invoked
470 it.
471
472 (Note that in your installation the Bignum package may already be
473 loaded from start, in which case the flag should be on by default.
474 This is probable, if you run bergman under Reduce.)
475
476 \index{obsoletenamesinform} \item [OBSOLETENAMESINFORM]
477
478 Default: ON.
479 Some procedures have chan\-ged names from older bergman versions. For
480 backward compatibility, some older names are retained as synonyms
481 in this version (although they may be thrown away later). (They are
482 not documented in this manual or elsewhere.) If OBSOLETENAMESINFORM
483 is ON, then using one of them causes a warning to be printed,
484 together with an information on the new name, before executing it.
485
486 \index{pbseries} \item [PBSERIES]
487
488 Turned ON/OFF by NONCOMMIFY/COMMIFY.
489 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
490 method ONLY WORKING IN THE NON-COMMUTATIVE CASE)! Its effects are
491 partially superceeded by turning CUSTSHOW ON - take care that your
492 DEGREEENDDISPLAY calls e. g. TDEGREECALCULATEPBSERIES in this case. The
493 most important use of this is to get the Hilbert series of the ring.
494
495 \index{posleadcoeffs} \item [POSLEADCOEFFS]
496
497 Default: ON.
498 In the characteristic 0 case, make sure that the final reduced Gr\"{o}bner
499 basis element leading coefficients are positive. (Turning it OFF saves
500 very little calculation, but makes the result compatible with results
501 from older versions of bergman.)
502
503 \index{reductivity} \item [REDUCTIVITY]
504
505 Turned ON when the SAWS module is loaded.
506 Inhibits the `cannibalising' garbage collection of lower degree
507 monomials, thus making it possible to use the Gr\"{o}bner basis for
508 calculating normal forms. It may be turned ON for this purpose, or
509 because the `cannibalism' may have unwanted side effects in the
510 context. (This still MIGHT happen with some weird non-commutative
511 inputs; I am not sure. It DEFINITELY could happen if you run the SAWS
512 algorithm with REDUCTIVITY OFF; DON'T do it!)
513
514 \index{saveaccidentalreducibilityinfo} \item [SAVEACCIDENTALREDUCIBILITYINFO]
515
516 Only active within the SAWS mode. If ON, save and re-use information on
517 whether or not a leading monomial is divisible by another Gbe leading
518 monomial (disregarding substance).
519
520 \index{savedegree} \item [SAVEDEGREE]
521
522 Turned ON/OFF by\\
523 DEGREEOUTPREPARE/ENDDEGREEOUTPUT.
524 Make GROEBNERKERNEL exhibit output degree by degree, by means of the
525 inbuilt procedure DEGREEOUTPUT. (Is overruled by CUSTSHOW.)
526 In general, the final result is output. However, if the SAWS algorithm
527 is active, it is the preliminary (staggered linear) basis which is
528 output. In this case, the final reduced Gr\"{o}bner basis is NOT calculated
529 degree-wise, and so no speed is gained by exhibiting output degree-wise.
530 If you anyhow wish such output (e. g., for compatibility reasons), you
531 may turn ON DEGREEPRINTOUTPUT.
532
533 %(SAVEINHOMOGMONLIST ?????)
534
535 \index{saverecvaluse} \item [SAVERECVALUES]
536
537 Default: ON.
538 In the Poicar\'e-Betti series algorithm, numerous interdepending integer
539 series are defined by linear recursion formulae. When the flag is ON,
540 the calculated values at each degree are saved. This saves (considerable)
541 time, but sometimes may use considerable space.
542
543 \index{trbr} \item [TRBR]
544
545 Only used in debugging.
546 If ON, calling IfTRBRbreak causes a break.)
547
548 \end{description}
549
550 \subsection{User available counters}
551
552 In most cases they should be initialised to 0 by SETQ or Reduce assignment.
553
554 \begin{description}
555 \index{noofnilreductions} \item [NOOFNILREDUCTIONS]
556
557 Counts the total number of times the normal form procedure ("ReducePol")
558 is called with an argument representing the zero polynomial.
559 (Ordinarily, this happens precisely whenever a new-formed S-polynomial
560 is zero before reduction.)
561
562 \index{noofreprioritations} \item [NOOFREPRIORITATIONS]
563
564 In the SAWS algorithm, counts the number of times `all' the prioritation
565 values must be changed, in order to enable new (integer!) values between
566 two old ones.
567
568 \index{noofspolcalcs} \item [NOOFSPOLCALCS]
569
570 Counts the number of S-polynomials actually formed. Together with a
571 counting of the final basis (except the input), this gives a good measure
572 of the efficiency of the critical pair elimination criteria.
573
574 \index{noofstagconecrit} \item [NOOFSTAGCONECRIT]
575
576 Counts the number of applications of a SAWS algorithm elimination
577 criterion. On this particular point, I am not sure whether this covers
578 up some implementation bug or not.
579
580 \end{description}
581
582
583 \subsection{User readable variables}
584
585 These variables should NOT be reset by the user.
586
587 The commutative/non-commutative series calculation results are available
588 as the values of (HILBERTNUMERATOR and HILBERTDENOMINATOR) or
589 (DOUBLEPBSERIES, HILBERTSERIES,\\
590 INVHILBERTSERIES, and SIMPLEPBSERIES),
591 respectively, in a printable LISP format.
592
593
594
595 \subsection{User defined variables}
596
597 To be set by SETQ (or Reduce assignment)):
598
599 \begin{description}
600
601 \index{algoutmode} \item [ALGOUTMODE]
602
603 Default: NIL
604 May be set to LISP, ALG, MACAULAY, or some user defined algebraic
605 output mode. (See ADDALGOUTMODE for the latter.). Governs the output
606 polynomial print-out form. (NIL has the same effect as LISP.)
607 For ALG form (Maple- or Reduce-like) or MACAULAY-like output to be
608 working, some knowledge of the intended variable names are necessary.
609 This is normally automatically provided by vars, used in ALGFORMINPUT.
610
611 Also see the input/output format section above.
612
613 \index{embdim} \item [EMBDIM]
614
615 Default: NIL. Is set automatically by some initialisers.
616 The (intended) number of variables. (Commutatively, the "embedding
617 dimension".) If you make lisp-form input in the non-commutative
618 case, and want to know the Hilbert series, the EMBDIM should be
619 provided. (If you enumerate variables with the ALGFORMINPUT vars
620 command, the embedding dimension is deduced automatically.)
621
622 \index{hdegvariable} \item [HDEGVARIABLE]
623
624 Default: !t.
625 The Poincar\'{e}-Betti series print out homological degree variable
626 name. (The exclamation mark guarantees a precise printing, with
627 no case change.)
628
629 \index{initprioritystart} \item [INITPRIORITYSTART]
630
631 Default: 0.
632 \index{initprioriysteplength} \item [INITPRIORITYSTEPLENGTH]
633
634 Default: 32.
635 \index{reprioritysteplength} \item [REPRIORITYSTEPLENGTH]
636
637 Default: 16.
638
639 In the SAWS algorithm, the priorities are represented by integers. At the
640 beginning, the `lowest input polynomial' is assigned the priority
641 INITPRIORITYSTART, the next one INITPRIORITYSTART + INITPRIORITYSTEPLENGTH,
642 the next one INITPRIORITYSTART + 2*INITPRIORITYSTEPLENGTH, et cetera. New
643 elements get priorities `between' the old priorities. If this is not
644 possible, i. e., if a new priority should be chosen between two succeeding
645 integers, all but the first priority are changed, so that they get evenly
646 `spaced' with the `distance' REPRIORITYSTEPLENGTH. (The number of times
647 this happens is counted by NOOFREPRIORITATIONS.)
648 The variables should be assigned (''small'') integer values, and (obviously)
649 you must choose INITPRIORITYSTEPLENGTH $>=1$ and REPRIORITYSTEPLENGTH $>=2$.
650
651 \index{maxdeg} \item [MAXDEG]
652
653 Default: NIL. If set (in which case it should be a positive integer), it provides an
654 upper bound for critical pair forming et cetera. Thus it makes the Gr\"{o}bner
655 basis or SAWS algorithm terminate not later than at MAXDEG. There is no
656 (direct) way to check whether or not the termination was due to the
657 MAXDEG, or would have occurred anyhow.
658
659 \index{tdegvariable} \item [TDEGVARIABLE]
660
661 Default: !z.
662 The Hilbert and Poincar\'{e}-Betti series print out total degree variable
663 name. (The exclamation mark guarantees a precise printing, with
664 no case change.)
665
666 \end{description}
667
668 %\subsection{Experimental functions handling inhomogeneous input/ouput}
669
670
671 %The bergman standard/Gr\"{o}bner basis calculation procedures always assume
672 %their input to be homogeneous. In the non-commutative case, this
673 %prerequisite cannot be eliminated completely, since finding normal forms
674 %in a general inhomogeneous algebra is an insoluble problem. In the
675 %commutative case, on the other hand, we may aaterfoera the inhomogeneous
676 %case on the homogeneous, by homogenising the input, ...
677
678 \section{The commutative Hilbert series procedures} \label{comHS}
679
680 This section contains information for the user about the
681 commutative Hilbert series procedures. Since series handling is
682 in a transitory phase, all this is not yet very fixed, whence
683 most of it is NOT contained in the manual.
684
685 There are two main uses for the \index{Hilbert series} Hilbert series facilities: Stand alone
686 and within the Hilbert series \index{interrupt strategy} interrupt
687 strategy minor mode. In the
688 former case, you may get the Hilbert series of the residue class
689 ring modulo a calculated Groebner basis or some user input
690 monomial ideal, as a rational expression$ p(t)/(1-t) \verb-^-q$, or with
691 the power series coefficient for some specified t degree(s). In
692 the latter, you should communicate a Hilbert series limitation to
693 the programme; it will automatically invoke the appropriate Hilbert
694 series calculations.
695
696 In either case, you may wish to inspect resulting series in situ
697 (especially as there are few prepared good user interface procedures
698 for this). You then should note that the global variables
699 HILBERTNUMERATOR and HILBERTDENOMINATOR represent a calculated
700 $$ p(t)/(1-t)\verb-^-q = (a_{n}t\verb-^-n + a_{n-1}t \verb-^-(n-1) +
701 \,.\,.\,. + a_{0})/(1-t) \verb-^-q $$
702 by (the lisp items) $ ((n\ .\ a_{n}) (n-1\ .\ a_{n-1})
703 \,.+,.\,.
704 (0\ .\ a_{0}))$ and $ q$,
705 respectively.
706
707
708 A principal use of Hilbert series calculation is with the Hilbert
709 series interrupt strategy (which is based on ideas by Ralf Froeberg). You then
710 should provide a Hilbert series limitation. The limitation should be
711 a representation of a function f from the set N = \{0,1,2,...\} to the
712 union of N and the set \{NIL, T, SKIPCDEG\} of lisp constants. The
713 default limitation function has the constant value NIL for each
714 input. You may change the function with the SETHSERIES... procedures,
715 and you may inspect the current limitation function or part thereof
716 with the GETHSERIES... procedures, as explained below.
717
718 When bergman is in the Hilbert series interrupt strategy minor mode
719 and is about to start considering a new current degree d within the
720 GROEBNERKERNEL execution, it extracts the limitation function value
721 $f(d)$ and proceeds as follows:
722 \begin{itemize}
723 \item If $ f(d)$ is NIL, then GROEBNERKERNEL follows "procedures as
724 usual" for the current degree d (with no non-ordinary
725 constraints on the calculations).
726 \item If $ f(d)$ is T, then GROEBNERKERNEL is exited without any further
727 calculations. (Thus we get an effect similar to a MAXDEG
728 setting, but probable with some unnecessary critical pair
729 calculation performed on degree d or higher.)
730 \item If $f(d)$ is SKIPCDEG, then the current degree d is "skipped":
731 critical pairs and input polynomials of degree d are removed,
732 as if they (or the corresponding S--polynomials) were found to
733 reduce to zero. (A new test is made for the next occurring
734 degree.)
735 \item If $f(d)$ is a non-negative integer, then calculation at degree
736 d continues only until either all input polynomials and
737 critical pairs of degree d are processed, or the associated
738 quotient ring Hilbert series value for d, i.e., the vector
739 space dimension of the degree d component of the residue class
740 ring of the current polynomial ring modulo the ideal generated
741 by the leading monomials of all (partial) groebner basis
742 elements found so far, no longer exceeds $f(d)$; the the
743 remaining input polynomials and critical pairs of degree d
744 (if any) are skipped (like in the SKIPCDEG case).
745 \end{itemize}
746
747 An $f(d)$ value either may be specified explicitly, or be calculated
748 by a default expression. The latter may be a constant (an integer
749 or one of NIL, T, and SKIPCDEG) or is considered as the definition
750 part of a lisp EXPR with the single argument HSDEG. An explicitly
751 specified value takes precedence over a default one. E.g., the
752 default expression
753
754 \begin{verbatim}
755 (COND ((GREATERP HSDEG 10) T)
756 ((LESSP HSDEG 3) SKIPCDEG)
757 (T (PLUS HSDEG 2)))
758 \end{verbatim}
759
760 will make $ f(0) = f(1) = f(2) = SKIPCDEG,$
761 $ f(3) = 5, \,.\,.\,. , f(10) = 12,$
762 and $ f(d) = T$ for all other legitimate d values, except for those $d$
763 for which explicit values are given.
764
765
766 Available high level procedures:
767
768 \begin{description}
769
770 \index{calcpolringseries} \item [(CALCPOLRINGHSERIES varno) : EXPR].
771
772 Initialises \index{hilbertnumerator} HILBERTNUMERATOR and
773 \index{hilbertdenominator} HILBERTDENOMINATOR values to
774 those for the present polynomial rings. Right now, varno isn't
775 used; instead, the numbers of variables is extracted by means
776 of GETVARNO.
777
778 \index{calcrathilbertseries} \item [(CALCRATHILBERTSERIES) : EXPR].
779
780 Uses the calculated (full or partial) Groebner basis in order to
781 calculate the Hilbert series for the residue class ring modulo
782 the ideal generated by the leading monomials of the basis elements.
783 Errs if no (partial) Gr\"{o}bner basis is stored in GBasis.
784
785 \index{gbasis2hseriesmonid} \item [(GBASIS2HSERIESMONID) : EXPR].
786
787 Creates a special kind of lisp form representation of the
788 monomial ideal generated by the leading monomials of the
789 calculated (full or partial) Gr\"{o}bner basis. The format is a
790 (printable) list of flagged monomials (FMon's), as described in
791 the introduction to the source file hseries.sl.
792
793 \index{gethseriesminima} \item [(GETHSERIESMINIMA) : EXPR].
794
795 Extracts the full information about the pre-stored Hilbert
796 series limitation, in a printable format acceptable as input to
797 SETHSERIESMINIMA.
798
799 \index{gethseriesminimum} \item [(GETHSERIESMINIMUM tdeg) : EXPR].
800
801 Extracts the information about the pre--stored Hilbert series
802 limitation for degree tdeg, as an integer or as one of the
803 constants NIL, T, and \index{skipdeg} SKIPCDEG. (tdeg must be a non-negative
804 integer; else, rather weird errors may occur.)
805
806 \index{sethseriesminima} \item [(SETHSERIESMINIMA \ldots ) : FEXPR].
807
808 Specify the Hilbert series limitations, as a sequence of
809 dotted pairs or as a list of limitation constants, in either
810 case optionally accompanied by a DEFAULT setting. In the
811 dotted pair variant, each dotted pair antecedent ("CAR part")
812 should be a non-negative integer or the identifier DEFAULT;
813 the postcedent ("CDR part") when the CAR is an integer d
814 should be the limitation for d (i.e., a non-negative integer
815 or one of the constants NIL, T, and SKIPCDEG), and when
816 the CAR is DEFAULT it should be of the
817 SETHSERIESMINIMUMDEFAULT input form. In the sequence case,
818 the items are considered as CDR parts corresponding to
819 CAR parts 0, 1, 2, \ldots (in thgis order); everything after
820 DEFAULT is considered as the DEFAULT CDR part (whether or
821 not it is on list form). In either case, the default value
822 or procedure is changed only if a new DEFAULT is specified.
823
824 Example:
825 \begin{verbatim}
826 (SETHSERIESMINIMA T SKIPCDEG NIL 6 7 8 9 DEFAULT 8)
827
828 and
829
830 (SETHSERIESMINIMA (0 . T) (1 . SKIPCDEG) (2) (3 . 6)
831 (4 . 7) (6 . 9) (DEFAULT . 8))
832 \end{verbatim}
833
834 have the same effects. (Note that in lisp, (2) and (2\ .\ NIL)
835 are considered as identical.)
836
837 \index{sethseriesminimumdefault} \item [(SETHSERIESMINIMUMDEFAULT ...) : FEXPR].
838
839 Specify the Hilbert series limitation default value or
840 procedure. (Explicitly specified values for specified
841 degrees are not changed.)
842
843
844 \index{tdegreehseriesout} \item [(TDEGREEHSERIESOUT PositiveInteger): EXPR].
845
846 Returns the Hilbert function (i. e. Hilbert series coefficient)
847 for PositiveInteger (provided adequate series calculation up to
848 that degree is done previously).
849
850
851 \end{description}
852
853 % -------------------------------------------------------------
854 %To document in protocol.txt: HSeriesCommify, ... .
855
856 %Recently defined/employed only in the non-commutative mode:
857 % DEGREEPBSERIESDISPLAY, PBINIT, TDEGREECALCULATEPBSERIES;
858 % !*IMMEDIATERECDEFINE, !*PBSERIES.
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933