Home > manopt > core > getEuclideanGradient.m

getEuclideanGradient

PURPOSE ^

Computes the Euclidean gradient of the cost function at x.

SYNOPSIS ^

function egrad = getEuclideanGradient(problem, x, storedb, key)

DESCRIPTION ^

 Computes the Euclidean gradient of the cost function at x.

 function egrad = getEuclideanGradient(problem, x)
 function egrad = getEuclideanGradient(problem, x, storedb)
 function egrad = getEuclideanGradient(problem, x, storedb, key)

 Returns the Euclidean gradient at x of the cost function described in the
 problem structure.

 storedb is a StoreDB object, key is the StoreDB key to point x.

 Because computing the Hessian based on the Euclidean Hessian will require
 the Euclidean gradient every time, to avoid overly redundant
 computations, if the egrad function does not use the store caching
 capabilites, this implements an automatic caching functionality. Writing
 egrad to accept the optional store or storedb parameter will disable
 automatic caching, but allow user controlled caching.

 See also: getGradient canGetGradient canGetEuclideanGradient

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function egrad = getEuclideanGradient(problem, x, storedb, key)
0002 % Computes the Euclidean gradient of the cost function at x.
0003 %
0004 % function egrad = getEuclideanGradient(problem, x)
0005 % function egrad = getEuclideanGradient(problem, x, storedb)
0006 % function egrad = getEuclideanGradient(problem, x, storedb, key)
0007 %
0008 % Returns the Euclidean gradient at x of the cost function described in the
0009 % problem structure.
0010 %
0011 % storedb is a StoreDB object, key is the StoreDB key to point x.
0012 %
0013 % Because computing the Hessian based on the Euclidean Hessian will require
0014 % the Euclidean gradient every time, to avoid overly redundant
0015 % computations, if the egrad function does not use the store caching
0016 % capabilites, this implements an automatic caching functionality. Writing
0017 % egrad to accept the optional store or storedb parameter will disable
0018 % automatic caching, but allow user controlled caching.
0019 %
0020 % See also: getGradient canGetGradient canGetEuclideanGradient
0021 
0022 % This file is part of Manopt: www.manopt.org.
0023 % Original author: Nicolas Boumal, July 9, 2013.
0024 % Contributors:
0025 % Change log:
0026 %
0027 %   April 3, 2015 (NB):
0028 %       Works with the new StoreDB class system.
0029 %
0030 %   June 28, 2016 (NB):
0031 %       Added support for getPartialEuclideanGradient
0032 
0033     % Allow omission of the key, and even of storedb.
0034     if ~exist('key', 'var')
0035         if ~exist('storedb', 'var')
0036             storedb = StoreDB();
0037         end
0038         key = storedb.getNewKey();
0039     end
0040 
0041     
0042     if isfield(problem, 'egrad')
0043     %% Compute the Euclidean gradient using egrad.
0044     
0045         % Check whether this function wants to deal with storedb or not.
0046         switch nargin(problem.egrad)
0047             case 1
0048                 % If it does not want to deal with the store structure,
0049                 % then we do some caching of our own. There is a small
0050                 % performance hit for this is some cases, but we expect
0051                 % that this is most often the preferred choice.
0052                 store = storedb.get(key);
0053                 if ~isfield(store, 'egrad__')
0054                     store.egrad__ = problem.egrad(x);
0055                     storedb.set(store, key);
0056                 end
0057                 egrad = store.egrad__;
0058             case 2
0059                 % Obtain, pass along, and save the store for x.
0060                 % If the user deals with the store structure, then we don't
0061                 % do any automatic caching: the user is in control.
0062                 store = storedb.getWithShared(key);
0063                 [egrad, store] = problem.egrad(x, store);
0064                 storedb.setWithShared(store, key);
0065             case 3
0066                 % Pass along the whole storedb (by reference), with key.
0067                 % Same here: no automatic caching.
0068                 egrad = problem.egrad(x, storedb, key);
0069             otherwise
0070                 up = MException('manopt:getEuclideanGradient:badegrad', ...
0071                     'egrad should accept 1, 2 or 3 inputs.');
0072                 throw(up);
0073         end
0074         
0075     elseif canGetPartialEuclideanGradient(problem)
0076     %% Compute the Euclidean gradient using a full partial Euclidean gradient.
0077         
0078         d = problem.ncostterms;
0079         egrad = getPartialEuclideanGradient(problem, x, 1:d, storedb, key);
0080 
0081     else
0082     %% Abandon computing the Euclidean gradient
0083     
0084         up = MException('manopt:getEuclideanGradient:fail', ...
0085             ['The problem description is not explicit enough to ' ...
0086              'compute the Euclidean gradient of the cost.']);
0087         throw(up);
0088         
0089     end
0090     
0091 end

Generated on Fri 08-Sep-2017 12:43:19 by m2html © 2005