We repeatedly had problems with engaging ASC loops to the bottom or penultimate mass that have a top stage relieve loop.

In a nutshell, the problem comes with engaging the loop with a relatively big initial misalignment. The fast loop to PUM or TST does the right thing, but saturates its drive stage before the top mass relieve can kick in. Increasing the top mass relief doesn't always work because different loops feed the same test mass.

The ideal approach would be a saturable integrator in the ASC filter banks. Since this this would require a front-end code change, I wrote a python version that watches filter module output and input, and simply turns the input off if the integrator exceeded the limit and the error signal would drive it further away.

The code relies on guardian decorators. I.e. it should be added to any state during which this logic should be active. The decorator is defined in ISC_library.py, and can be called as:

    @FM_limit_checker_decorator(ListOfFIlterModulePrefixes_pos_gain,+1)
    @FM_limit_checker_decorator(ListOfFIlterModulePrefixes_neg_gain,-1)

Example:
    @FM_limit_checker_decorator({'ASC-SRC2_P','ASC-SRC2_Y','ASC-DSOFT_Y','ASC-CSOFT_Y'},+1)
    @FM_limit_checker_decorator({'ASC-DSOFT_P','ASC-CSOFT_P'},-1)

Positive and negative gain characterizes the overall gain of all engaged filters, i.e.
 - +1 : positive input signal leads to growing output signal and vice versa
 - -1 : positive input signal leads to shrinking  output signal and vice versa



Current testing:
================
 - For initial testing we added the decorator to

i) DRMI guardian ENGAGE_DRMI_RUN state:
    @FM_limit_checker_decorator({'ASC-SRC2_P','ASC-SRC2_Y'},+1)

ii) ISC guardian ENGAGE_ASC run state:
    @FM_limit_checker_decorator({'ASC-SRC2_P','ASC-SRC2_Y','ASC-DSOFT_Y','ASC-CSOFT_Y'},+1)
    @FM_limit_checker_decorator({'ASC-DSOFT_P','ASC-CSOFT_P'},-1)

Known bugs:
===========
 - Currently the filter module will be left in whatever state it was when the decorator ran for the last time. It is up to the user to assure the filter module is actually on in the end.


The full code in ISC_library.py is:
---------------------------------------------------------------------------------------------------
def FM_limit_checker_decorator(FMlist,sign):
    class FM_limit_checker(GuardStateDecorator):
        """Check for FM reaching limiters - if so, turn of input"""
        def pre_exec(self):
            for FM in FMlist:
                if  ((-ezca[FM+'_OUTMON'] >= ezca[FM+'_LIMIT']) and (-ezca[FM+'_INMON']*sign> 0)) or
                    (( ezca[FM+'_OUTMON'] >= ezca[FM+'_LIMIT']) and ( ezca[FM+'_INMON']*sign> 0)) :
                    ezca.switch(FM, 'INPUT', 'OFF') 
                else:
                    ezca.switch(FM, 'INPUT', 'ON')   
    return FM_limit_checker