========================
 Bunch Pattern Decoding
========================

If desired, the FastADC can receive and decode the bunch pattern to
know which bunches in a train are going to a specific beamline and/or
have a pulse probe laser (PPL). Users can also specify a Max/Min of
acceptable bunch charges. When enable and configure, the Bunch IDs and
Charges are saved in the DAQ.

In addition, it is also possible to configure the FastADC to use this
information to do `Automatic Peak Integration`_ or `Conditional and/or
Dynamic Raw acquisition`_.
 
Settings
========

The decoding configuration is done in the device node **Bunch Pattern
Settings**.  The source of the X-ray bunch pattern to decode (*Light
Source* parameter) can be any of SASE1, SASE2, SASE3, SASE1+3 or
None. If bunch pattern decoding is enabled and None is selected, only
the PPL bunch pattern will be considered. The Bunch pattern logic
option defines whether a bunch ID is considered when there are bunches
in both the X-ray beam and the PPL patterns (AND) or when there are
bunches in either (OR).

Maximum and Minimum bunch charges can also be define.

If configure, during acquisition the Karabo device will update the
*First Bunch ID* and *Number of Bunches* parameters in the current Train. 

.. figure:: _images/bunchPattern_settings.png
   :scale: 40%

   Bunch pattern settings in the FastADC and correspondent Output channel. 

Output
======

An output channel is also available, wherein a list containing the of
bunch Ids determined by the conditions specified in the "Bunch Pattern
Settings" node are output. This is DAQ compatible, but if
DAQ recording is required it must be requested separately from the slow data
of the device (request "\<DeviceId\>:bunchPatternNode.output" to be added to
the data group.

FastADC Calibration
===================

To use the features described in the following sections, it is require
to enable and configure the Bunch Pattern and calibrate the
**FastADC**. This is done performing the following steps:

1. Stop acquisition of device 
2. Set *Raw Delay* and all *Peak Delay* parameters to 0
3. Configure the Bunch Pattern according to your requirements
4. Configure the *Pre Train Samples* parameter if require (see `Calibration for early bunches`_)
5. Start acquisition. Take note of the value in the property *Sample First Bunch*
6. Open the  **Karabo Trigger Middle Layer Device** of the trigger used by the FastADC (check *Board Configuration > Trigger Source* property. When in doubt, contact Control and/or EEE colleagues)
7. Configure **Macro P-Event** property to be *Standard Trigger*
8. Change the *Target Delay* so that first peak sample (as desired for the peak integration) of the first bunch in the raw trace matches the *Sample First Bunch* value

.. figure:: _images/sampleFirstBunch.png

   Pre Train Samples and Sample First Bunch parameter. 

Calibration for early bunches
-----------------------------

For bunches which are present at the very beginning of the train, like
PPL pulses, calibrating the FastADC following the previous section
will result in a raw trace with very few samples before the
train. This might not be desirable for setups which require data
before the train arrives or use a signal based baseline(s).

To surpass this, the FastADC parameter *Pre Train Samples* can be used
to configure an offset number of samples to acquire before the
train. 
   
Automatic Peak Integration
==========================

Once the FastADC is calibrated (see previous section), channels can
enable the *Use the Bunch Pattern for peak computation* feature. In this
configuration, the FastADC automatically updates the Peak Integration
parameters to integrate all the Bunches present in the Train that
match the configuration of the Bunch Pattern.

The parameters *Number of Pulses*, *Pulse Period* and *Pulse Delay*
are ignore by the device, since these will be updated by the
hardware. The user only needs to specify:

- how many samples per peak the device should consider
- baseline configuration (see `Baseline Configuration <Integrator_Processing_Module.html#baseline-configuration>`_ section)


.. figure:: _images/autoIntegrator_pars.png
   :scale: 40%

   Enable peak integration with the Bunch Pattern. Crossed are the
   parameters which are ignore in this setting
  
   
Conditional and/or Dynamic Raw acquisition
==========================================

With the FastADC calibrated (see `FastADC Calibration`_), the property
*Raw Data Acquisition* can be set to **Conditional**, meaning that raw
data will only be taken if there are bunches in the train which match
the configuration of the Bunch Pattern (please note that this applies
to **all channels**). This parameter can also be set to *Never*, in
case the user is only interested in values from peak integration.

When *Raw Dynamic trigger* is true, raw data acquisition will always
start at sample number (*Sample First Bunch* - *Raw Delay*), meaning
that acquisition will have a fix relation (time wise) with the first
bunch in the train. This is similar to use the dynamic trigger from
the timing system.

Using these features have **no affect** in the Automatic Peak Integration. 

.. figure:: _images/autoRaw.png
   :scale: 40%

   Conditional and Dynamic Raw Karabo properties