0. BASIC Channel Access INTEROP
===============================

EPICS V4 client side commands support both the new protocol PvAccess, and Channel Access.
However, by default V4 commands try only PvAccess, so if you want to use CA, you must
use "-p ca" or the full URI style syntax of EPICS V4.

$ eget -p ca EVNT:SYS0:1:LCLSBEAMRATE
0                                         [ok, we're not presently running the accelerator]

eget -p ca QUAD:LTU1:880:BACT

eget ca:///EVNT:SYS0:1:LCLSBEAMRATE

eget ca:///QUAD:LTU1:880:BACT

1. MODEL DATA
=============

Model data is example of using arguments to a PV. Arguments are given as
name value pairs (optionally with '=' between them)

Note that argument names *are case sensitive!* b != B. Also, if you get the name
wrong, the server won't complain, will ignore the invalid argument. However,
I have made MEME argument values case insensitive.

Both RMAT and TWISS take:
Name  Value             Default    Comment
----  ----------------  ---------  ------------------------------------------
run   <integer>         1          Run id number, as given by the model GUI.
                                   1==most recent gold, the default 
type  extant | design   extant     From real PV values (extant) or from Design 
Pos   beg | mid | end   end        From where in multi-component elements, the
                                   beginning, middle or end
mode  5 | 55 | 53 | 52  5          The timing mode. 5 for LCLS full machine.

RMAT PVs additionally take:
Name  Value             Default    Comment
----  ----------------  ---------  ------------------------------------------
b     device name       none       RMAT of A to B is returned
posb  beg | mid | end   beg        

1.1. R MATRICES 
---------------

1.1.1. R matrix of one element

$ eget -s QUAD:LTU1:880:RMAT             ("classic" syntax)
    -0.156946      -0.15959             0             0      0.391116    0.00540698
     0.0133542     0.0110122             0             0    -0.0173222   -0.00021337
  -1.05117e-06  -1.98485e-07    -0.0074217      0.479216   0.000110175   1.87252e-06
   1.12246e-07   2.11945e-08  -5.16277e-05    -0.0523249  -1.17647e-05   -1.9995e-07
  -0.000522173   -0.00039278    2.5574e-08   3.49462e-08    -0.0174609  -0.000185892
     0.0346964    0.00655144             0             0      -3.63658    -0.0618066
     
eget pva:///QUAD:LTU1:880:RMAT?        (URI syntax)

eget pva://mccas0.slac.stanford.edu:39633/QUAD:LTU1:880:RMAT?   (URI with direct address)

eget -s QUAD:LTU1:880:RMAT -a type design

eget -s QUAD:LTU1:880:RMAT -a run=46696

eget -s QUAD:LTU1:880:RMAT -a run=46696 -a pos=mid

eget pva://mccas0.slac.stanford.edu:39633/QUAD:LTU1:880:RMAT?type=design   

1.1.2. R matrix from A to B. Basis of steering, bumps etc.

$ eget -s XCOR:IN20:491:RMAT -a b BPMS:IN20:525
      0.669591      0.694604             0             0  -3.08532e-19   2.41325e-19
     -0.570851      0.901275             0             0  -1.23627e-19   1.45491e-19
             0             0       1.33379      0.966896             0             0
             0             0      0.358415       1.00957             0             0
  -2.29302e-24   8.92892e-20             0             0             1   1.20724e-05
   1.00974e-28             0             0             0             0             1

eget -s XCOR:LI24:900:RMAT -a b=BPMS:LI25:901 -a type=design

1.2. TWISS PARAMETERS
---------------------

# Twiss parameters at device (extant by default)
$ eget -s XCOR:LI24:900:TWISS
non-normative type
structure 
    double energy 5.00512
    double psix 37.7625
    double alphax 13.6562
    double betax -2.78671
    double etax -0.00698294
    double etaxp 0.00107115
    double psiy 31.9488
    double alphay 116.762
    double betay 5.2592
    double etay 0
    double etayp 0
    double z 2438.72
    double leff 0
    double sleff 0
    int ordinality 1332

# Compare design to existing
eget -s XCOR:LI24:900:TWISS -a type=design

# Twiss at middle of a quad
eget -s QUAD:LI28:901:TWISS -a type=extant -a pos=mid

1.3. MODEL DATA OF WHOLE MACHINE
--------------------------------
PVs named MODEL:* give data for whole beamlines. These PVs don't take arguments. Rather there
are a number of PVs for each major combination of parameter kind (Rmat, Twiss),
type (extant, design), beamline etc. See ds example below to get a list of these MODEL Pvs.

# R-matrices of all devices from Cathode to dump, plus devices names, elements names, S etc, sorted by S.
eget -s MODEL:RMATS:EXTANT:FULLMACHINE

# R-matrics computed from nominal design model, but from Cathode to end of the 52 line
eget -s MODEL:RMATS:DESIGN:CATHODETO52SL2

# Courant-synder params, plus Energy and a few other things
eget -s MODEL:TWISS:EXTANT:FULLMACHINE

Many others not shown here; get complete list with "eget -s ds -a name=MODEL:%"

2. MISCELLANEOUS GENERAL LCLS DATA
==================================
Information about devices and infrastructure of LCLS as a whole, is available though
EPICS V4 PVs. These PVs are named in general starting "LCLS". Most of them result in
large tables of device and element data from Oracle.

(with a wide window, say 120 chars, this will fit)

# All active elements and devices, sorted by S (element name, device name, S position, whether obstruction)
$ eget -s LCLS:ELEMENTS 
             ELEMENT          ELEMENT_TYPE     EPICS_DEVICE_NAME             S_DISPLAY           OBSTRUCTION
               SOL1BKS                   MAD     - NO EPICS NAME -                 5e-10                     N
              CATHODES                   MAD     - NO EPICS NAME -                 1e-09                     N
                 CQ01S                   MAD     - NO EPICS NAME -               0.19601                     N
                 SOL1S                   MAD     - NO EPICS NAME -               0.19601                     N
                 XC00S                   MAD     - NO EPICS NAME -               0.19601                     N
                 YC00S                   MAD     - NO EPICS NAME -               0.19601                     N
                 SQ01S                   MAD     - NO EPICS NAME -               0.19601                     N
                YAG01S                   MAD     - NO EPICS NAME -               0.74899                     N
                 FC01S                   MAD     - NO EPICS NAME -                   0.8                     N
               CATHODE                   MAD         CATH:IN20:111                2014.7                     N
                SOL1BK                   MAD         SOLN:IN20:111                2014.7                     N
                  CQ01                   MAD         QUAD:IN20:121                2014.9                     N
                  SOL1                   MAD         SOLN:IN20:121                2014.9                     N
                  XC00                   MAD         XCOR:IN20:121                2014.9                     N
      ... (many rows snipped)
      
# All elements in general, sorted by device name
eget -s LCLS:ELEMENTINFO

# All Beam Synchronous PV "ROOTNAMES", with areas, Z and element name, sorted by linac Z
eget -s LCLS:BSA_PVS

Many others not shown here, see "eget -t -s ds -a name=LCLS:%"

3. DIRECTORY SERVICE (DS)
=========================
The data sources for the directory service are the IOC input files (for PVnames) and
the "lines" files emitted by the new MEME model system, see [2]. There you'll find
the tags used for line names, element names, element types etc.

# The names of PVs of a device, by giving the device name pattern:

$ eget -s ds -a name=XCOR:LI21:135:% 
                                  name
                  XCOR:LI21:135:ABORT
                 XCOR:LI21:135:ACCESS
              XCOR:LI21:135:ALLFUNCGO
                   XCOR:LI21:135:BACT
                 XCOR:LI21:135:BACTFO
             XCOR:LI21:135:BACTLIMITS
                 XCOR:LI21:135:BADIFF
... (many rows snipped)

The PV names of BDES PVs matching regular expression (restrict to sectors LI25-LI29)
eget -s ds -a regex='XCOR:LI2[5-9]:.*:BDES'
 
# The device names matching a wildcard pattern
eget -t -s ds -a name=XCOR:LI21:% -a show=dname

The device names of deivces in L1
(DS only knows area tags like L1 for modelled devices, see modelled device topology of LCLS [1])
# eget -t -s ds -a tag=L1 -a show=dname

# The device names matching a pattern, that are also in a given line (L2)
eget -t -s ds -a name=XCOR:LI21:% -a show=dname -a tag L2

# Device name, given element name (Mike's "decoder ring")
eget -t -s ds -a tag=XC05 -a show=dname

# Element names given PV pattern
eget -t -s ds -a name=XCOR:LI21:% -a show=ename

# Names of devices only in the Dog Leg, sorted by z
eget -t -s ds -a tag=DL1 -a name=XCOR:% -a sort=z -a show=dname

# Verify a given PV name (uri syntax)
eget pva:///ds?name="QUAD:LI28:901:BDES"

# BPM X pv names, of BPMs in DL1, sorted by z 
eget -t -s ds -a tag=DL1 -a name=BPMS:%:X -a sort=z    

# Get names of BPMS in DL1 and then the values using eget from ds piped to eget
eget -t -s ds -a tag=DL1 -a name=BPMS:%:X -a sort=z | eget -p ca -f -

# X correctors and BPMS in DL1, showing use of regular expression
eget -s ds -a name='(XCOR|BPMS):.*' -a tag=DL1 -a show=dname -a sort=z

# QUAD polynomial PVs in LTU
eget -t -s ds -a tag=LTU -a name='QUAD:.*:POLYCOEF'

# Get PV names relating to LCLS global data
eget -t -s ds -a name=LCLS:%

# What's the device name of an element?
eget -s ds -a ename=XC06 -a show dname

# What's the BDES PV name of an element?
eget -s ds -a ename=XC06 -a name=%:BDES

# What's the element name of a device?
eget -s ds -a dname=XCOR:IN20:491 -a show ename

# Even, what's the element of a given PV?
eget -s ds -a name=XCOR:IN20:491:BDES -a show ename

# What are the device names of the instruments in the laser heater line?
$ eget -s ds -a etype INST -a tag LSRHTR -a show dname
           name
  DUMP:IN20:999
   HTR:IN20:467
  STPR:IN20:551

# What are the element names of the instruments in the laser heater line?
$ eget -s ds -a name % -a etype INST -a tag LSRHTR -a show ename -w 10
    name
  HTRUND
    RST1
    SDMP

Get systems of values with Directory Service searches for PVs
------------------------------------------------------------
# Get PV names. Use eget transpose to get array
eget -ts ds -a name 'XCOR:LI22:%:BDES' -T            
XCOR:LI22:202:BDES XCOR:LI22:302:BDES XCOR:LI22:402:BDES XCOR:LI22:502:BDES XCOR:LI22:602:BDES XCOR:LI22:702:BDES XCOR:LI22:802:BDES XCOR:LI22:900:BDES

# Get PV values of PVs whose names match wildcard
pvget -p ca `eget -ts ds -a name 'XCOR:LI22:%:BDES' -T `
XCOR:LI22:202:BDES             -0.000973934
XCOR:LI22:302:BDES             0.00490518
XCOR:LI22:402:BDES             -5.82456e-05
...

# Get polynomial values too. Since they're fields, and ds doesn't know fields, I have
# to add that with xargs 
eget -t -s ds -a tag=LTU -a name='QUAD:.*:POLYCOEF' | xargs -tI{} eget -p ca {}.{A,B,C}

# A recent search for invalid data in LTU corrector field PVs
eget -tTs ds -a name %COR:LTU%:%:%DES | eget -p ca -f - | grep nan
XCOR:LTU1:558:BDES nan
XCOR:LTU1:558:IDES nan 

# A recent search for invalid CALBOK fields:
$ eget -t -s ds -a name='%COR:.*:CALBOK' | xargs -I{} eget -p ca {}.{SEVR,STAT} | grep INVALID 
XCOR:LI21:275:CALBOK.SEVR INVALID
XCOR:LI27:202:CALBOK.SEVR INVALID
XCOR:LI27:302:CALBOK.SEVR INVALID
...

# Get values of RPC style PVs whose names match wildcard. Eg get design model of a number of devices.
# (NOTE that eget does not support (yet) streaming RPC Pvs, so getting values of many
# RPC type PVs must go via xargs)
eget -s ds -a regex='XCOR:LI2[5-6]:.*:TWISS' | xargs -I{} eget -s {} -a type=design

# Get R-mats of all quads in LI21 (careful, will be problematic in IN20
# since there are QUAD devices that are not online modelled). 
eget -ts ds -a name QUAD:LI21:%:RMAT | xargs -I{} eget -s {}

# Find the PV that says when slotted foil was finished moving. First find
# PVs with FOIL in their name, then having found all the PV names, see
# their values. 
eget -s ds -a name FOIL%
eget -ts ds -a name FOIL:LI24:807% | eget -p ca -f -

4. EPICS V4 METADATA
====================
pvlist tells you information about the EPICS V4 servers and their PVS which are on the network.

Without arguments, pvlist gives addresses of the PVA servers presently running:

$ pvlist
GUID 0x41A898A257D34E12B048D596, version 1: tcp@[134.79.151.36:56765]
GUID 0x8CB4FBCB467E4AAF85CBFB99, version 1: tcp@[134.79.151.36:41930]
GUID 0xA7D85FBAF71845B4BB6E060D, version 1: tcp@[134.79.151.36:39633]
GUID 0xB075C37C347D46C883E18B52, version 1: tcp@[134.79.151.36:5055]

With argument of address, it gives PVs known by the server at that address:

$ pvlist 134.79.151.36:41930
ds                                 [the directory service, whose PV name is "ds"]

$ pvlist 134.79.151.36:39633
....                               [the optics serivce, giving many PVs (of type RPC)]
BPMS:LI25:901:TWISS
BPMS:LI26:701:TWISS
QUAD:LI28:301:TWISS
YCOR:LI27:503:TWISS
YCOR:UND1:1880:RMAT
KLYS:LI27:41:RMAT

[NOTE though that all such names should also be available through the directory service]

[1] http://www.slac.stanford.edu/grp/ad/model/lcls.html#visualizations
[2] Device topologies http://www.slac.stanford.edu/grp/ad/model/output/lcls/latest/opt/LCLS_lines.dat