1 Preliminary LoopTickle documentation
   2 
   3 
   4 Disclaimer:
   5 LoopTickle is still work in progress, so there are still some unused files
   6 included in the distribution.
   7 
   8 == LoopTickle description ==
   9 LoopTickle is an add-on to optickle that allows closing control loops
  10 and provides a series of plotting functions for things like transfer
  11 functions and noise budgets at various ports.
  12 
  13 Looptickle needs to get the interferometer AC response matrix sigAC
  14 from optickle. The LoopTickle configuration file then defines
  15 control filters and correction pathes as well as several displacement
  16 and sensing noises. The control filters and correction pathes are
  17 converted into one control matrix H, such that the whole interferometer
  18 can be described by the diagram below (all arrows are vectors).
  19 
  20                    <---- H <------------
  21                   |                    |
  22                   |-                   |
  23 displacement --->  ---> sigAC ---> ---> ---> sensing ports
  24 signals/noises +                 +^
  25                                   |
  26                                   |
  27                              sensing noises
  28 
  29 The various high level functions described below use this schematic
  30 to calculate transfer function and noise contributions at different ports.
  31 --------
  32 
  33 
  34 Example
  35 
  36 demoAdvLIGO.m is an example of how to use LoopTickle:
  37 
  38 % add appropriate pathes
  39 addpath('./Optickle');
  40 addpath('./lib/Filter');
  41 addpath('./lib/Plot');
  42 addpath('../bench61');
  43 
  44 % define frequency vector
  45 Nsweep=201;
  46 f = logspace(0, 4, Nsweep)';
  47 
  48 % set up Optickle
  49 opt=optAdLIGO_9_45NS_lofi12cm;
  50 % calculate optickle fields
  51 [sigDC, sigAC, mechTF, fDC, fAC] = compute(opt, [], f);
  52 
  53 % set up LoopTickle
  54 loopt=looptickle(opt,f,fDC,'looptAdvLIGO');
  55 
  56 % load some nice definitions for plotting
  57 startup
  58 
  59 % LoopTickle is all set up now. The following functions can be called
  60 % in any desired order.
  61     openLoopGain(loopt,sigAC,loopt.LOOPNAMES);
  62     noiseBudget(loopt,sigAC,loopt.LOOPNAMES);
  63     lengthCoupling(loopt,sigAC,loopt.LOOPNAMES,loopt.LOOPNAMES,0,1);
  64     closedLoopGain(loopt,sigAC,loopt.LOOPNAMES);
  65     getSense(loopt,sigAC,loopt.LOOPNAMES);
  66     getResponse(loopt,sigAC,loopt.LOOPNAMES);
  67 
  68 --------
  69 
  70 === Description of LoopTickle configuration file ===
  71 looptAdvLIGO.m is an example configuration file.
  72 The configuration file needs to specify the following entries of the loopt
  73 structure (as of May 9):
  74 
  75   loopt.LOOPNAMES  : Cell list of loop names (strings)
  76   loopt.SENSE      : Cell list of optickle sensing ports numbers. Multiple
  77                      sensing ports possible, specified as row vector.
  78   loopt.CTRLINMTRX : Cell list of input matrix (scalar if only one port,
  79                      otherwise row vector)
  80   loopt.DRIVE      : Cell list of optickle actuation optic numbers
  81                      (column vector).
  82   loopt.CTRLOUTMTRX: Cell list of actuation output matrix (column vector).
  83                      Note that this also defines the degree of freedom,
  84                      i.e. for DARM=Lx-Ly we have [0.5;-0.5], but for
  85                      CARM=(Lx+Ly)/2 we have [1;1]. For the same reason
  86                      correction pathes with flat response should not be
  87                      included here.
  88   loopt.CORR       : Cell list of a vector of correction path structs.
  89                      Each correction path struct has the following fields:
  90                        filter.p   : list of filter poles
  91                        filter.z   : list of filter zeros
  92                        filter.k   : filter gain
  93                                     Note: The filter definition follows the
  94                                     more reasonable convention use e.g. in
  95                                     Matt's filter toolbox, iLIGO or FOTON, 
  96                                     (NOT the MATLAB definition with
  97                                     negative angular frequencies.)
  98                        DRIVE      : optickle actuation optic numbers
  99                        CORROUTMTRX: actuation output matrix
 100   loopt.CTRLFLTER  : Cell list of control filter structs each struct has
 101                      the following fields (see also note under loopt.CORR):
 102                        p : list of filter poles
 103                        z : list of filter zeros
 104                        k : filter gain
 105   loopt.plot.watt.axis:  Cell list of lower and upper limit on
 106                          y-axis for plotting [Watts]
 107   loopt.plot.meter.axis: Cell list of lower and upper limit on
 108                          y-axis for plotting [meters]
 109 
 110 --------
 111 
 112 === High level LoopTickle functions description ===
 113 function [varargout]=openLoopGain(loopt,M,loopnames,varargin)
 114 %
 115 % calculates olg for degree of freedoms specified in loopnames,
 116 % with all other loops closed (i.e. a new control matrix H' that does not
 117 % include the loop of interest is calculated and used for closing the
 118 % other loops.)
 119 % Examples:
 120 %   openLoopGain(loopt,sigAC,{'CARM','DARM'},<plotting arguments>)
 121 %     --> plot CARM and DARM OLG
 122 %   olg=openLoopGain(loopt,sigAC,'CARM')
 123 %     --> return CARM OLG
 124 %   [olg,sensing]=openLoopGain(loopt,sigAC,'CARM')
 125 %     --> return CARM OLG and plant-only TF (i.e. OLG w/o control filter)
 126 
 127 function [varargout]=closedLoopGain(loopt,M,loopnames,varargin)
 128 %
 129 % calculates clg for one degree of freedom, with all other loops closed
 130 % Examples:
 131 %   closedLoopGain(loopt,sigAC,{'CARM','SRCL'},<plotting arguments>)
 132 %     --> plot CARM & SRCL CLG
 133 %   clg=closedLoopGain(loopt,sigAC,'CARM')
 134 %     --> return CARM CLG
 135 
 136 function [varargout]=getSense(loopt,M,loopnames,varargin)
 137 %
 138 % calculates the sensing function in Watt/m for
 139 % the length control loop error signal
 140 %
 141 % Examples:
 142 %   getSense(loopt,sigAC,{'CARM','DARM'},<plotting arguments>)
 143 %     --> plot CARM & DARM sensing function
 144 %   sensing=getSense(loopt,sigAC,'CARM')
 145 %     --> return CARM sensing function
 146 
 147 function [varargout]=getResponse(loopt,M,loopnames,varargin)
 148 %
 149 % calculates the response function in m/Watt for
 150 % the length control loop error signal
 151 %
 152 % Examples:
 153 %   getResponse(loopt,sigAC,{'CARM','DARM'},<plotting arguments>)
 154 %     --> plot CARM & DARM response
 155 %   resp=getResponse(loopt,sigAC,'CARM')
 156 %     --> return CARM response
 157 
 158 function [varargout]=lengthCoupling(loopt,M,fromLoops,toLoops,closeFlag,calFlag,varargin)
 159 %
 160 % calculates the LSC matrix x-couplings from the 'fromLoops' to the
 161 % 'toLoops'
 162 % closeFlag specifies whether the control loops are closed or not.
 163 % calFlag specifies whether the coupling is calibrated in
 164 %  meters/meter (true) or Watts/meter (false)
 165 %
 166 % Examples:
 167 %   lengthCoupling(loopt,sigAC,{'PRCL','MICH'},'DARM',0,1,<plotting arguments>)
 168 %     --> plot coupling from 'PRCL' and 'MICH' to 'DARM'
 169 %   coupl=lengthCoupling(loopt,sigAC,{'PRCL','MICH'},'DARM',0,1)
 170 %     --> return coupling from 'PRCL' and 'MICH' to 'DARM'
 171 
 172 function noiseBudget(loopt,M,loopnames,calFlag,varargin)
 173 %
 174 % plots a noise budget for port 'loopnames' that includes
 175 % all previously added noise sources
 176 % calFlag=0: calibrated in Watts
 177 % calFlag=1: calibrated in meters
 178 % calFlag=2: calibrated in strain (actually just divides meters by 4000,
 179 %            i.e. is only meaningful for DARM.)
 180 %
 181 
 182 function loopt=addSensingNoise(loopt,name,x,SENSMTRX,PORTS,COHERENT)
 183 % adds a sensing noise to the loopticle model
 184 %
 185 % Example
 186 %   loopt=addSensingNoise(loopt,'MyNewNoise',x,[1],[nDARM])
 187 %   loopt=addSensingNoise(loopt,'MyNewNoise',x,'DARM')
 188 %     x is in Watts/rtHz
 189 %
 190 %     COHERENT specifies whether the noise from the different inputs is
 191 %     summed coherently or incoherently. Default is
 192 %     coherently, i.e. true, making SENSMTRX a true inputput matrix.
 193 %     Note that contributions from different addSensingNoise calls are
 194 %     ALLWAYS summed incoherently
 195 
 196 function loopt=addDisplacementNoise(loopt,name,x,ACTMTRX,OPTICS,COHERENT)
 197 % adds a displacement noise to the loopticle model
 198 %
 199 % Example
 200 %   loopt=addDisplacementNoise(loopt,'MyNewNoise',x,[1;1],[nEX;nEY])
 201 %     x is in meter/rtHz
 202 %
 203 %     COHERENT specifies whether the noise from the optics specified in
 204 %     ACTMTRX and OPTICS is summed coherently or incoherently. Default is
 205 %     coherently, i.e. true, making ACTMTRX a true output matrix.
 206 %     Note that contributions from different addDisplacementNoise calls
 207 %     are ALLWAYS summed incoherently.
 208 
 209 function loopt=importBench6(loopt,opt,ifo,src)
 210 %
 211 %  Imports the displacement noises from bench
 212 %  (only displacement noises, NOT IFO parameter are loaded)
 213 % note that bench works in strain^2, while LoopTickle works in meters
 214 % This function is currently called by default in looptickle.m.
 215 
 216 function loopt=addNaiveShot(loopt,opt,fDC,loopname)
 217 % adds naive shot noise (no quantum effects) to the loopticle model
 218 %
 219 % Example
 220 %   loopt=addNaiveShot(loopt,opt,'DARM')
 221 %
 222 % This function is currently called by default for all control loops in
 223 % looptickle.m.
 224 --------