Users Guide for the LCLS Save COmpare and REestore (SCORE) application 

New LEM and SCORE Functionality
What does it do?
How do I start it?
GUI Components
How do I use it?
  Opening a Save Set (Snapshot)
  Opening a Region in which new signals have just been added
  Golden Snapshots
  Comments
  Filtering-- Display Red
  Filtering-- Area and Subsystem areas
  Filtering- Signal Name Filter
  Select All /Apply Filters Buttons
  Table display / Colors
  Save Region Region - Create a save set (snapshot) of the machine.
  Save the World- Create a snapshot for each region of the machine
  Compare to an existing save set (snapshot)
  Load an existing save set (snapshot)
  Activate an existing save set (snapshot)
  Error reporting
  Screen Capture
Host Dependencies

Contact

What does it do?  Top

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.



How do I start it? Top

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 OPI, type "score" (lower-case).


GUI Components Top

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 regions, areas, subsystems and signals to filter upon for display purposes. There is also a "Display Red" button to display only those signals that are out of tolerance when compared to their saved values. In the middle of the main widow is a tabbed notebook panel containing a series of tabs. There is always one tab to list and open snapshots associated with the selected region, 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. (Area and subsystem selection occur on the left panels.) 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 this SCORE shell window for detailed status and error messages.

When SCORE starts, it automatically opens the latest snapshot of the first region - Injector.

How do I use it? Top

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.) When SCORE first starts, it automatically opens the latest snapshot of the first region – Injector.

Opening a Save Set (aka Snapshot) Top

To open any save set, first pulldown the "Region:" combo box to select the region you are interested in. The last snapshot saved in this region is automatically opened. You can browse all the save sets for this region for a given time range by going to the the Snapshot List tab. 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. While a snapshot is opening, the cursor changes to its waiting symbol (hourglass equivalent in linux – spinning circle). In the background, aida polling (for slc devices) and channel access (for epics devices) 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. If there is no magnet subsystem included in the region, then all subsystems and areas are selected.

Opening a Region in which new signals have just been added  Top

After signals have been added to an existing region (which could have previously saved snapshots), the newly added signals will be displayed with a "box" in their DES Save Val cell, indicating NotaNumber (Nan), or null. The next "Save Region" will save the newly added signals.

Golden Snapshots Top

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 Top

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 "Save Region All". Maximum comment size is 255 characters. Note that a dialog box will prompt you for the initial comment upon saving.

Filtering-- Display Red Top

Once a save set is selected and opened, you can display only those signals which have any of their live values out of tolerance with respect to the saved value. For magnets, each device's check tolerance (obtained from each device via aida or channel access) is used as the +/- tolerance around the saved value when each live value / RB save value is compared to it. If the live value falls outside of this +/- window, it is considered out of tolerance and displayed as red. This applies to CON Live Val, DES Live Val, ACT Live Val, and RB Save Val. For all other subsystems besides magnets, the "Red Threshold" value is used as the +/- tolerance value. This value is obtained via the Special | Red Threshold menu.

Press the "Display Red" button to show only those signals that are out of tolerance in any of the Live Val columns. This button is a toggle button – press again to display all signals. The Display Red button works in combination with any filters that are applied by the area, subsystem, and signal name filters below.

Filtering--Area and Subsystem areas Top

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 "Apply Filters" button near the lower left corner. A separate tab (and table) is created for each selected system being displayed. (Note that a "Save Region" operates on all signals, whether they are being displayed or not.) Also, if you want to see only certain devices, you can type a string into the Signal Name Filter – see next section.

Filtering- Signal Name Filter Top

To filter the displayed set of signals, enter any portion of any name(s) listed in the Name column – no wildcards necessary-  and press "Apply Filters". The "Apply Filters" button applies to all of the following: 1) areas selected in the "Area Filter:" box, 2) subsystems selected in the "Subsystem Filter:" box, 3) device names typed into the "Signal Name Filter" box, and 4) Display Red filter. For example, to view only quadropole magnets, type "QUAD" (upper or lower case) in the "Signal Name Filter:" box and ensure that the magnet "Subsystem Filter" is selected as well as the desired areas in the "Area Filter:" box. Then press the "Apply Filters" button. If the Display Red button is also depressed (showing Red), only the red quads are displayed.

Select All / Apply Filters Buttons Top

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. If anything is typed into the "Signal Name Filter:" box, it is also cleared. Select All retains the "Display Red" setting; it does not over-ride it.

The "Apply Filters" button operates on the combination of areas, subsystems, signal name filter typed in, if any, and the Display Red function. In more detail, it applies to all of the following: 1) areas selected in the "Area Filter:" box, 2) subsystems selected in the "Subsystem Filter:" box, 3) device names typed into the "Signal Name Filter" box, and 4) Display Red filter.

Table Display / Colors Top

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 edit the description of the saved set.

Table layout / colors Top

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

For magnet devices, if a Live Val or ACT Save Val differs from its DES Save Val by greater or less than its check tolerance (obtained from the slc database (TOLS[LCLSH:2]) via aida or epics (CHCKBTOL) via channel access, then it will be displayed as red.

For non-magnet devices, if a Live Val or ACT Save Val is more or less than a user settable fraction different from the DES Save Val, 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.

Save Region - Create a save set (snapshot) of the machine Top

If you want to take a snapshot of machine settings, optionally open a save set by referring to the "Opening a save set" instructions above. Then click the "Save Region" 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.

If you do not open a snapshot in the region first, the region (indicated in the pulldown combo box) will automatically be opened prior to the save. This is necessary in order to establish signal connections to get the live data.

Save the World- Create a snapshot for each region of the machine Top

If you want to automate the process of sequentially taking a snapshot for all regions, click the "Save the World" button on the toolbar. You will be prompted to enter a single comment that will apply to all of the snapshots to be saved. SCORE will begin to cycle through all regions, first loading each region (to establish the signal connections for live data), then saving each region in turn. The cursor will change to the waiting symbol, and change back to the arrow when the operation has completed. You will then see a new snapshot for every region (in the Snapshot list). The last region to be saved remains opened. You can "view -> console" or scroll through the SCORE window to see the status of the operation.

Compare to an existing save set (snapshot) Top

If someone already saved the machine state to a snapshot and you want to compare to it, first open the desired save set, following the "Opening a save set" instructions above. You may press the "Display Red" button to view significant differences between the saved values of this saved set and current live values.

Load an existing save set (snapshot) Top

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 being displayed on every tab, whether they are selected or not. The "Load Partial" loads only the selected (highlighted) 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) Top

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 being displayed 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 Top

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.

Screen Capture Top

Press the camera icon on the toolbar to capture the screen and store as a *.png file. You will be prompted to enter a file name.

Host Dependencies Top

  • Oracle RDB (Host mccora2). This Oracle database server is shared with the elog and error log. The SCORE RDB is on this machine. If this host is down, or if the Oracle database server is down, SCORE is unable to save and restore.
  • Aida
    1. Production webserver (mccas0). Aida needs this to contact its nameserver, currently hosted in SCCS.
    2. Aida nameserver requires its Oracle database, SLACPROD, hosted in SCCS. If the SLACPROD instance, or afs (network) is down, SCORE is unable to restore magnets and receive live data from existing slc devices.
    3. Various distributed Aida servers (VMS SLC data provider, VMS SLC Magnet data provider). If any of these processes are down, SCORE is unable to restore magnets and/or receive live data from existing slc devices. All magnet BCON signals, whether the magnet is new and controlled by EPICS or existing SLC, require loading via AIDA since BCON control is via the SLC database.

New LEM and SCORE Functionality Top

(from Patrick Krejcik's power point presentation)

  • Overview
    • LEM Collect Data and Scale Magnets are now java packages that can be called from other HLAs like SCORE, in addition to the standalone LEM GUI.
    • SCORE has designated "-LEM" regions where it is understood that magnet BDES values are subject to energy scaling.
    • If you SAVE a snapshot in a SCORE "-LEM" region then energy data will automatically be collected and saved alongside magnet data
    • LOADing a "-LEM" region will likewise automatically collect energy data and scale the snapshot BDESs accordingly.

LEM's Collect Data Overview

  • Klystron phase and amplitude data are read (from SLC)
  • Online model knows the configuration of accelerating structures (number and length) per klystron and calculates energy gain along the linac
  • Collect Data returns a list of EACTs at every magnet in the region.
  • Collect Data puts the EACT values into PVs for general access

SCORE SAVE function

  • If a "-LEM" region was selected Save Region will go and Collect Data via LEM
  • (soon) A pop up window will appear with LEM graphics displays where you can see if LEM is currently "green"
    • You will be prompted whether to proceed with the SCORE Save
  • SCORE populates the EDES Save Val column
  • The EACT values are written to PVs and are recorded in the SCORE Snapshot in the EACT Save Val column. Note, EDES and EACT columns should now agree.
    • At this stage the EDES PVs used for LEMing have not changed

SCORE SAVE

  • TIPS
    • Look at the new message window
      • Did SCORE finish contacting LEM? Patience!
    • Use the Signal Name Filter to inspect EDES values
    • Note TRMS have no EDES, only the parent magnet has an EDES (to avoid potential discrepancies)
    • Some magnets are never LEMmed, so have no matching EDES in the SCORE Snapshot

SCORE Load

  • Select a Snapshot in a LEM region and click 'LOAD All Tabs' or 'LOAD Partial' will
    • Prompt to proceed with Scaling
    • If Yes, Collect Data and Scale Magnets
  • SCORE will now automatically generate a new Snapshot
    • New Snapshot will be labeled "id no. scaled to present energy"
    • write in the current EDES and EACT values
    • populate the BDES values with new SCALEd MAGNET values from LEM
  • User may compare BDES Save Val with current Live values in adjacent column Con Live Val
  • Prompt to proceed with Loading
    • If Yes, BDES Save Val is PUT to BCON PVs and BCON Live Val is updated

SCORE Activate

  • Activate Partial or Activate All Tabs will
    • PUT BCON Live Val into BDES PVs
    • PUT ECON Live Val into EDES PVs
  • Prompt to TRIM
    • If Yes, TRIM magnets and update the BDES Live Val column
      *This makes LEM green, you have made this Snapshot your new optics
  • User can verify that BACT Live Val agrees with BDES Saved Val
  • Partial Load and Activate allows selections amongst Quads, Correctors, Bends, and excluding certain regions

Usage

  • LCLSHOME has a new LEM-SCORE button as well as the old SCORE button.
  • Continue to use Matlab LEM for displaying graphics only
  • In place of LEMing the machine, recommend LOADing the same Snapshot whenever you think LEM should be made green
  • An additional LEM GUI with new graphics is coming next week


Contact Top

Contact: Debbie Rogind, drogind@slac.stanford.edu, 650.926.5183  or Judy Rock, jrock@slac.stanford.edu for assistance or for adding signals to regions.

  • No labels