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.

Creating a new st.cmd

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.

Anchor
CALC_MAX_CURR CALC_MAX_CURR

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 of actions of each thread is described in details below:

...

Anchor
FILTERS FILTERS

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 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 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:

Anchor
ADJUST_INT_WINDOW ADJUST_INT_WINDOW

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.

...

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

Revisiting the equation defined some sections above, we already have described the origin of two components:

• TMIT: as described in Calculate the maximum current and signal sum, this component comes from the BPM IOC, through the FCOM network.
• ARAW: the calculation of this component was explained in the previous section.

...

Anchor
BSA BSA

Access a list with bunch length parameters aligned with the same timestamp

The Bunch Length IOC application provides 4 parameters for the BSA (Beam Synchronous Acquisition) system. A brief introduction for BSA can be found here: Beam Synchronous Acquisition (BSA).

...

int BlenBSA::createChannels(const char *stationName) {
    char param_name[64];
    bsaChannels = new BsaChannel[NUM_CHANNELS];

    /* Create NUM_CHANNELS BSA channels with the name formed by the 
     * stationName that comes from the IOC shell, plus the channel
     * acronym defined by the constant array channelNames. */
    using namespace std;
    for (int i = 0; i < NUM_CHANNELS; i++) {
        sprintf(param_name, "%s:%s", stationName, channelNames[i]);
        bsaChannels[i] = BSA_CreateChannel(param_name);
    }
    return 0;
}

As explained in Calculate the maximum current and signal sum, there is a thread responsible to store the data to the BSA Core as soon as the data is ready. The firmware sends the data to the software using a CPSW stream channel. The name of the stream channel is defined in the YAML file and must be informed to the BSA thread by the second parameter of the st.cmd function blenConfigure (explained before). Every time the data is ready, the firmware sends it asynchronously and the software must be prepared to read and process it. The complete data structure of this stream can be checked here. For what is in use by the current IOC application, this is the struct that is mapped to the stream packet:

typedef struct {
    epicsTimeStamp  time;
    epicsUInt32     mod[6];
    epicsUInt32     edefAvgDoneMask;
    epicsUInt32     edefMinorMask;
    epicsUInt32     edefMajorMask;
    epicsUInt32     edefInitMask;
} timing_header_t;

typedef struct {
    epicsFloat32    sum;
    epicsFloat32    iMax;
    epicsFloat32    scaledTMIT;
    epicsUInt32     status0;
    epicsUInt32     status1;
    // Seven 32-bit words reserved for future use
    epicsUInt32     reservedWords[6];
} payload_t;

/* This structure represents the entire content of the BSA stream message that
 * comes from the firmware. If the message content is changed, this structure
 * must be updated */
typedef struct {
    // Stream header is not described at the specification.
    epicsUInt64     streamHeader;
    epicsUInt32     headerWord;
    timing_header_t timingHeader;
    payload_t       AMC0_Data;
    payload_t       AMC1_Data;
} stream_t;

If you retake the BSA thread task activity diagram, the data receive some processing and is mapped to another data structure to make it easier to extract data to the BSA core. This is the structure:

// Data to be sent to BSA channels
typedef struct bsaData_t {
    epicsTimeStamp timeStamp;
    double         aImax;
    double         aSum;
    BsaStat        aStat;
    BsaSevr        aSevr;
    double         bImax;
    double         bSum;
    BsaStat        bStat;
    BsaSevr        bSevr;
} bsaData_t;

...

# BSA records
dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=AIMAX, SINK_SIZE=1")
dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=BIMAX, SINK_SIZE=1")
dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=ARAW, SINK_SIZE=1")
dbLoadRecords("db/Bsa.db", "DEVICE=BLEN:${AREA}:${POS},ATRB=BRAW, SINK_SIZE=1")

Algorithm description

Anchor

...

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.

...

SHOW_REPORT SHOW_REPORT

Check diagnostic reports

The IOC application provides an IOC shell function called blenReport to help the IOC Maintainer to diagnose the system. Once in the IOC shell, blenReport will output:

The first half of the output deals with statistics related to FCOM. It is broken into two parts: Rx for received packets and Tx for transmitted packets. The numbers are cumulative since when the IOC was booted.

The second half deals with general data received and transmitted. The table below explains each of the shown parameters.

Anchor
DATA_DUMP DATA_DUMP

Read data arriving from the firmware

Sometimes the IOC Maintainer would like to check the content of the raw BSA message that the firmware is sending to the IOC. For this, the function blen_dumpBSAStream can be used. It accepts one parameter: the number of packets in the sequence that is going to be printed on the IOC shell. The content of the bytes for this function is described in this document. This is a partial output after this function finishes printing 2 packets.

Algorithm description

Anchor
Waveform Waveform

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.

Anchor
AUTO_A0_A1 AUTO_A0_A1

Auto adjustment of weight factors A0 and A1

As seen before, moving the sliders to change the width of the integration windows changes the PVs NumSamp0 and NumSamp1, that, in sequence, send the value to the FPGA registers. This section is the continuation of this story.

Once NumSamp0 and NumSamp 1 changes, the coefficients A0 and A1 must change proportionally. The database diagram below shows that the records A0_NS0 and A1_NS1 will process whenever NumSamp0 and NumSamp1 are changed. CALC_Const_A0 and CALC_Const_A1 will not process because their INPA fields are not set with the CP directive. Once A0_NS0 process, it will divide A0_CONST by NumSamp0 and write the result to CoefA0, changing the value of the coefficient in the FPGA register. The calculation record has protection against division by zero using "A=0? B : B/A". The same process happens for CoefA1.

So, keeping it simple, whenever the user changes the width of the integration window, the A coefficient will change proportionally.

Now it comes to the reason for the existence of Reset_A0 and Reset_A1. These are tools that a user can use to force the values of CoefA0 and CoefA1. Once a number is written to Reset_A0, CALC_Const_A0 will make the inverted calculation compared to A0_NS0 and store it at A0_CONST. All these record chain processes and force A0_NS0 to process, undoing what CALC_Const_A0 did before. The final result is that the exact number that the user wrote to Reset_A0 will end up in Coef_A0. The same rules apply to the CoefA1 record chain.

BLEN MR Cheat Sheets

Database files

Files in blenApp/Db

Source code files

Files in blenApp/src

iocBoot files

IOC shell functions

Starting PyDM screens

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.

...

As seen before, moving the sliders to change the width of the integration windows changes the PVs NumSamp0 and NumSamp1, that, in sequence, send the value to the FPGA registers. This section is the continuation of this story.

Once NumSamp0 and NumSamp 1 changes, the coefficients A0 and A1 must change proportionally. The database diagram below shows that the records A0_NS0 and A1_NS1 will process whenever NumSamp0 and NumSamp1 are changed. CALC_Const_A0 and CALC_Const_A1 will not process because their INPA fields are not set with the CP directive. Once A0_NS0 process, it will divide A0_CONST by NumSamp0 and write the result to CoefA0, changing the value of the coefficient in the FPGA register. The calculation record has protection against division by zero using "A=0? B : B/A". The same process happens for CoefA1.

So, keeping it simple, whenever the user changes the width of the integration window, the A coefficient will change proportionally.

Now it comes to the reason for the existence of Reset_A0 and Reset_A1. These are tools that a user can use to force the values of CoefA0 and CoefA1. Once a number is written to Reset_A0, CALC_Const_A0 will make the inverted calculation compared to A0_NS0 and store it at A0_CONST. All these record chain processes and force A0_NS0 to process, undoing what CALC_Const_A0 did before. The final result is that the exact number that the user wrote to Reset_A0 will end up in Coef_A0. The same rules apply to the CoefA1 record chain.

...