Debian Codegraph @

include/deal.II/optimization/rol/vector_adaptor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_optimization_rol_vector_adaptor_h
16 #define dealii_optimization_rol_vector_adaptor_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_TRILINOS_WITH_ROL
21 # include <deal.II/base/exceptions.h>
22
23 # include <deal.II/lac/vector.h>
24
25 # include <ROL_Vector.hpp>
26
27 # include <limits>
28 # include <type_traits>
29
30
31 DEAL_II_NAMESPACE_OPEN
32
33 /**
34 * A namespace that provides an interface to the
35 * <a href="https://trilinos.org/docs/dev/packages/rol/doc/html/index.html">
36 * Rapid Optimization Library</a> (ROL), a Trilinos package.
37 */
38 namespace Rol
39 {
40 /**
41 * An adaptor that provides the implementation of the ROL::Vector interface
42 * for vectors of type <tt>VectorType</tt>.
43 *
44 * This class supports vectors that satisfy the following requirements:
45 *
46 * The <tt>VectorType</tt> should contain the following types.
47 * ```
48 * VectorType::size_type; // The type for size of the vector.
49 * VectorType::value_type; // The type for elements stored in the vector.
50 * VectorType::real_type; // The type for real-valued numbers.
51 * ```
52 *
53 * However, ROL doesn't distinguish VectorAdaptor::value_type from
54 * VectorAdaptor::real_type. This is due to ROL's assumption that the
55 * VectorAdaptor::value_type itself is a type for real-valued numbers.
56 * Therefore, VectorAdaptor supports vectors whose real_type is
57 * convertible to value_type in the sense that
58 * <code>std::is_convertible_v<real_type, value_type></code> yields
59 * <code>true</code>.
60 *
61 * The <tt>VectorType</tt> should contain the following methods.
62 * @code
63 * // Reinitialize the current vector using a given vector's
64 * // size (and the parallel distribution) without copying
65 * // the elements.
66 * VectorType::reinit(const VectorType &, ...);
67 *
68 * // Globally add a given vector to the current.
69 * VectorType::operator+=(const VectorType &);
70 *
71 * // Scale all elements by a given scalar.
72 * VectorType::operator*=(const VectorType::value_type &);
73 *
74 * // Perform dot product with a given vector.
75 * VectorType::operator*=(const VectorType &);
76 *
77 * // Scale all elements of the current vector and globally
78 * // add a given vector to it.
79 * VectorType::add(const VectorType::value_type, const VectorType &);
80 *
81 * // Copies the data of a given vector to the current.
82 * // Resize the current vector if necessary (MPI safe).
83 * VectorType::operation=(const VectorType &);
84 *
85 * // Return the global size of the current vector.
86 * VectorType::size();
87 *
88 * // Return L^2 norm of the current vector
89 * VectorType::l2_norm();
90 *
91 * // Iterator to the start of the (locally owned) element
92 * // of the current vector.
93 * VectorType::begin();
94 *
95 * // Iterator to the one past the last (locally owned)
96 * // element of the current vector.
97 * VectorType::end();
98 *
99 * // Compress the vector i.e., flush the buffers of the
100 * // vector object if it has any.
101 * VectorType::compress(VectorOperation::insert);
102 * @endcode
103 *
104 * @note The current implementation in ROL doesn't support vector sizes above
105 * the largest value of int type. Some of the vectors in deal.II (see
106 * @ref Vector)
107 * may not satisfy the above requirements.
108 */
109 template <typename VectorType>
110 class VectorAdaptor : public ROL::Vector<typename VectorType::value_type>
111 {
112 /**
113 * An alias for size type of <tt>VectorType</tt>.
114 */
115 using size_type = typename VectorType::size_type;
116
117 /**
118 * An alias for element type stored in the <tt>VectorType</tt>.
119 */
120 using value_type = typename VectorType::value_type;
121
122 /**
123 * An alias for real-valued numbers.
124 */
125 using real_type = typename VectorType::real_type;
126
127 static_assert(std::is_convertible_v<real_type, value_type>,
128 "The real_type of the current VectorType is not "
129 "convertible to the value_type.");
130
131 private:
132 /**
133 * ROL pointer to the underlying vector of type <tt>VectorType</tt>.
134 */
135 ROL::Ptr<VectorType> vector_ptr;
136
137 public:
138 /**
139 * Constructor.
140 */
141 VectorAdaptor(const ROL::Ptr<VectorType> &vector_ptr);
142
143 /**
144 * Return the ROL pointer to the wrapper vector, #vector_ptr.
145 */
146 ROL::Ptr<VectorType>
147 getVector();
148
149 /**
150 * Return the ROL pointer to const vector.
151 */
152 ROL::Ptr<const VectorType>
153 getVector() const;
154
155 /**
156 * Return the dimension (global vector size) of the wrapped vector.
157 */
158 int
159 dimension() const;
160
161 /**
162 * Set the wrapper vector to a given ROL::Vector @p rol_vector by
163 * overwriting its contents.
164 *
165 * If the current wrapper vector has ghost elements,
166 * then <code> VectorType::operator=(const VectorType&) </code> should still
167 * be allowed on it.
168 */
169 void
170 set(const ROL::Vector<value_type> &rol_vector);
171
172 /**
173 * Perform addition.
174 */
175 void
176 plus(const ROL::Vector<value_type> &rol_vector);
177
178 /**
179 * Scale the wrapper vector by @p alpha and add ROL::Vector @p rol_vector
180 * to it.
181 */
182 void
183 axpy(const value_type alpha, const ROL::Vector<value_type> &rol_vector);
184
185 /**
186 * Scale the wrapper vector.
187 */
188 void
189 scale(const value_type alpha);
190
191 /**
192 * Return the dot product with a given ROL::Vector @p rol_vector.
193 */
194 value_type
195 dot(const ROL::Vector<value_type> &rol_vector) const;
196
197 /**
198 * Return the $L^{2}$ norm of the wrapped vector.
199 *
200 * The returned type is of VectorAdaptor::value_type so as to maintain
201 * consistency with ROL::Vector<VectorAdaptor::value_type> and
202 * more importantly to not to create an overloaded version namely,
203 * <code> VectorAdaptor::real_type norm() const; </code>
204 * if real_type and value_type are not of the same type.
205 */
206 value_type
207 norm() const;
208
209 /**
210 * Return a clone of the wrapped vector.
211 */
212 ROL::Ptr<ROL::Vector<value_type>>
213 clone() const;
214
215 /**
216 * Create and return a ROL pointer to the basis vector corresponding to the
217 * @p i ${}^{th}$ element of the wrapper vector.
218 */
219 ROL::Ptr<ROL::Vector<value_type>>
220 basis(const int i) const;
221
222 /**
223 * Apply unary function @p f to all the elements of the wrapped vector.
224 */
225 void
226 applyUnary(const ROL::Elementwise::UnaryFunction<value_type> &f);
227
228 /**
229 * Apply binary function @p f along with ROL::Vector @p rol_vector to all
230 * the elements of the wrapped vector.
231 */
232 void
233 applyBinary(const ROL::Elementwise::BinaryFunction<value_type> &f,
234 const ROL::Vector<value_type> &rol_vector);
235
236 /**
237 * Return the accumulated value on applying reduction operation @p r on
238 * all the elements of the wrapped vector.
239 */
240 value_type
241 reduce(const ROL::Elementwise::ReductionOp<value_type> &r) const;
242
243 /**
244 * Print the wrapped vector to the output stream @p outStream.
245 */
246 void
247 print(std::ostream &outStream) const;
248 };
249
250
251 /*------------------------------member definitions--------------------------*/
252 # ifndef DOXYGEN
253
254
255 template <typename VectorType>
256 VectorAdaptor<VectorType>::VectorAdaptor(
257 const ROL::Ptr<VectorType> &vector_ptr)
258 : vector_ptr(vector_ptr)
259 {}
260
261
262
263 template <typename VectorType>
264 ROL::Ptr<VectorType>
265 VectorAdaptor<VectorType>::getVector()
266 {
267 return vector_ptr;
268 }
269
270
271
272 template <typename VectorType>
273 ROL::Ptr<const VectorType>
274 VectorAdaptor<VectorType>::getVector() const
275 {
276 return vector_ptr;
277 }
278
279
280
281 template <typename VectorType>
282 void
283 VectorAdaptor<VectorType>::set(const ROL::Vector<value_type> &rol_vector)
284 {
285 const VectorAdaptor &vector_adaptor =
286 dynamic_cast<const VectorAdaptor &>(rol_vector);
287
288 (*vector_ptr) = *(vector_adaptor.getVector());
289 }
290
291
292
293 template <typename VectorType>
294 void
295 VectorAdaptor<VectorType>::plus(const ROL::Vector<value_type> &rol_vector)
296 {
297 Assert(this->dimension() == rol_vector.dimension(),
298 ExcDimensionMismatch(this->dimension(), rol_vector.dimension()));
299
300 const VectorAdaptor &vector_adaptor =
301 dynamic_cast<const VectorAdaptor &>(rol_vector);
302
303 *vector_ptr += *(vector_adaptor.getVector());
304 }
305
306
307
308 template <typename VectorType>
309 void
310 VectorAdaptor<VectorType>::axpy(const value_type alpha,
311 const ROL::Vector<value_type> &rol_vector)
312 {
313 Assert(this->dimension() == rol_vector.dimension(),
314 ExcDimensionMismatch(this->dimension(), rol_vector.dimension()));
315
316 const VectorAdaptor &vector_adaptor =
317 dynamic_cast<const VectorAdaptor &>(rol_vector);
318
319 vector_ptr->add(alpha, *(vector_adaptor.getVector()));
320 }
321
322
323
324 template <typename VectorType>
325 int
326 VectorAdaptor<VectorType>::dimension() const
327 {
328 Assert(vector_ptr->size() < std::numeric_limits<int>::max(),
329 ExcMessage("The size of the vector being used is greater than "
330 "largest value of type int."));
331 return static_cast<int>(vector_ptr->size());
332 }
333
334
335
336 template <typename VectorType>
337 void
338 VectorAdaptor<VectorType>::scale(const value_type alpha)
339 {
340 (*vector_ptr) *= alpha;
341 }
342
343
344
345 template <typename VectorType>
346 typename VectorType::value_type
347 VectorAdaptor<VectorType>::dot(
348 const ROL::Vector<value_type> &rol_vector) const
349 {
350 Assert(this->dimension() == rol_vector.dimension(),
351 ExcDimensionMismatch(this->dimension(), rol_vector.dimension()));
352
353 const VectorAdaptor &vector_adaptor =
354 dynamic_cast<const VectorAdaptor &>(rol_vector);
355
356 return (*vector_ptr) * (*vector_adaptor.getVector());
357 }
358
359
360
361 template <typename VectorType>
362 typename VectorType::value_type
363 VectorAdaptor<VectorType>::norm() const
364 {
365 return vector_ptr->l2_norm();
366 }
367
368
369
370 template <typename VectorType>
371 ROL::Ptr<ROL::Vector<typename VectorType::value_type>>
372 VectorAdaptor<VectorType>::clone() const
373 {
374 ROL::Ptr<VectorType> vec_ptr = ROL::makePtr<VectorType>(*vector_ptr);
375
376 return ROL::makePtr<VectorAdaptor>(vec_ptr);
377 }
378
379
380
381 template <typename VectorType>
382 ROL::Ptr<ROL::Vector<typename VectorType::value_type>>
383 VectorAdaptor<VectorType>::basis(const int i) const
384 {
385 ROL::Ptr<VectorType> vec_ptr = ROL::makePtr<VectorType>();
386
387 // Zero all the entries in dealii vector.
388 vec_ptr->reinit(*vector_ptr, false);
389
390 if (vector_ptr->locally_owned_elements().is_element(i))
391 vec_ptr->operator[](i) = 1.;
392
393 if (vec_ptr->has_ghost_elements())
394 {
395 vec_ptr->update_ghost_values();
396 }
397 else
398 {
399 vec_ptr->compress(VectorOperation::insert);
400 }
401
402 return ROL::makePtr<VectorAdaptor>(vec_ptr);
403 }
404
405
406
407 template <typename VectorType>
408 void
409 VectorAdaptor<VectorType>::applyUnary(
410 const ROL::Elementwise::UnaryFunction<value_type> &f)
411 {
412 const typename VectorType::iterator vend = vector_ptr->end();
413
414 for (typename VectorType::iterator iterator = vector_ptr->begin();
415 iterator != vend;
416 iterator++)
417 *iterator = f.apply(*iterator);
418
419 if (vector_ptr->has_ghost_elements())
420 {
421 vector_ptr->update_ghost_values();
422 }
423 else
424 {
425 vector_ptr->compress(VectorOperation::insert);
426 }
427 }
428
429
430
431 template <typename VectorType>
432 void
433 VectorAdaptor<VectorType>::applyBinary(
434 const ROL::Elementwise::BinaryFunction<value_type> &f,
435 const ROL::Vector<value_type> &rol_vector)
436 {
437 Assert(this->dimension() == rol_vector.dimension(),
438 ExcDimensionMismatch(this->dimension(), rol_vector.dimension()));
439
440 const VectorAdaptor &vector_adaptor =
441 dynamic_cast<const VectorAdaptor &>(rol_vector);
442
443 const VectorType &given_rol_vector = *(vector_adaptor.getVector());
444
445 const typename VectorType::iterator vend = vector_ptr->end();
446 const typename VectorType::const_iterator rolend = given_rol_vector.end();
447
448 typename VectorType::const_iterator r_iterator = given_rol_vector.begin();
449 for (typename VectorType::iterator l_iterator = vector_ptr->begin();
450 l_iterator != vend && r_iterator != rolend;
451 l_iterator++, r_iterator++)
452 *l_iterator = f.apply(*l_iterator, *r_iterator);
453
454 if (vector_ptr->has_ghost_elements())
455 {
456 vector_ptr->update_ghost_values();
457 }
458 else
459 {
460 vector_ptr->compress(VectorOperation::insert);
461 }
462 }
463
464
465
466 template <typename VectorType>
467 typename VectorType::value_type
468 VectorAdaptor<VectorType>::reduce(
469 const ROL::Elementwise::ReductionOp<value_type> &r) const
470 {
471 typename VectorType::value_type result = r.initialValue();
472
473 const typename VectorType::iterator vend = vector_ptr->end();
474
475 for (typename VectorType::iterator iterator = vector_ptr->begin();
476 iterator != vend;
477 iterator++)
478 r.reduce(*iterator, result);
479 // Parallel reduction among processes is handled internally.
480
481 return result;
482 }
483
484
485
486 template <typename VectorType>
487 void
488 VectorAdaptor<VectorType>::print(std::ostream &outStream) const
489 {
490 vector_ptr->print(outStream);
491 }
492
493
494 # endif // DOXYGEN
495
496
497 } // namespace Rol
498
499
500 DEAL_II_NAMESPACE_CLOSE
501
502
503 #else
504
505 // Make sure the scripts that create the C++20 module input files have
506 // something to latch on if the preprocessor #ifdef above would
507 // otherwise lead to an empty content of the file.
508 DEAL_II_NAMESPACE_OPEN
509 DEAL_II_NAMESPACE_CLOSE
510
511 #endif // DEAL_II_TRILINOS_WITH_ROL
512
513 #endif // dealii_optimization_rol_vector_adaptor_h