Introduction

The Bunch Length system is responsible for measuring the length of the bunch of electrons after the bunch compressors, using indirect measurement techniques. For a detailed and hopefully entertaining introduction on the physics and mathematics behind the system, please read the document How the Length of the Bunch is Measured.

The system is based on the High-Performance System (HPS) over ATCA built at SLAC. For an introduction, please read ATCA 101.

Use cases

Actors

The figures with white heads represent a person and the ones with grey head represent a system.

• Operator: controls the accelerator, driving the beam with the parameters requested by the user (the users are not represented on this diagram). The Operator is responsible for identifying issues and solve them or call IOC maintainers or Physicists in order to get the best quality of a beam.
• Physicist: understands and design the connection between the electron and photon beam parameters, how sub-systems are interconnected and how the changing in parameters affects the overall beam quality.
• IOC maintainer: engineer responsible for diagnosing problems in IOCs, fixing bugs, and improving the software. For ATCA based platform, the IOC maintainer actor can also mean a firmware maintainer, that deals with the FPGA on carrier boards.
• BPM IOC: this represents an IOC responsible for measuring the electron beam position on a cross-section of the accelerator.
• Fast feedback: this system receives parameters from key accelerator systems and acts to correct the electron beam.
• MPS: this is the system responsible for the safety of some of the equipment of the accelerator.
• BSA: system responsible to hold important data aligned with a specific beam pulse in a way that a user can compare the state of many parameters of the accelerator within the same pulse.

Calculate the maximum current and signal sum

The goal is to receive inputs from sensors and other systems and calculate the maximum current and charge (called signal sum) of the electron beam. Those are indirect measurements representing the amplitude and area of a Gaussian, which are easily translated to a bunch length by the Physicists. Details on this process and the calculation itself are described in How the Length of the Bunch is Measured. 

The sequence diagram below breaks the bunch length system into software and firmware to be more precise. In this context, the software is considered the code made in C/C++ and running in a CPU with Linux RT as the operating system. Firmware is the code synthesized in the FPGA from a VHDL source code running on the carrier board in the ATCA crate. The maximum current is called IMAX and the charge is called SUM.

The BPM IOC and the Bunch Length firmware are triggered by the timing system. The firmware reads and digitizes the sensors upon receiving the trigger. Once the software receives TMIT from the BPM through the FCOM network, it resends the info to the firmware that uses it to calculate IMAX and SUM. The firmware sends the results to the software, that directs the info to two different places: the Fast Feedback receives it through the FCOM network and the BSA has its records filled with them.

Introduction to FCOM can be found here: Using FCOM in the IOC App.

The Bunch Length system uses two separate threads to deal with the data:

The FCOM thread is responsible for sending the TMIT information to the firmware as soon as it arrives from the BPM IOC. The BSA thread is responsible to receive the result from the firmware, send it to the Fast Feedback system, and store it in the BSA records.

The sequence of actions of each thread is described in details below:

Thread task in a continuous loop to deal with FCOM receiving. It is in the file blenFcom.cpp.

processBlob: a function called by the FCOM task. It is in the file blenFcom.cpp.

Thread task in a continuous loop to deal with BSA storing and data being sent to the fast feedback system. It is in the file cpswStreamBSA.cpp.

Control filters and check status of them

The system controls some optical filters and reads the position of the filters by using digital I/O located on the RTM attached to the blade dedicated to the Bunch Length system.

The IOC application reads and writes to the FPGA registers by using CPSW and the control is done entirely in the EPICS database. For reading the status of the filters the register provides an integer where each bit represents a status of a filter. For commanding the filter, an integer is written to the register, using this same bit code. The bit mapping is the following:

The EPICS database files are blenFilterDecoders.db, blenFilters.substitutions, blenFilters.template.

Check length parameters and measurement

The system provides data related to two different bunch length measurements for the Operators, one for each pyrodetector. This is the PyDM screen that can be used to check the system:

The streaming of the waveforms can be turned on or off to reduce the data from the ATCA to the CPU. The Operator can choose 4 different status for the stream: Running, Maintenance, Test, and OFFLINE. The first 3 don't change the behavior of the streaming, they are used only for alerting other users. "OFFLINE" is the only status the effectively shut down the streaming. The database that controls the stream is streamControl.db.

The Sum and IMAX are calculated by the firmware. TMIT is provided by the BMP IOC and sent to the firmware as described earlier. The TMIT value is replied back by the firmware and the software publishes it as the PV we can see on the screen. IMAX can show "nan" in case an error flag is sent by the firmware. In the example above, the pyrodetector is disconnected and, so, Sum is calculated on noise, resulting in a negative number. IMAX was also negative and the firmware alerted us about this, what we can see as a "nan" inside a pink box.

The dashed blue lines indicate where the integration window is placed. The left side tells the system where to integrate the background noise while the right side configures where the real signal is. The chart below the raw waveform shows the result when multiplying the background by +1 and the signal by -1. The system will integrate this second waveform to get the non-calibrated length measurement. The calibration parameters and windows adjustments are described in the next topic. 

Adjust calibration parameters

TMIT and the integral of the raw waveform are used to calculate the bunch length. The parameters that need to be input in the system are the integration windows, plus a linear adjustment function [f(x)=a.x+b] for the sum of the signal, plus the coefficients of this equation:

Each group of elements will be broken into sections for better comprehension:

Adjustment of the integration windows

The system provides a way to adjust 3 regions for the signal. The leftmost region, shown as "Duration pre edge (ns)" on the picture below, integrates the background noise to be subtracted from the signal region. The rightmost region, shown as "Duration pos edge (ns)" on the picture below, integrates the signal. An optional "Duration inter edges (ns)" defines a region between the background noise and the signal where the integration is ignored. It is useful for removing the slope from the calculation. This middle region is not shown in the chart below.

Both pre-edge and inter-edge regions have its zero nanosecond reference in the same place: the starting point of a trigger (corresponds to the beginning of the chart). That's why selecting an inter-edge with a value less than the pre-edge makes the middle region disappear. Check the diagram below to have things more clear. The post-edge zero reference starts at the end of the pre-edge or the inter-edge, which one is greater.

The firmware doesn't work in terms of nanoseconds, but it uses clock ticks. A transformation must be done from clock ticks to nanoseconds and vice-versa. Also, the firmware doesn't accept odd values for tick counts. The first 28 bytes of the raw waveform sent by the firmware contains diagnostics data and not sampled data and have to be removed. All of these operations are described in the section "Waveform and integration windows".

Linear adjustment function for the sum of the signal

This step ends with the result for ARAW for the formula described before. This step is performed by the firmware, not the software.

In the first step, we selected integration windows for the background (the left region on the pictures above) and for the signal (the right region). What the firmware does is to integrate over the points in one window, integrate over the points in the other window and subtract them. Essentially, this corresponds to subtracting the background from the signal. I will call these two integrations as BKGND and SIGNAL. In this first and simple approach, we are just doing:

[1] ARAW = SIGNAL - BKGND

The system provides a better level of flexibility where you can define separate weights for each integration. Suppose that the Physicist selected a small region for the background and a big region for the signal. We would need to give more weight for the background in order to compensate for the smallest number of samples to integrate. So, we add the weight factors A0 and A1 to the formula:

[2] ARAW = SIGNAL*A1 - BKGND *A0

The last level of flexibility is an offset. This is for adjusting the non-normalized sum for, as an example, avoiding negative values for the sum. The final formula for the sum is:

[3] ARAW = SIGNAL*A1 - BKGND *A0 + OFFSET

This is the screen that can be used to set the parameters:

The weight parameters A0 and A1, and Offset are the first 3 boxes on the snapshot.

The last section of this document showed how the integration windows are adjusted. An EPICS database takes care of changing A0 and A1 automatically when the windows' width is changed. So, this guarantees that if the background and signal are approximately horizontal lines, no change in the window's width will change the final result of ARAW. A deep detail about this database is described in Auto adjustment of weight factors A0 and A1 below.

Coefficients of the equation

Algorithm description

Waveform and integration windows

All the algorithm is processed in the EPICS database layer.

First thing, the waveform is delivered from the firmware to the software with the time axis measured in tick counts. We need to convert it to nanoseconds. The EPICS record responsible for this is in the weightFunctionXAxis.db database. The firmware informs half of its clock frequency in Hz for each of the AMC cards by using the registers /mmio/AppTop/AppCore/AmcGenericAdcDacCore[n]/AmcGenericAdcDacCtrl/AmcClkFreq, with n varying from 0 to 1 according to the AMC card. The registers are translated to Asyn parameters AMC0:AmcClkFreq and AMC1:AmcClkFreq by the dictionary blenMR.dict. The CALC field converts from Hz to nanoseconds, remembering that the firmware gives the number related to half of the frequency.

Next step is to calculate the time related to each section of the integration window: pre-edge, inter-edges, and post-edge. Basically, we multiply the size of the window section in ticks by the period of the tick in nanoseconds, as calculated before. The inter-edges is different because the firmware delivers half of the size. That's why we have B*2 in the calculation. The register names and Asyn parameter names for each of the AMC cards are in the table below.

The next step is to provide PVs for the user to change the pre, inter, and post edges windows in nanoseconds and convert them back to tick counts. The user changes the PVs TIME_PRE, TIME_MID, and TIME_POS and calc records convert it to tick counts, writing the value to the firmware through the records NumSamp0, NumSamp1, and TrigDelay1.

To convert from nanoseconds to tick counts we need the AMC clock frequency, as before, multiply by the number of nanoseconds and divide by 1 billion, as the clock frequency is taken as Hz. Also, the clock frequency informed by the firmware is half of what is real, so we need to multiply everything by 2. This is what gives us the equation 2*A*B/1000000000. This number is rounded with the FLOOR operator, that can generate an odd number. The firmware expects only even numbers, so we need to guarantee that the LSB is always zero by doing an AND with the result and ((~0)-1).  ~0 gives all "1" for all the bits. Subtracting 1 gives us all bits "1" besides the last one.

The inter-edges window must be divided by 2 per firmware requirement. Also, we are guaranteeing that the size of the inter-edge window is never lower than the pre-edge window for the reason explained before in Adjustment of the integration windows. That's the function of the record TIME_MIDC.

The firmware registers for these records are the same as described before, as you can see by the OUT field with the Asyn parameter name.

The last feature provided by the weightFunctionXAxis.db is to generate an array for the X-axis of the chart, containing the translation to nanosecond for each tick count. This is held by the aSub record BLEN:$(AREA):$(POS):$(INST)_WF_TIME, using the function calcTimeArray() available in the file asubWeightXAxis.c. The input for the record is the PV AmcClkFreq already described before.

Auto adjustment of weight factors A0 and A1