de.jtem.jtao
Class Tao

java.lang.Object
  extended by de.jtem.jpetsc.PrimitivNative
      extended by de.jtem.jpetsc.Native
          extended by de.jtem.jtao.Tao

public class Tao
extends Native


Nested Class Summary
static class Tao.GetGradientTolerancesResult
          Result class for getGradientTolerances()
static class Tao.GetSolutionStatusResult
          Result class for getSolutionStatus()
static class Tao.GetVariableBoundsResult
          Result class for getVariableBounds()
static class Tao.Method
           
 
Field Summary
 
Fields inherited from class de.jtem.jpetsc.PrimitivNative
destroyNative
 
Constructor Summary
Tao(int comm, Tao.Method method)
           
Tao(Tao.Method method)
           
 
Method Summary
 ConvergenceFlags checkConvergence()
          Checks the convergence of the solver
 void clearMonitor()
          Clears all the monitor functions for a TAO_SOLVER object.
static Tao createFiniteDifferenceTester(boolean testGradient, boolean testHessian)
           
 void finalize()
           
static void Finalize()
           
 void getDualVariables(TaoVec DXL, TaoVec DXU)
          Gets the dual variables corresponding to
the bounds of the variables.
 TaoVec getGradient()
          Sets a pointer to the address of a TaoVector that
contains the gradient of the Lagrangian function.
 Tao.GetGradientTolerancesResult getGradientTolerances()
          Returns the gradient termination tolerances.
 double getInitialTrustRegionRadius()
          Gets the initial trust region radius
 TaoMat getJacobian()
          Get the Jacobian matrix
 java.lang.String getMethod()
          Gets the TAO_SOLVER method type and name (as a string).
 TaoVec getSolution()
          Sets a pointer to a TaoVec to the address of the
vector containing the current solution.
 Tao.GetSolutionStatusResult getSolutionStatus()
          Get the current iterate, objective value, residual,
infeasibility, and termination
 ConvergenceFlags getTerminationReason()
          Gets the reason the TAO_SOLVER iteration was stopped.
 void getTolerances(double[] fatol, double[] frtol, double[] catol, double[] crtol)
          Gets convergence parameters.
 double getTrustRegionRadius()
          Gets the current trust region radius
 Tao.GetVariableBoundsResult getVariableBounds()
          Sets the vector pointers to the vectors
containing the upper and lower bounds on the variables.
static void Initialize()
           
static void Initialize(java.lang.String programName, java.lang.String[] args, boolean mpi)
           
protected  void nativeCreate()
           
 void printStatement(java.lang.String statement)
          prints a character string to stdout.
static void registerAll(java.lang.String path)
          Registers all of the minimization methods in the TAO_SOLVER package.
static void registerDestroy()
          Frees the list of minimization solvers that were
registered by TaoRegisterDynamic().
 void resetSolver()
          Take down the data structures created in TaoCreate__XXX().
 void setApplication(TaoApplication taoapp)
           
 void setConvergenceHistory(double[] a, int[] its, int na, boolean reset)
          Sets the array used to hold the convergence history.
 void setDown()
          Take down the data structures created in TaoSetUp().
 void setFromOptions()
          Sets many TAO_SOLVER parameters from the command line arguments.
 void setFunctionLowerBound(double fmin)
          Sets a bound on the solution objective value.
 void setGradientTolerances(double gatol, double grtol, double gttol)
          Sets the stopping criteria in terms of the norm
of the Lagrangian function.
 void setMaximumFunctionEvaluations(int nfcn)
          Sets a maximum number of
function evaluations.
 void setMaximumIterates(int maxits)
          Sets a maximum number of iterates.
 void setMethod(Tao.Method method)
           
 void setTerminationReason(ConvergenceFlags reason)
          Sets the termination reason
 void setTolerances(double fatol, double frtol, double catol, double crtol)
          Sets convergence parameters.
 void setTrustRegionRadius(double radius)
          Sets the initial trust region radius.
 void setTrustRegionTolerance(double steptol)
          Sets a minimum step size or trust region radius.
 void setVariableBounds(TaoVec xxll, TaoVec xxuu)
          Sets lower and upper bounds on the variables.
 void solve()
          Solves an unconstrained minimization problem.
 double testGradient(Vec x, boolean verbose)
          testGradient calculates finite difference gradient (fd) and compares it with the hand coded one (hc).
 double testHessian(Vec x, boolean verbose)
          testGradient calculates finite difference hessian (fd) and compares it with the hand coded one (hc).
 void view()
          Prints the TAO_SOLVER data structure.
 void viewLinearSolver()
          View the linear solver
 
Methods inherited from class de.jtem.jpetsc.PrimitivNative
getNativeObjectToString, load, toString
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Tao

public Tao(int comm,
           Tao.Method method)

Tao

public Tao(Tao.Method method)
Method Detail

nativeCreate

protected void nativeCreate()
Specified by:
nativeCreate in class Native

finalize

public void finalize()
              throws java.lang.Throwable
Overrides:
finalize in class PrimitivNative
Throws:
java.lang.Throwable

Initialize

public static void Initialize()

Initialize

public static void Initialize(java.lang.String programName,
                              java.lang.String[] args,
                              boolean mpi)

Finalize

public static void Finalize()

setApplication

public void setApplication(TaoApplication taoapp)

setMethod

public void setMethod(Tao.Method method)

createFiniteDifferenceTester

public static Tao createFiniteDifferenceTester(boolean testGradient,
                                               boolean testHessian)

testGradient

public double testGradient(Vec x,
                           boolean verbose)
testGradient calculates finite difference gradient (fd) and compares it with the hand coded one (hc). If it returns 0 (1.e-8), the hand-coded gradient is probably correct.

Parameters:
x - position to test at
verbose - print some interesting stuff on System.out
Returns:
||fd - hc|| / ||hc||
See Also:
TaoApplication.defaultComputeGradient(de.jtem.jpetsc.Vec, de.jtem.jpetsc.Vec), TaoApplication.computeGradient(de.jtem.jpetsc.Vec, de.jtem.jpetsc.Vec), createFiniteDifferenceTester(boolean, boolean)

testHessian

public double testHessian(Vec x,
                          boolean verbose)
testGradient calculates finite difference hessian (fd) and compares it with the hand coded one (hc). If it returns 0 (1.e-8), the hand-coded hessian is probably correct.

Parameters:
x - position to test at
verbose - print some interesting stuff on System.out
Returns:
||fd - hc|| / ||hc||
See Also:
TaoApplication.defaultComputeHessian(Vec, Mat), TaoApplication.computeHessian(Vec), createFiniteDifferenceTester(boolean, boolean)

printStatement

public void printStatement(java.lang.String statement)
prints a character string to stdout.
Not Collective

Parameters:
statement - the string to print

registerDestroy

public static void registerDestroy()
Frees the list of minimization solvers that were
registered by TaoRegisterDynamic().
Not Collective

See Also:
registerAll(java.lang.String)

getSolutionStatus

public Tao.GetSolutionStatusResult getSolutionStatus()
Get the current iterate, objective value, residual,
infeasibility, and termination

Returns:
Tao.GetSolutionStatusResult
See Also:
#monitor, getTerminationReason()

checkConvergence

public ConvergenceFlags checkConvergence()
Checks the convergence of the solver

Returns:
one of $ TAO_CONVERGED_ATOL (2), (res <= atol) $ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol) $ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol) $ TAO_CONVERGED_MINF (5), (f <= fmin) $ TAO_CONVERGED_USER (6), (user defined) $ TAO_DIVERGED_MAXITS (-2), (its>maxits) $ TAO_DIVERGED_NAN (-4), (Numerical problems) $ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts) $ TAO_DIVERGED_LS_FAILURE (-6), (line search failure) $ TAO_DIVERGED_TR_REDUCTION (-7), $ TAO_DIVERGED_USER (-8), (user defined) $ TAO_CONTINUE_ITERATING (0)

where

xdiff
current trust region size
rtol
relative tolerance
res0
initial residual of optimality conditions
res
residual of optimality conditions
maxits
maximum number of iterates
maxnfuncts
maximum number of function evaluations
nfunc
number of function evaluations
f
function value
its
current iterate number
atol
absolute tolerance
See Also:
getTerminationReason()

view

public void view()
Prints the TAO_SOLVER data structure.

See Also:
getTerminationReason(), getSolutionStatus(), viewLinearSolver()

setGradientTolerances

public void setGradientTolerances(double gatol,
                                  double grtol,
                                  double gttol)
Sets the stopping criteria in terms of the norm
of the Lagrangian function. The algorithm will terminate when the norm
of the gradient is less that the absolute tolerance, or when the norm
of the gradient has been reduced by a factor of the reduction tolerance,
or when the norm of the gradient divided by the absolute value of the
objective function is less than the relative tolerance.

Parameters:
gatol - stop if norm of gradient is less than
grtol - stop if relative norm of gradient is less than
gttol - stop if norm of gradient is reduced by a factor of
See Also:
setTolerances(double, double, double, double), getGradientTolerances()

getGradientTolerances

public Tao.GetGradientTolerancesResult getGradientTolerances()
Returns the gradient termination tolerances.

Returns:
Tao.GetGradientTolerancesResult
See Also:
setGradientTolerances(double, double, double)

setFunctionLowerBound

public void setFunctionLowerBound(double fmin)
Sets a bound on the solution objective value.
When an approximate solution with an objective value below this number
has been found, the solver will terminate.

Parameters:
fmin - the tolerance
See Also:
setTolerances(double, double, double, double)

setMaximumIterates

public void setMaximumIterates(int maxits)
Sets a maximum number of iterates.

Parameters:
maxits - the maximum number of iterates (>=0)
See Also:
setTolerances(double, double, double, double), setMaximumFunctionEvaluations(int)

setMaximumFunctionEvaluations

public void setMaximumFunctionEvaluations(int nfcn)
Sets a maximum number of
function evaluations.

Parameters:
nfcn - the maximum number of function evaluations (>=0)
See Also:
setTolerances(double, double, double, double), setMaximumIterates(int)

setTolerances

public void setTolerances(double fatol,
                          double frtol,
                          double catol,
                          double crtol)
Sets convergence parameters. TAO tries to satisfy an
absolute stopping criteria or a relative stopping criteria.

Parameters:
fatol - absolute convergence tolerance
frtol - relative convergence tolerance
catol - allowable error in constraints
crtol - allowable relative error in constraints
See Also:
setMaximumIterates(int), setTrustRegionTolerance(double), setGradientTolerances(double, double, double), setMaximumFunctionEvaluations(int)

getTolerances

public void getTolerances(double[] fatol,
                          double[] frtol,
                          double[] catol,
                          double[] crtol)
Gets convergence parameters.

Parameters:
fatol - absolute convergence tolerance
frtol - relative convergence tolerance
catol - trust region convergence tolerance
crtol - convergence of the function evaluates less than this tolerance
See Also:
setTolerances(double, double, double, double)

clearMonitor

public void clearMonitor()
Clears all the monitor functions for a TAO_SOLVER object.

See Also:
#defaultMonitor, #setMonitor

getTerminationReason

public ConvergenceFlags getTerminationReason()
Gets the reason the TAO_SOLVER iteration was stopped.
Not Collective

Returns:
one of $ TAO_CONVERGED_ATOL (2), (res <= atol) $ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol) $ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol) $ TAO_CONVERGED_MINF (5), (f <= fmin) $ TAO_CONVERGED_USER (6), (user defined) $ TAO_DIVERGED_MAXITS (-2), (its>maxits) $ TAO_DIVERGED_NAN (-4), (Numerical problems) $ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts) $ TAO_DIVERGED_LS_FAILURE (-6), (line search failure) $ TAO_DIVERGED_TR_REDUCTION (-7), $ TAO_DIVERGED_USER (-8), (user defined) $ TAO_CONTINUE_ITERATING (0)

where

xdiff
current trust region size
rtol
relative tolerance
res0
initial residual of optimality conditions
res
residual of optimality conditions
maxits
maximum number of iterates
maxnfuncts
maximum number of function evaluations
nfunc
number of function evaluations
f
function value
its
current iterate number
atol
absolute tolerance
See Also:
#setConvergenceTest, setTolerances(double, double, double, double)

setConvergenceHistory

public void setConvergenceHistory(double[] a,
                                  int[] its,
                                  int na,
                                  boolean reset)
Sets the array used to hold the convergence history.

Parameters:
a - array to hold history
its - integer array holds the number of linear iterations (or
negative if not converged) for each solve.
na - size of a and its
reset - TAO_TRUE indicates each new minimization resets the history counter to zero,
else it continues storing new values for new minimizations after the old ones
See Also:
#getConvergenceHistory

solve

public void solve()
Solves an unconstrained minimization problem. Call TaoSolve()
after calling TaoCreate() and optional routines of the form TaoSetXXX().

See Also:
#create, destroy()

getMethod

public java.lang.String getMethod()
Gets the TAO_SOLVER method type and name (as a string).
Not Collective

Returns:
TAO_SOLVER method (a charactor string)

setTrustRegionTolerance

public void setTrustRegionTolerance(double steptol)
Sets a minimum step size or trust region radius. The
solver will terminate when the step size or radius of the trust region is smaller
than this tolerance.

Parameters:
steptol - tolerance
See Also:
setTolerances(double, double, double, double)

getTrustRegionRadius

public double getTrustRegionRadius()
Gets the current trust region radius

Returns:
the trust region radius
See Also:
setTrustRegionRadius(double), setTrustRegionTolerance(double)

getInitialTrustRegionRadius

public double getInitialTrustRegionRadius()
Gets the initial trust region radius

Returns:
the initial trust region radius
See Also:
getTrustRegionRadius(), setTrustRegionRadius(double)

setTrustRegionRadius

public void setTrustRegionRadius(double radius)
Sets the initial trust region radius.

Parameters:
radius - the trust region radius
See Also:
getTrustRegionRadius(), setTrustRegionTolerance(double)

setVariableBounds

public void setVariableBounds(TaoVec xxll,
                              TaoVec xxuu)
Sets lower and upper bounds on the variables.

Parameters:
xxll - vector of lower bounds upon the solution vector
xxuu - vector of upper bounds upon the solution vector
See Also:
getVariableBounds(), #appSetVariableBounds

getDualVariables

public void getDualVariables(TaoVec DXL,
                             TaoVec DXU)
Gets the dual variables corresponding to
the bounds of the variables.

Parameters:
DXL - vector to place the dual variables of the lower bounds
DXU - vector to place the dual variables of the upper bounds
See Also:
getVariableBounds()

getVariableBounds

public Tao.GetVariableBoundsResult getVariableBounds()
Sets the vector pointers to the vectors
containing the upper and lower bounds on the variables.

Returns:
Tao.GetVariableBoundsResult

setTerminationReason

public void setTerminationReason(ConvergenceFlags reason)
Sets the termination reason

Parameters:
reason - one of
$ TAO_CONVERGED_ATOL (2), (res <= atol)
$ TAO_CONVERGED_RTOL (3), (res/res0 <= rtol)
$ TAO_CONVERGED_TRTOL (4), (xdiff <= trtol)
$ TAO_CONVERGED_MINF (5), (f <= fmin)
$ TAO_CONVERGED_USER (6), (user defined)
$ TAO_DIVERGED_MAXITS (-2), (its>maxits)
$ TAO_DIVERGED_NAN (-4), (Numerical problems)
$ TAO_DIVERGED_MAXFCN (-5), (nfunc > maxnfuncts)
$ TAO_DIVERGED_LS_FAILURE (-6), (line search failure)
$ TAO_DIVERGED_TR_REDUCTION (-7),
$ TAO_DIVERGED_USER (-8), (user defined)
$ TAO_CONTINUE_ITERATING (0)

where

xdiff
current trust region size
rtol
relative tolerance
res0
initial residual of optimality conditions
res
residual of optimality conditions
maxits
maximum number of iterates
maxnfuncts
maximum number of function evaluations
nfunc
number of function evaluations
f
function value
its
current iterate number
atol
absolute tolerance
See Also:
getTerminationReason(), #appSetMonitor, #setMonitor

setFromOptions

public void setFromOptions()
Sets many TAO_SOLVER parameters from the command line arguments.
This command does not set the solver type.

See Also:
#setMethodFromOptions

setDown

public void setDown()
Take down the data structures created in TaoSetUp().
These structures typically include the work vectors, and linear solver.

See Also:
#setUp, destroy()

resetSolver

public void resetSolver()
Take down the data structures created in TaoCreate__XXX().
This routine destroys the line search, and the solver context. It
also set many of the solver routines for solving, options, duals, viewing,
setup, and destroy to TAO_NULL.

See Also:
#create, setMethod(de.jtem.jtao.Tao.Method), setDown(), destroy()

registerAll

public static void registerAll(java.lang.String path)
Registers all of the minimization methods in the TAO_SOLVER package.
Not Collective

Parameters:
path -
See Also:
registerDestroy()

getJacobian

public TaoMat getJacobian()
Get the Jacobian matrix

Returns:
Jacobian Matrix
See Also:
application, #EvaluateJacobian, #appSetConstraintRoutine

getSolution

public TaoVec getSolution()
Sets a pointer to a TaoVec to the address of the
vector containing the current solution.

Returns:
the solution
See Also:
#create, getGradient(), setApplication(de.jtem.jtao.TaoApplication)

getGradient

public TaoVec getGradient()
Sets a pointer to the address of a TaoVector that
contains the gradient of the Lagrangian function.

Returns:
the gradient of the Lagrangian function
See Also:
getSolution(), getSolutionStatus(), #getHessian, setApplication(de.jtem.jtao.TaoApplication)

viewLinearSolver

public void viewLinearSolver()
View the linear solver

See Also:
view(), #linearSolve