SLAC ESD Software Engineering Group
Stanford Linear Accelerator Center

SLC Buffered Data Provider Guide

SLAC Detailed
SLAC Computing
Software Home
Software Detailed

This page provides documentation for users and programmers of AIDA's SLC Buffered Data Service. This data service gives access to the so called "Buffered BPM Data" acquisition facilities of the SLC Control System, in the SLAC accelerator complex. Buffered BPM data, is the name given to the pulse-by-pulse data acquisition system, in which a user names the devices whose values they want to be acquired, for how many beam pulses, and the service then returns a table of results - the x and y position values and the Tmit, given in one row per device, per pulse.

See Also: Basic Users Guide to Aida, REF_AIDASHR; AIDA SLC Peer Programmers Guide

Users Guide

This section describes what an AIDA user should know about accessing SLC Buffered 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, in aida.lib.da which form Aida's programming interface. One can also use Aida through Matlab.


The SLC Buffered Acquisition Service (dpslcbuff) gets SLC congrol system pulse synchronized "Buffered Data", for the following device types: BPM x (mm), y (mm), tmit (num particles estimated); TORO tmit; KLYS and SBST phase; GAPM data, and status information for these, as specified in the user's query. The acquisition is subject to the so-called measurement definition "BPMD" given, over the given "NRPOS" parameter sequential pulses.

A table is returned. Since the kind of data one gets back from these device types is all a little different, some elements of the table of data you get back should be ignored.

BPMS = x, y, tmit in columns 3, 4 and 5 respectively
TORO = tmit in column 5
KLYS = phase in column 3
SBST = phase in column 3
GAPM = data, in column 3.
For all, name and pulse id are in column 1 and 2, and stat and goodmeas are in columns 6 and 7:

[fphysics@facet-srv01 ~ ]$ aidaget NDRFACET//BUFFACQ -DBPMD=57 -DNRPOS=5 -DDEV1=KLYS:LI03:31 \
-DDEV2=SBST:LI03:001 -DDEV3=BPMS:LI02:501 -DDEV4=TORO:LI20:2040

  TORO:LI20:2040  31330          0.0          0.0   3.39403981E9  1  1
  TORO:LI20:2040  31690          0.0          0.0   3.39403981E9  1  1
  TORO:LI20:2040  32050          0.0          0.0   3.73344358E9  1  1
  TORO:LI20:2040  32410          0.0          0.0    3.5071744E9  1  1
  TORO:LI20:2040  32770          0.0          0.0   3.62030899E9  1  1
   BPMS:LI02:501  31330     0.331939  -0.20821595    9.2273582E9  1  1
   BPMS:LI02:501  31690   0.32889742  -0.19808215    9.5858289E9  1  1
   BPMS:LI02:501  32050    0.2943182  -0.18990237  1.02538885E10  1  1
   BPMS:LI02:501  32410   0.43009153  -0.19211863    9.4554767E9  1  1
   BPMS:LI02:501  32770   0.33982033  -0.18054654    9.3577114E9  1  1
     SBST:LI03:1  31330    21.059832          0.0            0.0  1  0
     SBST:LI03:1  31690    20.382906          0.0            0.0  1  0
     SBST:LI03:1  32050    21.436647          0.0            0.0  1  0
     SBST:LI03:1  32410    20.955797          0.0            0.0  1  0
     SBST:LI03:1  32770    21.267794          0.0            0.0  1  0
    KLYS:LI03:31  31330    0.3280487          0.0            0.0  1  0
    KLYS:LI03:31  31690  -0.44467163          0.0            0.0  1  0
    KLYS:LI03:31  32050    0.4645996          0.0            0.0  1  0
    KLYS:LI03:31  32410   0.10968016          0.0            0.0  1  0
    KLYS:LI03:31  32770   0.51013184          0.0            0.0  1  0
Status and limitations

Presently the service acquires only named devices in the query, each given by a "DEVn" or "BPMn" (it doesn't matter which you use) parameter; there is no support for simply getting all the BPMs in the DGRP implied by the AIDA entity - such as all those in NDRFACET.

Plan No active plans for extension, but could add the ability to acquire all devices in the DGRP implied by the AIDA entity name.
Names AIDA entities for making buffered acquisitions, are composed of DGRP name, with attribute == "BUFFACQ" (see INSTANCES and ATTRIBUTES below). So, see aidalist % BUFFACQ for an up-to-date list. The following names exist at the time of writing:
       $ aidalist % BUFFACQ

       E163BMLN                                           BUFFACQ
       ELECEP01                                           BUFFACQ
       INJ_ELEC                                           BUFFACQ
       INJ_POSI                                           BUFFACQ
       NDRFACET                                           BUFFACQ
       SCAVPOSI                                           BUFFACQ
       TAXXALL                                            BUFFACQ
       SDRFACET                                           BUFFACQ


Schematic Schematically, the syntax of an AIDA Buffered acquisition is an AIDA entity name (required), plus parameters giving a BPMD number (required), number of pulses (1 pulse is the default), and device names given in unique parameter names. The parameter names must begin "DEV" or "BPM" and at least 1 must be given.
      aidaget <DGRP-name>//BUFFACQ BPMD=n [NRPOS=m] {(BPM<i>|DEV<i>)=<device-name>}+1
An example using aidaget at the command line:
[flora03]:u/cd/greg> aidaget NDRFACET//BUFFACQ -DBPMD=57 -DNRPOS=10 -DDEV1=GAPM:LI18:930 -DDEV2=BPMS:LI11:501 
  BPMS:LI11:501  51778  0.14952832    0.04818424  1.84745226E10   1  1
  BPMS:LI11:501  51850  0.15105376  -0.007751522   1.8179285E10   1  1
  BPMS:LI11:501  51886  0.15066777   0.026444921  1.82530949E10   1  1
            . . . <17 rows snipped>
Java Java example (see $CD_SOFT/ref/package/aida/test/java/ for more examples. See in particular the method printffDaValue( DaValue v ) for how to extract each of the result vectors from the DaValue object returned (v in the example below):
	da = new DaObject();
	String query  = "NDRFACET//BUFFACQ";
	da.setParam("BPMD","57");             /* BPMD is a required parameter */
	da.setParam("NRPOS","180");           /* Number of pulses */ 
	da.setParam("BPM1","BPMS:LI11:501");  /* 3 bpms to acquire given */
	DaValue v = da.getDaValue(query);     /* Acquire Buffered data */
	System.out.println( v.toString() );   /* Print the results */

Having set up the DaObject (da in this example), you can execute da.getDaValue(query) repeatedly to make the same acquisition. Reset the da object using da.reset().

	% The following is matlab code to use AIDA to acquire 2 bpms, 
        % for the same 10 pulses, on measurement definition (BPMD) 57.

        % Set up the acquisition

	% Do the acquisition
	buffdata = d.getDaValue('NDRFACET//BUFFACQ');  

	% Extract the results from the returned buffdata DaValue java vector.
	pts = buffdata.get(0).size();
	StringArray = javaArray('java.lang.String',pts);
	namesStrings = char(buffdata.get(0).toArray(StringArray));
	% Then each bpm name is a 2 char matrix - namesString(1,:) is the whole name of the 1st BPM.
	pulses=[pulses; cell2mat(cell(buffdata.get(1).toArray()))]
	xs=[xs; cell2mat(cell(buffdata.get(2).toArray()))]  
	ys=[ys; cell2mat(cell(buffdata.get(3).toArray()))]
	tmits=[tmits; cell2mat(cell(buffdata.get(4).toArray()))]
	stats=[stats; cell2mat(cell(buffdata.get(5).toArray()))]
	goodmeas=[goodmeas; cell2mat(cell(buffdata.get(6).toArray()))]


AIDA Entities are the names, or queries, known to AIDA. An entity is composed of an instance part, followed by "//", followed by the attribute part. The instance should describe an object, the attribute should describe a property of that object. This table formally describes the entities associated with the SLC Buffered Acquisition service, and the data that can be acquired with them.

Instance Type Description
Buffered BPM Data Syntax <dgrp-mnemonic-name>//BUFFACQ
See aidalist % BUFFACQ for a complete list.
Attribute Description
BUFFACQ Makes a buffered acq reading of each given device, in the dgrp specified in the "instance" part of the query, under the BPM Measurement Definition specified by the BPMD (required) parameter, at each beam crossing for the number of pulses given by NRPOS.
Methods Name* Returns
getDaValue(q) Returns a DaValue containing a heterogenous vector of 7 homogenous congruent vectors. Ie, a table. Below is definition of the columns for a BPM device. See the summary above for the column interpretations for KLYS, SBST and TORO.
  • name of each BPM (string)
  • pulse id (integer)
  • x offsets (floating pt mm)
  • y offsets (floating pt mm)
  • tmits (floating pt coulomb)
  • STATs (32 bit field)
  • goodmeas (boolean 1 for good, or 0 for bad)
  • Parameters Name


    Syntax Semantics


    Integer Bpm Measurement Definition number. This specifies the timing profile of the acquisition. Each BPMD corresponds to exactly one DGRP. To find likely BPMDs, go to the BPM Device panel of a SCP and hit the 'HELP' button, then select the button corresponding to the bpm orbit you would have wanted to see. The button name for that acquisition, as displayed in the help, is the BPMD for the selected orbit. Use that number for this parameter. Eg BPMD=57 is the primary BPMD for the DGRP NDRFACET, and so will be the main one used for FACET.
    NRPOS opt 1=<n<=2800. Default is 1. In theory, this parameter can range up to 2800, but some things must be borne in mind. Firstly, roughly speaking the minimum time it could take a buffered acquisition to complete, is NRPOS/machine-rate-in-Hz. But, the SCP in fact adds time to this theroetical minimum heuristically, to give the micros time to prep the acquisition. Secondly, AIDA's network timeout ranges between 60 and 90 seconds depending on platform, so if your acquisition takes too long, the client will timeout. So, in practice, limit your NRPOS to numbers that will result in relatively short acquistions, plan for about 30 seconds max.
    BPMi or DEVi req BPM, TORO, GAPM, KLYS or SBST device name Parameters whose name begin "BPM" or "DEV" are used to pass the names of the devices from which a user would like the Buffered service to acquire data. The parameter name must begin BPM or DEV and be followed by an integer, and be unique in the parameter list used. See the examples above.

    Programmers Guide

    The server side code of the AIDA SLC Buff service is mainly in DPSLCBUFFI_IMPL.JAVA and DPSLCBUFF_JNI_HELPER.C. See also the files named beginning DPSCLCBUFF* in VMS REF_AIDASHR.

    The SLC Buff Data Provider is a provider in the AIDA SLC Peer (along with the SLC DB Data Provider, the SLC History Data Provider, the SLC Model Data provider, the SLC Magnet Data Provider, the SLC Multiknob Data Provider, the SLC Master Oscillator Data Provider, and the SLC Klystron Data Provider). Development of all these data providers is described in a Programmers Guide here.

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

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

    Author:  Greg White 23-May-2011