The screen layout, apart from the menu bar, consists of two types of graphic areas in which the values for the arrays of process variables are shown: Display areas, which display one or more arrays as a function of index, and a zoom area. In the zoom area specified arrays only are displayed as a function of lattice position along with symbols for the major elements of the lattice. There can be several display areas, but at most one zoom area. When the screen is resized these areas change size proportionally.
There are a number of options in the View Menu to change the way the values are displayed. It is also possible via the Options Menu to:
There are several (currently 5) slots in which you can store values internally. In addition you can display the values with specified reference values subtracted.
New values are sent to the program anytime the process variables change outside of their dead band (as specified in the control system record for that process variable). If the dead band is chosen appropriately, this should result in less traffic over the control network than if all of the values were polled at fixed intervals. The current values that have been received are displayed whenever the screen updates. It is also possible to manually update the variables via the Options/Epics/Rescan menu.
The program continuously updates and displays the standard deviation, average, and maximum absolute values for each array and will show the envelope of recent values if desired. The time between updates can be changed via the View Menu or may be specified in the PV file. Whether the statistics are for the current values or accumulated over a period of time is controlled by the Accumulated Statistics button in the Options Menu.
There is a configuration file that is needed to get ADT running. Most of the features of the screen layout, including what process variables are shown in what display areas, are determined by a PV file. The contents of this file determine such things as curve color, units, and scaling. Another relevant file is a lattice file, which specifies the symbols and longitudinal lattice positions of the elements in the lattice. Sets of values can be saved and restored via snapshot files.
Most of the available options can be discovered intuitively by looking through the menus. This manual is primary for reference and is not a tutorial.
The command line for ADT is of the form:
adt [Standard X Options] [-x] [-f pvfilename] [-a adthome]
It accepts any of the standard X-Window options, such as -display machine:0. The other options are:
Both adthome and pvfile must include a path if they are not in the directory from which adt is started.
The units per division of the display area can be changed by a control above it, as can the center value. There are also arrow buttons to change the center value by one unit per division. The starting units per division, center values, and a factor by which to multiply the raw data to get the desired units are set in the PV file, which also determines which process variables are displayed and the heading and units.
The standard deviation, average, and peak absolute values are shown and updated when the values are updated. (The standard deviation defined with n rather than n-1 is used since the whole population is known.) The peak absolute value includes the sign of the value that was largest. The update time interval can be changed in the View/Timing menu. If a log scale is used, the values displayed are the logirithms (base 10) of the actual values.
The units per division and the center value of the zoom window can be changed by the controls above it the same as for the display areas. The default units per division is the largest of those specified in the PV file and the default center value is the average. The length of the interval of the lattice shown in the zoom area an be changed via the box labeled Interval:. The sector shown in the box labeled Sector: is the sector that is at the center of the display area and can be varied by typing a new number or using the arrow buttons. In addition, numbers designating the sectors and a mark identifying the center of the display area are displayed in the zoom area to help identify the sectors and the midpoint for mouse scrolling.
The zoom area can be turned off entirely, and it does not appear if the process variables cannot be matched with the lattice elements in the lattice file or if no arrays are specified to appear in the zoom area.
There should be subdirectories pv for PV and lattice files and snap for snapshot files. There may be a similar set of subdirectories, xorbit/pv and xorbit/snap, for files used with Xorbit simulation.
All of these files may be located elsewhere if desired. See Configuration.
The help package also refers to screen layout files:
that are assumed to be in subdirectories, pv and snap, relative to the location of adt.html. If they are not there, you will not be able to view them from Mosaic.
The executable file, adt, should be located in a directory somewhere in your $PATH.
The application defaults file, ControlApp, is not required or necessary. If it is used, it should be located as specified in the section on the application defaults file. You can specify personal modifications to the resources in your .Xdefaults (or equivalent) file or in your own ControlApp file in your home directory. (See an X Windows manual for the involved search path that X uses to find resources.)
The directory for the configuration file may be specified on the command line with the -a option, in which case the program looks for a file named adtrc in that directory. If not specified, the program looks for it first in your home directory with the name .adtrc (with a dot). If one is not found, it next looks in the directory given in $ADTHOME if it exists, otherwise in the current working directory, for a file named adtrc (with no dot). If it still has not found one or it is invalid, there will be no options in the File/Load menu except Custom; the PV and snapshot files will be assumed to be in subdirectories, pv and snap, to the current working directory; and the help files will be assumed to be in the current working directory.
This configuration file is an SDDS[2] file. This manual assumes you are familiar with SDDS files. If not, you may need to consult the SDDS documentation to understand the meaning of terms such as parameter and fixed_value. The configuration file has string parameters, ADTPVDirectory, which specify the directory for the PV and lattice files, and ADTSnapDirectory, which specifies the suggested directory for the snapshot files. (Independently of these settings, Custom PV, custom lattice, and snapshot files may be read from or written to any directory by changing the filter in the file dialog box.) There are corresponding parameters, ADTXPVDirectory and ADTXSnapDirectory, which may specify different versions of these directories if Xorbit simulation is used. It is not necessary to do this. If the first two parameters are not specified and $ADTHOME exists, then they will default to $ADTHOME/pv and $ADTHOME/snap, respectively, and will default to ./pv and ./snap, respectively, otherwise. If the Xorbit parameters are not given, they will default to whatever is used for ADTPVDirectory and ADTSnapDirectory.
There is also a string parameter, ADTHelpFile, which specifies the location of the Mosaic[3] HTML help file. This file should be in $ADTHOME/adt.html. It defaults to $ADTHOME/adt.html if $ADTHOME exists and to ./adt.html, otherwise. If you are reading this in a browser, such as Mosaic, then you are probably browsing a version of the adt.html file.
If any file locations are specified through the above parameters, it is suggested that full pathnames be used.
Each page in the configuration file corresponds to one submenu. The required parameter ADTNMenus specifies how many submenus (pages) there will be. It is required because there is currently no way to tell how many pages are in an SDDS file until it has been read and the number is needed to allocate space. ADTNMenus applies to the whole file and should be a fixed_value, short parameter. The Parameter ADTMenuTitle is a string parameter which specifies the label for each submenu button.
There are two string columns, ADTPVFile and ADTMenuLabel, which give the name of a PV file (without the path) and the label that will appear in the File/Load submenu in order to select this file. These PV files will be expected to be in the ADTPVDirectory. If these columns are not there, there will be no options in the File/Load menu except Custom.
An example configuration file should be located in $ADTHOME/adtrc.
Parameter Summary
Column Summary
You can make new PV files containing any process variables you wish to monitor, and you can save them in your own directories. The easiest way to make a PV file is to find an existing one and modify it. It should be fairly obvious where the changes are to be made. These can then be read in from the File/Load/Custom menu. An example PV file should be located in $ADTHOME/pv/par.bpm.pv.
There are three types of SDDS parameters that appear in a PV file:
The possible parameters that may be specified in a PV file are:
ADTFileType: A required, string parameter that should be "ADTPV". This is a global parameter that merely serves for file checking.
ADTNarrays: A required, short parameter that specifies how many arrays (pages) are in the file. It is required because there is currently no way to tell how many pages are in an SDDS file until it has been read, and it is necessary to allocate space beforehand. This is a global parameter.
ADTNareas: A short parameter that specifies how many display areas are in the file. It is required because there is currently no way to know it until the file has been read, and it is necessary to allocate space. If given, it must be the correct number for the display areas assigned by ADTDisplayArea. No unused display areas are allowed. If not given, there will be one array per display area. This is a global parameter.
ADTLatticeFile: A string parameter that specifies the lattice file to use for the zoom area. If not given, there will be no zoom area. This is a global parameter.
ADTReferenceFile: A string parameter that specifies the reference file to use. If not given, there will be no referencing. This is a global parameter.
ADTTimeInterval: A short parameter that specifies the time interval in milliseconds between screen updates. If not specified, the built-in default (currently 3000 ms) will be used. This is a global parameter.
ADTMarkers, ADTLines, ADTBars, ADTGrid, ADTMaxMin, ADTFilledMaxMin: These short parameters specify the default settings for the toggle buttons in the View menu. Positive is true, and 0 is false. If not specified, the built-in defaults will be used. These are global parameters.
ADTHeading: A string parameter that specifies the heading part of the title that appears above the display areas. The title includes the heading followed by the units in parentheses. There is a built-in default.
ADTUnits: A string that specifies the units part of the title that appears above the display areas. The default is a blank string.
ADTColor: A string parameter that specifies the named color to use for this curve. The name must be in the X Windows color database. Case is not important. If not specified, a built-in default will be used. Names can be of the form #rrggbb (like #110000 for Red).
ADTZoomArea: A short parameter that specifies whether this array is to appear in the zoom area. Positive is true, and 0 is false. The default is false.
ADTLogScale: A short parameter that specifies whether this array is to appear as the logrithm (base 10) of the value. Positive is true, and 0 is false. The default is false.
ADTScaleFactor: A double parameter by which all the raw data will be multiplied before being displayed. For example, to convert raw data in millimeters to displayed values in meters, the ADTScaleFactor would be 0.001, and the ADTUnits would be "m". If this parameter is not supplied, it will be taken as 1.0.
ADTDisplayArea: A short parameter that specifies in which display area to display the array. The display areas are numbered starting with 1 at the top. The default is to display one array per display area.
ADTUnitsPerDiv: A double parameter that specifies the default units per division for the display area for that array. If there is more than one array for that area, the last one is used. If this number is not one of the available values, the next-higher available value will be used. If this parameter is not supplied, the built-in default will be used. This is an area parameter.
ADTCenterVal: A double parameter that specifies the value that corresponds to the horizontal axis. The default is 0.0. This is an area parameter.
The PV file has one required string column, ControlName, which contains the names of the process variables in the array. Two other string columns are required for the PV file to be a valid BURT request file, a useful thing to do. These columns are ControlType and ControlMode. The control type is the string "pv" for process variable and the control mode is usually "RO" for read only. The PV file will have one more column for StatusName if status is implemented. In that case the column contains the names of the process variables that specify the status.
Parameter Summary
Column Summary
The parameters that must be specified in a Lattice file are:
ADTFileType: A required, fixed value of type string that should be "ADTLATTICE".
Nsectors: A required, fixed value of type short that is the number of sectors into which to divide the lattice for the purposes of scrolling.
Stotal: A required, fixed value of type double that is total length of the lattice in meters.
Ring: A required, fixed value of type short that is 1 for a ring and 0 for a beamline.
There is a program, xintolat, that converts Xorbit input (.xin) files to lattice files. Its usage is:
xintolat [-h] [file1.xin] [file2.lat]
If the filenames are not specified, the program will prompt for them.
The columns that must be specified in a lattice file are:
S: A required column of type double that is the position of the start of the element in meters.
Length: A required column of type double that is the length of the element in meters.
SymbolHeight: A required column of type short that is the relative height of the symbol for the element. Correctors should use 1, quadrupoles should use 2, and sextupoles should use 3. The sign of the number should indicate the sign of its strength.
Name: A required column of type string that is the name of the element. ADT will match elements to process variables by looking for this string as a substring of the process variable name.
Parameter Summary
Column Summary
These snapshot files should be equivalent to the ones generated by BURT, except that they are paged the same way as the PV files (which are valid BURT request files). BURT collects all the process variables in all the pages of a request file, alphabetizes them, and puts the results in a single page in the snapshot file. This makes it hard to extract the information that belongs to each array. There is no loss, other than a lack of strict compatibility, in retaining the array pages and not alphabetizing. Either the conventional BURT snapshot files or the ones from ADT are valid request files for BURT. Therefore, they can be used to restore the process variables in them if these process variables are capable of being restored. (Monitor readings and corrector read backs cannot be restored, for example. Corrector set points can.) You can save snapshot files in your own directories. An example snapshot file should be located in $ADTHOME/snap/par.bpm.snap.
The snapshot file will have two more columns, StatusName and StatusValue, if status is implemented, also unlike a BURT snapshot. You cannot restore the status, so this should not be a problem. For definitions of the other parameters and columns, see the BURT documentation. A summary is given here, however.
Parameter Summary
Column Summary
. These values will be subtracted from the raw data before it is displayed. Even if a reference file has been read, referencing can be enabled or disabled via the Options Menu. This feature can be used to specify monitor offsets, for example, and to display the monitor readings relative to the monitor offsets, which is usually a more desirable thing to do. Referencing is similar in operation to differencing, except that it can be specified in the PV file. You can have both differencing and referencing on at the same time. The reference values in this case, however, will be subtracted from both the data array and the difference data array, which are then subtracted, so it is the same as having referencing off. (The code is smart enough to avoid the subtracting.)
Any snapshot made from the screen layout may be used for a reference file, and the requirements for a reference file are the same as those for a snapshot file. In particular, the reference file must contain the same arrays with the same elements as the PV file specifying the current screen layout. If this snapshot file cannot be made by saving values from ADT, then it would probably be wise to take a file that has been so saved and change the values.
If you do need to changes the resources for your personal needs, the resources are listed in resources.h, a file that is included in the distribution for ADT. ADT may also be used with the X client, Editres, to find the resource names, change them, and experiment with them.
In order to enable this capability there must be an additional string column in the PV file called StatusName. Each entry in this column should contain the name of the process variable that has the status information for the process variable that is to be displayed. If there is no status name or you don't want to use it, the entry should be a "-". If the column is not there, there will be no indication of status other than for process variables that are not connected.
When this has been done, the display should be the same as usual when the data is Valid. Otherwise there will be color-coded markers that indicate the status. Snapshot files will have two additional string columns, StatusName and StatusValue, to indicate the status. In addition to the three values above, StatusValue may also be NotConnected if ADT was unable to find either the process variable for the data or for the status.
Because of the asynchronous nature of EPICS, there is no guarantee the status displayed in ADT is exactly coordinated with the data, but it should be close. Decreasing the update time may make the status markers more accurately reflect what is happening.
Xorbit can in principle be made to simulate the orbit for any of the lattices in the APS, although not all of them have been implemented at this time. To do this there is a special database of process variables in an IOC. These process variables closely resemble the real process variables for monitors and power supplies and have the same names with "Xorbit:" attached. When setpoints for magnet power supplies are changed via the control system, Xorbit is notified and calculates the appropriate orbit. It then supplies the new readings to the readbacks for the power supplies and monitors. This process takes about 4 seconds for the over 3000 process variables for the storage ring, but is essentially instantaneous for the PAR.
The simulation includes the effects of random magnet displacements and monitor offsets and includes nonlinear effects from the sextupoles. This simulation capability allows physics application codes to be tested and debugged on something resembling a real system without disturbing the real system or before the real system is operational.
ADT may be run in Xorbit simulation mode by specifying -x on the command line. In this mode it attaches "Xorbit:" to the front of all process variable names when it reads them and removes this pattern when it writes them to a file. Consequently, PV files may be tested with Xorbit with no change to the files, provided the lattice has been implemented in Xorbit and provided the actual names and the names in the Xorbit database follow the same naming conventions.
Xorbit calculates magnet strengths in theoretical units (e.g. radians for corrector magnets) whereas the real process variables correspond to power supply currents (Amperes). The relationship between the current and the strength depends on the magnet hardware and the energy of the beam. The Xorbit database has been designed to convert between theoretical units and Amperes, taking these relationships into account.
[2]SSDS stands for Self-Describing Data Sets and is a format developed by Michael Borland to provide a flexible and standard, general purpose, file format. There are routines available for reading and writing SDDS files.
[3]This manual was designed to be printed and also viewed on-line in Mosaic. Mosaic is an information browser that connects to many information sites on the Internet and World Wide Web. It was developed at the National Center for Supercomputing Applications at the University of Illinois.
[4]BURT is the backup and restore program for the APS control system.