11/7/99
This document summarizes the software tools developed for physicists working on the ATF. A more general overview is available here(*), and should be read first.
The following comments and tools are largely the results of Nan Phinney (nan@slac.stanford.edu) and myself (Keith Jobe, rkj@slac.stanford.edu) while we visited with Marc Ross and Doug McCormick (all from SLAC) in 2/97. There are a few more recent additions:
History Buffer (Janice Nelson and Scott Anderson) and general routines for modelling with MATLAB (Mark Woodley).
As part of the SLAC contribution to the Linear Collider Development, and most specifically, the Accelerator Test Facility, we offer these contributions. Additional contributions are welcome, and any errors should be brought to my attention (rkj@slac.stanford.edu).
Vista control should be run from one of the VISTA operation accounts, ATFOP2 being an example. Why is not clear, but there seems to be some missing privilege from other accounts. Additionally, since the software is run from an account in [ATFSYS,*], your personal account must also be in that group. (this is required if you want to save any data from your programs run from [ATFSYS,ATFOP2]).
My login file sets up a number of parameters, and I highly recommend that you run it as part (or all) of your initialization. It can be executed as $ @[RKJ]LOGIN.COM. This does the following:
The ATF standard link for standalone programs is VMAKE2, which does not use the additional library of the VATF later, nor is the /DEBUG qualifier used. We use test links, examples of which are in [rkj.atf]*.com and in toolbox:[kek]*.com. You may need to link your code with a copy of the VMAKE2 command with the link/map qualifier, and look at the map to see which libraries are actually used. Do not change the library order, since several routines are in multiple libraries, and some routines (magnet trimming) are completely different if linked for the linac versus for the ring (same routine names, however).
The Matlab links define the *same* set of logicals that the vmake does, then links against the [rkj.atf]testlib/lib as well, which seems to work. You may need to recompile the routines by entering @c while in the directory.
The ATF implementation of the VISTA control system has an independent channel per device per entry, (with some exceptions). Most database values are updated by a rapidly cycling background process rather than by channel-specific driver code. To be very conservative, you must force an update of a channel prior to extracting data from the database. (The VISTA "standard model" would have the update occur automatically as data is extracted from the database.) The codes (below) can be used to explicitly update the channel values prior to extraction. Updating is required if you want to step a magnet through many values and read the results without introducing a several second pause at each stem.
In VISTA, a channel name is a string which is unique within the database, (and probably within all the ATF databases). Channel names are simply strings like ZV25R:CURRENT.DAC.WRITE, and this device's database name is DB_STR. The complete description is DB_STR::ZV25R:CURRENT.DAC.WRITE (no spaces, case insensitive).
The database names can be found by SHO LOG D*. The database names all end with the extension .VDB. An ASCII source module exists for each database with the same name, extension .ADB. (This is what I searched for to get DB_STR:: in the above example). Database names are a bit hard to guess, which is why we wrote VATF_DATABASE_NAME, which will return it for you. Most of our routines will call this routine for you.
The words CHANNEL NAME may mean:
The use is dependent on the context. Generally, the "names" used in the routines described below are the individual device names (e.g.: ZV25R), while the channel refers to the device's channel (called secondary in many databases) (e.g.: CURRENT.MONITOR).
Channels also have a group of additional attributes, such as labels, params, hparams, etc. Specialized access routines must be used to get these.
Of special note, the BPM data structure (a 10xn version) similar to what is returned by VATF_GET_BPM is not stored by device, but the entire ring's data is in one channel named COD.DATA. This channel contains the "most recent" data, which may be quite old.
The VATF_RGET (and sibling routines) provide a lower level data access tool for the purist (these are found in ATF$LIBRARY:VATF_LIB.FOR).
The following routines allow database access without specifying the database names. Additionally, many routines check magnets/bpms or return device names or twiss parameters not directly available from the database. Routines are currently stored in atfaxp::user$disk1:[rkj.atf]*.for, and archived copies are web viewable.
logical*4 iarg_pres (arg_index, arglist_p)
Allows the use of conditional arguments.
Integer*4 function CHTRUNB(string)
Returns string length. Use as: string = name(:chtrunb(name)) // "more characters"
Integer Function VATF_DATABASE_NAME(DEVICE_NAME, DATABASE_NAME, DB_NAMELEN)
Returns the VISTA database name and its length
Integer Function VATF_GET_NAMES(REGION, DEVICE, NAMELIST_LEN, NAME_COUNT, NAMELIST, POSN_LIST)
Returns the list of specified device names for the region and optionally their S positions. Wild cards and SLC device syntax supported.
Integer Function VATF_GET_TWISS(REGION, DEVICE, LIST_LEN, LIST_COUNT, TWISS_LIST, POSN_LIST)
Returns the TWISS parameters for the specified region and devices and optionally their S positions. A specific filename may replace Region.
Integer Function VATF_LISTGET(REGION, DEVICE, CHANNEL_NAME, LIST_LEN, LIST_COUNT, DATA_LIST)
Returns the specified channel data for all the device(s) as indicated. Calls Vatf_Get_Names to expand device specification.
Integer Function VATF_MAG_CHECK(REGION)
Forces a magnet device read. Must be used prior to depending on the value of the :current.monitor or :voltage.monitor channels.
Integer Function VATF_MAG_TRIM(DEVICE_COUNT, DEVICE_LIST, K_FLAG, K_VALUES)
Forces a magnet trim using the indicated values as currents or K_values.
The Alpha fortran compiler forces a much stricter compliance to the standard than the Vax version. Most specifically:
will not always do as expected. Use if - then - elseif structure to be sure.
The following routines are available, which largely mimic the fortran tools available above. They are stored in atfaxp::toolbox:[kek]*, and archived copies are web viewable. The Matlab Help <functionname> provides more complete documentation.
[value,status]=vatf_bpm_get(channel_name)
[names,status]=vatf_get_names(region, device)
[value,status]=vatf_get_twiss(channel_name)
[data, status]=vatf_listget(region, device, channel)
[status]=vatf_mag_check(region)
[status]=vatf_mag_trim(device_list, kflag, k_values)
These call the Fortran routines described above
[value, status]=vatf_get(channel)
This will try to figure out the database name and returns the string, real, integer, scalar or array as indicated by the internal typing of the indicated channel name.
usr_pause(seconds)
Pauses indicated number of seconds (Matlab pause waits 0.00 seconds for pauses less than about 1 second).
History Buffer (Janice Nelson and Scott Anderson)
A history buffer acquisition and display system. There is a users guide, that lists everything you need to start a nominal acquisition file and examine its results and a programmers guide made up of four files: an introduction, an acquisition control file (called 'slave'), a sample BPM file and some plot generation instructions.
MATLAB Modelling Instructions (Mark Woodley)
These are MS Word files.
Links to: The KEK ATF home page, the SLAC ATF page, KEK Institutional Home Page, SLAC Accelerator Department, and the SLAC Institutional Home Page.
* These links require Acrobat Reader.
This page is maintained by Keith Jobe