|
GSI
FRS
|
|
SATAN Help
LIST-MODE ANALYSIS
==================
List-mode data may be analyzed by use of a user-supplied analysis
routine. This routine consists of two parts, written in a compact
form in one dataset. The user defines his spectra, conditions,
table of list-mode data etc. in the first part, the definition part.
The analysis for every event from the input file is performed in
the second part, the analysis part. Here the input data may be used
for calculations, for setting conditions and for accumulating spectra.
A simple analysis of list-mode data in ASCII format is possible without
the need for compilation and linking due to the pre-defined default
analysis program by the command ANAL.
The programming language is modern VisualAge PL/I.
Example of a user-supplied analysis routine with explanations:
|%INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| /* This dataset contains the macros. */
|
| /* General remarks for syntax and use of macros:
| Macros may be specified with positional and keyword arguments.
| (In "AGEN(X1) LIMITS(1,100)", "X1" is a positional argument,
| "1,100" is a keyword argument with the keyword "LIMITS".)
| Positional arguments must appear in sequence,
| Keyword arguments may appear in any order.
| The macros below may only be used in the analysis procedure! */
|
|
|DEBUG; /* switch for debug mode, */
| /* is useful for testing but reduces the speed. */
| /* Without the DEBUG option, error checking is */
| /* not performed (e.g. writing into analyzers */
| /* which have not been created). */
| /* A new program may first be compiled with */
| /* this option. */
| /* DEBUG should not be used in the production */
| /* phase. */
|
|LISTPROC; /* Begin of analysis program */
|
|
| Syntax of LIST (list character strings and numerical variables)
| Positional arguments: text, numerical variables.
| ==> "LIST('First and second values',R1,R2);"
| lists the given text and the values of R1 and R2.
|
| Syntax of EXCMD (execute a SATAN command)
| One positional argument: command text.
| (command text not in quotation marks!)
| ==> "EXCMD(HALT)" executes the command HALT.
|
| Syntax of AGEN (create an analyzer, 1-dimensional)
| (1-dimensional analyzer, up to 5-dim. arrays allowed)
| 1. argument: analyzer name or array of analyzer names,
| ==> "AGEN(MUSIC)" defines one analyzer,
| ==> "AGEN(ATAR(3))" defines an array of three analyzers,
| ==> "AGEN(Z_RESPONSE(80:92))" defines an array of 13
| analyzers.
| ==> "AGEN(TEST(5:9,27:37))" defines a 2-dim. array of
| analyzers.
| TYPE keyword: FIXED or FLOAT (optional; default = FIXED),
| and PROTECTED (against ACLR)
| ==> "AGEN(TEST) TYPE(FLOAT,PROTECTED)" defines a floating-
| number analyzer which is protected against ACRL.
| LIMITS keyword: list of limits (2 values),
| BINS keyword: binsize (optional; default = 1),
| NCND keyword: number of conditions (optional; default = 0),
| CXAXIS keyword: description of x axis (optional; default =
| Channel),
| CYAXIS keyword: description of y axis (optional; default =
| Counts),
| TITLE keyword: title of analyzer (optional; default =
| analyzer name),
| COMMENT keyword: comment of analyzer (optional; default = '').
| FCAL keyword: calibration factor (default = 1).
| LINESYMBOL keyword: line and symbol (==> LTR11 , default is HT0)
| In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
| element number(s) of an array of analyzers.
|
|
| Syntax of AGEN (create an analyzer, 2-dimensional)
| (2-dimensional analyzer, up to 5-dim. arrays allowed)
| 1. argument: analyzer name or array of analyzer names (see above),
| TYPE keyword: FIXED or FLOAT (optional; default = FIXED),
| and PROTECTED (against ACLR) ==> TYPE(FLOAT,PROTECTED)
| LIMITS keyword: list of limits (4 values),
| BINS keyword: binsizes (optional; default = 1,1),
| NCND keyword: number of conditions (optional; default = 0),
| CXAXIS keyword: description of x axis (optional; default =
| Dimension 1),
| CYAXIS keyword: description of y axis (optional; default =
| Dimension 2),
| TITLE keyword: title of analyzer (optional; default =
| analyzer name),
| COMMENT keyword: comment of analyzer (optional; default = '').
| FCAL keyword: calibration factors.
| In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
| element number(s) of an array of analyzers.
|
|
| Syntax of ACDEF (define an analyzer condition)
| 1. argument: analyzer name,
| 2. argument: condition number,
| ID keyword: condition id (optional; default = cond. number),
| LIMITS keyword: list of condition limits (2 or 4 values)
| (optional; default = analyzer limits).
|
| (ACDEF may be used to define the limits or the condition ID -
| a word to characterize the condition - or both. Conditions may
| also be manipulated by the commands W1.., W2.., and ACDEF)
|
|
| Syntax of AC (return the value of an analyzer condition)
| (for 1-dim. and 2-dim. analyzers)
| 1. argument: analyzer name,
| 2. argument: condition number.
| AC yields always true for conditions which are not set (= open).
| AC yields always false for conditions which are closed.
|
|
| Syntax of ANAL (fill data into an analyzer, 1-dimensional)
| 1. argument: analyzer name,
| 2. argument: channel number,
| INCR keyword: increment (optional; default = 1) or
| VALUE keyword: set value (INCR and VALUE are exclusive).
|
|
| Syntax of ANAL (fill data into an analyzer, 2-dimensional)
| 1. argument: analyzer name,
| 2. argument: channel number 1. dimension,
| 3. argument: channel number 2. dimension,
| INCR keyword: increment (optional; default = 1) or
| VALUE keyword: set value (INCR and VALUE are exclusive).
| Analyzers used in ANAL must have been created by AGEN.
|
|
| Syntax of AGET (get value from an analyzer, 1-dimensional)
| 1. argument: analyzer name,
| 2. argument: channel number,
| AGET returns the content of the analyzer channel.
| Analyzers used in AGET must have been created by AGEN.
|
|
| Syntax of AGET (get value from an analyzer, 2-dimensional)
| 1. argument: analyzer name,
| 2. argument: channel number 1. dimension,
| 3. argument: channel number 2. dimension,
| AGET returns the content of the analyzer channel.
| Analyzers used in AGET must have been created by AGEN.
|
|
| Syntax of PARDCL (declare interactive parameter)
| (only DEC FLOAT(6), 1-dim arrays supported)
| 1. argument: variable name,
| INIT keyword: value (optional; default = 0),
| COMMENT keyword: comment (optional; default = '').
| For arrays, the INIT and COMMENT keywords are assigned to the
| different components in sequence. Missing values are
| repeated from the last given value.
| Parameters are declared in the analysis routine and may be used
| there like a normal variable declared by
| DECLARE "name" DEC FLOAT(6) STATIC INIT(..);
| for reading and writing. */
|
|
| LIST('Raw analysis of MUSIC detector');
|
| DECLARE DBRHO DEC FLOAT(6);
|
| PARDCL(BRHO_NULL(3)) INIT(9.7934,9.7320,9.7308)
| COMMENT('central magn. rigidity');
|
| AGEN(MUSIC(4)) LIMITS(0,1023) BINS(2) NCND(1)
| CXAXIS(ADC channel) CYAXIS(counts) TITLE(first music);
|
| AGEN(TOF_DBRHO) LIMITS(0,1023,-1000,1000) BINS(4,16) NCND(2)
| CXAXIS(TOF/100 ps) CYAXIS(Delta-Brho / Brho * 100000)
| TITLE(Identification of masses and charge states);
|
| ANTRY; /* end of definition part, begin of data-block loop */
|
| EVENT DATA(I_MUSIC(4),TOF,BRHO) FORMAT(FIXED);
| /* definition of list-mode event data, event loop */
|
| /* The following data formats are supported by $EVENT:
| FIXED (standard SATAN format, 2 byte integers)
| This is the default option.
| FLOAT (SATAN format, 4 byte reals)
| FIXED LONG (SATAN format, 4 byte integers)
| FLOAT LONG (SATAN format, 8 byte reals)
| GOOSY (see HELP GOOSYDATA for details)
| FRS2003 (FRS standard GOOSY data format)
| ASCII (simple ASCII format, data of one event per line;
| data may be reals or integers,
| devided by at least one blank)
| Lines in the input dataset beginning with "*" are ignored.
| IN2P3 Standard data format of IN2P3 (France)
| CAMDA CAMDA data format */
|
| DO I = 1 TO 4;
| ANAL(MUSIC(I),I_MUSIC(I));
| END;
|
| DBRHO = FLOAT(BRHO - BRHO_NULL(1),6) * 100000.E0;
| IF AC(MUSIC(1),1) THEN
| ANAL(TOF_DBRHO,TOF,DBRHO);
|
| /* Hints to handle events with variable length in SATAN format: */
| /* 1. Supply the maximum number of parameters for $EVENT */
| /* which may ever appear. */
| /* 2. Assign the actual number of parameters to the variable $N_EVT */
| /* just before the macro $ENDEVT. */
|
| ENDEVT; /* end of event loop */
| $CONDITION_CHECK(); /* check on declared but unused conditions */
| ENDANL; /* end of data-block loop and of analysis routine */
The same thing without comments:
|%INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
|DEBUG;
|
|LISTPROC;
|
| LIST('Raw analysis of MUSIC detector');
|
| DECLARE DBRHO DEC FLOAT(7);
|
| PARDCL(BRHO_NULL(3)) INIT(9.7934,9.7320,9.7308)
| COMMENT('central magn. rigidity');
|
| AGEN(MUSIC(4)) LIMITS(0,1023) BINS(2) NCND(1)
| CXAXIS(ADC channel) CYAXIS(counts) TITLE(first music);
|
| AGEN(TOF_DBRHO) LIMITS(0,1023,-1000,1000) BINS(4,16) NCND(2)
| CXAXIS(TOF/100 ps) CYAXIS(Delta-Brho / Brho * 100000)
| TITLE(Identification of masses and charge states);
|
| ANTRY;
|
| EVENT DATA(I_MUSIC(4),TOF,BRHO) FORMAT(FIXED);
|
| DO I = 1 TO 4;
| ANAL(MUSIC(I),I_MUSIC(I));
| END;
|
| DBRHO = FLOAT(BRHO - BRHO_NULL(1),6) * 100000.E0;
| IF AC(MUSIC(1),1) THEN
| ANAL(TOF_DBRHO,TOF,DBRHO);
|
| ENDEVT;
| $CONDITION_CHECK();
| ENDANL;
MONTE-CARLO simulations
=======================
Another version of the analysis program may be used for
MONTE-CARLO simulations
Example for a MONTE-CARLO analysis program:
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
| DECLARE I BIN FIXED(31) INIT(0);
| DECLARE ...
| PARDCL(...
| AGEN(...
|
| START; /* entry for commands START and CONTINUE */
|
| LOOP; /* begin of event loop */
|
| ... /* simulation calculation */
| ANAL(...
| I = I + 1;
| IF MOD(I,10000) = 0 THEN EXCMD(LHALT);
|
| NEXT; /* end of event loop */
|
| ENDANL;
The program starts execution at START by the command LSTART.
The extension of the LOOP loop can be specified by the LOOP
macro (see HELP MACROS) and by the command LSTART (see HELP LSTART).
The loop from START to NEXT can be stopped by pressing the BREAK
button or by executing EXCMD(LHALT) in the program. In the example,
the program stops after 10000 events. When it is restarted with
LCONTINUE, it is stopped again after another 10000 events.
MODEL CALCULATION
=================
A model calculation without a MONTE-CARLO event loop looks like the
following example:
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
| DECLARE I BIN FIXED(31) INIT(0);
| DECLARE ...
| PARDCL(...
| AGEN(...
|
| START; /* entry for command START */
|
| ... /* simulation calculation */
|
| ANAL(...
|
| ENDANL;
Generating or compressing list-mode data
========================================
Writing list-mode data by an analysis program is supported. This
feature may be used for creating list-mode data (e.g. from a
Monte-Carlo simulation) or for compressing data by omitting part of
the event parameters or by writing pre-analyzed data. A simple option to convert ASCII data into SATAN data format is
offered by the command LCONVERT. The purpose is to speed up in
execution time, since reading of binary data in SATAN format is
faster than reading ASCII data. For this option not analysis
program is needed. The command LCONVERT provides several parameters
to adapt the function to your needs.
First you must write an analysis program. Either it reads the input
list-mode data from file and defines the new list-mode data to be
written or it generates itself the list-mode data to be written.
Here an example for an analysis program for compressing existing
list-mode data:
(A new file is written with 3 event parameters taken from 120 initial
event parameters.)
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
| DECLARE N_EVT BIN FIXED(15);
| DECLARE IV_EVT (3) BIN FIXED(15);
| DECLARE I_RC BIN FIXED(15);
|
| ANTRY;
|
| EVENT DATA(I_EVT_IN(120));
|
| IV_EVT(1) = $FIXED(I_EVT_IN(13),15);
| IV_EVT(2) = $FIXED(I_EVT_IN(27),15);
| IV_EVT(3) = $FIXED(I_EVT_IN(104),15);
| N_EVT = 3;
|
| LOUT DATA(IV_EVT) N(N_EVT);
|
| ENDEVT;
|
| ENDANL;
LOUT can handle data arrays of BIN FIXED(15), BIN FIXED(31),
DEC FLOAT(6), and DEC FLOAT(15) values.
The use of the $FIXED function is recommended for BIN FIXED(15)
data because it prevents the FIXEDOVERFLOW condition to occur
in case the input values exceed the range of the BIN FIXED(15)
variables.
Here an example of DEC FLOAT(6) values:
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
| DECLARE N_EVT BIN FIXED(15);
| DECLARE RV_EVT (3) DEC FLOAT(6);
| DECLARE I_RC BIN FIXED(15);
|
| ANTRY;
|
| EVENT DATA(I_EVT_IN(120));
|
| RV_EVT(1) = FLOAT(I_EVT_IN(13),6) / FLOAT(I_EVT_IN(15),6);
| RV_EVT(2) = FLOAT(I_EVT_IN(27),6) * 1.E-5;
| RV_EVT(3) = FLOAT(I_EVT_IN(104),6);
| N_EVT = 3;
|
| LOUT DATA(RV_EVT) N(N_EVT);
|
| ENDEVT;
|
| ENDANL;
For reading these list-mode data with another analysis program,
the appropriate data-type option (FIXED, FIXED LONG, FLOAT or
FLOAT LONG) must be specified in the EVENT macro.
The analysis program must be linked to SATAN with the SLINK procedure.
Then SATAN is started. For writing modified data from existing
list-mode data, the new data file is written by applying the
following commands in SATAN:
LOUTPUT / DSN(output dataset name)
LINPUT / DSN(input dataset name)
If the list-mode data are generated in the user-supplied program (e.g.
see "MONTE-CARLO simulations" above), the following commands have to be
entered:
LIOUTPUT / DSN(output dataset name)
LSTART
Another LOUTPUT command with a new dataset name will close the output
dataset and open the new one. The last output dataset is closed when
you exit SATAN.
Dynamic analysis and live display
=================================
Dynamically created analyzers may be filled with list-mode data:
1. Insert the macro DYNANAL in your analysis program.
(The macro DYNANAL is necessary to enable the dynamic analysis. It must
appear directly after EVENT, the GOOREAD, or the START macros,
respectively.)
2. Create a dynamic analyzer with the command AGEN
(Large bin sizes do not affect the live display.)
3. Define the data to be accumulated with the command ANAL
(Data may be list-mode event data, values accumulated in resident
analyzers or the current list-mode event number.
The available list-mode event data are listed by the command
ELIST. The available analyzers are listed by the command AATT *.
The currently defined dynamic analysis may be viewed by
ANAL / LIST.)
(4. If a live display is required: Enter {GDISP, GPLOT, GOVER} / LIVE.
(Live display is supported for resident and dynamic 2-dimensional
analyzers.)
5. Read the list-mode data with the command LINPUT
(All analyzers, either resident or dynamic, are accumulated
according to the macro $ANAL or the command ANAL, also when their
live display is active.)
If no user-defined analysis program is provided, a default analysis program
with list-mode data in ASCII format up to 256 parameters is pre-defined.
These data may be read and sorted into analyzers by the command ANAL.
The following example shows a very simple and short version of a user-defined
analysis program:
|%INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
|LISTPROC; /* begin of procedure */
| ANTRY; /* begin of analysis part */
| EVENT DATA(I_MUSIC(4),TOF,BRHO) FORMAT(FIXED);
| /* give access to list-mode data */
| DYNANAL; /* activate dynamic analysis */
| ENDEVT; /* end of event loop */
| ENDANL; /* end of procedure */
Preparing an excecutable program
================================
The analysis routine, if written in analogy to the above example, may
be compiled without any further options by the normal PLI compiler.
* Compile the program(s) with the command "PLI module".
* Link the program with "SLINK module1.obj [module2.obj module3.obj ...] ".
* Run the program with "module1".
* ("module" stands for the name of your program(s).)
*********************************************************************
Subroutines
===========
In addition to the analysis routine, the user may supply the following
routines:
(These procedures do not have any parameters.)
routines called with
-------------------------------------------------------------
$MYINP command INPUT
$MYGO start of reading list-mode data
$MYHALT halt of reading list-mode data
$MYEXIT command EXIT
These routines have to be added to the LINK list just behind the
analysis routine.
The user may apply the following procedures:
(See also HELP MACROS for more detailed information)
(The following abbreviations are used:
CVx: CHAR(x) VAR, B1A: BIT(1) ALIGNED, Ixx: BIN FIXED(xx), Rxx DEC FLOAT(xx))
routines function
-------------------------------------------------------------
$PRTCL(CV,I15) write to screen and to protocol (I15=1)
$PROMPT(CV,any) prompt a variable
$PROMPTO(CV,any) propose and prompt a variable
GPEDIT(R15,I15) RETURNS(CV256) transform a DEC FLOAT(15) number
to a character string with given precision
$2FIX16FLOL(I15,I15) RETURNS(R15) converts two unsigned 16bit
numbers (BIN FIXED(15))
(e.g. from 32 bit counter)
to one DEC FLOAT(15) number
==> RESULT = $2FIX16FLOL(I_LOW,I_HIGH);
$2FIXL16FLOL(I31,I31) RETURNS(R15) converts two unsigned 16bit
numbers
$2FIXL24FLOL(I31,I31) RETURNS(R15) converts two unsigned 24bit
numbers
$FIXED(value,precision) RETURNS(Ixx)
transform a value of a variable
into BIN FIXED format with
indicated precision.
(Precision values 7, 15, 31 are
supported. Protected against fixed
overflow, values are limited
inside permitted range.)
$NLBL(CV) RETURNS(CV256) remove leading blanks
$NTBL(CV) RETURNS(CV256) remove trailing blanks
$NOBL(CV) RETURNS(CV256) remove all blanks
PRN RETURNS(R6) random generator (0 .. 1)
PGAUSS(R6,R6) RETURNS(R6) random generator (Gaussian
distribution)
==> R1 = PGAUSS(R_MEAN,R_SIGMA)
PEXP(R6) RETURNS(R6) random generator (exponential
distribution) P=exp(-x/R_TAU)
==> R1 = PEXP(R_TAU)
PMAXWELL(R6) RETURNS(R6) random generator (Maxwell
distribution) P=x*exp(-x/R_T)
==> R1 = PMAXWELL(R_T)
and several other routines.
The procedures beginning with a $ sign as well as PRN, PGAUSS, PEXP,
and PMAXWELL are already declared in the analysis routine. |
