NLP second order information interface class {abstract}. More...

#include <NLPInterfacePack_NLPSecondOrder.hpp>

Inheritance diagram for NLPInterfacePack::NLPSecondOrder:

Classes
struct	SecondOrderInfo
	Struct for zero, first and second order quantities (pointers) More...

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

Public Types inherited from NLPInterfacePack::NLPFirstOrder
typedef Teuchos::RCP< const Teuchos::AbstractFactory < MatrixOp > >	mat_fcty_ptr_t

typedef Teuchos::RCP< BasisSystem >	basis_sys_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

Protected Member Functions
const SecondOrderInfo	second_order_info () const
	Return objective gradient and zero order information. More...

Protected Member Functions inherited from NLPInterfacePack::NLPFirstOrder
const FirstOrderInfo	first_order_info () const
	Return objective gradient and zero order information. More...

virtual void	imp_calc_Gc (const Vector &x, bool newx, const FirstOrderInfo &first_order_info) const =0
	Overridden to compute Gc(x) and perhaps Gf(x), f(x) and c(x). 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...

Constructors
	NLPSecondOrder ()
	Initialize to no reference set to calculation quanities. More...

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

Matrix factory objects
virtual const mat_sym_fcty_ptr_t	factory_HL () const =0
	Return a matrix factory object for creating `HL`. More...

<<std aggr>> members for the Hessian of the Lagrangian HL
virtual void	set_HL (MatrixSymOp *HL)
	Set a pointer to a matrix object to be updated when `this->calc_HL()` is called. More...

virtual MatrixSymOp *	get_HL ()
	Return pointer passed to `this->set_HL()`. More...

virtual MatrixSymOp &	HL ()
	Returns non-`const` `*this->get_HL()`. More...

virtual const MatrixSymOp &	HL () const
	Returns `const` `*this->get_HL()`. More...

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

Calculation Members
virtual void	calc_HL (const Vector &x, const Vector *lambda, bool newpoint=true) const
	Update the matrix for `HL` at the point `x`, `lambda`, `lambdaI` and put it in the stored reference. More...

Number of function evaluations
virtual size_type	num_HL_evals () const
	Number of Hessian evaluations. More...

Protected methods to be overridden by subclasses
virtual void	imp_calc_HL (const Vector &x, const Vector *lambda, bool newpoint, const SecondOrderInfo &second_order_info) const =0
	Overridden to compute `Gc(x)` and perhaps `Gf(x)`, `f(x)` and `c(x)`. More...

Additional Inherited Members
Public Member Functions inherited from NLPInterfacePack::NLPFirstOrder
	NLPFirstOrder ()
	Initialize to no reference set to calculation quanities. More...

virtual const mat_fcty_ptr_t	factory_Gc () const =0
	Return a matrix factory object for creating `Gc`. More...

virtual const basis_sys_ptr_t	basis_sys () const
	Return a `BasisSystem` object compatible with `Gc` and `Gh`. More...

virtual void	set_Gc (MatrixOp *Gc)
	Set a pointer to a matrix object to be updated when `this->calc_Gc()` is called. More...

virtual MatrixOp *	get_Gc ()
	Return pointer passed to `this->set_Gc()`. More...

virtual MatrixOp &	Gc ()
	Returns non-`const` `*this->get_Gc()`. More...

virtual const MatrixOp &	Gc () const
	Returns `const` `*this->get_Gc()`. More...

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

virtual size_type	num_Gc_evals () const
	Gradient of constraints matrix `Gc` evaluations count. More...

Public Member Functions inherited from NLPInterfacePack::NLPObjGrad
	NLPObjGrad ()
	Initialize to no reference set to calculation quanities. 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...

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

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

Detailed Description

NLP second order information interface class {abstract}.

Overview:

This class adds second order inforamtion to the first order information and basic information given in the NLPFirstOrder and base interfaces.

Specifically the Hesssian of the Lagrangian is defined as:

HL = Hf + sum( Hc(j) * lambda(j), j = 1...m )

Where:

Hf is the hessian of the objective function f(x)
Hc(j) is the hessian of the jth equality constriant c_j(x)
lambda is the vector of lagrange multipliers for the equality constraints c(x)

Client Usage:

ToDo: Finish Documentation!

Subclass developer's notes:

ToDo: Finish Documentation!

Definition at line 77 of file NLPInterfacePack_NLPSecondOrder.hpp.

Member Typedef Documentation

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

Definition at line 82 of file NLPInterfacePack_NLPSecondOrder.hpp.

Constructor & Destructor Documentation

NLPInterfacePack::NLPSecondOrder::NLPSecondOrder ( )

Initialize to no reference set to calculation quanities.

Definition at line 53 of file NLPInterfacePack_NLPSecondOrder.cpp.

Member Function Documentation

void NLPInterfacePack::NLPSecondOrder::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), Gf(x), Gc(x), Gh(x) and HL(x) evaluations. This implementation calls this->NLPFirstOrder::initialize()

Postconditions:

See NLPFirstOrder::initialize()
this->num_HL_evals() == 0

Reimplemented from NLPInterfacePack::NLPFirstOrder.

Definition at line 58 of file NLPInterfacePack_NLPSecondOrder.cpp.

virtual const mat_sym_fcty_ptr_t NLPInterfacePack::NLPSecondOrder::factory_HL ( ) const

pure virtual

Return a matrix factory object for creating HL.

The returned matrix object may not support the creation of any sub-matrix spaces (i.e. return->sub_space(rrng,crng).get() == NULL for all rrng and crng).

void NLPInterfacePack::NLPSecondOrder::set_HL ( MatrixSymOp * HL )

virtual

Set a pointer to a matrix object to be updated when this->calc_HL() is called.

Parameters

HL	[in] Pointer to Hessian of the Lagrangian matrix. May be `NULL`.

Preconditions:

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

Postconditions:

this->get_HL() == HL

Definition at line 65 of file NLPInterfacePack_NLPSecondOrder.cpp.

MatrixSymOp * NLPInterfacePack::NLPSecondOrder::get_HL ( )

virtual

Return pointer passed to this->set_HL().

Preconditions:

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

Definition at line 70 of file NLPInterfacePack_NLPSecondOrder.cpp.

MatrixSymOp & NLPInterfacePack::NLPSecondOrder::HL ( )

virtual

Returns non-const *this->get_HL().

Preconditions:

this->is_initialized() == true (throw NotInitialized)
this->get_HL() != NULL (throw NoRefSet)

Definition at line 75 of file NLPInterfacePack_NLPSecondOrder.cpp.

const MatrixSymOp & NLPInterfacePack::NLPSecondOrder::HL ( ) const

virtual

Returns const *this->get_HL().

Preconditions:

this->is_initialized() == true (throw NotInitialized)
this->get_HL() != NULL (throw NoRefSet)

Definition at line 80 of file NLPInterfacePack_NLPSecondOrder.cpp.

void NLPInterfacePack::NLPSecondOrder::unset_quantities ( )

virtual

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

Preconditions:

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

Postconditions:

See NLPFirstOrder::unset_quantities()
this->get_HL() == NULL

This method must be called by all subclasses that override it.

Reimplemented from NLPInterfacePack::NLPFirstOrder.

Definition at line 85 of file NLPInterfacePack_NLPSecondOrder.cpp.

void NLPInterfacePack::NLPSecondOrder::calc_HL	(	const Vector &	x,
		const Vector *	lambda,
		bool	newpoint = `true`
	)		const

virtual

Update the matrix for HL at the point x, lambda, lambdaI and put it in the stored reference.

The referenced storage for f, c, Gf and Gc may also be changed but are not guarentied to be. But no other quanities from possible subclasses are allowed to be updated as a side effect.

Parameters

x	[in] Unknown primal variables
lambda	[in] Lagrange muitipliers for equality constriants. If `m() == 0` then `lambda` must be `NULL`. However, if `m() > 0` then `lambda == NULL` is still allowed and is treated as `lambda = 0`.
newpoint	[in] (default `true`) If `false`, the values in `x`, `lambda` and `lambdaI` are the same as the last call to `this->calc_HL()`. If `true`, then this is a new point.

Preconditions:

this->is_initialized() == true (throw NotInitialized)
x.space().is_compatible(*this->space_x()) == true (throw VectorSpace::IncompatibleVectorSpaces)
this->get_HL() != NULL (throw NoRefSet)
[this->m() == 0] lambda == NULL (throw std::invalid_argument)
[this->m() != 0 && lambda != 0] lambda->space().is_compatible(*this->space_c()) == true) (throw std::invalid_argument)

Postconditions:

this->HL() is updated to HL(x)

Definition at line 93 of file NLPInterfacePack_NLPSecondOrder.cpp.

size_type NLPInterfacePack::NLPSecondOrder::num_HL_evals ( ) const

virtual

Number of Hessian evaluations.

This function can be called to find out how many evaluations the client requested since initialize() was called.

Definition at line 104 of file NLPInterfacePack_NLPSecondOrder.cpp.

const NLPSecondOrder::SecondOrderInfo NLPInterfacePack::NLPSecondOrder::second_order_info ( ) const

inlineprotected

Return objective gradient and zero order information.

Definition at line 311 of file NLPInterfacePack_NLPSecondOrder.hpp.

virtual void NLPInterfacePack::NLPSecondOrder::imp_calc_HL	(	const Vector &	x,
		const Vector *	lambda,
		bool	newpoint,
		const SecondOrderInfo &	second_order_info
	)		const

protectedpure virtual

Overridden to compute Gc(x) and perhaps Gf(x), f(x) and c(x).

Parameters

x	[in] Unknown vector (size n).
lambda	[in] Lagrange multipliers for equality constraints c(x). Must be `NULL` if `m() == 0`. If `NULL`, then treated as `lambda = 0`.
newpoint	[in] (default `true`) If `false`, the values in `x`, `lambda` and `lambdaI` are the same as the last call to `this->calc_HL()`. If `true`, then this is a new point.
second_order_info	[out] Pointers to `HL`, `Gc`, `Gh`, `Gf`, `f`, `c` and `h` On output `second_order_info.HL` is updated to HL(x)*. Any of the other objects pointed to in `second_order_info` may also be updated but are not guaranteed to be.

Preconditions:

x.space().is_compatible(*this->space_x()) (throw IncompatibleType)
second_order_info.HL != NULL (throw std::invalid_argument)

Postconditions:

*second_order_info.HL is updated to HL(x).

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

Classes

Public Types

Protected Member Functions

Constructors

NLP initialization

Matrix factory objects

<<std aggr>> members for the Hessian of the Lagrangian HL

Unset calculation quantities

Calculation Members

Number of function evaluations

Protected methods to be overridden by subclasses

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation