optmt#

Purpose#

Solve the optimization problem with or without simple bounds.

Format#

out = optmt(&modelProc, par[, ..., c1])#
Parameters:
  • &modelProc (pointer) – Pointer to a procedure that computes the function to be minimized.

  • par (struct) – An instance of a PV structure. The par instance is passed to the user-provided procedure pointed to by &fct. par is constructed using the “pack” functions.

  • ... (various) – Optional input arguments. They can be any set of structures, matrices, arrays, strings required to compute the function. Can include GAUSS data types or a DS structure for dataset manipulation. Specific usage depends on the requirements of the modelProc.

  • c1 (struct) –

    Optional input. Instance of a optmtControl structure containing the following members:

    c1.algorithm

    Scalar, descent algorithm, 0 - Modified BFGS (Default), 1 = BFGS, 2 = DFP, 3 = Newton.

    c1.useThreads

    Scalar, if nonzero threading is turned on, else off. Default = off.

    c1.switch

    4x1 or 4x2 vector, controls algorithm switching. If 4x1, specifics include algorithm number to switch to, COMT switches if function changes less than a certain amount, COMT switches if a certain number of iterations is exceeded, COMT switches if line search step changes less than a certain amount. Default = {1 3, .0001 .0001, 10 10, .0001 .0001}.

    c1.lineSearch

    Scalar, sets line search method, 0 augmented Lagrangian penalty method (requires constraints), 1 STEPBT (quadratic and cubic curve fit) (default), 2 Brent’s method, 3 half, 4 Strong Wolfe’s condition.

    c1.trustRadius

    Scalar, radius of the trust region. If scalar missing, trust region not applied. Sets a maximum amount of the direction at each iteration. Default = 0.1.

    c1.penalty

    Scalar, augmentation constant for augmented Lagrangian penalty line search method.

    c1.active

    Kx1 vector, set K-th element to zero to fix it to start value. Use the GAUSS function pvGetIndex to determine where parameters in the PV structure are in the vector of parameters. Default = {}, all parameters are active.

    c1.maxIters

    Scalar, maximum number of iterations. Default = 10000.

    c1.dirTol

    Scalar, convergence tolerance. Iterations cease when all elements of the direction vector are less than this value. Default = 1e-5.

    c1.feasibleTest

    Scalar, if nonzero, parameters are tested for feasibility before computing function in line search. If function is defined outside inequality boundaries, then this test can be turned off. Default = 1.

    c1.maxTries

    Scalar, maximum number of attempts in random search. Default = 100.

    c1.randRadius

    Scalar, if zero, no random search is attempted. If nonzero, it is the radius of the random search. Default = .001.

    c1.gradMethod

    Scalar, method for computing numerical gradient. 0 = central difference, 1 = forward difference (default), 2 = backward difference.

    c1.hessMethod

    Scalar, method for computing numerical Hessian. 0 = central difference, 1 = forward difference (default), 2 = backward difference.

    c1.gradStep

    Scalar or Kx1, increment size for computing numerical derivatives (gradient and/or Hessian). If scalar, stepsize will be gradStep value times parameter estimates for the numerical derivative. If Kx1, the step size for the numerical derivatives will be the literal values of the elements of the gradStep vector.

    c1.gradCheck

    Scalar, if nonzero and if analytical gradients and/or Hessian have been provided, numerical gradients and/or Hessian are computed and compared against the analytical versions.

    c1.state

    Scalar, seed for random number generator.

    c1.title

    String, title of run.

    c1.printIters

    Scalar, if nonzero, prints iteration information. Default = 0.

    c1.disableKey

    Scalar, if nonzero, keyboard input disabled.

Returns:

out (struct) –

An instance of a optmtResults structure. Contains the results of the nonlinear programming problem solution, including parameter estimates, function evaluations, and detailed information about constraints handling and optimization process. The optmtResults structure includes:

out1.par

Instance of a PV structure containing the parameter estimates will be placed in the member matrix out1.par.

out1.fct

Scalar, function evaluated at parameters in par.

out1.gradient

Kx1 vector, gradient evaluated at the parameters in par.

out1.numIterations

Scalar, number of iterations.

out1.elapsedTime

Scalar, elapsed time of iterations.

out1.title

String, title of run.

out1.retcode

Return code:

  • 0 - Normal convergence.

  • 1 - Forced exit.

  • 2 - Maximum number of iterations exceeded.

  • 3 - Function calculation failed.

  • 4 - Gradient calculation failed.

  • 5 - Hessian calculation failed.

  • 6 - Line search failed.

  • 7 - Functional evaluation failed.

  • 8 - Error with initial gradient.

  • 10 - Second update failed.

  • 11 - Maximum time exceeded.

  • 16 - Function evaluated as complex.

  • 17 - Nnull activeset.

  • 20 - Hessian failed to invert.

  • 20 - Data set could not open.

Examples#

Remarks#

  • There is one required user-provided procedure, the one computing the objective function and optionally the first and/or second derivatives, and four other optional procedures, one each for computing the equality constraints, the inequality constraints, the Jacobian of the equality constraints, and the Jacobian of the inequality constraints.

  • The main procedure, computing the objective function and optionally the first and/or second derivatives:
    • Requires a vector of parameters or an instance of a PV structure containing the parameters as the first input.

    • Any number of optional arguments including structures, matrices, arrays, strings, required to compute the objective function.

    • A last input named ind.

  • The remaining optional procedures take just two arguments: the parameters and any optional arguments that were passed to optmt().

  • The instance of the PV structure is set up using the PV pack procedures, pvPack(), pvPackm(), pvPacks(), and pvPacksm(). These procedures allow for setting up a parameter vector in a variety of ways.

  • The optional arguments passed to the user-provided objective function procedure are untouched. This allows you to pass into your function any information it needs.