SLAC CD Software Engineering
Stanford Linear Accelerator Center
AIDA

LCLS Model Data Provider Guide

SLAC Detailed
SLAC Computing
Software Home
Software Detailed
AIDA

This page provides documentation for users and programmers of AIDA's LCLS Model Data Provider.

See Also: Basic Users Guide to Aida, Dp Model Source;, DpModelI_impl class java doc


Users Guide

This section describes what an AIDA user should know about accessing the LCLS Model Data through AIDA. For general information on using AIDA see Basic Users Guide to Aida, and the Aida javadoc, in particular the classes DaObject and DaReference (and DaReference's parent _DaReference) in aida.lib.da which form Aida's programming interface. One can also use Matlab.

Table 1: Summary of AIDA Data Provider for LCLS Model Data

SUMMARY
Acquires Twiss and Rmatrix parameters of devices modelled in the LCLS Online modelling system. Presently, the LCLS online modelling system is done by XAL.
Status and limitations

Recently added GOLD support (see RUN argument). Presently, only acquires the COMPUTED or DESIGN model, no MEASURED. There is a small set of devices which are not modelled, see below.

Plan
See Also Tables of most recent twiss and most recent Rmat model data uploaded

EXAMPLES
Schematic Matlab example of getting R matrix of the MIDdle of QUAD. For more examples see xalModelDemo.m:

BPMS:IN20:781//twiss

BPMS:IN20:781//twiss RUN=GOLD

QUAD:IN20:361//R MODE=53 POS=BEG

ACCL:IN20:300//R POS=MID MODE=5 TYPE=DESIGN

QUAD:IN20:361//R B=WIRE:IN20:531

Java $CD_SOFT/ref/package/aida/test/java/DpModelTests.java
Matlab $CD_SOFT/ref/package/aida/test/matlab/xalModelDemo.m

INSTANCES and ATTRIBUTES
Instance Type Description
XAL Modelled Device Syntax <prim>:<area>:<unit>//{twiss|R}. XAL model of SLC CS devices is usually by name <area>:<prim>:<unit>. A list of name translations is presently maintained by Henrik here.
Examples

BPMS:IN20:781//twiss

QUAD:IN20:361//R

Attributes
Attribute Description
twiss The Courant-Snyder parameters of given modelled "device" (d)
Methods Name* Returns
getDaValue(q) DaValue containing an array of 15 floats: Kinetic Energy (GeV), psix, betax (m), alphax , etax (m), etax', psiy, betay (m), alphay, etay (m), etay', Z (m), Effective Length (m), Slice Effective Length (m), Ordinal position in beamline (as a float)
geta(d,DaValue.Types.FLOATA) array of 11 Float, see getDaValue
geta(d,DaValue.Types.DOUBLEA) array of 11 Double, see getDaValue
Arguments Name

Req/
Opt

Syntax Semantics
RUN

opt

"LATEST" (or "0"), "GOLD" (or "1"), or an integer corresponding to a Run Id. Egs RUN="LATEST", RUN=2208 The Model Run for which to get data. The default is the GOLD model run, subject also to the TYPE (see below). If given, RUN must be "GOLD" or "LATEST" or a valid Run Id, as can be checked in the Oracle XAL Model report. A more precise articulation of the behavior for each of these 3 possible kinds of RUN, is given below.
MODE opt An integer, corresponding to a machine model mode. Eg MODE=51 MODE identifies the model of a given beamline run under given initial conditions. At the time of writing, there are 4 possible MODES: 5 (Full Machine), 51 (Cathode to Gun Spectrometer), 52 (Cathode to 135 MeV Spectrometer), 53 (Cathode to 52SL2). If MODE is given, the model of the device requested will be taken from that MODE. If MODE is not given, the model returned will be from the MODE 5 model of the device if it is MODE 5, and simply the model indicated by the RUN parameter (GOLD or LATEST) otherwise. Put simply, the default is MODE 5 for devices which are in MODE 5.
TYPE opt EXTANT or DESIGN The type of desired model: The EXTANT (DATABASE is a synonym) is a model computed from machine PVs and then uploaded. DESIGN is model from constants in the model. The default is EXTANT.
POS opt BEG, MID, or END The position within a sliced device for which the model value should be returned: BEG (BEGINNING is a synonym), MID (MIDDLE is a synonym), or END. The default is END (for compatibility with SLC modelling).
R The 6x6 transfer matrix of a named device (d), returned as 1D array. If the B argument is specified, AIDA gets the transfer R-matrix from the A device d, to the B device specified by the B argument.
Methods Name* Returns
geta(d,DaValue.Types.FLOATA) array of 36 Float, 1st 6 are 1st row of R-matrix, 2nd 6 are 2nd row, and so on.
geta(d,DaValue.Types.DOUBLEA) array of 36 Double, 1st 6 are 1st row of R-matrix, 2nd 6 are 2nd row, and so on.
getDaValue(d) DaValue containing an array of 36 float. Extract array with methods of java.util.Vector such as get() (which DaValue extends).
Arguments Name

Req/
Opt

Syntax Semantics
RUN (as above)

opt

"LATEST" (or "0"), "GOLD" (or "1"), or an integer corresponding to a Run Id. Egs RUN="LATEST", RUN=2208 The Model Run for which to get data. The default is the GOLD model run, subject also to the TYPE (see below). If given, RUN must be "GOLD" or "LATEST" or a valid Run Id, as can be checked in the Oracle XAL Model report. A more precise articulation of the behavior for each of these 3 possible kinds of RUN, is given below.
MODE (as above) opt An integer, corresponding to a machine model mode As described above for twiss. eg MODE=51
TYPE (as above) opt EXTANT or DESIGN The type of desired model: The EXTANT (DATABASE is a synonym) is a model computed from machine PVs and then uploaded. DESIGN is model from constants in the model. The default is EXTANT.
POS (as above) opt BEG, MID, or END The position within a sliced device for which the model value should be returned: BEG (BEGINNING is a synonym), MID (MIDDLE is a synonym), or END. The default is END (for compatibility with SLC modelling).
B opt <prim>:<area>:<unit> If specified, the specification of the second device for the transfer R-matrix. For sliced devices the position within each may be given using POS and POSB arguments also. The defaults are POS=END and POSB=BEG.
POSB opt BEG, MID, or END When using argument B, POSB allows one to specify the position within B to which the Rmat A to B value should be returned, so it's only pertinent when B is a sliced device. Permitted values are as POS, BEG (BEGINNING is a synonym), MID (MIDDLE is a synonym), or END. The default is BEG (unlike default for POS).

* See DaObject and DaReference (and DaReference's parent _DaReference) in aida.lib.da for full API and method signatures.


Devices not presently modelled

BEND:IN20:231 is "BXG", the bend that takes the 6 MeV beam to the Gun Spectrometer. The Gun Spectrometer sequence ("BXG TO GUN SPECT DUMP") has not been added to XAL yet, so no XML upolad contains it. Coming soon ...

LI30:QUAD:615 and LI30:QUAD:715 (each a triplet of "wraparound" quads on a single power supply) are not going to be used for LCLS operations. Because of that and the fact that they're tricky to deal with in XAL, we've changed them from QUADs to MARKers in the xdxf-file. I'm not sure if they appear in the XML upload file, or if, being MARKers, they have database id's. If they were and they did, you'd get three rows from the model for each.

QUAD:IN20:121 ("CQ01") and QUAD:IN20:122 ("SQ01") are quadrupole and skew quadrupole windings (respectively) incorporated (along with "XC00" and "YC00" dipole windings) into the "SOL1" solenoid very near the gun. They are zeor-length devices in the MAD deck and are tricky to deal with in XAL, so they are not in the xdxf-file, nor will they be as far as I know. You could get the model for these guys from, for instance, XCOR:IN20:121 or YCOR:IN20:121 .

SOLN:IN20:111 is the gun "bucking" solenoid ... not in the XAL model. You could get the model for it from "DBMARK80" (VX00:MARK:80).

SOLN:IN20:311 is "SOL2", a solenoid that's wrapped around the L0A structure. It has zero-length in MAD, and so is tricky to handle in XAL, and so has been left out of the xdxf-file. No model for this guy explicitly, but if you really wanted it you could get it from "L0A___2" exit.

MODE and GOLD Parameters in Detail

Whenever AIDA is asked for the model of a specific device (like BPMS:IN20:235//twiss it implements a search for an appropriate online model upload from which to get the model for the device, subject to the RUN, MODE and TYPE paramters given. This section explains the search algorithm in detail.

(In all of the search criteria below, it's assumed that the type, "Design" or "Extant", is also a conjunction in the search criteria).

If only a single device's model (A) is required

  1. If a run ID is given (RUN>1), then look for the device (A) in the model identified by the given Run ID. If A is not found in the given Run ID model, return an error "device not found in run id." [This is unchanged from before GOLD was added]
  2. If Run ID = 1 (GOLD) is given;
    1. If MODE is given, then return the model parameters from the gold model of the given mode. If A is not in the gold model of the given mode, return an error (do not search further).
    2. If MODE is not given, then;
      1. If A is in the MODE = 5 gold model, then return the params of A from that model.
      2. If A is NOT in the MODE = 5 gold model, then return params of A from the gold model with the largest Run ID (that is, chronologically latest uploaded) that contains A.
  3. If Run ID = 0 (LATEST) - the default;
    1. If MODE is given, then return the model params of A from the model with the largest run ID of the given MODE that contains A. If A is not any model matching the given MODE, return an error like "device not found in MODE".
    2. If MODE is NOT given, then;
      1. If A is in the MODE = 5 model, then return the params of A from model largest Run ID whose MODE == 5.
      2. If A is NOT in a MODE = 5 model, then return the params of A from the model with the largest Run-ID containing A. This is the present behavior.

If the model Rmat A to B is required

(In all of the search criteria below, it's assumed that the type, "Design" or "Extant", is also a conjunction in the search criteria).

  1. If a (>1) run ID is given, then look for A and B in the model identified by that Run ID. If A or B is not found in the model with the given Run ID, return an error like "device not found in run id."
  2. If RUN = "GOLD" is given;
    1. If MODE is given, then return the model parameters computed from A and B Rmats from the gold model of the given mode. If A or B is not in the gold model of the given mode, return an error (do not search further).
    2. If MODE is not given,
      1. If A & B are in the gold MODE = 5 model, then return the params computed from A and B from that model.
      2. If A or B is not in the gold MODE 5 model, then return the params computed form the gold model with largest run id (chronologically most recent) that contains both A and B.
  3. If Run ID = "LATEST" - the default if RUN param is not specified
    1. If MODE is given, then return the model params of A and B from the model with the largest run-ID that matches the given MODE, and contains both A and B. If A or B is not in the model with the largest run ID matching the given MODE, return an error like "device not found in MODE."
    2. MODE is NOT given, then
      1. If A & B are in any MODE = 5 model, then attempt to return the Rmat computed from A and B of the model with the largest Run ID, whose MODE == 5, that contains both. However, if the largest Run-ID model of MODE = 5 that contains the downstream device, does not in fact also contain the upstream device (which of course it should), then AIDA returns an error.
      2. If A or B is NOT in a MODE = 5 model, then return the Rmat computed from A and B from the model with the largest Run ID that contains both A and B.

[SLAC ESD Software Engineering Group][ SLAC Home Page]

Author:  Greg White 09-Sep-2008, 12-Feb-2009, Added MODE, and limitations of XAl Modelling from Mark Woodley