= KAGRA VIS Operations Manual - Guardian =

Link to the aLigo Guardian Introduction:

[[https://dcc.ligo.org/public/0111/G1400016/007/guardian-introduction.pdf|aLigo Guardian]].

[[http://klog.icrr.u-tokyo.ac.jp/osl/?r=906|first start guardian klog:906]]

== Guardian System-Level Installation ==
`/kagra/apps/guardian/bin` has shell scripts `guardctrl` etc. 

 * `guardian` Core guardian daemon program. Executes system state machines, or single states or graph paths.
 * `guardmedm` Launch MEDM control interface for a Guardian node. 
 * `guardutil ` Utility program for displaying system information.
 * `guardctrl ` Interface to the site Guardian infrastructure, for controlling nodes and accessing logs.
 * `guardlog` Interface to view node logs.

These can be run directly on the machine `k1grd0`. If run from another computer they will still work but will ask for the `controls@k1grd0` password first.

`/kagra/apps/guardian/bin/guardian` ends up running guardian in `/kagra/apps/guardian/lib/python2.7/site-packages/guardian`.

All the scripts take a Guardian script name (less `.py`) as the primary argument, e.g., `VIS_BS`. 

Once a Guardian has been set up for a system (with `guardutil create`), it is rarely necessary to use the scripts directly. Changes to a Guardian script can normally be applied using the `LOAD` button on the associated MEDM screen:<<BR>>
[[attachment:SRM Guardian Screen.png|{{attachment:SRM Guardian Screen.png||width=400}}]]<<BR>>
However if the names or numbering of the states in a Guardian script have been changed, it is sometimes necessary to stop and restart it with:
{{{
> guardctrl stop VIS_BS
> guardctrl start VIS_VIS
}}}
Note that this will send the Guardian back to the `SAFE` state, whereas the `LOAD` method normally won't.

== Type B ==

The main Python scripts for the VIS Guardians, including Type B, live in `/opt/rtcds/userapps/release/vis/k1/guardian`. `TYPEB.py` is the main file - `VIS_BS.py`, `VIS_SR2.py`, `VIS_SR3.py` and `VIS_SRM.py` are one-line programs which simply load it. (They could also point to test versions of `TYPEB.py`, e.g., `TYPEB_MB.py`.)

`TYPEB.py` adds `/opt/rtcds/userapps/release/vis/k1/scripts/` to the path, making available support packages including `burt.py`, `vistools.py` etc.

The Guardian makes use of various snapshot files in directories as follows. These are modified by commands in the `Take/Restore Snapshot` pop-up menu on the `VIS_CUST_TYPEB_OVERVIEW.adl` screen. The examples below are for BS, but apply equally to other Type B with obvious substitutions (BS->SR2/SR3/SRM and bs->sr2/sr3/srm).
When a model is run, the system looks for files like 
 * `/opt/rtcds/kamioka/k1/target/k1visbst/k1visbstepics/burt/safe.snap`   # for the top model
 * `/opt/rtcds/kamioka/k1/target/k1visbsp/k1visbspepics/burt/safe.snap`   # for the payload model
These are symbolic links to the following files in the SVN-controlled userapps area:
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbst_safe.snap`   # for the top model
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbsp_safe.snap`   # for the payload model
The `Take Payload Model Safe Snapshot` and `Take Top Model Safe Snapshot` menu items create these snapshots using the request files automatically generated when the models are compiled:
 * `/opt/rtcds/kamioka/k1/target/k1visbst/k1visbstepics/autoBurt.req`   # for the top model
 * `/opt/rtcds/kamioka/k1/target/k1visbsp/k1visbspepics/autoBurt.req`   # for the payload model
The `Restore Safe Snapshots` menu item restores both of the above .snap files at once.

The system for making Guardian-related snaps is now divided into three sections, for IP, GAS and ALIGN/MISALIGN.

The IP setpoint is managed with the menu items `Take IP Setpoints Snapshot` and `Restore IP Setpoints Snapshot`, which use the files
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbst_IP.req`   # note "t" for the top model
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbst_IP.snap`   
The GAS setpoints are managed with the menu items `Take GAS Setpoints Snapshot` and `Restore GAS Setpoints Snapshot`, which use the files
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbst_GAS.req`   # note "t" for the top model
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbst_GAS.snap`   
The ALIGN setpoints are managed with the menu items `Take Align Setpoints Snapshot` and `Restore Align Setpoints Snapshot`, which use the files
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbsp_align.req`   # note "p" for the payload model
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbsp_align.snap`   
The MISALIGN setpoints are managed with the menu items `Take Misalign Setpoints Snapshot` and `Restore Misalign Setpoints Snapshot`, which use the files
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbsp_align.req`   # note "p" for the payload model, and plain "align" - this is the same file as above.
 * `/opt/rtcds/userapps/release/vis/k1/burtfiles/k1visbsp_misalign.snap`