Concrete class that tests the computed values of the NLPDirect
interface using finite differences.
More...
#include <NLPInterfacePack_NLPDirectTester.hpp>
Public Types  
enum  ETestingMethod 
More...  
Public Member Functions  
STANDARD_COMPOSITION_MEMBERS (CalcFiniteDiffProd, calc_fd_prod)  
 
STANDARD_MEMBER_COMPOSITION_MEMBERS (ETestingMethod, Gf_testing_method)  
Members for option Gf_testing_method() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (ETestingMethod, Gc_testing_method)  
Members for option Gc_testing_method() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gf_warning_tol)  
Members for option Gf_warning_tol() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gf_error_tol)  
Members for option Gf_error_tol() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gc_warning_tol)  
Members for option Gc_warning_tol() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gc_error_tol)  
Members for option Gc_error_tol() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (size_type, num_fd_directions)  
Members for option num_fd_directions() .  
STANDARD_MEMBER_COMPOSITION_MEMBERS (bool, dump_all)  
Members for option dump_all() .  
NLPDirectTester (const calc_fd_prod_ptr_t &calc_fd_prod=Teuchos::null, ETestingMethod Gf_testing_method=FD_DIRECTIONAL, ETestingMethod Gc_testing_method=FD_DIRECTIONAL, value_type Gf_warning_tol=1e6, value_type Gf_error_tol=1e1, value_type Gc_warning_tol=1e6, value_type Gc_error_tol=1e1, size_type num_fd_directions=1, bool dump_all=false)  
Constructor.  
bool  finite_diff_check (NLPDirect *nlp, const Vector &xo, const Vector *xl, const Vector *xu, const Vector *c, const Vector *Gf, const Vector *py, const Vector *rGf, const MatrixOp *GcU, const MatrixOp *D, const MatrixOp *Uz, bool print_all_warnings, std::ostream *out) const 
This function takes an NLP object and its computed derivatives and function values and validates the functions and the derivatives by evaluating them about the given point xo . 
Concrete class that tests the computed values of the NLPDirect
interface using finite differences.
There are two options for testing the derivatives by finite differences. Each option can be picked independently for the computations with the objective f(x)
and its gradient Gf
and for the constraints c(x) and its Jacobian Gc'
. The tests involving the objective and the constraints will be discussed separatly.
For testing the gradient of the objective function, two options are available. The first option (Gf_testing_method==FD_COMPUTE_ALL
) is to compute FDGf
by brute force which requries 2*n
evaluations of f(x) using central differences. Given FDGf
the following comparison is then made:
(1) FDGf \approx Gf
The other option (Gf_testing_method==FD_DIRECTIONAL
) is to compute random dot products of the form DFGf'*y
where y
is a randomly generated vector. Using central differences DFGf'*y
can be computed using two evaluations of f(x) per random y
. The number of random y
's used is determined by the option num_fd_directions()
. So the number of evaluations of f(x) for this option is 2*num_fd_directions()
.
The test for the quantity py = inv(C)*c(con_decomp)
is shown below:
(2)  FDC * (inv(C)*c) \approx c(c_decomp) \_________/ py
Computing FDC * py
requires only two evaluations of c(x) using central differences. There is no other option needed for this test.
Lastly, we have to test D = inv(C)*N
. The first option (Gc_testing_method==FD_COMPUTE_ALL
) is to directly compute N
using central differences (2*(nm)
evaluations of c(x)) as FDN
and then perform the comparison:
(3)  FDC * (inv(C)*N) \approx FDN \_________/ D
The matrix FDC * D
can be computed using 2*(nm)
evaluations with c(x) using central differences. Therefore, the total number of evaluations with c(x) for comparing (3) is 4*(nm)
. If nm
is not too large then this is definitely the preferred method to use.
The other option for testing D = inv(C)*N
is to compute directional derivatives using finite differences. In this approach, for the random vector y
, we can compute:
(4)  FDC * (inv(C)*N) * y \approx FDN * y \_________/ D
Using central differences, (4) can be computed with 4 evaluations of c(x). The number of random y
's used is determined by the option num_fd_directions()
. So the number of evaluations of c(x) for this option is 4*num_fd_directions()
.
The client can pick a set of tolerances to measure if the values of the above comparisons are close enough to the finite difference values. Let's define the relative error between the computed value and the finite difference value to be:
err(i) =  (h(i)  fdh(i))  / (hinf + fdhinf + sqrt(epsilon))
The above error takes into account the relative sizes of the elements and also allows one or both of the elements to be zero without ending up with 0/0 or something like 1e16
not comparing with zero.
All errors err(i) >= warning_tol
are reported to *out
if out != NULL
. The first error err(i) >= error_tol
that is found is reported to *out
if out != NULL
and immediatly finite_diff_check()
returns false
. If all errors err(i) < error_tol
, then finite_diff_check()
will return true
.
Given these two tolerances the client can do many things:
1) Print out all the comparisons that are not equal by setting warning_tol <= epsilon
and error_tol >> 1
.
2) Print out all suspect comparisons by setting epsilon < warning_tol < 1
and error_tol >> 1
.
3) Just validate that the quantities are approximatly equal and report the first discrepency if not by setting epsilon < error_tol < 1
and warning_tol >= error_tol
.
4) Print out any suspect comparisons by setting epsilon < warning_tol < 1
but also quit if the error is too large by setting 1 > error_tol > warning_tol
.
The tolerances Gf_warning_tol
and Gf_error_tol
are applied to the tests for Gf
shown in (1) for instance. The tolerances Gc_warning_tol
and Gc_error_tol
are used for the comparisions (2), (3) and (4).
There is one minor hitch to this testing. For many NLPs, there is a * strict region of x where f(x) or c(x) are not defined. In order to help ensure that we stay out of these regions, variable bounds and a scalar max_var_bounds_viol
can be included so that the testing software will never evaluate f(x) or c(x) outside the region:
xl  max_var_bounds_viol <= x <= xu + max_var_bounds_viol
This is an important agreement made with the user.
Definition at line 154 of file NLPInterfacePack_NLPDirectTester.hpp.
Definition at line 158 of file NLPInterfacePack_NLPDirectTester.hpp.
NLPInterfacePack::NLPDirectTester::NLPDirectTester  (  const calc_fd_prod_ptr_t &  calc_fd_prod = Teuchos::null , 

ETestingMethod  Gf_testing_method = FD_DIRECTIONAL , 

ETestingMethod  Gc_testing_method = FD_DIRECTIONAL , 

value_type  Gf_warning_tol = 1e6 , 

value_type  Gf_error_tol = 1e1 , 

value_type  Gc_warning_tol = 1e6 , 

value_type  Gc_error_tol = 1e1 , 

size_type  num_fd_directions = 1 , 

bool  dump_all = false  
) 
Constructor.
Definition at line 57 of file NLPInterfacePack_NLPDirectTester.cpp.
NLPInterfacePack::NLPDirectTester::STANDARD_COMPOSITION_MEMBERS  (  CalcFiniteDiffProd  ,  
calc_fd_prod  
) 
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  ETestingMethod  ,  
Gf_testing_method  
) 
Members for option Gf_testing_method()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  ETestingMethod  ,  
Gc_testing_method  
) 
Members for option Gc_testing_method()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  value_type  ,  
Gf_warning_tol  
) 
Members for option Gf_warning_tol()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  value_type  ,  
Gf_error_tol  
) 
Members for option Gf_error_tol()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  value_type  ,  
Gc_warning_tol  
) 
Members for option Gc_warning_tol()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  value_type  ,  
Gc_error_tol  
) 
Members for option Gc_error_tol()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  size_type  ,  
num_fd_directions  
) 
Members for option num_fd_directions()
.
NLPInterfacePack::NLPDirectTester::STANDARD_MEMBER_COMPOSITION_MEMBERS  (  bool  ,  
dump_all  
) 
Members for option dump_all()
.
bool NLPInterfacePack::NLPDirectTester::finite_diff_check  (  NLPDirect *  nlp,  
const Vector &  xo,  
const Vector *  xl,  
const Vector *  xu,  
const Vector *  c,  
const Vector *  Gf,  
const Vector *  py,  
const Vector *  rGf,  
const MatrixOp *  GcU,  
const MatrixOp *  D,  
const MatrixOp *  Uz,  
bool  print_all_warnings,  
std::ostream *  out  
)  const 
This function takes an NLP object and its computed derivatives and function values and validates the functions and the derivatives by evaluating them about the given point xo
.
If all the checks as described in the intro checkout then this function will return true, otherwise it will return false.
If the finite difference steps are limited by relaxed variable bounds then a warning message is printed and the derivatives computed could be very inaccurate.
nlp  [in] NLP object used to compute and test derivatives for.  
xo  [in] Point at which the derivatives are computed at.  
xl  [in] If != NULL then this is the lower variable bounds.  
xu  [in] If != NULL then this is the upper variable bounds. If xl != NULL then xu != NULL must also be true and visaversa or a std::invalid_arguement exceptions will be thrown.  
c  [in] Value of c(x) computed at xo. If NULL, then none of the tests involving it will be performed.  
Gf  [in] Gradient of f(x) computed at xo. If NULL, then none of the tests involving it will be performed.  
py  [in] Newton step py = inv(C) * c(con_decomp) If NULL, then none of the tests involving it will be performed.  
rGf  [in] Reduced gradient of the objective function rGf = Gf(var_indep)  D' * Gf(var_dep). If NULL, then none of the tests involving it will be performed.  
GcU  [in] Auxiliary jacobian matrix del(c(con_undecomp),x) . If NULL, htne none of the tests involving it will be performed.  
D  [in] Direct sensitivity matrix D = inv(C)*N . If NULL, none of the tests involving it will be performed.  
Uz  [in] Uz = F + E * D , which is the an auxiliary sensitivity matrix. If NULL, then none of the tests involving it will be performed.  
print_all_warnings  [in] If true then all errors greater than warning_tol will be printed if out!=NULL  
out  [in/out] If != null then some summary information is printed to it and if a derivative does not match up then it prints which derivative failed. If out == 0 then no output is printed. 
true
if all the derivatives comparisons are within the error tolerances or returns false otherwise. This function will return false if any NaN or Inf values where encountered. Definition at line 82 of file NLPInterfacePack_NLPDirectTester.cpp.