reduce-historical/r38/packages/assist/assist.tex

\documentstyle[11pt,reduce]{article}
\newcommand{\nl}{\hfill\newline}
\newcommand{\bq}{\begin{quotation}}
\newcommand{\eq}{\end{quotation}}
\newcommand{\bi}{\begin{itemize}}
\newcommand{\ei}{\end{itemize}}
\title{{\bf ASSIST}\ :\\[2pt]
 A General Purpose Addition to~\REDUCE \\[5pt]
       \mbox{\hfill Version 2.3\hfil}}
\author{Hubert Caprasse \\
D\'epartement d'Astronomie et d'Astrophysique \\
Institut de Physique, B--5, Sart Tilman \\
B--4000 LIEGE 1 \\[3pt]
E--mail: caprasse@vm1.ulg.ac.be}
\begin{document}
\maketitle
%\index{ASSIST package}
\section{Introduction}
 The package ASSIST contains
an appreciable number of additional general purpose functions which allow
one to better adapt \REDUCE\ to various calculational strategies,
to make the programming task more straightforward and, sometimes, 
more efficient.

In contrast with all other packages, ASSIST does not aim to provide either a
new facility to compute a definite class of mathematical objects or to extend
the base of mathematical knowledge of \REDUCE\ .
The functions it contains should be
useful independently of the nature of the application which is considered.
They were initially written while applying \REDUCE\ to specific problems in
theoretical physics. Most of them were designed
in such a way that their applicability range is broad. Though it was not
the primary goal, efficiency has been sought whenever possible.

The source code in ASSIST contains many comments concerning
the meaning and use of the supplementary functions available
in the algebraic mode. These comments, hopefully, make the code transparent
and allow a thorough exploitation of the package. The present documentation
contains a non--technical description of it and describes the
various new facilities it provides.
\section{ Survey of the Available New Facilities}
An elementary help facility is available both within
the MS-DOS\ and Windows environments. It is independent of the
help facility of \REDUCE\ itself. It includes two functions:

\f{ASSIST} is a function which takes no argument. If entered, it returns 
the informations required for a proper use  of \f{ASSISTHELP}.\\   
\f{ASSISTHELP} takes one argument.   
\begin{itemize}
\item[i.] If the argument is the identifier \f{assist}, the function 
returns the information necessary to retrieve the names of all the available
functions.
\item[ii.] If the argument is an integer equal to one of the section numbers
of the present documentation. The names of the functions described
in that section are obtained.\nl
There is, presently, no possibility to retrieve the number and the type of 
the arguments of a given function.
\end{itemize}
The package contains several modules. Their content reflects closely
the various categories of facilities listed below. Some functions do
already exist inside the KERNEL of \REDUCE\ . However, their range
of applicability is {\em extended}.\nl

\begin{itemize}
\item{Control of Switches:}
\begin{quotation}
\noindent
\f{SWITCHES SWITCHORG}
\end{quotation}
\item{Operations on Lists and Bags:}
\begin{quotation}
\noindent
\f{MKLIST KERNLIST ALGNLIST LENGTH \nl
POSITION FREQUENCY SEQUENCES SPLIT \nl
INSERT INSERT\_KEEP\_ORDER MERGE\_LIST \nl
FIRST SECOND THIRD REST REVERSE LAST \nl
BELAST CONS ( . ) APPEND APPENDN \nl
REMOVE DELETE DELETE\_ALL DELPAIR \nl
MEMBER ELMULT PAIR DEPTH MKDEPTH\_ONE \nl
REPFIRST REPREST ASFIRST ASLAST ASREST \nl
ASFLIST ASSLIST RESTASLIST SUBSTITUTE \nl
BAGPROP PUTBAG CLEARBAG BAGP BAGLISTP \nl
ALISTP ABAGLISTP LISTBAG }
\end{quotation}
\item{Operations on Sets:}
\begin{quotation}
\noindent
\f{MKSET SETP UNION INTERSECT DIFFSET SYMDIFF}
\end{quotation}
%\newpage
\item{General Purpose Utility Functions:}
\begin{quotation}
\noindent
\f{LIST\_TO\_IDS MKIDN MKIDNEW DELLASTDIGIT DETIDNUM \\
ODDP FOLLOWLINE  == RANDOMLIST MKRANDTABL \\
PERMUTATIONS CYCLICPERMLIST PERM\_TO\_NUM NUM\_TO\_PERM\\ 
COMBNUM COMBINATIONS SYMMETRIZE REMSYM \\
SORTNUMLIST SORTLIST ALGSORT EXTREMUM GCDNL\\
DEPATOM FUNCVAR IMPLICIT EXPLICIT REMNONCOM \\
KORDERLIST SIMPLIFY CHECKPROPLIST EXTRACTLIST} 
\end{quotation}
\item{ Properties and Flags:}
\begin{quotation}
\noindent
\f{PUTFLAG PUTPROP DISPLAYPROP DISPLAYFLAG \\
CLEARFLAG CLEARPROP }
\end{quotation}
\item{ Control Statements, Control of Environment:}
\begin{quotation}
\noindent
\f{NORDP DEPVARP ALATOMP ALKERNP PRECP \\
 SHOW SUPPRESS CLEAROP CLEARFUNCTIONS }
\end{quotation}
\item{Handling of Polynomials:}
\begin{quotation}
\noindent
\f{ALG\_TO\_SYMB SYMB\_TO\_ALG \\
DISTRIBUTE LEADTERM REDEXPR MONOM\\
LOWESTDEG DIVPOL SPLITTERMS SPLITPLUSMINUS}
\end{quotation}
% \vfill\pagebreak
\item{Handling of Transcendental Functions:}
\begin{quotation}
\noindent
\f{TRIGEXPAND HYPEXPAND TRIGREDUCE HYPREDUCE}
\end{quotation}
\item{Coercion from Lists to Arrays and converse:}
\begin{quotation}
\f{LIST\_TO\_ARRAY ARRAY\_TO\_LIST}
\end{quotation}
\item{Handling of n-dimensional Vectors:}
\begin{quotation}
\noindent
\f{SUMVECT MINVECT SCALVECT CROSSVECT MPVECT }
\end{quotation}
{\item Handling of Grassmann Operators:}
\begin{quotation}
\noindent
\f{PUTGRASS REMGRASS GRASSP GRASSPARITY GHOSTFACTOR }
\end{quotation}
\item{Handling of Matrices:}
\begin{quotation}
\noindent
\f{UNITMAT MKIDM BAGLMAT COERCEMAT \\
SUBMAT MATSUBR MATSUBC RMATEXTR RMATEXTC \\
 HCONCMAT VCONCMAT TPMAT HERMAT \\
SETELTMAT GETELTMAT}
\eq
\item{Control of the HEPHYS package:}
\bq
\noindent
\f{REMVECTOR REMINDEX MKGAM}
\end{quotation}
\end{itemize}
In the following all these functions are described.
\section{Control of Switches}
The two available functions i.e. \f{SWITCHES, SWITCHORG} have
no argument and are called as if they were mere identifiers.

\f{SWITCHES} displays the actual status of the most frequently used switches
when manipulating rational functions. The chosen switches are
\begin{quotation}
\noindent
{\tt EXP, ALLFAC, EZGCD, GCD, MCD, LCM, DIV, RAT, \\%
INTSTR, RATIONAL, PRECISE, REDUCED, RATIONALIZE, \\% 
COMBINEEXPT, COMPLEX, REVPRI, DISTRIBUTE.}
\end{quotation}

The selection is somewhat arbitrary but it may be changed in a trivial
fashion by the user.

The new switch {\tt DISTRIBUTE} allows one to put polynomials in a
distributed form (see the description below of
the new functions for manipulating  them.~).

Most of the symbolic variables {\tt !*EXP, !*DIV, $\ldots$}
which have either the value T or the value NIL are made available in the
algebraic mode so that it becomes possible to write conditional
statements of the kind
\begin{verbatim}

        IF !*EXP THEN DO ......

        IF !*GCD THEN OFF GCD;

\end{verbatim}
\f{SWITCHORG} resets  the switches enumerated above to the status
they had when {\bf starting} \REDUCE\ .
\section{Manipulation of the List Structure}

Additional functions for list manipulations are provided and some already
defined functions in the kernel of \REDUCE\ are modified to properly
generalize them to the available new structure {\tt BAG}.
\begin{itemize}
\item[i.]
Generation of a list of length n with all its elements initialized to 0
and possibility to append to a list $l$ a certain number of
zero's to make it of length $n$:
\begin{verbatim}

        MKLIST n ;    n is an INTEGER

        MKLIST(l,n);    l is List-like, n is an INTEGER

\end{verbatim}

\item[ii.]
Generation of a list of sublists of length n containing p elements
equal to 0 and q elements equal to 1 such that  $$p+q=n .$$
The function \f{SEQUENCES} works both in algebraic and
symbolic modes.  Here is an example in the algebraic mode:
\begin{verbatim}

        SEQUENCES 2 ; ==> {{0,0},{0,1},{1,0},{1,1}}

\end{verbatim}
An arbitrary splitting of a list can be done. The function \f{SPLIT} 
generates a list which contains the splitted parts of the original list.
\begin{verbatim}
        
        SPLIT({a,b,c,d},{1,1,2}) ==> {{a},{b},{c,d}}

\end{verbatim}
The function \f{ALGNLIST} constructs a list which contains n copies  
of a list bound to its first argument.
\begin{verbatim}

        ALGNLIST({a,b,c,d},2); ==> {{a,b,c,d},{a,b,c,d}}

\end{verbatim}
The function \f{KERNLIST} transforms any prefix of a kernel into the
{\bf \verb+list+} prefix. The output list is a copy:
\begin{verbatim}

        KERNLIST (<kernel>); ==> {<kernel arguments>}

\end{verbatim}
Four functions to delete elements are \f{DELETE, REMOVE, DELETE\_ALL} and
\f{DELPAIR}. The first two act as in symbolic mode, and the third
eliminates from a given list {\em all}
elements equal to its first argument. The fourth acts on a list of pairs
and eliminates from it the {\em first} pair whose first element is equal to
its first argument :
\begin{verbatim}

        DELETE(x,{a,b,x,f,x}); ==> {a,b,f,x}

        REMOVE({a,b,x,f,x},3); ==> {a,b,f,x}

        DELETE_ALL(x,{a,b,x,f,x}); ==> {a,b,f}

        DELPAIR(a,{{a,1},{b,2},{c,3}}; ==> {{b,2},{c,3}}

\end{verbatim}
\item[iv.]
The function \f{ELMULT} returns an {\em integer} which is the
{\em multiplicity} of its first argument inside the list which is its
second argument.
The function \f{FREQUENCY} gives a list of pairs
whose second element indicates the number of times the first element
appears inside the original list:
\begin{verbatim}

        ELMULT(x,{a,b,x,f,x}) ==> 2

        FREQUENCY({a,b,c,a}); ==> {{a,2},{b,1},{c,1}}

\end{verbatim}
\item[v.]
The function \f{INSERT} allows one to insert a given object into a list
at the desired position.

The functions \f{INSERT\_KEEP\_ORDER} and \f{MERGE\_LIST} allow one to
keep a given ordering when inserting one element inside a list or
when merging two lists. Both have 3 arguments. The last one  is
the name of a binary boolean ordering function:
\begin{verbatim}

        ll:={1,2,3}$

        INSERT(x,ll,3); ==> {1,2,x,3}

        INSERT_KEEP_ORDER(5,ll,lessp); ==> {1,2,3,5}

        MERGE_LIST(ll,ll,lessp); ==> {1,1,2,2,3,3}

\end{verbatim}
Notice that \f{MERGE\_LIST} will act correctly only if the two lists 
are well ordered themselves. 
\item[vi.]
Algebraic lists can be read from right to left or left to right.
They {\em look} symmetrical. One would like to dispose of manipulation
functions which reflect this.
So, to the already defined functions  \f{FIRST} and \f{REST} are
added the functions \f{LAST}  and \f{BELAST}. \f{LAST} gives the last
element of the list while \f{BELAST} gives the list {\em without} its
last element. \\
Various additional functions are provided. They are:
\bq
\noindent
\f{ . (``dot''), POSITION, DEPTH, MKDEPTH\_ONE, \\
PAIR, APPENDN, REPFIRST, REPREST}
\eq
The token ``dot'' needs a special comment. It corresponds to
several different operations.
\begin{enumerate}
\item If one applies it on the left of a list, it acts as the \f{CONS}
function. Note however that blank spaces are required around the dot:
\begin{verbatim}

        4 . {a,b}; ==> {4,a,b}

\end{verbatim}
\item If one applies it on the right of a list, it has the same
effect as the \f{PART} operator:
\begin{verbatim}

         {a,b,c}.2; ==> b

\end{verbatim}
\item If one applies it to  a 4--dimensional vectors, it acts as in the
HEPHYS package.
\end{enumerate}
\f{POSITION} returns the POSITION of the first occurrence of x in
a list or a message if x is not present in it.

\f{DEPTH} returns an {\em integer} equal to the number of levels where a
   list is found if and only if this number is the {\em same} for each
   element of the list  otherwise it returns a message telling the user
  that the list is of {\em unequal depth}. The function \f{MKDEPTH\_ONE}
  allows to transform any list into a list of depth equal to 1.

\f{PAIR} has two arguments which must be lists. It returns a list
whose elements are {\em lists of two elements.}
The $n^{th}$ sublist contains the $n^{th}$ element of the first list
and the $n^{th}$ element of the second list. These types of lists are called
{\em association lists} or ALISTS in the following.
To test for these type of lists a boolean function \f{ABAGLISTP}
is provided. It will be discussed below.\\
\f{APPENDN} has {\em any} fixed number of lists as arguments. It
generalizes the already existing function \f{APPEND} which accepts
only two lists as arguments. It may also be used for arbitrary kernels 
but, in that case, it is important to notice that {\em the concatenated 
object is always a list}.\\
\f{REPFIRST} has two arguments. The first one is any object, the second one
is a list. It replaces the first element of the list by the object. It
works like the symbolic function \f{REPLACA} except that the
original list is not destroyed.\\
\f{REPREST} has also two arguments. It replaces the rest of the list by
its first argument and returns the new list {\em without destroying} the
original list. It is analogous to the symbolic function \f{REPLACD}.
Here are examples:
\begin{verbatim}

        ll:={{a,b}}$
        ll1:=ll.1; ==> {a,b}
        ll.0; ==> list
        0 . ll; ==> {0,{a,b}}

        DEPTH ll; ==> 2

        PAIR(ll1,ll1); ==> {{a,a},{b,b}}

        REPFIRST{new,ll); ==> {new}

        ll3:=APPENDN(ll1,ll1,ll1); ==> {a,b,a,b,a,b}

        POSITION(b,ll3); ==> 2

        REPREST(new,ll3); ==> {a,new}

\end{verbatim}
\item[vii.]
The functions \f{ASFIRST, ASLAST, ASREST, ASFLIST, ASSLIST, \\RESTASLIST}
act on ALISTS or on lists of lists of well defined depths
and have two arguments. The first is the key object
which one seeks to associate in some way with an element of the association
list which is the second argument.\\
\f{ASFIRST} returns the pair whose first element is equal to the
first argument.\\
\f{ASLAST} returns the pair whose last element is equal to the first
argument.\\
\f{ASREST} needs a {\em list} as its first argument. The function
seeks the first sublist of a list of lists (which is its second argument)
equal to its first argument and returns it.\\
\f{RESTASLIST} has a {\em list of keys} as its first argument. It
returns the collection of pairs which meet the criterium of \f{ASREST}.\\
\f{ASFLIST} returns a list containing {\em all pairs} which
satisfy the criteria of the function \f{ASFIRST}. So the output
is also an association list.\\
\f{ASSLIST} returns a list which contains {\em all pairs} which have
their second element equal to the first argument.\\
Here are a few examples:
\begin{verbatim}

        lp:={{a,1},{b,2},{c,3}}$

        ASFIRST(a,lp); ==> {a,1}

        ASLAST(1,lp); ==> {a,1}

        ASREST({1},lp); ==> {a,1}

        RESTASLIST({a,b},lp); ==> {{1},{2}}

        lpp:=APPEND(lp,lp)$

        ASFLIST(a,lpp); ==> {{a,1},{a,1}}

        ASSLIST(1,lpp); ==> {{a,1},{a,1}}

\end{verbatim}
\item[vii.] The function \f{SUBSTITUTE} has three arguments. The first
is the object to be substituted, the second is the object which must be
replaced by the first, and the third is the list in which the substitution 
must be made. Substitution is made to
all levels. It is a more elementary function than \f{SUB} but its
capabilities are less. When dealing with algebraic quantities, it is
important to make sure that {\em all} objects involved in the function
have either the prefix lisp or the standard quotient representation
otherwise it will not properly work.
\end{itemize}
\section{ The Bag Structure and its Associated Functions}
The LIST structure of \REDUCE\ is very convenient for manipulating
groups of objects which are, a priori, unknown. This structure is
endowed with other properties such as ``mapping'' i.e. the fact that
if \verb+OP+ is an operator one gets, by default,
\begin{verbatim}

        OP({x,y}); ==> {OP(x),OP(y)}

\end{verbatim}
It is not permitted to submit lists to the operations valid on rings
so that, for example, lists cannot be indeterminates of polynomials.\\
Very frequently too, procedure arguments cannot be lists.
At the other extreme, so to say, one has the \verb+KERNEL+
structure associated
with the algebraic declaration \verb+operator+ .  This structure behaves as
an ``unbreakable'' one and, for that reason, behaves
like an ordinary identifier.
It may generally be bound to all non-numeric procedure parameters
and it may appear
as an ordinary indeterminate inside polynomials. \\
The \verb+BAG+ structure is intermediate between a list and an operator.
From the operator it borrows the property of being a \verb+KERNEL+ and,
therefore, may be an indeterminate of a polynomial. From the list structure
it borrows the property of being a {\em composite} object.\\[5pt]
\mbox{\underline{{\bf Definition}:\hfill}}\\[4pt]
A bag is an object endowed with the following properties:
\begin{enumerate}
\item It is a \verb+KERNEL+ i.e. it is  composed of an atomic prefix (its
envelope) and
its content (miscellaneous objects).
\item Its content may be handled in an analogous way as the content of a
list. The important difference is that during these manipulations 
the name of the bag is {\em kept}.
\item Properties may be given to the envelope. For instance, one may
declare it \verb+NONCOM+ or \verb+SYMMETRIC+ etc.\ $\ldots$
\end{enumerate}
\vspace{5pt}
\mbox{\underline{{\bf Available Functions}:\hfill}}
\bi
\item[i.] A default bag envelope \verb+BAG+ is defined.
It is a reserved identifier.
An identifier other than \verb+LIST+ or one which is already associated
with a boolean function may be defined as a bag envelope through the
command \f{PUTBAG}. In particular, any operator may also be declared
to be a bag. {\bf When and only when} the identifier is not an already defined
function does \f{PUTBAG} put on it the property of an OPERATOR PREFIX.
The command:
\begin{verbatim}

        PUTBAG id1,id2,....idn;

\end{verbatim}
declares \verb+id1,.....,idn+ as bag envelopes.
Analogously, the command
\begin{verbatim}

        CLEARBAG id1,...idn;

\end{verbatim}
eliminates the bag property on \verb+id1,...,idn+.
\item[ii.] The boolean function \f{BAGP} detects the bag property.
Here is an example:
\begin{verbatim}

        aa:=bag(x,y,z)$

        if BAGP aa then "ok"; ==> ok

\end{verbatim}
\item[iii.] The functions listed below may act both on lists or bags.
Moreover, functions subsequently  defined for  SETS also work for a bag
when its content is a set.
Here is a list of the main ones:

\begin{quotation}
\noindent
\f{FIRST, SECOND, LAST, REST, BELAST, DEPTH, LENGTH, REVERSE,\\
MEMBER, APPEND, . (``dot''), REPFIRST, REPREST} $\ldots$
\end{quotation}

However, since they keep track of the envelope, they act
somewhat differently. Remember that   
\vspace{5pt}
\begin{center}
the NAME of the ENVELOPE is KEPT by the functions \\[3pt]
\f{FIRST, SECOND and LAST}.
\end{center}
Here are a few examples (more examples are
given inside the test file):
\begin{verbatim}

        PUTBAG op; ==> T

        aa:=op(x,y,z)$

        FIRST op(x,y,z); ==> op(x)

        REST op(x,y,z); ==> op(y,z)

        BELAST op(x,y,z); ==> op(x,y)

        APPEND(aa,aa); ==> op(x,y,z,x,y,z)

        APPENDN(aa,aa,aa); ==> {x,y,z,x,y,z,x,y,z}

        LENGTH aa; ==> 3

        DEPTH aa; ==> 1

        MEMBER(y,aa); ==> op(y,z)

\end{verbatim}
When ``appending'' two bags with {\em different} envelopes, the resulting bag
gets the name of the one bound to the first parameter of \f{APPEND}. When  
\f{APPENDN} is used, the output is always a list.\\
The function \f{LENGTH} gives the number of objects contained in the 
bag.
\item[iv.]
The connection between the list and the bag structures is made easy
thanks to \f{KERNLIST} which transforms a bag into a list and thanks to
the coercion function \f{LISTBAG} which transforms a list into a bag. 
This function has 2 arguments
and is used as follows:
\begin{verbatim}

        LISTBAG(<list>,<id>); ==> <id>(<arg_list>)

\end{verbatim}
The identifier \verb+<id>+, if allowed, is automatically declared as a bag
envelope or an error message is generated. \\[3pt]
Finally, two boolean functions which work both for bags and lists are
provided. They are \f{BAGLISTP} and \f{ABAGLISTP}.
They return t or nil (in a conditional statement) if their argument
is a bag or a list for the first one, or if their argument is a list of
sublists or a bag containing bags for the second one.
\end{itemize}
\section{Sets and their Manipulation Functions}
Functions for sets exist at the level of symbolic mode. The
package makes them available in algebraic mode but also {\em generalizes}
them so that they can be applied to bag-like objects as well.
\bi
\item[i.]
The constructor \f{MKSET} transforms a list or bag into a set by eliminating
duplicates.
\begin{verbatim}

        MKSET({1,a,a}); ==> {1,a}
        MKSET bag(1,a,1,a); ==> bag(1,a)

\end{verbatim}

\f{SETP} is a boolean function which recognizes set--like objects.
\begin{verbatim}

        if SETP {1,2,3} then ... ;

\end{verbatim}
\item[ii.]
The available functions are
\begin{center}
\f{UNION, INTERSECT, DIFFSET, SYMDIFF}.
\end{center}
They have two arguments which must be sets otherwise an error message
is issued.
Their meaning is transparent from their name. They respectively give the
union, the intersection, the difference and the symmetric difference of two
sets.
\ei
\section{General Purpose Utility Functions}
Functions in this sections have various purposes. They have all been used
many times in applications in some form or another. The form given
to them in this package is adjusted to maximize their range of applications.
\bi
\item[i.]
The functions \f{MKIDNEW DELLASTDIGIT DETIDNUM LIST\_TO\_IDS}
handle identifiers. 

\f{MKIDNEW} has either 0 or 1 argument. 
It generates an identifier which has not yet been used before.
\begin{verbatim}

        MKIDNEW(); ==> g0001

        MKIDNEW(a); ==> ag0002

\end{verbatim}
\f{DELLASTDIGIT} takes an integer as argument and strips it from its last
digit.
\begin{verbatim}

        DELLASTDIGIT 45; ==> 4

\end{verbatim}
\f{DETIDNUM} deletes the last digit from an
identifier. It is a very convenient function when one wants to make a do
loop starting from a set of indices $ a_1, \ldots , a_{n} $.
\begin{verbatim}

        DETIDNUM a23; ==> 23

\end{verbatim}

\f{LIST\_to\_IDS} generalizes the function \f{MKID} to a list of
atoms. It creates and intern an identifier from the concatenation of
the atoms. The first atom cannot be an integer.
\begin{verbatim}

        LIST_TO_IDS {a,1,id,10}; ==> a1id10

\end{verbatim}
The function \f{ODDP}  detects odd integers.

The function \f{FOLLOWLINE} is convenient when using the function \f{PRIN2}.
It allows one to format output text in a much more flexible way than with
the function \f{WRITE}. \\
Try the following examples :
\begin{verbatim}

        <<prin2 2; prin2 5>>$ ==> ?

        <<prin2 2; followline(5); prin2 5;>>; ==> ?

\end{verbatim}
The function \f{==} is a short and convenient notation for the \f{SET}
function. In fact it is a {\em generalization} of it to allow one to
deal also with KERNELS:
\begin{verbatim}

        operator op;

        op(x):=abs(x)$

        op(x) == x; ==> x

        op(x); ==> x
        
        abs(x); ==> x

\end{verbatim}
The function \f{RANDOMLIST} generates a list of random numbers. It takes
two arguments which are both integers. The first one indicates the range
inside which the random numbers are chosen. The second one indicates how
many numbers are to be generated. Its output is the list of 
generated numbers.
\begin{verbatim}

        RANDOMLIST(10,5); ==> {2,1,3,9,6}

\end{verbatim}
\f{MKRANDTABL} generates a table of random numbers. This table is either
a one or two dimensional array. The base of random numbers may be either
an integer or a decimal number. In this last case, to work properly,
the switch \f{rounded} must be ON. It has three arguments. The first is
either a one integer or a two integer list. The second is the base chosen
to generate the random numbers. The third is the chosen name for the
generated array. In the example below a two-dimensional table of
random integers is generated as array elements of the identifier {\f ar}.
\begin{verbatim}

        MKRANDTABL({3,4},10,ar); ==>

               *** array ar redefined

                      {3,4}

\end{verbatim}
The output is the dimension of the constructed array.

\f{PERMUTATIONS} gives the list of permutations of $n$ objects.
Each permutation is itself a list. \f{CYCLICPERMLIST} gives the list of
{\em cyclic} permutations. For both functions, the argument may
also be a {\tt bag}.
\begin{verbatim}

        PERMUTATIONS {1,2} ==> {{1,2},{2,1}}

        CYCLICPERMLIST {1,2,3} ==>

                {{1,2,3},{2,3,1},{3,1,2}}

\end{verbatim}
\f{PERM\_TO\_NUM} and \f{NUM\_TO\_PERM} allow to associate to a given 
permutation of n numbers or identifiers a number between $0$ and 
$n! - 1$. The first function has the two permutated lists  
as its arguments and it returns an integer. The second one has an integer  
as its first argument and a list as its second argument. It returns the 
list of permutated objects.
\begin{verbatim}

        PERM_TO_NUM({4,3,2,1},{1,2,3,4}) ==> 23

        NUM_TO_PERM(23,{1,2,3,4}); ==> {4,3,2,1}

\end{verbatim}
\f{COMBNUM} gives the number of combinations of $n$ objects
taken $p$ at a time. It has the two integer arguments $n$ and $p$.

\f{COMBINATIONS} gives a list of combinations on $n$ objects taken $p$
at a time. It has two arguments. The first one is a list (or a bag) and
the second one is the integer $p$.
\begin{verbatim}

        COMBINATIONS({1,2,3},2) ==> {{2,3},{1,3},{1,2}}

\end{verbatim}
\f{REMSYM} is a command that suppresses the effect of the \REDUCE\ commands
\verb+symmetric+ or \verb+antisymmetric+ .

\f{SYMMETRIZE} is a powerful function which generates a symmetric expression.
It has 3 arguments. The first is a list (or a list of lists) containing
the expressions which will appear as variables for a kernel. The second
argument is the kernel-name and the third is a permutation function
which exists either in algebraic or symbolic mode. This
function may be constructed by the user. Within this package
the two functions \f{PERMUTATIONS} and \f{CYCLICPERMLIST} may be used.
Examples:
\begin{verbatim}

        ll:={a,b,c}$

        SYMMETRIZE(ll,op,cyclicpermlist); ==>

                OP(A,B,C) + OP(B,C,A) + OP(C,A,B)

        SYMMETRIZE(list ll,op,cyclicpermlist); ==>

                OP({A,B,C}) + OP({B,C,A}) + OP({C,A,B})

\end{verbatim}
Notice that, taking for the first argument a list of lists gives rise to
an expression where  each kernel has a {\em list as argument}. Another
peculiarity of this function is the fact that, unless a pattern matching is
made on the operator \verb+OP+, it needs to be reevaluated. This peculiarity
is convenient when \verb+OP+ is an abstract operator if one wants to 
control the subsequent simplification process. Here is an illustration:
\begin{verbatim}

        op(a,b,c):=a*b*c$

        SYMMETRIZE(ll,op,cyclicpermlist); ==>

                 OP(A,B,C) + OP(B,C,A) + OP(C,A,B)

        REVAL ws; ==>
                 
                 OP(B,C,A) + OP(C,A,B) + A*B*C

        for all x let op(x,a,b)=sin(x*a*b);

        SYMMETRIZE(ll,op,cyclicpermlist); ==>

                  OP(B,C,A) + SIN(A*B*C) + OP(A,B,C)

\end{verbatim}
The functions \f{SORTNUMLIST} and \f{SORTLIST} are functions which sort
lists. They use the {\em bubblesort} and the {\em quicksort} algorithms.

\f{SORTNUMLIST} takes as argument a list of numbers. It sorts it in
increasing order.

\f{SORTLIST} is a generalization of the above function.
It sorts the list according
to any well defined ordering. Its first argument is the list and its
second argument is the ordering function. The content of the list
need not necessarily be numbers but must be such that the ordering function
has a meaning.
\f{ALGSORT} exploits the PSL \f{SORT} function. It is intended to replace
the two functions above.
\begin{verbatim}

        l:={1,3,4,0}$  SORTNUMLIST l; ==> {0,1,3,4}

        ll:={1,a,tt,z}$ SORTLIST(ll,ordp); ==> {a,z,tt,1}

        l:={-1,3,4,0}$  ALGSORT(l,>); ==> {4,3,0,-1}

\end{verbatim}
It is important to realise that using these functions for kernels or bags
may be dangerous since they are destructive. If it is necessary, it is
recommended to first apply \f{KERNLIST} to them to act on a copy.

The function \f{EXTREMUM} is a generalization of the already defined functions
\f{MIN, MAX} to include general orderings. It is a 2 argument function.
The first is the list and the second is the ordering function.
With the list \verb+ll+ defined in the last example, one gets
\begin{verbatim}

        EXTREMUM(ll,ordp); ==> 1

\end{verbatim}

\f{GCDNL} takes a list of integers as argument and returns their gcd.  
\item[iii.] There are four functions to identify dependencies.
\f{FUNCVAR} takes any expression as argument and returns the set of
variables on which it depends. Constants are  eliminated.
\begin{verbatim}

        FUNCVAR(e+pi+sin(log(y)); ==> {y}

\end{verbatim}
\f{DEPATOM} has an {\bf atom} as argument. It returns it if it is
a number or if no dependency has previously been declared. Otherwise,
it returns the list of variables which the prevoius \f{DEPEND} declarations
imply.
\begin{verbatim}

        depend a,x,y;

        DEPATOM a; ==> {x,y}

\end{verbatim}
The functions \f{EXPLICIT} and \f{IMPLICIT} make explicit or
implicit the dependencies. This example shows how they work:
\begin{verbatim}

        depend a,x; depend x,y,z;

        EXPLICIT a; ==> a(x(y,z))

        IMPLICIT ws; ==> a

\end{verbatim}
These are useful when one wants to trace the names of the independent 
variables
and (or) the nature of the dependencies.

\f{KORDERLIST} is a zero argument function which displays the actual
ordering.
\begin{verbatim}

        korder x,y,z;

        KORDERLIST; ==> (x,y,z)

\end{verbatim}

\item[iv.] A command \f{REMNONCOM} to remove the non-commutativity of 
operators previously declared non-commutative is available. Its use is like 
the one of the command \f{NONCOM}.

\item[v.] Filtering functions for lists.

\f{CHECKPROPLIST}  is a  boolean function which checks if the
elements of a list have a definite property. Its first argument
is the list, its second argument is a boolean function
(\f{FIXP NUMBERP $\ldots$}) or an ordering function (as \f{ORDP}).

\f{EXTRACTLIST} extracts from the list given as its first argument
the elements which satisfy the boolean function given as its second
argument. For example:
\begin{verbatim}

        if CHECKPROPLIST({1,2},fixp) then "ok"; ==> ok

        l:={1,a,b,"st")$

        EXTRACTLIST(l,fixp); ==> {1}

        EXTRACTLIST(l,stringp); ==> {st}

\end{verbatim}
\item[vi.] Coercion.

Since lists and arrays have quite distinct behaviour and storage properties,  
it is interesting to coerce lists into arrays and vice-versa in order to 
fully exploit the advantages of both datatypes. The functions  
\f{ARRAY\_TO\_LIST} and \f{LIST\_TO\_ARRAY} are provided to do that easily.
The first function has the array identifier as its unique argument. 
The second
function has three arguments. The first is the list, the second is the 
dimension of the array and the third is the identifier which defines it.  
If the chosen dimension is not compatible with the
the list depth, an error message is issued.  
As an illustration suppose that $ar$ is an array whose components are  
1,2,3,4. then
\begin{verbatim}

        ARRAY_TO_LIST ar; ==> {1,2,3,4}

        LIST_TO_ARRAY({1,2,3,4},1,arr}; ==> 

\end{verbatim}
generates the array $arr$ with the components 1,2,3,4.
\item[vii.] Control of the \f{HEPHYS} package.  

The commands \f{REMVECTOR} and \f{REMINDEX} remove the property of 
being a 4-vector or a 4-index respectively. 

The function \f{MKGAM} allows to assign to any identifier the property 
of a Dirac gamma matrix and, eventually, to suppress it. Its interest lies 
in the fact that, during a calculation, it is often useful to transform 
a gamma matrix into an abstract operator and vice-versa. Moreover, in many 
applications in basic physics, it is interesting to use the identifier $g$ 
for other purposes.  
It takes two arguments. The first is the identifier. The second must be 
chosen equal to {\tt\bf t} if one wants to transform it into a gamma matrix. Any
other binding for this second argument suppresses the property of being 
a gamma matrix the identifier is supposed to have. 
\ei
\section{Properties and Flags}
In spite of the fact that many facets of the handling of
property lists is easily accessible in algebraic mode, it is useful to
provide analogous functions {\em genuine} to the algebraic mode. The reason is
that, altering property lists of objects, may easily destroy the integrity
of the system. The functions, which are here described, {\bf do ignore}
the property list and flags already defined by the system itself. They
generate and track the {\em addtional properties and flags} that the user
issues using them. They offer him
the  possibility to work on property lists so
that he can design a programming style of the ``conceptual'' type.
\bi
\item[i.] We first consider ``flags''. \\
To a given identifier, one may
associate another one linked to it ``in the background''. The  three
functions \f{PUTFLAG, DISPLAYFLAG} and \f{CLEARFLAG} handle them.

\f{PUTFLAG} has 3 arguments. The first one is the identifier or a list
of identifiers, the second one is the name of the flag,
and the third one is T (true) or 0 (zero).
When the third argument is T, it creates the flag, when it is 0 it
destroys it. In this last case, the function does return nil (not seen 
inside the algebraic mode).
\begin{verbatim}

        PUTFLAG(z1,flag_name,t); ==> flag_name

        PUTFLAG({z1,z2},flag1_name,t); ==> t

        PUTFLAG(z2,flag1_name,0) ==>

\end{verbatim}
\f{DISPLAYFLAG} allows one to extract flags. The previous actions give:
\begin{verbatim}

        DISPLAYFLAG z1; ==>{flag_name,flag1_name}

        DISPLAYFLAG z2 ; ==> {}

\end{verbatim}
\f{CLEARFLAG} is a command which clears {\em all} flags associated with
the identifiers $id_1, \ldots , id_n .$
\item[ii.] Properties are handled by similar functions.
\f{PUTPROP} has four arguments. The second argument is, here, the
{\em indicator} of the property. The third argument may be {\em any
valid expression}. The fourth one is also T or 0.
\begin{verbatim}

        PUTPROP(z1,property,x^2,t); ==> z1

\end{verbatim}
In general, one enters
\begin{verbatim}

        PUTPROP(LIST(idp1,idp2,..),<propname>,<value>,T);

\end{verbatim}
To display a specific property, one uses
\f{DISPLAYPROP} which takes two arguments. The first is the name of the
identifier, the second is the indicator of the property.
\begin{verbatim}

                                                 2
        DISPLAYPROP(z1,property); ==> {property,x  }

\end{verbatim}
Finally, \f{CLEARPROP} is a nary commmand which clears {\em all}
properties of the identifiers which appear as arguments.
\ei
\section{Control Functions}
Here we describe additional functions which
improve user control on the environment.
\bi
\item[i.]
The first set of functions is composed of unary and binary boolean functions.
They are:
\begin{verbatim}

        ALATOMP x;    x is anything.
        ALKERNP x;    x is anything.
        DEPVARP(x,v); x is anything.

           (v is an atom or a kernel)

\end{verbatim}
\f{ALATOMP} has the value T iff x is an integer or  an identifier
{\em after} it has been evaluated down to the bottom.

\f{ALKERNP} has the value T iff x is a kernel {\em after}
it has been evaluated down to the bottom.

\f{DEPVARP} returns T iff the expression x depends on v at
{\bf any level}.

The above functions together with \f{PRECP} have
 been declared operator functions to ease the verification of
their value.

\f{NORDP} is equal to \verb+NOT+\f{ ORDP}.
\item[ii.]
The next functions allow one to {\em analyze} and to
{\em clean} the environment
of \REDUCE\ created by the user while working
{\bf interactively}. Two functions are provided:\\
\f{SHOW} allows the user to get the various identifiers already
assigned and to see their type. \f{SUPPRESS} selectively clears the
used identifiers or clears them all. It is to be stressed that identifiers
assigned from the input of files are {\bf ignored}.
Both functions have one argument and the same options for this
argument:
\begin{verbatim}

       SHOW (SUPPRESS) all
       SHOW (SUPPRESS) scalars
       SHOW (SUPPRESS) lists
       SHOW (SUPPRESS) saveids    (for saved expressions)
       SHOW (SUPPRESS) matrices
       SHOW (SUPPRESS) arrays
       SHOW (SUPPRESS) vectors
                    (contains vector, index and tvector)
       SHOW (SUPPRESS) forms

\end{verbatim}
The option \verb+all+ is the most convenient for \f{SHOW} but,
with it, it may
takes some time to get the answer after one has worked several hours.
When entering \REDUCE\ the option \verb+all+ for \f{SHOW} gives:
\begin{verbatim}

        SHOW all; ==>

                scalars are: NIL
                arrays are: NIL
                lists are: NIL
                matrices are: NIL
                vectors are: NIL
                forms are: NIL

\end{verbatim}
It is a convenient way to remind the various options. Here is an example
which is valid when one starts from a fresh environment:
\begin{verbatim}

        a:=b:=1$

        SHOW scalars; ==>  scalars are: (A B)

        SUPPRESS scalars; ==> t

        SHOW scalars; ==>  scalars are: NIL

\end{verbatim}
\item[iii.]
The \f{CLEAR} function of the system does not do a complete cleaning of
\verb+OPERATORS+ and \verb+FUNCTIONS+ . The following two functions do a more


complete cleaning and, also, automatically takes into account the
{\em user} flag and properties that the functions
\f{PUTFLAG} and \f{PUTPROP} may have introduced.


Their names are \f{CLEAROP} and \f{CLEARFUNCTIONS}.
\f{CLEAROP} takes one operator as its argument.\\
 \f{CLEARFUNCTIONS} is a nary command. If one issues


\begin{verbatim}


        CLEARFUNCTIONS a1,a2, ... , an $

\end{verbatim}
The functions with names \verb+ a1,a2, ... ,an+  are cleared.
One should be careful when  using this facility since the
only functions which cannot be erased are those which are
protected with the \verb+lose+ flag.
\ei
\section{Handling of Polynomials}
The module contains some utility functions to handle
standard quotients and several new facilities to manipulate polynomials.
\bi
\item[i.] Two functions \f{ALG\_TO\_SYMB} and \f{SYMB\_TO\_ALG}
allow one to change an expression which is in the algebraic standard
quotient form into a prefix lisp form and vice-versa. This is done
in such a way that the symbol \verb+list+ which appears in the
algebraic mode disappears in the symbolic form (there it becomes
a parenthesis ``()'' ) and it is reintroduced in the translation
from a symbolic prefix lisp expression  to an algebraic one.
Here, is an example, showing how the wellknown lisp function
\f{FLATTENS} can be trivially transposed inside the algebraic mode:
\begin{verbatim}

     algebraic procedure ecrase x;
     lisp symb_to_alg flattens1 alg_to_symb algebraic x;

      symbolic procedure flattens1 x;
      % ll; ==> ((A B) ((C D) E))
      % flattens1 ll; (A B C D E)
        if atom x then list x else
        if cdr x then
            append(flattens1 car x, flattens1 cdr x)
          else flattens1 car x;

\end{verbatim}


gives, for instance,
\begin{verbatim}

        ll:={a,{b,{c},d,e},{{{z}}}}$


        ECRASE ll; ==> {A, B, C, D, E, Z}



\end{verbatim}
The function \f{MKDEPTH\_ONE} described above implements that functionality.
\item[ii.]
\f{LEADTERM} and \f{REDEXPR} are the algebraic equivalent of the
symbolic functions \f{LT} and \f{RED}. They give, respectively, the
{\em leading term} and the {\em reductum} of a polynomial. They also work
for rational functions. Their interest lies in the fact that they do not
@@require one to extract the main variable. They work according to the current
ordering of the system:
\begin{verbatim}

        pol:=x++y+z$

        LEADTERM pol; ==> x

        korder y,x,z;

        LEADTERM pol; ==> y

        REDEXPR pol; ==> x + z

\end{verbatim}
By default, the representation of multivariate polynomials is recursive.
It is justified since it is the one which takes the least memory.
With such a representation, the function \f{LEADTERM} does not necessarily
extract a true monom. It extracts a monom in the leading indeterminate
multiplied by a polynomial in the other indeterminates. However, very often,
 one needs to handle true monoms separately. In that case, one needs a
polynomial in {\em distributive} form. Such a form is provided by the
package GROEBNER (H. Melenk et al.). The facility there is, however,
much too involved in many applications and the necessity to load the package 
makes it interesting
to construct an elementary facility to handle the distributive representation 
of polynomials. A new switch has been created for that purpose.
It is called {\tt DISTRIBUTE} and a new function \f{DISTRIBUTE} puts a
polynomial in distributive form. With that switch set to {\bf on},
\f{LEADTERM} gives {\bf true} monoms.

\f{MONOM} transforms a polynomial into a list of monoms. It works
{\em whatever the position of the switch} {\tt DISTRIBUTE}.

\f{SPLITTERMS} is analoguous to \f{MONOM} except that it gives
a list of two lists. The first sublist contains the positive terms
while the second sublist contains the negative terms.

\f{SPLITPLUSMINUS}  gives a list whose first element is the positive
part of the polynomial and its second element is its negative part.
\item[iii.]
Two complementary functions \f{LOWESTDEG} and \f{DIVPOL} are provided.
The first takes a polynomial as its first argument and the name of an
indeterminate as its second argument. It returns the {\em lowest degree}
 in that indeterminate. The second function takes two polynomials and
returns both the quotient and its remainder.
\ei
\section{Handling of Transcendental Functions}
%\item[i.]
The functions \f{TRIGREDUCE} and \f{TRIGEXPAND} and the equivalent
@@ones for hyperbolic functions \f{HYPREDUCE} and \f{HYPEXPAND}
make the transformations to multiple arguments and from
@@multiple arguments to elementary arguments. Here is a simple example:
\begin{verbatim}

        aa:=sin(x+y)$

        TRIGEXPAND aa; ==> SIN(X)*COS(Y) + SIN(Y)*COS(X)

        TRIGREDUCE ws; ==> SIN(Y + X)

\end{verbatim}
When a trigonometric or hyperbolic expression is symmetric with
respect to the interchange of {\tt SIN (SINH)} and {\tt COS (COSH)},
the application of\nl \f{TRIG(HYP)-REDUCE} may often lead to great
simplifications. However, if it is highly assymetric, the repeated
application of \f{TRIG(HYP)-REDUCE} followed by the use of
\f{TRIG(HYP)-EXPAND} will lead to {\em more} complicated
but more symmetric expressions:
\begin{verbatim}

        aa:=(sin(x)^2+cos(x)^2)^3$

        TRIGREDUCE aa; ==> 1

\end{verbatim}
\begin{verbatim}

        bb:=1+sin(x)^3$



        TRIGREDUCE bb; ==>

                - SIN(3*X) + 3*SIN(X) + 4
               ---------------------------
                           4

         TRIGEXPAND ws; ==>


                3                  2
          SIN(X)  - 3*SIN(X)*COS(X)  + 3*SIN(X) + 4
          -------------------------------------------
                             4

\end{verbatim}
%\ei
%\section{Coercion from lists to arrays and converse}
%Sometimes when a list  is very long and,
% especially if frequent access to its elements are needed,
%it is advantageous to (temporarily) transform it into an array.\nl
%\f{LIST\_TO\_ARRAY} has three arguments. The first is the list. The
%second is an integer which indicates the array dimension required. The
%third is the name of an identifier which will play the role of the array
%name generated by it. If the chosen dimension is not compatible with the
% the list depth, an error message is issued.  
%\f{ARRAY\_TO\_LIST} does the opposite coercion. It takes the array
%name as its unique argument.
\section{Handling of n--dimensional Vectors}
Explicit vectors in {\tt EUCLIDEAN} space may be represented by
list-like or bag-like objects of depth 1.
The components may be bags but may {\bf not} be lists.
Functions are provided to do the sum, the difference and the
@@scalar product. When the space-dimension is three there are also functions
for the cross and mixed products.
\f{SUMVECT, MINVECT, SCALVECT, CROSSVECT} have two arguments.
\f{MPVECT} has three arguments. The following example
is sufficient to explain how they work:
\begin{verbatim}

       l:={1,2,3}$

       ll:=list(a,b,c)$

       SUMVECT(l,ll); ==> {A + 1,B + 2,C + 3}

       MINVECT(l,ll); ==> { - A + 1, - B + 2, - C + 3}

       SCALVECT(l,ll); ==> A + 2*B + 3*C

       CROSSVECT(l,ll); ==> { - 3*B + 2*C,3*A - C, - 2*A + B}

       MPVECT(l,ll,l); ==> 0

\end{verbatim}
\section{Handling of Grassmann Operators}
Grassman variables are often used in physics. For them the multiplication
operation is associative, distributive but anticommutative. The
{\tt KERNEL} of \REDUCE\ does not provide it. However, implementing
it in full generality would almost
certainly decrease the overall efficiency of the system. This small
module together with the declaration of antisymmetry for operators is
enough to deal with most calculations. The reason is, that a
product of similar anticommuting kernels can easily  be transformed
into an antisymmetric operator with as many indices as the number of
these kernels. Moreover, one may also issue pattern matching rules
to implement the anticommutativity of the product.
The functions in this module represent the minimum functionality
required to identify them and to handle their specific features.

\f{PUTGRASS} is a (nary) command which give identifiers the property
@@of being the names of Grassmann kernels. \f{REMGRASS} removes this property.

\f{GRASSP} is a boolean function which detects grassmann kernels.

\f{GRASSPARITY} takes a {\bf monom}  as argument and gives its parity.
If the monom is a simple grassmann kernel it returns 1.

\f{GHOSTFACTOR} has two arguments. Each one is a monom. It is equal to
\begin{verbatim}

        (-1)**(GRASSPARITY u * GRASSPARITY v)

\end{verbatim}
Here is an illustration to show how the above functions work:
\begin{verbatim}

        PUTGRASS eta; ==> t

        if GRASSP eta(1) then "grassmann kernel"; ==>

                        grassmann kernel

        aa:=eta(1)*eta(2)-eta(2)*eta(1); ==>

                AA :=  - ETA(2)*ETA(1) + ETA(1)*ETA(2)

        GRASSPARITY eta(1); ==> 1

        GRASSPARITY (eta(1)*eta(2)); ==> 0

        GHOSTFACTOR(eta(1),eta(2)); ==> -1

        grasskernel:=
          {eta(~x)*eta(~y) => -eta y * eta x when nordp(x,y),
          (~x)*(~x) => 0 when grassp x};

        exp:=eta(1)^2$

        exp where grasskernel; ==> 0

        aa where grasskernel; ==>  - 2*ETA(2)*ETA(1)

\end{verbatim}
\section{Handling of Matrices}
This module provides functions for handling matrices more comfortably.
\bi
\item[i.]
Often, one needs to construct some {\tt UNIT} matrix of
a given dimension. This construction is done by the system thanks
@@to the function \f{UNITMAT}. It is a nary function. The command is
\begin{verbatim}

        UNITMAT M1(n1), M2(n2), .....Mi(ni) ;

\end{verbatim}
where \verb+M1,...Mi+ are names of matrices and
\verb+ n1, n2, ..., ni+ are integers .

@@\f{MKIDM} is a generalization of \f{MKID}. It allows one to connect
two or several matrices. If \verb+u+ and \verb+u1+ are two matrices,
one can go from one to the other:
\begin{verbatim}

        matrix u(2,2);$  unitmat u1(2)$

        u1; ==>

                [1  0]
                [    ]
                [0  1]


        mkidm(u,1); ==>

                [1  0]
                [    ]
                [0  1]

\end{verbatim}
@@This function allows one to make loops on matrices like in the following
illustration. If \verb+U, U1, U2,.., U5+ are matrices:
\begin{verbatim}

        FOR I:=1:5 DO U:=U-MKIDM(U,I);

\end{verbatim}
can be issued.
\item[ii.]
The next functions map matrices on bag-like or list-like objects
and conversely  they generate matrices from bags or lists.

\f{COERCEMAT} transforms the matrix \verb+U+ into a list of lists.
The entry is
\begin{verbatim}

        COERCEMAT(U,id)

\end{verbatim}
where \verb+id+ is equal to \verb+list+ othewise it transforms it into
a bag of bags whose envelope is equal to \verb+id+.

\f{BAGLMAT} does the opposite job. The {\bf first} argument is the
bag-like or list-like object while the second argument is the matrix
identifier. The entry is
\begin{verbatim}

         BAGLMAT(bgl,U)

\end{verbatim}
\verb+bgl+ becomes the matrix \verb+U+ . The transformation is
{\bf not} done if \verb+U+  is {\em already} the  name of a
previously  defined matrix. This is to avoid ACCIDENTAL redefinition
of that matrix.
\item[ii.]
The functions \f{SUBMAT, MATEXTR, MATEXTC} take parts of a given matrix.

\f{SUBMAT} has three arguments. The entry is
\begin{verbatim}

         SUBMAT(U,nr,nc)

\end{verbatim}
The first is the matrix name, and the other two are the row  and column
@@numbers.  It gives the
@@submatrix obtained from \verb+U+ by deleting the row \verb+nr+ and
the column \verb+nc+.
When one of them is equal to zero only column \verb+nc+
or row \verb+nr+ is deleted.

\f{MATEXTR} and \f{MATEXTC} extract a row or a column and place it into
a list-like or bag-like object.
@@The entries are
\begin{verbatim}

        MATEXTR(U,VN,nr)

        MATEXTC(U,VN,nc)

\end{verbatim}
where \verb+U+ is the matrix,  \verb+VN+ is the ``vector name'',
\verb+nr+  and \verb+nc+ are integers.  If \verb+VN+  is equal
to {\tt list} the vector  is given  as a list otherwise  it is
given as a bag.
\item[iii.]
Functions which manipulate matrices. They are
\f{MATSUBR, MATSUBC, HCONCMAT, VCONCMAT, TPMAT, HERMAT}

\f{MATSUBR MATSUBC} substitute rows and columns. They have three arguments.
Entries are:
\begin{verbatim}

        MATSUBR(U,bgl,nr)

        MATSUBC(U,bgl,nc)

\end{verbatim}
The meaning of the variables \verb+U, nr, nc+ is the same as above
while \verb+bgl+ is a list-like or bag-like vector.
Its  length should be compatible with the dimensions of the matrix.

\f{HCONCMAT VCONCMAT} concatenate two matrices. The entries are
\begin{verbatim}

        HCONCMAT(U,V)

        VCONCMAT(U,V)

\end{verbatim}
The  first   function  concatenates  horizontally,   the   second  one
concatenates vertically. The dimensions must match.

\f{TPMAT} makes the tensor product of two matrices. It is also an
{\em infix} function. The entry is
\begin{verbatim}

        TPMAT(U,V) or U TPMAT V

\end{verbatim}
\f{HERMAT} takes the hermitian conjuguate of a matrix
The entry is
\begin{verbatim}

         HERMAT(U,HU)

\end{verbatim}
where \verb+HU+ is the identifier for the hermitian matrix of \verb+U+.
@@It should be {\bf unassigned} for this function to work  successfully.
This is done on  purpose to prevent accidental redefinition of an already
used identifier .
\item[iv.]
\f{SETELMAT GETELMAT} are functions of two integers. The first one
@@resets the element \verb+(i,j)+ while the second one extracts an
element identified by \verb+(i,j)+. They may be useful when
dealing with matrices {\em inside procedures}.
\ei
\end{document}