atparamgroup

 PARAMETER GROUP in AT is a general way
 to define a functional relationship between a single
 scalar (control) paramer and mulltiple
 (dependent) paramters in the accelerator lattice.

 Examples:
 1. Simultaneously varying the strength of all 
    quadrupole magnets in the same family
 2. Moving a magnet longitudinally. This requires 
    changing the lengh of the drift spaces before and 
    after the element while constrining the total length.
 3. Setting the R1, R2, T1 and  T2 field for misaligned magnets.
    All elements of these matrixes are parametrized with  
    three angles and two displacemets.

 To use Parameter Group - first define a 
 MATLAB structure array that describes it.
 Each element in this structure arraay for each of the
 dependent paramanters
 
 This structure must have the following fields:
   ElemIndex  - Index of an element in the lattice
   FieldName  - Name of the field to be modified
   Function   - MATLAB inline objct the defines the
                functional relationship with
                the control parameter
   FieldIndex - If the data in the field given by FieldName 
                is a matrix or a vector, FieldIndex specifies
                inexes of elements to be varied
   SavedValue - saved values that can be restored with RESTOREPARAMGROUP
   Args       - Cell array of aditional arguments to be passed 
                to the function

 After the parameter group structure is defined
 it is used as an argument to AT function SETPARAMGROUP:
 NEWRING = setparamgroup(RING,PARAMGROUPSTRUCT,PARAMVALUE)

0001 % PARAMETER GROUP in AT is a general way
0002 % to define a functional relationship between a single
0003 % scalar (control) paramer and mulltiple
0004 % (dependent) paramters in the accelerator lattice.
0005 %
0006 % Examples:
0007 % 1. Simultaneously varying the strength of all
0008 %    quadrupole magnets in the same family
0009 % 2. Moving a magnet longitudinally. This requires
0010 %    changing the lengh of the drift spaces before and
0011 %    after the element while constrining the total length.
0012 % 3. Setting the R1, R2, T1 and  T2 field for misaligned magnets.
0013 %    All elements of these matrixes are parametrized with
0014 %    three angles and two displacemets.
0015 %
0016 % To use Parameter Group - first define a
0017 % MATLAB structure array that describes it.
0018 % Each element in this structure arraay for each of the
0019 % dependent paramanters
0020 %
0021 % This structure must have the following fields:
0022 %   ElemIndex  - Index of an element in the lattice
0023 %   FieldName  - Name of the field to be modified
0024 %   Function   - MATLAB inline objct the defines the
0025 %                functional relationship with
0026 %                the control parameter
0027 %   FieldIndex - If the data in the field given by FieldName
0028 %                is a matrix or a vector, FieldIndex specifies
0029 %                inexes of elements to be varied
0030 %   SavedValue - saved values that can be restored with RESTOREPARAMGROUP
0031 %   Args       - Cell array of aditional arguments to be passed
0032 %                to the function
0033 %
0034 % After the parameter group structure is defined
0035 % it is used as an argument to AT function SETPARAMGROUP:
0036 % NEWRING = setparamgroup(RING,PARAMGROUPSTRUCT,PARAMVALUE)
0037 
0038 % Example 1
0039 clear all
0040 spear2;
0041 QFI = findcells(THERING,'FamName','QF');
0042 InitialValue = THERING{QFI(1)}.K;
0043 
0044 % Create parameter group structure P
0045 P = struct('ElemIndex',num2cell(QFI),'FieldName','K',...
0046     'Function',inline('x'));
0047 % In this case the field 'K' in quadrupoles is a scalar
0048 [P.FieldIndex]=deal({1,1});
0049 [P.Args]=deal({});
0050 
0051 
0052 % Inspect P:
0053 disp(P(1))
0054 % Change the K field by 0.1%
0055 NewValue = InitialValue*1.001;
0056 THERING = setparamgroup(THERING,P,NewValue);
0057 
0058 
0059 % Example 2
0060 clear all
0061 spear2;
0062 QFI = findcells(THERING,'FamName','QF');
0063 FirstQF = QFI(1);
0064 
0065 L1 = THERING{FirstQF-1}.Length;
0066 L2 = THERING{FirstQF+1}.Length;
0067 
0068 P(1).ElemIndex=FirstQF-1;
0069 P(2).ElemIndex=FirstQF+1;
0070 
0071 P(1).Function=inline('P1+x',1);
0072 P(1).Args={L1};
0073 
0074 P(2).Function=inline('P1-x',1);
0075 P(2).Args={L2};
0076 
0077 [P.FieldName]=deal('Length');
0078 [P.FieldIndex]=deal({1,1});
0079 
0080 THERING = setparamgroup(THERING,P,0.1);