Markhits Package for Sunsort

Relies on: ADCs Structure Sunsort
C include file: hitsubs.h
FORTRAN include files: subs.i and hitsubs.i

This package provides a fast way to identify which parts of a large detector system have been involved in an event. This, coupled with the almost object orientated approach of the Structure package, provides a very flexible and sophisticated approach to processing events. The clever way in which it is coded avoids many of the overheads associated with traditional sorting approaches, consequently it can be faster than a standard sort code (particularly when the event processing is simple so standard sort codes spend most of their time finding which detector elements have fired).

This package activates the following variables in struct detectors:

hits: The number of children of this node that were hit in an event
hitlist.head: a pointer to the first child of this node that was hit.
hitlist.next: a pointer to the next node at this level that was hit
gain: multiplicative factor for gain correction
offset: offset for gain correction
threshmin: The lowest raw adc value that will be counted as a hit
threshmax: The highest raw adc value that will be counted as a hit
value: The adc reading after correction with gain and offset

gain, offset, threshmin and threshmax may be read and written. value may also be read and written, but it's usually treated as read only as its contents are reset for each event. hits and hitlist must never be written to.

When an event is processed with this package, it first finds which ADCs have been hit, it propagates the hits up the tree so that at each level, the hit variable holds the number of immediate sub-elements that were hit. For example, if in an event in the example experiment structure given in the description of the structure package caused signala, signalat, signalb and signalbt of the first pssd to be hit, and signale and signalet of the second monitor to be hit, then those elements would have hit set to one and all other signal elements would have hit set to zero. The first pssd would have hit set to four, the second pssd would have hit set to zero, the first monitor would have hit set to zero and the second monitor would have hit set to two. At the top level, experiment would have hit set to two.

The members of hitlist could be used to traverse the experiment structure to find just the elements that have been hit and to process them, but in practice, it's much easier to use the detector_event() call which does all the hard work for you and then calls the right routine for the detector type that's been hit. The key to getting fast processing is to get this detector processing working properly. See the section Detector Routines later for more details.

Routines

int initmarkhits(struct detectors *dp, int nadcs)
integer function initmarkhits(integer nadcs)

This routine initialises the markhits package for use. It must be called before markhits() or markhitslist() is called.

On entry to the C routine, dp should point to the top of the experiment tree. The FORTRAN routine always refers to the top of the default experiment tree.

On entry nadcs should hold the highest ADC number used in the experiment.

Returns 0 on success and <0 on failure.

void markhits(short adc);
subroutine markhits(integer2 adc(*))

This routine marks the experiment tree with which elements have been hit. It then propagates the hits up the tree so that every element has the correct hits value. adc should be the adc array that was passed to the sort code. This call is deprecated, it's much faster to call markhitslist().

void markhitslist(short adclist, short adc);
subroutine markhitslist(integer2 adclist(), integer2 adc())

This routine does the same thing as markhits only faster. Adclist and adc should be the list of which adcs have fired, and their values as passed to the sort code.

int loadgainoffset(char filename);
integer function loadgainoffset(character(*) filename)

Load the gains and offsets from the file specified in filename. The file should consist of a series of lines of the form:

adc gain offset

where adc is the adc number (integer) and gain and offset are the (real) gain and offset to use for that adc. Lines in the file that start with # or that are blank are ignored. This call returns 0 if all went well, 1 if there was an error. If this call isn't made, or if the file couldn't be found then the gains and offsets will default to 1.0 and 0.0 respectively. Similarly, any adcs not mentioned in the file will have their gains and offsets default to 1.0 and 0.0.

int loadthresholds(char filename);
integer function loadthresholds(character(*) filename)

Similar to loadgainoffsets except it loads the thresholds from file. The file format is

adc min max

The defaults values for min and max are 1 and something slightly over 250,000,000 respectively. If you feel that hits which give a reading of zero are important and should be processed, then you should set the minimum threshold to 0.

int detector_event(int proc, struct detectors *dp);
integer function detector_event(integer proc)

Process an event by calling the event handling routines set with setdetprocs. Only those elements that were hit in this event are called. Proc is an integer that is passed to the detector routines to allow you to chose what processing is done. See the section Detector Routines later for more details. The return value is that of the last detector routine that was called.

The C routine should pass the top of the experiment tree in dp. The FORTRAN routine always refers to the top of the default experiment tree.

void event_dump(struct detectors *dp, int indent);
subroutine event_dump(integer indent)

Dumps out which bits of the event structure have been hit and the value of hits. Also, for those elements which have adcs associated with them (that is, have had their adcnum set to something other than -1), it dumps the adc number, the raw value and the processed value.

You can pass a pointer to the top of a sub-tree in the C routine to just dump out part of an experiment. The FORTRAN routine always dumps out the whole experiment.

void plot_chanspecs(int plot_type, struct detectors *dp, int sp2_channsa, int sp2_channst);
subroutine plot_chanspecs(integer plot_type, integer sp2_channsa, integer sp2_channst)

Routine to generate some standard spectra very quickly.

sp2_channsa and sp2_channst hold the numbers of the 2d spectra used for the plots of energy like signals and time like signals respectively.

On entry, plot_type should be set equal to one of the following symbols to get the listed effect.

PLOT_2D: Plot raw adc values as a function of channel number into the 2d spectra.
PLOT_2DC: Plot the calibrated values as a function of channel number into the 2d spectra.
PLOT_A: Plot the raw energy like signals into 1d spectra with channel 1 in spectrum 1 etc. Also do PLOT_2D as well.
PLOT_T: Plot the raw time like signals into 1d spectra with the time corresponding to energy channel 1 in spectrum 1 etc. Also do PLOT_2D as well.
PLOT_AT: Equivalent to PLOT_A and PLOT_T with both energy and time going on the same spectrum. Both are divided by 2 and the time has 4096 added to push it to the top of the spectrum. Also do PLOT_2D as well.
PLOT_AC: As PLOT_A but with calibrated values (so 2d plot is equivalent to PLOT_2DC).
PLOT_TC: As PLOT_A but with calibrated values (so 2d plot is equivalent to PLOT_2DC).
PLOT_ATC: As PLOT_A but with calibrated values (so 2d plot is equivalent to PLOT_2DC).

To do: Find a more flexible way of specifying which channels are ADCs and which are TDCs.

FORTRAN only routines

The following get and set routines are provided for use in FORTRAN codes. Their syntax is the same as similar routines provided in the ADCs and Structure packages.

double precision function getgain(...)
double precision getthisgain()
subroutine setgain(double precision value, ...)
subroutine setthisgain(double precision value)
double precision function getoffset(...)
double precision getthisoffset()
subroutine setoffset(double precision value, ...)
subroutine setthisoffset(double precision value)
integer function getthreshmin(...)
integer getthisthreshmin()
subroutine setthreshmin(integer value, ...)
subroutine setthisthreshmin(integer value)
integer function getthreshmax(...)
integer getthisthreshmax()
subroutine setthreshmax(integer value, ...)
subroutine setthisthreshmax(integer value)
double precision function getvalue(...)
double precision getthisvalue()
subroutine setvalue(double precision value, ...)
subroutine setthisvalue(double precision value)

integer function detectorhitlistnext(): Move to next hit element at this level
integer function detectorhitlisthead(): Move to first hit element at next level

Steven M. Singer

Last modified: Thu Sep 30 20:40:32 BST 1999

Markhits Package for Sunsort

Routines

int initmarkhits(struct detectors *dp, int nadcs) integer function initmarkhits(integer nadcs)

void markhits(short *adc); subroutine markhits(integer*2 adc(*))

void markhitslist(short *adclist, short *adc); subroutine markhitslist(integer*2 adclist(*), integer*2 adc(*))

int loadgainoffset(char *filename); integer function loadgainoffset(character*(*) filename)

int loadthresholds(char *filename); integer function loadthresholds(character*(*) filename)

int detector_event(int proc, struct detectors *dp); integer function detector_event(integer proc)

void event_dump(struct detectors *dp, int indent); subroutine event_dump(integer indent)

void plot_chanspecs(int plot_type, struct detectors *dp, int sp2_channsa, int sp2_channst); subroutine plot_chanspecs(integer plot_type, integer sp2_channsa, integer sp2_channst)