Users Guide for the LCLS Save COmpare and REestore (SCORE) application
#Opening a Save Set (Snapshot)
#Filtering - Select Area and Select Subsystem areas
#Filtering - Signal Name Filter
#Select All / Display Selections Buttons
#Snap n Save All - Create a save set (snapshot) of the machine
#Compare to an existing save set (snapshot)
#Load an existing save set (snapshot)
#Activate an existing save set (snapshot)
What does it do?
The LCLS Save COmpare and REestore (SCORE) stand-alone application provides capability to: 1) save machine settings and their associated readbacks, 2) compare saved settings to the live machine values, and 3) restore the machine to a set of saved values.
For the 2008 commissioning, LCLS SCORE will operate alongside SCP Configs and will handle all EPICS setpoint signals as well as both old (slc) and new magnets. In the future, a new Save/Restore application, based upon SCORE, will replace SCP Configs and SCORE.
How do I start it?
From lclshome: Press the "Save/Restore..." button on the Tools tab on the right side of the LCLS Home Screen. Score runs in the context of a shell window entitled "score". This shell must not be closed, or it will terminate the score application itself. Look to the shell window for detailed status and error messages.
Stand-Alone: From the command-line, type "score".
GUI Components
The main window has the (xal application) file menu items on top. Underneath is the "toolbar" containing buttons for saving and restoring. On the Left Hand Side are panels for selecting subsystems, areas, and signals to filter upon for display purposes. In the middle of the main widow is a tabbed panel with a series of tabs. There is always one tab to open snapshots and one tab to edit the currently opened snapshot's comments. Once a snapshot is opened, there are separate tabs containing a table for each selected area. Finally, at the bottom of the window is a text field for abbreviated error and warning messages to the user.
The score application runs in the context of a shell window entitled "score". This shell must not be closed, or it will terminate the score application itself. Look to the shell window for detailed status and error messages.
How do I use it?
By default, the application will try and connect to the Oracle database with a generic account that has access to tables used by operations and physics (viewed via the "Connect" button.)
Opening a Save Set (Snapshot)
Click the "Snapshot List" tab if it is not already selected. First select the region pulldown list (second from left on top) to select the group you are interested in. Once a group is selected - you can browse all the save sets for a given time range. Select the time range using the two date selectors at the top (you can edit any of the year- month-date- .. fields in these). Then click the "Find" button. A list of available save sets will appear below - sorted by date, and also displaying the number and comment for each set. Click on the row you are interested in and then click "Open Selected Snapshot" button. Note - if you just want an empty template of the save set (i.e. you just want to create a new save set and do not care at all about previous data), skip the "Find" step above. Simply click the "Open Selected Snapshot" button right after you have selected the region. This is useful for creating the first save set.
While a snapshot is opening, the GUI will appear to be "frozen". In the background, aida inquiries and channel access connections are being established. Once the snapshot is fully opened, the magnet subsystem and all the area tabs are automatically selected on the left, with the associated area tabs being displayed in the main window.
Golden Snapshots
Click the "Open Gold Snapshot" button to open the snapshot last tagged as gold. To make a snapshot gold, first select it in the list displayed on the "Snapshots" tab, and click "Make Selected Snapshot Gold" button. The golden snapshot has a 'Y'es in the last column and is displayed in gold.
Comments
Once a save set is selected and opened, you can edit the comments by typing in the text area and save via the "Save Comments" button. You are prompted for the initial comment when you "Snap n Save All".
Filtering - Select Area and Select Subsystem areas
Once a save set is selected and opened, you can select the portion of data you wish to display. If you want to see everything, click the select all button near the bottom left corner. Alternatively you can select only the systems and subsystems you are interested in and then click the "Display Selections" button near the lower left corner. A separate tab (and table) is created for each selected system being displayed. (Note that a "Snap n Save" operates on all signals, whether they are being displayed or not.)
Filtering - Signal Name Filter
To filter the displayed set of signals, enter any portion of any name(s) listed in the Name column - no wildcards necessary- and press "Display Selections".
Select All / Display Selections Buttons
The "Select All" button selects all areas and all subsystems of the opened snapshot and displays all of these signals in the area table on each area tab. The "Display Selections" operates on the combination of area and subsystem selected as well as the signal name filter typed in, if any.
Table Display / Colors
Within a table, device types are sorted (alphabetically). That is, for a given device type, the associated setpoint and readback process variables - (EPICS PVs) are sorted alphabetically by the PV names. Note that PVs for setpoints and for readback are treated differently (i.e. you can only "restore" setpoint values). It is not necessary to have both a setpoint and readback PV on the same table row.
Also - there is a tab in the table panel labeled "Comment". This is an editable text area for you to enter a description of the saved set.
Table layout / colors
For each table row, there is a column for:
- Subsys - each subsystem is listed with a blank row. Shared with Madname, if any
* Name - EPICS Signal name, without attribute. (Note equivalent SLC magnet names, for reference, would have IM20 versus IN20, LM21 versus LI21, etc)
- DES Save Val -the setpoint saved value in bold. The next three live value columns and following ACT Save Val column are compared to the DES Save Val.
- CON Live Val - the Configure setpoint live value (for magnets); brown unless differs from threshold, then red
- DES Live Val -the setpoint live value; blue unless differs from threshold, then red
- ACT Live Val -the readback live value; green unless differs from threshold, then red
- ACT Save Val -readback saved value; olive unless differs from threshold, then red
- Three more columns naming the setpoint (DES), readback (ACT) and configure (CON) attribute names. These attribute names can be appended to the Name, separated by ":" to form a complete EPICS name.
Generally, associated setpoint and readback PVs will be associated on the same row, but it is possible to have table rows with setpoint only.
Table display behavior / threshold Top
If a readback value is more than a user settable fraction different from the saved value, it is displayed in red. Here is the equation for threshold comparisons: ratio = value/DES Save Val; if (ratio > 1 + threshold value) or if (ratio < 1 - threshold value), display red. The live value displays are updated at 0.5 Hz for EPICS values and 0.25 Hz for SLC magnet values.
Snap n Save All - Create a save set (snapshot) of the machine
If you want to take a snapshot of machine settings, first open a save set by referring to the "Opening a save set" instructions above. Then click the "Snap n Save" button on the toolbar. You will be prompted to enter a comment. This comment can be edited later, at any time after the save (see Comment tab above). The timestamp for this save set is done automatically. After you create a snapshot, if there are any errors in the operation, you will be notified by a message in the error field at the bottom, and notified to "view -> console" to see details.
Compare to an existing save set (snapshot)
If someone already saved the machine state to a file and want to compare to it, first open a save set following the database connection and "Opening a save set" instructions above. Then follow the "viewing instructions above to compare live values with the saved ones.
Load an existing save set (snapshot)
If you want to update the present machine setpoints to those in the tables, first click the "Load All Tabs" or "Load Partial" button. The "Load All Tabs" loads all signals on every tab, whether they are selected or not. The "Load Partial" loads only selected rows of each tab. You can select rows by clicking on them (the usual multiple-selection features of drag, click with control, and click with shift work). A "Load *" for the magnet subsystem loads BCON values from the (BDES) DES Save Values. For all other subsystems, the setpoint is loaded with the DES Save Value. When you press "Load *", you will be prompted to see if you want to proceed. Also, a check is done to see if any of the restore PVs did not succeed (within 3 seconds). All setpoint failures are reported to the console window, which is viewable by clicking the "view" menu item on the top menu bar and selecting console.
Activate an existing save set (snapshot)
After a Load operation , if you want to update the present magnet machine setpoints (DES Live Val) to the configured value (CON Live Val), click the "Activate All Tabs" or "Activate Partial" button. The "Activate All Tabs" activates all signals on every tab, whether they are selected or not. The "Activate Partial" activates only selected rows of each tab. You can select rows by clicking on them (the usual multiple-selection features of drag, click with control, and click with shift work). An "Activate *" for the magnet subsystem loads BDES values from the CON Save Values. For all other subsystems, an Activate performs no operation. When you press "Activate *", you will be prompted to see if you want to proceed. Then you will be prompted to see if you want to trim. After the operation(s), a check is done to see if any of the restored PVs did not succeed (within 3 seconds). All setpoint failures are reported to the console window, which is viewable by clicking the "view" menu item on the top menu bar and selecting console.
Error reporting
When you open a snapshot or restore the machine to the saved values some error checking is done. A check is done on each PV action for a specified timeOut period (currently = 3 seconds). Any failed readback or setpoint actions are reported to the console (in red). The console output can be viewed by clicking the "view" menu item on the top menu bar and then selecting console, or by looking at the "score" shell window. An abbreviated message is also shown in the lower error text field.
Host Dependencies
- Oracle RDB (mccora2)
- Production webserver (mccas0)
- Various distributed Aida servers (SLC data provider, SLC Magnet data provider)
Contact
Contact: Debbie Rogind, drogind@slac.stanford.edu, 650.926.5183 or Judy Rock, jrock@slac.stanford.edu for assistance.