Line data Source code
1 : // The libMesh Finite Element Library.
2 : // Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
3 :
4 : // This library is free software; you can redistribute it and/or
5 : // modify it under the terms of the GNU Lesser General Public
6 : // License as published by the Free Software Foundation; either
7 : // version 2.1 of the License, or (at your option) any later version.
8 :
9 : // This library is distributed in the hope that it will be useful,
10 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 : // Lesser General Public License for more details.
13 :
14 : // You should have received a copy of the GNU Lesser General Public
15 : // License along with this library; if not, write to the Free Software
16 : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 :
18 :
19 :
20 : #ifndef LIBMESH_NUMERIC_VECTOR_H
21 : #define LIBMESH_NUMERIC_VECTOR_H
22 :
23 : // Local includes
24 : #include "libmesh/libmesh_common.h"
25 : #include "libmesh/enum_parallel_type.h" // AUTOMATIC
26 : #include "libmesh/id_types.h"
27 : #include "libmesh/int_range.h"
28 : #include "libmesh/reference_counted_object.h"
29 : #include "libmesh/libmesh.h"
30 : #include "libmesh/parallel_object.h"
31 : #include "libmesh/dense_subvector.h"
32 : #include "libmesh/dense_vector.h"
33 :
34 : // C++ includes
35 : #include <cstddef>
36 : #include <set>
37 : #include <vector>
38 : #include <memory>
39 : #include <mutex>
40 : #include <string>
41 :
42 : namespace libMesh
43 : {
44 :
45 :
46 : // forward declarations
47 : template <typename T> class NumericVector;
48 : template <typename T> class DenseVector;
49 : template <typename T> class DenseSubVector;
50 : template <typename T> class SparseMatrix;
51 : template <typename T> class ShellMatrix;
52 : enum SolverPackage : int;
53 :
54 : /**
55 : * \brief Provides a uniform interface to vector storage schemes for different
56 : * linear algebra libraries.
57 : *
58 : * \note This class is the abstract base class for different implementations
59 : * of numeric vectors. Most of the time you should use a System object to
60 : * create numeric vectors. If this is not desired, you can instantiate one of
61 : * the derived classes (PetscVector, EigenSparseVector, etc.) or use the
62 : * NumericVector::build method. When creating the vector yourself, make sure
63 : * that you initialize the vector properly (NumericVector::init).
64 : *
65 : * \author Benjamin S. Kirk
66 : * \date 2003
67 : */
68 : template <typename T>
69 : class NumericVector : public ReferenceCountedObject<NumericVector<T>>,
70 : public ParallelObject
71 : {
72 : public:
73 :
74 : /**
75 : * Dummy-Constructor. Dimension=0
76 : */
77 : explicit
78 : NumericVector (const Parallel::Communicator & comm_in,
79 : const ParallelType ptype = AUTOMATIC);
80 :
81 : /**
82 : * Constructor. Set dimension to \p n and initialize all elements with zero.
83 : */
84 : explicit
85 : NumericVector (const Parallel::Communicator & comm_in,
86 : const numeric_index_type n,
87 : const ParallelType ptype = AUTOMATIC);
88 :
89 : /**
90 : * Constructor. Set local dimension to \p n_local, the global dimension
91 : * to \p n, and initialize all elements with zero.
92 : */
93 : NumericVector (const Parallel::Communicator & comm_in,
94 : const numeric_index_type n,
95 : const numeric_index_type n_local,
96 : const ParallelType ptype = AUTOMATIC);
97 :
98 : /**
99 : * Constructor. Set local dimension to \p n_local, the global
100 : * dimension to \p n, but additionally reserve memory for the
101 : * indices specified by the \p ghost argument.
102 : */
103 : NumericVector (const Parallel::Communicator & comm_in,
104 : const numeric_index_type N,
105 : const numeric_index_type n_local,
106 : const std::vector<numeric_index_type> & ghost,
107 : const ParallelType ptype = AUTOMATIC);
108 :
109 : /**
110 : * This _looks_ like a copy assignment operator, but note that,
111 : * unlike normal copy assignment operators, it is pure virtual. This
112 : * function should be overridden in derived classes so that they can
113 : * be copied correctly via references to the base class. This design
114 : * usually isn't a good idea in general, but in this context it
115 : * works because we usually don't have a mix of different kinds of
116 : * NumericVectors active in the library at a single time.
117 : *
118 : * \returns A reference to *this as the base type.
119 : */
120 : virtual NumericVector<T> & operator= (const NumericVector<T> & v) = 0;
121 :
122 : /**
123 : * These 3 special functions can be defaulted for this class, as it
124 : * does not manage any memory itself.
125 : */
126 : NumericVector (NumericVector &&) = default;
127 : NumericVector (const NumericVector &) = default;
128 : NumericVector & operator= (NumericVector &&) = default;
129 :
130 : /**
131 : * While this class doesn't manage any memory, the derived class might and
132 : * users may be deleting through a pointer to this base class
133 : */
134 2844582 : virtual ~NumericVector() = default;
135 :
136 : /**
137 : * Builds a \p NumericVector on the processors in communicator
138 : * \p comm using the linear solver package specified by
139 : * \p solver_package
140 : */
141 : static std::unique_ptr<NumericVector<T>>
142 : build(const Parallel::Communicator & comm,
143 : SolverPackage solver_package = libMesh::default_solver_package(),
144 : ParallelType parallel_type = AUTOMATIC);
145 :
146 : /**
147 : * \returns \p true if the vector has been initialized,
148 : * false otherwise.
149 : */
150 1529238717 : virtual bool initialized() const { return _is_initialized; }
151 :
152 : /**
153 : * \returns The type (SERIAL, PARALLEL, GHOSTED) of the vector.
154 : *
155 : * This is metadata reflecting what type of vector was requested,
156 : * which should reflect what level of replication and ghosting is
157 : * necessary in parallel.
158 : */
159 2810472 : ParallelType type() const { return _type; }
160 :
161 : /**
162 : * \returns Whether the vector is effectively serial, i.e. whether
163 : * all vector data is accessible on every processor.
164 : *
165 : * This is true for explicitly SERIAL vectors, but also for vectors
166 : * on serial (1-processor) communicators.
167 : */
168 :
169 341538 : bool is_effectively_serial() const
170 4402802 : { return (this->n_processors()==1) || (_type == SERIAL); }
171 :
172 : /**
173 : * \returns Whether the vector is effectively ghosted, i.e. whether
174 : * vector operations require handling of ghosted coefficients.
175 : *
176 : * This is true for GHOSTED vectors in parallel, but in serial
177 : * subclasses may return false here for GHOSTED vectors since every
178 : * ghosted vector is effectively serial and thus may be able to take
179 : * advantage of serial-specific code paths.
180 : */
181 :
182 571993086 : bool is_effectively_ghosted() const
183 594285150 : { return (this->n_processors()!=1) && (_type == GHOSTED); }
184 :
185 : /**
186 : * \returns The type (SERIAL, PARALLEL, GHOSTED) of the vector.
187 : *
188 : * \deprecated because it is dangerous to change the ParallelType
189 : * of an already-initialized NumericVector. See NumericVector::set_type()
190 : * for a safer, non-deprecated setter.
191 : */
192 : #ifdef LIBMESH_ENABLE_DEPRECATED
193 460808 : ParallelType & type() { return _type; }
194 : #endif
195 :
196 : /**
197 : * Allow the user to change the ParallelType of the NumericVector
198 : * under some circumstances. If the NumericVector has not been
199 : * initialized yet, then it is generally safe to change the
200 : * ParallelType. otherwise, if the NumericVector has already been
201 : * initialized with a specific type, we cannot change it without
202 : * doing some extra copying/reinitialization work, and we currently
203 : * throw an error if this is requested.
204 : */
205 : void set_type(ParallelType t);
206 :
207 : /**
208 : * Sets the prefix that solver packages prepend to option names when
209 : * they configure this vector, e.g. a PETSc options prefix. The
210 : * prefix takes effect at the next init() of the vector.
211 : */
212 93246 : void set_options_prefix(std::string prefix) { _options_prefix = std::move(prefix); }
213 :
214 : /**
215 : * \returns The options prefix of this vector. See set_options_prefix().
216 : */
217 45462 : const std::string & options_prefix() const { return _options_prefix; }
218 :
219 : /**
220 : * \returns \p true if the vector is closed and ready for
221 : * computation, false otherwise.
222 : */
223 978051 : virtual bool closed() const { return _is_closed; }
224 :
225 : /**
226 : * Calls the NumericVector's internal assembly routines, ensuring
227 : * that the values are consistent across processors.
228 : */
229 : virtual void close () = 0;
230 :
231 : /**
232 : * Restores the \p NumericVector<T> to a pristine state.
233 : */
234 : virtual void clear ();
235 :
236 : /**
237 : * Set all entries to zero. Equivalent to \p v = 0, but more obvious and
238 : * faster.
239 : */
240 : virtual void zero () = 0;
241 :
242 : /**
243 : * \returns A smart pointer to a copy of this vector with the same
244 : * type, size, and partitioning, but with all zero entries.
245 : *
246 : * \note This must be overridden in the derived classes.
247 : */
248 : virtual std::unique_ptr<NumericVector<T>> zero_clone () const = 0;
249 :
250 : /**
251 : * \returns A copy of this vector wrapped in a smart pointer.
252 : *
253 : * \note This must be overridden in the derived classes.
254 : */
255 : virtual std::unique_ptr<NumericVector<T>> clone () const = 0;
256 :
257 : /**
258 : * Change the dimension of the vector to \p n. The reserved memory
259 : * for this vector remains unchanged if possible. If \p n==0, all
260 : * memory is freed. Therefore, if you want to resize the vector and
261 : * release the memory not needed, you have to first call \p init(0)
262 : * and then \p init(n). This behaviour is analogous to that of the
263 : * STL containers.
264 : *
265 : * On \p fast==false, the vector is filled by zeros.
266 : */
267 : virtual void init (const numeric_index_type n,
268 : const numeric_index_type n_local,
269 : const bool fast = false,
270 : const ParallelType ptype = AUTOMATIC) = 0;
271 :
272 : /**
273 : * Call \p init() with n_local = N.
274 : */
275 : virtual void init (const numeric_index_type n,
276 : const bool fast = false,
277 : const ParallelType ptype = AUTOMATIC) = 0;
278 :
279 : /**
280 : * Create a vector that holds the local indices plus those specified
281 : * in the \p ghost argument.
282 : */
283 : virtual void init (const numeric_index_type n,
284 : const numeric_index_type n_local,
285 : const std::vector<numeric_index_type> & ghost,
286 : const bool fast = false,
287 : const ParallelType ptype = AUTOMATIC) = 0;
288 :
289 : /**
290 : * Creates a vector that has the same dimension and storage type as
291 : * \p other, including ghost dofs.
292 : */
293 : virtual void init (const NumericVector<T> & other,
294 : const bool fast = false) = 0;
295 :
296 : /**
297 : * Sets all entries of the vector to the value \p s.
298 : *
299 : * \returns A reference to *this.
300 : */
301 : virtual NumericVector<T> & operator= (const T s) = 0;
302 :
303 : /**
304 : * Sets (*this)(i) = v(i) for each entry of the vector.
305 : *
306 : * \returns A reference to *this as the base type.
307 : */
308 : virtual NumericVector<T> & operator= (const std::vector<T> & v) = 0;
309 :
310 : /**
311 : * \returns The minimum entry in the vector, or the minimum real
312 : * part in the case of complex numbers.
313 : */
314 : virtual Real min () const = 0;
315 :
316 : /**
317 : * \returns The maximum entry in the vector, or the maximum real
318 : * part in the case of complex numbers.
319 : */
320 : virtual Real max () const = 0;
321 :
322 : /**
323 : * \returns The sum of all values in the vector.
324 : */
325 : virtual T sum() const = 0;
326 :
327 : /**
328 : * \returns The \f$ \ell_1 \f$-norm of the vector, i.e. the sum of the
329 : * absolute values of the entries.
330 : */
331 : virtual Real l1_norm () const = 0;
332 :
333 : /**
334 : * \returns The \f$ \ell_2 \f$-norm of the vector, i.e. the square root
335 : * of the sum of the squares of the entries.
336 : */
337 : virtual Real l2_norm () const = 0;
338 :
339 : /**
340 : * \returns The \f$ \ell_{\infty} \f$-norm of the vector, i.e. the maximum
341 : * absolute value of the entries of the vector.
342 : */
343 : virtual Real linfty_norm () const = 0;
344 :
345 : /**
346 : * \returns The \f$ \ell_1 \f$-norm of the vector, i.e. the sum of the
347 : * absolute values for the specified entries in the vector.
348 : *
349 : * \note The indices must necessarily live on this processor.
350 : */
351 : virtual Real subset_l1_norm (const std::set<numeric_index_type> & indices) const;
352 :
353 : /**
354 : * \returns The \f$ \ell_2 \f$-norm of the vector, i.e. the square root
355 : * of the sum of the squares of the elements for the specified
356 : * entries in the vector.
357 : *
358 : * \note The indices must necessarily live on this processor.
359 : */
360 : virtual Real subset_l2_norm (const std::set<numeric_index_type> & indices) const;
361 :
362 : /**
363 : * \returns The maximum absolute value of the specified entries of
364 : * this vector, which is the \f$ \ell_{\infty} \f$-norm of a vector.
365 : *
366 : * \note The indices must necessarily live on this processor.
367 : */
368 : virtual Real subset_linfty_norm (const std::set<numeric_index_type> & indices) const;
369 :
370 : /**
371 : * \returns The \f$ \ell_2 \f$-norm of \f$ \vec{u} - \vec{v} \f$, where
372 : * \f$ \vec{u} \f$ is \p this.
373 : */
374 : Real l2_norm_diff (const NumericVector<T> & other_vec) const;
375 :
376 : /**
377 : * \returns The \f$ \ell_1 \f$-norm of \f$ \vec{u} - \vec{v} \f$, where
378 : * \f$ \vec{u} \f$ is \p this.
379 : */
380 : Real l1_norm_diff (const NumericVector<T> & other_vec) const;
381 :
382 : /**
383 : * \returns The size of the vector.
384 : */
385 : virtual numeric_index_type size () const = 0;
386 :
387 : /**
388 : * \returns The local size of the vector, i.e. \p index_stop - \p index_start.
389 : */
390 : virtual numeric_index_type local_size() const = 0;
391 :
392 : /**
393 : * \returns The index of the first vector element actually stored on
394 : * this processor.
395 : *
396 : * \note The minimum for this index is \p 0.
397 : */
398 : virtual numeric_index_type first_local_index() const = 0;
399 :
400 : /**
401 : * \returns The index+1 of the last vector element actually stored
402 : * on this processor.
403 : *
404 : * \note The maximum for this index is \p size().
405 : */
406 : virtual numeric_index_type last_local_index() const = 0;
407 :
408 : /**
409 : * \returns A copy of the ith entry of the vector.
410 : */
411 : virtual T operator() (const numeric_index_type i) const = 0;
412 :
413 : /**
414 : * \returns (*this)(i).
415 : */
416 0 : virtual T el(const numeric_index_type i) const { return (*this)(i); }
417 :
418 : /**
419 : * Access multiple components at once. \p values will *not* be
420 : * reallocated; it should already have enough space. The default
421 : * implementation calls \p operator() for each index, but some
422 : * implementations may supply faster methods here.
423 : */
424 : virtual void get(const std::vector<numeric_index_type> & index,
425 : T * values) const;
426 :
427 : /**
428 : * Access multiple components at once. \p values will be resized,
429 : * if necessary, and filled. The default implementation calls \p
430 : * operator() for each index, but some implementations may supply
431 : * faster methods here.
432 : */
433 : void get(const std::vector<numeric_index_type> & index,
434 : std::vector<T> & values) const;
435 :
436 : /**
437 : * Adds \p v to *this,
438 : * \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$.
439 : * Equivalent to \p u.add(1, v).
440 : *
441 : * \returns A reference to *this.
442 : */
443 : virtual NumericVector<T> & operator += (const NumericVector<T> & v) = 0;
444 :
445 : /**
446 : * Subtracts \p v from *this,
447 : * \f$ \vec{u} \leftarrow \vec{u} - \vec{v} \f$.
448 : * Equivalent to \p u.add(-1, v).
449 : *
450 : * \returns A reference to *this.
451 : */
452 : virtual NumericVector<T> & operator -= (const NumericVector<T> & v) = 0;
453 :
454 : /**
455 : * Scales the vector by \p a,
456 : * \f$ \vec{u} \leftarrow a\vec{u} \f$.
457 : * Equivalent to \p u.scale(a)
458 : *
459 : * \returns A reference to *this.
460 : */
461 11572 : NumericVector<T> & operator *= (const T a) { this->scale(a); return *this; }
462 :
463 : /**
464 : * Computes the component-wise multiplication of this vector's entries by
465 : * another's,
466 : * \f$ u_i \leftarrow u_i v_i \, \forall i\f$
467 : *
468 : * \returns A reference to *this.
469 : */
470 : virtual NumericVector<T> & operator *= (const NumericVector<T> & v) = 0;
471 :
472 : /**
473 : * Scales the vector by \p 1/a,
474 : * \f$ \vec{u} \leftarrow \frac{1}{a}\vec{u} \f$.
475 : * Equivalent to \p u.scale(1./a)
476 : *
477 : * \returns A reference to *this.
478 : */
479 7430 : NumericVector<T> & operator /= (const T a) { this->scale(1./a); return *this; }
480 :
481 : /**
482 : * Computes the component-wise division of this vector's entries by another's,
483 : * \f$ u_i \leftarrow \frac{u_i}{v_i} \, \forall i\f$
484 : *
485 : * \returns A reference to *this.
486 : */
487 : virtual NumericVector<T> & operator /= (const NumericVector<T> & v) = 0;
488 :
489 : /**
490 : * Computes the component-wise reciprocal,
491 : * \f$ u_i \leftarrow \frac{1}{u_i} \, \forall i\f$
492 : */
493 : virtual void reciprocal() = 0;
494 :
495 : /**
496 : * Negates the imaginary component of each entry in the vector.
497 : */
498 : virtual void conjugate() = 0;
499 :
500 : /**
501 : * Sets v(i) = \p value. Note that library implementations of this method are
502 : * thread safe, e.g. we will lock \p _numeric_vector_mutex before writing to the vector
503 : */
504 : virtual void set (const numeric_index_type i, const T value) = 0;
505 :
506 : /**
507 : * Adds \p value to the vector entry specified by \p i. Note that library implementations of this
508 : * method are thread safe, e.g. we will lock \p _numeric_vector_mutex before writing to the vector
509 : */
510 : virtual void add (const numeric_index_type i, const T value) = 0;
511 :
512 : /**
513 : * Adds \p s to each entry of the vector,
514 : * \f$ u_i \leftarrow u_i + s \f$
515 : */
516 : virtual void add (const T s) = 0;
517 :
518 : /**
519 : * Adds \p v to \p this,
520 : * \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$.
521 : * Equivalent to calling \p operator+=().
522 : */
523 : virtual void add (const NumericVector<T> & v) = 0;
524 :
525 : /**
526 : * Vector addition with a scalar multiple,
527 : * \f$ \vec{u} \leftarrow \vec{u} + a\vec{v} \f$.
528 : * Equivalent to calling \p operator+=().
529 : */
530 : virtual void add (const T a, const NumericVector<T> & v) = 0;
531 :
532 : /**
533 : * Computes \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$,
534 : * where \p v is a pointer and each \p dof_indices[i] specifies where
535 : * to add value \p v[i]. This should be overridden in subclasses
536 : * for efficiency. Note that library implementations of this
537 : * method are thread safe
538 : */
539 : virtual void add_vector (const T * v,
540 : const std::vector<numeric_index_type> & dof_indices);
541 :
542 : /**
543 : * Computes \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$,
544 : * where \p v is a std::vector and each \p dof_indices[i] specifies
545 : * where to add value \p v[i]. This method is guaranteed to be thread safe as long as library
546 : * implementations of \p NumericVector are used
547 : */
548 : void add_vector (const std::vector<T> & v,
549 : const std::vector<numeric_index_type> & dof_indices);
550 :
551 : /**
552 : * Computes \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$,
553 : * where \p v is a NumericVector and each \p dof_indices[i]
554 : * specifies where to add value \p v(i). This method is
555 : * guaranteed to be thread-safe as long as library implementations of \p NumericVector are used
556 : */
557 : void add_vector (const NumericVector<T> & v,
558 : const std::vector<numeric_index_type> & dof_indices);
559 :
560 : /**
561 : * Computes \f$ \vec{u} \leftarrow \vec{u} + \vec{v} \f$,
562 : * where \p v is a DenseVector and each \p dof_indices[i] specifies
563 : * where to add value \p v(i). This method is guaranteed to be thread safe as long as library
564 : * implementations of \p NumericVector are used
565 : */
566 : void add_vector (const DenseVector<T> & v,
567 : const std::vector<numeric_index_type> & dof_indices);
568 :
569 : /**
570 : * Computes \f$ \vec{u} \leftarrow \vec{u} + A \vec{v} \f$,
571 : * i.e. adds the product of a \p SparseMatrix \p A and a \p
572 : * NumericVector \p v to \p this.
573 : */
574 : virtual void add_vector (const NumericVector<T> & v,
575 : const SparseMatrix<T> & A) = 0;
576 :
577 : /**
578 : * Computes \f$ \vec{u} \leftarrow \vec{u} + A \vec{v} \f$,
579 : * i.e. adds the product of a \p ShellMatrix \p A and a \p
580 : * NumericVector \p v to \p this.
581 : */
582 : void add_vector (const NumericVector<T> & v,
583 : const ShellMatrix<T> & A);
584 :
585 : /**
586 : * Computes \f$ \vec{u} \leftarrow \vec{u} + A^T \vec{v} \f$,
587 : * i.e. adds the product of the transpose of a \p SparseMatrix \p A
588 : * and a \p NumericVector \p v to \p this.
589 : */
590 : virtual void add_vector_transpose (const NumericVector<T> & v,
591 : const SparseMatrix<T> & A) = 0;
592 :
593 : /**
594 : * Inserts the entries of \p v in *this at the locations specified by \p v. Note that library
595 : * implementations of this method are thread safe
596 : */
597 : virtual void insert (const T * v,
598 : const std::vector<numeric_index_type> & dof_indices);
599 :
600 : /**
601 : * Inserts the entries of \p v in *this at the locations specified by \p v. This method is
602 : * guaranteed to be thread-safe as long as library implementations of \p NumericVector are used
603 : */
604 : void insert (const std::vector<T> & v,
605 : const std::vector<numeric_index_type> & dof_indices);
606 :
607 : /**
608 : * Inserts the entries of \p v in *this at the locations specified by \p v. This method is
609 : * guaranteed to be thread-safe as long as library implementations of \p NumericVector are used
610 : */
611 : void insert (const NumericVector<T> & v,
612 : const std::vector<numeric_index_type> & dof_indices);
613 :
614 : /**
615 : * Inserts the entries of \p v in *this at the locations specified by \p v. This method is
616 : * guaranteed to be thread-safe as long as library implementations of \p NumericVector are used
617 : */
618 : void insert (const DenseVector<T> & v,
619 : const std::vector<numeric_index_type> & dof_indices);
620 :
621 : /**
622 : * Inserts the entries of \p v in *this at the locations specified by \p v. This method is
623 : * guaranteed to be thread-safe as long as library implementations of \p NumericVector are used
624 : */
625 : void insert (const DenseSubVector<T> & v,
626 : const std::vector<numeric_index_type> & dof_indices);
627 :
628 : /**
629 : * Scale each element of the vector by the given \p factor.
630 : */
631 : virtual void scale (const T factor) = 0;
632 :
633 : /**
634 : * Sets \f$ u_i \leftarrow |u_i| \f$ for each entry in the vector.
635 : */
636 : virtual void abs() = 0;
637 :
638 : /**
639 : * \returns \f$ \vec{u} \cdot \vec{v} \f$, the dot product of
640 : * (*this) with the vector \p v.
641 : *
642 : * Uses the complex-conjugate of \p v in the complex-valued case.
643 : */
644 : virtual T dot(const NumericVector<T> & v) const = 0;
645 :
646 : /**
647 : * Creates a copy of the global vector in the local vector \p
648 : * v_local.
649 : */
650 : virtual void localize (std::vector<T> & v_local) const = 0;
651 :
652 : /**
653 : * Same, but fills a \p NumericVector<T> instead of a \p
654 : * std::vector.
655 : */
656 : virtual void localize (NumericVector<T> & v_local) const = 0;
657 :
658 : /**
659 : * Creates a local vector \p v_local containing only information
660 : * relevant to this processor, as defined by the \p send_list.
661 : */
662 : virtual void localize (NumericVector<T> & v_local,
663 : const std::vector<numeric_index_type> & send_list) const = 0;
664 :
665 : /**
666 : * Fill in the local std::vector "v_local" with the global indices
667 : * given in "indices".
668 : *
669 : * \note The indices can be different on every processor, and the
670 : * same index can be localized to more than one processor. The
671 : * resulting v_local can be shorter than the original, and the
672 : * entries will be in the order specified by indices.
673 : *
674 : * Example:
675 : * \verbatim
676 : * On 4 procs *this = {a, b, c, d, e, f, g, h, i} is a parallel vector.
677 : * On each proc, the indices arrays are set up as:
678 : * proc0, indices = {1,2,4,5}
679 : * proc1, indices = {2,5,6,8}
680 : * proc2, indices = {2,3,6,7}
681 : * proc3, indices = {0,1,2,3}
682 : *
683 : * After calling this version of localize, the v_local vectors are:
684 : * proc0, v_local = {b,c,e,f}
685 : * proc1, v_local = {c,f,g,i}
686 : * proc2, v_local = {c,d,g,h}
687 : * proc3, v_local = {a,b,c,d}
688 : * \endverbatim
689 : *
690 : * This function is useful in parallel I/O routines, when you have a
691 : * parallel vector of solution values which you want to write a
692 : * subset of.
693 : */
694 : virtual void localize (std::vector<T> & v_local,
695 : const std::vector<numeric_index_type> & indices) const = 0;
696 :
697 : /**
698 : * Updates a local vector with selected values from neighboring
699 : * processors, as defined by \p send_list.
700 : */
701 : virtual void localize (const numeric_index_type first_local_idx,
702 : const numeric_index_type last_local_idx,
703 : const std::vector<numeric_index_type> & send_list) = 0;
704 :
705 : /**
706 : * Creates a local copy of the global vector in \p v_local only on
707 : * processor \p proc_id. By default the data is sent to processor
708 : * 0. This method is useful for outputting data from one processor.
709 : */
710 : virtual void localize_to_one (std::vector<T> & v_local,
711 : const processor_id_type proc_id=0) const = 0;
712 :
713 : /**
714 : * \returns \p -1 when \p this is equivalent to \p other_vector
715 : * (up to the given \p threshold), or the first index where
716 : * \p abs(a[i]-b[i]) exceeds the threshold.
717 : */
718 : virtual int compare (const NumericVector<T> & other_vector,
719 : const Real threshold = TOLERANCE) const;
720 :
721 : /**
722 : * \returns \p -1 when \p this is equivalent to \p other_vector, (up
723 : * to the given local relative \p threshold), or the first index
724 : * where \p abs(a[i]-b[i])/max(a[i],b[i]) exceeds the threshold.
725 : */
726 : virtual int local_relative_compare (const NumericVector<T> & other_vector,
727 : const Real threshold = TOLERANCE) const;
728 :
729 : /**
730 : * \returns \p -1 when \p this is equivalent to \p other_vector (up
731 : * to the given global relative \p threshold), or the first index
732 : * where \p abs(a[i]-b[i])/max_j(a[j],b[j]) exceeds the threshold.
733 : */
734 : virtual int global_relative_compare (const NumericVector<T> & other_vector,
735 : const Real threshold = TOLERANCE) const;
736 :
737 : /**
738 : * Computes \f$ u_i \leftarrow u_i v_i \f$ (summation not implied)
739 : * i.e. the pointwise (component-wise) product of \p vec1 and
740 : * \p vec2, and stores the result in \p *this.
741 : */
742 : virtual void pointwise_mult (const NumericVector<T> & vec1,
743 : const NumericVector<T> & vec2) = 0;
744 :
745 : /**
746 : * Computes \f$ u_i \leftarrow \frac{v_{1,i}}{v_{2,i}} \f$ (summation not implied)
747 : * i.e. the pointwise (component-wise) division of \p vec1 and
748 : * \p vec2, and stores the result in \p *this.
749 : */
750 : virtual void pointwise_divide (const NumericVector<T> & vec1,
751 : const NumericVector<T> & vec2) = 0;
752 :
753 : /**
754 : * Prints the local contents of the vector, by default to
755 : * libMesh::out
756 : */
757 : virtual void print(std::ostream & os=libMesh::out) const;
758 :
759 : /**
760 : * Prints the global contents of the vector, by default to
761 : * libMesh::out
762 : */
763 : virtual void print_global(std::ostream & os=libMesh::out) const;
764 :
765 : /**
766 : * Same as above but allows you to use stream syntax.
767 : */
768 0 : friend std::ostream & operator << (std::ostream & os, const NumericVector<T> & v)
769 : {
770 0 : v.print_global(os);
771 0 : return os;
772 : }
773 :
774 : /**
775 : * Print the contents of the vector in Matlab's sparse matrix
776 : * format. Optionally prints the vector to the file named \p name.
777 : * If \p name is not specified it is dumped to the screen.
778 : */
779 : virtual void print_matlab(const std::string & filename = "") const;
780 :
781 : /**
782 : * Read the contents of the vector from the Matlab-script format
783 : * used by PETSc.
784 : *
785 : * If the size of the matrix in \p filename appears consistent with
786 : * the existing partitioning of \p this then the existing parallel
787 : * decomposition will be retained.
788 : * If not, then \p this will be initialized with the size from
789 : * the file, linearly partitioned onto the number of processors
790 : * available.
791 : */
792 : virtual void read_matlab(const std::string & filename);
793 :
794 : /**
795 : * Fills in \p subvector from this vector using the indices in \p rows.
796 : *
797 : * \p supplying_global_rows communicates whether
798 : * the supplied vector of rows corresponds to all the rows that
799 : * should be used in the subvector's index set, e.g. whether the
800 : * rows correspond to the global collective. If the rows supplied
801 : * are only the local indices, then \p supplying_global_rows should
802 : * be set to false
803 : *
804 : * This is currently only implemented for \p PetscVector and \p
805 : * EigenSparseVector.
806 : */
807 0 : virtual void create_subvector(NumericVector<T> & /* subvector */,
808 : const std::vector<numeric_index_type> & /* rows */,
809 : bool /* supplying_global_rows */ = true) const
810 : {
811 0 : libmesh_not_implemented();
812 : }
813 :
814 : /**
815 : * Creates a view into this vector using the indices in \p
816 : * rows. Calls to this API should always be paired with a call to \p restore_subvector,
817 : * else any changes made in the subvector will not be reflected in (\p this) original vector.
818 : *
819 : * This is currently only implemented for \p PetscVector and \p
820 : * EigenSparseVector.
821 : */
822 : virtual std::unique_ptr<NumericVector<T>>
823 0 : get_subvector(const std::vector<numeric_index_type> & /* rows */)
824 : {
825 0 : libmesh_not_implemented();
826 : }
827 :
828 : /**
829 : * Restores a view into this vector using the indices in \p
830 : * rows. The \p subvector should have been acquired from \p
831 : * get_subvector() with the same rows.
832 : *
833 : * This is currently only implemented for \p PetscVector and \p
834 : * EigenSparseVector.
835 : */
836 0 : virtual void restore_subvector(std::unique_ptr<NumericVector<T>> /* subvector */,
837 : const std::vector<numeric_index_type> & /* rows */)
838 : {
839 0 : libmesh_not_implemented();
840 : }
841 :
842 : /**
843 : * Swaps the contents of this with \p v. There should be enough
844 : * indirection in subclasses to make this an O(1) header-swap
845 : * operation.
846 : */
847 : virtual void swap (NumericVector<T> & v);
848 :
849 : /**
850 : * \returns the max number of entries (across all procs) that the
851 : * NumericVector can have.
852 : *
853 : * Although we define numeric_index_type, and it is typically
854 : * required that the NumericVector's underlying implementation's
855 : * indices have _size_ equal to sizeof(numeric_index_type), these
856 : * two types can still have different _signedness_, which affects
857 : * the maximum number of values which can be stored in the
858 : * NumericVector.
859 : */
860 : virtual std::size_t max_allowed_id() const = 0;
861 :
862 : /**
863 : * \returns whether or not this vector is able to be read for
864 : * global operations
865 : */
866 : bool readable() const;
867 :
868 : /**
869 : * \returns whether or not this vector and the vector \p v are
870 : * able to be read for global operations with one-another
871 : */
872 : bool compatible(const NumericVector<T> & v) const;
873 :
874 : protected:
875 :
876 : /**
877 : * Flag which tracks whether the vector's values are consistent on
878 : * all processors after insertion or addition of values has occurred
879 : * on some or all processors.
880 : */
881 : bool _is_closed;
882 :
883 : /**
884 : * \p true once init() has been called.
885 : */
886 : bool _is_initialized;
887 :
888 : /**
889 : * Type of vector.
890 : */
891 : ParallelType _type;
892 :
893 : /**
894 : * Prefix for solver-package options. See set_options_prefix().
895 : */
896 : std::string _options_prefix;
897 :
898 : /**
899 : * Mutex for performing thread-safe operations
900 : */
901 : std::mutex _numeric_vector_mutex;
902 : };
903 :
904 :
905 : /*----------------------- Inline functions ----------------------------------*/
906 :
907 :
908 :
909 : template <typename T>
910 : inline
911 3582938 : NumericVector<T>::NumericVector (const Parallel::Communicator & comm_in,
912 : const ParallelType ptype) :
913 : ParallelObject(comm_in),
914 3410378 : _is_closed(false),
915 3410378 : _is_initialized(false),
916 3582266 : _type(ptype)
917 : {
918 3486720 : }
919 :
920 :
921 :
922 : template <typename T>
923 : inline
924 0 : NumericVector<T>::NumericVector (const Parallel::Communicator & comm_in,
925 : const numeric_index_type /*n*/,
926 : const ParallelType ptype) :
927 : ParallelObject(comm_in),
928 0 : _is_closed(false),
929 0 : _is_initialized(false),
930 0 : _type(ptype)
931 : {
932 0 : libmesh_not_implemented(); // Abstract base class!
933 : // init(n, n, false, ptype);
934 : }
935 :
936 :
937 :
938 : template <typename T>
939 : inline
940 0 : NumericVector<T>::NumericVector (const Parallel::Communicator & comm_in,
941 : const numeric_index_type /*n*/,
942 : const numeric_index_type /*n_local*/,
943 : const ParallelType ptype) :
944 : ParallelObject(comm_in),
945 0 : _is_closed(false),
946 0 : _is_initialized(false),
947 0 : _type(ptype)
948 : {
949 0 : libmesh_not_implemented(); // Abstract base class!
950 : // init(n, n_local, false, ptype);
951 : }
952 :
953 :
954 :
955 : template <typename T>
956 : inline
957 0 : NumericVector<T>::NumericVector (const Parallel::Communicator & comm_in,
958 : const numeric_index_type /*n*/,
959 : const numeric_index_type /*n_local*/,
960 : const std::vector<numeric_index_type> & /*ghost*/,
961 : const ParallelType ptype) :
962 : ParallelObject(comm_in),
963 0 : _is_closed(false),
964 0 : _is_initialized(false),
965 0 : _type(ptype)
966 : {
967 0 : libmesh_not_implemented(); // Abstract base class!
968 : // init(n, n_local, ghost, false, ptype);
969 : }
970 :
971 :
972 :
973 : template <typename T>
974 : inline
975 0 : void NumericVector<T>::clear ()
976 : {
977 0 : _is_closed = false;
978 0 : _is_initialized = false;
979 0 : }
980 :
981 :
982 :
983 : template <typename T>
984 : inline
985 2077793 : void NumericVector<T>::get(const std::vector<numeric_index_type> & index,
986 : T * values) const
987 : {
988 0 : const std::size_t num = index.size();
989 20993694 : for (std::size_t i=0; i<num; i++)
990 : {
991 18915901 : values[i] = (*this)(index[i]);
992 : }
993 2077793 : }
994 :
995 :
996 :
997 : template <typename T>
998 : inline
999 95615732 : void NumericVector<T>::get(const std::vector<numeric_index_type> & index,
1000 : std::vector<T> & values) const
1001 : {
1002 17261819 : const std::size_t num = index.size();
1003 95615732 : values.resize(num);
1004 95615732 : if (!num)
1005 24266 : return;
1006 :
1007 95345666 : this->get(index, values.data());
1008 : }
1009 :
1010 :
1011 :
1012 : template <typename T>
1013 : inline
1014 0 : void NumericVector<T>::add_vector(const std::vector<T> & v,
1015 : const std::vector<numeric_index_type> & dof_indices)
1016 : {
1017 0 : libmesh_assert(v.size() == dof_indices.size());
1018 0 : if (!v.empty())
1019 0 : this->add_vector(v.data(), dof_indices);
1020 0 : }
1021 :
1022 :
1023 :
1024 : template <typename T>
1025 : inline
1026 19618296 : void NumericVector<T>::add_vector(const DenseVector<T> & v,
1027 : const std::vector<numeric_index_type> & dof_indices)
1028 : {
1029 1891327 : libmesh_assert(v.size() == dof_indices.size());
1030 21543198 : if (!v.empty())
1031 21543198 : this->add_vector(&v(0), dof_indices);
1032 19618296 : }
1033 :
1034 :
1035 :
1036 : template <typename T>
1037 : inline
1038 0 : void NumericVector<T>::insert(const std::vector<T> & v,
1039 : const std::vector<numeric_index_type> & dof_indices)
1040 : {
1041 0 : libmesh_assert(v.size() == dof_indices.size());
1042 0 : if (!v.empty())
1043 0 : this->insert(v.data(), dof_indices);
1044 0 : }
1045 :
1046 :
1047 :
1048 : template <typename T>
1049 : inline
1050 0 : void NumericVector<T>::insert(const DenseVector<T> & v,
1051 : const std::vector<numeric_index_type> & dof_indices)
1052 : {
1053 0 : libmesh_assert(v.size() == dof_indices.size());
1054 0 : if (!v.empty())
1055 0 : this->insert(&v(0), dof_indices);
1056 0 : }
1057 :
1058 :
1059 :
1060 : template <typename T>
1061 : inline
1062 1728 : void NumericVector<T>::insert(const DenseSubVector<T> & v,
1063 : const std::vector<numeric_index_type> & dof_indices)
1064 : {
1065 0 : libmesh_assert(v.size() == dof_indices.size());
1066 1728 : if (!v.empty())
1067 1728 : this->insert(&v(0), dof_indices);
1068 1728 : }
1069 :
1070 :
1071 :
1072 : // Full specialization of the print() member for complex
1073 : // variables. This must precede the non-specialized
1074 : // version, at least according to icc v7.1
1075 : template <>
1076 : inline
1077 0 : void NumericVector<Complex>::print(std::ostream & os) const
1078 : {
1079 : libmesh_assert (this->initialized());
1080 0 : os << "Size\tglobal = " << this->size()
1081 0 : << "\t\tlocal = " << this->local_size() << std::endl;
1082 :
1083 : // std::complex<>::operator<<() is defined, but use this form
1084 0 : os << "#\tReal part\t\tImaginary part" << std::endl;
1085 0 : for (auto i : index_range(*this))
1086 0 : os << i << "\t"
1087 0 : << (*this)(i).real() << "\t\t"
1088 0 : << (*this)(i).imag() << std::endl;
1089 0 : }
1090 :
1091 :
1092 :
1093 : template <typename T>
1094 : inline
1095 0 : void NumericVector<T>::print(std::ostream & os) const
1096 : {
1097 0 : libmesh_assert (this->initialized());
1098 0 : os << "Size\tglobal = " << this->size()
1099 0 : << "\t\tlocal = " << this->local_size() << std::endl;
1100 :
1101 0 : os << "#\tValue" << std::endl;
1102 0 : for (auto i : index_range(*this))
1103 0 : os << i << "\t" << (*this)(i) << std::endl;
1104 0 : }
1105 :
1106 :
1107 :
1108 : template <>
1109 : inline
1110 0 : void NumericVector<Complex>::print_global(std::ostream & os) const
1111 : {
1112 : libmesh_assert (this->initialized());
1113 :
1114 0 : std::vector<Complex> v(this->size());
1115 0 : this->localize(v);
1116 :
1117 : // Right now we only want one copy of the output
1118 0 : if (this->processor_id())
1119 : return;
1120 :
1121 0 : os << "Size\tglobal = " << this->size() << std::endl;
1122 0 : os << "#\tReal part\t\tImaginary part" << std::endl;
1123 0 : for (auto i : make_range(v.size()))
1124 0 : os << i << "\t"
1125 0 : << v[i].real() << "\t\t"
1126 : << v[i].imag() << std::endl;
1127 : }
1128 :
1129 :
1130 : template <typename T>
1131 : inline
1132 0 : void NumericVector<T>::print_global(std::ostream & os) const
1133 : {
1134 0 : libmesh_assert (this->initialized());
1135 :
1136 0 : std::vector<T> v(this->size());
1137 0 : this->localize(v);
1138 :
1139 : // Right now we only want one copy of the output
1140 0 : if (this->processor_id())
1141 0 : return;
1142 :
1143 0 : os << "Size\tglobal = " << this->size() << std::endl;
1144 0 : os << "#\tValue" << std::endl;
1145 0 : for (auto i : make_range(v.size()))
1146 0 : os << i << "\t" << v[i] << std::endl;
1147 : }
1148 :
1149 :
1150 :
1151 : template <typename T>
1152 : inline
1153 1300776 : void NumericVector<T>::swap (NumericVector<T> & v)
1154 : {
1155 28712 : std::swap(_is_closed, v._is_closed);
1156 28712 : std::swap(_is_initialized, v._is_initialized);
1157 28712 : std::swap(_type, v._type);
1158 1327868 : std::swap(_options_prefix, v._options_prefix);
1159 1300776 : }
1160 :
1161 : template <typename T>
1162 : auto
1163 : l1_norm(const NumericVector<T> & vec)
1164 : {
1165 : return vec.l1_norm();
1166 : }
1167 :
1168 : template <typename T>
1169 : auto
1170 : l1_norm_diff(const NumericVector<T> & vec1, const NumericVector<T> & vec2)
1171 : {
1172 : return vec1.l1_norm_diff(vec2);
1173 : }
1174 :
1175 : } // namespace libMesh
1176 :
1177 :
1178 : // Workaround for weird boost/NumericVector interaction bug
1179 : #ifdef LIBMESH_DEFAULT_QUADRUPLE_PRECISION
1180 : #include <boost/mpl/bool.hpp>
1181 :
1182 : namespace boost { namespace multiprecision { namespace detail {
1183 : template <typename T, typename To>
1184 : struct is_lossy_conversion<libMesh::NumericVector<T>, To> {
1185 : typedef boost::mpl::true_ type;
1186 : static const bool value = type::value;
1187 : };
1188 : }}}
1189 : #endif
1190 :
1191 :
1192 : #endif // LIBMESH_NUMERIC_VECTOR_H
|