\chapter{ASSIST: Various Useful Utilities}
\label{ASSIST}
\typeout{{ASSIST: Various Useful Utilities}}
{\footnotesize
\begin{center}
Hubert Caprasse \\
D\'epartement d'Astronomie et d'Astrophysique \\
Institut de Physique, B--5, Sart Tilman \\
B--4000 LIEGE 1, Belgium\\[0.05in]
e--mail: caprasse@vm1.ulg.ac.be
\end{center}
}
The {\tt ASSIST}\ttindex{ASSIST} package provides a number of general
purpose functions which adapt \REDUCE\ to various
calculational strategies. All the examples in this section require
the {\tt ASSIST} package to be loaded.
\section{Control of Switches}
The two functions \f{SWITCHES, SWITCHORG}
\ttindex{SWITCHES}\ttindex{SWITCHORG} have no argument and are called
as if they were mere identifiers.
\f{SWITCHES} displays the current status of the most often used switches
when manipulating rational functions;
{\tt EXP}, {\tt DIV}, {\tt MCD}, {\tt GCD}, {\tt ALLFAC}, {\tt
INTSTR}, {\tt RAT}, {\tt RATIONAL}, {\tt FACTOR}.
The switch {\tt DISTRIBUTE} which controls the handling
of distributed polynomials is included as well (see section~\ref{DISTRIBUTE}).
\f{SWITCHORG} resets (almost) {\em all} switches in the status they
have when {\bf entering} into \REDUCE. (See also {\tt RESET},
chapter~\ref{RESET}\ttindex{RESET}). The new switch {\tt DISTRIBUTE}
facilitates changing polynomials to a distributed form.
\section{Manipulation of the List Structure}
Functions for list manipulation are provided and are generalised
to deal with the new structure {\tt BAG}.
\begin{itemize}
\item[i.]
Generation of a list of length $n$ with its elements initialised to 0
and also to append to a list $l$ sufficient zeros to
make it of length $n$:\ttindex{MKLIST}
\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 $n-p$ elements equal to $1$.
\begin{verbatim}
SEQUENCES 2; ==> {{0,0},{0,1},{1,0},{1,1}}
\end{verbatim}
The function \f{KERNLIST}\ttindex{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}
There are four functions to delete elements from lists. The
\f{DELETE} function deletes the first occurrence of its first argument
from the second, while \f{REMOVE} removes a numbered element.
\f{DELETE\_ALL} eliminates from a list {\em all} elements equal to its
first argument. \f{DELPAIR} acts on list of pairs and eliminates from
it the {\em first} pair whose first element is equal to its first
argument:\ttindex{DELETE}\ttindex{REMOVE}\ttindex{DELETE\_ALL}\ttindex{DELPAIR}
\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}\ttindex{ELMULT} returns an {\em integer} which is the
{\em multiplicity} of its first argument in the list which is its
second argument.
The function \f{FREQUENCY}\ttindex{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}\ttindex{INSERT} inserts a
given object into a list at the wanted position. The functions
\f{INSERT\_KEEP\_ORDER}\ttindex{INSERT\_KEEP\_ORDER} and
\f{MERGE\_LIST}\ttindex{MERGE\_LIST} 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}
\item[vi.]
Algebraic lists can be read from right to left or left to right.
They {\em look} symmetrical. It is sometimes convenient to have
functions which reflect this. So, as well as \f{FIRST} and \f{REST}
this package provides the functions \f{LAST}\ttindex{LAST} and
\f{BELAST}\ttindex{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:
\f{CONS}, \f{(.)}, \f{POSITION}, \f{DEPTH}, \f{PAIR}, \f{APPENDN},
\f{REPFIRST}, \f{REPLAST}
\ttindex{CONS}\ttindex{.}\ttindex{POSITION}\ttindex{DEPTH}
\ttindex{PAIR}\ttindex{APPENDN}\ttindex{REPLAST}\ttindex{REPLAST}
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 on 4--dimensional vectors, it acts as in the
HEPHYS package (chapter~\ref{HEPHYS}
\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 list is of {\em unequal depth}.
\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.
\f{APPENDN} has {\em any} number of lists as arguments, and appends
them all.
\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.
\f{REPREST} has also two arguments. It replaces the rest of the list
by its first argument and returns the new list without destroying the
original list.
\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}\ttindex{ASFIRST},
\f{ASLAST}\ttindex{ASLAST}, \f{ASREST}\ttindex{ASREST},
\f{ASFLIST}\ttindex{ASFLIST}, \f{ASSLIST}\ttindex{ASSLIST},
and \f{RESTASLIST}\ttindex{RESTASLIST}
act on ALISTS or on list of lists of well defined depths
and have two arguments. The first is the key object
which one seeks to associate in some way to 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 arguments. It
returns the collection of pairs which meet the criterion of \f{ASREST}.
\f{ASFLIST} returns a list containing {\em all pairs} which
satisfy to the criteria of the function \f{ASFIRST}. So the output
is also an ALIST or a list of lists.
\f{ASSLIST} returns a list which contains {\em all pairs} which have
their second element equal to the first argument.
\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}
\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, {\em a priori}, unknown. This structure is
endowed with other properties such as ``mapping'' {\em 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 lists cannot be indeterminates of polynomials. Frequently
procedure arguments cannot be lists.
At the other extreme, so to say, one has the \verb+KERNEL+
structure associated
to 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 to be a \verb+KERNEL+ and,
therefore, may be an indeterminate of a polynomial. From the list structure
it borrows the property to be 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+ composed of an atomic prefix (its
envelope) and
its content (miscellaneous objects).
\item Its content may be changed in an analogous way as the content of a
list. During these manipulations the name of the bag is {\em conserved}.
\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}}
\begin{itemize}
\item[i.] A default bag envelope \verb+BAG+\index{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}\ttindex{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} puts 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\ttindex{CLEARBAG}
\begin{verbatim}
CLEARBAG id1,...idn;
\end{verbatim}
eliminates the bag property on \verb+id1,...,idn+.
\item[ii.] The boolean function \f{BAGP}\ttindex{BAGP} detects the bag
property.
\begin{verbatim}
aa:=bag(x,y,z)$
if BAGP aa then "ok"; ==> ok
\end{verbatim}
\item[iii.] Most functions defined above for lists do also work for
bags.
Moreover functions subsequently defined for SETS (see
section~\ref{A-SETS}) also work.
However, because of the conservation of the envelope, they act
somewhat differently.
\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)
LENGTH aa; ==> 3
DEPTH aa; ==> 1
\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}.
The function \f{LENGTH} gives the actual number of variables on which
the operator (or the function) depends.
The NAME of the ENVELOPE is kept by the functions \f{FIRST},
\f{SECOND}, \f{LAST} and \f{BELAST}.
\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}\ttindex{LISTBAG}. 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.
Finally, two boolean functions which work both for bags and lists are
provided. They are \f{BAGLISTP}\ttindex{BAGLISTP} and
\f{ABAGLISTP}\ttindex{ABAGLISTP}.
They return T or NIL (in a conditional statement) if their argument
is a bag or a list for the first one, 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}
\label{A-SETS}
The ASSIST package makes the Standard LISP set functions available in
algebraic mode and also {\em generalises} them so that they can be
applied on bag--like objects as well.
\begin{itemize}
\item[i.]
The constructor \f{MKSET}\ttindex{MKSET} transforms a list or bag into
a set by eliminating duplicates.
\begin{verbatim}
MKSET({1,a,a1}); ==> {1,a}
MKSET bag(1,a,a1); ==> bag(1,a)
\end{verbatim}
\f{SETP}\ttindex{SETP} is a boolean function which recognises
set--like objects.
\item[ii.]
The standard functions are \f{UNION}\ttindex{UNION},
\f{INTERSECT}\ttindex{INTERSECT}, \f{DIFFSET}\ttindex{DIFFSET}
and \f{SYMDIFF}\ttindex{SYMDIFF}.
They have two arguments which must be sets; otherwise an error message
is issued.
\end{itemize}
\section{General Purpose Utility Functions}
\begin{itemize}
\item[i.]
The functions \f{MKIDNEW}\ttindex{MKIDNEW},
\f{DELLASTDIGIT}\ttindex{DELLASTDIGIT},
\f{DETIDNUM}\ttindex{DETIDNUM},
\f{LIST\_TO\_IDS}\ttindex{LIST\_TO\_IDS}
handle identifiers. \f{MKIDNEW}\ttindex{MKIDNEW} is a variant of \f{MKID}.
\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, it strips it from its last
digit.
\begin{verbatim}
DELLASTDIGIT 45; ==> 4
\end{verbatim}
\f{DETIDNUM}, determines the trailing integer from an identifier. It is
convenient 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} generalises the function \f{MKID} to a list of
atoms. It creates and interns 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}\ttindex{ODDP} detects odd integers.
The function \f{FOLLOWLINE}\ttindex{FOLLOWLINE} is convenient when
using the function \f{PRIN2} for controlling layout.
\begin{verbatim}
<<prin2 2; prin2 5>>$
25
<<prin2 2; followline(3); prin2 5>>$
2
5
\end{verbatim}
The function \f{RANDOMLIST}\ttindex{RANDOMLIST} generates a list of
positive 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.
\begin{verbatim}
RANDOMLIST(10,5); ==> {2,1,3,9,6}
\end{verbatim}
\f{MKRANDTABL}\ttindex{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 floating point number. In this latter case
the switch \f{rounded} must be ON. The function 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 integer random numbers 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 array dimension.
\f{COMBNUM(n,p)}\ttindex{COMBNUM} gives the number of combinations of
$n$ objects taken $p$ at a time. It has the two integer arguments $n$
and $p$.
\f{PERMUTATIONS(n)}\ttindex{PERMUTATIONS} gives the list of permutations
on $n$ objects, each permutation being represented as a list.
\f{CYCLICPERMLIST}\ttindex{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{COMBINATIONS}\ttindex{COMBINATIONS} gives a list of combinations on
$n$ objects taken $p$ at a time. The first argument is a
list (or a bag) and the second is the integer $p$.
\begin{verbatim}
COMBINATIONS({1,2,3},2) ==> {{2,3},{1,3},{1,2}}
\end{verbatim}
\f{REMSYM}\ttindex{REMSYM} is a command that erases the \REDUCE\ commands
{\tt symmetric} or {\tt antisymmetric}.
\f{SYMMETRIZE}\ttindex{SYMMETRIZE} is a powerful function which
generate 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 either exist in the algebraic or in the symbolic mode. This
function may have been constructed by the user. Within this package
the two functions \f{PERMUTATIONS} and \f{CYCLICPERMLIST} may be used.
\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 that, unless a pattern matching is
made on the operator \verb+OP+, it needs to be reevaluated. 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)
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}\ttindex{SORTNUMLIST} and
\f{SORTLIST}\ttindex{SORTLIST} are functions which sort
lists. They use {\em bubblesort} and {\em quicksort} algorithms.
\f{SORTNUMLIST} takes as argument a list of numbers. It sorts it in
increasing order.
\f{SORTLIST} is a generalisation 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
is not necessary numbers but must be such that the ordering function has
a meaning.
\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}
\end{verbatim}
Note: using these functions for kernels or bags may be
dangerous since they are destructive. If it is needed, it is recommended
first to apply \f{KERNLIST} on them.
The function \f{EXTREMUM}\ttindex{EXTREMUM} is a generalisation of the
functions \f{MIN} and \f{MAX} to include general orderings. It is a 2
arguments 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}
\item[iii.] There are four functions to identify dependencies.
\f{FUNCVAR}\ttindex{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}\ttindex{DEPATOM} has an {\bf atom} as argument. It returns
its argument if it is
a number or if no dependency has previously been declared. Otherwise,
it returns the list of variables on which in depends as declared in
various {\tt DEPEND} declarations.
\begin{verbatim}
DEPEND a,x,y;
DEPATOM a; ==> {x,y}
\end{verbatim}
The functions \f{EXPLICIT}\ttindex{EXPLICIT} and
\f{IMPLICIT}\ttindex{IMPLICIT} make explicit or
implicit the dependencies.
\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 does not know the names of the variables
and (or) the nature of the dependencies.
\f{KORDERLIST}\ttindex{KORDERLIST} is a zero argument function which
display the actual ordering.
\begin{verbatim}
KORDER x,y,z;
KORDERLIST; ==> (x,y,z)
\end{verbatim}
\item[iv.] A function \f{SIMPLIFY}\ttindex{SIMPLIFY} which takes an
arbitrary expression
is available which {\em forces} down-to-the-bottom simplification of
an expression. It is useful with \f{SYMMETRIZE}. It has also proved
useful to simplify some output expressions of the package EXCALC
(chapter~\ref{EXCALC}).
\begin{verbatim}
l:=op(x,y,z)$
op(x,y,z):=x*y*z$
SYMMETRIZE(l,op,cyclicpermlist); ==>
op(x,y,z)+op(y,z,x)+op(z,x,y)
SIMPLIFY ws; ==> op(y,z,x)+op(z,x,y)+x*y*z
\end{verbatim}
\item[v.] Filtering functions for lists.
\f{CHECKPROLIST}\ttindex{CHECKPROLIST} is a boolean function which
checks if the elements of a list have a definite property. Its first
argument is the list, and its second argument is a boolean function
(\f{FIXP NUMBERP $\ldots$}) or an ordering function (as \f{ORDP}).
\f{EXTRACTLIST}\ttindex{EXTRACTLIST} extracts from the list given as
its first argument the elements which satisfy the boolean function
given as its second argument.
\begin{verbatim}
l:={1,a,b,"st")$
EXTRACTLIST(l,fixp); ==> {1}
EXTRACTLIST(l,stringp); ==> {st}
\end{verbatim}
\end{itemize}
\section{Properties and Flags}
It may be useful to provide analogous functions in algebraic mode to
the properties and flags of LISP. Just using the symbolic mode
functions to alter 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 additional properties and
flags} that the user issues using them. They offer the possibility of
working on property lists in an algebraic context.
\begin{description}
\item[i. Flags]
To a given identifier, one may
associates another one linked to it ``in the background''. The three
functions \f{PUTFLAG}\ttindex{PUTFLAG},
\f{DISPLAYFLAG}\ttindex{DISPLAYFLAG} and
\f{CLEARFLAG}\ttindex{CLEARFLAG} handle them.
\f{PUTFLAG} has 3 arguments. The first is the identifier or a list
of identifiers, the second is the name of the flag,
the third is T (true) or 0 (zero).
When the third argument is T, it creates the flag, when it is 0 it
destroys it.
\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 to extract flags. Continuing the example:
\begin{verbatim}
DISPLAYFLAG z1; ==> {flag_name,flag1_name}
DISPLAYFLAG z2; ==> {}
\end{verbatim}
\f{CLEARFLAG} is a command which clears {\em all} flags associated to
the identifiers $id_1, \ldots , id_n$.
\item[ii. Properties]
\f{PUTPROP}\ttindex{PUTPROP} has four arguments. The second argument
is 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 enter
\begin{verbatim}
PUTPROP(LIST(idp1,idp2,..),<propname>,<value>,T);
\end{verbatim}
If the last argument is 0 then the property is removed.
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.
\end{description}
\section{Control Functions}
The ASSIST package also provides additional functions which
improve the user control of the environment.
\begin{itemize}
\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}\ttindex{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}\ttindex{ALKERNP} has the value T iff x is a kernel {\em
after} it has been evaluated down to the bottom.
\f{DEPVARP}\ttindex{DEPVARP} returns T iff the expression x depends on
v at {\bf any level}.
The above functions together with \f{PRECP}\ttindex{PRECP} have been
declared operator functions to ease the verification of their value.
\f{NORDP}\ttindex{NORDP} is essentially equivalent to \verb+not+\f{ORDP}
when inside a conditional statement. Otherwise, it can be used
while \verb+not+\f{ORDP} cannot.
\item[ii.]
The next functions allow one to {\em analyse} and to {\em clean} the
environment of \REDUCE\ which is created by the user while
working interactively. Two functions are provided:\\
\f{SHOW}\ttindex{SHOW} allows to get the various identifiers already
assigned and to see their type. \f{SUPPRESS}\ttindex{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 it may
takes 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 remember the various options.
Starting 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}\ttindex{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}\ttindex{CLEAROP} and
\f{CLEARFUNCTIONS}\ttindex{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.
\end{itemize}
\section{Handling of Polynomials}
The module contains some utility functions to handle
standard quotients and several new facilities to manipulate polynomials.
\begin{itemize}
\item[i.] Two functions \f{ALG\_TO\_SYMB}\ttindex{ALG\_TO\_SYMB} and
\f{SYMB\_TO\_ALG}\ttindex{SYMB\_TO\_ALG} allow the changing of an expression
which is in the algebraic standard quotient form into a prefix lisp
form and vice-versa. This is made
in such a way that the symbol \verb+list+ which appears in the
algebraic mode disappear 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.
The following example shows how the well-known lisp function
\f{FLATTENS} can be trivially transportd into 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}
\item[ii.] \f{LEADTERM}\ttindex{LEADTERM} and
\f{REDEXPR}\ttindex{REDEXPR} are the algebraic equivalent of the
symbolic functions \f{LT} and \f{RED}. They give 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 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.
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 (chapter~\ref{GROEBNER}). The facility there may be
too involved and the need to load an additional package can be a
problem. So,
a new switch is created to handle {\em distributed} polynomials. It is
called {\tt DISTRIBUTE}\ttindex{DISTRIBUTE} and a new function
\label{DISTRIBUTE} \f{DISTRIBUTE} puts a polynomial in distributive
form. With the switch {\bf on}, \f{LEADTERM} gives {\bf true} monoms.
\f{MONOM}\ttindex{MONOM} transforms a polynomial into a list of
monoms. It works whatever the setting of the switch {\tt DISTRIBUTE}.
\f{SPLITTERMS}\ttindex{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}\ttindex{SPLITPLUSMINUS} gives a list whose first
element is an expression of the positive part of the polynomial and
its second element is its negative part.
\item[iii.]
Two complementary functions \f{LOWESTDEG}\ttindex{LOWESTDEG} and
\f{DIVPOL}\ttindex{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.
\end{itemize}
\section{Handling of Transcendental Functions}
The functions \f{TRIGREDUCE}\ttindex{TRIGREDUCE} and
\f{TRIGEXPAND}\ttindex{TRIGEXPAND} and the equivalent
ones for hyperbolic functions \f{HYPREDUCE}\ttindex{HYPREDUCE} and
\f{HYPEXPAND}\ttindex{HYPEXPAND}
make the transformations to multiple arguments and from
multiple arguments to elementary arguments.
\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 \f{TRIG(HYP)REDUCE} may often lead to great
simplifications. However, if it is highly asymmetric, 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
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}
See also the TRIGSIMP package (chapter~\ref{TRIGSIMP}).
\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 (temporarily) to
transform it into an array.
\f{LIST\_TO\_ARRAY}\ttindex{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 list depth and structure an error
message is issued. \f{ARRAY\_TO\_LIST}\ttindex{ARRAY\_TO\_LIST} does
the opposite coercion. It takes the array name as its sole 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 space-dimension is three
there are also functions for the cross and mixed products.
\f{SUMVECT}\ttindex{SUMVECT}, \f{MINVECT}\ttindex{MINVECT},
\f{SCALVECT}\ttindex{SCALVECT}, \f{CROSSVECT}\ttindex{CROSSVECT} have
two arguments. \f{MPVECT}\ttindex{MPVECT} has three arguments.
\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}
\index{Grassmann Operators}
Grassman variables are often used in physics. For them the
multiplication operation is associative, distributive but
anticommutative. The basic \REDUCE\ does not provide this.
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}\ttindex{PUTGRASS} is a (nary) command which give
identifiers the property to be the names of Grassmann kernels.
\f{REMGRASS}\ttindex{REMGRASS} removes this property.
\f{GRASSP}\ttindex{GRASSP} is a boolean function which detects
Grassmann kernels.
\f{GRASSPARITY}\ttindex{GRASSPARITY} takes a {\bf monom} as argument
and gives its parity. If the monom is a simple Grassmann kernel it
returns 1.
\f{GHOSTFACTOR}\ttindex{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;
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}
There are additional facilities for matrices.
\begin{itemize}
\item[i.]
Often one needs to construct some {\tt UNIT} matrix of
a given dimension. This construction is performed by the function
\f{UNITMAT}\ttindex{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}\ttindex{MKIDM} is a generalisation of
\f{MKID}\ttindex{MKID}. It allows the indexing of matrix names. 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}
Note: MKIDM(V,1) will fail even if the matrix V1 exists, unless V is
also a matrix.
This function allows to make loops on matrices like the following.
If \verb+U, U1, U2,.., U5+ are matrices:
\begin{verbatim}
FOR I:=1:5 DO U:=U-MKIDM(U,I);
\end{verbatim}
\item[ii.]
The next functions map matrices onto bag-like or list-like objects
and conversely they generate matrices from bags or lists.
\f{COERCEMAT}\ttindex{COERCEMAT} transforms the matrix first argument
into a list of lists.
\begin{verbatim}
COERCEMAT(U,id)
\end{verbatim}
When \verb+id+ is \verb+list+ the matrix is transformed into a list of
lists. Otherwise it transforms it into a bag of bags whose envelope is
equal to \verb+id+.
\f{BAGLMAT}\ttindex{BAGLMAT} does the inverse. The {\bf first}
argument is the bag-like or list-like object while the second argument
is the matrix identifier.
\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, to avoid accidental redefinition
of that matrix.
\item[ii.]
The functions \f{SUBMAT}\ttindex{SUBMAT},
\f{MATEXTR}\ttindex{MATEXTR}, \f{MATEXTC}\ttindex{MATEXTC} take parts
of a given matrix.
\f{SUBMAT} has three arguments.
\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+ 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.
\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: \f{MATSUBR}\ttindex{MATSUBR},
\f{MATSUBC}\ttindex{MATSUBC}, \f{HCONCMAT}\ttindex{HCONCMAT},
\f{VCONCMAT}\ttindex{VCONCMAT}, \f{TPMAT}\ttindex{TPMAT},
\f{HERMAT}\ttindex{HERMAT}.
\f{MATSUBR} and \f{MATSUBC} substitute rows and columns. They have
three arguments.
\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} and \f{VCONCMAT} concatenate two matrices.
\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.
\begin{verbatim}
TPMAT(U,V) or U TPMAT V
\end{verbatim}
\f{HERMAT} takes the hermitian conjugate of a matrix
\begin{verbatim}
HERMAT(U,HU)
\end{verbatim}
where \verb+HU+ is the identifier for the hermitian matrix of
\verb+U+. It should {\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} and \f{GETELMAT} are functions of two integers. The first
one reset the element \verb+(i,j)+ while the second one extract an
element identified by \verb+(i,j)+. They may be useful when
dealing with matrices {\em inside procedures}.
\end{itemize}