Copyright © 2007 SLAC
These are requirements for a new "Correlation Plots" feature of the Physics Applications suite. This feature will help users to perform ad hoc experiments on the accelerators of SLAC accelerator complex (primarily LCLS), by scanning one or two independent control points through an interval, and reading the resulting values from some others. In this way the system can be used to make measurements and find correlations in the apparent behavior of the accelerator.
This section describes the status of this document at the time of its publication.
This is a draft and is intended to be reviewed both internally by the controls software section, and by potential users.
"Correlation Plots" (CP) is an interactive program which helps accelerator physicists1 to perform ad hoc experiments on the accelerators of SLAC accelerator complex (primarily LCLS), by scanning one or two independent control points (the "step", or "scanned" variable) through an interval, and reading the resulting values from some other dependent (or "sampled") variables. In this way the system can be used to make measurements and find correlations in the apparent behavior of the accelerator. One independent variable makes a 1-d scan, two independent variables may be scanned to make a 2-dimensional analysis (ie a surface plot). The system will include facilities to help in entering the names of variables, (both step and sampled), and range through which the independent variables' setpoints will be swept. It then conducts the data acquisition, paying attention to such things as settle time of magnets and klystrons, averaging, acquiring beam data on the same pulse, etc. When the measurements are completed the collected data can be viewed and plotted, and saved for later analysis.
Using CP it will be possible to make beam synchronous acquisitions using the LCLS event system (though not the SLC timing system, and so it will not support beam synchronous acq for a coordinated acquisition using both control systems of the same pulse).
The program described here will be based on the functionality of the SCP "Correlation Plots" facility [CRRREF] (and for continuity will also be referred to as "Correlation Plots", or simply "CP", until another name is decided on).
The XAL applications 1-d scan and 2-d scan may form the basis of Correlation Plots. Evaluation of them for suitability to implement Correlation Plots is part of this project.
This section deals with the required interactive functionality of CP. See below for non-functional, general and systemic requirements.
"variables" in the Correlation Plots sense, are most often the setpoint or readback values of a control system device. So they're often assigned to a process variable, and their value is the process variable's value. However, variables in CP may be assigned also from other more complex quantities, as described below.
As outlined above, there are basically two kinds of variable: stepped (sometimes called "scanned" since the acquisition 'scans' through a number of setpoints of this variable), and sampled - the variables whose values are acquired for each setpoint value .
When a variable name is entered, the user may use upper or lower case. CP should establish which is the proper name for actually making the acquisition, and replace, if necessary, what the user typed with the real name.
This section lists those types of control system control points which CP will be able to "step".
The following are listed in the order in which they would be matched, so that if all else fails they'll match "arbitrary" EPICS PV.
Action of stepping TIME is simply to wait (non-blocking) the Δt seconds.
A "multiknob", which is a file containing a list of devices (almost always magnets) whose values are to be changed by the "value" of the multiknob, times a coefficient for each device, which are also in the file.
Defined by: the name of the MKB file
including .MKB extension. Step range is defined by 3 floats:
start-value, increment, end-value-min. Recognised by:
regexp .+(\.mkb)$, ie anything ending ".MKB".
Action of stepping a multiknob will be done initially through the AIDA API. The value of the step scan is used as the passed value of the MKB (and is subsequently used by the MKB software to scale all the magnets in the MKB file by the passed value times the coefficient in the file. That is, they're always treated as relative knobs. See [AIDA-MKB].
A single magnet controllable by the EPICS magnet control
system. Defined by: the PV name of a magnet. Recognized as an
EPICS magnet B-field PV by the name matching a regular expression
like /(XCOR|YCOR|LGPS).+:BDES[\.VAL]/. Step range
is defined by 3 floats: start-value, increment, end-value-min.
Additionally the user must be able to specify which trimming method (one of "trim" or "perturb") is to be used.
Action of stepping an EPICS magnet is to set the BDES by Channel Access, and affect trim operation by the trim method specified (Q: where can we find the API for EPICS magnet control?).
A single magnet controllable by the SLC magnet control
system. Defined by: the AIDA name of an SLC magnet. Recognized as an
SLC magnet B-field by the name matching regular expression
(XCOR|YCOR|LGPS):.+//BDES. Step range
is defined by 3 floats: start-value, increment, end-value-min.
Additionally the user must be able to specify which trimming method (one of "trim" or "perturb") is to be used (which is used to set the "MAGFUNC" Aida parameter for SLC magnet control).
Action of stepping an SLC magnet is to use the MAGNETSET//BDES AIDA instance, giving the AIDA name supplied by the user, and affect trim operation by calling DaObject.setDaValue; see [AIDA-MAG].
.+. Step range is
defined by 3 floats: start-value, increment, end-value-min.
SLC Klystron PDES (desired phase) may be stepped. Defined
by:The name of an SLC Klystron with PDES secondary. Recognised by:
matching regexp KLYS:.*//PDES. Step
range:defined by 3 floats: start-value, increment,
end-value-min.
Step action: Use the AIDA SLC Klystron interface to change the PDES. That is, use AIDA name KLYSTRIM//PDES, with the first element of the passed DaValue being the name of the Klystron, as given by the user. See [AIDA-KLYS].
This subsection describes the variables whose value CP should be able to acquire.
The readable data of some device types, such as BPMs, TOROiods, Faraday cups some in the LCLS EPICS system, should be read "synchronously". That is, synchronized to a beam pulse, so that the values acquired for those devices together are known to be synchronized to that beam pule. Where one or more such devices are entered as Sampled Variables, Correlation plots must collect them together, and use the Beam Synchronous Acquisition system API to acquire them on the same beam pulse.
Defined by:The EPICS BSA name of each device to be acquired synchronously. The list of beam synchronous devices is given in [BSALIST.
Recognized by: TODO: See how to recognize items in this list and only these items.
Acquired by:See Matlab BSA API in lieu of source EPICS API for a description of the BSA user interface [BSA].
There must be a way to enter the number of pulses to average, which will pertain to all the sampled variable devices entered which are to be treated as beam synchronous.
Acquisition of buffered (nrpos > 1) BPM readings is [I think] a 'later' item. Comments are invited on the priority of this functionality.
.+:.+:.*^(//.*)$, that is, anything with two
colons and not ending "//something", since that would make it AIDA.
Acquired value: The PV understood value as a float. Note that for this "arbitrary" PV there is no secondary status acquisition. If particular PV's must be acquired with respect to a given status, then they must be handled individually (so, if you're reading this spec, and you know of a PV who's value CP should be able to acquire, and that PV has associated with it a way to determine the status of the acquisition, and it is not listed above, please tell us).
(a-z){4}(:|\s+)(a-z){2}(0-9){2}(:|\s+)[1-9][0-9]{2,3}(//\s+)(a-z){3,4},
that is, the familiar "primary micro unit secondary" quadruplet,
either space delimited or in the form
primary:micro:unit//secondary. If the space delimited form is given,
then it should be transformed to the AIDA instance//attribute syntax
before attempting to check the name in the aida names system.
Acquired value:The value acquired via AIDA (by DaReference for better efficiency that DaValue), as a float.
Value: Most varaibles likely to be acquired by CP are going to be real valued natively. It is sufficient to understand the value of each sampled variable as a float in the first instance. Array or "waveform" valued variables can be added later.
Error: The RMS error if the variable was "errorable" and N>1.
Status: A status value (whose definition is to be decided), for the read value of the variable at each acquisition cycle. This is likely to be an integer, or possibly a mask, by which CP understands the "reliability" of every acquired point of every variable.
Given a partial name (most significant characters) CP should provide intelligent name completion help. This should not swamp the user with all possible matches but rather search EPICS, AIDA, and its own directory service of special names, to find names which match the input so far, up to the next most significant separator (":" in the case of EPICS and AIDA names).
eg, if someone types in "LLRF ?" or "LLRF: ?" they should get simply "IN20 LI21 LI24 LI29" in reply, those tokens being the next most significant in the following name-part in the set of all possible names which match (informally) "LLRF:*:".
As well as the intuitive "auto" acquisition interface, in which correlation plots steps through the step variable values (either as fast as it can or according to the TIME range specification), it should also allow someone to manually specify when to take the next sample (by hitting a button).
Some variables, such as beam synchronous variables, should be read a number of times for each acquisition cycle. Their value will the be the mean value, plus an associated 1 standard deviation. Call such variables "errorable". For such variables CP must take a single parameter for the aquistion as a whole, n, being the number of times all such errorable devices are sampled in each acquisition cycle.
A user should be able to save and reload a CP configuration - that is an "experimental setup". This would functionally take two forms (though in practice these two would probably be managed by the same facility):
Both "1d" (and single step variable) and "2d" (two step variables) should be supported. In 2d acquisitions one step variable (the "primary" sv) is slow-moving and the other ("secondary" stv) is fast-moving. Thereby, the data collected for any single sampled variables is a matrix, and plotted as a mesh (or surface) in the coordinate system of the primary vs secondary vs sampled-variable.
This section deals with the requirements for charting the results of data acquisitions.
For 1D scans the following plots must be supported at the least:
The values of sampled variables for which sampling errors were acquired (for instance, when averaging BPMS values over a number of beam position samples), must be displayed with error bars.
At the minimum, fitting functionality should be to offer chi-sq linear and polynomial fits. If no errors, then unweighted fitting; if errors, then weighted fitting. ideally the Curve Fitting Toolbox from mathworks can be offered as the display and fitting engine.
It must be very easy to select which variables (both step and sampled) to be plotted on each axis. Note that it is not true that users always want to plot the independent variables on the x-axis and dependent variables always on the y-axis.
The default should be that the primary step variable is assigned to the x-axis, and the user selects which sampled variable to plot on the y-axis.
For 2D scans, at least the mesh grid of stv1 vs stv2 vs svn must be plottable. There must obviously be some way to nominate which sv to plot.
The Settle Time is a period of time which CP should wait between the time it has stepped a step variable to a new value in the acquisition cycle and the time that CP should begin collecting data for the sampled variables. This gives, for instance, magnets, or klystrons, time to settle and feedback loop to take effect before the acquisition is made. The Settle Time must be enterable by the user, in seconds, for each of the step variables individually (that is, there may be 2 settle times, one for the inner step variable, and one for the outer).
Magnets and klystrons, in particular, may cause beam disruption if they are moved to the starting value of the step range in "one go". Rather they should be ramped slowly to the point at which the acquisition should start, and, after the acquisition cycle has completed, ramped slowly back to their nominal value.
CP must be able to display all the data for an acquisition in tabular form. This functionality should also permit a user to "deselect" a given data point for a given variable, so that that point does not show up in successive plots.
CTRL-C. One must be able to interrupt an acquisition cycle, part way completed, and review the data collected so far as if the acquisition had completed normally.
CP must be useable both through its own GUI and as a data acquisition engine by other applications. The data acq API should not imply use of a specific GUI framework like Eclipse/SEAL - so it can be used by a simple batch Java app, or Swing/XAL.
ECLIPSE SEAL or XAL 1d/2-d and XIO combination. See Scope and Goals below.
Evaluation of XAL 1-d and 2-d applications for suitability as basis of Correlation Plots, either as i) Correlation Plots being implemented as modifications to XAL 1-d and 2-d applications, or ii) in part (code from XAL 1-d and 2-d scan being used in Correlation Plots), iii) XAL 1-d & 2-d apps implemented only as SEAL launchable items, with CP developed as a separate application.
CP will not include the ability to step or read SLC control system variables other than those listed above. Specifically, it will not include facilities for making beam synchronous acquisition from the SLC control system.
No need to write fit parameters to disk during data save and reload.
There is no requirement for spreadsheet-like arithmetic, as in the SLC CP, in the first release.
See Debbie Rogind, Mike Zelazny and Stephanie Allison re Beam Synchronous Acquisition.
Check requirements for step and sampled variables with Paul Emma, Pat Krecjik, Henrik Loos.
This section includes some issues which should be borne in mind during design.
Name Classification. Since CP will capable of acquisition of more than just EPICS PVs, it must include some facility for classification of names, so that it can distinguish sources. The order in which these are checked should be from specific variable type, to general.
1. Physicists will be used to mean any person performing a correlation experiment on the machine.