%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % This file is part of the C Meat-Axe. % % Written by Michael Ringe % % (C) Copyright 1992: Lehrstuhl D fuer Mathematik % % RWTH Aachen % % Aachen, Germany % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} %--------------------- The {\MeatAxe} is a set of programs for working with matrices over finite fields. Its primary purpose is the calculation of modular character tables, although it can be used for other purposes, such as investigating subgroup structure, module structure etc.\ Indeed, there is a set of programs (see section \ref{sec:lattice}) to compute automatically the submodule lattice of a given module. There is one common module (ZZZ) which does all the finite field calculations. ZZZ works with single elements and rows of elements, does the input and output, handles the memory allocation and a few miscellaneous simple operations besides. This makes it possible to code the most time-consuming parts in assembler and still have the algorithms presented in C. Another advantage is, that all the system dependent stuff (file i/o, for example) is concentrated in one place. Each of the programs is self-contained, except that it calls the ZZZ subroutines, reading its input from files, and writing its output to files. To make the {\MeatAxe} usable, therefore, it is necessary to write operating system commands to run the various programs. This documentation is primarily for the programs, and further documentation is necessary for the various implementations in differing operating environments. The primitive objects are of two types: matrices and permutations. Permutation objects can be handled, but not as smoothly as you might expect. However, the matrix part is more or less complete. For example, it is hoped that programs such as split (ZSP) and multiply (ZMU) will be able to work with mixed types, but at present ZSP is restricted to matrices only, and ZMU can multiply matrix * permutation, but not vice versa. \subsection*{Remarks on the C implementation} %-------------------------------------------- Most of the programs (including their documentation) in this package are based on the FORTRAN code written by Richard~A.~Parker. The translation from FORTRAN to C was done in 1989 and since then both versions have developed independently. The user interface of the C programs has been changed significantly (e.g., command line arguments were introduced) and some new programs have been added which are not available in the FORTRAN {\MeatAxe}. However, the data formats are still compatible, so it is possible to share even binary data files between FORTRAN and C programs. The objective of this suite of programs is research, so that where simplicity and power are in contention, power is selected. Nevertheless, I have tried to make the programs as straightforward and user-friendly as possible. Moreover, the source code is available, so the user can change any parts he is annoyed with. There are dangers in changing the source, though, in that future versions may then need to have the same changes made to them. I hope that the file formats and ZZZ interface will remain the same, so that the user is welcome to write his own programs to do the special parts he needs. Of course, I would appreciate any comments on bugs and suggestions for improvements of the existing programs, which may be included in future releases. \section{Installation} %----------------------- This section contains some information on the installation of the {\MeatAxe} on a computer system. The procedure described here applies to a UNIX system. Other operating systems are supported (see below), but the installation will be more complicated and is not described here. \subsection{Contents of the Package} %----------------------------------- You should have received the {\MeatAxe} as a (compressed) {\tt tar} archive, possibly named \msg{MeatAxe-\MTXRelease.tar} Extracting the archive will create the directory {\tt mtx} with several subdirectories containing the C source code, library files, documentation and some auxiliary files. These subdirectories will be referenced below as {\tt src} (instead of {\tt ./mtx/src}), {\tt bin}, {\tt lib}, {\tt tests} and {\tt doc}. \begin{itemize} \item The {\tt src} directory contains the complete source code for the programs and libraries. \item The {\tt bin} directory contains the executable files. Initially, this directory is empty except for the makefile. There is a subdirectory \verb"bin/proggy" which contains some shell scripts for running the {\MeatAxe} programs. \item The {\tt lib} directory contains miscellaneous `library' files as for example input files for the ZEV program, and generators for some matrix and permutation groups in text format. \item The {\tt tests} directory contains some test files for testing the {\MeatAxe}. \item The {\tt doc} directory contains the documentation in {\LaTeX} format. \end{itemize} \subsection{Compiling the Programs}\label{sec:compile} %------------------------------- \begin{enumerate} \item Change to the {\tt bin} directory and edit the {\tt Makefile}. At the top of file there are some macro definitions which must be modified according to your directory structure and operating system. In particular, you must decide which version of the arithmetic will be used and under which operating systems the programs will run. \item Run \msg{make} to compile the {\MeatAxe}. All programs should compile without any error message. If your {\tt make} command has difficulties with the Makefile, use {\tt gmake}. \item Change to the {\tt tests} directory and enter msg{./testmtx} This will start an automatic test of some of the {\MeatAxe} programs. After some time, depending on your computer, you should get the message \msg{All tests passed.} \end{enumerate} \subsection{Other Operating Systems} %----------------------------------- All the programs have been developed and tested in an UNIX environment. Some other systems --- currently MS-DOS and VM/CMS --- are supported, but this is not thoroughly tested. \subsubsection{MS-DOS/DJGPP} %--------------------------- The {\MeatAxe} has been compiled with DJGCC, a DOS port of GNU gcc. DJGCC has a built-in DOS extender which allows programs to run in protected mode and providing full 32-bit memory access. Some restrictions are imposed by the MS-DOS operating system. \begin{itemize} \item Process time information and time limits are not available. Programs that report the CPU time at end will print the real run time of the program. The \verb"-T" option is silently ignored. \item File names are restricted to 8 characters plus a 3 character extension. The {\MeatAxe} i/o system will try to convert any name that does not fit into this pattern into a valid file name. For example, \msg{zad matrix.1 matrix.2 matrix.sum.1.2} will write its ouput to \verb"matrixsu.m12". \end{itemize} \subsubsection{VM/CMS} %--------------------- File names are translated as follows: \begin{list}{}{} \item {\tt file1} becomes \mbox{\tt FILE1 MTX A} \item {\tt file2.test} becomes \mbox{\tt FILE2 TEST A} \item {\tt file3.test.b} becomes \mbox{\tt FILE3 TEST B} \end{list} \section{Using the {\MeatAxe} Programs} %-------------------------------------- This section contains some general information about the {\MeatAxe} programs and how to use them. \subsection{Setting up the Environment} %-------------------------------------- Before you can use the {\MeatAxe} you must include the {\tt bin} and {\tt bin/proggy} directories in your shell's path. You may also want to define the following environment variables: \begin{center} \begin{tabular}{|l|p{0.75\linewidth}|} \hline Name & Meaning \\ \hline \tt MTXLIB & Name of the {\tt lib} directory. You need to define this variable only if you want to use a library directory different from the default library (see section \ref{sec:libdir}).\\ \hline \end{tabular} \end{center} \subsection{Arithmetic Tables} %----------------------------- All programs use lookup tables for row operations and finite field arithmetic. These tables are read from a file named \msg{pXXX.zzz} where `XXX' is the field order. For example, tables for GF(25) are read from the file {\tt p025.zzz}. If the table file is not found, the following error message will be generated: \msg{ZZZ ERROR (zzz.c, line {\it lll}) - Error opening table file} If this happens, you must either \begin{enumerate} \item run the MAKETAB program to generate the table file (see \ref{sec:maketab}), or \item copy/link an existing table file into the current working directory \end{enumerate} The table files may also be placed in the library directory (see section \ref{sec:libdir}). Thus it is not necessary to keep a separate table file in each directory. \subsection{File Types} %---------------------- All {\MeatAxe} programs operate on files --- normally, no interactive i/o is required during the run. There are two kinds of files: \begin{itemize} \item Binary (internal format) data files. Programs usually read and write data in binary format. For a description of the file format, see section \ref{sec:filefmt}. Default names are G1, G2, \ldots for input files and P1, P2, \ldots for output files. \item Text files, used by some programs as ZCV and ZPR. The format of text files is described with the ZCV program (see section \ref{sec:zcv}). \end{itemize} Typically, a program reads its input from G1,\ldots,G$n$ and writes its output to P$n+1$,\ldots,P$m$. For example, the ZTE (tensor matrices) program reads two matrices from G1 and G2 and writes their tensor product to P3. To find out which files are used by a specific program, look up the program description in chapter \ref{chap:progs}. You may override the default names by specifying new file names on the command line. For example, to multiply two matrices in {\tt mat1} and {\tt mat2} and write the result to {\tt result} call ZMU with 3 arguments as follows: \msg{zmu mat1 mat2 result} \subsection{The Library}\label{sec:libdir} %-------------------- When given a file name, all programs look for the file in the current directory first. If the file is not found there, some programs try to find it in the library directory, provided a library has been defined. This extended search applies, for example, to ZEV and ZCV input files and also to the arithmetic table files. The library is usually defined at compile-time by assigning a value to the symbol {\tt MTXLIB}. This definition may be overridden at run-time by defining the environment variable {\tt MTXLIB}. In either case {\tt MTXLIB} must be a complete directory name including a trailing separator character (e.g., '/' for UNIX). When looking for files in the library, the programs simply append the file name to the value of {\tt MTXLIB} in order to build the complete file name.