New pyDARM MCMC spits out N/A or N/V^2, old pyDARM MCMC spits out N/ct

Table of contents:

• PART I: Start with verification of the units for new pydarm by walking through the code maze.
• PART II: Then verify the old pydarm units by walking through that code maze.
• PART III: Then conclude that new pydarm spitting out [N/A] or [N/V^2] is good, but now that we know this, doc strings should be updated.

Only really super verified thus far for TST stage, but by glancing at the code construction, I can tell this is an issue for the UIM and PUM stage too. And I'm sure, in the end, @evan-goetz probably told me this 1+ years ago, and I've just forgotten. Even worse, I probably told Evan to make this change consciously. Eh well.

%%%%%%% PART I %%%%%%%%

get_processed_measurement_response -- a method of ProcessActuationMeasurement class in new pydarm measurement.py -- uses known_actuation_terms_for_measurement method from ActuationModel class of actuation.py to create correction_tst on lines 1186 and 1187.

correction_tst is then divided into the measurement on lines 1192 and 1193 to create processed_measurement_response -- the input to the MCMC.

correction_tst is a rename of the tst_response output of known_actuation_terms_for_measurement method. On lines 550 and 551 of actuation.py, multiplies the output of drivealign_to_displacement method tst_response, which has units of [TST m / iEXC ct] by the value and units of the quantity (tst_dc_gain_V2pct / tst_dc_gain_Npct()), which are core methods of methods of the ActuationModel class. That ratio (tst_dc_gain_V2pct / tst_dc_gain_Npct()) has units [V^2 / N].

Thus, tst_response output of known_actuation_terms_for_measurement method has units of [TST m / iEXC ct] * [V^2 / N].

That means that the input to the MCMC, processed_measurement_response, has units of

             | tf_meas1 |           | pcal_correction |
MCMC input = | -------- |        x  | --------------- |
             | tf_meas2 |_meas      |  correction_tst |_model

             | (DARM IN1 [ct] / iEXC [ct]) |         |        (PCAL [m] / PCAL [ct])       |
           = | --------------------------- |      x  |  ---------------------------------  | 
             | (DARM IN1 [ct] / PCAL [ct]) |_meas    |  ( TST [m] / iEXC [ct] x [V^2 / N]) |_model

              (~~ cancels ~~, ** cancels **, _ cancels _ , -- cancels --)

             | (~~DARM IN1 [ct]~~ / **iEXC [ct]**)   |         |       ( --PCAL [m]-- / _PCAL [ct]_ )         |
           = | -----------------------------------   |      x  |   ------------------------------------------ |
             | (~~DARM IN1 [ct]~~ / _PCAL [ct]_ )    |_meas    |   ( --TST [m]-- / **iEXC [ct]** x [V^2 / N]) |_model

             |  N  |  
           = | --- |
             | V^2 |_meas

where the user inputs tf_meas1 as the iEXC2DARM measurement and tf_meas2 as the PCAL2DARM measureemnt.

%%%%%%% PART II %%%%%%%%

old pyDARM actuation.py The transfer function gain is passed to the EnsembleSampler MCMC on line 1003 as the input to the MCMC.

gain is extracted from the first element's .actuation value of the nameded tuple allresults which is the output of the method process_actuation_measurements.

In line 653, the variable gain inside the process_actuation_measurements is put into the .actuation field of the allresults named tuple.

gain has (dimensionless) kappa_act divided out on line 646.

gain is defined on line 600 as the ratio of A_meas and elecTF.

On line 586, A_meas is the ratio of (in new pyDARM's parlance) tf_meas2, the iEXC2DARM measurement, and C_truth_over_1plusG_tf. C_truth_over_1plusG_tf is the product of (in new pyDARM's parlance) tf_meas1, the PCAL2DARM measurement, and pcalCorrection, the equivalent to (in new pyDARM's parlance) pcal_correction.

On line 595, elecTF is set to actProd.TSTCALexc2DARM_noNpct, and in doing so explicitly says

#here elecTF is not just the electronics transfer function, but also includes meters per Newton and drivealign if driving at CALEXC

You can already see by this variable name and corresponding comment that elecTF has "no N/ct" i.e. it has units of ( TST [m] / iEXC [ct] x [ct / N]), but following the really complicated construction of actProd.TSTCALexc2DARM_noNpct you can eventually see that it all depends on line 227 tstDriverResponse_noNpct.gain /= abs(tstDCgain) where has units of [N/ iEXC ct].

So, summing it all up for old pyDARM, that means the MCMC input has units

             |  A_meas  |           |        pcalCorrection         |
MCMC input = | -------- |        x  | ----------------------------- |
             | PCAL_tf  |_meas      | actProd.TSTCALexc2DARM_noNpct |_model

             | (DARM IN1 [ct] / iEXC [ct]) |         |        (PCAL [m] / PCAL [ct])       |
           = | --------------------------- |      x  |  ---------------------------------  | 
             | (DARM IN1 [ct] / PCAL [ct]) |_meas    |  ( TST [m] / iEXC [ct] x [ct / N])  |_model

           as before,  (~~ cancels ~~, ** cancels **, _ cancels _ , -- cancels --),


             | (~~DARM IN1 [ct]~~ / **iEXC [ct]**)   |         |       ( --PCAL [m]-- / _PCAL [ct]_ )         |
           = | -----------------------------------   |      x  |   ------------------------------------------ |
             | (~~DARM IN1 [ct]~~ / _PCAL [ct]_ )    |_meas    |   ( --TST [m]-- / **iEXC [ct]** x [ct / N]) |_model

             |  N   |  
           = | ---- |
             |  ct  |_meas

%%%%%%% PART III %%%%%%%%

SO. DOES THIS MATTER? Now that I understand it and have identified it and confirmed it -- no. And I've only glanced at the PUM and UIM, but I wouldn't be surprised of new pyDARM MCMC spits out [N/A] rather than [N/ct]. I think I like that the MCMC spits out the [N/V^2] and [N/A], since these are what we put in the parameter file, so let's keep that.

BUT

I think it's worth improving the "self" documentation on the ProcessActuationMeasurement class to actually fill out the "Returns" comments. Perhaps more specifically,

• the get_processed_measurement_response method's self-docs should definitely be updated to specify the units.
• the run_mcmc method's self-docs should definitely be updated to specify the units.