$Id: GSSort.html,v 1.5 2003/01/13 22:42:15 tl Exp tl $

GSSortŪ

the GAMMASPHERE sorting program for ROOT

Please note: We have had problems with some newer versions of ROOT (at least on the Suns). If you want to use GSSort, please use root_v3.02.07 from CERN. That version seems to be ok. (latest: root_v3.10.02 seems to be ok as well, we are now switching over to that version!!!!)



PURPOSE

This program is NOT meant to necessarily sort the date at the level of a 'final' data analysis for publication; but it may serve a a starting point for a full data analysis program. This sorter cannot do everything although it is becoming quite powerful. It is geared towards monitoring data online during experiments and provide utilities for calibration of GammaSphere data.

This program is under development, so expect frequent updates and new interesting bugs in short order...


PORTABILITY

GSSort/GSUtil are available on the Linux machines as well. Look for an executable in ~tl/bin on the linux machines and GSUtil_cc.so in ~tl/bin.

GSSort was compiled in a MAC using the Darwin environment. However, the code did not run properly. But GSUtil_cc.so works fine in this environment.

WRT Scarlet: Gammasphere uses udp datagrams to allow users to monitor data online (spy on the data). Ken's Scarlet uses tcp. Thus, it is not really possible to use the current version of the GSSorter with Ken's Scarlet system. Another sorter, with a tcp receiver, has to be developed for this system. Also, with Scarlet it may not be possible to just 'spy' on the data flow as we do at Gammasphere -- so that creates a another level of complexity which has to be dealt with. The GSSorter, in its present form, is not ready for that. Besides, at the moment, GSSort only understands data in the Gammasphere format. It cannot read any other formats.


STARTING SORT


To setup ROOT on the suns, see the instructions at URL:

   https://www.phy.anl.gov/computers/hints/index.html
   
(you must have the environment variable ROOTSYS set properly,
as well at the PATH and the LD_LIBRARY_PATH path)   

To use GSSort type:

  GSSort_3.10.02 -chat chatfile

or whatever version is available or you want to use.  The
chatfile is a file with sorting instructions. Below is a
list of what instructions can be given in this chatfile,
with some examples.

To get this help

  GSSort_3.10.02 -help

To see the version

  GSSort_3.10.02 -version


You may also start the sorter from inside rootn.exe with

  startsort("chatfile","logfile");

and you can stop it again using

  stopsort();

see GSUtil utilities for more options to control GSSort from inside rootn.exe (root).


SIGNALING GSSORT


It is possible to signal GSSort to write out the current root
spectra and continue its sort. This allows for the user to 
look at the data while it is being sorted!

To ask GSSort to write the root spectra out - or update
the shared memory, type

  pkill -HUP GSSort_3.10.02

The sort will continue after the write-out/update. To write the spectra out
AND stop the program, type

  pkill -HUP GSSort_3.10.02
  pkill -KILL GSSort_3.10.02

When you signal GSSort as described above, the program will first look
for a special command file (GSSort.command). If this
file is present, the program will try and execute the command in the
file. Only a small fraction of the chat script commands described below
are recognized. A few other commands that do not make sense in the
chatscript are recognized as well.

When you start a GSSort, you probably want to update the
shared memory often to see that things are working. Later on,
such frequent updates could be wasteful. You can change the
update time on the fly by:

  echo "dumpevery 15" > GSSort.command ; pkill -HUP GSSort

here you are setting subsequent update intervals to 15 minutes.

To zap all the spectra, this will do

  echo "zapall" > GSSort.command ; pkill -HUP GSSort

currently the following commands are recognized through the
command file:

   dumpevery #
   zapall
   zap 'spectrum'
   printevents

see GSUtil utilities for options to control GSSort from inside rootn.exe.

CHAT FILE FORMAT




----------------------------------------
option: echo

if set, the program will echo the chatscript instructions
from the point where echo is mentioned

example

echo

----------------------------------------
option: setrecordver id

We like to change the RecordVer number in the GS buffers
when we change data format (as we should do). However, for
mostly stupid reasons, we cannot always increase this
dataformat ID because old sorting codes here and there,
which we cannot recompile, breaks.  With this option you
can overwrite the version code that is on the tape so that
things will work anyway. The example below outlines the
usual scenario.

Example:

setrecordver    1

A tape was really writing in format 1; but the eff code was
forced $) to write RecordVer=0 to tape so that the old DAPHNE code
would not break. With this option we make sure the GSSort
parse routine sees a RecordVer of 1 anyway - so it will
read any dirty Germaniums and clean BGOs correct.

$) FYI, in the old DAQ system that is done by changing the file
~gs/user/eff/eff.user entry from

   record_ver_id=1
   
as it really should be, to   
   
   record_ver_id=0   
   
and then reboot the EFFs (or issue the  'record_ver_id=0'
command in each of the EFFs tip windows)  

----------------------------------------
option: nevents #

specify the max numbers of events to sort

example
nevents 500000

----------------------------------------
option: input source device/port

specify where the data is read from. Options for source is
'tape', 'net' or 'disk'. If tape is specified you must also
specify the tape drive.  For the 'net' option you must
specify the port to listen to (Gammasphere uses port
1101).  For 'disk', specify the diskfile to sort from (this
file may be on a remote NFS mounted disk; but that would
not be efficient though. It would also create a lot of
network traffic. It is better to use a local disk).

examples:
input tape /dev/rmt/1mbn
input net  1101
input disk /home/expdata/run2.data

Note: on the Solaris machines, the tape drives are ~usually named 
something like:

/dev/rmt/1mbn - stacker
/dev/rmt/0mbn - single side drive
/dev/rmt/2mbn - DLT drive (sun1 only)

...to make sure, put a tape in and probe it as e.g.,

   mt -f /dev/rmt/0mbn status

Note: you can use 'GSudpSender' to simulate the Gammasphere sender

Note: Use 'tape2disk' to dump data from a tape to disk

----------------------------------------
option: output file

specify the root disk output file

example
output data.root

----------------------------------------
option: rootfileoption s

specify how the root file (specified with "output file")
should be opened. s can be:

   RECREATE or  UPDATE


RECREATE: create a new file, if the file already
          exists it will be overwritten.

UPDATE:   open an existing root file and sort more 
          data into it.


the default is RECREATE

example1
rootfileoption RECREATE

create a new root file at the beginning of a sort

example1
rootfileoption UPDATE

read in the content of the root file specified with the
'output' chat script option before the sort start. I.e
start the sort with the current content of the output
root file.

Note: At the moment you cannot add to a shared memory file.
      Always use 'RECREATE' with shared memory files.

----------------------------------------
option: sharedmem s #

Use roots shared memory implementation. Second argument
should be the name of the shared memory map and the 
third argument should be the size of the memory map
in bytes.

example
sharedmem gs.map 200000000

.........
note1: You MUST specify a shared memory file on a local disk
on the machine you are working on. Otherwise you will get
extremely poor performance! You should only use shared memory
on machines that have a lot of memory.

.........
note2: if you make the shared memory map too small you
will get an error message as:

updating empty shared mem file... Segmentation fault (core dumped)

In that case, just increase the size and try again. 

----------------------------------------
option: startmapaddress #

Set the start address of the root shared map file.

example
startmapaddress 0xe2000000

note: To figure out what address to use, follow these
steps:

  start rootn.exe
  .L GSUtil_cc.so
  sdummyload(200000000)

see what start address rootn.exe chose. Set the argument to sdummyload
above to the shared memory size you chose with the 'sharedmem'
chatscript option. This start address will in general be
different on different machines.

----------------------------------------
option: dumpevery #

write all spectra to root file every so many minutes.
(Note: you can always dump spectra using 'pkill -HUP
GSSort' or update() from inside rootn.exe)

example
dumpevery 10

warning: program may only respond if it has data flowing to
it.

----------------------------------------
option: printevents #

number of GammaSphere events to print out in glory
details (including FERA interpretation). Good for
debugging the electronics... and seeing conditions
and Pseudo event vector

example
print 200

----------------------------------------
option: evtime0 #

sets the start time of the experiment so that EvTime in
rate spectra can be related to the beginning of the
experiment. The argument is the number of seconds since
time zero.

example:

evtime0           2057030

The experiment started 2057030 seconds after the MTM clock
was zeroed last.

NOTE: if you do not set this value, and the master crate
has been up for a long time, chances are that the event time
in seconds is very large and will overflow the rate spectrum
which is only so long. If you use 'printevents()' GSSort will
report the current event time in seconds so you can set
evtime0 to something reasonable.

----------------------------------------
option: compress #

sets the compression level of the root file.
0: no compression, 9 max compression. 1 
is the default used if you do not specify
this value.

example
compress 2

----------------------------------------
option: ignoreexternal

If this option is set, then GSSort will not try to
interprete the external FERA data, I.e., it will
ignore external data. This is sometimes useful if
you want to debug Gammasphere, but do not want to
deal with (strange or unknown) FERA formats.

----------------------------------------
option: egemin e0

set the minimum energy of germaniums before they are
accepted in the sort. The cut is applied to the raw data
before doppler corrections of compression with the option
"hiresdatamult". Thus, it will influence the multiplicity
cuts (cleanmultlim dirtymultlim totalmultlim). E.g, this
option could be used to cut x-rays.

example:

egemin 20

----------------------------------------
option: ebgomin e0 

set the minimum energy of BGOs before they are accepted in
the sort. Thus, it will influence the multiplicity cuts
(cleanmultlim dirtymultlim totalmultlim). E.g, this option
could be used to cut x-rays.

example:

ebgomin 30

----------------------------------------
option: undotac2sub factor offset

Will add  to all the germanium times, thus,
undoing the tac2 subtraction done in the EFFs

example

undotac2sub 0.5 4000

----------------------------------------
option: ignorehs

ignore the honeycomb suppression of germanium detectors. The default
for GSSort is to remove detectors that are honeycomb suppressed (or
rather, marked as such).

example

ignorehs

----------------------------------------
option: tac2subge factor

Mostly, TAC2 is already subtracted by from the germanium
times by the EFF processors, but in case it is not, this
option can be used to do it in GSSort. Factor, if set to
anything but 1.0, can be used to modify the tac2 values.
This factor is multiplied to tac2 before the result is
subtracted

example

subtac2ge 1.0
gerfoffset 1000

note: see also 'gerfoffset'

----------------------------------------
option: tac2subbgo factor

TAC2 is currently not subtracted by from the BGO times by
the EFF processors.  This option can be used to do it in
GSSort. Factor, if set to anything but 1.0, can be used to
modify the tac2 values. This factor is multiplied to tac2
before the result is subtracted

example

subtac2bgo 1.0
bgorfoffset 1000

note: see also 'bgorfoffset'

----------------------------------------
option: geroffset #

To get the germanium time with respect to the RF, we subtract tac2. To
get the range right after the subtraction, the number specified with
gerfoffset is added to clean and dirty germanium times.

example
gerfoffset 1000

Note: this value is not used unless 'subtac2' is specified.

----------------------------------------
option: bgorfoffset #

As geoffset, but for clean BGOs

example
bgorfoffset 3000

Note: this value is not used unless 'subtac2' is specified
and 'binbgo' is specified

----------------------------------------
option: getalignment calfile

time align with the offsets in the "calfile".  The formats
of the file is 'detector #' 'offset' -- one set per
detector.  These offsets are subtracted from the germanium
times.

example

getalignment tge_1.cal

the "tge_1.cal" file looks like this:

#tge alignment root/GSSort
  1    0
  2    0
  3    0
  4    0
  5    0
  6    0
  7  511
  8  510
.
.
.
.
106  505
107  508
108  509
109  506
110  507

Lines beginning with # or ; are ignored and can
thus be used for comments.

Note: you can use the tgealign utility in the
GSUtil utilities to find
these offsets.

----------------------------------------
option: bgotalignment calfile

as getalignment but for BGO detectors

example

bgotalignment tbgo_2.cal

Note: you can use the tbgoalign utility in the
GSUtil utilities to find
the offsets.

----------------------------------------
option: recalcgssume tgelo tgehi tbgolo tbgohi

if this option is switched on, the BGO sum energy, "sumbgo"
pev, and the germanium sum energy, "sumge" pev, are
recalculated in GSSort with the germanium time windows:
tgelo -> tgehi and bgo time windows: tbgolo -> tbgohi. The
header sbgo and sge values are replaced as well.

I.e., the summed energies calculated by the EFFs are
overwritten and presented in the pevs: "sumge" and "sumbgo"
The pev "lentotal" is also recalculated with the time
windows specified.

Note: Do NOT use this option unless you are writing dirty
germanium and clean BGOs out. You need dirty germaniums and
and clean BGOs to recalculate the sge and sbgo (the 'H')
values and find the true "lentotal" ('K') value for an
event.

Note: the calibration of sge and sbgo will in general be
much different from the calibration of the sge and sbgo
spectra calculated in the EFFs - since the EFFs compress a
lot. The typical energy calibration of the recalculated sge
spectrum is: [4.014938xch-11.9] and for the sbgo spectrum:
[4.989150xch+11.38].

Example:

recalsgssume 6950 7050 900 1100

----------------------------------------
option: mkgetemats ne elo ehi nt tlo thi

Make 2D matrices of Time vs Energy of all the GS
germaniums. 'ne' channels, from 'elo' to 'ehi', for energy
and 'nt' channels, from 'tlo' to 'thi' for time.

example

mkgetemats 256 1 2048 128 3850 4106

note: make sure you do not 'over dimension' these matrices,
or they will take a huge chunk of memory and impede the
sort.

----------------------------------------
option: anglefile file

This instruction is optional.  If this file is not
specified, GSSort will use the default angles for the
detectors in GS. However, sometimes a detector does not
show up at the 'designed' angles because a grey cable has
been moved (and the a database not updated accordingly). In
such a case you can overwrite the default angles with this
file.

example

suppose detector 4, which is at angle 17.27, is using the
grey cable and electronics of the detector at position 8.
Thus, in the sort this detector would show up as det 8 at
an angle of 31.72. To overwrite this, add the line

   8     17.27

to the file "myangles.dat" and add the line

anglefile myangles.dat 

to you sort chat script. You can add as many 'corrections' as you
need. One 'detector-number angle' line per correction.

----------------------------------------
option: beta #

specify the beta=v/c of the recoil residues. 

example
beta 0.02650

----------------------------------------
option: hiresdatamult #

Multiply germanium energy data by this number before binning.

example
hiresdatamult 0.66666666

----------------------------------------
option: firstfile #

Used to position a tape a a specific file before sorting is started. If
you do not want to position the tape (and continue from current
position) specify -1 or leave out this line. 

example
firstfile 0

position at 1th file on tape, file=0

example 
firstfile 3

skip over the first 3 files on the tape and position
at file=3 (first file is labeled 0 in this scheme) or
4th file.

note:
the files on the tape are know as

0 1 2 3 4 5.........

so file 3 is the 4th file on the tape.

----------------------------------------
option: nfiles #

max number of files to sort. Used in conjunction with firstfile to just
sort the data in a specific file on a tape (with e.g., source data)

example
nfiles 1

----------------------------------------
option: include file.chat

include 'file.chat' in the current chat script. This
is a way of organizing the chat script

Example

include counting_test.chat
----------------------------------------
option: exit

abandon the rest of the chat script and start sort
(mostly used for debugging of if you are working on
some sort instruction that are not yet ready)

Example

exit
----------------------------------------
option: quit

abandon the rest of the chat script and exit
(this option is sometimes useful to make GSSort
just interpret the chat file, but sort anything)

Example

exit
----------------------------------------
option: writerawfera

write raw fera data in data dump listing.
Default is to just write interpreted fera data


example
writerawfera


----------------------------------------
option: binbgo

asks GSSort to process and bin BGO energies and times. Default
is not to do that since many datasets do not have BGO information
written to tape.

example

binbgo

----------------------------------------
option: nposwarn #

Typically there are a few errors once in a while in the
GS data buffers. E.g., when the basic reader routine 'get_ev'
has read an event it checks for end-of-event or fera-marker.
If this fails, it will quietly recover unless you ask
GSSort to documents such errors with the nposwarn option.

example

nposwarn 10

The first 10 position errors will be documented in great
details.

Note: at the end of the sort, or when you update, statistics
will be given for how often such buffer position errors
occur (whether you specify nposwarn or not).

----------------------------------------
option: printpevraw

In the sort code, the pevs are filled first without regard
to conditions. Then the conditions are applied and some of
the filled pevs will drop out again. With this option, the
code will write the 'raw' pevs out before they are
subjected to any conditions. This option is mostly used for
debugging in order to follow the logic of the code when it
comes to conditions and application of conditions.

----------------------------------------
option: nferaerrtoprint #

number of FERA errors to print out when we print
events

example
nferaerrtoprint 5

note: it is not unusual to have ~1% fera errors in a typical
dataset. 

note: this option does not do anything at the moment...

----------------------------------------
option: ferapev vsn ch name [ thresh [offset gain]]

declare a pseudo event vector (pev) entry and associate it
with FERA channel VSN='vsn' and CH='ch' and name this entry
'name'. 'name' is used later when you bin the pev or apply
a condition or otherwise refer to data from this FERA
channel.

example
#       vsn ch name
ferapev 24  0  left
ferapev 24  1  right
ferapev 24  2  up
ferapev 24  3  down

note: the program will assign pev numbers, but you will
never refer to the numbers, - only to the names. This
is a major difference to Daphne.

note: both regular FERA data (LeCroy) as well as Silena
fera data are interpreted automatically by this program.

Optionally one can specify a threshold 'thesh' which the
raw fera data must exceed before the FERA channel is
processed.  This is useful to eliminate noisy FERA channels
so that don't show up in the filled pev list and processed
in the sorting.

A gain correction can be optinally be specified: 'offset'
'gain'.  A random number between -0.5 and 0.5, rn, is added
to the FERA data before the FERA data is first multiplied
by 'gain' and then has 'offset' added to it. i.e.,

  pev_value= (fera_data+rn)*gain+offset

---------------------------------------
option: silena vsnmumbers

Instructs GSSort that the fera pev vsn numbers 'vsnmumbers'
are silena FERAs. 

Example:
silena 17

..here we state that the FERA that gives VSN number 17 
  has silena FERA format.

Example:
silena 17-19,23

..here we state that the FERAS with VSN numbers: 17,18,19,23
  have silena fera formats.
  
FERAformats

---------------------------------------
option: lecroy vsnmumbers

Instructs GSSort that the fera pev vsn numbers 'vsnmumbers'
are lecroy (or lecroy type) FERAs. 

Example:
lecroy 25-30,40-45

FERAformats

---------------------------------------
option: export:phillips vsnmumbers #FERAs

Instructs GSSort that the fera pev vsn number 'vsnmumbers'
are export modules. #FERAs indicates how many fara modules
the export module services.

Example:
export:phillips 49,61,70-71 11

..here we state that the FERAs with (base) VSN
  numbers:49,61,70,71 are export module - which all serves
  11 Phillips FERA modules each. The modules served from these
  export module will return VSN numbers:
  49,50,51,.....,61,62,.....

FERAformats

Note: for the faulty exportmodules where there is an extra
ghost word after the header, simply specify one more FERA
module than really is there -- and this problem is
overcome. However, be aware that all the vsn numbers moves
up one then. I.e., in the example above, if they all are
faulty export module, vsns 49,61,70 and 71 will never come
out. The first vsn numbers would be 50,62,71 and 72

Note: this options was formerly known just as 'export', but
that was kind of misleading since the format of data from
the export module depends on what module it serves.

---------------------------------------
option: export:4208TDC vsnmumbers #TDCs

Instructs GSSort that the fera pev vsn number 'vsnmumbers' are export modules
serving 24 bit long range TDCs.  #TDCs indicates how many TDC modules the
export module services.

Example:
export:4208TDC 37 2

here we declare that VSN 37 is an export module that serves
two long range 24 bit LeCroy TDCs.

---------------------------------------
option: ortec vsnmumbers

Instructs GSSort that the fera pev vsn numbers 'vsnmumbers'
are Ortec FERAs. 

Example:
silena 21-23

.. here we inform GSSort that FERAS with VSN numbers 21,22,23
have Ortec FERA format

FERAformats

---------------------------------------
option: feraclock1 vsnmumber scalefactor maxvalue

Instructs GSSort that the fera pev vsn numbers 'vsnmumber'
is a Clock registers and it should be passed back in
'clock1' after being scaled by 'scalefactor' and limited to
have the max value of 'maxvalue'. 

Example:
feraclock1 98 0.01 16380

.. here we tell GSSort that the FERA with VSN number 98
has a clock format and should be passed back in clock1 after
being downscale by a factor of 100 and limited to the max value
of 16380 (any value over 16380 will be set to 16380)

FERAformats

---------------------------------------
option: feraclock2 vsnmumber scalefactor maxvalue

Instructs GSSort that the fera pev vsn numbers 'vsnmumber'
is a Clock registers and it should be passed back in
'clock2'  after being scaled by 'scalefactor' and limited to
have the max value of 'maxvalue'. 

Example:
feraclock2 97 0.1 8100

.. here we tell GSSort that the FERA with VSN number 97
has a clock format and should be passed back in clock1 after
being downscale by a factor of 10 and limited to the max value
of 8100 (any value over 8100 will be set to 8100)

FERAformats

---------------------------------------
option: mkpev name

declare a pseudo event vector with name 'name'. This
command is somewhat equivalent to ferapev, but it has no
FERA output associated with it.  This command is used to
create a pev which derives its content from the pev's
created by ferapev by use of the modpev commands.

example

mkpev xx
mkpev yy

Note:
The pev you declare this way will be created 'empty'.

----------------------------------------
option: modpev 

a set of commands allows for manipulation of pev
vectors from the chat script. They are:

1) modpev addconst pev constant
2) modpev mulconst pev factor
3) modpev addpev pev1 offset factor pev2
4) modpev mulpev pev1 factor pev2
5) modpev divpev pev1 factor pev2
6) modpev countcond cond in pev

No 1 adds a 'constant' to pev number 'pev' (but only if pev
number 'pev' has been filled). No 2 does the same but
multiplies with a factor instead (but again only if pev
number 'pev' has been filled).  No 3 adds the value of pev
'pev2' to pev 'pev1' (after pev2 has been multiplied with
'factor') but only if pev 'pev1' OR pev 'pev2' were
filled.  etc...

The 'checks' mentioned above can be bypassed using the
'overridempevcheck' option.

No 6 is different: if 'cond' is fulfilled, then 1 (one) is
added to pev. I.e., this feature can be used to count a
number of conditions fulfilled (e.g., three protons
detected in uball) and you can place conditions (and use the
condition later) on the (counting) pev.

You usually first create a pev with 'mkpev' to operate on
with the 'modpev', but you can manipulate the so called
FERA pevs as well.

Note: more modpev functions can be added. If you have
suggestions let us know!

Example1:

say you have the the PPAC 'left' and 'right' signals
declared as:

ferapev  24  0  left
ferapev  24  1  right

and you would like to create an ppac x signal.
You would do the following:

mkpev xxraw
modpev addpev   xxraw 0  1 left
modpev addpev   xxraw 0 -1 right  
modpev addconst xxraw 2000
binpev1d xxraw 512 0  4095

I.e., you create the xxraw pev, the add the left signal
and subtract the right signal. You then add 2000 and
ask GSSort to bin the xxraw in the range 0->4095 in
512 channels.

Example2:

Here is an example of a 'counting' pev following 
example 1.

pevcond1d left  10-8000 okleft
pevcond1d right 10-8000 okright
mkpev noklr
modpev countcond okleft  in noklr
modpev countcond okright in noklr 
pevcond1d noklr 2-2 oklrsig
binpev1d noklr 10 0 9

applycond oklrsig to xxraw

We are here effectively requiring that BOTH the left and the
right signals are there before we want to see xxraw. 

----------------------------------------
option: ratespectrum pev nn lo hi

make a rate spectrum based on updates to the pev
named 'pev' (with any conditions it may have on it).
Use nn channels in spectrum and display from
event time 'lo' to 'hi'

example1:

ratespectrum iso1e 120 2054700 2061900

here we are asking for the rate of updates w.r.t
the event time for the pev 'iso1e' the event
time interval is 7,200 seconds long = 2*60*60 or
2 hours, so by specifying 120 channels we effectively
display the rate in 1 minute slices.

The event times are printed in seconds etc with
the printevents() option in GSUtil and in the beginning
of the sort.

Note: the x axis of the rate spectra will always be
seconds nomatter how many bins you specify. That is
a feature and not a bug.

example 2:

#--------------------------
# gammasphere and isomer rate spectra

ratespectrum gammasphere 2048 0 122879

mkpev isomer
modpev addpev isomer 0 1 gammasphere
applycond isotok to  isomer
applycond isoeok to  isomer
ratespectrum isomer 2048 0 122879
#

here is an example where we ask for the raw gammasphere
rate spectrum and a related rate where two conditions
have to be fulfilled. Note that we really do not use
the 'isomer' pev for anything, but to apply conditions 
to.

----------------------------------------
option: mkdssdmap GN file

When working with dssd (strip) detectors, it is useful to
to specify the VSNs and channel numbers in a simpler form
than through a lengthly list of 'ferapev' lines
in the chat script. mkdssdmap allows you to do just that
and specify thresholds, gains and offsets as well. A dssd map file
would typically look something like this:

81 0 1 10 0 1
81 1 2 10 0 1
81 2 3 10 0 1
81 3 4 10 0 1
81 4 5 10 0 1
81 5 6 10 0 1
81 6 7 10 0 1
81 7 8 10 0 1
81 8 9 10 0 1
81 9 10 10 0 1
81 10 11 10 0 1
81 11 12 10 0 1
.
.
.
85 10 75 10 0 1
85 11 76 10 0 1
85 12 77 10 0 1
85 13 78 10 0 1
85 14 79 10 0 1
85 15 80 10 0 1

The collums are: VSN-number channel strip_number threshold offset gain

Example:

mkdssdmap FD FD.dssdmap
devmatrix FD001 FD080 FDdssd 512 0 4096
mkdssdmap BD BD.dssdmap
devmatrix BD001 BD080 BDdssd 512 0 4096
hit2dmat FD001 FD080 BD001 BD080 HitDecay 20
binpev1d HitDecay_emax 512 1 4096

Here FD.dssdmap and BD.dssdmap specifies the map for the
forward and backward strips on a dssd detector. The forward
strips will be assigned pev names: FD001 to FD080 and the
backward strips will be assigned pev names: BD001 BD080
(the first generic name is from the second argument in the
mkdssdmap chatscript commmand and the three digit number is
from the third collumn of the mapfile). Thus, a 2D hit
matrix is declared on the 5'th line. The processing of the
hitmatrix will also make one extra pev: HitDecay_emax
(_emax is appended to the 2D hitmatrix name). This pev is
the max energy deposited in any strip in an event. We
typically use this value as the implant energy.

You can also 'primary' gate the DSSD energies with associated
times by adding the gating_pev lo and hi values as in this
example DE1_e.dssdmap file:

34  0  1 10 0 1 DE1_t001 10 8000
34  1  2 10 0 1 DE1_t002 10 8000
34  2  3 10 0 1 DE1_t003 10 8000
34  3  4 10 0 1 DE1_t004 10 8000
34  4  5 10 0 1 DE1_t005 10 8000
.
.
.

which is invoked as

mkdssdmap DE1_t DE1_t.dssdmap
mkdssdmap DE1_e DE1_e.dssdmap

the DE1_t001,DE1_t002,... pevs were declared in the DE1_t.dssdmap
file and are now used to gate the energies declared in the DE1_e.dssdmap.
Naturally, the DE1_t DE1_t.dssdmap must be used first or GSSort will
not be able to find the DE1_t001,DE1_t002... pevs. It will check and
exit if you do. Notice that the .dssdmap files can have lines with
6 or 9 arguments. With 6 arguments, there will be no 'primary' gating.

Note: it is a feature that pevs that are gated away using this gating
method will not even show up in the 'rew pev' list.

----------------------------------------
option: devmatrix namepevlo namepevhi name nn ylo yhi

Sometimes it is useful to make a matrix of channels of a
segmented detector vs the associated energies. The
devmatrix allows you to do just that. All the pevs from (name)
namepevlo to (name) namepevhi will be on the x axis of the
matrix named 'name' and the values of the pevs (usually
from the ferapev assignments) will be on the yaxis in nn
channels from ylo to yhi.  The matrix x limits runs from 0
to the pev number conversion of (namepevhi-namepevlo+1)

Example

# seven strip detector

ferapev  24  0  s1
ferapev  24  1  s2
ferapev  24  2  s3
ferapev  24  3  s4
ferapev  24  4  s5
ferapev  24  5  s6
ferapev  24  6  s7

# make devmatrix

devmatrix s1 s7 512 0 8000

Note1: for this to work, s1 to s7 in the example must have
been declared with ferapev IN ORDER since GSSort will use
the underlying pev numbering to make this matrix (despite
the fact that you specify pev names as limits).

----------------------------------------
option: hit2dmat namepevlo1 namepevhi1 namepevlo2 namepevhi2 name thresh

2D hit pattern, typically for use with a double sided
silicon strip detector (DSSSD). The use is best illustrated
by the example below:

Example:

# front of seven strip detector
ferapev  24  0  f1
ferapev  24  1  f2
ferapev  24  2  f3
ferapev  24  3  f4
ferapev  24  4  f5
ferapev  24  5  f6
ferapev  24  6  f7
# back of seven strip detector
ferapev  25  0  b1
ferapev  25  1  b2
ferapev  25  2  b3
ferapev  25  3  b4
ferapev  25  4  b5
ferapev  25  5  b6
ferapev  25  6  b7
# make 2D hit pattern
hit2dmat f1 f7 b1 b7 dssd 5

Here we are dealing with a DSSD detector with seven strips
on the front and seven strips on the back. We ask for a 2D
hitpattern with a name of 'dssd'.  The entries in the 2D
hit pattern matrix will be updated if the FERA values is
greater than 5 in both the front and back strips. For this
to work f1 to f7 and b1 b7 must be declared IN ORDER since
GSSort will use the underlying pev numbering to make this
matrix (despite the fact that you specify pev names as
limits).

The processing of the hitmatrix
will also make one extra pev: name_emax (_emax is appended to
the 2D hitmatrix name). This pev is the max energy deposited
in any strip in an event. We typically use this value as the
implant energy.

----------------------------------------
option: overridempevcheck

In the modpev operations, a number of checks are performed
before the operations are performed. E.g., normally "modpev
addconst..." will not add a constant unless the pev you are
adding the constant to has been filled. This is to prevent
the resulting pev from always be filled (with the constant)
in events where the underlying pev was not filled -- and,
thus, give rise to a spike in the binned pev spectrum.
Occasionally it is desirable to bypass these checks. If you
specify 'overridempevcheck' the "modpev addconst..."
operations you request will not be questioned and ALL mpev
operations are ALWAYS carried out no matter what.

note:
you do not normally want to specify this option!

----------------------------------------
option: countpevlevcheck #

for  modpev operations counting pevs,
it may be necessary to evaluate pevs several times
before the 'last generation' is filled. With
countpevlevcheck you can specify how many generations
to follow. There is no harm in setting this value
in the range 2-5; but there is a sorting performance
hit if you set it high and have a lot of pevs in
your sort.

example

countpevlevcheck 1

note: unless you have a counting pev that is
generated from other counting pevs, you need not
use this option.

----------------------------------------
option: pevcond1d pev mask cname

Create a one dimensional condition on pev 'pev' with the
the mask 'mask'. cname is the name of the resulting
condition.  'mask' is a STRING of the form
'lo1-hi1,lo2-hi2,...,lon-hin' - see examples below,
especially the second one. Be careful not to have spaces in
the mask string - or GSSort will not interpret the
pevcond1d sort option properly.

NOTE: In order to use lookup tables in GSSort (which has
some important advantages), the lowest limit that can be
specified is 0 and the max limits is 16383. Thus, you may
have to massage the pev signal you apply the condition to
to be in this range with the modpev sort options!

Example1:

pevcond1d gsppactof 854-974 oktof

oktof will be true if the gsppactof is between 854 and 974.
this condition can be used as e.g.,

applycond oktof to xxclean
applycond oktof to yyclean

Example2:

pevcond1d xxrecoil 1815-1850,2060-2090 oklomass

here two intervals, 1815-1850 and 2060-2090 in a FMA x
spectrum is associated with the maskname 'oklomass' -
taking into account that two charge states are getting
through to the focal plane. This example hints at why we
use a 'mask' rather than just a 'lo' and a 'hi' value in
GSSort in 1D conditions.

----------------------------------------
option: applycond con to pevname

Apply condition named 'con' tp pev 'pevname'.

Examples:
applycond oksumlr to xclean
oksumud to yclean
applycond okrecoil to gammasphere

The last example applies the condition 'okrecoil' (which
in the chat file it was taken from was a 2D condition, but
it could equally well be a 1D condition) to 'gammasphere'.
the pev 'gammasphere' is a special pev that is used to
control any updates of 1D and 2D spectra that contains
gamma rays. I.e, this condition applied to a lot of
spectra in the sort, but NOT any spectra that only contains
FERA data. Those you will have to apply the condition to
individually (or through derived pevs, see modpev).

----------------------------------------
option: pevcond2d pev1 pev2 2dwin cname

Create a 2D condition with name 'cname' by using the 2D
window '2dwin' (created with mk2dwin() and save2dwin from
the GSUtil utility) on the pev pair pev1 and pev2.


Example:

pevcond2d ictot icde recoil.2dwin okrecoil

here we use the 'recoil.2dwin' 2dwin file created with
mk2dwin() and save2dwin on the two pev signals: ictot icde.
the resulting condition is called okrecoil and can be
applied as e.g., 

applycond okrecoil to xxrecoil

notice that applycond doesn't really know whether the
condition you specify is 1D or 2D. To it, a condition
is just a name.

----------------------------------------
option: binpev1d pev len lo hi

utility to bin pseudo vector 'pev' in a spectrum
with length 'len' with lower limit 'lo' and higher 
limit 'hi'. The spectrum will be called the name
you gave for the pseudo event vector when you declared it 
with 'ferapev' or 'mkpev'

example

# bin the xxraw pev in the range 0->4095 in 512 channels.
binpev1d xxraw 512 0  4095

----------------------------------------
option: binpev2d   pevx lenx lox hix    pevy leny loy hiy

makes a 2D histogram of pseudo event vectors 'pevx'
and 'pevy' with length, lo and hi specified as for
binpev1d. The name will be 'name1'X''name2' where

example
mkpev xxraw
mkpev yyraw
.
. (manipulate pev xxraw and yyraw)
.
binpev2d xxclean 512 1500 2500 yyclean 512 1500 2500

In this case, the 2D spectrum will be named "xxcleanXyyclean"

----------------------------------------
option: pevgam2d name    pev nch lo hi     nch lo hi

Utility like binpev2d, but the y axis are gamma rays.
The matrix will have the name 'name' (both as a
root spectrum as well as when conditions are
applied).

#              ---x-----------  --gam----------  
#        name  pev nch  lo      hi    nch lo hi
pevgam2d xxgam xxclean 512 1700 2200 2048 0 2047

You could add a prompt time condition to this
matrix as e.g., 

mktimemask rfprompt 3887-4090
applyrftimemask rfprompt to xxgam

and the matrix will have the same conditions as xxclean

----------------------------------------
option: cleanmultlim # #

Clean germanium multiplicity limits. Events not fulfilling
this requirement are not binned.

example
cleanmultlim 3 25

----------------------------------------
option: dirtymultlim # #

Dirty germanium multiplicity limits. Events not fulfilling
this requirement are not binned. Dirty multiplicity also
includes clean modules (so it is really clean+dirty)!

example
dirtymultlim 5 30

----------------------------------------
option: totalmultlim # #

Clean germanium + Dirty germanium + BGO multiplicity limits.  Events
not fulfilling this requirement are not binned.

example
totalmultlim 5 50

----------------------------------------
option: mktimemask mname mask

make a timer mask called 'mname' with the mask specified by
the 'mask' string. This option is easy to understand by two
examples:

mktimemask rfprompt 3887-4090
mktimemask delayed 3600-3675,3770-3837,3881-3928

The first mask is a simple condition: some time has to be
between  3887 and 4090 (e.g., a ge prompt time requirement). The
'delayed' time mask, specifies ranges that a time must be
in to be declared 'delayed' (in this case avoiding other
beam bursts).

These time masks can be applied to gamma gamma matrices
with the 'applyrftimemask' and 'applydttimemask' instructions.

----------------------------------------
option: applyrftimemask mask to matrix

require the the germanium times of the two gamma rays to be updated
in matrix 'matrix' are in the mask 'mask' before the matrix
is updated. This is typically a prompt gate, but could also
be a delayed gate.

example:

ggmatrix mlogg 2048 0 2047
mktimemask rfprompt 3887-4090
applyrftimemask rfprompt to mlogg

Here we apply a rather simple prompt time condition to a matrix.
This could also be a delayed condition.

----------------------------------------
option: applydttimemask mask to matrix

require that the DIFFERENCE between the two gamma rays to be
updated in the matrix 'matrix' is in the time mask 'mask'. E.g.,
a mask like

  mktimemask dtwindow 0-100

would require that all gamma coincidences in the matrix
are within about 100 time units of one another. A mask
like

  mktimemask dtwindow 200-400

would require that the two gamma rays were delayed by
50-100 time units from one another (relatively).
 
----------------------------------------
option: ggmatrix name len lo hi

Make a gamma-gamma matrix, named 'name' with the lenxlen channels
and limits lo->hi in x and y direction. 

Example

ggmatrix m152gg 2048 0 2047
ggmatrix m153gg 2048 0 2047

Here two matrices, m152gg and m153gg,  are made. If nothing
else is specified, they will be identical; but
you can control the update of these matrices by
applying conditions to them with the 'applycond' option.
Here is a typical example: 

pevcond1d xxrecoil 1815-1850,2060-2090 oklomass
pevcond1d xxrecoil 1870-1910,2110,2150 okhimass
pevcond1d xxrecoil 0-8000 okanymass
#
applycond oklomass  to mlogg
applycond okhimass  to mhigg
applycond okanymass to mallgg

Here we have an x spectrum (mass spectrum), xxclean, from the FMA
and we sort gamma rays into the two gg gatrices according to
what mass was observed at the focal plane in coincidence
with the gamma rays.

----------------------------------------




















DATA FORMAT IN GSSORT



The Gammasphere data is extracted using the function:

   get_gsII_ev(&hdr, ev, ext);

where the arguments are defined as

  struct EVHDR    hdr;
  struct EVENT    ev[NGE];
  unsigned short int ext[300];

You should only try to use the event if the return error code was zero!

The EVHDR structure and EVENT structures are defined as:

struct EVHDR
{

  unsigned short int len;       /* total length of event */
  unsigned short int len_clean; /* no of clean ge */
  unsigned short int len_dirty; /* no of dirty ge */
  unsigned short int len_bgo;   /* no of bgo-only */
  unsigned short int ttH;       /* usec-time high bits  */
  unsigned short int ttM;       /* usec-time medium bits*/
  unsigned short int ttL;       /* usec-time low bits   */
  unsigned short int tac1;      /* tac1 */
  unsigned short int tac2;      /* tac2 (RF tac) */
  unsigned short int sumge;     /* ge summed energy */
  unsigned short int sumbgo;    /* bgo summed energy */
  unsigned short int mtm;       /* mtm word */
};

struct EVENT
{
  unsigned short int id;        /* detector id */
  unsigned short int gebit;     /* ge hit bit */
  unsigned short int bgohit;    /* bgo hitpattern */
  unsigned short int ehi;       /* high resolution ge energy */
  unsigned short int pu;        /* pileup bit */
  unsigned short int over;      /* overrange bit */
  unsigned short int tge;       /* germanium time */
  unsigned short int tc;        /* trap corrector */
  unsigned short int elo;       /* low resolution ge energy */
  unsigned short int eside;     /* side chan. energy for seg ge */
  unsigned short int tbgo;      /* bgo time */
  unsigned short int ebgo;      /* bgo energy */
  unsigned short int hs;        /* honeycomb suppress flag */
};

The ext[] array contains the external FERA data collected by the
Gammasphere DAQ (ext[0] says how many words follow); but you do not
need to look at this array yourself. GSSort calls the function

   decode_fera(ext, &nEXT, fera_type,
	       fera_vsn, fera_ch, fera_data);

which will return the extracted 'nEXT' fera data words in the form
of the arrays:

 nEXT;           # fera words            
 fera_type[];	 LeCroy/Silena etc type array 
 fera_vsn[];	 VSN array                
 fera_ch[];	 channel array            
 fera_data[];	 data array               

defined as

  unsigned int    nEXT, fera_type[EXTLEN], fera_vsn[EXTLEN], fera_ch[EXTLEN];
  unsigned int    fera_data[EXTLEN],



SOURCE CODE

The source code for GSSort can be found here

DISPLAYING SHARED MEMORY DATA

To display the data you sort into shared memory, you typically go through a sequence like this:

CHAT FILE EXAMPLES

click here... for a directory with some examples. Since GSSort is changing rapidly, some of the older chat scripts may not work anymore.

ADDING YOUR OWN SORTING CODE

GSSort cannot do everything! There may be some cases where you need to add you own specialized code in oder to do your (on-line) sort properly. Thus, GSSort has provisions for compiling your own code into the sorting code. Four header files:

  UserFunctions.h <-- executed just before main(), put your functions here
  UserDeclare.h   <-- executed just after GSSort declarations
  UserInit.h      <-- excuted just before sort starts
  UserRawEv.h     <-- executed just after raw event has been read
  UserEv.h        <-- executed when GSSort has done its eveluations/binning
  UserExit.h      <-- executed just before GSSort quits

are available for inclusion of your own code into GSSort. If you make useful general additions to GSSort this way, let me know (torben@anl.gov) and I could add it to the standard GSSort code. Click here for an example.

MISC




removed options

--------------------------------------- _ption: isomerdata mod # segments # # # # # # # Instruct GSSort that the data is isomer encrypted from Gammasphere and that the module speciefied is used as an isomer detector. For the segments, specify 1 if the segment detects isomers and 0 if it doesn't. specify -1 if you don't care if segment fired or not. example tac2subbgo 1.0 bgorfoffset 2500 # module # 1 2 3 4 5 6 7(bp) isomerdata mod 1 segments 1 0 0 0 1 1 1 isomerdata mod 2 segments 1 0 0 0 1 1 1 isomerdata mod 3 segments 1 0 0 0 1 1 1 isomerdata mod 4 segments 1 0 0 0 1 1 1 isomerdata mod 6 segments 1 0 0 0 1 1 1 here we are specifying that modules 1,2,3,4 and 6 (not 5) are used as isomer modules. We also specicy that we want to see at least one hit in segments 1,5,6,7 to accept isomers, but reject if we see any hits in segments 2,3,4 (which are away from the forward beam pipe). If you specified isomerdata mod 1 segments 1 -1 -1 -1 1 1 1 you would just require a hit in any of the segments 1,5,6,7 but segments 2,3,4 would nolonger veto the event as being tagged as an isomer. With the 'tac2subbgo' and 'bgorfoffset' we make sure the bgo times are with respect to the RF pulse (since the EFFs do not do rf timing for BGO detectors!) The iomer data will be available as regular pev vectors with VNS numbers == module numbers and with the BGO energy and time in channels 1 and 2, respectively. Thus, for the above example, you can use ferapev to access the data as ferapev 1 1 iso1e ferapev 1 2 iso1t 0 198 1.0 ferapev 2 1 iso2e ferapev 2 2 iso2t 0 198 1.0 ferapev 3 1 iso3e ferapev 3 2 iso3t 0 75 1.0 ferapev 4 1 iso4e ferapev 4 2 iso4t 0 199 1.0 ferapev 6 1 iso6e ferapev 6 2 iso6t 0 179 1.0 (here the times are aligned through the ferapev assignment) note: this option should only be used if the EFFs have the isomer tag mode flag on and you have a recoil stopper foil between the forward BGO detectors. It would not make sense to write out clean BGO detectors and have the isomer tag mode flag on at the same time. Click here for more info on the isomer tagged data mode --------------------------------------- _ption: mkisomerfromfull Sometimes we will write all data out rather than use the isomer tag modeflag for isomer tagged data (so that we have all information to play with off-line). In that case, this option will make GSSort extract the isomer modules (specified by the 'isomerdata' option) from the clean BGO data stream and pack it into the 'fake' external format described under the 'isomerdata' option. The isomer modules will be removed from the clean BGO data stream (where they do not logically belong in this this tagging mode).