The SUS guardians has been revamped

This was done in order to fix a couple of outstanding usability issues with the SUS guardians, and to make things generally easier to deal with.  Here are the key changes:

complete overhaul of alignment procedure

• The OPTICALIGN OFFSET is now user ONLY for holding the ALIGNED offset value.
• We will no longer misalign the optic by writing different values into the OPTICALIGN OFFSET.
• The OFFSET in the top-stage TEST_P/Y filter banks will be used to store relative misalignment values, which will be engaged (with a ramp) to misalign the optic.

This is a fairly substantial change to procedure, but it has a couple of important benefits:

• no longer need to store and update alignment offsets in separate files
• can misalign optic by engaging just the TEST_OFFSET switches
• now have a trend-able record of the optic alignment offsets

This gives an effective "one button" misalign/align.  We also no longer need to worry about saving alignments.  w00t!

no more ALIGN_TO_PD* states

Sheila declared that the ALIGN_TO_PD1 and ALIGN_TO_PD4 states are no longer needed with the new changes.

alignment offset ramps are now reset to default values after offsets are (dis)engaged

guardian no longer touches filter gains

In general, guardian now touches less stuff.  This is important because it reduces the cross section with the ISC automation that occaissionally needs to adjust the LOCK filter module gains.  It also increases what can be monitored by the new SDF system.

INIT improvements to better determine SUS state on intialization

This will help get the suspensions to the correct state quicker on guardian restarts, with less disturbance.

new procedure to fully enable SUS

In the SAFE state, the SUS is in the following state:

• outputs of (almost) all control filter banks (LOCK, OPTICALIGN, TEST, DAMP) are DISABLED
• alignment OFFSETS, in both the OPTICALIGN and top-stage TEST filter modules, are DISABLED
• MASTERSWITCH is OFF

The full "enable" and alignment procedure is as follows:

• turn on MASTERSWITCH
• turn on DAMP outputs, which enables the damping loops (in reaction masses as well for the quads)
• enable alignment and control module outputs (LOCK, OPTICALIGN, TEST)
• engage OPTICALIGN OFFSET to set DC alignment
• (to misalign, engaged TEST_{P,Y}_OFFSETs)

Here's the new graph:

The DAMPED state now has just the DAMP outputs engaged, so just the damping loops are on.  The FULLY_ENABLED state has the remaining control outputs engaged.  The ALIGNED and MISALIGNED states have the OPTICALIGN and TEST P/Y OFFSETs enabled.

Current status

All SUS guardians were updated such that the TEST_P and TEST_Y filter modules have the same GAIN calibrations that are in the OPTICALIGN banks.  The OFFSETS in the TEST_{P,Y} modules were set such that they corresponded to the last stored "misaligned" values in the alignment snapshots.

All SUS guardian nodes were then restarted.  They all came up without issue.

Important notes

OPTICALIGN OFFSET is no longer the full story of the SUS alignment

This is probably the biggest gotcha.  We need to update the IFO_ALIGN screen to give an indication that the MISALIGNMENT (TEST) OFFSETs are enabled.  There is also no indicator on the SUS_*_OVERVIEW screens that the suspension is in a misaligned state.  Guardian should be considered the main authority for SUS alignment state now.

ALIGNMENT OFFSETS are no longer stored in files, nor are they stored in the safe.snaps

This means that after a front end reboot the stored alignment and misalignment OFFSETS will be lost.  However, they can be easily restored from the BURT snapshots.

I will put together a script that will allow us to easily restore an alignment offset to any point in past, including possibly the last alignment before a reboot.

OPTICALIGN calibrations should be set in the TEST_{P,Y}_GAINs

This is to ensure the same calibrations for the OPTICALIGN and TEST OFFSETs.  These don't usually change, so it shouldn't be an issue, but when they do need to be changed, they will need to be updated in two places

Configuration

The new code is in two new files:

• USERAPPS/sus/h1/guardian/SUS2.py
• USERAPPS/sus/h1/guardian/sustools2.py
• USERAPPS/sus/h1/guardian/SUS.py is a symbolic link to SUS2.py

The new SUS2.py holds all the new guardian logic, and the new sustools2.py is a slightly cleaned-up, guardian-ified and improved version of sustools.  SUS2.py imports sustools2.py.  The old SUS.py was renamed to SUS1.py.  Reverting to the old configuration is a simple matter of repointing the new SUS.py symlink to the old SUS1.py module.

TODO

The plan is still to overhaul the OPTICALIGN parts such that they handle all of this in one place, without needing to use these TEST modules.  This will make things even cleaner.  We will also integrate the new Sigg integrators so that we can have glitch-less offloading of integrated DC values from the ASC loops to the OPTICALIGN biases.

So, things to do:

• Update IFO_ALIGN screen to reflect ALIGNED/MISALIGNED status (maybe add guardian MINI or MICRO screens).
• Script to reset OFFSET from some date in the past.
• Update sustools to handle turning on/off the other control filter modules (DITHER, OLDAMP, etc.)
• Make sure SDF for all SUS is up-to-date for these changes.