J. Kissel, J. Betzwieser
ECR E2300125
IIET Ticket 27801
WP 11166

Executive Summary: Based on the *very* encouraging results from last week's install of the prototype of real-time monitoring of the systematic error lines that we inherited from LLO (see LHO:68961 for code changes, and the success story a mere 3 days later in LHO:69157), we crave finalizing this prototype infrastructure by incorporating standard stuff that other time-dependent calculations are doing, and re-casting the final answers into units that we regularly use elsewhere. In addition, we're also making some changes to the demodulation parameters given the systems-level compromises we discovered on at the end of last week LHO:69175, namely, changing undocumented hard-coded values into user-definable EPICs records.

I've compiled the model with the below detailed changes, so the model is ready for build, install, and restart tomorrow.

This will result in removal of 28 EPICs records, in addition to the addition of 164 EPICs records.

This aLOG covers the changes to the front end model library parts that enacts the changes to the following library parts:
     /opt/rtcds/userapps/release/cal/common/models/
          CAL_LINE_MONITOR_MASTER.mdl
          CAL_CS_MASTER.mdl
as well as the following c-code chunk
     /opt/rtcds/userapps/release/cds/common/src/
          RING_BUFFER.c
These common parts have had their changes committed to the above mentioned location in the userapps SVN repo.

(1) In order to support LLO's independent, front-end subtraction of calibration lines, he'd installed "gated running median" (GRM) infrastructure on the live calculations of (DELTAL / PCAL) transfer functions and (DELTAL / SUS) calculations on the output of those ratios that come directly from the DEMOD I and Q outputs. The GRM process is "just" a copy and paste from what we've been using for years to smooth out the answers for the the time-dependent correction factors (TDCFs). Indeed, the front-end GRM process is itself a copy of the gst-lal_calibration, "GDS" pipeline's function that's used in production of TDCF-corrected GDS-CALIB_STRAIN.

The I and Q outputs are good enough for what Joe needs to subtract them out of DELTAL. However, in order to produce a true systematic error, the DELTAL / PCAL transfer function needs corrected for flaws in CALCS and then a conversion into magnitude and phase systematic error transfer functions for ease of interpretation. But -- the trends of the answer from this prototype of the systematic error transfer functions are quite noisy (2023-04-28_SYSERROR_LINES_FirstResults_30minutetrend.png from LHO:69157). 

As such, we've now moved the gated running median down-stream of the simple ratio of I & Q demod outputs, such that *both* the subtraction output *and* the systematic error output receive the noise cleaning benefits of the standard GRM process.

(2) For better or worse, the "gated running median" is a bubble-gum and duct tape with super glue process for the DEMOD I and Q outputs:
    (A low-passed) The DEMOD I and Q banks themselves, have low-passes in them. As discussed in LHO:69175, these low passes correspond to "FFT lengths" if one were doing the analysis in the frequency domain. This has been traditionally a 0.1 Hz corner frequency low pass to correspond to a "10 second FFT."
    (B buffered) In the first stage of the GRM process, this low-passed I and Q data is held in a ring buffer for 10 seconds (and in the front-end this duration *used* to be a hard-coded input of RING_BUFFER.c as 163840 samples, i.e. model_sampling_frequency * buffer_size_sec = 16384 Hz * 10 sec = 163840.)
    (C gated) The output of RING_BUFFER.c, is then feed into a gating function, that either passes the current values through, or holds on the previous 10 second's value based on the last cycle's median. This reduces the sensitivity to glitches in the current 10 seconds.
    (D down-sampled and medianed) The current cycle's low-passed, buffered, gated output is then passed into a median function, which has an "array size" parameter, and a "stride" parameter. These parameters were hard-coded in the front-end to be a stride, (or a sample rate) of 1/16 seconds = 0.0625 seconds -- essentially down sampling the data, with an array size, or it's own collection of 2049 samples, i.e. 16384 / 8 -- 2048 ... so it calculates the median of 8 seconds of 16 Hz data.
    (E averaged) The current cycle's low-passed, buffered, gated, medianed output is then fed into an averaging buffer, with the same stride (sample rate) of 0.0625 sec, and it's own buffer of 160 samples i.e. 
    (F up-sampled) Finally the current cycle's low-passed, buffered, gated, medianed, averaged 16 Hz signal is then uses a spline algorithm to upsample the data back to 16384 Hz. Thus *it* has a hardcoded parameter that serves as the upsampling ratio of 16384 Hz / 16 Hz = 1024.
It's gross.

Anyways, I walk through all this to illuminate that -- for the DELTA / PCAL and DELTA / SUS transfer functions, which are now mapped through the GRM process (see (1) above) -- I've converted all of these simulink hard-coded numbers that are all inter-related to the choice of FFT length into user-definable EPICs records. This way, if we every decide to make a *different* choice of FFT length, then we can change all of the inter-related parameters at the same time, in a hopefully intelligent way without an ECR to change the front-end model.

Importantly, all the front-end computed TDCF values are the same, and are still using all the old hard-coded values. This is *just* for the newly commissioned DELTA/PCAL and DELTAL/SUS transfer functions that are now newly passed through their own GRM process.

(3) Here's an easy one -- for the DELTAL / PCAL transfer function, which had been converted from the TF's real and imaginary parts to magnitude and phase -- I've converted added an additional readback that converts the phase from radians as it was to degrees.

(4) It's important that the systematic error monitor has an uncertainty associated with it. To date, we've been using *only* a coherence based uncertainty, the usual Bendat and Piersol sqrt( (1 - coh) / (2 * navg * coh) ). This covers the *statistical* uncertainty of this transfer function nicely, but it does not reflect the fixed uncertainty in the model of the amplitude of PCAL displacement -- typically between 0.25 - 0.5%. So, if one of the PCAL lines has particularly loud signal-to-noise ratio, the measurement uncertainty can be quite low, lower than the uncertainty in the model of PCAL displacement. 

As such, I've added an additional EPICs record where one can install the fixed uncertainty of the PCAL amplitude, and that uncertainty will be added in quadrature to the coherence-based measurement uncertainty.

(5) Finally, while we're still exploring what the best options are for the "FFT length," i.e. the frequency of the low-pass filter of the I & Q demods, we want to make sure that there's no fundamental code limit to choosing a long FFT -- say 100 seconds. As such, we've modified 
     /opt/rtcds/userapps/release/cds/common/src/
          RING_BUFFER.c
, which was formerly limited to have a maximum buffer (a hard-coded definition in the c-code itself) of 20 seconds (16384 Hz * 20 seconds = 327680 samples). After some verification of of whether the front-end process could handle this increased limit (see TST:15369), we've increased this limit to 100 seconds (i.e. 16384 Hz * 100 seconds = 163840 samples).

I'll post screenshots of the changes in a series of comments below.