Getting Started
Last updated: September 11, 2019
This document assumes a fresh install of simpleScan and that the user will be running the program from a clean directory (e.g. from inside ./scan/). I'll also assume that the user has built the source in the directory /opt/SimpleScan/. Your build may be located elsewhere, but note that it will change the relative paths.
Running simpleScan with no arguments results in an error
simpleScan
NOTE: As of version 6, ROOT will throw an error complaining that it cannot find RootDict_rdict.pcm. This is not actually an error, however, and may be safely ignored. If you wish, you may copy the file from the SimpleScan build directory to wherever you intend to run the program using
cp /opt/SimpleScan/build/dict/RootDict_rdict.pcm ./This will resolve the error, but changes nothing in the actual analysis.
Passing the -h flag to simpleScan will display a list of all command line options. These options are
summarized in the table below.
| Long Option | Flag | Argument | Description |
|---|---|---|---|
| --batch | -b | Run in batch mode (i.e. with no command line) | |
| --config | -c | path | Specify path to setup to use for scan |
| --counts | Write all recorded channel counts to a file | ||
| --debug | Enable readout debug mode | ||
| --dry-run | Extract spills from file, but do no processing | ||
| --fast-fwd | word | Skip ahead to a specified fraction (.xx) or word in the file (start of file at zero) | |
| --stop-point | word | Stop scanning the input file when the specified fraction (.xx) or word is reached | |
| --help | -h | Display this dialogue | |
| --input | -i | filename | Specifies the input file to analyze |
| --output | -o | filename | Specifies the name of the output file. Default is out.root |
| --quiet | -q | Toggle off verbosity flag | |
| --shm | -s | Enable shared memory readout | |
| --version | -v | Display version information | |
| --auto-start | -A | Automatically start scan upon loading input file | |
| --untriggered | -u | Run without a start detector | |
| --force | -f | Force overwrite of the output root file | |
| --online | Plot online root histograms for monitoring data | ||
| --fitting | Use root fitting for high resolution timing | ||
| --cfd | Use traditional CFD for high resolution timing | ||
| --traces | Dump raw ADC traces to output root file | ||
| --raw | Dump raw pixie module data to output root file | ||
| --stats | Dump event builder information to the output root file | ||
| --record | Write all start events to output file even when no other events are found | ||
| --parameters | list | Set default fitting/CFD parameters by supplying comma-delimited string | |
| --force-traces | Change all entries in map file to type 'trace' to do trace analysis | ||
| --output-prefix | prefix | Set the output file prefix (default is ./) |
Let's start by resolving the first error that we saw in the section above.
MapFile: ERROR! Failed to open input map file!
Scanner: Failed to read map file './setup/map.dat'.
By default, simpleScan looks for all configuration files in the directory ./setup/. This may be changed
by using the -c flag as detailed in the table above. For simplicity, let's create a new directory named
setup and copy the default configuration files there.
mkdir setup
cp /opt/SimpleScan/config/* ./setup/Now let's attempt to run it again, this time we use batch-mode (to avoid brining up the interactive terminal)
simpleScan -b
That worked. But, after everything is initialized, the program pauses because it doesn't know what to do
(use ctrl^c to kill it). We need to specify an input file for simpleScan to process using the -i flag. I
assume you have some generic Pixie data lying around. The contents don't really matter at this point, we
will look more into the specifics later. I'll be using a file named data.ldf for the following examples.
simpleScan -i data.ldf -bNow we have a new error
Scanner: Failed to open output root file 'out.root'!
SimpleScan will not overwrite existing output files, unless the user forces it to do so. This is a safety
catch to make sure you don't accidentally overwrite existing output files or, god forbid, overwrite a
binary data file if you accidentally swap the input and output filenames (obviously very bad). If you
want to overwrite output files, use the -f flag. We may also specify the output filename using the -o
flag
simpleScan -i data.ldf -o data.root -fb
The scan will output header information from the input file and will then start to process data. Since we're using the example simpleScan configuration files, we know that whatever simpleScan is doing is probably nonsense. Let's update the config files to suit our needs.
Let's look at the example map file we copied from the build directory (./setup/map.dat).
# Example simpleScan detector map file.
# Author: Cory R. Thornsberry (Oct. 4, 2018)
# - Entries must be delimited with SPACES!
# - Blank lines and text following a # are ignored.
# - Empty channels DO NOT need to be defined here.
# Syntax:
# MOD CHAN TYPE:SUBTYPE:TAG(S)
#0 0 hagrid::start # This line is commented and will be ignored
0 0 trigger::start # Detector TAG "start" indicates that this is the global start detector
0 1 trigger::start # Multiple starts are allowed (e.g. double-sided beta starts etc.)
0 14 logic::untriggered # Logic signal, does not require coincidence with start detector due to "untriggered" TAG
1 0:15 genericbar:: # Generic bar type detectors (e.g. VANDLE) defined for channels 0-15 in module 1
2 0:9 liquidbar:: # Generic liquid bar type detectors (e.g. SABRE) defined for channels 0-9 in module 2
# Double-sided PSPMT bar definition follows
# TAG="" denotes the DYNODE, TAG=inter-cardinal direction denotes ANODE (e.g. SE, NE, NW, SW)
# SUBTYPE="left" denotes the LEFT side PSPMT, SUBTYPE="right" denotes the RIGHT side
# SUBTYPE="" denotes SINGLE-ENDED detector
3 0 pspmt:left: # Left dynode of a PSPMT bar
3 1 pspmt:right: # Right dynode of a PSPMT bar
3 2 pspmt:left:SE # Left PSPMT bottom right corner
3 3 pspmt:right:SW # Left PSPMT top right corner
3 4 pspmt:left:NE # Left PSPMT top left corner
3 5 pspmt:right:NW # Left PSPMT bottom left corner
3 6 pspmt:left:NW # Right PSPMT bottom right corner
3 7 pspmt:right:NE # Right PSPMT top right corner
3 8 pspmt:left:SW # Right PSPMT top right corner
3 9 pspmt:right:SE # Right PSPMT bottom right corner
Yours may look different if it was updated after this guide was written, but the basic components will be the same. Everything after a # is a comment and will be ignored by simpleScan. The actual lines which define a detector have a layout such as the one shown below.
0 0 trigger::start
It is a space-delimited string with the syntax <module> <channel> <type>:<subtype>:<tags>. The <module>
and <channel> fields are integer values which specify the input Pixie channel. Every detector has a <type>
which corresponds to one of the processor types. Currently there are 9 valid detector types which are summarized
in the table below
| Name | Type | Subtypes | Description |
|---|---|---|---|
| GenericBarProcessor | genericbar | Generic dual-sided bar detector | |
| GenericProcessor | generic | Generic single-sided detector | |
| LiquidBarProcessor | liquidbar | Dual-sided bar detector (w/ PSD) | |
| LiquidProcessor | liquid | Single-sided detector (w/ PSD) | |
| HagridProcessor | hagrid | Gamma-ray detector | |
| LogicProcessor | logic | Logic or pulser input (counting) | |
| PSPmtProcessor | pspmt | left, right | Position sensitive PMT detector (single or dual-sided and w/ or w/o PSD) |
| TraceProcessor | trace | Generic trace analyzer type (useful for in-depth trace analysis) | |
| TriggerProcessor | trigger | Generic trigger type (typically used as the start) |
Some processors may use the tags field for specific purposes, but there are currently two reserved detector tags untriggered and start.
The start tag indicates that the channel is used as a trigger signal which other signals will be timed against. In addition to modifying channel timing, the start signals are also used to build the lists of time-ordered events (referred to as raw events here and in the source code). The raw event builder will be discussed in the next section.
If you run simpleScan without a start defined, it will throw a warning
MapFile: WARNING! Found no start detector!
and you will likely see no events in the output file. This requirement may be removed by using the --untriggered
command line flag which will analyze ALL events which are encountered.
The untriggered tag indicates that the channel does not need a valid start signal to fire, and it will be analyzed
whenever it is encountered. This tag is useful for untriggered detector types (i.e. singles coincidence) and for
logic and pulser signals. Note that the --untriggered flag is equivalent to setting the untriggered tag for all
detector channels defined in the map file.
Let's delete all the channel definitions and add a simplistic experimental setup e.g.
0 0 trigger::start
0 1 generic::
I know this will work for my input file, because there were detectors connected to the 0th and 1st channels in the
0th module. You may need to change the channel indices above to suit your particular file. If you're not sure which
channels are active, run the scan with no channels defined in the map. The program will throw a warning, but it will
still run. Once the scan completes, open the output file root data.root and plot the channel count debug histogram
root [1] chanCounts->Draw("COLZ"). The chanCounts histogram for my input file is shown below.
This histogram shows every channel fire that was found in the input file, regardless of whether or not it was validated by the map file. This is a useful process in the event that you are unfamiliar with the hardware setup used for a given data file, or you misplace the simpleScan map and need to remake it.
Once you have the map configured correctly, let's run the scan again. This time we see that the scan concludes
successfully with the notification Scanner: Scan complete. and a list of information similar to that below.
Scanner: Retrieved 119854 spills!
Scanner: Cleaning up...
Scanner: Read 158701 spill chunks.
Scanner: Lost at least 34 spill chunks.
Scanner: Found 2.6081e+06 total events.
Scanner: Writing 274342 processed data entries to root file.
Scanner: Processed 1 files.
Scanner: Found 560162 events.
Scanner: Found 285820 start events.
Scanner: Total data time is 149356
TriggerProcessor: Used 0.290157 seconds of CPU time
TriggerProcessor: 274342 Total Events
TriggerProcessor: 274342 Handled Events (100%)
TriggerProcessor: 274336 Valid Events (99.9978%)
[1] Not Valid: 6
[d] CFD Failure: 6
[3] Total Invalid: 6
GenericProcessor: Used 0.183147 seconds of CPU time
GenericProcessor: 274342 Total Events
GenericProcessor: 274342 Handled Events (100%)
GenericProcessor: 274338 Valid Events (99.9985%)
[1] Not Valid: 4
[d] CFD Failure: 4
[3] Total Invalid: 4
Some of this information is extraneous but there are some important values as well. Some of the important fields are discussed below.
-
Scanner: Found 2.6081e+06 total events
- The total number of ALL events, including untriggered events and events from channels not included in the map file.
- This number should be equal to the number of entries in the chanCounts diagnostic histogram
root [1] chanCounts->GetEntries().
-
Scanner: Writing 274342 processed data entries to root file
- The number of events which were written to the output TTree. Basically the number of raw events which were constructed.
- This number should correspond to the number of start events which were detected.
-
Scanner: Found 560162 events
- The total number of good (map-validated) events.
-
Scanner: Found 285820 start events
- The total number of good start events. Typically, this number should correspond to the number of events which were written to the output TTree.
- If more than one start was defined in the map, or if the frequency of start signal is very high, these two values may differ.
-
Scanner: Total data time is 149356
- The difference in time between the first and last event timestamps in the input file.
- This value is given in seconds and should correspond to the physical wall-clock time (i.e. the Poll2 acquisition time) for the file.
You may notice that some of the events for the two processors (Trigger and Generic in this case) were not validated correctly. Sometimes this is caused by failure of the timing analysis algorithms (e.g. CFD Failure as seen above), but this is rare. More commonly, validation failure is caused by events falling outside the raw event window. Tuning of the raw event window parameters may mitigate this problem as described in the next section. When everything is working correctly, the percentages of valid events should be 99.9% and above for a given processor type.
Now you should be able to configure the map file for most types of experimental setups. More complex detector types (such as PSPMT detectors) will require more setup, but will be covered in more advanced sections of this wiki.
SimpleScan's raw-event builder may be configured using the configuration file (./setup/config.dat). Let's look at the example file we copied from the build directory.
# Example simpleScan configuration file.
# Author: Cory R. Thornsberry (Oct. 4, 2018)
# - Entries must be delimited with SPACES!
# - Blank lines and text following a # are ignored.
# - Undefined variables will take default values.
# Syntax:
# NAME VALUE
configVersion 1.2 # Version of this file
adcClock 4E-9 # Module ADC clock in seconds
sysClock 8E-9 # Module system clock in seconds
eventWidth 0.500 # Maximum event width in us
eventDelay -0.250 # Delay of raw event window in us
buildMethod 2 # Raw event builder method
Again, yours may look different but it should be roughly the same. As with the map file, the entries here are space-delimited. Each config variable name has one value. SimpleScan can read any variable name from this file without complaining, but they may not necessarily do anything. The valid variables are summarized in the table below
| Name | Units | Description |
|---|---|---|
| configVersion | Not used | |
| adcClock | seconds | Sets the ADC clock tick for high-res timing using traces |
| sysClock | seconds | Sets the system clock tick for the Pixie event timestamp |
| eventWidth | microseconds | Sets the width of the raw-event window for timing correlation |
| eventDelay | microseconds | Sets the delay of the raw-event window from the validated start signal |
| buildMethod | Sets the raw-event builder method |
NOTE: The clock tick lengths are configured for a 250 MSPS Pixie card. If you're using a different frequency, you'll need to change these values, otherwise your times will be incorrect.
Events in the input data file have no inherent time structure. SimpleScan builds raw-events which are defined with respect to the user defined start detectors (as described in the previous section). When a start signal is found, a new raw-event window is opened.
Each raw-event has a width defined by eventWidth and are delayed from the start signal by eventDelay. Events will be placed into a raw-event if their timestamp falls within this window. Therefore, all time structure is directly dependent upon these two values. Setting the width or delay incorrectly could mean losing good events, or including events which are not physically correlated with the start signal.
There are two raw-event builder methods included in simpleScan. These two builders are referred to as method 0 and method 2 and may be selected using the buildMethod variable shown above. Technically there are four methods, but the odd-numbered methods (1 and 3) are simply copies of the other two with negative timing windows. The two builder methods are shown below
| Mode | Description |
|---|---|
| 0 (1) | Raw event window opens for any detected signal. The event delay is not used for this method |
| 2 (3) | Raw event window opens only for channels marked as start (default) |
Mode 0 is how the scan worked originally. Events having timestamps within the range between the time of the first detected signal and that time plus eventWidth were added to the raw-event. This method is still useful for processing singles coincidence experiments.
The new builder method only triggers for channels labeled as start. Events with timestamps within the range Tstart+eventDelay to Tstart+eventDelay+eventWidth are added to the raw-event. This allows much more flexibility and allows the user to exclude events which occur between the start event time and some known minimum time (such as a gamma-flash, i.e. the minimum possible time).
NOTE: When using --untriggered mode, using builder method 2 (or 3) is not valid because there is
no start signal. The program will throw a warning and will automatically switch the builder method to 0.
The output time structure is heavily dependent upon cabling, detector geometry, Pixie coincidence triggering offsets, and so on. Typically, whenever you first scan a new data file, you won't know the offsets you'll need. So it's good practice to start by setting the eventWidth and eventDelay very large to ensure that you see all events of interest and then restrict the two as necessary. Setting the eventWidth to 1 us and the eventDelay to 0.5 us (ensuring the window is centered at zero) is typically sufficient for capturing the majority of events. Note, however, that you may need an even larger window if the time-of-flight is expected to be long.
The figure below shows a typical neutron time-of-flight setup with an offset of -500 ns and a width of 1000 ns.
Because the geometry of the setup is known, we know where we expect to see good neutron events. The "good" events faill somewhere in the range of -75 to +125 ns (as shown by the vertical dashed lines). So by setting the delay to -75 ns and the width to 200 ns will allow all of the good events while ignoring uncorrelated events outside of the range.
As stated, simpleScan knows nothing about more complex detector types (dual-sided bar detectors, PSPMTs, etc), it is simply a pre-processor. Higher level analysis is required for some experimental setups and will be discussed in other sections of this wiki.