KAGRA VIS Operations Manual - vistools.py

vistools.py is a Python module and command-line utility for manipulating the suspensions. It lives in /opt/rtcds/userapps/release/vis/k1/scripts (although it may get moved to /opt/rtcds/userapps/release/vis/common/scripts and there is a symlink to it in /opt/rtcds/userapps/release/vis/k1/guardian. Nearby there may be a test version vistoolstest.py.

vistools.py usage modes

vistools.py has three modes of use:

• In a generic Python script.

• In Guardian.

• As a command line utility.

vistools.py as a Python module

vistools.py is primarily an ordinary Python module which provides the class Vis. Each instance of Vis represents a single suspension and can be created with any of the following forms:

BS = vistools.Vis('BS') # an Ezca instance with prefix 'K1:' is created internally
BS = vistools.Vis('VIS-BS') # channel name prefix style
BS = vistools.Vis('VIS_BS') # Guardian file name style
BS = vistools.Vis(('BS',ezca)) # ezca should be an existing ezca.Ezca instance with prefix 'K1:'; 'BS' can be 'VIS-BS' or 'VIS_BS'

A Vis object has a large number of methods which are mostly organized and named by blocks of filters of the same function (e.g., DAMP) at different levels of the suspension:

BS.masterSwitchWrite('ON') # turns the master switch on
BS.dampGainWrite(1.0) # sets all gain values in all DAMP blocks to 1.0. 
BS.dampGainWrite(1.0,levels=['IP']) # sets all gain values in the IP DAMP block to 1.0.  
BS.dampGainWrite(1.0,levels=['IP'],chans=['L','T']) # sets the gain values for the L and T channels of the IP DAMP block to 1.0 

Do dir(vistools.Vis) for a complete listing and help(vistools.Vis.methodName) for more details on individual methods. A typical signature is dampGainWrite([self,] value, levels=[], chans=[], verbose=False, pair='none', withprefix='bare', matlab=False, dorw=2). The arguments are as follows:

• value: a value or list of values to be written (write methods only)

• levels: a list of levels to restrict the request or change the default order, e.g, ['IP','F0','F1','BF']

• chans: a list of channels within a block to restrict the request or change the default order, e.g., ['L','T'] for IP DAMP.

• verbose: if True, bring debugging information, typically the channel names written to

• withprefix: can be 'full', 'half full', 'half bare' or 'bare'; selects how much of the PV name to return (see next argument)

• pair: can be 'pv', 'both' or 'value'; selects whether to return the channel name along with the read/written value

• matlab: if True, returns lists with Matlab-style syntax

• dorw: 0 -> no live channel access; 1 -> no live write channel access (read only); 2 -> live reading and writing

Not all methods are implemented for every block (feel free to add more based on existing patterns) but DAMP has a fairly complete set which illustrate the naming scheme:

• dampPvs: Return a list of PVs for DAMP blocks.

• dampInputSwitchWrite: Write 'ON' or 'OFF' to the INPUT switch in DAMP blocks.

• dampInputSwitchRead: Read the INPUT switch in DAMP blocks.

• dampOutputSwitchWrite: Write 'ON' or 'OFF' to the OUTPUT switch in DAMP blocks.

• dampOutputSwitchRead: Read the OUTPUT switch in DAMP blocks.

• dampOffsetSwitchWrite: Write 'ON' or 'OFF' to the OFFSET switch in DAMP blocks.

• dampHoldSwitchWrite: Write 'ON' or 'OFF' to the HOLD switch in DAMP blocks.

• dampOffsetWrite: Write a value or list of values to the OFFSET field in DAMP blocks.

• dampGainRead: Read the gain value in DAMP blocks.

• dampGainWrite: Write a value or list of values to the GAIN field in DAMP blocks.

• dampFilterModuleEnableWrite: Write 'ON' or 'OFF' to the filter switches in DAMP blocks.

• dampRampWrite: Write a value or list of values to the RAMP field in DAMP blocks.

• dampGainRampingRead: Read the gain ramping state (GRAMP) in DAMP blocks.

• dampOffsetRampingRead: Read the offset ramping state (ORAMP) in DAMP blocks.

• dampRampingRead: Read the overall ramping state (GRAMP or ORAMP) in DAMP blocks.

• dampPressButton: Simulate a press of the CLEAR HISTORY ('CLEAR') or LOAD COEFFICIENTS ('LOAD') button in DAMP blocks.

vistools.py from within Guardian

The usage from within Guardian is a bit complicated. According to some versions of the Guardian documentation, there is supposed to be a global Ezca instance called ezca which can be used for channel access. And according to some versions of the documentation, it is supposed to have prefix K1:VIS_BS_ or the like (which gets prepended to channel name fragments passed to it). If you run the Guardian in interactive mode, e.g.,

guardian -i VIS_BS

then there is indeed a global ezca object, but it has prefix just K1:, so the appropriate setup is

vis=vistools.Vis((SYSTEM,ezca))

• because (i) there is already one the ezca object used to communicate with EPICS has been changed to being

vistools.py as a command-line utility

vistools.py Internal Organization

vistools.py uses two large nested dictionary structures, visTypes and visData to define what groups of channels are available. A typical entry in visTypes specifies a particular suspension (e.g., "BS") in terms of a generic type (e.g., "TypeB") plus watchdog and BIO information:

visTypes = {
...,
    ('K1','BS') : {'type': 'TYPEB', 'watchdogs': typebwd, 'bio' : typebbio},
...
}

where

typebwd = {'IOP':'DACKILL','IP':'IP_WDMON', 'F0':'F0_WDMON','F1':'F1_WDMON','BF':'BF_WDMON', 'IM':'IM_WDMON','TM':'TM_WDMON'}
typebbio = {'GAS':'BIO_GAS_MON','IP':'BIO_IP_MON','GAS':'BIO_GAS_MON','IMV':'BIO_IMV_MON','TM':'BIO_TM_MON'}

Then, a typical entry in visData specifies a generic suspension type, which is further structured by level ('IP', 'F0', 'F1' etc).

visData = {
    'levelorder': ['IP','F0','F1','BF','SF','IM','TM'],
    'levels' : {
     ... 
     'IM':{
          'dofs' : ['L', 'T', 'V', 'R', 'P', 'Y'],
          'isichans' : ['X', 'Y', 'RZ', 'Z', 'RX', 'RY'],
          ...
          'cart2eul' : {'blockname':'CART2EUL', 'inames':'isichans', 'onames':'dofs', 'default':[...]},
          ...
         },
     },
     ....
}

vistools.py Style Guide

vistools.py should have groups of 4 spaces for indentation. To select this in gedit, select Automatic Indentation off, Tab Width 4, Use Spaces on in the Tab Width menu in the lower window frame:<<br>>