KBMAG Version 1.4.4 8. August 1996. KBMAG stands for Knuth-Bendix on Monoids and Automatic Groups. The package has three principal applications: (i) A standalone Knuth-Bendix program for finitely presented monoids; (ii) A package for calculating the automatic structure of a short-lex automatic group, which supercedes the existing Warwick "Automata" package; (iii) A few programs for manipulating finite state automata. All programs are in standard 'C', but there is one Bourne shell script (which is not completely essential for using the package). It is designed to run on any Unix sytem. CONTENTS -------- This distribution contains a single directory, kbmag, which contains the following files: README (the file you are now reading) lib (directory) .c files for library src (directory) .c source files for executables bin (directory) for executables - empty on distribution doc (directory) documentation Makefile general makefile to make all executables kb_data (directory) sample data files for Knuith-Bendix program ag_data (directory) sample data files for automatic groups program fsa_data (directory) sample data files for general fsa programs gap some GAP library files You will probably want to put the bin directory into your path. MAKING THE PACKAGE ------------------ By default, simply type "make" from within the kbmag directory If you are using bsd UNIX, rather than System V, you should however type "make SYSTEM=BSD" (this affects only timing information in the program kbprog). The default C-compiler is gcc; to use cc, type "make CC=cc". The default compiler option is -O; to use -g, for example (if you wish to do your own debugging), then type "make COPTS=-g". To make things in two steps instead of one, first go into the lib directory and type "make" (+ any options) and then go into the src directory and type "make". (This is what the general "make" does anyway.) To recompile individual programs later, for example "kbprog", go into the src directory and type "make ../bin/kbprog". (To do this, the file "fsalib.a" must be present in the lib directory - this may have been removed, if you have done "make clean" in the meantime, in which case you will need to go back into lib and type "make" again.) If successful, you can remove .o and .a files by typing "make clean". You can remove everything created by make (and a few other things besides, such as .dvi files) by typing "make distclean". To do a very quick test, type "make test". You should get about 28 lines of output, with nothing which looks like an error message, ending with: #The language accepted has size 60. If this succeeds, then things are probably working properly (although it is not a very thorough test). This package has not yet been compiled on a wide variety of machines, so you may encounter problems. If so, please let me know (and preferably sort the problem out yourself first.) DOCUMENTATION ------------- This is in the directory doc. The main documentation is in the latex file manual.tex. You need to run "latex manual" of course. The plain-text file fsa_format is a not completely precise and not completely up-to-date description of the file format for finite state automata that is used in the programs, and was agreed by the international GASP committee. You may be better off not bothering to read this, and just copying and editing the example files in the data directories. All of the files conform to GAP format, and so can be read from within the GAP system. (See below.) SAMPLE DATA FILES ----------------- These are in the directories kb_data, ag_data and fsa_data. They correspond roughly to the three principal uses of KBMAG, as a standalone Knuth-Bendix program, an automatic groups package, and a collection of programs for manipulating finite state automata. The files in fsa_data are simply the examples in the file doc/fsa_format. GAP FILES --------- In the directory gap, there are some GAP library files, which contain functions that can be used to manipulate finite state automata and rewriting systems that are read into GAP from files produced by the programs in the package. See the manual for more information. They do work after a fashion, but eventually they will hopefully form part of a proper interface with the GAP system. Installing KBMAG as GAP share library package --------------------------------------------- If you want to install KBMAG as a share library package for GAP, go into the directory where GAP resides on your system and from there into the directory pkg. Unpack the tar file kbmag.tar in this directory: tar xzf kbmag.tar.Z After this has finished, perform the commands cd kbmag make -f Makefile.gap In order to update the GAP manual follow these instructions: cp gapdoc/kbmag.tex ../../doc cp gapdoc/kbmag.bib ../../doc cd ../../doc Now edit the file manual.tex. There is a list of lines of the form \Include{...} towards the end of the file. Add the line \Include{kbmag} and, a couple of lines further down, add kbmag to the arguments of the command \bibliography: \bibliography{manual,kbmag} All that is left to do now is to run LaTeX and bibtex: latex manual bibtex manual latex manual latex manual When this is finished you should be able to use kbmag from within GAP via the GAP function RequirePackage(): gap> RequirePackage("kbmag"); Typing gap> ?KB gives you an introduction to the package. Using `?>' one can step through the subsequent manual entries. Note that this way of installing KBMAG creates a subdirectory in the directory kbmag/bin with the name of the computer you are working on. In this way you can install KBMAG as a share library package on different computer architectures that share the same GAP directory. If you have several computers with the same architecture sharing the same GAP directory it is sufficient to install GAP on one of them and create symbolic links in the directory bin for each of the others. Please report all problems, bugs, etc. to me. (Derek Holt, dfh@maths.warwick.ac.uk)