Quick Introduction to cscan

1
Quick Introduction to cscan
cscan correlates raw adc (energy) and tdc (time)
data from experiments to specific detectors
and writes spectra (.spe), matrices (.mat),
and/or cubes (.cub) that can be read in the
Radware software. The adc/tdc data can be read
from a FIFO buffer on-line, or from one or more
files off-line. cscan is very well documented.
If you need help 1. Look at the
web http//wnsl.physics.yale.edu/cscan/ 2.
Look at the users manual that should be in the
data room. 3. Ask someone (Jo or John Ai)
2
Data Acquisition
Save to disk run000.raw.gz
scaler
ADC
controller
ADC
ADC
TDC
TDC
TDC
Send raw data to Roo for JAM
(assemble)
Save to disk run000.wnsl.gz cscan offline
VMEacquire.c
FIFO ( 4 kb)
iotwo
cscan online
3
Events
WNSL format
HEADER scaler id,data scaler id,data adc
id,data adc id,data tdc id,data tdc
id,data HEADER scaler id,data scaler id,data adc
id,data adc id,data tdc id,data tdc
id,data HEADER scaler id,data scaler id,data adc
id,data adc id,data tdc id,data tdc id,data
scaler
ADC
controller
ADC
ADC
TDC
TDC
TDC
id 0 -31
id 0 -31
id 0 -31
id 64 -95
id 64 -95
id 32 - 63
id 32 - 63
VMEacquire.c
assemble
iotwo
4
Cscan commands
online cscan --online --ws (default is
10) --wm (default is 3600) offline cscan
--file filename where filename is
run000.wnsl.gz run000.wnsl
/data/jo/run000.wnsl.gz thisismyfile
thisismyfile.gz cscan --listfile
filename where filename is a text file
containing a list of runs to
sort --presort filename --interval
5
write .spe, .mat, .cub and quit hist_paramsnum
_histograms
allocate memory for histo- grams defined
in wnsluser.inc USER_HIST hist_paramsnum_histogr
ams
read wnsluser.inc USER_TERMINATION
read wnsluser.inc USER_DETTYPES detector_typeNUM
_DETECTOR_TYPES
read detfile detector_infonum_detectors
increment histograms histogram_ptr
read corrections correction_infoNUM_DETECTOR_TYPE
S
make standard histograms and read wnsluser.inc
USER_CODE
read adcgains adc_infoNUM_ADCS
raw data gt data_itemnum_data_items corrected
data gt hitnum_hits
read tdcgains tdc_infoNUM_TDCS
read wnsluser.inc USER_VAR
each event
read wnsluser.inc USER_INIT
6
Example Event
HEADER (16 bytes) scaler 00 1568865 scaler 01
5261 adc 00 1045 adc 03 452 adc 04 986 adc 05
782 adc 06 2045 adc07 1965 tdc 00 2214 tdc 03
2082 tdc 05 2737 tdc 07 1367
scaler
ADC
controller
ADC
ADC
TDC
TDC
TDC
id 0 -31
id 0 -31
id 0 -31
id 64 -95
id 64 -95
id 32 - 63
id 32 - 63
HEADER scaler id,data scaler id,data adc
id,data adc id,data tdc id,data tdc id,data
VMEacquire.c
assemble
iotwo
7
cscan raw data array
cscan counts the number of data items, and fills
an array num_data_items
data_itemi.data_type DATA_TYPE_SCALER DAT
A_TYPE_ADC DATA_TYPE_TDC data_itemi.id data_
itemi.data where i 0 to (num_data_items
1) scaler_dataj where j 0, NUM_SCALERS 1
(NUM_SCALERS 8) adc_dataj where j 0,
NUM_ADCS 1 (NUM_ADCS 128)
tdc_dataj where j 0, NUM_TDCS 1 (NUM_TDCS
128) wnsluser.c
8
cscan raw data array
HEADER (16 bytes) scaler 00 1568865 scaler 01
5261 adc 00 1045 adc 03 452 adc 04 986 adc 05
782 adc 06 2045 adc07 1965 tdc 00 2214 tdc 03
2082 tdc 05 2737 tdc 07 1367
num_data_items 12
i data_itemi.data_type data_itemi.id
data_itemi.data 0 DATA_TYPE_SCALER 00
1568865 1 DATA_TYPE_SCALER 01
5261 2 DATA_TYPE_ADC 00
1045 3 DATA_TYPE_ADC 03
452 4 DATA_TYPE_ADC 04
986 5 DATA_TYPE_ADC 05
782 6 DATA_TYPE_ADC 06
2045 7 DATA_TYPE_ADC 07
1965 8 DATA_TYPE_TDC 00
2214 9 DATA_TYPE_TDC 03
2082 10 DATA_TYPE_TDC 05
2737 11 DATA_TYPE_TDC 07 1367
9
cscan corrections
Now cscan has all of the raw scaler, adc, and
tdc data. Cscan can make histograms of the raw
data, but very often we will want to modify
the data before we look at it. For example, if
we have an experiment involving Ge detectors, we
will want gain shift the adc data (make it so
each detector has the same number of keV/channel)
and shift the tdc data (make it so that
the timing peak is in the same channel, then
select only times within a certain range.) cscan
doesnt change the adc/tdc data it sees how the
user wants the data modified, then writes the
modified data into a new histogram denoted by the
detector name. Example one clover, two
coaxial and one particle detector adc00,
adc01, adc02, adc03, adc04, adc05, adc07
tdc00, tdc01, tdc02, tdc03, tdc04, tdc05,
tdc06 leaf01, leaf02, leaf03, leaf04, clov01,
coax01, coax02, part01, leaft01,
leaft02, leaft03, leaft04, clovt01, coaxt01,
coaxt02, partt01
10
cscan files
There are 12 files for cscan
Different for every experiment!
Typically not changed.
11
detfile
The detfile consists of a list of detector types
and the adc/tdc assignments. The general format
is
detector type id adc adc_id tdc tdc_id
theta theta_value ring ring_value rowcol
row column elements leaf1 leaf2 leaf3 leaf4end
Each entry is optional.
12
detfile array
Cscan counts each detector and fills a structure
array with all of the detector
information (done in wnsluser.c)
num_detectors (MAX_DETECTORS
512) detector_infoi.type detector_infoi.id de
tector_infoi.has_adc detector_infoi.adc detect
or_infoi.has_tdc detector_infoi.theta detector
_infoi.ring detector_infoi.column detector_inf
oi.element0, detector_infoi.element1,
detector_infoi.element2, detector_infoi.ele
ment3,
where i 0 to (num_detectors - 1)
13
A few examples
c c clover 1 c
detector leaf 01 adc 00 tdc 00 theta
133.5 end detector leaf 02 adc 01 tdc
01 theta 143.5 end detector leaf 03 adc
02 tdc 02 theta 143.5 end detector leaf
04 adc 03 tdc 03 theta 133.5 end
detector clov 01 elements 01 02 03 04 end
c c solar cells c
detector focal_he 01 adc 00 tdc 00
rowcol 1 1 end detector focal_le 01 adc 96
tdc 00 rowcol 1 2 end detector focal_he
02 adc 01 tdc 01 rowcol 1 3 end
detector focal_le 02 adc 97 tdc 01
rowcol 1 1 end
c c coaxial 1 c
detector coax 01 adc 00 tdc 00 end c
c tac c time between recoil c and
delayed gammas c detector tac 01
adc 10 end
14
Standard detector types
coax leaf badleaf leps part focal_le
focal_he macy isomer_coax hex bafl tac
clov isomer_clov
But adding a new kind of detector is easy see
the on-line manual http//wnsl.physics.yale.ed
u/cscan/
15
corrections
After reading the detfile, cscan knows what adcs
and tdcs belong to each detector. But
sometimes the raw data has to be modified the
corrections file tells cscan which detector data
need to be changed. The general format is
detectortype type gain gain must
have adcgains file! beta beta must
have theta defined in detfile! energycut
low_ch high_ch timeposition
time_central_channel must have tdcgains file!
timecut low_ch high_chend
Again, every entry is optional.
16
corrections array
Cscan fills another structure array with all of
the correction information (done in wnsluser.c)
correction_infoi.gain_match correction_infoi.g
ain correction_infoi.time_shift correction_info
i.position correction_infoi.doppler_correct cor
rection_infoi.beta correction_infoi.energy_cut
_min correction_infoi.energy_cut_max correction_
infoi.time_cut_min correction_infoi.time_cut_m
ax
where i 0 to (NUM_DETECTOR_TYPES 1)
17
corrections gain adcgains
The gain parameter is used to define how many
keV/channel are wanted. The adcgains file is
needed for this! (Note gf3 (Radware) will
display 0.5 keV/channel by default.) The adcgains
file is a list of adc id, followed by gain
parameters. There are three options
1. linear fit for channels and energies
(energy channel slope intercept)linearadc_
id intercept_value slopeadc_id
intercept_value slope 2. quadratic fit for
channels and energies (energy channel2 a
channel b c)quadraticadc_id c b
aadc_id c b a 3. interpolated linearly
between two or more calibration
pointslinterpadc_id energy1 channel1
energy2 channel2 energy3 channel3adc_id
energy1 channel1 energy2 channel2
energy3 channel3
18
adcgains array
Cscan fills a structure array with all of the adc
gain information (done in wnsluser.c)
NUM_ADCS
(NUM_ADCS 128) adc_infoi.mode ad
c_mode_none adc_mode_quadratic adc_mode_linea
r adc_mode_linterp adc_infoi.a,
adc_infoi.b, adc_infoi.c, adc_infoi.num_pts
adc_infoi.energyMAX_NUM_PTS
(MAX_NUM_PTS 5) adc_infoi.channelMAX_NUM_PTS
where i 0 to (NUM_ADCS - 1)
19
corrections gain adcgains example
A common problem is assigning a gain value in
corrections, but not having the the adc in the
adcgains file
BAD (cscan will crash and complain) ERROR ADC
gain needed for gainmatching is
undefined detfile
corrections
adcgains detector coax 01 detectortype
coax linear adc 03 gain 0.5
00 -42.345 0.512 tdc 03
end
01 -34.789 0.546 end
04
-56.890 0.786 GOOD detfile
corrections
adcgains detector coax 01 detectortype
coax linear adc 03 gain 0.5
00 -42.345 0.512 tdc 03
end
01 -34.789 0.546 end
03
-7.8790 0.891
20
corrections timeposition tdcgains
The timeposition parameter is used to define what
channel the tdcs should be shifted to. The
tdcgains file is needed for this! The tdcgains
file is a list of tdc id, followed by which
channel the peak is in. cscan will calculate
how much each channel needs to be shifted.
corrections detectortype coax timeposition
1500 end tdcgains offset 00 1532 01 1241
detfile detector coax 01 adc 00 tdc
00 end detector coax 02 adc 01 tdc 01 end
tdc 00
1532
tdc 01
1241
21
tdcgains array
cscan fills a structure array with all of the tdc
gain information (done in wnsluser.c)
NUM_TDCS
(NUM_TDCS 128) tdc_infoi.mode td
c_mode_none tdc_mode_offset tdc_infoi.
offset
where i 0 to (NUM_TDCS - 1)
22
corrections energycut, timecut
The energycut and timecut parameters can be used
to select a specified energy or time range.
The detectors energy or time must be within this
range to be incremented. This will be more clear
in a moment
corrections detectortype coax timeposition
1500 timecut 1300 1700 end tdcgains offset 00
1532 01 1241
detfile detector coax 01 adc 00 tdc
00 end detector coax 02 adc 01 tdc 01 end
coaxt01
1500
coaxt02
1500
23
timecut is important for reducing randoms!
24
cscan corrected data array
Remember that cscan counted the number of data
items, and filled an array. Now cscan uses the
information from detfile, corrections, adcgains,
and tdcgains modify the data and fill a new array
-- Cscan counts the number of detector hits and
fills a new array. Some important aspects If
both an adc and a tdc are defined in detfile,
both this adc and tdc must be present in
the event to count as a hit. If energycut or
timecut are used in corrections, the energy or
time must be within the defined window to
count as a hit. num_hits hitihit.type
hitihit.theta
folddet_type hitihit.id
hitihit.ring hitihit.energy
hitihit.row hitihit.time
hitihit.column
hitihit.element_fold where ihit 0 to
(num_hits 1)
25
Think of it like asking a bunch of questions
cscan loops through each detector and
asks -- is there data in the adc and tdc for
this detector? detfile if yes, then
continue if no, quit -- does the adc (energy)
data need to be gainmatched? corrections and
adcgains if no, continue if yes, gainmatch,
then continue -- does the energy data need to be
doppler corrected? corrections and detfile if
no, continue if yes, doppler correct, then
continue -- is there only a specific range of
acceptable energies? corrections if no,
continue if yes, check, then continue if within
range, otherwise quit -- does the tdc (time) data
need to be shifted? corrections and tdgains if
no, continue if yes, shift, then continue -- is
there only a specific range of acceptable times?
corrections if no, continue if yes, check,
then continue if within range, otherwise
quit made it to the end make a hit
26
Cscan corrected array
scaler_data0 1568865 scaler_data1
5261 num_hits 5 ihit hitihit.type
hitihit.id hitihit.energy
hitihit.time 0 leaf 01
547 2109 1 leaf
03 188 2116 2 coax
02 427 2305 3 tac
01 2045 4 clov
01 736 2109
27
wnsluser.inc
Now cscan has all of the information from an
event stored in arrays. Some of this information
can be used to make histograms (spectra, matrices,
cubes) right away, but some will have to be
modified more. The user-defined histograms and
sorting routines are done in wnsluser.inc. This
file consists of the following parts wnsluser.inc
ifdef USER_HIST ifdef USER_DETTYPES histogra
m declarations detector types endif endif
ifdef USER_VARS ifdef USER_INIT user
variables code to be read once at the
beginning endif endif ifdef
USER_CODE ifdef USER_TERMINATION user
code code to be read once at the
end endif endif
28
USER_HIST
Before histograms can be filled, they must be
declared The format is name start_id
end_id dimensions channels Spectra (.spe)
to be read in gf3 tot_proj -1 -1 1 4096
tot_proj.spe clov 01 10 1 4096
clov01.spe, clov02.spe,
clov10.spe Matrices (.mat) to be read in gf3m
(4k x 4k only), xmesc (4k x 4k only), or DAMM
(any size) ggmat -1 -1 2 4096
4096 ggmat.mat sc_tac 01 10 2 4096
4096 sc_tac01.mat, sc_tac02.mat, Cubes(.cub)
to be read in xmlev gggcub -1 -1 3 871
871 871 gggcub.cub (see web for DAMM and cube
instructions)
29
USER_CODE
The array holding the detector data can be used
to create user-defined spectra or matrices
for (ihit 0 ihit lt num_hits ihit) if
((hitihit.type clover) (hitihit.type
coax)) for (jhit 0 jhit lt num_hits
jhit) if ((hitjhit.type clover)
(hitjhit.type coax)) if (ihit ! jhit
) inc_ggmat(hitihit.energy,
hitjhit.energy) Note that ihit is
just a counter, going from zero to (num_hits 1)
you can use i or whatever you want! The
following must also be added under
USER_HIST ggmat -1 -1 2 4096 4096
30
cscan histogram array
Cscan counts the number of histograms listed in
USER_HIST, and saves all of the histogram
information in an array num_histograms hist_pa
ramsi.name hist_paramsi.xlen
hist_paramsi.start_id hist_paramsi.ylen
hist_paramsi.end_id hist_paramsi.zlen
hist_paramsi.dim hist_paramsi.entry_size
hist_paramsi.total_entries where i 0 to
(num_histograms 1). This information is used
to point to a specific area of computer
memory where data for each channel of the
histogram is stored. histogram_ptr(name, id, x,
y, z) When a histogram is incremented
(inc_hisname) or decremented (dec_hisname) in
USER_CODE, the number of counts in the specific
channel(s) change by one unit.
31
write .spe, .mat, .cub and quit hist_paramsnum
_histograms
allocate memory for histo- grams defined
in wnsluser.inc USER_HIST hist_paramsnum_histogr
ams
read wnsluser.inc USER_TERMINATION
read wnsluser.inc USER_DETTYPES detector_typeNUM
_DETECTOR_TYPES
read detfile detector_infonum_detectors
increment histograms histogram_ptr
read corrections correction_infoNUM_DETECTOR_TYPE
S
make standard histograms and read wnsluser.inc
USER_CODE
read adcgains adc_infoNUM_ADCS
raw data gt data_itemnum_data_items corrected
data gt hitnum_hits
read tdcgains tdc_infoNUM_TDCS
read wnsluser.inc USER_VAR
each event
read wnsluser.inc USER_INIT
32
HELP
Cscan is very well documented. If you need help
1. Look at the web http//wnsl.physics.yale
.edu/cscan/ 2. Look at the users manual that
should be in the data room. (A copy is also
on the data room PC users/jo/New_shift_guide.doc
) 3. Ask someone (Jo or John Ai) Cscan is
small everyone has a copy of the entire
program. Read it, play with it, make mistakes
with it. Another copy can always be made you
cant hurt it!
33
EXTRA
Cscan makes one big hit array of all detector
types rather than smaller, separate arrays. This
was done to make it easy to add and subtract
detector types. The old wnsl sorting routines
used tscan consisting of many small arrays for
each detector type. Adding detectors was a
pain. However, some experiments (like those
involving SASSYER) use many different detectors,
requiring multiple coincidences. Scrolling
through the hit array numerous times
quickly becomes confusing.
34
EXTRA
for (ihit 0 ihit lt num_hits ihit) if
(hitihit.type coax)
coax_energycoax_fold hitihit.energy
coax_timecoax_fold hitihit.time
coax_fold ge_energyge_fold
hitihit.energy ge_timege_fold
hitihit.time ge_fold if
(hitihit.type clov)
clov_energyclov_fold hitihit.energy
clov_timeclov_fold hitihit.time
clov_fold ge_energyge_fold
hitihit.energy ge_timege_fold
hitihit.time ge_fold if
(hitihit.type leaf)
leaf_energyleaf_fold hitihit.energy
leaf_timeleaf_fold hitihit.time
leaf_fold if (hitihit.type
leps) leps_energyleps_fold
hitihit.energy leps_timeleps_fold
hitihit.time
tcon.inc tscan style, for Con / do
gamma-particle-tac triple coin. / for
(i0iltge_fold i) if ((part_fold gt 1)
(tac_fold gt 1)) if ((tac_data0 gt 1000)
(tac_data0 lt 2500))
inc_gecoin(ge_energyge_fold)