source: CGBLisp/README@ 1

#       $Id: README,v 1.7 1997/11/30 19:33:01 marek Exp $       

From: rychlik@math.arizona.edu
----------------------------------------------------------------
I. GENERAL REMARKS
----------------------------------------------------------------
Dear User:

        This is an experimental Comprehensive Grobner Basis package.
In order to use the package you must be familiar with the lisp
syntax. The command language used is that of lisp. However,
in order to facilitate input and output, some limited facilities
for the customary infix notation are included. The documentation
of the Lisp code can be found in sets of automatically
generated manuals, in the following sub-directories:

        ./latex-doc     - a LaTeX documentation
        ./doc           - pure text documentation

The package has been tested under the following environments:
----------------------------------------------------------------
1. SUN SPARC/UNIX, AKCL (Austing Kyoto Common Lisp version 615 )
2. Linux 1.2.13 + gcl 2.0
3. Linux 2.0 + Allegro 4.3 
----------------------------------------------------------------
The current development environment is

        Linux 2.0 + Allegro Common Lisp v. 4.3

If incompatibilities arise with other environments as a result
of new code being added, please let me know. In general, only
then I will try to fix the compatibility issues.
----------------------------------------------------------------
II. THE MATHEMATICAL BACKGROUND
----------------------------------------------------------------
For a definition of a Comprehensive Grobner Basis, see

        Volker Weispfenning, Comprehensive Groebner Bases,
        Journal of Symbolic Computation
        volume 14, 1992,
        Pages 1-29

That paper defines the basic notion of a Grobner System (the object that
is calculated by the current package). In the paper you will also find 
a description of a software system which calculates Comprehensive Grobner
Bases. Our package initially grew out of frustration with that package,
however, we feel that in the process of writing thin new package we made
a number of substantial improvements to the original mathematical idea
of the Weispfenning's paper.

William Dunn has written a dissertation which describes the ideas behind
the current package. It also contains an elaboration of the ideas of
Weispfenning. To obtain a copy, contact the author at
................................................................
        dunn@math.arizona.edu
................................................................

----------------------------------------------------------------
II. HOW TO USE THE PACKAGE?
----------------------------------------------------------------

The basic operation of the package consists in typing commands at the
Lisp prompt:
Example: The basic example of the theory is the following
----------------------------------------------------------------
>(STRING-GROBNER-SYSTEM "[x+y,x+u*y]" '(X Y) '(U))
------------------- CASE 1 -------------------
Condition:
  Green list: [  ]
  Red list: [ U - 1 ]
 Basis: [ (U - 1) * X, ( - U + 1) * Y ]
------------------- CASE 2 -------------------
Condition:
  Green list: [ U - 1 ]
  Red list: [  ]
 Basis: [ (1) * X + (1) * Y ]
----------------------------------------------------------------
This example calculates the Grobner System corresponding to the
ideal [x+y,x+u*y] in k[u][x,y], where u is a parameter. The output
consists of a number of CASES. The cases correspond to distinct elements
of the partition of the parameter space. The "Green List" is a list of
polynomial in parameters that are 0 on a given chunk of the parameter space,
while "Red List" is a list of polynomials which are different from 0.
Thus, CASE 1 corresponds to those parameters for which u is not 1,
while CASE 2 corresponds to u=1. The "Basis" part lists a plain Grobner Basis
of the ideal in k[x,y] obtained by specializing the parameter u in such
a way that the restriction imposed by the corresponding Green List and Red
List are satisfied.

The ideal specification is given as string "[x+y,x+u*y]". As a rule, when
we have a command in our package which starts with a prefix string-... then
one or more of the arguments are going to have a form of a string. This string
is immediately parsed from infix notation to internal form and then typically
a corresponding command without the prefix string-... is called to perform the
calculation on internal representation. Most of the string commands provide
a keyword argument :suppress-value which is by default set to T, but if it
is set to NIL, the corresponding internal form of the answer is returned.

The ./tests subdirectory of the distribution directory contains
several files which can be used as examples of problem formulation
in the form acceptable to cgb-lisp

For more examples, see the files colored-poly-tests.lisp and
colored-poly-tests.output. These files are used by me to test the 
operation of the primary commands of the package.
----------------------------------------------------------------
IV. INSTALLATION
----------------------------------------------------------------
First make an empty directory of your choice, say /usr/local/CGBlisp.
The following instructions require a modification if you install
in a different directory.

        0. Copy the tared and compressed source (cgb.tar.gz) into /usr/local/CGBlisp
        Unpack the files:

                % zcat cgb.tar.gz | tar xvf -
        1. Change working directory to /usr/local/CGBlisp/src.
        
        2. Start your Common Lisp in the src directory and do
                > (load "defsystem.lisp")
                > (in-package :make-cgb)
        Then do
                MAKE-CGB> (cgb-load)
        to get an interpreted version of the package (slow!) or
        make a compiled version with
                MAKE-CGB> (cgb-compile-and-load)
        If you want, you may create a custom binary by dumping
        core and making it executable, in a fashion depending on your
        lisp system. For instance, kcl/gcl uses
                MAKE-CGB> (cgb-save "fileOfYourChoice")
        and Allegro Common Lisp uses
                MAKE-CGB> (dumplisp :name "fileofyourchoice")
        If you do not create the custom binary, each time you start
        your Lisp, you will need to repeat the first two steps, i.e.

                > (load "defsystem.lisp")
                > (make-cgb::cgb-load)
                > (in-package :cgb-lisp)
        to get either an interpreted or compiled version of the package.

NOTE: Some lisps use .lisp as extension of Lisp source code and others
.lsp, and perhaps others.  You will need to rename and edit all files
if the extension .lisp is not accepted.

Yet another compatibility issue may arise from the fact that this
package was developed before the ANSI standard was finalized. Thus,
compatibility issues arise, for instance with the current version of
Allegro Common Lisp because the package uses the "Cltl1" conventions
(the book of Guy Steele which was a de facto Common Lisp definition in
the 80's). The incompatibilities for Allegro were resolved in
defsystem.lisp by setting some Allegro switches which turn on "Cltl1"
conventions for package loading and compilation.  You may need to
adapt the same strategy with other lisps, or rewrite the top of each
file to observe the new ANSI standard.

----------------------------------------------------------------
V. FINAL REMARKS
----------------------------------------------------------------
Please send your comments to me, and I will try to improve your package
according to your suggestions.

Enjoy,

--Marek Rychlik (rychlik@math.arizona.edu)