Poblano Toolbox

Optimization Output Parameters

Each of the optimization methods in Poblano outputs a single structure containing fields for the approximate solution, function and gradient values at the solution, and various information about the optimization run (e.g., number of function evaluations, etc.). The Poblano function poblano_out is used by the optimization methods to set the output parameters.

Contents


Output Parameters

Each of the optimization methods in Poblano outputs a single structure containing fields described below.

X                Final iterate
F                Function value at X
G                Gradient at X
Params           Input parameters used for the minimization method (as
                 parsed Matlab inputParser object)
FuncEvals        Number of function evaluations performed
Iters            Number of iterations performed (see individual minimization
                 routines for details on what each iteration consists of
ExitFlag         Termination flag, with one of the following values
                 0 : scaled gradient norm < StopTol input parameter)
                 1 : maximum number of iterations exceeded
                 2 : maximum number of function values exceeded
                 3 : relative change in function value < RelFuncTol input parameter
                 4 : NaNs found in F, G, or ||G||


Optional Trace Output Parameters

Additional output parameters returned by the Poblano optimization methods are presented below. The histories (i.e., traces) of different variables and parameters at each iteration are returned as output parameters if the corresponding input parameters are set to true (see the Optimization Input Parameters documentation for more details on the input parameters).

TraceX           History of X (iterates)
TraceFunc        History of the function values of the iterates
TraceRelFunc     History of the relative difference between the function
                 values at the current and previous iterates
TraceGrad        History of the gradients of the iterates
TraceGradNorm    History of the norm of the gradients of the iterates
TraceFuncEvals   History of the number of function evaluations performed
                 at each iteration


Example Output

The following example shows the output produced when the default input parameters are used.

out = ncg(@(x) example1(x,3), pi/4)
 Iter  FuncEvals       F(X)          ||G(X)||/N        
------ --------- ---------------- ----------------
     0         1       0.70710678       2.12132034
     1        14      -0.99998885       0.01416497
     2        16      -1.00000000       0.00000147

out = 

       Params: [1x1 inputParser]
     ExitFlag: 0
            X: 70.686
            F: -1
            G: -1.4734e-06
    FuncEvals: 16
        Iters: 2

The following example presents an example where a method terminates before convergence (due to a limit on the number of iterations allowed).

out = ncg(@(x) example1(x,3), pi/4,'MaxIters',1)
 Iter  FuncEvals       F(X)          ||G(X)||/N        
------ --------- ---------------- ----------------
     0         1       0.70710678       2.12132034
     1        14      -0.99998885       0.01416497

out = 

       Params: [1x1 inputParser]
     ExitFlag: 1
            X: 70.684
            F: -0.99999
            G: -0.014165
    FuncEvals: 14
        Iters: 1

The following shows the ability to save traces of the different information for each iteration.

out = ncg(@(x) example1(x,3), [1 2 3]','TraceX',true,'TraceFunc', true, ...
    'TraceRelFunc',true,'TraceGrad',true,'TraceGradNorm',true,'TraceFuncEvals',true)
 Iter  FuncEvals       F(X)          ||G(X)||/N        
------ --------- ---------------- ----------------
     0         1       0.27382300       1.65292785
     1         5      -2.65134210       0.79522946
     2        11      -2.93709563       0.35196906
     3        14      -2.99999975       0.00070154
     4        16      -3.00000000       0.00000000

out = 

            Params: [1x1 inputParser]
          ExitFlag: 0
                 X: [3x1 double]
                 F: -3
                 G: [3x1 double]
         FuncEvals: 16
             Iters: 4
            TraceX: [3x5 double]
         TraceFunc: [0.27382 -2.6513 -2.9371 -3 -3]
      TraceRelFunc: [10.683 0.10778 0.021417 8.2026e-08]
         TraceGrad: [3x5 double]
     TraceGradNorm: [4.9588 2.3857 1.0559 0.0021046 2.5726e-09]
    TraceFuncEvals: [1 4 6 3 2]

We can examine the final solution and its gradient (which list only their sizes when viewing the output structure):

X = out.X
G = out.G
X =

       3.6652
      -0.5236
       5.7596


G =

   7.2032e-11
   -2.052e-09
    -1.55e-09

We can also see the values of X (current iterate) and its gradient G for each iteration (including iteration 0, which just computes the function and gradient values of the initial point):

out.TraceX
out.TraceGrad
ans =

            1       3.7424       3.7441       3.6652       3.6652
            2     -0.65978     -0.61064     -0.52378      -0.5236
            3       5.5239       5.7756       5.7594       5.7596


ans =

        -2.97      0.68856      0.70313   6.1109e-05   7.2032e-11
       2.8805      -1.1918     -0.77453    -0.001668   -2.052e-09
      -2.7334      -1.9486      0.14372    -0.001282    -1.55e-09


Poblano Toolbox