Artifact e1da7fcd5a83e64b35d31f420b2b94212addefc88939bf3414d3d7f2e3c2eafd:
- Executable file
r36/doc/ASSIST.TEX
— part of check-in
[f2fda60abd]
at
2011-09-02 18:13:33
on branch master
— Some historical releases purely for archival purposes
git-svn-id: https://svn.code.sf.net/p/reduce-algebra/code/trunk/historical@1375 2bfe0521-f11c-4a00-b80e-6202646ff360 (user: arthurcnorman@users.sourceforge.net, size: 48745) [annotate] [blame] [check-ins using] [more...]
\documentstyle[11pt,reduce]{article} \newcommand{\nl}{\hfill\newline} \newcommand{\bq}{\begin{quotation}} \newcommand{\eq}{\end{quotation}} \newcommand{\bi}{\begin{itemize}} \newcommand{\ei}{\end{itemize}} \date{} \title{{\bf ASSIST}\ :\\[2pt] A General Purpose Facility~for~\REDUCE \\[5pt] \mbox{\hfill Version 2.2\hfil}} \author{Hubert Caprasse \\ D\'epartement d'Astronomie et d'Astrophysique \\ Institut de Physique, B--5, Sart Tilman \\ B--4000 LIEGE 1 Belgium\\[3pt] E--mail: caprasse@vm1.ulg.ac.be} \begin{document} \maketitle \index{ASSIST package} \section{Introduction} ASSIST contains an appreciable number of additional general purpose functions which allow to better adapt \REDUCE\ to various calculational strategies, to make the programming task more straightforward and more efficient. Contrary to all other packages, ASSIST does not aim to provide neither a new facility to compute a definite class of mathematical objects nor 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 doing specific applications of \REDUCE\ to problems in theoretical physics. Most 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 meaaning and the use of the supplementary functions available in the algebraic mode. These comments, hopefully, makes 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 in the MS-DOS\ and Windows environments. It is made independent of the help facility of \REDUCE\ itself. It includes only one function: \f{HELPASSIST} which takes one argument. \begin{itemize} \item[i.] The argument is the identifier \f{assist}. Then the function gives the informations necessary to retrieve the names of the functions. \item[ii.] The argument is an integer equal to one of the section number of the present documentation. Then the names of the functions described in that section are obtained.\nl There is, presently, no way to retrieve the number and the nature of the arguments. \end{itemize} The package contains several modules. Their content reflects closely the various categories of facilities quoted 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 FREQUENCY SEQUENCES \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 POSITION \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 COMBNUM COMBINATIONS \\ SYMMETRIZE REMSYM SORTNUMLIST SORTLIST ALGSORT \\ EXTREMUM DEPATOM FUNCVAR IMPLICIT EXPLICIT \\ KORDERLIST 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} \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} \end{quotation} \end{itemize} In the following each group of functions is, successively, 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 often used switches when manipulating rational functions. The chosen switches are \begin{quotation} \noindent {\tt EXP, DIV, MCD, GCD, ALLFAC, INTSTR,\\ RAT, RATIONAL, FACTOR } \end{quotation} The switch {\tt DISTRIBUTE} which controls the handling of distributed polynomials is added to them (see below the description of the new functions for manipulating polynomials ). The selection is somewhat arbitrary but it may be changed in a trivial fashion by the user. 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 (almost) {\em all} switches in the status they have when {\bf entering} into \REDUCE\ . The new switch {\tt DISTRIBUTE} allows to put polynomials in a distributed form. \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 the algebraic and symbolic modes. Here is an example: \begin{verbatim} SEQUENCES 2 ; ==> {{0,0},{0,1},{1,0},{1,1}} \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, the third eliminates from a given list {\em all} elements equal to its first argument. The fourth act on 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 to insert a given object into a list at the wanted position. The functions \f{INSERT\_KEEP\_ORDER} and \f{MERGE\_LIST} allow 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} \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 \f{ CONS (.), POSITION, DEPTH, PAIR, \\ APPENDN, REPFIRST, REPLAST} \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. Be careful, 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 packge. \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. 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. \\ \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 tho 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 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 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.\\ 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 substitute, the second is the object which must be replaced by the first, the third is a list. 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 to manipulate 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 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 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}} \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} 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. Analoguously, 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.] Almost all functions defined above for lists do also work for bags. Moreover, functions subsequently defined for SETS do also work. Here is a list of the main ones: \begin{quotation} \f{FIRST, SECOND, LAST, REST, BELAST, DEPTH,\\ LENGTH, APPEND, CONS (.), REPFIRST, REPREST} $\ldots$ \end{quotation} However, because of the conservation of the envelope, they act somewhat differently. 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) 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. \vspace{5pt} \begin{center} The NAME of the ENVELOPE is KEPT by the functions \\[3pt] \f{FIRST, SECOND, LAST, BELAST }. \end{center} \vspace{5pt} \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}. 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, 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 do exist on the level of the symbolic mode. The package make them available in the algebraic mode but also {\em generalizes} them so that they can be applied on 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,a1}); ==> {1,a} MKSET bag(1,a,a1); ==> 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 under 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} 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}, extracts the last digit from an identifier. It is a very 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} 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 to format an 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 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. It is also the length of the list which is generated. \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 floating point 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 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} gives the number of combinations of $n$ objects taken $p$ to $p$. It has the two integer arguments $n$ and $p$. \f{PERMUTATIONS} gives the list of permutations on $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{COMBINATIONS} gives a list of combinations on $n$ objects taken $p$ to $p$. 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 erases the \REDUCE\ commands \verb+symmetric+ or \verb+antisymmetric+ . \f{SYMMETRIZE} is a powerful function which generate a symmetric expression. It has 3 arguments. The first is a list (or a list of list) 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. Here are two 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 list 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 maching is made on the operator \verb+OP+, it needs to be reevaluated. This peculiarity is induced by the need to maximize efficiency when \verb+OP+ is an abstract operator. 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} and \f{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 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 is not necessary 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} One must know that using these functions for kernels or bags may be dangerous since they are destructive. If it is needed, it is recommended to first apply \f{KERNLIST} on them. The function \f{EXTREMUM} is a generalization of the already defined functions \f{MIN, 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} 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 on which it depends as declared in various {\tt DEPEND} declarations. \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 show 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 does not know the names of the variables and (or) the nature of the dependencies. \f{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.] The function \f{REVAL} which takes an arbitrary expression is available which {\em forces} down-to-the-botttom simplification of an expression. It is useful with \f{SYMMETRIZE}.\nl Here is an example: \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) REVAL ws; ==> op(y,z,x)+op(z,x,y)+x*y*z \end{verbatim} \item[v.] Filtering functions for lists. \f{CHECKPROLIST} 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} l:={1,a,b,"st")$ EXTRACTLIST(l,fixp); ==> {1} EXTRACTLIST(l,stringp); ==> {st} \end{verbatim} \ei \section{Properties and Flags} In spite of the fact that many facets of the handling of property lists is easily accessible in the 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 additional 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 associates 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 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. 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 to 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 can be T or 0. If it is 0, the property is removed. \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} 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 the 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 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 analyze} and to {\em clean} the environment of \REDUCE\ which is created by the user while he is working {\bf interactively}. Two functions are provided:\\ \f{SHOW} allows 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 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. Here 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, takes automatically 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 to change 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. 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} \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 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 of 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 and the necessity to load the package makes interesting quite complicated, so it makes sense to have an elementary facility for writing polynomials in a distributive form. So, a new switch is created to handle {\em distributed} polynomials. It is called {\tt DISTRIBUTE} and a new function \f{DISTRIBUTE} puts a polynomial in distributive form. With the switch put 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 analogous 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, 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 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 \end{verbatim} \pagebreak \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 list depth and structure an error message is issued.\nl \f{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, 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 to be 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 to create a matrix name from an identifier and a number. For example, 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 as in the following. 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+ otherwise 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+ 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 entry 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 conjugate 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 {\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 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}. \ei %\input assist1 %\input assist2 %\input assist3 %\input assist4 %\input assist5 %\input assist6 %\input assist7 %\input assist8 \end{document}