function optout=imfil_optset(varargin)
% IMFIL_OPTSET
%
% Set the options in imfil.
% C. T. Kelley, Nov 11, 2007
%
% OPTIONS = IMFIL_OPTSET('name1',val1,'name2',val2, ... );
%           creates the options structure with the options named
%           in the list set to something other than the defaults.
%
% OPTOUT = IMFIL_OPTSET('name1',val1,'name2',val2, ... , OPTIN);
%           modifies the structure OPTIN and creates a new structure
%           OPTOUT.
%
% And now for the lists. The details of the options, the motiviation
% for the defaults, and suggestions for their use live in the manual.
%
% Scalar Options:
%
% armijo_reduction: Reduction factor for the linesearch. The default is .5.
%
% fscale: A ``typical value of f'', used to improve the quality of
%         the difference gradient. The default is
%         1.2*| f(x_0) |.
%
% function_error: Set this to an estimate for the absolute error in f
%         if you have one. Ignore this option if you do have no idea
%         how accurate your function evaluation is. The optimization
%         loop will terminate when the maximum absolute difference
%         of function values on the stencil is < function_error. 
%         The default is -1, which means that function_error has no
%         effect.
%
% least_squares: imfil does the smart thing if you're solving a nonlinear
%         overdetermined (m >=n) least squares problem. Set 
%         least_squares = 1 and let your function return the vector residual
%         in R^m. imfil will compute f'*f/2 as part of the optimization.
%
% maxit:  The quasi-Newton inner iteration is limited to maxit*n iterations
%         for each scale. The default is 50.
%
% maxitarm: The line search will reduce the step by at most maxitarm times
%           before declaring failure. The default is 3. The line search is
%           on a short leash for good reason. If you don't find something
%           useful after three reductions, you're not likely to do better
%           with more effort. 
%
% noise_aware: Set this to one if your function can return as estimate 
%           of the norm of the noise. The call is
%           [fout,ifail,icount,noise_val]=f(x).
%           In this case imfil will declare stencil failure if 
%           the difference between the max and min values on the
%           stencil is < noise_val.
%           The default is 0 (not noise_aware).
%           You can set stencil_aware=1 and noise_aware=1 at the same time.
%
%           noise_val is not the same as function_error. You set noise_val
%           via the call to f as f's best estimate of the error. noise_val
%           is used as a test to reject the stencil and reduce the scale.
%           function_error is used to terminate the optimization.
%
% parallel: Set this to one if f can accept multiple input vectors and
%           exploit parallelism. The output should be vectors of
%           [fout,ifail,icount], with a length equal to the number of
%           input variables. When imfil computes the stencil gradient
%           f will get all the directions at once. It is then your job
%           to manage the parallel coputation for optimal load balancing.
%
%           You may also want to parallelize the line search and enable
%           additional exploration of the stencil directions. To do this
%           set parallel to the number of processors you want to committ
%           to this part of the optimization. Read the manual to see how
%           this rapidly changing part of the code works. 
%
% quasi: Your choices for quasi-Newton acceleration are none (0),
%        BFGS (1), or SR-1 (2). The default as of today is BFGS, but
%        I may change that as I have done in the past.
%
% random_stencil: Set this to k > 0 and k random unit vectors will be
%        added to the stencil before each call to the simplex gradient.
%        The default is 0.
%
% scalestart and scaledepth: The range of scales is 2^-scalestart
%        to 2^-scaledepth. The defaults are scalestart=1, scaledepth=7.
%
% scale_aware: Setting this to 1 tells imfil that f can do something
%              smart if it knows the scale. The call then becomes
%              [fout,ifail,icount]=f(x,h)
%              The scale is the second input argument. 
%              The default is 0 (not scale-aware)
%              You can set stencil_aware=1 and noise_aware=1 at the same time.
%
% stencil: imfil has three built-in stencils, with room for you to 
%          create you own in the matrix options. Setting stencil
%          lets you chose the centered difference stencil (0), the
%          forward difference stencil (1), and the positive basis
%          stencil (2). The default is the centered difference stencil
%          (stencil = 0). Choosing the forward difference stencil will
%          cause a warning, and that option will go away in a future 
%          version.
%
% target: You may have either a good lower estimate of the optimal
%         value of f, or an idea about when the optimization has done
%         enough. If you do, set target to that value and the optimization
%         will stop when f < target.
%
%
% Matrix options
%
% vstencil: You may replace the built-in stencils with your own custom
%           design. If VS is your N x M list of M directions, then
%
%           optout=imfil_optset('vstencil',VS,optin)
%
%           will get it done.   
% 
nv=length(varargin);
%
% Even number of arguments means you're setting options from scratch.
%
if 2*floor(.5*nv) == nv
   optin = set_defaults;
   mv=nv/2;
else
%
% Odd number of arguments means you're changing options.
%
   mv=(nv-1)/2;
   optin=varargin{nv};
end
optout=optin;
for i=1:mv
   optout=imfil_optset_base(varargin{2*i-1},varargin{2*i},optout);
end

function optout=imfil_optset_base(str,val,optin)
optout=set_defaults;
if nargin == 3
   optout=optin;
end
if nargin > 0
str=lower(str);
parms=fieldnames(optout);
n=length(parms);
okflag=0;
%
% Test for verbal shortcuts and do the right thing.
%
[okflag,optout]=verbal_shortcut(str,val,optin);
%
% Update options.
%
for p=1:n
   if strcmp(str,parms(p))
       optout=setfield(optout,str,val);
       okflag=1;
   end
end
if okflag == 0
   disp('error in imfil_optset');
   disp([str,' is not a known parameter name']);
end
end


function imfil_defaults = set_defaults
%
% Default values
%
armijo_reduction = .5; % Step size reduction factor for Armijo rule.
%
fscale = -1.2;         % Scale function by 1.2 times abs(f(x_0)).
%
function_error = -1;   % Do not terminate on small variation of f.
%
least_squares = 0;     % Is this a nonlinear least squares problem?
%
maxit = 50;            % At most maxit*n quasi-Newton iterations/scale,
%
maxitarm = 3;          % Limit on number of step length reductions.
%
noise_aware = 0;       % Can your function estimate the noise? Default = no.
%
parallel = 0;          % Serial is the default.
%
quasi=1;               % BFGS
%
random_stencil = 0;    % Leave the stencil alone.
%
scale_aware = 0;       % Can your function use the scale?
%
scalestart = 1;        % Scales begin at h=(1/2)^scalestart;
%
scaledepth = 7;        % Scales end at h=(1/2)^(scalestart+scaledepth)
%
stencil = 0;           % Central difference stencil.
%
target = -1.d8;        % Target for optimal value = -1.d8.
                       % You should try to do better.
%
verbose = 0;           % Shut up.
%
vstencil = [];         % No fancy stencil.
%
% Fill the structure
%
imfil_defaults=struct(...
'armijo_reduction',armijo_reduction,...
'fscale', fscale,...
'function_error',function_error,...
'least_squares',least_squares,...
'maxit',maxit,...
'maxitarm', maxitarm,...
'noise_aware', noise_aware,...
'parallel',parallel,...
'quasi',quasi,...
'random_stencil',random_stencil,...
'scale_aware',scale_aware,...
'scalestart',scalestart,...
'scaledepth',scaledepth,...
'stencil',stencil,...
'target',target,...
'verbose',verbose,...
'vstencil',vstencil);


function [okflag,optout]=verbal_shortcut(str,val,optin)
% VSHORT
% Plugs into imfil_optset and lets you use verbal shortcuts
% to control options with yes/no, on/off, or short lists of 
% options.
%
okflag=0;
optout=optin;
val=lower(val);
switch str
case 'Quasi'
    okflag=1;
    strout='quasi';
    switch val
       case 'bfgs' 
            valout=1;
       case 'sr1'
            valout=2;
       case 'none'
            valout=0;
       otherwise
          okflag=0; 
    end
case 'ScaleAware'
    strout='scale_aware';
    [valout,okflag]=yes_no(val);
case 'Verbose'
    strout='verbose'
    [valout,okflag]=yes_no(val);
end
if okflag==1;
   optout=imfil_optset(strout,valout,optin);
end

function [valout,okflag]=yes_no(val)
valout=-1;
okflag=1;
switch val
  case 'yes'
     valout=1;
  case 'no'
     valout=0;
  otherwise
     okflag=0;
end