steptune

STEPTUNE - Step the tune
  [DelQuad, QuadFamily] = steptune(DeltaTune, TuneResponseMatrix);

  Step change in storage ring tune using the default tune correctors (findmemberof('Tune Corrector'))

0001 function [DelQuad, ActuatorFamily] = steptune(varargin)
0002 %STEPTUNE - Step the tune
0003 %  [DelQuad, QuadFamily] = steptune(DeltaTune, TuneResponseMatrix);
0004 %
0005 %  Step change in storage ring tune using the default tune correctors (findmemberof('Tune Corrector'))
0006 
0007 %  INPUTS
0008 %  1.             | Change in Horizontal Tune |
0009 %     DeltaTune = |                           |
0010 %                 | Change in Vertical Tune   |
0011 %  2. TuneResponseMatrix - Tune response matrix {Default: findmemberof('Tune Corrector')}
0012 %  3. ActuatorFamily -  Quadrupole to vary, ex {'Q7', 'Q9'} {Default: findmemberof('Tune Corrector')}
0013 %  4. Optional override of the units:
0014 %     'Physics'  - Use physics  units
0015 %     'Hardware' - Use hardware units
0016 %  5. Optional override of the mode:
0017 %     'Online'    - Set/Get data online
0018 %     'Model'     - Set/Get data on the simulated accelerator using AT
0019 %     'Simulator' - Set/Get data on the simulated accelerator using AT
0020 %     'Manual'    - Set/Get data manually
0021 %
0022 %
0023 %  OUTPUTS
0024 %  1. DelQuad
0025 %  2. QuadFamily - Families used (cell array)
0026 %
0027 %  ALGORITHM
0028 %     SVD method
0029 %  DelQuad = inv(TuneResponseMatrix) * DeltaTune
0030 
0031 %
0032 %  Written by Gregory J. Portmann
0033 %  Modified by Laurent S. Nadolski
0034 %   06/01/06 - Introduction of ActuatorFamily as a input
0035 
0036 % Initialize
0037 
0038 UnitsFlag = {}; 
0039 ModeFlag = {};
0040 for i = length(varargin):-1:1
0041     if strcmpi(varargin{i},'physics')
0042         UnitsFlag = varargin(i);
0043         varargin(i) = [];
0044     elseif strcmpi(varargin{i},'hardware')
0045         UnitsFlag = varargin(i);
0046         varargin(i) = [];
0047     elseif strcmpi(varargin{i},'Simulator') | strcmpi(varargin{i},'Model')
0048         ModeFlag = varargin(i);
0049         varargin(i) = [];
0050     elseif strcmpi(varargin{i},'online')
0051         ModeFlag = varargin(i);
0052         varargin(i) = [];
0053     elseif strcmpi(varargin{i},'manual')
0054         ModeFlag = varargin(i);
0055         varargin(i) = [];
0056     end        
0057 end
0058 
0059 if length(varargin) >= 1
0060     DeltaTune = varargin{1};
0061 else
0062     DeltaTune = [];    
0063 end
0064 if isempty(DeltaTune)
0065     answer = inputdlg({'Change the horizontal tune by', 'Change the vertical tune by'},'STEPTUNE',1,{'0','0'});
0066     if isempty(answer)
0067         return
0068     end
0069     DeltaTune(1,1) = str2num(answer{1});
0070     DeltaTune(2,1) = str2num(answer{2});
0071 end
0072 
0073 DeltaTune = DeltaTune(:);
0074 if size(DeltaTune,1) ~= 2
0075     error('Input must be a 2x1 column vector.');
0076 end
0077 if DeltaTune(1)==0 && DeltaTune(2)==0
0078     return
0079 end
0080 
0081 if length(varargin) >= 2
0082     TuneResponseMatrix = varargin{2};
0083 else
0084     TuneResponseMatrix = [];    
0085 end
0086 if isempty(TuneResponseMatrix)
0087     TuneResponseMatrix = gettuneresp(UnitsFlag{:});
0088 end
0089 if isempty(TuneResponseMatrix)
0090     error('The tune response matrix must be an input or available in one of the default response matrix files.');
0091 end
0092 
0093 % User ActuatorFamily
0094 if length(varargin) >= 3
0095     ActuatorFamily = varargin{3};
0096 else
0097     ActuatorFamily = findmemberof('Tune Corrector')';
0098     if isempty(ActuatorFamily)
0099         ActuatorFamily = {'QF','QD'};
0100     end
0101 end
0102 
0103 % It's probably wise to check the .Units fields
0104 
0105 % 1. SVD Tune Correction
0106 % Decompose the tune response matrix:
0107 [U, S, V] = svd(TuneResponseMatrix, 'econ');
0108 % TuneResponseMatrix = U*S*V'
0109 %
0110 % The V matrix columns are the singular vectors in the quadrupole magnet space
0111 % The U matrix columns are the singular vectors in the TUNE space
0112 % U'*U=I and V*V'=I
0113 %
0114 % TUNECoef is the projection onto the columns of TuneResponseMatrix*V(:,Ivec) (same space as spanned by U)
0115 % Sometimes it's interesting to look at the size of these coefficients with singular value number.
0116 TUNECoef = diag(diag(S).^(-1)) * U' * DeltaTune;
0117 %
0118 % Convert the vector TUNECoef back to coefficents of TuneResponseMatrix
0119 DelQuad = V * TUNECoef;
0120 
0121 
0122 % 2. Square matrix solution
0123 % DelQuad = inv(TuneResponseMatrix) * DeltaTune;
0124 
0125 
0126 % 3. Least squares solution
0127 % DelQuad = inv(TuneResponseMatrix'*TuneResponseMatrix)*TuneResponseMatrix' * DeltaTune;
0128 %
0129 % see Matlab help for "Matrices and Linear Algebra" to see what this does
0130 % If overdetermined, then "\" is least squares
0131 %
0132 % If underdetermined (like more than 2 quadrupole families), then only the
0133 % columns with the 2 biggest norms will be keep.  The rest of the quadupole
0134 % families with have zero effect.  Hence, constraints would have to be added for
0135 % this method to work.
0136 % DelQuad = TuneResponseMatrix \ DeltaTune;
0137 
0138 
0139 
0140 % Make the setpoint change
0141 SP = getsp(ActuatorFamily, UnitsFlag{:}, ModeFlag{:});
0142 
0143 if iscell(SP)
0144     for i = 1:length(SP)
0145         SP{i} = SP{i} + DelQuad(i);
0146     end
0147 else
0148     SP = SP + DelQuad;
0149 end
0150 
0151 setsp(ActuatorFamily, SP, UnitsFlag{:}, ModeFlag{:});
0152