% Reference Card for Liverpool Sort Program
%**start of header
\newcount\columnsperpage
 
% This file can be printed with 1, 2, or 3 columns per page (see below).
% Specify how many you want here.  Nothing else needs to be changed.
 
\columnsperpage=3
 
% This file is intended to be processed by plain TeX (TeX82).
%
% The final reference card has six columns, three on each side.
% This file can be used to produce it in any of three ways:
% 1 column per page
%    produces six separate pages, each of which needs to be reduced to 80%.
%    This gives the best resolution.
% 2 columns per page
%    produces three already-reduced pages.
%    You will still need to cut and paste.
% 3 columns per page
%    produces two pages which must be printed sideways to make a
%    ready-to-use 8.5 x 11 inch reference card.
%    For this you need a dvi device driver that can print sideways.
% Which mode to use is controlled by setting \columnsperpage above.
%
 
\def\versionnumber{2.0}
\def\year{1991}
\def\version{April \year\ v\versionnumber}
 
\def\shortcopyrightnotice{\vskip 1ex plus 2 fill
  \centerline{\small \copyright\ \year\ Liverpool Nuclear Structure Group
    v\versionnumber}}
 
\def\copyrightnotice{
\vskip 1ex plus 2 fill\begingroup\small
\centerline{Produced by Janet Sampson and John Cresswell, \version}
\centerline{Contact SAMPSON or CRESSWELL @ UK.AC.LIV.PH.GB}
 
Permission is granted to make and distribute copies of
this card as long as its contents are not altered.
 
\centerline{For copies of the Liverpool Sort Program User Manual ...}
\centerline{extract document EDOC033 from the NSF document server.}
 
\endgroup}
 
% make \bye not \outer so that the \def\bye in the \else clause below
% can be scanned without complaint.
\def\bye{\par\vfill\supereject\end}
 
\newdimen\intercolumnskip
\newbox\columna
\newbox\columnb
 
\def\ncolumns{\the\columnsperpage}
 
\message{[\ncolumns\space 
  column\if 1\ncolumns\else s\fi\space per page]}
 
\def\scaledmag#1{ scaled \magstep #1}
 
% This multi-way format was designed by Stephen Gildea
% October 1986.
\if 1\ncolumns
  \hsize 4in
  \vsize 10in
  \voffset -.7in
  \font\titlefont=\fontname\tenbf \scaledmag3
  \font\headingfont=\fontname\tenbf \scaledmag2
  \font\smallfont=\fontname\sevenrm
  \font\smallsy=\fontname\sevensy
 
  \footline{\hss\folio}
  \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}}
\else
  \hsize 3.2in
  \vsize 7.70in
  \hoffset -.75in
  \voffset -.745in
  \font\titlefont=cmbx10 \scaledmag2
  \font\headingfont=cmbx10 \scaledmag1
  \font\smallfont=cmr6
  \font\smallsy=cmsy6
  \font\eightrm=cmr8
  \font\eightbf=cmbx8
  \font\eightit=cmti8
  \font\eighttt=cmtt8
  \font\eightsy=cmsy8
  \textfont0=\eightrm
  \textfont2=\eightsy
  \def\rm{\eightrm}
  \def\bf{\eightbf}
  \def\it{\eightit}
  \def\tt{\eighttt}
  \normalbaselineskip=.8\normalbaselineskip
  \normallineskip=.8\normallineskip
  \normallineskiplimit=.8\normallineskiplimit
  \normalbaselines\rm		%make definitions take effect
 
  \if 2\ncolumns
    \let\maxcolumn=b
    \footline{\hss\rm\folio\hss}
    \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}}
  \else \if 3\ncolumns
    \let\maxcolumn=c
    \nopagenumbers
  \else
    \errhelp{You must set \columnsperpage equal to 1, 2, or 3.}
    \errmessage{Illegal number of columns per page}
  \fi\fi
 
  \intercolumnskip=.46in
  \def\abc{a}
  \output={%
      % This next line is useful when designing the layout.
      %\immediate\write16{Column \folio\abc\space starts with \firstmark}
      \if \maxcolumn\abc \multicolumnformat \global\def\abc{a}
      \else\if a\abc
	\global\setbox\columna\columnbox \global\def\abc{b}
        %% in case we never use \columnb (two-column mode)
        \global\setbox\columnb\hbox to -\intercolumnskip{}
      \else
	\global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi}
  \def\multicolumnformat{\shipout\vbox{\makeheadline
      \hbox{\box\columna\hskip\intercolumnskip
        \box\columnb\hskip\intercolumnskip\columnbox}
      \makefootline}\advancepageno}
  \def\columnbox{\leftline{\pagebody}}
 
  \def\bye{\par\vfill\supereject
    \if a\abc \else\null\vfill\eject\fi
    \if a\abc \else\null\vfill\eject\fi
    \end}  
\fi
 
% we won't be using math mode much, so redefine some of the characters
% we might want to talk about
\catcode`\^=12
\catcode`\_=12
 
\chardef\\=`\\
\chardef\{=`\{
\chardef\}=`\}
 
\hyphenation{mini-buf-fer}
 
\parindent 0pt
\parskip 1ex plus .5ex minus .5ex
 
\def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip}
 
\outer\def\newcolumn{\vfill\eject}
 
\outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex}
 
\outer\def\section#1{\par\filbreak
  \vskip 3ex plus 2ex minus 2ex {\headingfont #1}\mark{#1}%
  \vskip 2ex plus 1ex minus 1.5ex}
 
\newdimen\keyindent
 
\def\beginindentedkeys{\keyindent=1em}
\def\endindentedkeys{\keyindent=0em}
\endindentedkeys
 
\def\paralign{\vskip\parskip\halign}
 
\def\<#1>{$\langle${\rm #1}$\rangle$}
 
\def\cop#1{$\lbrack\!\lbrack${\rm #1}$\rbrack\!\rbrack$}
 
\def\kbd#1{{\rm#1}\null}	%\null so not an abbrev even if period follows
 
\def\beginexample{\par\leavevmode\begingroup
  \obeylines\obeyspaces\parskip0pt\tt}
{\obeyspaces\global\let =\ }
\def\endexample{\endgroup}
 
\def\key#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.215\hsize\rightskip=1em
  \hskip\keyindent\relax#1}\kbd{#2}\hfil}}
 
\def\kkj#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.30\hsize\rightskip=0em
  \hskip 0em\relax#1}\kbd{#2}\hfil}}
 
\def\kkk#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.35\hsize\rightskip=0em
  \hskip 0em\relax#1}\kbd{#2}\hfil}}
 
\def\kk#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.15\hsize\rightskip=0em
  \hskip 0em\relax#1}\kbd{#2}\hfil}}
 
\def\k#1{\leavevmode\hbox to \hsize{\vtop
  {\rightskip=0em
  \hskip 0em\relax#1}\hfil}}
 
\newbox\metaxbox
\setbox\metaxbox\hbox{\kbd{M-x }}
\newdimen\metaxwidth
\metaxwidth=\wd\metaxbox
 
\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize
  {\hskip\keyindent\relax#1\hfil}%
  \hskip -\metaxwidth minus 1fil
  \kbd{#2}\hfil}}
 
\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\quad
  &\kbd{#3}\quad\cr}
 
%**end of header
 
 
\title{Eurogam Sort Reference Card}
 
\centerline{(for version \versionnumber)}
 
\section{Setting up}
 
There are three steps involved in getting a sort program running.
 
A data file has to be created using any text editor.
The data file has to contain sections as described in File Sections below.
 
Secondly, the complete description file must be passed through
the Sort Compiler, see elsewhere.
 
\section{File Sections}
 
\kkk{{\bf *formats}}{... see Adc Definitions}
\k{$<$adc-definition-statements$>$}
\kkk{\bf *data}{... see Data Definitions}
\k{$<$data-definition-statements$>$}
\kkk{\bf *spectra}{... see Spectrum Definitions}
\k{$<$spectrum-definition-statements$>$}
\kkk{\bf *commands}{... see Command Definitions}
\k{$<$command-statements$>$}
\kkk{\bf *runfiles}{... (Offline only) tape files}
\k{$<$tape-file-definition-statements$>$}
\kkk{\bf *specfiles}{... (Offline only) spectrum files}
\k{$<$spectrum-file-definition-statements$>$}
\kkk{\bf *finish}{... File terminator}
\k{ }
 
Parts of the description may be included from separate files ...
 
\k{ }
\k{{\bf include } $<$filename$>$}
 
\section{Adc Definitions}
 
This is the first and possibly most important section
of information required.
It defines the maximum set of data acquisition parameters
(ADCs, TDCs, etc.) to be expected in each event to be processed.
Each parameter is labelled by an ``address''.
 
\key{ }{ }
\k{{\bf $<$adc-name$>$} $<$address$>$}
\k{{\bf $<$group-name$>$} [ $<$group-range$>$ ]  ( $<$item-list$>$ ) }
\k{ }
 
 
\section{Data Definitions}
 
Definitions of variables used in the commands section.
These variables are accessible interactively during
the running of a sort.
 
\k{ }
\kk{\bf word    }{ \cop{ $<$name$>$ \cop{= $<$integer-value$>$} }r}
\kk{\bf long    }{ \cop{ $<$name$>$ \cop{= $<$integer-value$>$} }r}
\kk{\bf float   }{ \cop{ $<$name$>$ \cop{= $<$floating-point-value$>$} }r}
 
 
\newcolumn
 
\k{{\bf gainword} $<$name$>$  $<$a$>$  $<$b$>$  $<$c$>$}
 
\k{{\bf gainarray} $<$name$>$  $<$n-gains$>$}
\k{\cop{ $<$a$>$  $<$b$>$  $<$c$>$ }r=n-gains}
 
\k{{\bf gatemap mask} $<$name$>$ $<$ngates$>$}
\k{$<$16-bit mask$>$r=ngates}
 
\k{{\bf gatemap 1d} $<$name$>$ [$<$xrange$>$]  $<$ngates$>$}
\k{($<$low-limit$>$ $<$high-limit$>$ )r=ngates}
\k{{\bf gatearray} $<$name$>$  $<$ngates$>$}
\k{($<$low-limit$>$ $<$high-limit$>$ )r=ngates}
 
\k{{\bf gatemap 2d} $<$name$>$ [$<$xrange$>$,$<$yrange$>$] $<$ngates$>$}
\k{($<$xy-coordinate-pairs$>$ )r=ngates}
\k{ }
 
The {\bf valuearray} command allows 1D,2D,or 3D arrays
to be initialised with data provided in a free-format
ordered data-list. 
The ordering is normal Fortran convention of
x moves faster than y,moves faster than z.
 
\k{ }
\k{{\bf valuearray} $<$array-name$>$ $<$xbase$>$ $<$xrange$>$}
\k{\hfill \cop{$<$ybase$>$ $<$yrange$>$  \cop{$ <$zbase$>$ $<$zrange$>$}}}
\k{$<$data-list$>$}
\k{ }
Arrays can be written and read
using Arithmetic Commands.
 
 
\section{Spectrum Definitions}
 
The {\bf *spectra} section defines spectrum names and dimensions etc.
 
\key{ }{ }
\k{$<$spec-name$>$ $<$nchns$>$   \hfill  (1D,16bit)}
\k{$<$spec-name$>$  $<$nchns$>$  {\bf 32}   \hfill  (1D,32bit)}
\k{$<$spec-name$>$  $<$xchns$>$ $<$ychns$>$      \hfill  (2D,16bit)}
\k{$<$spec-name$>$  $<$xchns$>$ $<$ychns$>$ {\bf 32}  \hfill  (2D,32bit)}
\k{$<$spec-name$>$  $<$nchns$>$ {\bf 2D}    \hfill  (2D,16bit)}
\k{$<$spec-name$>$  $<$xchns$>$ $<$ychns$>$ $<$zchns$>$ \hfill  (3D,16bit)}
\k{$<$spec-name$>$  $<$xchns$>$ $<$ychns$>$ $<$zchns$>$ {\bf 32} \hfill  (3D,32bit)}
\k{$<$spec-name$>$  $<$nchns$>$ {\bf 3D}    \hfill  (3D,16bit)}
 
where $<$spec-name$>$ can be array of spectra ... NAME[1:10]
The {\bf 3d} variant is symmetrized (1/6 of cube).
 
\section{Command Definitions}
 
Commands all start on a new line except where indicated.
For example, a simple command following an {\bf if} statement.
 
\k{ }
\k{$<$...-name$>$ ... upto 8 characters (alphanumeric plus \_)}
\k{$<$expr$>$ ... see Arithmetic Commands}
 
\k{$<$parameter$>$ is $<$adc-name$>$ or $<$group$>$.$<$item-name$>$}
\k{$<$sortword$>$ is one of ... word,long,float}
 
\section{Spectrum Access Commands}
 
The 1D,2D,and 3D spectra defined in the {\bf *spectra} section
can be incremented and decremented  using the following commands.
 
\key{ }{ }
\k{{\bf inc}  $<$spec-name$>$ ( $<$xchan$>$ )}
\k{{\bf dec}  $<$spec-name$>$ ( $<$xchan$>$ )}
 
\k{{\bf inc}  $<$spec-name$>$ ( $<$xchan$>$ , $<$ychan$>$ )}
\k{{\bf dec}  $<$spec-name$>$ ( $<$xchan$>$ , $<$ychan$>$ )}
 
\k{{\bf inc}  $<$spec-name$>$ ( $<$xchan$>$ , $<$ychan$>$ , $<$zchan$>$)}
\k{{\bf dec}  $<$spec-name$>$ ( $<$xchan$>$ , $<$ychan$>$ , $<$zchan$>$)}
\k{ }
 
where
$<$xchan$>$,$<$ychan$>$ and $<$zchan$>$ can be either
an $<$expr$>$ or $<$list-name$>$
\k{ }
 
Each of the above spectrum update variants may have an extra
keyword field allowing indexing into an array of spectra.
E.g. typical index could be {\bf \$gate} or {\bf \$groupx}.
 
\k{ }
\k{{\bf inc}  $<$spec-name$>$ ( $<$xchan$>$ ) \  {\bf  indexed } $<$expr$>$}
\k{ }
 
 
The following command increments channel if bit set in word.
 
\k{ }
\k{{\bf incbits} $<$spec-name$>$($<$expr$>$) \ {\bf offset} $<$integer-offset$>$}
\k{ }
 
\section{List Processing Commands}
 
Lists are a useful way of applying commands to a selected set
of similar $<$sortwords$>$. A list must first be created, and then 
used (see spectrum updates, flow control).
 
\k{ }
\k{{\bf createlist } $<$list-name$>$ $<$parameter$>$r}
\k{{\bf createlist } $<$list-name$>$ $<$group.item$>$}
\k{ }
 
Some condition testing commands can generate a revised list
of those items not involved in the current test.
Extract can be used to obtain a fixed number of sortwords from the list.
 
\k{ }
\k{{\bf extract} $<$list-name$>$ $<$word$>$r \ \cop{{\bf ordered$|$reversed}}}
\k{ }
Loopextract loops over command(s) in brackets for every combination
of ``n'' parameters in the list.
 
\k{ }
\k{{\bf loopextract} $<$list-name$>$ $<$word$>$n \ \cop{{\bf ordered$|$reversed}}
}
\k{\ \ $\lbrace$}
\k{\ \ $<$one-or-more-commands$>$}
\k{\ \ $\rbrace$ }
 
 
\section{Flow Control Commands}
 
A series of commands that affect direction of flow.
Various conditions may be applied to data parameters.
In the following list there are,
arithmetic comparisons,1D filter tests,1D veto tests,
1D mask tests and 1D/2D gate list tests.
 
\k{ }
\k{{\bf if} $<$test$>$ $<$statements$>$ \cop{ {\bf else} $<$statements$>$}}
 
\key{where}{ }
\kkk{$<$statements$>$ \hfill =}{\  $<$single-command$>$}
\kkk{\hfill or }{\  $\lbrace$}
\kkk{ }{\  $<$one-or-more-commands$>$}
\kkk{ }{\  $\rbrace$}
 
\key{$<$test$>$ =}{$<$sortword$>$  {\bf valid}}
\key{ }{$<$expr1$>$ {\bf eq$|$ne$|$ge$|$le$|$gt$|$lt} $<$expr2$>$}
\key{ }{$<$expr$>$ {\bf passes} ($<$lolimit$>$ $<$hilimit$>$)}              
\key{ }{$<$expr$>$ {\bf fails} ($<$lolimit$>$ $<$hilimit$>$)}              
\key{ }{$<$expr$>$ {\bf maskedby} $<$16bit-mask$>$}              
\key{ }{$<$expr$>$ {\bf gatedby} $<$1d-gate-record$>$}              
\key{ }{$<$xexpr$>$ $<$yexpr$>$ {\bf gatedby} $<$2d-gate-record$>$}              
 
\k{ }
 
The following is the syntax for word-list tests.
The same set of tests as above apply.
The {\bf loopfail} section is only executed if all tests in the list fail.
 
\k{ }
\k{{\bf loopif}  $<$test$>$ $<$statements$>$ \cop{ {\bf loopfail} $<$statements$>$}}
 
\key{where}{ }
\key{$<$test$>$ =}{$<$list-name$>$  {\bf valid}}
\key{ }{$<$list-name$>$ {\bf eq$|$ne$|$ge$|$le$|$gt$|$lt} $<$expr$>$}
\key{ }{$<$list-name$>$ {\bf passes} ($<$lolimit$>$ $<$hilimit$>$)}
\key{ }{$<$list-name$>$ {\bf passes} $<$gate-array$>$($<$index$>$)}
\key{ }{$<$list-name$>$ {\bf fails} ($<$lolimit$>$ $<$hilimit$>$)}
\key{ }{$<$list-name$>$ {\bf fails} $<$gate-array$>$($<$index$>$)}
\key{ }{$<$list-name$>$ {\bf maskedby} $<$16bit-mask$>$}              
\key{ }{$<$list-name$>$ {\bf gatedby} $<$1d/mask-gate-record$>$}              
\key{ }{$<$xlist$>$ $<$ylist$>$ {\bf gatedby} $<$2d-gate-record$>$}
 
\k{ }
\k{Gate tests set sortword {\bf \$gate} to gate number passed}
\k{All tests set sortword {\bf \$wordx} to current test word from list}
\k{2d gate tests similarly set {\bf \$wordy} }
\k{{\bf \$groupx} and {\bf \$groupy} return group number of current word}
\k{Resultant sub-lists are available in {\bf \$listx} and {\bf \$listy} }
\k{{\bf group(}$<$sortword$>${\bf )} returns group part of address}
\k{{\bf item(}$<$sortword$>${\bf )} returns item part of address}
\k{ } 
 
The following is the syntax for executing different sets of commands
dependent on 1 or 2 values calculated.
 
\k{ }
\k{{\bf select } ($<$expr$>$)}
\k{\cop{($<$value$>$) $<$statements$>$}r}
 
\k{{\bf select } ($<$expr1$>$,$<$expr2$>$)}
\k{\cop{($<$value1$>$,$<$value2$>$) $<$statements$>$}r}
\k{ }
 
To remove whole group from current event ...
 
\k{}
\k{{\bf invalidate} $<$group-name$>$}
 
\newcolumn
To break out of processing current event ...
 
\k{ }
\k{\bf endevent}
\k{ }
 
To directly transfer command execution ...
 
\k{ }
\k{{\bf goto} $<$label-name$>$}
\k{{\bf label} $<$label-name$>$}
\k{ }
 
\section{Looping Command}
 
Equivalent of a do loop. The loop counter is available as sortword {\bf loop}.
 
\k{ }
\k{{\bf doloop from } $<$integer$>$ {\bf to } $<$integer$>$ {\bf step } $<$integer$>$}
\k{\ \ $\lbrace$}
\k{\ \ $<$one-or-more-commands$>$}
\k{\ \ $\rbrace$ }
 
\section{Arithmetic Commands}
 
Expression defaults to integer unless resultant $<$sortword$>$
pre-defined as floating point in {\bf *data} section.
Upto 6 levels of parenthesis are allowed.
Fortran operator precedence.
 
\k{ }
\k{{\bf $<$sortword$>$} = $<$expr$>$}
\k{{\bf $<$array-element$>$} = $<$expr$>$}
 
\k{ }
\kkk{Integer operators:} {\bf $+ - * / < > \&$ ior xor not neg abs}
\kkk{Floating operators:} {\bf $+ - * / **$ neg abs}
\kkk{Floating functions:} {\bf sqrt exp log log10 sin cos tan}
\kkk{}{{\bf asin acos atan}} 
\kkk{Other functions:}{{\bf number}($<$list$>$), {\bf nbit}($<$expr$>$),}
\kk{ }{\hfill $<$array-element$>$,$<$word1$>$:$<$word2$>$}
 
\k{where}
\k{$<$array-element$>$=$<$array-name$>${\bf (}$<$x$>${\bf )}}
\k{$<$array-element$>$=$<$array-name$>${\bf (}$<$x$>$,$<$y$>${\bf)}}
\k{$<$array-element$>$=$<$array-name$>${\bf (}$<$x$>$,$<$y$>$,$<$z$>${\bf)}}
\k{and $<$x$>$,$<$y$>$ and $<$z$>$ are each $<$expr$>$} 
 
The sortword {\bf random} can be used to obtain 
a floating point random number between 0.0 and 1.0
 
\section{Gain Command}
 
A special command that applies a gain adjustment
to the specified parameter
using the function  {\rm $(a+bx+cx^{2})$}.
A {\bf gainword/array} 
must be defined in {\bf *data} section.
 
\k{ }
\k{{\bf gain} $<$sortword$>$ \ $<$gain-record-name$>$} 
\k{{\bf gain} $<$group-name$>$ \ $<$gain-array-name$>$} 
 
\section{Subroutines}
 
Subroutine calls are allowed with upto 8 arguments.
Any command may then be included up the return
command (see below).
 
\k{ }
\kk{{\bf call}}{ $<$routine-name$>$ {\bf (}\cop{$<$arg$>$}r{\bf )}}
\kk{{\bf routine}}{ $<$routine-name$>$ {\bf (}\cop{$<$arg$>$}r{\bf )}}
 
Returns may be controlled by placing one of the 
following commands at the end of the routine.
 
\k{ }
\kkk{\bf end}{returns to command after call}
\kkk{\bf endevent}{terminates processing event}
 
\section{Writing New Events}
 
User specified events may be output using the
following commands.
 
\k{ }
\k{{\bf output} $<$stream-number$>$ {\bf event}}
\k{{\bf output} $<$stream-number$>$ $<$sortword$>$r}
\k{{\bf output} $<$stream-number$>$ $<$list-name$>$r}
 
\section{Writing Sortfiles}
 
An example:
 
\beginexample%
*formats
trigger [255]   (type,mraw)
ge [1:32,34,71] (e1,e2,tac,hit)
*data
gatemap 1d gate1[0,4095] 3
(100 110) (200 210) (300 310) 
include \char'176/gains/current-e1
*spectra
ge1 4096 2d
*commands
if trigger.type ne 1 endevent
gain ge.e1 e1gains
createlist list1 ge.e1
loopif list1 gatedby gate1 \{
  extractall \$listx  a b
    \{
    inc ge1(a,b)
    inc ge1(b,a)
    \}
  \}
*finish
\endexample
 
\vfill
 
\copyrightnotice
 
\bye
 
% End: