source: branches/f4grobner/README@ 4516

Dear User:

This directory contains files which provide Grobner basis support for
the free computer algebra system Maxima. The older versions of the
package are distributed with Maxima in the subfolder of the Maxima
installation tree, like:

maxima/5.xx.x/share/contrib/Grobner

This version is meant to be a backward-compatible replacement for this
package. It features an implementation of the Faugere's F4 algorithm.

== INSTALLATION INSTRUCTIONS ==

In order to use the package, 
 1. Copy the files in this directory to your favorite location;
   or better, checkout the contents of this repository with SVN.
 2. Edit the file "grobner.mac" to modify the location of the Lisp
   files, to reflect your choice made in previous step.
 3. Start your Maxima and load the file "grobner.mac"
 4. Optionally, compile the Lisp files, so that the next file
    you load "grobner.mac", the compiled (.fasl) versions of
    the files will be loaded. The compilation instructions
    vary slightly depending on Lisp version.

This version has been verified to work under this Maxima version:

----------------------------------------------------------------
Maxima 5.34.1 http://maxima.sourceforge.net
using Lisp SBCL 1.2.4-1.fc21
----------------------------------------------------------------

It should also be portable across other ANSI Common Lisp implementations.

The file grobner.demo is a Macsyma-style demo file for most of the operations
provided by the package. In order to run it, go to the Maxima level and
type:

demo("grobner.demo");

or

batch("grobner.demo");

and watch the demonstration.

Maxima documentation for this package has not been written yet, but
there is a sizable amount of documentation in the LISP source.

== COMPILATION INSTRUCTIONS FOR SBCL ==

=== When using ASDF (preferred way):
----------------------------------------------------------------
* (require :asdf)
* (load "ngrobner.asd")
* (asdf:load-system :ngrobner)
----------------------------------------------------------------
The compiled files (extension .fasl for SBCL) will be typically
placed in a standard location determined by the ASDF configuration. On my system it is:
----------------------------------------------------------------
/home/marek/.cache/common-lisp/sbcl-1.2.4-1.fc21-linux-x64/home/marek/Repos/MaximaGrobner/branches/f4grobner/
----------------------------------------------------------------
given that the SVN repository was copied to /home/marek/Repos/MaximaGrobner.

=== When not using ASDF (for whatever reason):

Step 1. Start SBCL in the directory which is a copy of this directory.
Step 2. Execute Lisp commands:
----------------------------------------------------------------
* (load "compile-me.lisp")
----------------------------------------------------------------

The resulting compiled files (extension .fasl for SBCL) will end up in
the same folder as the Lisp files. Then can be moved any directory
where Maxima can find them, as determined by the variable
file_search_lisp. This variable needs to be modified in "grobner.mac"
accordingly. After that, every time you load "grobner.mac" the
compiled version will be used.

== 5AM TESTS ==

The system is set up for using the FiveAM unit testing framework.
One performs the tests by loading a single file:
----------------------------------------------------------------
* (load "5am-tests")
----------------------------------------------------------------
Note that this requires ASDF and QuickLisp being installed.

NOTE: The coverage is still minimal. The number of tests
will increase over time. 

== TESTING WITH ORACLE APPROACH ==

The alternative mechanism is enabled
by doing this *BEFORE* loading/compiling NGROBNER:
----------------------------------------------------------------
* (push :grobner-check *features*)
----------------------------------------------------------------
This will enable verification of every Grobner basis computed,
by performing Buchberger criterion, after the basis is computed.
This is an "oracle" testing, given that the portion of the code
required for verification of Groebner bases is correct. A significant
test involves loading the demonstration code, like:
----------------------------------------------------------------
(%i1) batch("grobner.demo");
----------------------------------------------------------------
The failure will result in a spectacular error message.
NOTE: For this to work (push :grobner-check *features*)
needed to be executed before loading/compiling Lisp code.

== ADDITIONAL COMMENTS ==

The files were derived the sources of a package CGBlisp, version 2,
also authored by me, which will eventually be released at my Web site
(see below).  An older version of CGBlisp is available at the Web
site.

== VIEWING DOCUMENTATION ==

Various components of the system have significant documentation
attached.  This can be browsed with tools such as DOCBROWSER or
MANIFEST.  Both start a web server on a local port. A quick tutorial
on these tools: if you have Quicklisp, you can use this one-liner to
start MANIFEST:

* (ql:quickload :manifest) (manifest:START)

The port of MANIFEST server is printed.

Or this one-liner to start DOCBROWSER on port 8084:

* (ql:quickload :docbrowser) (docbrowser:start-docserver 8084)

Enjoy.
--Marek Rychlik

5-24-2002
Revised: 1-25-2009
Revised: 1-25-2015

E-mail: rychlik@u.arizona.edu
URL: http://marekrychlik.com