Home > atmatch > atVariableBuilder.m

atVariableBuilder

PURPOSE ^

atVarBuilder create a simple variable structure for use with atmatch

SYNOPSIS ^

function variable=atVariableBuilder(varargin)

DESCRIPTION ^

atVarBuilder   create a simple variable structure for use with atmatch

 Single variable : it corresponds to a scalar numeric value to be varied in
 the optimization process. It may be applied to several elements.It is
 represented as a scalar structure.

   var=atVariableBuilder(refpts,parameter,highlim,lowlim)
       refpts:     indices of the variable elements or logical mask
       parameter:    cell array defining the field name and indices of the
                   variable parameter
       lowlim:     minimum parameter value (default: no limit)
       highlim:    maximum parameter value (default: no limit)

       Example:    qf=atgetcells(ring,'FamName','QF');
                   var=atVariableBuilder(qf,{'PolynomB',{2}});

   var=atVariableBuilder(@func,inival,highlim,lowlim)
       func:       function building a new ring for the given variable value
                   called as new_ring=func(base_ring,variable)
       inival:     initial value of the variable
       lowlim:     minimum parameter value (default: no limit)
       highlim:    maximum parameter value (default: no limit)

       Example: var=atVariableBuilder(@(r,v) some_function(r,v,...), 0.0);

   var=atVariableBuilder(ring,location,...)
       In this syntax, the location may be specified as the family name of the
       variable elements

       Example: var=atVariableBuilder(ring,'QF',{'PolynomB',{2}});

 Multiple variables: if location,parameter,lowlim and highlim are cell arrays
 with the same length or with length 1, atVariableBuilder will build a
 structure array of variables. Examples:

   vars=atVariableBuilder(ring,{'QD','SF'},{{'PolynomB',{1,2}},{'PolynomB',{1,3}}});

   qf=atgetcells(ring,'FamName','QF');
   qd=atgetcells(ring,'FamName','QD');
   vars=atVariableBuilder({qf,qd},{{'PolynomB',{1,2}}});

   vars=atVariableBuilder({qf,@buildring},{{'PolynomB',{1,2}},0.0})

 More sophisticated variables, can be defined using directly the variable
 structure. The general variable definition is:

 ex: Variab=struct('Indx',{findcells(RING,'FamName','QFM'),...
                            k1start(1)},...
                   'LowLim',{[],[]},...
                   'HighLim',{[],[]},...
                   'Parameter',{{'PolynomB',{1,2}},...
                                {'FUN',...
                           @(RING,K1Val)VaryQuadFam(RING,K1Val,'QDM')}}...
                  );

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function variable=atVariableBuilder(varargin)
0002 %atVarBuilder   create a simple variable structure for use with atmatch
0003 %
0004 % Single variable : it corresponds to a scalar numeric value to be varied in
0005 % the optimization process. It may be applied to several elements.It is
0006 % represented as a scalar structure.
0007 %
0008 %   var=atVariableBuilder(refpts,parameter,highlim,lowlim)
0009 %       refpts:     indices of the variable elements or logical mask
0010 %       parameter:    cell array defining the field name and indices of the
0011 %                   variable parameter
0012 %       lowlim:     minimum parameter value (default: no limit)
0013 %       highlim:    maximum parameter value (default: no limit)
0014 %
0015 %       Example:    qf=atgetcells(ring,'FamName','QF');
0016 %                   var=atVariableBuilder(qf,{'PolynomB',{2}});
0017 %
0018 %   var=atVariableBuilder(@func,inival,highlim,lowlim)
0019 %       func:       function building a new ring for the given variable value
0020 %                   called as new_ring=func(base_ring,variable)
0021 %       inival:     initial value of the variable
0022 %       lowlim:     minimum parameter value (default: no limit)
0023 %       highlim:    maximum parameter value (default: no limit)
0024 %
0025 %       Example: var=atVariableBuilder(@(r,v) some_function(r,v,...), 0.0);
0026 %
0027 %   var=atVariableBuilder(ring,location,...)
0028 %       In this syntax, the location may be specified as the family name of the
0029 %       variable elements
0030 %
0031 %       Example: var=atVariableBuilder(ring,'QF',{'PolynomB',{2}});
0032 %
0033 % Multiple variables: if location,parameter,lowlim and highlim are cell arrays
0034 % with the same length or with length 1, atVariableBuilder will build a
0035 % structure array of variables. Examples:
0036 %
0037 %   vars=atVariableBuilder(ring,{'QD','SF'},{{'PolynomB',{1,2}},{'PolynomB',{1,3}}});
0038 %
0039 %   qf=atgetcells(ring,'FamName','QF');
0040 %   qd=atgetcells(ring,'FamName','QD');
0041 %   vars=atVariableBuilder({qf,qd},{{'PolynomB',{1,2}}});
0042 %
0043 %   vars=atVariableBuilder({qf,@buildring},{{'PolynomB',{1,2}},0.0})
0044 %
0045 % More sophisticated variables, can be defined using directly the variable
0046 % structure. The general variable definition is:
0047 %
0048 % ex: Variab=struct('Indx',{findcells(RING,'FamName','QFM'),...
0049 %                            k1start(1)},...
0050 %                   'LowLim',{[],[]},...
0051 %                   'HighLim',{[],[]},...
0052 %                   'Parameter',{{'PolynomB',{1,2}},...
0053 %                                {'FUN',...
0054 %                           @(RING,K1Val)VaryQuadFam(RING,K1Val,'QDM')}}...
0055 %                  );
0056 %
0057 
0058 % history of changes
0059 % created 21-03-2013
0060 % update 29-03-2013 create many variables with the same parameter field.
0061 % update 30-03-2013 create function variables.
0062 % update 13-11-2015 reorganize function and help
0063 
0064 if iscell(varargin{1}) && isfield(varargin{1}{1},'PassMethod')
0065     variable=atVariableBuilder(getid(varargin{1},varargin{2}),varargin{3:end});
0066 elseif iscell(varargin{1})
0067     vals={{[]},{{}},{[]},{[]}};
0068     vals(1:nargin)=varargin;
0069     expand=1:max(cellfun(@length,varargin));
0070     location(expand)=cellfun(@tonum,vals{1},'UniformOutput',false);
0071     parameters(expand)=vals{2};
0072     lowl(expand)=vals{3};
0073     highl(expand)=vals{4};
0074     variable=struct('Indx',location,...
0075         'Parameter',parameters,...
0076         'LowLim',lowl,...
0077         'HighLim',highl...
0078         );
0079 else
0080     vals=cellfun(@(i) {i}, varargin, 'UniformOutput',false);
0081     variable=atVariableBuilder(vals{:});
0082 end
0083 
0084     function id=getid(ring,name)
0085         if iscell(name)
0086             id=cellfun(@(nm) getid(ring,nm), name, 'UniformOutput',false);
0087         elseif ischar(name)
0088             id=atgetcells(ring,'FamName',name);
0089         else
0090             id=name;
0091         end
0092     end
0093     function vnum=tonum(vnum)
0094         if islogical(vnum)
0095             vnum=find(vnum);
0096         end
0097     end
0098 
0099 end

Generated on Thu 24-Aug-2017 18:47:33 by m2html © 2005