EVent Generator Graphical User Interface (EVGUI)
Introduction
The EVent Generator (EVG) has the task of generating signals that coordinate many pieces of the control system to do what is wanted on each of 360 pulses per second. Typically there are several types of things we can do on a pulse like, nothing, send beam to the LCLS electron dump or send beam to end station A. Each of these things happens on different pulses. Each has a rate (e.g. 60 Hz) at which it happens and that rate can be quickly changed by operator actions or hardware inputs from operator buttons, the beam containment system or the machine protection system.
This GUI allows the user to define patterns (also known as modifier bits) that are used to execute the above. These modifier bits are then used in other places to decide on e.g. whether to trigger a device or read a BPM. This GUI is not used for day-to-day control. Rather it is used a few times per run to define the rates at which various beams can be run.
Note that all data changed in this GUI remains local to the GUI until you press the "Save to IOC & SCORE" button near the bottom of the screen or the "Put Checked Rate Groups to EVG" button near the top of the "Define Rate Groups" tab. Of course, in addition to saving to SCORE, one can load a previous setup from SCORE with the adjacent button. The setup presently in use in the EVG is always the gold SCORE configuration.
The GUI is divided into five tabs. We will cover them one-by-one.
1. Define Modifiers Tab
On each pulse the EVG generates a set of 128 modifier bits. It uses these internally to generate event codes and sends them to all the EVRs where they are also used by the IOCs. This tab is used to name those modifier bits and provide a bit on information on how they are used. Please note that MANY applications use bitmasks and/or hard coding to choose modifier bits. So it is VERY unwise to move a modifier bit from one location to another. Rather, this tab can be used to add new modifier bits or eliminate ones that are no longer used.
To add a new modifier, click on the "Add New Modifier" button. This will add a row at the bottom of the table which you can then edit. Note that the table can be sorted by clicking on a column heading. By default, they start out ordered by bit position. Each column is described below.
Editable? Column
A "Yes" in this column means the user is allowed to edit the columns to the right for this modifier bit. "No" means the user cannot. This just adds a little protection against making accidental changes to the definition of a modifier bit that is used in so many places that changing it is unthinkable.
Modifier Name Column
This is the name of the modifier bit. It is used in many places of the operator interface to indentify a modifier bit.
Category Column
There are many modifier bits so it is useful to divide them up into a few distinct groups (categories) so one can deal with a subset. The category is selected with a drop down box. At present there are only three categories. If a new category is desired, one can CAPUT that new category name to any single element of the PNBN PV and then that new category will appear in the drop down list. PNBN is where all the data entered on this tab is stored in the EPICS database.
Bit Position Column
This tells which set of the 128 modifier bits is being described by the rest of the data in the row. The bit numbering starts at 0.
Bit length Column
Gives the number of bits this row describes. Most modifiers are 1 bit long. A few are multi-bit and hence can have values other than 0 or 1. The canonical example of this is the beam code (PP) which is typically used to describe the general purpose of that pulse (like which beam line it will end up in).
From MPG? Column
The MPG (Master Pattern Generator) is a micro processor in the legacy SLC control system that originally generated these modifier bits. The MPG's output is sent to the EVG via PNET, a special purpose network. To ease the transition for production of modifier bits from the MPG to the EVG, this column allows one to set for each bit whether the EVG just takes it from the MPG and passes it on (check mark in the box) or whether it generates it following rules set on other tabs of this GUI. As the MPG still runs parts of the accelerator complex like FACET, this connection to the MPG is also useful to let one accelerator know what the other one is doing.
2. Define Rate Groups Tab
A "Rate Group" contains all the information needed to generate modifier bits for closely related purposes. Each rate group is likely to contain information for several different beam rates (defined on the "Define Beam Rates" tab) – hence the name "Rate Group." A couple of examples will help make the concept clear.
We might have a rate group named "LCLS" using timeslots 1 and 4 that contains information on beam rates of 120 Hz, 10 Hz and 1 Hz. We might have a separate rate group for the NLCTA (if it were hooked up to the same EVG, which it is not) on time slot 2 that contains information on beam rates of 60 Hz, 10 Hz and 1 Hz.
This might lead you to believe that each beam destination has its own rate group. Life is not always that simple. For example, if we want to send the LCLS beam to end station A (ESA) at a minimum of 1 Hz, but at a higher rate if LCLS is running at less than 119 Hz for some reason (e.g. running at 1 Hz or burst mode for a user) then the LCLS XFEL beam and the ESA test beam would be put together in a single rate group. There could be Beam Rates of 119 Hz to LCLS plus 1 Hz to ESA, 10 Hz to LCLS plus 110 Hz to ESA and 10 Hz to LCLS plus 10 Hz to ESA etc. The system is flexible enough that this CAN be done.
In an obvious fashion, one can add and remove rate groups using the buttons on the top right. There can be many rate groups defined with only a few of them presently in use. Only those actually in the EVG are used by the EVG. The check box in the column "Put to EVG?" determines which rate groups will be put into the EVG and used when the "Put Checked Rate Groups to EVG" button on the top left is pressed.
The other six columns determine for which of the six timeslots the rate group will generate modifier bits. Note that one cannot put two rate groups to the EVG that generate modifier bits for the same time slot. The EVG is not smart enough to be able to figure out how to merge the modifier bit requests from two rate groups.
3. Define Input Bits Tab
The control system has several hardware input bits that are intended to change what the accelerator does and hence need to change the pattern of the modifier bits. The master beam control button boxes that the operators use to change beam rates are one use of this. Another use is a bit from the beam containment system (BCS) that indicates it has tripped and is used to change the modulator timing to standby to match the time change the BCS forced on the klystron triggers.
This tab simply allows one to name the bits and give a longer description of its purpose. The names are used in other places to refer to the bit in a user friendly fashion.
4. Define Beam Rates Tab
This tab is used to describe the various beam rates which are in each rate group. As should be obvious, the "Add New Rate" and "Remove Selected Rate" on the upper right are used to add or remove rows from the table. Note that the rows are automatically sorted to group those in the same group together and to go from low to high nominal rate within a group. So the row you are making entries into may move just after you enter the rate group name or nominal rate. The individual columns are described below.
Rate Group Column
This gives the name of the rate group to which this beam rate belongs. A drop down list of the rate groups defined on the "Define Rate Groups" tab makes selection easy.
Nominal Rate Column
This gives the nominal beam rate (in Hz) that will be produced when this rate is active. It is important to set this correctly as when the EVG has conflicting instructions as to which rate should be active, it chooses the one with the lowest nominal rate. This happens when, for example, via the EDM screen the operator has requested the 120 Hz rate, but via the master beam controller buttons he has requested 10 Hz. This happens all the time and it is the lowest rate that should be produced.
Short Rate Name Column
Enter a relatively short yet descriptive name for the rate here.
Long Rate Name Column
Enter a longer more exact description for the rate here.
Inputs Column
Here you can select one of the hardware input bits defined on the "Define Input Bits." When that input bit is active (it can be separately defined whether "active" is a high or low state) the EVG will reduce the rate to this one.
5. Define Patterns Tab
It is on this tab that one defines what modifier bits will come out when for each Beam rate in each beam rate group.
On the upper left is a rate group selection box that lets one select the rate group to display and change. Just to the right of that, you can choose whether to display 0.2 or 2.0 seconds of the modifier bit pattern. The 2.0 second choice slows down display updates considerably.
The next section of the display lists the six timeslots in the first column. The second column is for display purposes only and shows which timeslots the selected rate group uses. This can be changed on the "Define Rate Groups" tab. The third column, labeled "Display Pattern" is used to set which timeslots should be displayed in the lower part of this tab. The settings have no effect on the actual setup of the EVG. They just affect this display.
Next come one section for each rate in the rate group. This list of rates was defined on the "Define Beam Rates" tab of this GUI. Each of these sections has buttons to add or remove modifier bits. The line for each modifier bit allows one to setup the pattern that bit should have for that rate. Note that patterns MUST repeat every two seconds. There is no way to make, for example, a bit which is on once every 10 seconds. The individual columns are described below
Modifier Bit Column
Here one can select from a drop down list the name of a modifier bit. These names were defined on the "Define Modifiers" tab of this GUI. Any modifier bit whose pattern is not defined here on the "Define Patterns" tab will always be zero unless it is a bit handled special by the EVG (described in a later section)
If Column
The pattern of the modifier bit defined on this row will only come out if the hardware bit specified in this column is active. The BCSFAULT modifier bit uses this feature to make it so modulators fire on standby when there is a BCS fault. Note than an "If" defined for a modifier bit applies to all rates in the rate group even if it is only entered for one of the rates.
Frequency Column
Enter the frequency in Hz at which this bit should come out. While the interface will accept any integer, it is only reasonable to enter numbers that divide evenly into 720. Otherwise you will not actually get the exact frequency you request. In case of the 'beam_code' modifier bit, if you do not enter a valid frequency value, you will receive an error message when you try to put the checked rate groups to EVG. The valid frequency values are 1, 10, 30, 60 and 120. Also, if the beam code TMSK value is not a subset of the Active Klystrons and sub boosters TMSK value, you will receive an error message and will not be able to save the configurations to EVG.
Also note that if you request a bit to be output on timeslots not used by this rate group, you will receive a warning and that output will NOT actually occur.
Offset (1/360 sec) Column
The pulses (and columns on the right side of this display) are numbered from 1 to 720 for a 2 second period. By definition, pulses 1, 7, 13… are on timeslot 1 and pulses 2,8,14… are on timeslot 2 etc. This offset gives the number of the first pulse that should be set to the value given in the next column. It will be set for this pulse number and for pulses numbered N*int(360/frequency)+offset for all pulses numbered 720 or less. That two second pattern then gets repeated forever.
Value Column
This gives the value the bit field should be set to.
Handling irregular patterns
Sometimes it is desired to have an irregular pattern. The canonical example of this for the LCLS is the NO_GUN_PERM bit. We always output the beam code at 120 Hz and turn on the NO_GUN_PERM modifier bit on pulses where we don't want beam. So to get beam at 10 Hz, NO_GUN_PERM must be on 110 times per second. These are not evenly spaced. Rather it is a 120 Hz pattern with every 12th one missing. This can be done by putting the same modifier bit on two or more adjacent rows. The pattern starts out all zeros and the effect of each row is merged in, in order. An example will make it clear.
Note that the second NO_GUN_PERM line has the desired pattern which is what the EVG will output.
Special modifier bits
Some modifier bits are used so universally and are so important that the patterns are hard coded into the EVG and it is unnecessary to set them up via this GUI. These include
- The six timeslot bits (TS1…TS6)
- MOD720RESYNC (used to resynchronize PDUs)
- PULSEIDRESYNC (Put out every few minutes to resynchronize the pulseIDs)
- 64 bits from the linknode MPS system occupy positions after the 128 bits controlled here
- MPG_IPLING is set if any error occurs
- I think it sets SHUTTER_PERM if POCKEL_PERM is set.
- It sets KICKER_LTU according to some algorithm.
- There may be a few other bits set in special fashions. Note that all but the first three bullets are old EVG code that has nothing to do with the new stuff that allows us to phase out the MPG.