NLPInterfacePack: C++ Interfaces and Implementation for NonLinear Programs Version of the Day

Interface providing only direct first order sensitivity information. More...
#include <NLPInterfacePack_NLPDirect.hpp>
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 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 .  
Dimensionality  
virtual size_type  r () const 
Returns the number of decomposed equality constraints (r <= m ).  
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.  
virtual Range1D  var_indep () const 
Return the range of independent (i.e. nonbasic) variables.  
virtual Range1D  con_decomp () const 
Return the range of decomposed equality constraints.  
virtual Range1D  con_undecomp () const 
Return the range of undecomposed equality constraints.  
Matrix factory objects  
virtual const mat_fcty_ptr_t  factory_GcU () const 
Return a matrix factory object for creating GcU .  
virtual const mat_fcty_ptr_t  factory_D () const =0 
Return a matrix factory object for D = inv(C)*N {abstract}.  
virtual const mat_fcty_ptr_t  factory_Uz () const 
Return a matrix factory object for Uz = F + E * D .  
virtual const mat_fcty_ptr_t  factory_GcUD () const 
Return a matrix factory object for a mutable matrix compatible with GcU(var_dep) .  
virtual const mat_sym_fcty_ptr_t  factory_transDtD () const 
Returns a matrix factory for the result of J = D'*D  
virtual const mat_sym_nonsing_fcty_ptr_t  factory_S () const 
Returns a matrix factory for the result of S = I + D'*D  
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.  
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() .  
Overridden from NLP  
void  initialize (bool test_setup) 
Initialize the NLP for its first use. 
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 SQPtype 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 (nr)) E <: R^((mr) x r) F <: R^((mr) x (nr))
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 subvectors 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 subvectors and subspaces may not be available (but the algorithm should not need access to other subspaces).
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.
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.
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:
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 nonnull 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 nonnull 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 nonnull 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.
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
) 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.
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
) 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:
Reimplemented from NLPInterfacePack::NLPObjGrad.
Definition at line 115 of file NLPInterfacePack_NLPDirect.cpp.