NLPInterfacePack::NLPDirectTester Class Reference

Concrete class that tests the computed values of the NLPDirect interface using finite differences. More...

#include <NLPInterfacePack_NLPDirectTester.hpp>

Public Types
enum	ETestingMethod { FD_COMPUTE_ALL, FD_DIRECTIONAL }

Public Member Functions
	STANDARD_COMPOSITION_MEMBERS (CalcFiniteDiffProd, calc_fd_prod)
	STANDARD_MEMBER_COMPOSITION_MEMBERS (ETestingMethod, Gf_testing_method)
	Members for option Gf_testing_method() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (ETestingMethod, Gc_testing_method)
	Members for option Gc_testing_method() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gf_warning_tol)
	Members for option Gf_warning_tol() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gf_error_tol)
	Members for option Gf_error_tol() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gc_warning_tol)
	Members for option Gc_warning_tol() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (value_type, Gc_error_tol)
	Members for option Gc_error_tol() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (size_type, num_fd_directions)
	Members for option num_fd_directions() More...
	STANDARD_MEMBER_COMPOSITION_MEMBERS (bool, dump_all)
	Members for option dump_all() More...
	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=1e-6, value_type Gf_error_tol=1e-1, value_type Gc_warning_tol=1e-6, value_type Gc_error_tol=1e-1, size_type num_fd_directions=1, bool dump_all=false)
	Constructor. More...
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. More...

Detailed Description

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*(n-m) 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*(n-m) evaluations with c(x) using central differences. Therefore, the total number of evaluations with c(x) for comparing (3) is 4*(n-m). If n-m 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)) | /  (||h||inf + ||fdh||inf + 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 1e-16 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 167 of file NLPInterfacePack_NLPDirectTester.hpp.

Member Enumeration Documentation

enum NLPInterfacePack::NLPDirectTester::ETestingMethod

Enumerator
FD_COMPUTE_ALL
FD_DIRECTIONAL

Definition at line 171 of file NLPInterfacePack_NLPDirectTester.hpp.

Constructor & Destructor Documentation

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 = 1e-6,
		value_type	Gf_error_tol = 1e-1,
		value_type	Gc_warning_tol = 1e-6,
		value_type	Gc_error_tol = 1e-1,
		size_type	num_fd_directions = 1,
		bool	dump_all = false
	)

Constructor.

Definition at line 70 of file NLPInterfacePack_NLPDirectTester.cpp.

Member Function Documentation

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.

Parameters

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 visa-versa 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.

Returns

Returns 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 95 of file NLPInterfacePack_NLPDirectTester.cpp.

---

The documentation for this class was generated from the following files:

• NLPInterfacePack_NLPDirectTester.hpp
• NLPInterfacePack_NLPDirectTester.cpp