Forgot to add spectators.tex

doc/manual/spectators.tex

@@ -0,0 +1,208 @@
+
+\chapter{Spectators}
+\label{spectators}
+
+At times expressions contain many terms that will not be treated for many 
+modules to come. For the actions in those modules they are considered 
+spectator terms. and they may consume much computer time due to their 
+presence during the sorting. For this we have the spectator system in which 
+we can send those terms to a special file, named a spectator file, in such 
+a way that they can be picked up at a convenient time in the future. In 
+short:
+
+\noindent
+Spectators are expressions together with a \index{filename}filename. The 
+file is for storage when the spectator becomes too big. Create a spectator 
+with the statement\index{createspectator}
+
+    CreateSpectator Exprname,"filename";
+
+\noindent
+The file will be made in the same directory where the tmp files are made. 
+Example:
+
+    CreateSpectator Yintegrals,"Yfile.spec";
+
+\noindent
+One may send terms to a spectator with the executable 
+statement\index{tospectator}
+
+    ToSpectator Exprname;
+
+\noindent
+An example would be
+
+    if ( count(Z,1) == 0 ) ToSpectator Yintegrals;
+
+\noindent
+The terms are dumped into the file as they are at the moment the 
+ToSpectator statement is executed. No brackets etc.
+In the future they may be compressed. At the moment they are not.
+
+\noindent
+Recovery of the contents of the spectator is done whith the CopySpectator
+statement as in\index{copyspectator}
+
+    CopySpectator NewExp = Yintegrals;
+
+\noindent
+Cuttently you can only read the spectators this way. You cannot make more 
+complicated constructions. You can only do things with the terms of the 
+spectator expression after the contents have been put in your new 
+expression. The spectator file remains in existence. In later modules you 
+can still add to it. You cannot read from and add to the same spectator in 
+the same module. The CopySpectator command can be followed by executable 
+statements in the same module. This may not be economical because the 
+contents of the spectator have not been sorted. There could be identical 
+terms that occur many times or even cancel. Better sort them first.
+
+\noindent
+A spectator can be removed from the system with the 
+statement\index{removespectator}
+
+\begin{minipage}{10cm}
+    RemoveSpectator Yintegrals;
+\end{minipage}
+
+\noindent
+It is also possible to truncate a spectator down to zero length 
+with\index{emptyspectator}
+
+\begin{minipage}{10cm}
+    EmptySpectator Yintegrals;
+\end{minipage}
+
+\noindent
+You can have as many spectators as you like, but they all have some cache 
+buffers. There may also be limitations in the file system on the maximum 
+number of open files. The filename for the spectator is purely for the sake 
+of the users administration and recognition. You cannot carry the file over 
+to other programs. There is no variable administration in it as in the 
+saved files.
+
+\noindent
+The .global instruction makes a spectator file survive a .store. It is up 
+to the user to make sure that all the variables in it also survive the 
+.store. There is no checking!
+
+\noindent
+One use of the spectator system would be when integrating many different 
+terms by means of a very prolonged recursion system in which integrals of a 
+given complexity are reduced to integrals of lower complexity, but each 
+such reduction may take quite a few steps. One could have:
+
+\begin{minipage}{14cm}
+\#do i = `MAXCOMPLEXITY'-1,0,-1
+
+CreateSpectator complex`i',"complex`i'.spec";
+
+\#enddo
+
+Local F`MAXCOMPLEXITY' = ....;
+
+\#do i = `MAXCOMPLEXITY'-1,1,-1
+
+\ \#do ii = 1,1;
+
+\ \ \ routine for doing a part of the recursion level `i'
+
+\ \ \ \#do j = `i'-1,0,-1
+
+\ \ \ \ \ if ( complexityofterm == `i' ) ToSpectator complex`i';
+
+\ \ \ \#enddo
+
+\ \ if ( notyetfinished ) redefine ii "0";
+
+\ \ .sort
+
+\ \#enddo
+
+\ Drop F{`i'+1};
+
+\ CopySpectator F`i' = complex`i';
+
+\ .sort
+
+\ RemoveSpectator complex`i';
+
+\#enddo
+
+*
+
+*\ \ and finally, assuming that complexity zero means finished:
+
+*
+
+Drop F1;
+
+CopySpectator F0 = complex0;
+
+.sort
+
+RemoveSpectator complex0;
+\end{minipage}
+
+\noindent
+Some remarks are called for here. If one works with the 
+polyratfun\index{polyratfun} concept and the rational 
+polynomials\index{rational polynomials} become rather complicated, the 
+sorting after the CopySpectator statement can have serious bottleneck 
+problems in \index{TFORM}\TFORM{} and \index{ParFORM}\ParFORM{} because the 
+addition of those polynomials can be rather expensive and much of it ends 
+up in the master processor. This can be made better with the following 
+construction (assuming the function rat was declared as polyratfun at the 
+moment of all the ToSpectator statements that wrote to the spectator):
+
+\begin{minipage}{10cm}
+PolyRatFun;
+
+Drop F1;
+
+CopySpactator F0 = complex0;
+
+ABracket+ rat;
+
+.sort
+
+PolyRatFun rat;
+
+RemoveSpectator complex0;
+
+.sort
+\end{minipage}
+
+\noindent
+First we remove the declaration of rat as polyratfun. Then we read the 
+spectator and sort it such that all terms that should be added eventually 
+are grouped together. This sorting is very cheap as only identical terms 
+are combined. Then we declare the polyratfun again and because of the way 
+the terms are sorted nearly all additions take place inside the workers, 
+hence at maximum parallelization efficiency.
+
+\noindent
+The above method still contains one inefficiency: because the polyratfun is 
+declared again, the contents of the rat function need to be 'normalized' 
+again, while they were already normalized. This involves calculating a gcd 
+of the numerator and the denominator, which is an expensive operation 
+and is useless in this case. For this we have a special option in the 
+polyratfun declaration:
+
+\begin{minipage}{10cm}
+   PolyRatFun rat-;
+\end{minipage}
+
+\noindent
+This will skip the normalization on the input of the module. One should 
+note however that if one uses this option under different conditions in 
+which the input rat function might not be normalized, the program might 
+crash or even give wrong answers. Hence this option should only be used 
+with the highest degree of caution! This is an option for very experienced 
+users only. No support is given concerning programs that run correctly 
+without the use of this option and fail when using it.
+
+\noindent
+It should be noted that in the sequential version of \FORM{} this 
+construction is not needed at all, because there is only one processor 
+anyway.
+