source: branches/f4grobner/README@ 3199

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:install-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