J. Kissel, K. Izumi

Motivated by recent confusion about calibration because changes in the optical gain, Kiwamu and I took a long hard look at a front-end implementation of computing slowly-time-varying optical gain correction to the IFO's DARM sensing function, traditionally called 'gamma' among the Calibration group. Re-convincing ourselves of what we want to do, based on how gamma has been computed in the past, and how aLIGO's *offline* GDS code is still doing it (see T1300088, L1400081, LHO aLOG 16926), we've decided to try the following attached configuration.

We have not yet done anything with this new version of the h1calcs.mdl (no compile, no svn commit, no nothing), I just want to document what we've done for discussion (though there should be no harm in committing to the repo and just installing this model since its independent of any control system, and we've made sure that the configuration control for the EPICs records for this model are now sound -- see LHO aLOG 17037).

There're lots of changes to what was implemented BEFORE, (i.e. the first crack at it):
- The BEFORE implementation had fed DARM_ERR into the GAMMA block for calculation... that was just wrong, so we fixed it.
- The calibration line's oscillator parts, the filtering of DARM_CTRL, and the phasing and filtering of the I and Q outputs have all been brought together into one block -- the already existing library part for a demodulator,
${userapps}/cds/common/models/lockin.mdl.
The advantage is that there's already canned, generic, MEDM screens pre-made for such a tool, so we don't have to re-invent that wheel. This changes the individual calibration line's channel names from
${IFO}:CAL-CS_LINEn_LO 
to
${IFO}:CAL-CS_GAMMA_LINEn_DEMOD_LO
where n = 1,2,3,4. The former wasn't stored in the frames and now screens have been made using them, or to our knowledge even measured once as a test point, so I don't think this channel change matters much. The overall sum of lines is still, the perhaps more transparent,
${IFO}:CAL-CS_LINE_SUM
- Surrounding the DEMOD library part, is the actual calculation of gamma. In this calculation, we've found the need to create two new EPICs records: 
${IFO}:CAL-CS_GAMMA_LINEn_REF_OLG
and
${IFO}:CAL-CS_GAMMA_LINEn_AMP
the former is to be the reference, DARM open loop gain transfer function magnitude or real part at the calibration line frequency, and AMP is the calibration line amplitude. It would be best is AMP was taken directly from the output of the OSC part in the DEMOD block, but unfortunately that front-end code accessibility is not a feature yet built into the part. We'll ask Rolf about adding it, but of course, the OSC part is used in LOTS of other places, so the headache may be better dealt with by keeping two EPICs records synchronous than to terminate the output of every one else's oscillator parts in every other model literally world-wide. This new library block lives in
${userapps}/cal/common/models/CAL_GAMMA_CALC_MASTER.mdl
- There had been 4 calibration lines, which means one could potentially calculate a gamma from any of these lines -- but only one should be used to correct the DARM calibration time series. So, we've installed the infrastructure to calculate a gamma for every line, but sent the output into a 4x1 matrix, so we can choose which gamma to use "on the fly," or at least without have to change the front-end code.

Comments on what we intend to *do* with the infrastructure:
- Make / Improve the CAL-CS overview screen to include the GAMMA calculation as well as a display of the calibration lines.
- We'll install two DARM calibration lines at 34.7 and 538.1 [Hz] as described in LLO aLOG 15870.
- We'll set the amplitude such that we have an SNR of 30 as described in LLO aLOG 15944, and make sure to copy the CLK_GAIN over to the AMP EPICs record and update the records in the CAL-CS SDF system.
- We'll use some reasonably aggressive band-pass at the given line's frequency in the DEMOD_SIG bank, and install a low-pass filter with a corner frequency at 0.01 [Hz] in the I and Q. The corner frequency is chosen to represent a 100 [sec] "average." In S5 and S6, recall that the offline calibration correction was computed by averaging over one minute (60 [sec]) and applied on the minute. Over the entire two year run of S5, this correction factor did not deviate from unity by more than 5% (see P0900120). Indeed, in S5, a study was done the compute this factor faster, every second, and it was deemed unnecessary (I think this study was posted on Myungkee Sung's personal webpage or on a S5 Review wiki page or something, I'm not gunna bother finding it. #trustme #doctor). So, in aLIGO, where we believe the optical gain is *more* stable, we'll chose an averaging time of 100 [sec] for now.