FACET Developers Guide - this document is under construction!

Overview

The FACET facility is controlled by a combination of the VMS-based SCP control system, and EPICS. EPICS controls are centered in the new experimental region in LI20, and include these subsystems: profile monitor, collimator/motion, bunch length monitor, wire scanner and event. Magnet, bpm and toroid subsystems in the new LI20 region are controlled by the SCP. A single EPICS controlled profile monitor will eventually reside in LI10.
All other FACET controls are SCP-based. 

This document is a basic overview FACET control system physics development guide.

For complete information, detailed instructions and examples please refer to the "MATLAB Programmer's Guide for FACET physicists" programming_guide_matlab_facet.pdf:

• document is attached to this page
• also in /usr/local/facet/tools/matlab/programming_guide_matlab_facet.pdf

I. Logging into the FACET control system network

The FACET EPICS control system resides on its own MCC-based private network, parallel to and separate from the LCLS network.  The FACET server that will be used for physics work is:

• facet-srv01

To log into the FACET network from a linux terminal session:

• Account setup:
  • Your afs unix account must be added to the facet group.  Contact Ken Brobeck (x2558).
  • You will be logging into the facet network as the shared fphysics account. For personal matlab settings, Mike Zelazny (x3673) will set you up with an optional user-specific directory and environment under fphysics.

• Login:
  • Bring up a linux terminal window:
    • from an MCC OPI or linux box click the terminal icon on the desktop
    • from Windows use Secure CRT or XWin-32
  • Log into mcclogin with your afs account:
    ssh mcclogin
  • From mcclogin, log into facet-srv01 as the fphysics account
    ssh fphysics@facet-srv01
  • When prompted, enter your user number assigned by Mike (or 0 if you don't have one.)
  • With a personal setup by Mike, you are now in /home/fphysics/userid (e.g. /home/fphysics/fred)
  • With the generic login setup, you are now in /home/fphysics

an fyi: the FACET and LCLS directory structures have a parallel naming convention:

• LCLS top-level directory: /usr/local/lcls
• FACET top-level directory: /usr/local/facet

II. FACET edm displays: facethome

facethome is the toplevel edm display for the FACET accelerator. It is similar to lclshome, a grid showing areas and subsystems, with clickability into the various displays.

To launch facethome from a terminal session on the facet network:

• log into facet-srv01 (see above)
• enter
  facethome &
  at the command prompt

To launch facethome from a an MCC opi:

• click the facethome icon on the display

III. SCP

To run a SCP from a terminal session window:

• you will need a VMS account and userid on MCC. To get one, please contact Ken Brobeck (x2558)
• from your afs account on mcclogin, log into mcc and run the scp:
  ssh mcc
  scp xt userid (e.g. scp xt fred)

To run a SCP from facethome:

• click the "SCP..." button

Example: displaying a Design TWISS plot

IV. Matlab

For a complete overview, detailed instructions and examples please see the "MATLAB Programmer's Guide for FACET physicists"

Environment setup
After you log onto a Linux machine using the fphysics account, you'll need to customize the environment for matlab. Once Mike Z. has set up your user directory under fphysics as described in II. above, add these commands to your /home/fphysics/userid/ENVS file, and they will be automatically invoked every time you log in. Note: All strings are case-sensitive.

• source /usr/local/facet/tools/script/ENVS_facet.bash
• export EPICS_CA_MAX_ARRAY_BYTES=40000000 (if you'll be using OTR image data)
• export DISPLAY=your_IP_address:0 (if you're logging in from Windows - your_IP_address can be found after running ipconfig)

Starting matlab

• If you want the full GUI development environment, type
  matlab
• If you want to run applications only and/or do some basic scripting (recommended), type
  matlab -nodesktop -nosplash
  This starts the fully working command-line version that requires much less resources.

Directories

• tested matlab scripts that are shared can be found here:
  /usr/local/facet/tools/matlab/toolbox

• matlab scripts developed by the FACET software engineering group are here:
  /usr/local/facet/tools/matlab/src

getSystem() function
Within a matlab script you can use the getSystem function to determine the accelerator system defined in the current working environment. This is useful for writing scripts that can be used for multiple accelerator systems, with conditional actions depending on accelerator.

[system,accelerator] = getSystem();

Return values are:

CVS

• For instructions and examples see the Programmer's Guide.
• All shared matlab scripts are stored in the version control system, CVS. LCLS and FACET matlab scripts share their CVS repository, so there are many LCLS-specific scripts to be found in the toolbox and src directories, alongside the FACET and so-called "accelerator-agnostic" versions.
• Please note: to release a matlab script to production (i.e. to copy the completed and tested version into /usr/local/facet/tools/matlab/toolbox) you need to use the cvs2prod command.
  In the same directory where you are developing and testing script newScript.m, enter this:
  cvs2prod newScript.m

Matlab support PVs
A set of Matlab support PVs for FACET are available from the matlab support soft IOCs, with the naming convention
SIOC:SYS1:ML0x:<type><n>

• x is the IOC number, from 1 - 3
• type indicates PV type
• n is a 3-digit number

To view the PVs:

• bring up facethome
• click the “Matlab GUIs…” button
• click the “Matlab PVs…” button (bottom center)
• click the button for the PV type you’re interested in (e.g. “Matlab Calculation PVs…”)
• in the dropdown list, select the range of PVs to view

To use the PVs:

• Use the edm displays above to find PV(s) that are not used already
• Optionally, edit in the edm display
• Use PV name(s) in your matlab program

Example display of Matlab support CALC PVs:

V. BSA: Beam Synchronous Acquisition

For a complete overview, detailed instructions and examples please see the "MATLAB Programmer's Guide for FACET physicists"

Here is a short description:

A LCLS event system has been setup to read devices synchronous with beam crossing, such as BPMS and toroids. FACET beam synchronous acquisition will interface with both EPICS and the VMS-based SCP. Implementation of this interface is currently in process. The BSA system will be usable from within Matlab. Note that this is not implemented for image data collection, which is described in a separate section of the Programmer's Guide.

Basically, the steps for using BSA are:

• Reserve an event definition
• Change default parameters
• Start data acquisition
• Release event definition

VI. AIDA: Accelerator Integrated Data Access

http://www.slac.stanford.edu/grp/cd/soft/aida/

For a complete overview, detailed instructions and examples please see the "MATLAB Programmer's Guide for FACET physicists"

Here is a short excerpt:

To obtain control system names and values, AIDA is accessible from the linux command line, via aidaWeb https://seal.slac.stanford.edu/aidaweb, through matlab and other language interfaces.

For FACET, the AIDA interface will provide SLC model data, .... (BPM? etc.?)

Basically, to get data from AIDA, use the function
aidaget(aida_name, type, params)

• aida_name is the AIDA control system name, following the pattern <device>//<attribute>
• type (optional case-insensitive string)
• params (optional parameter=value pairs)

VII. FAQs

Q: How do I log onto the channel access network?
A: While shared accounts are used, the command is:
ssh fphysics@facet-srv01
If that hangs, then ssh into mcclogin first:
ssh mcclogin

Q: Where do I put changes to the standard environment setup?
A: Put them in /home/fphysics/<username>/ENVS.
See /home/fphysics/zelazny/ENVS for an example.

Q: How do I check things out of cvs?
A: To checkout software (you only need to do this once):
cd /home/fphysics/zelazny
cvs co matlab/toolbox

Q: How to I put things back in cvs?
A: To put software into cvs:
cd /home/fphysics/zelazny/matlab/toolbox
cvs commit

Q: What if I created some new files?
A: To put new files into cvs:
cvs add <filename>
cvs commit

Q: Why is CVS asking for someone else's password?
A: Your environment isn't setup correctly. Setup with:
set_profile

Q: I'm not listed when I "set_profile", what do I do?
A: Press "0" for none, then create your profile with:
cd /home/fphysics
mkdir <your afs username>
set_profile

Q: How do I release to production?
A: To make software available for general use:
cvs2prod

Q: How do I get files from /afs to the channel access network?
A: To get a file from /afs that's not in cvs:
scp loos@mcclogin:~loos/controls/profmon/profmon_setup.m

Q: Where are the Matlab data files?
A: (on facet-srv01) ls -als $MATLABDATAFILES
(on mcclogin) ls -als ls /mccfs2/u1/facet/matlab
(from SLAC web browsers) http://mccas0.slac.stanford.edu/u1/facet

Q: I'm totally lost, what do I do?
A: Call Jingchen Zhou x4661
fphysics-zelazny@facet-builder ~>

VIII. Useful links