TRANSVERSAL: A MAPLE PACKAGE FOR SINGULARITY THEORY.
                Versions 3.1 and 3.2
===================================================

Calculations which arise in local singularity theory lend
themselves naturally to symbolic algebra methods. Transversal
is a package which uses such methods to deal with problems in
the classification and unfolding theory of smooth map-germs.
It consists of a collection of procedures which run under the
symbolic algebra system Maple.

The package is available to subscribers to the London
Mathematical Society, Journal of Computational Mathematics, as
an add-on link to the article:

Computational Aspects of Classifying Singularities,
Neil P. Kirk, LMS J. Comp. Math., 2000.
www.lms.ac.uk/
www.lms.ac.uk/jcm

This is the first published account of material discussing
the package, and the only published account of this article.

The package is also available on the internet; see the
AVAILABILITY section below.


RESOURCES
Transversal is a library of Maple routines. It runs under
Maple V and is presently available in two versions due to
compatibility problems with different releases of Maple.

Transversal 3.1 - runs under Maple V Release 3 and Release 4.

Transversal 3.2 - runs under Maple V Release 5.

Other than compatibility issues, there are no major
differences between the two versions of Transversal.

The package should run on most platforms, though the majority
of development has been carried out using the Unix version of
Maple. In particular, a simple Unix shell script is provided
which installs Transversal as a Maple library (available
using the "with" command). However, for portability reasons
the whole package is provided as a set of ASCII files, not as
Maple ".m" files which are machine dependent. Thus, it should
be possible to run the package on any platform which supports
Maple by issuing several (in fact a lot of!) "read" statements
from within the Maple session.


AVAILABILITY
The Transversal package is available via ftp from the
Liverpool University Department of Mathematics ftp server. For
latest information refer to the Web page for details. Either
open the Pure Mathematics Research Division home page:

www.liv.ac.uk/PureMaths/
 or
www.liv.ac.uk/maths/PURE/

and navigate to the Singularity Theory Group page, or try the
direct link:

www.liv.ac.uk/maths/PURE/MIN_SET/CONTENT/RESEARCH_GROUPS/sing.html

The package is also available to subscribers to the London
Mathematical Society, Journal of Computational Mathematics, as
an add-on link to the article:

Computational Aspects of Classifying Singularities,
Neil P. Kirk, LMS J. Comp. Math., 2000.
www.lms.ac.uk/
www.lms.ac.uk/jcm

The files transversal_31.tar and transversal_32.tar contain
the two versions of the package in tar format. (These can be
downloaded either via a Web browser or via anonymous ftp. In
the latter case switch ftp transfer to BINARY (bin) mode
before transferring the files.)

On Unix the tar file may be unpacked via the command
tar xvf transversal_31.tar

On Windows it may be unpacked using a suitable archive utility
(for example, WinZip, www.winzip.com). Note that whatever
utility you use it must recognise the tar format and be
capable of unpacking the tar file into the original directory
structure. In addition, many of the filenames used in the
package do not conform to the older DOS 8.3 naming limitations.
It is preferable to use an archive program that unpacks the
files using their actual filenames as opposed to shortening
them to conform to the 8.3 conventions. See your local
administrator for details of your particular system.

Note that the files will be extracted and PUT IN YOUR CURRENT
WORKING DIRECTORY. Thus, you may prefer to create an
appropriate subdirectory (such as transversal_31 or TRANS_31)
and change to that before extracting the tar file (see also the
installation notes below). For usage and copying restrictions
see the copyright file.


CONTENTS
On unpacking the tar file the following will be created in your
current directory.

COPYRIGHT
   copyright notice.
DOC
   directory containing documentation for the package.
README
   this file.
installtrans
   Unix shell script to install Transversal as a Maple library.
loadtr
   Maple file (ASCII text) which loads the Transversal package
   by reading in the files containing the Maple procedures. This
   provides a means of using the package on most platforms.
loadtrW
   as loadtr but for the package Transversal_W.
transversal.maple
   Maple file (ASCII text) containing the tables which define the
   Transversal package(s) as a library (required by the Maple
   command "with").
transversal_lib
   directory containing Maple files (ASCII text) defining the
   actual procedures which make up the Transversal package(s).

Note: only Transversal and Transversal_W are available in the
      present release. The other extensions (Transversal_M and
      Transversal_L) will be available in a later release.


INSTALLATION
There are two methods of installation. Method 1) is neater
and installs Transversal as a Maple library which may be
called up from any Maple session via the "with" command; it
mainly applies to Maple on Unix platforms and is the recommended
method in this case. Method 2) involves the brute force "read
all files in" technique. This is simpler and can be used on
other platforms where method 1) has not been developed yet (for
example on a PC or Mac) or by anyone unfamiliar with Maple
libraries who has problems with method 1). Method 2), which is
provided for portability reasons, will be slightly slower than
the technique used in method 1), the latter loading versions of
the files which have been stored in Maple internal ".m" format.
Note that whichever platform you are using you will still need
to obtain the package via ftp and untar the resulting files.
This is described below for Unix but may be achieved on other
systems via several available programs; ask your local
administrator for the relevant details.

The details below refer to version 3.1; version 3.2 is dealt
with similarly.


Method 1)

These installation notes apply to Unix machines running Maple V.
The installation script requires the standard "commandline Maple"
command to be present in order to run. It should be possible to
rewrite the (very simple) shell installation script to run on
other platforms, but in practice problems may arise for several
reasons. For example, the commandline Maple command may not be
available or problems may arise with regard to the limit to the
number of characters allowed in a file name in DOS. Method 2) is
suggested for non-Unix platforms unless you are confident you
can translate method 1).

The following describes complete installation instructions and
includes how to unpack the tar file in a suitable installation
directory. The symbol % denotes the Unix prompt and the example
refers to the user "person" having home directory
/usr/people/person
You should substitute these accordingly.

Firstly choose a suitable directory to install your personal
Maple libraries (or even in the Maple directory tree if you
have administration access). A good choice would be
~/maple/lib/transversal_31
in your home directory. Note: if this directory already exists
its contents may be overwritten so rename the directory and
create a new one accordingly. The directory ~/maple/lib would
be your general directory for storing Maple libraries.

% cd                   # ensure you are in your home directory
% mkdir maple
% cd maple
% mkdir lib
% cd lib
% mkdir transversal_31
% cd transversal_31

Now copy the tar file transversal_31.tar into this directory
and untar it ...

% tar xvf transversal_31.tar

All the relevant files and directories (installation files,
documentation, etc.) will then be placed in this directory.
The actual Transversal source code is written to the
subdirectory transversal_lib created during the untaring
process.

The package can now be installed by executing the shell script
"installtrans" ...

% sh installtrans

This firstly uses the data in the file transversal.maple to
build the corresponding files transversal.m and transversal_W.m
which store tables defining the Transversal libraries (these
are used by the Maple command "with" when loading the library).
It then creates ".m" versions of the ASCII files containing the
actual Transversal source code in ~/maple/lib/transversal_31/
transversal_lib. Note that such ".m" files are machine dependent
and this installation procedure must therefore be repeated if
Transversal is to be installed as a library on a different
version of Unix: you cannot just copy across the files.

Next, the pathname of the library directory needs to given to
Maple (use the full pathname and avoid ~). The Maple variable
_translib is used to store the pathname and this must also be
added to the Maple list variable libname as follows. Change to
your home directory and edit (or create) the (hidden) Maple
initialisation file .mapleinit . The commands in this file are
executed by default at the beginning of every Maple session. A
line similar to the following should be added to the file. The
full pathname of your home directory should be substituted for
/usr/people/person (and similarly if you chose to install the
library in a different place to the suggested maple/lib/
transversal_31 directory).

_translib := `/usr/people/person/maple/lib/transversal_31`:
libname := libname,_translib:

Do *NOT* forget to "backquote" the full pathname so that Maple
treats it as a single name. Since the lines are terminated with
a colon Maple will not display the result as it executes them.

The Transversal or Transversal_W libraries may now be loaded by
issuing the command:

with(transversal); 

or

with(transversal_W);

from within any Maple session.

Note: the remaining files and directories (such as DOC or README)
may be moved to a different location, but the ".m" files which
define the libraries and the directory transversal_lib which
contains the library procedures as ".m" files must remain in the
chosen Maple directory /usr/people/person/maple/lib/transversal_31.


Method 2)

Firstly unpack the Transversal tar file. This is described in
detail for Unix machines under method 1); for other platforms
plenty of software exists in order to do this. On Windows
platforms it is preferable to use an archive program such as
WinZip (www.winzip.com) that unpacks the files using their
actual, non truncated, filenames.

In what follows it is assumed that Transversal is unpacked into
one of the following directories. These are typical directory
names one may choose on a Unix machine or a PC (the Unix case
refers to the user "person" having home directory
/usr/people/person). You should substitute this directory path
for the one you chose when installing Transversal, as necessary.
Likewise the appropriate changes should be made if carrying out
this procedure on a platform different to a Unix machine or PC.

Unix:
/usr/people/person/maple/lib/transversal_31

PC:
C:\MAPLE\LIB\TRANSVERSAL_31
or (say)
C:\MAPLE\LIB\TRANS_31

Initiate a Maple session and then define the Maple variable
_translib, which is used to store the pathname of the
Transversal library directory, by issuing one of the following
Maple commands (suitably modified to suit your directory path).
In both cases do *NOT* forget to "backquote" the full pathname
so that Maple treats it as a single name.

Unix:
_translib := `/usr/people/person/maple/lib/transversal_31`;

Note: use the full Unix pathname and avoid ~.

PC:
_translib := `c:/maple/lib/trans_31`;

Note: use a forward slash / between directories, even though
a backslash is used in DOS pathnames. The use of capital
letters is not necessary.

This command must be typed at the start of every Maple session
in which you wish to use Transversal. Alternatively, the
command may be included in your Maple initialisation file so
that it is executed by default at the beginning of every Maple
session. For example, on Unix, this is the (hidden) file
.mapleinit in your home directory.

Next, to load Transversal instruct Maple to read the file
loadtr (or loadtrW for Transversal_W) ...

read loadtr;

This file contains the relevant Maple commands to read in all
of the files which make up the Transversal library.

Note: the commands in the file loadtr find where the
Transversal files live through the variable _translib.

Possible Problems:

1) Maple may be unable to find the file loadtr and thus return
a read error. The simplest solution is to change to the
directory where you installed Transversal and then run Maple
from there, if possible. For example on Unix:

% cd ~/maple/lib/transversal_31

Maple will then (correctly) look for loadtr in this directory
when you issue the read command. If all else fails you can
issue the read command giving the full pathname, thus:

Unix:
read `/usr/people/person/maple/lib/transversal_31/loadtr`;

PC:
read `c:/maple/lib/trans_31/loadtr`;

2) Maple is unable to complete the read statements present in
the file loadtr (this will result in numerous error messages
being output). The most likely reason for these errors is that
the operating system you are using imposes DOS limits on the
number of characters allowed in a file name and its extension,
or the archive program unpacked the tar file and adopted such
limits. In the latter case the preferred solution is to use
an archive program that does not impose the DOS 8.3 naming
limitations. Alternatively, the solution is for the user to
edit the read statements within the file loadtr so that the
directory names and file names match those used by your
operating system. For example, suppose you rename the
Transversal directory transversal_lib as tran_lib (the former
directory is created by unpacking the tar file and contains
the Maple source code) and, in addition, the file
jetcalc.maple in transversal_lib/Standard is shortened to
jetcal~1.map then in loadtr change the line

read cat(_translib,`/transversal_lib/Standard/jetcalc.maple`):

to 

read cat(_translib,`/tran_lib/Standard/jetcal~1.map`): 

And similarly for the other read statements.


DOCUMENTATION
The directory DOC contains a copy of the Transversal User Manual
in PostScript and LaTeX2e formats. The PostScript version was
prepared for A4 paper. If this is unsuitable then try editing
and recompiling the LaTeX file: the A4 page settings are clearly
marked at the start of the document so it should be clear what
to change (though you may have to edit the LaTeX code slightly
to eliminate any serious overfull boxes and the like). Note that
the manual was prepared for double-sided printing, for example,
chapters ending on a right-hand-side, odd-numbered page are
immediately followed by a blank, left-hand-side page.

A tutorial and reference guide are also available - these are
included as part of the user manual. The manual was written for
Transversal 3.1. It has not been updated for version 3.2 but,
other than being slightly out of date with regard to the sections
on background and history, should be equally applicable.


COPYRIGHT, DISCLAIMERS, CONTACT INFO, ETC.
Transversal, and its documentation, is Copyright (c) 2000 by
Neil P. Kirk; see the separate copyright notice for details
of use and copying.

If you use this software in your work I request that you give a
suitable acknowledgement in any publication or presentation.

Although this software has been extensively tested the standard
``disclaimers'' apply. There is no warranty or other guarantee of
fitness for the software, it is provided solely "as is". All
comments and suggestions are welcome and may be sent to me at the
following address. Bug reports and fixes may be sent to this
address too.

Dr. N.P. Kirk,
Department of Mathematical Sciences,
University of Liverpool,
P.O. Box 147,
Liverpool,
L69 3BX.
England.

Email: npkirk@hotmail.com
       neilpk@liverpool.ac.uk


--------------------

Neil Kirk
June 2000