FACET Developers Guide

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
  • click the paperclip near the upper lefthand corner of the screen, beneath the Confluence man logo
  • click programming_guide_matlab_facet.pdf to view it
• also in /usr/local/facet/tools/matlab/programming_guide_matlab_facet.pdf

#top

---

I. Logging into the FACET control system

The FACET EPICS control system resides on a 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 server from a linux terminal session:

• Obtain a unix account if you don't have one already: http://www2.slac.stanford.edu/comp/slacwide/account/account.html

• Account setup
  • Please send Ken Brobeck an e-mail request that includes your unix username (with a cc: to your supervisor) to:
    • add your unix ssh key to the fphysics account
    • add your username to controls software unix groups to enable CVS access

• Login:
  • Bring up a linux terminal window:
    • from an MCC OPI  (MCC Control Room Workstation)
      • Click on taskbar icon "Facet Konsole"    
      • This will automatically log you into fphysics on facet-srv01
        • On the OPI's the background color will be a light yellow to differentiate between LCLS and FACET
          
    • From Linux (konsole/xterm), Windows (Secure CRT or XWin32) 
      • Log into mcclogin with your unix account:
        • ssh mcclogin
      • From mcclogin, log into facet-srv01 as the fphysics account
        • ssh fphysics@facet-srv01
           
  • Enter the number corresponding to your username from the list. If you are not in the username list yet and would like be, then:
    • enter 0 (for None). You will end up in directory /home/fphysics.
    • mkdir username (username is your Unix login username)
    • logout
    • log back in, as above: ssh fphysics@facet-srv01
    • Enter the number corresponding to your username
       
  • You should now be in /home/fphysics/username (e.g. /home/fphysics/fred)
  • Your environment should now be set up to run and develop matlab scripts.

• Optional: if you want to customized your environment further
  • Create file /home/fphysics/username/ENVS
  • ENVS will be sourced every time you log in

#top

---

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

#top

---

III. SCP

SLC system principles and development documents:
The different kinds of Mode in the SCP http://www.slac.stanford.edu/%7Egreg/modes.html
Facet model preparation http://www.slac.stanford.edu/~mdw/FACET/doc/OnlineModel.txt
SLAC Online Modelling Programmers Guide http://www-mcc.slac.stanford.edu/%7Egreg/model_overall_pg.html

Principals of Operation (POOP): http://www.slac.stanford.edu/grp/cd/soft/wwwman/poop.html
Basic User Guide (BUG): http://www.slac.stanford.edu/grp/cd/soft/wwwman/bug.www/

To run a SCP from a terminal session window:

• obtain a VMS account and userid on MCC if you don't have one already: https://slacspace.slac.stanford.edu/SITES/CONTROLS/Pages/MCCComputerAccount.aspx

• from your unix 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

An example: displaying a Design TWISS plot from the SCP:

#top

---

IV. Matlab

For detailed instructions on developing matlab scripts, and examples, please see the "MATLAB Programmer's Guide for FACET physicists", attached to this Confluence page.

Environment setup

• After you log onto a Linux machine using the fphysics account, your environment will be set up for running and developing matlab scripts.

Starting matlab

• type
  matlab

• 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 a 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.

basic flow for working with matlab scripts and CVS

• if you haven't already, cvs checkout the matlab toolbox directory into your working area (/home/fphysics/fred)
  cd /home/fphysics/fred (if you're fred!)
  cvs co matlab/toolbox
• cd into the toolbox directory
  cd matlab/toolbox
• to get the latest CVS-ed copy of a script, use cvs update:
  cvs update myScript.m
  or to get the latest CVS-ed copies of all the scripts:
  cvs update
• work on a new script, or an existing script
• test thoroughly until your work is ready for primetime
• cvs add any new scripts you've created
  cvs add myScript.m
• cvs commit scripts that you have added or changed
  cvs commit myScript.m
• release new/changed scripts to the production directory (/usr/local/facet/tools/matlab/toolbox)
  cvs2prod myScript.m

Development environment note
Once you have done cvs checkout matlab/toolbox, the next time you login to facet-srv01 (as fphysics - see above #login section) your matlab working directory /home/fphysics/yourusername/matlab/toolbox will be prepended to the MATLABPATH environment variable. This means that when you (logged in as your username) run a script you're developing, your version will run instead of over the one in production.

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:

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 Support PVs…”)
• in the dropdown list, select the range of PVs to view

To use the PVs:

• Use the edm displays above to select PV(s) that are not used already (value is spare, description is comment)
• Enter a description in the comment field (overwrite "comment")
• Use the PV name(s) in your matlab program

Example display of Matlab support AO PVs:

CODE Examples

• Buffered Data Acquisition example script:
  • log into facet-srv01 as fphysics
  • have a look at Mike Zelazny's script:
    /usr/local/facet/tools/matlab/toolbox/EPICS_SLC_buffAcq_Example.m

EPICS PV visibility

• On the FACET network, PVs hosted by all FACET IOCs are available.
• In addition, LCLS PVs are available read-only via a PV gateway, which is configured in the default FACET epics setup. For more information see: https://confluence.slac.stanford.edu/display/ACCSOFT/LCLS+and+FACET+production+PV+gateways
  #top

---

V. BSA: Beam Synchronous Acquisition - CURRENTLY UNDER CONSTRUCTION FOR FACET

For a complete overview, detailed instructions and examples please see the "MATLAB Programmer's Guide for FACET physicists", attached to this Confluence page.

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.

more coming...

#top

---

VI. AIDA: Accelerator Integrated Data Access - CURRENTLY UNDER CONSTRUCTION FOR FACET

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

For instructions and examples please see the "MATLAB Programmer's Guide for FACET physicists", attached to this Confluence page.

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.

list of data sources

• see Individual Service Data Users Guides on [http://www.slac.stanford.edu/grp/cd/soft/aida/ ]

command line tools

• aidalist: [http://www.slac.stanford.edu/grp/cd/soft/aida/aida_ug.html#What ]
• aidaget, aidaset: [https://confluence.slac.stanford.edu/display/ACCSOFT/AIDA+Command-line+tools ]

matlab

• using aida in matlab programs: [http://www.slac.stanford.edu/grp/cd/soft/aida/aida_matlab.html ]

SLC Buffered Data Service

• [http://www.slac.stanford.edu/grp/cd/soft/aida/slcBuffDpGuide.html ]

web interface

• AidaWeb: [https://confluence/display/ACCSOFT/AidaWeb+Help ]

#top

---

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 unix username>
log out of fphysics, and log back in. You should be listed.

Q: How do I release to production?
A: To make software available for general use, you will use the cvs2prod utility. See above #matlab "basic flow" section abovve
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

#top

---

VIII. Useful links

#top

---

IX. Edit the Developers Guide

Please feel free to modify/correct/add to this document

• Click the "Log In" link in the upper right-hand corner to the left of the Search box.
• Enter your Unix username and password
• Click the Edit link (pencil) beneath the Search box
• Edit in the Rich Text Editor, or click the Wiki Markup tab to edit in the Markup language.
• Markup syntax guide: https://wiki.ucar.edu/renderer/notationhelp.action
• Be sure and click the Preview tab before saving to make sure your changes look ok
• Click the "Save" button to publish your changes.

#top