View source for TITAN DAQ General Documentation

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[TITAN]] page
* [[MPET DAQ]]
* [[CPET DAQ]]
* [[EBIT DAQ]]
* [[PPG Building Blocks]]
</div>

== Introduction ==
The DAQ for the three TITAN experiments (MPET, EBIT, CPET) share common features, notably a PPG module that needs to have pulse timings adjusted often, and other hardware that needs to be scanned / read-out during a run.

All three are now built on a common "cycling framework" that is common to TITAN (MPET, EBIT, CPET) and CMMS (BNMR, BNQR). This framework includes:

* Webpages, python and C++ code for defining and compiling a PPG routine
* Webpages and python code for saving/loading ODB settings
* A C++ system for interacting with a PPG and other hardware, reading out data at the end of each PPG cycle (or at some other desired rate)
* Ability to edit PPG timings during a run, re-compile, and reload the program onto the PPG
* Scanning/toggling/reading EPICS variables during a run
* Reading out scalers during a run (for MPET and EBIT)
* Scanning softdac-based trap voltages during a run (for MPET)
* Scanning RF frequencies during a run (for MPET)

The vast majority of the code is contained in the [https://bitbucket.org/ttriumfdaq/cycling_framework/ cycling_framework] repository, which is included as a submodule in the cpet, ebit and mpet repositories. This keeps the distinction between the different experiment very clear, and the C++ code for the main frontend mostly consists of enabling/configuring features provided by the submodule.

Custom webpages are provided that allow the user to configure all the above features.

== Core principles ==

The heart of each DAQ is the PPG (a VME hardware module), which is programmed with a user-specified routine for issuing signals to other pieces of hardware. The frontend is in constant communications with the PPG, to see whether it has finished the current cycle yet. After each cycle is complete, the frontend reads out any data (e.g. from digitizers), sets up the next step (e.g. incrementing an EPICS variable if doing an EPICS scan), then starts the next PPG signal.

This system, where data is read out after each PPG cycle, makes offline analysis significantly easier, as each midas event contains data from one PPG cycle (by default), and analyzers know exactly what the experimental setup was for that cycle.

The system allows for different scanning modes:

* No scanning
* 1-dimensional scan (X)
* 2-dimensional scan (X and Y)

Multiple variables can be scanned at the same time - e.g. you could do a 1 dimensional scan where you change 5 different settings at the same time. In the 2D scan, there is a tight loop over all the Y steps before moving on to the next X step.

From the inner-most scoping to outer-most:

* A <b><i>cycle</i></b> consists of running a PPG program one time.
* A <b><i>supercycle</i></b> runs N cycles of the PPG. The DAQ can be configured to only read out data after each supercycle (e.g. if you have a very short PPG program, and want to read out data only after the cycle has run 1000 times, so you can collect a large amount of statistics without having the latency of reading out data 1000 times).
* Scan over all Y values (if doing a 2D scan).
* Scan over all X values (if doing a 1D or 2D scan).
* Each <b><i>loop</i></b> involves one full scan of the X/Y values.

As well as the above, you can also have devices that are "flipped" or toggled between two states (e.g. having a Faraday cup in and out of the beam). The flipping can happen after every supercycle or after every loop. If flipping every supercycle, data is taken in both states before moving to the next scan value.

== Features used by each experiment ==

<table border="1">
<tr><th></th><th>CPET</th><th>MPET</th><th>EBIT</th></tr>
<tr><th>PPG: Standard programming</th><td>[[PPG_Building_Blocks#Introduction|Yes]]</td><td>[[PPG_Building_Blocks#Introduction|Yes]]</td><td>[[PPG_Building_Blocks#Introduction|Yes]]</td></tr>
<tr><th>PPG: Extra begin-of-run program</th><td></td><td>[[PPG_Building_Blocks#Begin-of-run_program|Yes]]</td><td></td></tr>
<tr><th>PPG: Allow formulae for defining time offsets / pulse widths</th><td>[[PPG_Building_Blocks#Specifying_times_with_a_formula|Yes]]</td><td>[[PPG_Building_Blocks#Specifying_times_with_a_formula|Yes]]</td><td>[[PPG_Building_Blocks#Specifying_times_with_a_formula|Yes]]</td></tr>
<tr><th>PPG: Run program N times in a single cycle</th><td></td><td></td><td>[[PPG_Building_Blocks#Adding_an_automatic_loop|Yes]]</td></tr>
<tr><th>PPG: Scanning</th><td>[[PPG_Building_Blocks#Scanning_parameters|Yes]]</td><td>[[PPG_Building_Blocks#Scanning_parameters|Yes]]</td><td>[[PPG_Building_Blocks#Scanning_parameters|Yes]]</td></tr>
<tr><th>PPG: Toggling muted/unmuted pulses during a run</th><td>[[PPG_Building_Blocks#Muting_blocks|Yes]]</td><td></td><td></td></tr>
<tr><th>PPG: Running without the PPG program enabled</th><td></td><td></td><td>[[EBIT_DAQ#Enabling.2Fdisabling_the_PPG_program|Yes]]</td></tr>
<tr><th>EPICS: Scanning</th><td>Yes</td><td>Yes</td><td>Yes</td></tr>
<tr><th>EPICS: Readout of Faradday cups</th><td></td><td></td><td>[[EBIT_DAQ#Faraday_cup_readout|Yes]]</td></tr>
<tr><th>EPICS: Toggling cup in/out</th><td></td><td></td><td>[[EBIT_DAQ#Faraday_cup_in.2Fout_toggling|Yes]]</td></tr>
<tr><th>Softdac voltage scanning</th><td></td><td>Yes</td><td></td></tr>
<tr><th>CPET DAC voltage scanning</th><td>[[CPET_DAQ#DAC_control|Yes]]</td><td></td><td></td></tr>
<tr><th>Labview voltage scanning</th><td>[[CPET_DAQ#Voltage_control|Yes]]</td><td></td><td></td></tr>
<tr><th>Agilent AFG programming</th><td></td><td>Yes</td><td></td></tr>
<tr><th>MCA4 readout</th><td>[[CPET_DAQ#MCA4_.2F_MCS4_.28time-of-flight.29|Yes]]</td><td></td><td>[[EBIT_DAQ#MCA4_.2F_MCS4_.28time-of-flight.29|Yes]]</td></tr>
<tr><th>WS3504 readout</th><td>[[CPET_DAQ#LeCroy_Wavesurfer_3504_scope|Yes]]</td><td></td><td></td></tr>
<tr><th>SR430 readout</th><td>[[CPET_DAQ#SR430_.28time-of-flight.29|Yes]]</td><td></td><td></td></tr>
<tr><th>V1290 readout</th><td></td><td>Yes</td><td></td></tr>
<tr><th>VT2 readout</th><td></td><td>Yes</td><td></td></tr>
<tr><th>LRS1190 readout</th><td></td><td>Yes</td><td></td></tr>
<tr><th>ZMQ announcement of cycle state</th><td></td><td></td><td>[[EBIT_DAQ#ZMQ_announcement_of_the_cycle_state|Yes]]</td></tr>
</table>

== Data format ==

The [https://bitbucket.org/ttriumfdaq/titan_data/src/master/ titan_data repository] provides user-friendly python tools for reading the data. If you want to know more about the file format, read on.

Data is written as midas files, which contain a series of [https://midas.triumf.ca/MidasWiki/index.php/Event_Structure#MIDAS_Format_Event events containing midas banks]. Each file also contains a dump of the ODB at the start and end of each file, which records various experimental settings.

Python-based tools for reading and interpreting the data are provided for EBIT and MPET. Currently this code resides in the DAQ repositories, but will soon be split into a separate respository for easier use by analysts.

'''Most analyzers do not need to read the rest of this page''', which contains detailed information about the structure of the midas files.

By default, banks are written at the end of every PPG cycle (this can be configured to write less frequently in a specific experiment's frontend code if desired). One event contains all banks.

=== Cycle information: SCAN ===

The SCAN bank contains metadata about how many PPG cycles have been run, and the progress of any scan that is happening.

It consists of 5 integers:

* Loop count (total number of 1D/2D scans that have been completed so far)
* X step (if doing a 1D or 2D scan)
* Y step (if doing a 2D scan)
* Step repetition (if running more than 1 PPG cycle at an X/Y step value before moving on to the next step)
* Total PPG cycle count

=== Flip states: FLIP ===

If devices are being toggled between 0/off/out and 1/on/in during a run (e.g. moving the RFCBL:FC0 Faraday cup into and out of the beamline for EBIT), this bank contains the current state of each device being flipped/toggled. It is a series of booleans. If multiple devices are being flipped in the same run, the ODB entry "/Scanning/Global/Computed/FLIP bank order" tells you the order in which their states are reported in the FLIP bank list of booleans. The mapping from true/false to a physical interpretation is found in the ODB at "/Scanning/<device>/Computed/True meaning" and "/Scanning/<device>/Computed/False meaning".

=== PPG scanning: XPPG/YPPG ===

These banks are written if you're scanning PPG variables (time offsets or pulse widths), and tell you what the current settings are for the given cycle.

The ODB paths being scanned are found in the ODB at <code>/Scanning/PPG/Settings/X paths</code> and <code>/Scanning/PPG/Settings/Y paths</code>, which are each arrays of length 20 (so up to 20 variables can be scanned if desired).

The XPPG/YPPG banks contain the current value for each path. The banks are simple lists of 20 doubles each (written in the same order as the X/Y paths arrays in the ODB).

=== EPICS scanning: XEPD/YEPD/XEPM/YEPM ===

These banks are written if you're scanning EPICS variables, and tell you what the current settings/measured values are for the given cycle.

EPICS devices are defined in the ODB in the the <code>/Scanning/Epics/Definitions</code> subdirectory, with arrays for:

* <code>Human name</code> - a human-readable description of the device
* <code>Demand device</code> - the EPICS PV name that should be set
* <code>Measured device</code> - the EPICS PV name that should be read to verify that the device has responded appropriately to the requested set value. For example, a power supply may only ramp at 10V/sec. If you change the demand voltage by 100V, EPICS will report the change immediately. However, it will take 10s for the actual supplied voltage to change to what you really want. This is often referred to as the "readback" or "measured" value. You do not have to specify a measured device, but it will make your data cleaner if you do.
* <code>Custom threshold check fn</code> - what tolerance is required to check that the measured value is close to the demand value after we've made a change during a scan.

These definitions are long-term things and do not change often.

Configuring which EPICS devices are scanned during a run is done in the ODB at <code>/Scanning/Epics/Settings</code>. The <code>X devices</code> and <code>Y devices</code> arrays contain lists of integers that point to indices of devices defined in <code>/Scanning/Epics/Definitions</code> (or -1 if not needed).

The XEPD and YEPD banks contain the demand value for each EPICS device being scanned, and XEPM and YEPM contain the measure value for each scanned device. The banks are simple lists of 20 doubles each (written in the same order as the X/Y devices arrays in the ODB).

=== Softdac trap voltage scanning: XSFT/YSFT (MPET only) ===

The softdac contains 8 channels, each controlling a different trap voltage. The voltage applied can be changed within a PPG cycle by issuing a pulse on PPG channel 1. Currently there are three different voltages applied, changed by the <code>pulse_trapv_injection</code>, <code>pulse_trapv_capture</code>, and <code>pulse_trapv_ejection</code> pulses. 

The default voltages for each phase/channel are specified in the ODB in <code>/Scanning/Softdac/Defaults</code>. The voltages to be scanned during a run are specified in <code>/Scanning/Softdac/Settings</code>, in the arrays <code>X blocks</code> and <code>X chan index</code> (plus the Y equivalents). These arrays are 24 elements long.

To simplify analysis (and because there aren't too many variables) the XSFT/YSFT banks write out the voltages for every pulse and channel combination. So with 8 channels * 3 pulses, the bank is 24 elements long. The order is:

* pulse_trapv_injection channel 1
* pulse_trapv_injection channel 2
* ....
* pulse_trapv_ejection channel 8

=== Labview trap voltage scanning: XLVV/YLVV (CPET only) ===

These banks contain the present value of each X/Y voltage being scanned. Each bank is a fixed length. Match the ODB arrays <code>/Equipment/LabViewVoltages/Settings/X keys</code> to the same order in XLVV etc.

=== DAC voltage scanning: XDAC, YDAC, DACV (CPET only) ===

The XDAC and YDAC banks contain the present value of each X/Y parameter being scanned. Each bank is a fixed length. Match the ODB arrays <code>/Equipment/DAC/Settings/X path</code> to the same order in XDAC etc.

The DACV bank contains the computed voltage for each channel. It is 16 elements long, with one entry for each of the 16 DAC channels.

=== VT4 timestamp data: DVT4 (MPET only) ===

This bank simply contains all the data that was recorded by the VT4 module. Each timestamp contains 2 32-bit words, which are decoded like:

 lo = data[i]
 hi = data[i+1]
 
 hitime    = (hi & 0xFFFF)
 count     = (hi & 0x03FF0000) >> 16
 channels  = (hi & 0x3C000000) >> 26
 new_cycle = (hi & 0x80000000) >> 31
 gate_rise = (hi & 0x40000000) >> 30
 
 tottime   = lo + (hitime << 32)

* If new_cycle is set, it indicates the start of a new PPG cycle. 
* If gate_rise is set and channels == 0, it indicates the start of a new gate. 
* Timestamps are incremented at 100MHz.
* channels is a bit pattern indicating the channels that saw a hit at this time.
* If gate_rise, new_cycle, and channels are all 0, it indicates the end of a gate.

=== LRS1190 position data: MCPP (MPET only) ===

This bank simply contains all the data that was read from the LRS1190 module. Each position hit consists of a single 16-bit word, which is decoded like:

 x_pos = (data[i] >> 8) & 0xFF
 y_pos = data[i] & 0xFF

=== CAEN V1290 25ps TDC data: 25PS (MPET only) ===

This bank contains timestamps from the CAEN V1290 25ps TDC. There is one initial word containing the PPG cycle number, then the raw data from the V1290.

See the V1290 manual for a full explanation of the data format bits. Decoding is implemented in C++ in [https://bitbucket.org/ttriumfdaq/cycling_framework/src/master/ cycling_framework]/v1290/v1290_format.h/cxx, and in Python in [https://bitbucket.org/ttriumfdaq/titan_data/src titan_data]/titan_data/mpet/__init__.py

For MPET, the order of words is:
* ppg cycle number
* global header for 1st trigger in this cycle
* timestamp
* timestamp
* ...
* global trailer for 1st trigger in this cycle
* global header for 2nd trigger in this cycle
* timestamp
* ...
* global trailer for 2nd trigger in this cycle
* ... etc

There should be the same number of triggers in each cycle as there are iterations of the "RAMP" loop in the MPET PPG program.

=== MCA4/MCS4 ToF histograms: MCS1, MCS2 (EBIT and CPET only) ===

The MCS1 bank simply contains the histogram that was read from the MCA4 for the STOP1 channel. MCS2 is for the STOP2 channel. Each entry is a 32-bit integer of the number of counts in that bin.

=== Faraday cup readings: FCUP (EBIT only) ===

This bank contains two double-precision numbers. The first value is the reading of TRFCBL:FC0:SCALECUR, and the second value is the reading of ILE2T:FC3:SCALECUR.

=== SR430 ToF histograms: S430 (CPET only) ===

The S430 bank simply contains the histogram that was read from the SR430 TDC. Each entry is a 16-bit unsigned integer of the number of counts in that bin.

=== Electron count from LeCroy WaveSurfer 3504: WS35 (CPET only) ===

The WS35 bank contains one double-precision floating point number - the pulse area calculated by the scope in V*s (Wb).