$Id: GSSort.html,v 1.5 2003/01/13 22:42:15 tl Exp tl $
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!!!!)
This program is under development, so expect frequent updates and new interesting bugs in short order...
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.
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).
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' printeventssee GSUtil utilities for options to control GSSort from inside rootn.exe.
---------------------------------------- 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 addto 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:
- rootn.exe
- .L ~tl/bin/GSUtil_cc.so (you may have to add a version here)
- sload("gs.map");
- mkcanvas();
- d1("hitpat") etc, etc
- d2("ppac_xx_yy");
- etc, etc....
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 quitsare 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).