Optimization
************

Octave comes with support for solving various kinds of optimization problems.  Specifically Octave can solve problems in Linear Programming, Quadratic Programming, Nonlinear Programming, and Linear Least Squares Minimization.

Linear Programming
==================

Octave can solve Linear Programming problems using the glpk function.  That is, Octave can solve

     min C'*x

subject to the linear constraints A*x = b where x ≥ 0.

The glpk function also supports variations of this problem.

 -- [XOPT, FMIN, ERRNUM, EXTRA] =: glpk (C, A, B, LB, UB, CTYPE, VARTYPE, SENSE, PARAM)
     Solve a linear program using the GNU GLPK library.

     Given three arguments, glpk solves the following standard LP:

          min C'*x

     subject to

          A*x  = b
            x >= 0

     but may also solve problems of the form

          [ min | max ] C'*x

     subject to

          A*x [ "=" | "<=" | ">=" ] b
            x >= LB
            x <= UB

     Input arguments:

     c
          A column array containing the objective function coefficients.

     A
          A matrix containing the constraints coefficients.

     b
          A column array containing the right-hand side value for each constraint in the constraint matrix.

     lb
          An array containing the lower bound on each of the variables.  If LB is not supplied, the default lower bound for the variables is zero.

     ub
          An array containing the upper bound on each of the variables.  If UB is not supplied, the default upper bound is assumed to be infinite.

     ctype
          An array of characters containing the sense of each constraint in the constraint matrix.  Each element of the array may be one of the following values

          "F"
               A free (unbounded) constraint (the constraint is ignored).

          "U"
               An inequality constraint with an upper bound (A(i,:)*x <= b(i)).

          "S"
               An equality constraint (A(i,:)*x = b(i)).

          "L"
               An inequality with a lower bound (A(i,:)*x >= b(i)).

          "D"
               An inequality constraint with both upper and lower bounds (A(i,:)*x >= -b(i)) and (A(i,:)*x <= b(i)).

     vartype
          A column array containing the types of the variables.

          "C"
               A continuous variable.

          "I"
               An integer variable.

     sense
          If SENSE is 1, the problem is a minimization.  If SENSE is -1, the problem is a maximization.  The default value is 1.

     param
          A structure containing the following parameters used to define the behavior of solver.  Missing elements in the structure take on default values, so you only need to set the elements that you wish to change from the default.

          Integer parameters:

          msglev (default: 1)
               Level of messages output by solver routines:

               0 (GLP_MSG_OFF)
                    No output.

               1 (GLP_MSG_ERR)
                    Error and warning messages only.

               2 (GLP_MSG_ON)
                    Normal output.

               3 (GLP_MSG_ALL)
                    Full output (includes informational messages).

          scale (default: 16)
               Scaling option.  The values can be combined with the bitwise OR operator and may be the following:

               1 (GLP_SF_GM)
                    Geometric mean scaling.

               16 (GLP_SF_EQ)
                    Equilibration scaling.

               32 (GLP_SF_2N)
                    Round scale factors to power of two.

               64 (GLP_SF_SKIP)
                    Skip if problem is well scaled.

               Alternatively, a value of 128 (GLP_SF_AUTO) may be also specified, in which case the routine chooses the scaling options automatically.

          dual (default: 1)
               Simplex method option:

               1 (GLP_PRIMAL)
                    Use two-phase primal simplex.

               2 (GLP_DUALP)
                    Use two-phase dual simplex, and if it fails, switch to the primal simplex.

               3 (GLP_DUAL)
                    Use two-phase dual simplex.

          price (default: 34)
               Pricing option (for both primal and dual simplex):

               17 (GLP_PT_STD)
                    Textbook pricing.

               34 (GLP_PT_PSE)
                    Steepest edge pricing.

          itlim (default: intmax)
               Simplex iterations limit.  It is decreased by one each time when one simplex iteration has been performed, and reaching zero value signals the solver to stop the search.

          outfrq (default: 200)
               Output frequency, in iterations.  This parameter specifies how frequently the solver sends information about the solution to the standard output.

          branch (default: 4)
               Branching technique option (for MIP only):

               1 (GLP_BR_FFV)
                    First fractional variable.

               2 (GLP_BR_LFV)
                    Last fractional variable.

               3 (GLP_BR_MFV)
                    Most fractional variable.

               4 (GLP_BR_DTH)
                    Heuristic by Driebeck and Tomlin.

               5 (GLP_BR_PCH)
                    Hybrid pseudocost heuristic.

          btrack (default: 4)
               Backtracking technique option (for MIP only):

               1 (GLP_BT_DFS)
                    Depth first search.

               2 (GLP_BT_BFS)
                    Breadth first search.

               3 (GLP_BT_BLB)
                    Best local bound.

               4 (GLP_BT_BPH)
                    Best projection heuristic.

          presol (default: 1)
               If this flag is set, the simplex solver uses the built-in LP presolver. Otherwise the LP presolver is not used.

          lpsolver (default: 1)
               Select which solver to use.  If the problem is a MIP problem this flag will be ignored.

               1
                    Revised simplex method.

               2
                    Interior point method.

          rtest (default: 34)
               Ratio test technique:

               17 (GLP_RT_STD)
                    Standard ("textbook").

               34 (GLP_RT_HAR)
                    Harris' two-pass ratio test.

          tmlim (default: intmax)
               Searching time limit, in milliseconds.

          outdly (default: 0)
               Output delay, in seconds.  This parameter specifies how long the solver should delay sending information about the solution to the standard output.

          save (default: 0)
               If this parameter is nonzero, save a copy of the problem in CPLEX LP format to the file "outpb.lp".  There is currently no way to change the name of the output file.

          Real parameters:

          tolbnd (default: 1e-7)
               Relative tolerance used to check if the current basic solution is primal feasible.  It is not recommended that you change this parameter unless you have a detailed understanding of its purpose.

          toldj (default: 1e-7)
               Absolute tolerance used to check if the current basic solution is dual feasible.  It is not recommended that you change this parameter unless you have a detailed understanding of its purpose.

          tolpiv (default: 1e-10)
               Relative tolerance used to choose eligible pivotal elements of the simplex table.  It is not recommended that you change this parameter unless you have a detailed understanding of its purpose.

          objll (default: -DBL_MAX)
               Lower limit of the objective function.  If the objective function reaches this limit and continues decreasing, the solver stops the search.  This parameter is used in the dual simplex method only.

          objul (default: +DBL_MAX)
               Upper limit of the objective function.  If the objective function reaches this limit and continues increasing, the solver stops the search.  This parameter is used in the dual simplex only.

          tolint (default: 1e-5)
               Relative tolerance used to check if the current basic solution is integer feasible.  It is not recommended that you change this parameter unless you have a detailed understanding of its purpose.

          tolobj (default: 1e-7)
               Relative tolerance used to check if the value of the objective function is not better than in the best known integer feasible solution.  It is not recommended that you change this parameter unless you have a detailed understanding of its purpose.

     Output values:

     xopt
          The optimizer (the value of the decision variables at the optimum).

     fopt
          The optimum value of the objective function.

     errnum
          Error code.

          0
               No error.

          1 (GLP_EBADB)
               Invalid basis.

          2 (GLP_ESING)
               Singular matrix.

          3 (GLP_ECOND)
               Ill-conditioned matrix.

          4 (GLP_EBOUND)
               Invalid bounds.

          5 (GLP_EFAIL)
               Solver failed.

          6 (GLP_EOBJLL)
               Objective function lower limit reached.

          7 (GLP_EOBJUL)
               Objective function upper limit reached.

          8 (GLP_EITLIM)
               Iterations limit exhausted.

          9 (GLP_ETMLIM)
               Time limit exhausted.

          10 (GLP_ENOPFS)
               No primal feasible solution.

          11 (GLP_ENODFS)
               No dual feasible solution.

          12 (GLP_EROOT)
               Root LP optimum not provided.

          13 (GLP_ESTOP)
               Search terminated by application.

          14 (GLP_EMIPGAP)
               Relative MIP gap tolerance reached.

          15 (GLP_ENOFEAS)
               No primal/dual feasible solution.

          16 (GLP_ENOCVG)
               No convergence.

          17 (GLP_EINSTAB)
               Numerical instability.

          18 (GLP_EDATA)
               Invalid data.

          19 (GLP_ERANGE)
               Result out of range.

     extra
          A data structure containing the following fields:

          lambda
               Dual variables.

          redcosts
               Reduced Costs.

          time
               Time (in seconds) used for solving LP/MIP problem.

          status
               Status of the optimization.

               1 (GLP_UNDEF)
                    Solution status is undefined.

               2 (GLP_FEAS)
                    Solution is feasible.

               3 (GLP_INFEAS)
                    Solution is infeasible.

               4 (GLP_NOFEAS)
                    Problem has no feasible solution.

               5 (GLP_OPT)
                    Solution is optimal.

               6 (GLP_UNBND)
                    Problem has no unbounded solution.

     Example:

          c = [10, 6, 4]';
          A = [ 1, 1, 1;
               10, 4, 5;
                2, 2, 6];
          b = [100, 600, 300]';
          lb = [0, 0, 0]';
          ub = [];
          ctype = "UUU";
          vartype = "CCC";
          s = -1;

          param.msglev = 1;
          param.itlim = 100;

          [xmin, fmin, status, extra] = ...
             glpk (c, A, b, lb, ub, ctype, vartype, s, param);

Quadratic Programming
=====================

Octave can also solve Quadratic Programming problems, this is

     min 0.5 x'*H*x + x'*q

subject to

          A*x = b
          lb <= x <= ub
          A_lb <= A_in*x <= A_ub

 -- [X, OBJ, INFO, LAMBDA] =: qp (X0, H)
 -- [X, OBJ, INFO, LAMBDA] =: qp (X0, H, Q)
 -- [X, OBJ, INFO, LAMBDA] =: qp (X0, H, Q, A, B)
 -- [X, OBJ, INFO, LAMBDA] =: qp (X0, H, Q, A, B, LB, UB)
 -- [X, OBJ, INFO, LAMBDA] =: qp (X0, H, Q, A, B, LB, UB, A_LB, A_IN, A_UB)
 -- [X, OBJ, INFO, LAMBDA] =: qp (..., OPTIONS)
     Solve a quadratic program (QP).

     Solve the quadratic program defined by

          min 0.5 x'*H*x + x'*q
           x

     subject to

          A*x = b
          lb <= x <= ub
          A_lb <= A_in*x <= A_ub

     using a null-space active-set method.

     Any bound (A, B, LB, UB, A_IN, A_LB, A_UB) may be set to the empty matrix ([]) if not present.  The constraints A and A_IN are matrices with each row representing a single constraint.  The other bounds are scalars or vectors depending on the number of constraints.  The algorithm is faster if the initial guess is feasible.

     OPTIONS is a structure specifying additional parameters which control the algorithm.  Currently, qp recognizes these options: "MaxIter", "TolX".

     "MaxIter" proscribes the maximum number of algorithm iterations before optimization is halted.  The default value is 200. The value must be a positive integer.

     "TolX" specifies the termination tolerance for the unknown variables X.  The default is sqrt (eps) or approximately 1e-8.

     On return, X is the location of the minimum and FVAL contains the value of the objective function at X.

     info
          Structure containing run-time information about the algorithm.  The following fields are defined:

          solveiter
               The number of iterations required to find the solution.

          info
               An integer indicating the status of the solution.

               0
                    The problem is feasible and convex.  Global solution found.

               1
                    The problem is not convex.  Local solution found.

               2
                    The problem is not convex and unbounded.

               3
                    Maximum number of iterations reached.

               6
                    The problem is infeasible.

     sqp

 -- X =: pqpnonneg (C, D)
 -- X =: pqpnonneg (C, D, X0)
 -- X =: pqpnonneg (C, D, X0, OPTIONS)
 -- [X, MINVAL] =: pqpnonneg (...)
 -- [X, MINVAL, EXITFLAG] =: pqpnonneg (...)
 -- [X, MINVAL, EXITFLAG, OUTPUT] =: pqpnonneg (...)
 -- [X, MINVAL, EXITFLAG, OUTPUT, LAMBDA] =: pqpnonneg (...)

     Minimize  (1/2 * X' * C * X + D' * X) subject to X >= 0.

     C and D must be real matrices, and C must be symmetric and positive definite.

     X0 is an optional initial guess for the solution X.

     OPTIONS is an options structure to change the behavior of the algorithm (see optimset).  pqpnonneg recognizes one option: "MaxIter".

     Outputs:

     x
          The solution matrix

     minval
          The minimum attained model value, 1/2*XMIN'*C*XMIN + D'*XMIN

     exitflag
          An indicator of convergence.  0 indicates that the iteration count was exceeded, and therefore convergence was not reached; >0 indicates that the algorithm converged.  (The algorithm is stable and will converge given enough iterations.)

     output
          A structure with two fields:

            * "algorithm": The algorithm used ("nnls")

            * "iterations": The number of iterations taken.

     lambda
          Lagrange multipliers.  If these are nonzero, the corresponding X values should be zero, indicating the solution is pressed up against a coordinate plane.  The magnitude indicates how much the residual would improve if the X >= 0 constraints were relaxed in that direction.

     lsqnonneg, qp, optimset

Nonlinear Programming
=====================

Octave can also perform general nonlinear minimization using a successive quadratic programming solver.

 -- [X, OBJ, INFO, ITER, NF, LAMBDA] =: sqp (X0, PHI)
 -- [...] =: sqp (X0, PHI, G)
 -- [...] =: sqp (X0, PHI, G, H)
 -- [...] =: sqp (X0, PHI, G, H, LB, UB)
 -- [...] =: sqp (X0, PHI, G, H, LB, UB, MAXITER)
 -- [...] =: sqp (X0, PHI, G, H, LB, UB, MAXITER, TOLERANCE)
     Minimize an objective function using sequential quadratic programming (SQP).

     Solve the nonlinear program

          min phi (x)
           x

     subject to

          g(x)  = 0
          h(x) >= 0
          lb <= x <= ub

     using a sequential quadratic programming method.

     The first argument is the initial guess for the vector X0.

     The second argument is a function handle pointing to the objective function PHI.  The objective function must accept one vector argument and return a scalar.

     The second argument may also be a 2- or 3-element cell array of function handles.  The first element should point to the objective function, the second should point to a function that computes the gradient of the objective function, and the third should point to a function that computes the Hessian of the objective function.  If the gradient function is not supplied, the gradient is computed by finite differences.  If the Hessian function is not supplied, a BFGS update formula is used to approximate the Hessian.

     When supplied, the gradient function PHI{2} must accept one vector argument and return a vector.  When supplied, the Hessian function PHI{3} must accept one vector argument and return a matrix.

     The third and fourth arguments G and H are function handles pointing to functions that compute the equality constraints and the inequality constraints, respectively.  If the problem does not have equality (or inequality) constraints, then use an empty matrix ([]) for G (or H).  When supplied, these equality and inequality constraint functions must accept one vector argument and return a vector.

     The third and fourth arguments may also be 2-element cell arrays of function handles.  The first element should point to the constraint function and the second should point to a function that computes the gradient of the constraint function:

                      [ d f(x)   d f(x)        d f(x) ]
          transpose ( [ ------   -----   ...   ------ ] )
                      [  dx_1     dx_2          dx_N  ]

     The fifth and sixth arguments, LB and UB, contain lower and upper bounds on X and when provided must be vectors of the same size as the the vector X0.  The bounds must be consistent with the equality and inequality constraints G and H.

     The seventh argument MAXITER specifies the maximum number of iterations.  The default value is 100.

     The eighth argument TOLERANCE specifies the tolerance for the stopping criteria.  The default value is sqrt (eps).

     The value returned in INFO may be one of the following:

     101
          The algorithm terminated normally. All constraints meet the specified tolerance.

     102
          The BFGS update failed.

     103
          The maximum number of iterations was reached.

     104
          The stepsize has become too small, i.e., delta X, is less than TOL * norm (x).

     An example of calling sqp:

          function r = g (x)
            r = [ sumsq(x)-10;
                  x(2)*x(3)-5*x(4)*x(5);
                  x(1)^3+x(2)^3+1 ];
          endfunction

          function obj = phi (x)
            obj = exp (prod (x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
          endfunction

          x0 = [-1.8; 1.7; 1.9; -0.8; -0.8];

          [x, obj, info, iter, nf, lambda] = sqp (x0, @phi, @g, [])

          x =

            -1.71714
             1.59571
             1.82725
            -0.76364
            -0.76364

          obj = 0.053950
          info = 101
          iter = 8
          nf = 10
          lambda =

            -0.0401627
             0.0379578
            -0.0052227

     qp

Linear Least Squares
====================

Octave also supports linear least squares minimization.  That is, Octave can find the parameter b such that the model y = x*b fits data (x,y) as well as possible, assuming zero-mean Gaussian noise.  If the noise is assumed to be isotropic the problem can be solved using the \ or / operators, or the ols function.  In the general case where the noise is assumed to be anisotropic the gls is needed.

 -- [BETA, SIGMA, R] =: ols (Y, X)
     Ordinary least squares (OLS) estimation.

     OLS applies to the multivariate model Y = X*B + E where Y is a t-by-p matrix, X is a t-by-k matrix, B is a k-by-p matrix, and E is a t-by-p matrix.

     Each row of Y is a p-variate observation in which each column represents a variable.  Likewise, the rows of X represent k-variate observations or possibly designed values.  Furthermore, the collection of observations X must be of adequate rank, k, otherwise B cannot be uniquely estimated.

     The observation errors, E, are assumed to originate from an underlying p-variate distribution with zero mean and p-by-p covariance matrix S, both constant conditioned on X.  Furthermore, the matrix S is constant with respect to each observation such that mean (E) = 0 and cov (vec (E)) = kron (S, I). (For cases that don't meet this criteria, such as autocorrelated errors, see generalized least squares, gls, for more efficient estimations.)

     The return values BETA, SIGMA, and R are defined as follows.

     beta
          The OLS estimator for matrix B. BETA is calculated directly via inv (X'*X) * X' * Y if the matrix X'*X is of full rank. Otherwise, BETA = pinv (X) * Y where pinv (X) denotes the pseudoinverse of X.

     sigma
          The OLS estimator for the matrix S,

               SIGMA = (Y-X*BETA)' * (Y-X*BETA) / (t-rank(X))

     r
          The matrix of OLS residuals, R = Y - X*BETA.

     gls, pinv

 -- [BETA, V, R] =: gls (Y, X, O)
     Generalized least squares (GLS) model.

     Perform a generalized least squares estimation for the multivariate model Y = X*B + E where Y is a t-by-p matrix, X is a t-by-k matrix, B is a k-by-p matrix and E is a t-by-p matrix.

     Each row of Y is a p-variate observation in which each column represents a variable.  Likewise, the rows of X represent k-variate observations or possibly designed values.  Furthermore, the collection of observations X must be of adequate rank, k, otherwise B cannot be uniquely estimated.

     The observation errors, E, are assumed to originate from an underlying p-variate distribution with zero mean but possibly heteroscedastic observations.  That is, in general, mean (E) = 0 and cov (vec (E)) = (s^2)*O in which s is a scalar and O is a t*p-by-t*p matrix.

     The return values BETA, V, and R are defined as follows.

     beta
          The GLS estimator for matrix B.

     v
          The GLS estimator for scalar s^2.

     r
          The matrix of GLS residuals, R = Y - X*BETA.

     ols

 -- X =: lsqnonneg (C, D)
 -- X =: lsqnonneg (C, D, X0)
 -- X =: lsqnonneg (C, D, X0, OPTIONS)
 -- [X, RESNORM] =: lsqnonneg (...)
 -- [X, RESNORM, RESIDUAL] =: lsqnonneg (...)
 -- [X, RESNORM, RESIDUAL, EXITFLAG] =: lsqnonneg (...)
 -- [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT] =: lsqnonneg (...)
 -- [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT, LAMBDA] =: lsqnonneg (...)

     Minimize norm (C*X - D) subject to X >= 0.

     C and D must be real matrices.

     X0 is an optional initial guess for the solution X.

     OPTIONS is an options structure to change the behavior of the algorithm (see optimset).  lsqnonneg recognizes these options: "MaxIter", "TolX".

     Outputs:

     resnorm
          The squared 2-norm of the residual: norm (C*X-D)^2

     residual
          The residual: D-C*X

     exitflag
          An indicator of convergence.  0 indicates that the iteration count was exceeded, and therefore convergence was not reached; >0 indicates that the algorithm converged.  (The algorithm is stable and will converge given enough iterations.)

     output
          A structure with two fields:

            * "algorithm": The algorithm used ("nnls")

            * "iterations": The number of iterations taken.

     lambda
          Lagrange multipliers.  If these are nonzero, the corresponding X values should be zero, indicating the solution is pressed up against a coordinate plane.  The magnitude indicates how much the residual would improve if the X >= 0 constraints were relaxed in that direction.

     pqpnonneg, lscov, optimset

 -- X =: lscov (A, B)
 -- X =: lscov (A, B, V)
 -- X =: lscov (A, B, V, ALG)
 -- [X, STDX, MSE, S] =: lscov (...)

     Compute a generalized linear least squares fit.

     Estimate X under the model B = AX + W, where the noise W is assumed to follow a normal distribution with covariance matrix \sigma^2 V.

     If the size of the coefficient matrix A is n-by-p, the size of the vector/array of constant terms B must be n-by-k.

     The optional input argument V may be an n-element vector of positive weights (inverse variances), or an n-by-n symmetric positive semi-definite matrix representing the covariance of B.  If V is not supplied, the ordinary least squares solution is returned.

     The ALG input argument, a guidance on solution method to use, is currently ignored.

     Besides the least-squares estimate matrix X (p-by-k), the function also returns STDX (p-by-k), the error standard deviation of estimated X; MSE (k-by-1), the estimated data error covariance scale factors (\sigma^2); and S (p-by-p, or p-by-p-by-k if k > 1), the error covariance of X.

     Reference: Golub and Van Loan (1996), Matrix Computations (3rd Ed.), Johns Hopkins, Section 5.6.3

     ols, gls, lsqnonneg

 -- optimset: ()
 -- OPTIONS =: optimset ()
 -- OPTIONS =: optimset (PAR, VAL, ...)
 -- OPTIONS =: optimset (OLD, PAR, VAL, ...)
 -- OPTIONS =: optimset (OLD, NEW)
     Create options structure for optimization functions.

     When called without any input or output arguments, optimset prints a list of all valid optimization parameters.

     When called with one output and no inputs, return an options structure with all valid option parameters initialized to [].

     When called with a list of parameter/value pairs, return an options structure with only the named parameters initialized.

     When the first input is an existing options structure OLD, the values are updated from either the PAR/VAL list or from the options structure NEW.

     If PAR does not exactly match the name of a standard parameter, optimset will attempt to match PAR to a standard parameter and will set the value of that parameter if a match is found.  Matching is case insensitive and is based on character matching at the start of the parameter name.  optimset produces an error if it finds multiple ambiguous matches.  If no standard parameter matches are found a warning is issued and the non-standard parameter is created.

     Standard list of valid parameters:

     AutoScaling

     ComplexEqn

     Display
          Request verbose display of results from optimizations.  Values are:

          "off" [default]
               No display.

          "iter"
               Display intermediate results for every loop iteration.

          "final"
               Display the result of the final loop iteration.

          "notify"
               Display the result of the final loop iteration if the function has failed to converge.

     FinDiffType

     FunValCheck
          When enabled, display an error if the objective function returns an invalid value (a complex number, NaN, or Inf).  Must be set to "on" or "off" [default].  Note: the functions fzero and fminbnd correctly handle Inf values and only complex values or NaN will cause an error in this case.

     GradObj
          When set to "on", the function to be minimized must return a second argument which is the gradient, or first derivative, of the function at the point X.  If set to "off" [default], the gradient is computed via finite differences.

     Jacobian
          When set to "on", the function to be minimized must return a second argument which is the Jacobian, or first derivative, of the function at the point X.  If set to "off" [default], the Jacobian is computed via finite differences.

     MaxFunEvals
          Maximum number of function evaluations before optimization stops. Must be a positive integer.

     MaxIter
          Maximum number of algorithm iterations before optimization stops. Must be a positive integer.

     OutputFcn
          A user-defined function executed once per algorithm iteration.

     TolFun
          Termination criterion for the function output.  If the difference in the calculated objective function between one algorithm iteration and the next is less than TolFun the optimization stops.  Must be a positive scalar.

     TolX
          Termination criterion for the function input.  If the difference in X, the current search point, between one algorithm iteration and the next is less than TolX the optimization stops.  Must be a positive scalar.

     TypicalX

     Updating

     This list can be extended by the user or other loaded Octave packages.  An updated valid parameters list can be queried using the no-argument form of optimset.

     Note 1: Only parameter names from the standard list are considered when matching short parameter names, and PAR will always be expanded to match a standard parameter even if an exact non-standard match exists. The value of a non-standard parameter that is ambiguous with one or more standard parameters cannot be set by optimset and can only be set using setfield or dot notation for structs.

     Note 2: The optimization options structure is primarily intended for manipulation of known parameters by optimset and optimget. Unpredictable behavior on future calls to optimset or optimget can result from creating non-standard or ambiguous parameters or from loading/unloading packages that change the known parameter list after creation of an optimization options structure. optimget

 -- VAL =: optimget (OPTIONS, PAR)
 -- VAL =: optimget (OPTIONS, PAR, DEFAULT)
     Return the value of the specific parameter PAR from the optimization options structure OPTIONS created by optimset.

     If PAR is not defined then return the DEFAULT value if supplied, otherwise return an empty matrix.

     If PAR does not exactly match the name of a standard parameter, optimget will attempt to match PAR to a standard parameter and will return that parameter's value if a match is found.  Matching is case insensitive and is based on character matching at the start of the parameter name.  optimget produces an error if it finds multiple ambiguous matches.  If no standard parameter matches are found a warning is issued.  See optimset for information about the standard options list.

     Note: Only parameter names from the standard list are considered when matching short parameter names, and PAR will always be expanded to match a standard parameter even if an exact non-standard match exists.  The value of a non-standard parameter that is ambiguous with one or more standard parameters cannot be returned by optimget and can only be accessed using getfield or dot notation for structs. optimset