[Pvmanager-devel] Partital Working Draft, Epics Scientific Service Interfaces

[White, G. <gr...@sl...>]

[Partial working draft, July 28 2010]

Colleagues, 

Please find below a partial working draft of a minimum set of 4 scientific service interfaces for accelerator applications;
  A) Modelling
  B) BPM Orbit
  C) Magnet readback/control
  D) Archive history. 

This documents the discussion in our meeting Tuesday 20th July 2010. As such it only includes the basic data *returned* by a minimum set of scientific services. 

A following draft will include the parameters required as *inputs*, a more complete API for each service, and document the association between data services and the applications which use them.

These interfaces are based on those in existence in AIDA [1], where further clarification can be sought.


A) Modelling
============

The following 3 output data types for modelling, are each parameterized by an identifier which specifies the modelling run that produced the model. The identifier most used the "GOLD", meaning the modelling run identified by the control room operations, as most descriptive of the present operating conditions, or which describes the objective operational conditions. Different labs may have different names for this "best" short term model.

Required Data:

1. The 1st order transfer matrix. 
---------------------------------
This is the full plane coupled (ie the 6x6) matrix, from the beamline beginning to each lattice element, given as a table. Ie 36 values for each row.

1 row = 1 lattice element. That is, one beamline device may well correspond to more than one lattice element eg, quads may well be split into 2 lattice elements, other magnets may be >2 slices; one klystron may be represented as a sequence of cavities, etc. Elements given in phase advance beamline order from the beginning of the beamline. 

If the beamline is a transport line, then the 6x6 should be interpreted as a linear transport matrix (i.e. an R aka T matrix). If the beamline is a ring, then the 6x6 should be interpreted as a closed orbit transfer matrix (i.e. a C matrix).

Use cases: Basis for the system matrix of orbit correction software. Also can be used for client side caching the whole model, making repeated model operations faster than using the element by element interface (3 below).

Multiplicity: 1 such table for each modelling run of each beamline.

Columns:

i)    Ordinal position of the lattice slice described by this row (as defined by phase advance)
ii)   EPICS device name, if there is one, of the lattice slice described by this row
iii)  The MAD or otherwise offline modelling code name, if different to ii.
iv)   S position of the lattice slice described by this row
v)    Where in the lattice element the row pertains to, "BEGIN|MID|END."
      + Default (ie for thin elements) should be END. 
      + Thick elements, e.g. quadrupoles, will require >1 row, since the transfer matrix will be required at least at their BEGINning, MIDdle, and END. MIDdle means the end of the median lattice slice of the element.
      + Klystrons with many cavities will need a convention. I propose this convention, whose advantage is that it limits entries for klystrons to at most 3 rows:
         - 1st row describes the entry of the 1st cavity, labeled BEG.
         - If == 1 cavity then 
             2nd row describes the exit plan of the cavity, labelled END.
           else if == 2 cavities then 
             2nd row describes the end of the 1st cavity, labelled MID.
             3rd row described the end of the 2nd cavity, labelled END.
           else if > 2 cavities then
             2nd row is for the end of the medial cavity, labelled MID
             3rd row is the end of the last cavity, labelled END.

      + Another perfectly reasonable convention would be that 
        all cavities are included;
           1st row = entry to first cavity
           2nd and all subsequent rows describe the exit of each cavity.

vi) The 36 elements of the 6x6 transfer matrix (R or C depending on whether linac or circular).

[Example in next draft.]


2. The basic Twiss / aka Courant Snyder parameters. 
--------------------------------------------------
Given as a table, for each lattice element, in phase advance beamline order from the beginning of the beamline. 

Use cases: control room lattice diagnostics. 

Multiplicity: 1 such table for each modelling run of each beamline.

Columns:

i) - v) as above for the transfer matrix.

v) The Twiss parms themselves: Kinetic Energy (GeV), psi x, beta x (m), alpha x (rad), eta x (m), eta x' (rad), psi y, beta y (m), alpha y (rad), eta y (m), eta y' (rad).

vi) Slice Effective Length (m). Include this since only the model really knows this, and 
not worth creating a different interface for it.

[Example in next draft]


3. The transfer matrix (6x6) of a single given lattice element. 
---------------------------------------------------------------
Given as the 36 floats of the 6x6 transfer matrix of the given lattice element, in row major order.

Use cases: This is the basic interface for building bump software, feedbacks etc. Eg this is the way you get the "R12" of a device.

Multiplicity: 1 such 6x6 table for each lattice element in each beamline, computed by a model run. So, for instance, there would be 1 for a BPM; but there would be 3 for a single quad split into 2 slices (the entry of the first slice, the exit of the first slice, and the exit of the second slice). 

If no "B" parameter is given, then the transfer matrix returned should be the R matrix from the the beamline start to the given lattice element (or in case of circular machine, the C matrix from injection to given element).

If a B parameter is given, the transfer matrix returned should be the R matrix from the given device to B. 


B. BPM Orbit
============

Given as a table of the X and Y offsets from the calibrated center of each beam monitor (BPMs and Toroids). Each value should be accompanied by an RMS, giving the measured error. Valued 0 if only 1 reading was made.

Note, this interface is independent of the question of whether all BPM readings were taken on the same pulse, or whether the RMS is over consecutive pulses/turns of ring etc. This same output interface can be used.

Use cases: BPM orbit plots, orbit fitting, orbit correction.

Columns:

[columns i - iv as A.1 above]
i)    Ordinal position of the lattice slice described by this row (as defined by phase advance)
ii)   EPICS device name, if there is one, of the lattice slice described by this row
iii)  The MAD or otherwise offline modelling code name, if different to ii.
iv)   S position (m) of the lattice slice described by this row
v)    X offset (mm) (null if Y only bpm)
vi)   Y offset (mm) (null if x only bpm)
vii)  TMIT (coulombs) 
viii) X rms (null if Y only bpm)
ix)   Y rms (null if x only bpm)
x)    BPM status (codified cause of most important severity or alarm). 

Note that a client might well merge the above table with a table of all beamline devices by S (not included here), so that it can display an orbit plot that includes beamline obstructions, stoppers etc.

For AIDA example see [2].


C. Magnet readback/control
==========================

Given as a table of magnet B fields [I'm not sure we can push B on places that operate in KG/m etc. Also not sure all places integrate field strength of different magnet types equally.]  

Use case: operational diagnostics. Orbit correction. 

[Columns i - iv as A.1 above]
i)    Ordinal position of the magnet by this row (as defined by phase advance)
ii)   EPICS device name, if there is one, of the magnet. 
iii)  The MAD or otherwise offline modelling code name, if different to ii.
iv)   S position of the magnet
v)    B field
      
B field may be the B "desired" (the control setpoint), B "actual", or B "configured" (the last loaded configuration value, eg SCORE CON), depending on an input parameter, eg (field=DES or field=CON). 

The above data type may be used for magnet readback or control.


D. Archive/History
==================

The archived data points for a given device.

Given as a table of timestamped values, containing a rectangular matrix of 5 arrays: 

Columns:
i)   the values (double)
ii)  the times as strings "dd-mmm-yyyy hh:mm:ss" (matlab dateform '0', suitable for datenum); 
iii) repeat count; 
iv)  the times as numeric timestamps in UNIX system time format
v)   the pulse id; 
vi)  the count (1 for a scalar and greater than 1 for a waveform-- count may be used to index into the values array for waveforms to extract the waveform values for each sample
vii) a flag indicating whether the times represent Daylight Savings Time. 

For example see [3].


E. Klystron
===========
[To follow in next draft - for now see example in http://www.slac.stanford.edu/grp/cd/soft/aida/slcKlysDpGuide.html]


Assumptions and Definitions.
============================

At each facility a naming convention will map EPICS PVs to beamline devices (say the first 3 fields of the EPICS PV name identify the device), and some other field identifies a property of the device. Eg In PV name "XCOR:LI21:245:BDES," XCOR:LI21:245 identifies a device, and BDES identifies a property.

Element. A modelled element in the MAD sense. A element may correspond to an EPICS device, but not necessarily. Eg Mad Element "X245" may be EPICS device "XCOR:LI21:245". However, there may well be elements that have no corresponding EPICS device, eg "MARK4" might be a modelled marker point, for which no EPICS PV is needed. *So, don't expect all rows in a table of all the R-matrices of an accelerator to map to a PV, and for those that do, don't expect only 1 row to match a single PV.  

References
==========
[1] Accelerator Independent Data Access (AIDA) [1], http://www.slac.stanford.edu/grp/cd/soft/aida/. See in particular links under the section "Individual Service Data Users Guides."

[2] AIDA SLC Bpm Data Provider Guide http://www.slac.stanford.edu/grp/cd/soft/aida/slcBpmDpGuide.html

[3] AIDA EPICS Channel Archiver Data Provider Guide http://www.slac.stanford.edu/grp/cd/soft/aida/epicsChannelArchiverDpGuide.html