Interface providing only direct first order sensitivity information. More...

#include <NLPInterfacePack_NLPDirect.hpp>

Inheritance diagram for NLPInterfacePack::NLPDirect:

Public Types
typedef Teuchos::RCP< const Teuchos::AbstractFactory < MatrixOp > >	mat_fcty_ptr_t

typedef Teuchos::RCP< const Teuchos::AbstractFactory < MatrixSymOp > >	mat_sym_fcty_ptr_t

typedef Teuchos::RCP< const Teuchos::AbstractFactory < MatrixSymOpNonsing > >	mat_sym_nonsing_fcty_ptr_t

Public Types inherited from NLPInterfacePack::NLP
typedef Teuchos::RCP< const VectorSpace >	vec_space_ptr_t

typedef Teuchos::RCP< const OptionsFromStreamPack::OptionsFromStream >	options_ptr_t

Public Member Functions
void	set_factories (const mat_sym_fcty_ptr_t &factory_transDtD, const mat_sym_nonsing_fcty_ptr_t &factory_S)
	Initialize the factory objects for the special matrices for `D'D` and `S = I + D'D`. More...

Public Member Functions inherited from NLPInterfacePack::NLPObjGrad
	NLPObjGrad ()
	Initialize to no reference set to calculation quanities. More...

void	initialize (bool test_setup)
	Initialize the NLP for its first use. More...

virtual bool	supports_Gf () const
	Determine if the objective gradient is supported or not. More...

virtual bool	supports_Gf_prod () const
	Determine if the objective gradient product is supported or not. More...

virtual void	set_Gf (VectorMutable *Gf)
	Set a pointer to a vector to be updated when `this->calc_Gf()` is called. More...

virtual VectorMutable *	get_Gf ()
	Return pointer passed to `this->set_Gf()`. More...

virtual VectorMutable &	Gf ()
	Returns non-`const` `*this->get_Gf()`. More...

virtual const Vector &	Gf () const
	Returns `const` `*this->get_Gf()`. More...

void	unset_quantities ()
	Call to unset all storage quantities (both in this class and all subclasses). More...

virtual void	calc_Gf (const Vector &x, bool newx=true) const
	Update the vector for `Gf` at the point `x` and put it in the stored reference. More...

virtual value_type	calc_Gf_prod (const Vector &x, const Vector &d, bool newx=true) const
	Calculate the inner product `Gf(x)'*d` at the point `x` and put it in the stored reference. More...

virtual size_type	num_Gf_evals () const
	Objective gradient evaluations count. More...

Public Member Functions inherited from NLPInterfacePack::NLP
const ZeroOrderInfo	zero_order_info () const
	Return pointer to set quantities. More...

const ZeroOrderInfo	zero_order_info_breve () const
	Return pointer to set `hat` quantities. More...

	NLP ()
	Initialize to no reference set to calculation quanities. More...

virtual	~NLP ()
	Destructor that cleans all the memory it owns. More...

virtual void	force_xinit_in_bounds (bool force_xinit_in_bounds)=0
	Set if the initial point must be within the bounds. More...

virtual bool	force_xinit_in_bounds () const =0
	Returns if the initial point must be within the bounds. More...

virtual void	set_options (const options_ptr_t &options)
	Set the options that `this` NLP may be interested in. More...

virtual const options_ptr_t &	get_options () const
	Get the `OptionsFromStream` object being used to extract the options from. More...

virtual bool	is_initialized () const =0
	Return if `this` is initialized. More...

virtual size_type	n () const
	Return the number of variables. More...

virtual size_type	m () const
	Return the number of general equality constraints. More...

virtual vec_space_ptr_t	space_x () const =0
	Vector space object for unknown variables x (dimension n). More...

virtual vec_space_ptr_t	space_c () const =0
	Vector space object for general equality constraints c(x) (dimension m). More...

virtual size_type	num_bounded_x () const =0
	Returns the number of variables in `x(i)` for which `xl(i)> -infinite_bound()` or `xu(i) < +infinite_bound()`. More...

virtual const Vector &	xl () const =0
	Returns the lower bounds on the variables `x`. More...

virtual const Vector &	xu () const =0
	Returns a reference to the vector of upper bounds on the variables `x`. More...

virtual value_type	max_var_bounds_viol () const =0
	Set the maximum absolute value for which the variable bounds may be violated by when computing function and gradient values. More...

virtual const Vector &	xinit () const =0
	Returns a reference to the vector of the initial guess for the solution `x`. More...

virtual void	get_init_lagrange_mult (VectorMutable lambda, VectorMutable nu) const
	Get the initial value of the Lagrange multipliers lambda. More...

virtual void	set_f (value_type *f)
	Set a pointer to an value to be updated when `this->calc_f()` is called. More...

virtual value_type *	get_f ()
	Return pointer passed to `this->set_f()`. More...

virtual value_type &	f ()
	Returns non-`const` `*this->get_f()`. More...

virtual const value_type &	f () const
	Returns `const` `*this->get_f()`. More...

virtual void	set_c (VectorMutable *c)
	Set a pointer to a vector to be updated when `this->calc_c()` is called. More...

virtual VectorMutable *	get_c ()
	Return pointer passed to `this->set_c()`. More...

virtual VectorMutable &	c ()
	Returns non-`const` `*this->get_c()`. More...

virtual const Vector &	c () const
	Returns `const` `*this->get_c()`. More...

virtual void	scale_f (value_type scale_f)=0
	Set the scaling of the objective function. More...

virtual value_type	scale_f () const =0
	Return the scaling being used for the objective function. More...

virtual void	calc_f (const Vector &x, bool newx=true) const
	Update the value for the objective `f` at the point `x` and put it in the stored reference. More...

virtual void	calc_c (const Vector &x, bool newx=true) const
	Update the constraint residual vector for `c` at the point `x` and put it in the stored reference. More...

virtual void	report_final_solution (const Vector &x, const Vector lambda, const Vector nu, bool is_optimal)
	Used by the solver to report the final solution and multipliers. More...

virtual size_type	num_f_evals () const
	Gives the number of object function f(x) evaluations called by the solver since initialize() was called. More...

virtual size_type	num_c_evals () const
	Gives the number of constraint function c(x) evaluations called by the solver since initialize() was called. Throws exception if `this->m() == 0`. More...

virtual size_type	ns () const
	Return the number of slack variables (i.e. number of general inequalities). More...

virtual vec_space_ptr_t	space_c_breve () const
	Vector space object for the original equalities `c_breve(x_breve)` More...

virtual vec_space_ptr_t	space_h_breve () const
	Vector space object for the original inequalities `h_breve(x_breve)` More...

virtual const Vector &	hl_breve () const
	Returns a reference to the vector of lower bounds on the general inequality constraints `h_breve(x_breve)`. More...

virtual const Vector &	hu_breve () const
	Returns a reference to the vector of upper bounds on the general inequality constraints `h_breve(x_breve)`. More...

virtual void	set_c_breve (VectorMutable *c_breve)
	Set a pointer to a vector to be updated when `this->calc_c_breve()` is called. More...

virtual VectorMutable *	get_c_breve ()
	Return pointer passed to `this->set_c_breve()`. More...

virtual VectorMutable &	c_breve ()
	Returns non-`const` `*this->get_c_breve()`. More...

virtual const Vector &	c_breve () const
	Returns `const` `*this->get_c_breve()`. More...

virtual void	set_h_breve (VectorMutable *h_breve)
	Set a pointer to a vector to be updated when `this->calc_h_breve()` is called. More...

virtual VectorMutable *	get_h_breve ()
	Return pointer passed to `this->set_h_breve()`. More...

virtual VectorMutable &	h_breve ()
	Returns non-`const` `*this->get_h_breve()`. More...

virtual const Vector &	h_breve () const
	Returns `const` `*this->get_h_breve()`. More...

virtual const Permutation &	P_var () const
	Return the permutation object for the variables. More...

virtual const Permutation &	P_equ () const
	Return the permutation object for the constraints. More...

virtual void	calc_c_breve (const Vector &x, bool newx=true) const
	Update the constraint residual vector for `c_breve` at the point `x` and put it in the stored reference. More...

virtual void	calc_h_breve (const Vector &x, bool newx=true) const
	Update the constraint residual vector for `h_breve` at the point `x` and put it in the stored reference. More...

Dimensionality
virtual size_type	r () const
	Returns the number of decomposed equality constraints (`r <= m`). More...

Ranges for dependent and independent variables and decomposed and undecomposed equalities
virtual Range1D	var_dep () const
	Return the range of dependent (i.e. basic) variables. More...

virtual Range1D	var_indep () const
	Return the range of independent (i.e. nonbasic) variables. More...

virtual Range1D	con_decomp () const
	Return the range of decomposed equality constraints. More...

virtual Range1D	con_undecomp () const
	Return the range of undecomposed equality constraints. More...

Matrix factory objects
virtual const mat_fcty_ptr_t	factory_GcU () const
	Return a matrix factory object for creating `GcU`. More...

virtual const mat_fcty_ptr_t	factory_D () const =0
	Return a matrix factory object for `D = -inv(C)*N` {abstract}. More...

virtual const mat_fcty_ptr_t	factory_Uz () const
	Return a matrix factory object for `Uz = F + E * D`. More...

virtual const mat_fcty_ptr_t	factory_GcUD () const
	Return a matrix factory object for a mutable matrix compatible with `GcU(var_dep)`. More...

virtual const mat_sym_fcty_ptr_t	factory_transDtD () const
	Returns a matrix factory for the result of `J = D'*D` More...

virtual const mat_sym_nonsing_fcty_ptr_t	factory_S () const
	Returns a matrix factory for the result of `S = I + D'*D` More...

Calculation members
virtual void	calc_point (const Vector &x, value_type f, VectorMutable c, bool recalc_c, VectorMutable Gf, VectorMutable py, VectorMutable rGf, MatrixOp GcU, MatrixOp D, MatrixOp Uz) const =0
	Compute all of the needed quanities for direct sensitivities. More...

virtual void	calc_semi_newton_step (const Vector &x, VectorMutable c, bool recalc_c, VectorMutable py) const =0
	Calculate an approximate newton step given the Jacobian computed for the last call to `calc_point()`. More...

Overridden from NLP
void	initialize (bool test_setup)
	Initialize the NLP for its first use. More...

Additional Inherited Members
Static Public Member Functions inherited from NLPInterfacePack::NLP
static value_type	infinite_bound ()
	Value for an infinite bound. More...

Protected Member Functions inherited from NLPInterfacePack::NLPObjGrad
const ObjGradInfo	obj_grad_info () const
	Return objective gradient and zero order information. More...

virtual void	imp_calc_Gf (const Vector &x, bool newx, const ObjGradInfo &obj_grad_info) const =0
	Overridden to compute f(x) and perhaps c(x) (if multiple calculaiton = true). More...

Protected Member Functions inherited from NLPInterfacePack::NLP
template<class T >
void	assert_ref_set (T *p, std::string info) const
	Assert referece has been set for a quanity. More...

virtual void	imp_calc_f (const Vector &x, bool newx, const ZeroOrderInfo &zero_order_info) const =0
	Overridden to compute f(x) (and perhaps other quantities if set). More...

virtual void	imp_calc_c (const Vector &x, bool newx, const ZeroOrderInfo &zero_order_info) const =0
	Overridden to compute c(x) and perhaps f(x) and/or h(x) (if multiple calculaiton = true). More...

virtual void	imp_calc_c_breve (const Vector &x, bool newx, const ZeroOrderInfo &zero_order_info_breve) const
	Overridden to compute c_breve(x_breve) and perhaps f(x) and/or h_breve(x_breve) More...

virtual void	imp_calc_h_breve (const Vector &x, bool newx, const ZeroOrderInfo &zero_order_info_breve) const
	Overridden to compute h_breve(x_breve) and perhaps f(x) and/or c_breve(x_breve). More...

Detailed Description

Interface providing only direct first order sensitivity information.

Overview:

This interface defines a basis for the equality constriants and then only certain linear systems with this basis are solved for. This interface is useful in reduced space SQP-type and other related optimization algorithms.

Specifically, the variables are partitioned into dependent and independent sets x = [ x_dep' x_indep' ]' and Jacobians of the constraints c(x) at the point x are:

 del(c,x) = Gc' = [ del(c(con_decomp))   ] = [ GcD' ] = [ GcDD'  GcDI' ] = [ C  N ]
                  [ del(c(con_undecomp)) ]   [ GcU' ]   [ GcUD'  GcUI' ]   [ E  F ]

   where:
     C <: R^(r x r) is nonsingular
     N <: R^(r x (n-r))
     E <: R^((m-r) x r)
     F <: R^((m-r) x (n-r))

This partitions the general equality constraints c(x) into two sets; decomposed c(con_decomp) and undecomposed c(con_undecomp). It is therefore expected that sub-vectors and subspaces from space_x().sub_space(var_dep), space_x().sub_space(var_indep), space_c().sub_space(con_decomp) and space_c().sub_space(con_undecomp) can all be accessed. Other sub-vectors and sub-spaces may not be available (but the algorithm should not need access to other sub-spaces).

Free access to solves with the basis C is not given however and instead this interface computes, for the current point x, the direct sensitivity matrice D = -inv(C)*N, the auxiliary matrices Uz = F + E * D and GcU = [ GcUD; GcUI ] = [ E'; F' ], and the Newton step py = -inv(C)*c(con_decomp). In general, linear solves with the transpose with C are not possible and therefore are not avalible. A number of very specialized applications can only provide this information but this is all that is needed by many numerical optimization (and related) algorithms.

Client Usage:

The dimension of the basis matrix C is returned by r(). The ranges for the dependent and independent varaibles are returned by var_dep() and var_indep(). The ranges for the decomposed and undecomposed equality constraints are con_decomp() and con_undecomp(). Note that con_undecomp() will return an invalid range if there are no undecomposed equalities.

Note that the matrix objects returned from factory_GcU(), factory_D() and factory_Uz() can not be expected to be usable until they are passed to the calculation routines or have been intialized in some other way.

Subclass Developer's Notes:

The default implementation of this interface assumes that there are no undecomposed equality constraints (i.e. this->con_decomp().size() == this->m()).

ToDo: Finish Documentation!

Definition at line 111 of file NLPInterfacePack_NLPDirect.hpp.

Member Typedef Documentation

typedef Teuchos::RCP< const Teuchos::AbstractFactory<MatrixOp> > NLPInterfacePack::NLPDirect::mat_fcty_ptr_t

Definition at line 117 of file NLPInterfacePack_NLPDirect.hpp.

typedef Teuchos::RCP< const Teuchos::AbstractFactory<MatrixSymOp> > NLPInterfacePack::NLPDirect::mat_sym_fcty_ptr_t

Definition at line 120 of file NLPInterfacePack_NLPDirect.hpp.

typedef Teuchos::RCP< const Teuchos::AbstractFactory<MatrixSymOpNonsing> > NLPInterfacePack::NLPDirect::mat_sym_nonsing_fcty_ptr_t

Definition at line 123 of file NLPInterfacePack_NLPDirect.hpp.

Member Function Documentation

void NLPInterfacePack::NLPDirect::set_factories	(	const mat_sym_fcty_ptr_t &	factory_transDtD,
		const mat_sym_nonsing_fcty_ptr_t &	factory_S
	)

Initialize the factory objects for the special matrices for D'*D and S = I + D'*D.

Postconditions:

this->factory_transDtD().get() == factory_transDtD.get()
this->factory_S().get() == factory_S.get()

Definition at line 53 of file NLPInterfacePack_NLPDirect.cpp.

size_type NLPInterfacePack::NLPDirect::r ( ) const

virtual

Returns the number of decomposed equality constraints (r <= m).

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation returns this->con_decomp().size(). This implementation will work for all implementations.

Definition at line 62 of file NLPInterfacePack_NLPDirect.cpp.

Range1D NLPInterfacePack::NLPDirect::var_dep ( ) const

virtual

Return the range of dependent (i.e. basic) variables.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation returns Range1D(1,this->m()).

Definition at line 67 of file NLPInterfacePack_NLPDirect.cpp.

Range1D NLPInterfacePack::NLPDirect::var_indep ( ) const

virtual

Return the range of independent (i.e. nonbasic) variables.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation returns Range1D(this->m()+1,this->n()).

Definition at line 71 of file NLPInterfacePack_NLPDirect.cpp.

Range1D NLPInterfacePack::NLPDirect::con_decomp ( ) const

virtual

Return the range of decomposed equality constraints.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation returns Range1D(1,this->m()).

Definition at line 75 of file NLPInterfacePack_NLPDirect.cpp.

Range1D NLPInterfacePack::NLPDirect::con_undecomp ( ) const

virtual

Return the range of undecomposed equality constraints.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation returns Range1D::Invalid.

Definition at line 80 of file NLPInterfacePack_NLPDirect.cpp.

const NLPDirect::mat_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_GcU ( ) const

virtual

Return a matrix factory object for creating GcU.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation is to return return.get() == NULL. This is the proper implementation when m() == r(). When m() > r() then the subclass must override this method to return a valid matrix factory object. Moreover, the returned matrix object from this->factory_GcU()->create()->get_sub_view(rng,Range1D()) must be non-null for rng == this->var_dep() or rng == this->var_indep(). This gives access to the matrices E' and F' as shown above.

Definition at line 86 of file NLPInterfacePack_NLPDirect.cpp.

virtual const mat_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_D ( ) const

pure virtual

Return a matrix factory object for D = -inv(C)*N {abstract}.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

const NLPDirect::mat_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_Uz ( ) const

virtual

Return a matrix factory object for Uz = F + E * D.

Preconditions:

this->is_initialized() == true (throw NotInitialized)

The default implementation is to return return.get() == NULL. This is the correct implementation when m() == r(). However, when m() > r() this method must be overridden to return a non-null matrix factory object.

Definition at line 92 of file NLPInterfacePack_NLPDirect.cpp.

const NLPDirect::mat_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_GcUD ( ) const

virtual

Return a matrix factory object for a mutable matrix compatible with GcU(var_dep).

This matrix factory object is designed to create mutable matrix objects compatible with GcU(var_dep). For example, a matrix object Uy created by this matrix factory can be used to compute Uy = Gc(var_dep,con_undecomp)' - Gc(var_indep,con_undecomp)'*D' (this is needed by a orthogonal range/null decomposition.

The default implementation is to return return.get() == NULL. This is the correct implementation when m() == r(). However, when m() > r() this method must be overridden to return a non-null matrix factory object.

Definition at line 98 of file NLPInterfacePack_NLPDirect.cpp.

const NLPDirect::mat_sym_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_transDtD ( ) const

virtual

Returns a matrix factory for the result of J = D'*D

The resulting matrix is symmetric but is assumed to be singular.

Definition at line 104 of file NLPInterfacePack_NLPDirect.cpp.

const NLPDirect::mat_sym_nonsing_fcty_ptr_t NLPInterfacePack::NLPDirect::factory_S ( ) const

virtual

Returns a matrix factory for the result of S = I + D'*D

The resulting matrix is symmetric and is guarrenteed to be nonsingular

Definition at line 110 of file NLPInterfacePack_NLPDirect.cpp.

virtual void NLPInterfacePack::NLPDirect::calc_point	(	const Vector &	x,
		value_type *	f,
		VectorMutable *	c,
		bool	recalc_c,
		VectorMutable *	Gf,
		VectorMutable *	py,
		VectorMutable *	rGf,
		MatrixOp *	GcU,
		MatrixOp *	D,
		MatrixOp *	Uz
	)		const

pure virtual

Compute all of the needed quanities for direct sensitivities.

Parameters

x	[in] (dim == n()) Current value of unkowns. This vector should have been created by `this->space_x()->create_member()`.
f	[out] Value of `f(x)`. If f == NULL then this quantity is not computed.
c	[in/out] (dim == m()) Value of the equality constraints c(x). If `c == NULL` then this quantity is not computed. If c != NULL and `recalc_c == true` then this quantity is recomputed. If c != NULL and `recalc_c == false` then this quantity is not recomputed and is used in the computation of `py` if requested (i.e. `py != NULL`). If `c != NULL` this this vector should have been created by `this->space_c()->create_member()`.
recalc_c	[in] If `true` then `c` will be recomputed at `x`. If `false` then `c` will not be recomputed but will be used as stated above.
Gf	[out] (dim == n()) Gradient of `f(x)`. If `Gf == NULL` then this quantity is not computed. If `Gf!=NULL` this this vector should have been created by `this->space_x()->create_member()`.
py	[out] (dim == r()) `py = -inv(C)*c(con_decomp)`. If `py == NULL` then this quantity is not computed. If `recalc_c == false` on input then the input `c != NULL` argument may be used in the computation of `py`. If `py!=NULL` this this vector should have been created by `this->space_x()->sub_space(this->var_dep())->create_member()`.
rGf	[out] (dim == n()-r()) `rGf = Gf(var_indep()) + D'*Gf(var_dep())`, which is the reduced gradient of the objective function projected into the manifold of the decomposed equality constraints. If `rGf==NULL`, this vector is not computed. If `rGf!=NULL` then this vector should have been created by `this->space_x(this->var_indep())->create_member()`.
GcU	[out] (dim = n x (m()-r())) Auxiliary jacobian matrix `del(c(con_undecomp),x)`. If m() == r() then `GcU` should be set to `NULL` on input. If GcU == NULL then this quantitiy is not computed. If `!=NULL` this this matrix should have been created by `this->factory_GcU()->create()`.
D	[out] (dim = r() x (n()-r())) `D = -inv(C)*N`, which is the direct sensitivity of the constraints to the independent variables. If D == NULL then this quantity is not computed. If `!=NULL` this this matrix should have been created by `this->factory_D()->create()`.
Uz	[out] (dim = (m()-r()) x (n()-r())) `Uz = F + E * D`, which is the an auxiliary sensitivity matrix. If `m() == r()` then `Uz` should be set to `NULL` on input. If `Uz==NULL` then this quantity is not computed. If `!=NULL` this this matrix should have been created by `this->factory_Uz()->create()`.

Preconditions:

this->is_initialized() == true (throw NotInitialized)
Lots more!

virtual void NLPInterfacePack::NLPDirect::calc_semi_newton_step	(	const Vector &	x,
		VectorMutable *	c,
		bool	recalc_c,
		VectorMutable *	py
	)		const

pure virtual

Calculate an approximate newton step given the Jacobian computed for the last call to calc_point().

The idea behind this method is that with some applications it may be much cheaper to compute an approximate Newton step for the constraints given information computed during the last call to calc_point(). It is assumed that this approximate solution py will still be a descent direction for c(x). Some subclasses may have to perform an equal amount of work as calc_point(...) to perform this calculation but those are the breaks.

Parameters

x	[in] (dim == n()) current value of unkowns.
c	[out] (dim == m()) Value of the constraints c(x) If c == NULL then this quantity is not computed. If c != NULL and recalc_c == true on input then this quantity is not recomputed and is used in the computation of py if requested (i.e. py!=NULL).
recalc_c
py	[out] (size == r() on output) Approximate value of -inv(C)*c Note that py == NULL is not allowed here.

Preconditions:

this->is_initialized() == true (throw NotInitialized)
Lots more.

void NLPInterfacePack::NLPDirect::initialize ( bool test_setup )

virtual

Initialize the NLP for its first use.

This function implementation should be called by subclass implementations in order to reset counts for f(x), c(x), h(x) and Gf(x) evaluations. This implementation calls this->NLPObjGrad::initialize()

Postconditions:

See NLPObjGrad::initialize()

Reimplemented from NLPInterfacePack::NLP.

Definition at line 115 of file NLPInterfacePack_NLPDirect.cpp.

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

Public Types

Public Member Functions

Dimensionality

Ranges for dependent and independent variables and decomposed and undecomposed equalities

Matrix factory objects

Calculation members

Overridden from NLP

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Function Documentation