Jerry Cai (Fermilab)

January, 2009

An initial version of the high level Schottky Software for LHC at CERN
has been developed. It fulfills the requirements listed in the document
"4.8 GHZ SCHOTTKY SOFTWARE -- HIGH LEVEL REQUIREMENTS[^1]" by Dave
McGinnis (Fermilab) and R. Steinhagen (BE/BI) etc.

Introduction
============

The Schottky Software consists of two main parts: a Monitor Application
and a Control and Display Application. The Monitor Application, also
known as the Daemon, will run continuously and unattended, with no GUI.
One or more Control and Display Applications, also known as the GUI, can
run to gather and view data from the Daemon. Exactly one GUI may be
enabled to control the Daemon.

This user guide provides an introduction on the functionality and use of
the current version of this software suite. In this guide, we insert a
number like this, \[3.20\], to represent the requirement number in the
requirements document that is satisfied by the proceeding information.

The Monitor Application
=======================

Motivation
----------

The Monitor Application runs unattended as a daemon process. It is
intended to implement three main tasks:

1.  To be the exclusive client that reads the raw data from the Schottky
    front ends.

2.  To perform various fits on these data and to publish these fit
    results for the consumption of the Control and Display
    Application(s) and other users (for example the logging database).

3.  To send the appropriate configuration parameters, for specifying the
    appropriate hardware settings, to the front end(s) based on the beam
    mode of the LHC.

The last point is crucial to the understanding of this suite. It is
known from operational experience at the Tevatron that the Schottky
hardware must be configured differently for the different beam states in
the system. Since these beam states change as the LHC passes through its
cycle(s), an agent must be identified to watch for these changes and to
update the hardware appropriately. It is not advisable to have this
responsibility rest in a GUI application. This daemon is assigned this
responsibility. The Control and Display Application provides a GUI
through which the user can affect these configuration files.

User Guide
----------

Here is an outline of the operation of the Monitor Application.

When the Monitor Application starts, it creates four independent threads
corresponding to the four Schottky detectors in the LHC: **BEAM1-H**,
**BEAM1-V**, **BEAM2-H**, **BEAM2-V**. Each thread starts by reading a
default configuration file and applying these settings to the hardware.
Then, it subscribes to the FFT trace data from the front end at the
specified rate \[2.10\]. The Monitor Application does curve fitting for
the acquired FFT trace, producing the tune, momentum dispersion,
emittance, chromaticity, noise background and fit quality \[3.10\]. It
also calculates the averages of the FFT spectra and of the parameters
mentioned above, then publishes this continuously at the same rate the
DAB board is set to acquire data \[3.20\]. The Monitor also maintains a
circular buffer of the last 200 FFT spectra, fitting parameters and
their averages for post-mortem check \[4.20\][^2].

The Monitor Application runs continuously as a daemon. It archives, into
local SDDS files[^3], FFT spectra and fitting parameters, including the
averages, for regular measurements and post-mortem data at the specified
rate for each beam mode \[4.10, 8.80\].

Control and Display Application
===============================

Motivation
----------

This GUI has two purposes:

1.  To allow the display and manipulation of the data produced by the
    Schottky and

2.  To allow the user to affect the operation of the Monitor
    Application/Daemon.

The default mode of this application allows only the display mode. One
must request setting rights from the daemon in order to change the
operation of the daemon. Only one GUI may have setting rights at a time.

User Guide
----------

When an instance of the Control and Display Application is launched, the
RBA credentials are checked in the normal way. If there are no
credentials, the user will be asked to perform an RBA authentication
\[1.30\].

The initial GUI is shown in Figure 1. The GUI is divided into four parts
(as marked on the figure):

-   **Left-Selection-Panel**,

-   **Top-Tool-Bar**,

-   **Bottom-Console**, and

-   **Central-Tabbed-Panel**.

Figure 1. The general view of the Display and Control Application

We will discuss each of the labeled areas of this GUI in turn.

### Left Selection Panel

The **Left Selection Panel** has three blocks, see Figure 2 and Figure
3. The first one is "**DEVICE**" which allows the user to select a
device, such as **BEAM1-H** or **BEAM2-V**. The selected device name
will also be shown on the title bar. The second block has two tabs:
**Running Mode** and **Measure Mode**. Under **Running Mode**, there are
two running modes for selection: "**READ ONLY**", and "**READ and SET**"
\[1.60, 6.50, and 6.40\]. (They may be re-named as "**DISPLAY**" and
"**CONTROL**" modes as reflected in the name of application, **Display
and Control Application)**. The "**READ ONLY**" mode is the default
mode. Most of time, the GUI should be running in this mode. In this
mode, the Monitor Application sets the Front End with the parameters
specified from the default configuration file.

For the user to change the parameters used by the daemon, and thus the
front end, the GUI must be placed in the "**READ and SET**" mode . Upon
entering this mode, a popup window will appear in order to ask the user
for the estimated time (in minutes) the user needs. The maximum time a
user may request is currently set to 10 minutes. This information is
captured and sent to the daemon, which then sends it to all other
Control and Display instances. For example, in Figure 2 the user "jicai"
has control of the Monitor for the next 297 seconds. When another user
launches an instance of Control and Display Application, s/he will see
which running mode the Monitor Application is running, either "**READ
ONLY**" or "**READ and SET**". If it is in the "**READ and SET**" mode,
it will also show who has set the Monitor Application into "**READ and
SET**" mode, and how long this mode will last.

When the application is running under "**READ and Set**" mode, no one
else can change it. This is to make sure that the measurements from the
controlling user will continue unimpeded. When the estimated time
expires, the monitor will automatically switch to the default "**READ
ONLY**" mode, and monitor parameters will be replaced with the default
ones. The controlling user can click on the "**READ and SET**" button at
any time to change the estimated time before it is expired.

![left\_pane1.jpg](media/image2.jpeg){width="2.7948720472440947in"
height="5.814103237095363in"}
![](media/image3.jpeg){width="2.7762685914260716in"
height="5.840579615048119in"}

Figure 2 and figure 3. The Left-Selection Panel for GUI of Display and
Control Application

If the monitor is running under "**READ ONLY**" mode, any user can
change it to "**READ and SET**" mode. This is to make sure that the
**Control and Display Application** may have more than one instance to
view data simultaneously, but only one instance at a time to control the
**Monitor Application** \[6.40, 6.50\].

There are three selections under the **Measure** tab,

-   "**AUTO**",

-   "**Manual**" and

-   "**Standby**".

The Requirements Document states, "The Monitor Application should be
able to put in a standby mode" \[1.50\], which the third option
implements. One must be in "**READ and SET**" mode to put the Monitor
into standby. The selection of "**Manual**", at this moment, is
implemented only for the control in the **Electronic States** tab, which
will be discussed later. In the "**Manual"** mode, user can manually set
amplifier switch to either pilot or nominal branch, or change the
amplifier gain or attenuator factor, but the new entered setting status
or new values will not be overwritten by those parameters specified in
the configuration files when the beam mode changes \[8.10\]. The
"**AUTO**" mode is the default and is appropriate for most normal
measurements. The user is allowed to change to "**Manual**" or
"**Standby**" mode only when the **Running Mode** is in "**READ and
SET**". When the **Running Mode** changes to "**READ ONLY**" mode, the
Measure Mode will automatically change to "**AUTO**".

The third block shows what Beam Mode the Monitor is running, such as
RAMP, FLAT TOP, SQUEEZE[^4] etc. The Monitor Idle Time is also shown
there, which tells how many seconds has elapsed since data were received
from the Monitor, so it functions as a "heartbeat" for the Monitor
\[1.40\]. If this monitor idle time is too long, it may mean either
Monitor is dead, or the communication channel between Monitor
Application and Control and Display is broken. (We might need another
parameter for Front-End idle time in future when the FESA class for
Front-End becomes available).

Many other parameters are shown in the third block, such as [Average
Number]{.underline} used to calculate the smoothed FFT spectra, and
[calibration factor]{.underline} used to calculate emittance and many
other parameters under the tab **Parameters**, such as [center
frequency]{.underline}, [frequency span]{.underline}, [resolution
bandwidth]{.underline}, [trace rate]{.underline} etc\..., are used to
show that we can also display and change these parameters by entering
the new values from here. We will discuss another way to change the
monitor parameters by loading a configuration file with the attempted
new setting values from **Configuration Editor** Tab. Which is
preferable? Comments are welcome!

### Top Tool Bar

The top part is a tool bar, see Figure 4, and Figure 5, which allows a
user to exit the program, to save the current data instantly , to read
archived data, to refresh acquisition after read archived data , to stop
data acquisition temporarily( red square icon), or return to normal data
acquisition state( green triangle icon) etc.
![tool\_bar2.jpg](media/image4.jpeg){width="6.067708880139983in"
height="0.43in"}

Figure 4. The Top-Tool Bar for the GUI of the Display and Control
Application

![tool\_bar.jpg](media/image5.jpeg){width="6.067708880139983in"
height="0.4270833333333333in"}

Figure 5. The Top-Tool Bar for the GUI of the Display and Control
Application

### Bottom Console

The part in the bottom is a console to show the important messages while
the program is running. See Figure 6.

![console.jpg](media/image6.jpeg){width="6.367948381452319in"
height="1.1757239720034995in"}

Figure 6. The Console to show important messages.

### Central Tabbed Panel

The most important part of the application is the Central Tabbed Panel,
which has five tabs for displaying the data from the Monitor, and for
affecting the operation of the Monitor and of the Schottky itself. These
tabs are:

-   **Contour & Trace**,

-   **Time Plot**,

-   **Electronic states**,

-   **Tune Resonance Line** and

-   **Configuration Editor**.

The **Contour & Trace** tab, see Figure 7, displays a contour of 20 FFT
traces, with the newest FFT trace highlighted on the bottom. Also on the
bottom chart is shown the fitted curve and averaged FFT data, along with
the fit results in the yellow box. The contour and trace are updated
continuously. The user can click on a contour to select it to display on
the bottom chart \[8.10, 8.20, 8.30, 8.60\]. Because both the contour
and trace are updated regularly, the selected trace will be replaced
with a new one when it is received. If more time is needed to exam the
selected trace, the user can click on the "**stop**" icon (the red
rectangle) on the tool bar (Figure 4). When done, the user should click
on "**run**" (the green triangle, Figure 5) to resume the updates.

![contour.jpg](media/image7.jpeg){width="6.5in" height="5.375in"}

Figure 7. Contour and Trace tab

Recall that the Monitor archives data regularly based on the parameters
specified in the configuration file. However, if the user needs to save
some trace data for their own use, then click on the icon "**Save an
SDDS file**" on the tool bar. A file chooser will be shown to allow user
to select a file in which to save the current data (Figure 8). The time
stamp and the "sdds" extension will be added automatically.

![save.jpg](media/image8.jpeg){width="5.25in" height="3.625in"}

Figure 8. Save current data to a file.

To retrieve one of these saved traces, click on "**READ a SDDS File**"
on the tool bar. Then a file chooser will display the archived files,
including the most recent post-mortem file, which contains 200 traces
(it will look just like the popup in Figure 8). \[8.70\]

Use the **Contour & Trace** tab to look at the saved contour and each of
its FFT traces, including the averaged ones, and their fitting results.
(The user can do the same to select any specific slice to display on the
trace plot panel as it is in normal data acquisition). See Figure 9.

When the user wants to return to normal data acquisition, click on the
icon "**REFRESH daq**" on the tool bar.

![postmortem\_time\_contour.jpg](media/image9.jpeg){width="6.395833333333333in"
height="5.729166666666667in"}

Figure 9. Display the archived postmortem file for the contour and
trace.

Click on the tab "**Time Plot**" to show the time plots for the tune,
momentum spread, chromaticity and emittance , including their averages,
over the time as shift data. The time is shown as the last 20
measurements, just like in the Contour & Display tab, with the newest
measurement shown in slot 19 (the 20^th^ slot, starting from 0). See
Figure 10. \[8.50\]

![timeplot..jpg](media/image10.jpeg){width="6.322916666666667in"
height="5.429907042869641in"}

Figure 10 Display the time plot for the tune, momentum spread,
chromaticity, emittance and their average ones over the time slots as
shift data.

If one clicks on the icon "**READ a SDDS File**" on the tool bar to read
archived file, and use Time Plot tab, then, the tune, momentum spread,
chromaticity, emittance and their averages saved in the archived file
will be shown as in Figure 11. ( For this example, the selected archived
file is a Post-Mortem file with 200 saved traces)

![postmortem\_timeplot.jpg](media/image11.jpeg){width="6.177083333333333in"
height="5.46875in"}.

Figure 11. Display the archived postmortem file for its tune, momentum
spread, chromaticity and emittance as function of time.

Clicking on the tab **Electronic State** will show a schematic of the
electronics in the Schottky front end, see Figure 12. This shows,
graphically, the present state of the front end, which is determined by
the configuration that the daemon has put into the front end. This
changes when the beam mode changes, or when the user explicitly changes
it\[8.10\]. This is discussed further, below.

![electronic\_state.jpg](media/image12.jpeg){width="6.198611111111111in"
height="5.260416666666667in"}

Figure 12. Electronic State Tab

The parts of this schematic that can change are:

-   Four front end amplifier switches will select either the pilot or
    the nominal branch.

-   The amplifier gain and attenuator factor.

> The normal way for these values to change is for the daemon process to
> set them, based on the configurations it has for the particular beam
> mode that is active now. However, the user can manually set these
> values at any time as follows. First, change the mode to "**READ and
> SET**" (see page 3). Then, go to the "**Manual**" mode (see page 4).
> Then the user may change any of these values dynamically. Clicking on
> a switch will toggle that switch. Clicking on a number will pop up a
> change dialog box for changing that number. Note that in this
> "**Manual**" mode, the parameter values will not be overwritten when
> the beam mode changes.

By clicking on the tab **Tune Resonance Lines**, you will see the Figure
13. Because the scale is too large, it is hard to see the details of the
track of the tune. To change the scale, use the mouse and drag a
rectangle around the resonance tune points: you will see something
similar to Figure 14. Currently, we track only 20 tune values. The last
tune will be removed after a new tune values is updated. To get back to
the figure similar to Figure 13, simply right-click on the chart.
\[8.40\]

![tune\_lines1.jpg](media/image13.jpeg){width="4.26182195975503in"
height="2.7394367891513562in"}

Figure 13. Tune Resonance Line in large scale

![tune\_lines2.jpg](media/image14.jpeg){width="4.294688320209974in"
height="2.8098589238845144in"}

Figure 14 Tune Resonance Line in small scale

Click on the tab **Configuration Editor** and you will see something
similar to Figure 15.

![configEditor.jpg](media/image15.jpeg){width="6.1875in"
height="4.645833333333333in"}

Figure 15. Configuration Editor tab.

The top part of this tab is a table, which shows the front end
configuration for each defined beam mode \[7.10\]. In this example, we
have defined configurations for four beam modes: 0 through 3.

Each beam mode has eight parameters, they are:

-   The amplifier gain ("Amplif"),

-   The attenuator factor ("Attenua"),

-   Four pilot switch states,

-   How long to archive one set of data ("Archi P"), and

-   Maximum number of the data sets is to archive on each specific beam
    mode ("Archi N").

This is only for the illustration purposes. More parameters may need to
be added. For example, we can include all parameters, such as center
frequency, frequency span, resolution bandwidth, trace rate, calibration
factor, average number, etc., in this table. Some parameters may be beam
mode independent. The Monitor Daemon will reset parameters only when the
beam mode changes.

The user can edit any value in the table by double clicking on a cell
and entering a new value (followed by pressing the *Enter* key). The
user can also use the button "**Add New Beam Mode**" to add a new row to
the table for a new beam mode. The user can also highlight a row, and
then click on the button "**Remove Beam Mode**" to remove a beam mode
from the table.

Click on the button "**Read Config from File**" and a file chooser will
show all saved configuration files. Choose one of the configuration
files to display its contents on the table, including the comments,
similar to that shown on the Figure 15. The file name will be shown on
the top of table. One can also save a configuration in a new or existing
file by clicking on "**Save Config to File**". \[7.40, 7.50\]

![configEditor2.jpg](media/image16.jpeg){width="6.083333333333333in"
height="4.479166666666667in"}

Figure 16. To view and set bunch gates

The bunch gating information for each beam mode is available by clicking
first on the beam mode of interest, then clicking the "**Gating
Selection**" button. You will see something similar to Figure 16. There
are more than 2000 possible gates for LHC, so it is not possible to
represent the bunch gate setting with a simple value such as amplifier
gain, etc. To change the setting of a gate, you can either enter a
pattern like "1-100:2" on the Bunch Pattern field, then click on the
button "**set**" on the up-right, or one can select or de-select the
exact check boxes desired. (The key for the shorthand selections is
shown in the middle area of this panel.) Accept your selection by
clicking "**Accept**", or one can "**Cancel**" the selection.

If the user wants to know the current beam mode configuration being used
by the Monitor, click on the button "**Read From Monitor**". The values
of the table will be updated with the current configuration values in
the Monitor. Highlight a row, then click on the button of "Gate
Selection", you will have the current gate settings for the selected
row/ beam mode.

When the user clicks on the button "**Load To Monitor**", the Monitor
will be loaded with your new data. Please remember to change the running
mode to "**READ and SET**" mode before load your new setting values to
Monitor. When time expires, the Monitor will automatically switches to
"**READ ONLY**" mode, and the setting parameters will be replaced with
the default ones.

Whenever the parameters in the daemon change, either the user loads it
with new data, or monitor automatically switches to a new one, the
information, including "Who, When, and What" will be logged into log
files.

Click on the button "**Read Log History**" \[7.60, 7.70, 7.80\] to see
the log files. Select one and its contents will be shown on the table,
including using "**Gate Selection**" button to see gate settings. It
will also show information on when and by whom the log was created in
the OUTPUT INFORMATION area.

The final button "**Reload default**" is to allow the user to select a
new default configuration file to load to Monitor. This button differs
from the button "**Load To Monitor**" in that the "**Load To Monitor**"
is temporary. When the time expires, it will automatically switch to the
default configuration. The "**Reload default**" changes the parameters
in the Monitor permanently until another user uses the same button to
load another default configuration file to monitor or the daemon is
re-started.

Summary
=======

In summary, this initial version of the Schottky software has covered
all the features described in the requirement document. There are many
possibilities for further improvements, especially through feedback from
operations on this suite.

One very important issue is that the FESA class for the Schottky
front-end is not yet available. At this moment, we are using data from
the Tevatron at Fermilab.

End notes
=========

[^1]: <https://edms.cern.ch/document/908986/0.1>

[^2]: The Requirements Document asks for 500. It has been determined
    that 500 traces is very slow in the GUI, so 200 has been selected
    for this initial version of the software.

[^3]: It is thought that the data written by the Monitor will be to
    database tables. For the purposes of this demonstration, it was
    chosen to write to SDDS files.

[^4]: These beam modes are simulated at this time. This information will
    be read from the LHC telegrams.