Home > manopt > core > applyHook.m

applyHook

PURPOSE ^

Apply the hook function to possibly replace the current x (for solvers).

SYNOPSIS ^

function [newx, newkey, info, hooked] = applyHook(problem, x, storedb, key, options, info, last)

DESCRIPTION ^

 Apply the hook function to possibly replace the current x (for solvers).

 function [newx, newkey, info, hooked] = 
                  applyHook(problem, x, storedb, key, options, info, last)

 Applies the options.hook user-supplied function (if there is one) to the
 current x of a solver. If this leads to a change, than the boolean
 'hooked' is true, and newx, newkey are different from x, key. Otherwise,
 newx, newkey are equal to x, key, and the boolean 'hooked' is false.

 storedb is a StoreDB object, key is the StoreDB key to point x; likewise
 for newkey and newx.

 info and last work the same way as in stoppingcriterion.

 The hook is called at the beginning of each iteration, after saving the
 stats information, but before evaluating stopping criteria. Time spent in
 the hook is included in the solver's reported computation time.

 This function takes care of logging the boolean 'hooked' in the info
 struct-array. (This requires the field 'hooked' to exist in the first
 place: applyStatsfun ensures this.)

 The options.hook function handle can have these prototypes:

   [newx, hooked]                = hook(problem, x)
   [newx, newkey, hooked]        = hook(problem, x, storedb, key)
   [newx, newkey, hooked, stats] = hook(problem, x, storedb, key, stats)

 See also: applyStatsfun stoppingcriterion

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function [newx, newkey, info, hooked] = applyHook(problem, x, storedb, key, options, info, last)
0002 % Apply the hook function to possibly replace the current x (for solvers).
0003 %
0004 % function [newx, newkey, info, hooked] =
0005 %                  applyHook(problem, x, storedb, key, options, info, last)
0006 %
0007 % Applies the options.hook user-supplied function (if there is one) to the
0008 % current x of a solver. If this leads to a change, than the boolean
0009 % 'hooked' is true, and newx, newkey are different from x, key. Otherwise,
0010 % newx, newkey are equal to x, key, and the boolean 'hooked' is false.
0011 %
0012 % storedb is a StoreDB object, key is the StoreDB key to point x; likewise
0013 % for newkey and newx.
0014 %
0015 % info and last work the same way as in stoppingcriterion.
0016 %
0017 % The hook is called at the beginning of each iteration, after saving the
0018 % stats information, but before evaluating stopping criteria. Time spent in
0019 % the hook is included in the solver's reported computation time.
0020 %
0021 % This function takes care of logging the boolean 'hooked' in the info
0022 % struct-array. (This requires the field 'hooked' to exist in the first
0023 % place: applyStatsfun ensures this.)
0024 %
0025 % The options.hook function handle can have these prototypes:
0026 %
0027 %   [newx, hooked]                = hook(problem, x)
0028 %   [newx, newkey, hooked]        = hook(problem, x, storedb, key)
0029 %   [newx, newkey, hooked, stats] = hook(problem, x, storedb, key, stats)
0030 %
0031 % See also: applyStatsfun stoppingcriterion
0032 
0033 % This file is part of Manopt: www.manopt.org.
0034 % Original author: Nicolas Boumal, July 19, 2020.
0035 % Contributors: Eitan Levin
0036 % Change log:
0037 
0038     if isfield(options, 'hook')
0039         
0040         nin = nargin(options.hook);
0041         nout = nargout(options.hook);
0042         
0043         if nin == 2 && nout == 2
0044             [newx, hooked] = options.hook(problem, x);
0045             if hooked
0046                 storedb.remove(key);
0047                 newkey = storedb.getNewKey();
0048             else
0049                 newkey = key;
0050             end
0051         elseif nin == 4 && nout == 3
0052             [newx, newkey, hooked] = options.hook(problem, x, storedb, key);
0053             if hooked
0054                 storedb.removefirstifdifferent(key, newkey);
0055             end
0056         elseif nin == 5 && nout == 4
0057             stats = info(last);
0058             [newx, newkey, hooked, stats] = ...
0059                              options.hook(problem, x, storedb, key, stats);
0060             info(last) = stats;
0061             if hooked
0062                 storedb.removefirstifdifferent(key, newkey);
0063             end
0064         else
0065             newx = x;
0066             newkey = key;
0067             hooked = false;
0068             warning('manopt:hook', ...
0069                     'options.hook unused: wrong number of inputs/outputs');
0070         end
0071         
0072     else
0073         newx = x;
0074         newkey = key;
0075         hooked = false;
0076     end
0077     
0078     % Always register whether or not the point was hooked (i.e., changed).
0079     % This field is first created in applyStatsfun.
0080     stats = info(last);
0081     stats.hooked = hooked;
0082     info(last) = stats;
0083 
0084 end

Generated on Sun 05-Sep-2021 17:57:00 by m2html © 2005