#include <deal.II/trilinos/rol_adaptor.h>

Detailed Description

template<typename VectorType>
class TrilinosWrappers::ROLAdaptor< VectorType >

An adaptor that provides an interface to the Rapid Optimization Library (ROL), a Trilinos package.

This class provides the implementation of the ROL::Vector interface for vectors of type VectorType. It supports vectors that satisfy the following requirements:

The VectorType should contain the following types.

VectorType::size_type;  // The type for size of the vector.
VectorType::value_type; // The type for elements stored in the vector.
VectorType::real_type;  // The type for real-valued numbers.

However, ROL doesn't distinguish ROLAdaptor::value_type from ROLAdaptor::real_type. This is due to ROL's assumption that the ROLAdaptor::value_type itself is a type for real-valued numbers. Therefore, ROLAdaptor supports vectors whose real_type is convertible to value_type in the sense that std::is_convertible_v<real_type, value_type> yields true.

The VectorType should contain the following methods.

// Reinitialize the current vector using a given vector's
// size (and the parallel distribution) without copying
// the elements.
void VectorType::reinit(const VectorType &, ...);
 
// Copies the data of a given vector to the current.
// Resize the current vector if necessary (MPI safe).
VectorType& VectorType::operator=(const VectorType &);
 
// Return the global size of the current vector.
VectorType::size_type VectorType::size();
 
// Access the value of the ith component.
VectorType::value_type&
VectorType::operator[](const VectorType::size_type i);
 
// Compress the vector i.e., flush the buffers of the
// vector object if it has any.
void VectorType::compress(VectorOperation);

Note: The current implementation in ROL doesn't support vector sizes above the largest value of int type. Some of the vectors in deal.II (see Vector) may not satisfy the above requirements.

Optimization and finite elements

Numerical optimization can be a useful tool in the context of finite element methods. However, not all degrees of freedom of a finite element discretization should really be part of the optimization space – typically those that are constrained through boundary conditions and hanging nodes should be excluded from the optimization process.

This can be achieved in two different ways: either through constrained optimization; or by reducing the optimization space which allows unconstrained optimization. For the latter, one way to do it is explicitly defining those vector elements that correspond to the optimization space. All operations necessary for the optimization process would only see these specified entries, which are effectively only a subspace of the finite element discretization.

This wrapper class provides a means for defining the optimization space using an IndexSet upon construction.

Ghost elements on distributed vectors

This wrapper class also manages all distributed vector classes of deal.II.

ROL will manipulate the wrapped vector during the optimization progress. For vector classes of the PETScWrappers and TrilinosWrappers namespaces, this manipulation is only allowed on vectors without ghost elements. For the LinearAlgebra::distributed::Vector class, manipulation with ghost elements is permitted, although it requires a potentially slow ghost exchange. For more information on ghost vectors, see also the corresponding glossary entry.

To enforce the same behavior of this wrapper on all distributed vectors classes, we only allow manipulating operations for vectors without ghost elements.

Definition at line 126 of file rol_adaptor.h.

Inheritance diagram for TrilinosWrappers::ROLAdaptor< VectorType >:

[legend]

Public Member Functions
	ROLAdaptor (const ROL::Ptr< VectorType > &vector_ptr)

	ROLAdaptor (const ROL::Ptr< VectorType > &vector_ptr, const IndexSet &optimization_space)

ROL::Ptr< VectorType >	getVector ()

ROL::Ptr< const VectorType >	getVector () const

int	dimension () const override

void	set (const ROL::Vector< value_type > &rol_vector) override

void	plus (const ROL::Vector< value_type > &rol_vector) override

void	axpy (const value_type alpha, const ROL::Vector< value_type > &rol_vector) override

void	scale (const value_type alpha) override

value_type	dot (const ROL::Vector< value_type > &rol_vector) const override

value_type	norm () const override

ROL::Ptr< ROL::Vector< value_type > >	clone () const override

ROL::Ptr< ROL::Vector< value_type > >	basis (const int i) const override

void	applyUnary (const ROL::Elementwise::UnaryFunction< value_type > &f) override

void	applyBinary (const ROL::Elementwise::BinaryFunction< value_type > &f, const ROL::Vector< value_type > &rol_vector) override

value_type	reduce (const ROL::Elementwise::ReductionOp< value_type > &r) const override

void	print (std::ostream &outStream) const override

Private Types
using	size_type = typename VectorType::size_type

using	value_type = typename VectorType::value_type

using	real_type = typename VectorType::real_type

Private Attributes
ROL::Ptr< VectorType >	vector_ptr

IndexSet	optimization_space

::types::global_dof_index	global_opt_dimension

::types::global_dof_index	local_opt_start_index

Member Typedef Documentation

◆ size_type

template<typename VectorType >

using TrilinosWrappers::ROLAdaptor< VectorType >::size_type = typename VectorType::size_type

private

An alias for size type of VectorType.

Definition at line 131 of file rol_adaptor.h.

◆ value_type

template<typename VectorType >

using TrilinosWrappers::ROLAdaptor< VectorType >::value_type = typename VectorType::value_type

private

An alias for element type stored in the VectorType.

Definition at line 136 of file rol_adaptor.h.

◆ real_type

template<typename VectorType >

using TrilinosWrappers::ROLAdaptor< VectorType >::real_type = typename VectorType::real_type

private

An alias for real-valued numbers.

Definition at line 141 of file rol_adaptor.h.

Constructor & Destructor Documentation

◆ ROLAdaptor() [1/2]

template<typename VectorType >

TrilinosWrappers::ROLAdaptor< VectorType >::ROLAdaptor ( const ROL::Ptr< VectorType > & vector_ptr )

Constructor.

This constructor does not take an index set as argument (for this, see the other constructor) and as a consequence considers all variables represented by the vector as available to optimization.

◆ ROLAdaptor() [2/2]

template<typename VectorType >

TrilinosWrappers::ROLAdaptor< VectorType >::ROLAdaptor	(	const ROL::Ptr< VectorType > &	vector_ptr,
		const IndexSet &	optimization_space
	)

Constructor.

The IndexSet optimization_space specifies entries in the wrapped vector to which the optimization process will be applied. It needs to be equal to or a subset of the locally owned indices of the wrapped vector.

Passing in the complete index set (partitioned among processors) is equivalent to the previous constructor.

Member Function Documentation

◆ getVector() [1/2]

template<typename VectorType >

ROL::Ptr< VectorType > TrilinosWrappers::ROLAdaptor< VectorType >::getVector ( )

Return the ROL pointer to the wrapped vector.

◆ getVector() [2/2]

template<typename VectorType >

ROL::Ptr< const VectorType > TrilinosWrappers::ROLAdaptor< VectorType >::getVector ( ) const

Return the ROL pointer to the wrapped vector as read-only.

◆ dimension()

template<typename VectorType >

int TrilinosWrappers::ROLAdaptor< VectorType >::dimension ( ) const

override

Return the global dimension of the optimization space.

◆ set()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::set ( const ROL::Vector< value_type > & rol_vector )

override

Set the wrapped vector to a given rol_vector by overwriting its contents.

If the current wrapped vector has ghost elements, then VectorType::operator=(const VectorType&) should still be allowed on it.

Note: rol_vector has to be of type ROLAdaptor.

◆ plus()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::plus ( const ROL::Vector< value_type > & rol_vector )

override

Add rol_vector to the wrapped vector.

The operation will only be applied to elements of the specified optimization space. Both vectors need to correspond to the same optimization space.

Note: rol_vector has to be of type ROLAdaptor.

◆ axpy()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::axpy	(	const value_type	alpha,
		const ROL::Vector< value_type > &	rol_vector
	)

override

Scale the wrapped vector by alpha and add rol_vector to it.

The operation will only be applied to elements of the specified optimization space. Both vectors need to correspond to the same optimization space.

Note: rol_vector has to be of type ROLAdaptor.

◆ scale()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::scale ( const value_type alpha )

override

Scale the wrapped vector by alpha.

The operation will only be applied to elements of the specified optimization space.

◆ dot()

template<typename VectorType >

value_type TrilinosWrappers::ROLAdaptor< VectorType >::dot ( const ROL::Vector< value_type > & rol_vector ) const

override

Return the dot product with a given rol_vector.

The operation will only be applied to elements of the specified optimization space. Both vectors need to correspond to the same optimization space.

Note: rol_vector has to be of type ROLAdaptor.

◆ norm()

template<typename VectorType >

value_type TrilinosWrappers::ROLAdaptor< VectorType >::norm ( ) const

override

Return the \(L^{2}\) norm of the wrapped vector.

The operation will only be applied to elements of the specified optimization space.

The returned type is of ROLAdaptor::value_type so as to maintain consistency with ROL::Vector<ROLAdaptor::value_type> and more importantly to not to create an overloaded version namely, ROLAdaptor::real_type norm() const; if real_type and value_type are not of the same type.

◆ clone()

template<typename VectorType >

ROL::Ptr< ROL::Vector< value_type > > TrilinosWrappers::ROLAdaptor< VectorType >::clone ( ) const

override

Create and return a ROL pointer to a clone of the wrapped vector. The cloned vector has the same size as the wrapped vector, but is initialized with zeros.

◆ basis()

template<typename VectorType >

ROL::Ptr< ROL::Vector< value_type > > TrilinosWrappers::ROLAdaptor< VectorType >::basis ( const int i ) const

override

Create and return a ROL pointer to the basis vector corresponding to the i \({}^{th}\) element of the global optimization space.

◆ applyUnary()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::applyUnary ( const ROL::Elementwise::UnaryFunction< value_type > & f )

override

Apply unary function f to all the elements of the wrapped vector.

The operation will only be applied to elements of the specified optimization space.

◆ applyBinary()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::applyBinary	(	const ROL::Elementwise::BinaryFunction< value_type > &	f,
		const ROL::Vector< value_type > &	rol_vector
	)

override

Apply binary function f along with ROL::Vector rol_vector to all the elements of the wrapped vector.

The operation will only be applied to elements of the specified optimization space. Both vectors need to correspond to the same optimization space.

Note: rol_vector has to be of type ROLAdaptor.

◆ reduce()

template<typename VectorType >

value_type TrilinosWrappers::ROLAdaptor< VectorType >::reduce ( const ROL::Elementwise::ReductionOp< value_type > & r ) const

override

Return the accumulated value on applying reduction operation r on all the elements of the wrapped vector.

The operation will only be applied to elements of the specified optimization space.

◆ print()

template<typename VectorType >

void TrilinosWrappers::ROLAdaptor< VectorType >::print ( std::ostream & outStream ) const

override

Print the wrapped vector to the output stream outStream.

This function will print the entire vector, and not just the elements of the specified optimization space.

Member Data Documentation

◆ vector_ptr

template<typename VectorType >

ROL::Ptr<VectorType> TrilinosWrappers::ROLAdaptor< VectorType >::vector_ptr

private

ROL pointer to the underlying vector of type VectorType.

Definition at line 151 of file rol_adaptor.h.

◆ optimization_space

template<typename VectorType >

IndexSet TrilinosWrappers::ROLAdaptor< VectorType >::optimization_space

private

IndexSet that represents the locally owned optimization space.

Definition at line 156 of file rol_adaptor.h.

◆ global_opt_dimension

template<typename VectorType >

::types::global_dof_index TrilinosWrappers::ROLAdaptor< VectorType >::global_opt_dimension

private

Global dimension of the optimization space.

Definition at line 161 of file rol_adaptor.h.

◆ local_opt_start_index

template<typename VectorType >

::types::global_dof_index TrilinosWrappers::ROLAdaptor< VectorType >::local_opt_start_index

private

Prefix sum of the number of elements in the optimization space of lower rank MPI processes.

Denotes the starting index in the optimization space, at which the locally owned elements of the wrapped vector begin.

Definition at line 170 of file rol_adaptor.h.

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

include/deal.II/trilinos/rol_adaptor.h

Detailed Description

Optimization and finite elements

Ghost elements on distributed vectors

Public Member Functions

Private Types

Private Attributes

Member Typedef Documentation

◆ size_type

◆ value_type

◆ real_type

Constructor & Destructor Documentation

◆ ROLAdaptor() [1/2]

◆ ROLAdaptor() [2/2]

Member Function Documentation

◆ getVector() [1/2]

◆ getVector() [2/2]

◆ dimension()

◆ set()

◆ plus()

◆ axpy()

◆ scale()

◆ dot()

◆ norm()

◆ clone()

◆ basis()

◆ applyUnary()

◆ applyBinary()

◆ reduce()

◆ print()

Member Data Documentation

◆ vector_ptr

◆ optimization_space

◆ global_opt_dimension

◆ local_opt_start_index