From a99c439ead3e4458b4a5f656f6580c7dcf42ab42 Mon Sep 17 00:00:00 2001 From: Martin Kronbichler Date: Tue, 8 Jul 2014 08:19:47 +0000 Subject: [PATCH] Document which basic linear algebra functions are currently multithreaded. git-svn-id: https://svn.dealii.org/trunk@33116 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/base/aligned_vector.h | 17 +- deal.II/include/deal.II/lac/full_matrix.h | 6 + deal.II/include/deal.II/lac/sparse_matrix.h | 18 + deal.II/include/deal.II/lac/vector.h | 823 +++++++----------- 4 files changed, 368 insertions(+), 496 deletions(-) diff --git a/deal.II/include/deal.II/base/aligned_vector.h b/deal.II/include/deal.II/base/aligned_vector.h index f963e8e894..e6decccd45 100644 --- a/deal.II/include/deal.II/base/aligned_vector.h +++ b/deal.II/include/deal.II/base/aligned_vector.h @@ -77,6 +77,9 @@ public: /** * Sets the vector size to the given size and initializes all elements with * T(). + * + * @note If deal.II is configured with threads, the initialization will run + * multi-threaded over subranges of the vector. */ AlignedVector (const size_type size, const T &init = T()); @@ -88,11 +91,17 @@ public: /** * Copy constructor. + * + * @note If deal.II is configured with threads, the initialization will run + * multi-threaded over subranges of the vector. */ AlignedVector (const AlignedVector &vec); /** * Assignment to the input vector @p vec. + * + * @note If deal.II is configured with threads, the initialization will run + * multi-threaded over subranges of the vector. */ AlignedVector & operator = (const AlignedVector &vec); @@ -109,6 +118,9 @@ public: * available, and initializes each element with the specified data. If the * new vector size is shorter than the old one, the memory is not released * unless the new size is zero. + * + * @note If deal.II is configured with threads, the initialization will run + * multi-threaded over subranges of the vector. */ void resize (const size_type size_in, const T &init = T()); @@ -155,7 +167,10 @@ public: ForwardIterator end); /** - * Fills the vector with size() copies of the given input + * Fills the vector with size() copies of the given input. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void fill (const T &element); diff --git a/deal.II/include/deal.II/lac/full_matrix.h b/deal.II/include/deal.II/lac/full_matrix.h index 3ebef4e653..4d7ada0229 100644 --- a/deal.II/include/deal.II/lac/full_matrix.h +++ b/deal.II/include/deal.II/lac/full_matrix.h @@ -268,6 +268,9 @@ public: /** * Assignment operator. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded (if the number of matrix entries is larger than 20,000). */ FullMatrix & operator = (const FullMatrix &); @@ -283,6 +286,9 @@ public: * This operator assigns a scalar to a matrix. To avoid confusion with the * semantics of this function, zero is the only value allowed for * d, allowing you to clear a matrix in an intuitive way. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded (if the number of matrix entries is larger than 20,000). */ FullMatrix & operator = (const number d); diff --git a/deal.II/include/deal.II/lac/sparse_matrix.h b/deal.II/include/deal.II/lac/sparse_matrix.h index f0cf4bf438..b0e1631ea1 100644 --- a/deal.II/include/deal.II/lac/sparse_matrix.h +++ b/deal.II/include/deal.II/lac/sparse_matrix.h @@ -632,6 +632,9 @@ public: * exists to allow for the obvious notation matrix=0, which sets * all elements of the matrix to zero, but keep the sparsity pattern * previously used. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ SparseMatrix &operator = (const double d); @@ -1074,6 +1077,9 @@ public: * consider using a BlockSparseMatrix as well. * * Source and destination must not be the same vector. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ template void vmult (OutVector &dst, @@ -1109,6 +1115,9 @@ public: * consider using a BlockSparseMatrix as well. * * Source and destination must not be the same vector. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ template void vmult_add (OutVector &dst, @@ -1146,12 +1155,18 @@ public: * The underlying template types of both this matrix and the given vector * should either both be real or complex-valued, but not mixed, for this * function to make sense. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ template somenumber matrix_norm_square (const Vector &v) const; /** * Compute the matrix scalar product $\left(u,Mv\right)$. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ template somenumber matrix_scalar_product (const Vector &u, @@ -1163,6 +1178,9 @@ public: * l2 norm of the residual vector is returned. * * Source x and destination dst must not be the same vector. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded by splitting the work over matrix rows. */ template somenumber residual (Vector &dst, diff --git a/deal.II/include/deal.II/lac/vector.h b/deal.II/include/deal.II/lac/vector.h index ceea283c5d..9adec866d2 100644 --- a/deal.II/include/deal.II/lac/vector.h +++ b/deal.II/include/deal.II/lac/vector.h @@ -111,10 +111,8 @@ class Vector : public Subscriptor { public: /** - * Declare standard types used in all - * containers. These types parallel - * those in the C++ standard libraries - * vector<...> class. + * Declare standard types used in all containers. These types parallel those + * in the C++ standard libraries vector<...> class. */ typedef Number value_type; typedef value_type *pointer; @@ -126,23 +124,13 @@ public: typedef types::global_dof_index size_type; /** - * Declare a type that has holds - * real-valued numbers with the - * same precision as the template - * argument to this class. If the - * template argument of this - * class is a real data type, - * then real_type equals the - * template argument. If the - * template argument is a - * std::complex type then - * real_type equals the type - * underlying the complex - * numbers. + * Declare a type that has holds real-valued numbers with the same precision + * as the template argument to this class. If the template argument of this + * class is a real data type, then real_type equals the template + * argument. If the template argument is a std::complex type then real_type + * equals the type underlying the complex numbers. * - * This typedef is used to - * represent the return type of - * norms. + * This typedef is used to represent the return type of norms. */ typedef typename numbers::NumberTraits::real_type real_type; @@ -166,43 +154,32 @@ public: */ //@{ /** - * Constructor. Create a vector of - * dimension zero. + * Constructor. Create a vector of dimension zero. */ Vector (); /** - * Copy-constructor. Sets the dimension - * to that of the given vector, and + * Copy-constructor. Sets the dimension to that of the given vector, and * copies all elements. * - * We would like to make this - * constructor explicit, but STL - * insists on using it implicitly. + * We would like to make this constructor explicit, but STL insists on using + * it implicitly. */ Vector (const Vector &v); #ifndef DEAL_II_EXPLICIT_CONSTRUCTOR_BUG /** - * Copy constructor taking a vector of - * another data type. This will fail if - * there is no conversion path from - * @p OtherNumber to @p Number. Note that - * you may lose accuracy when copying - * to a vector with data elements with + * Copy constructor taking a vector of another data type. This will fail if + * there is no conversion path from @p OtherNumber to @p Number. Note that + * you may lose accuracy when copying to a vector with data elements with * less accuracy. * - * Older versions of gcc did not honor - * the @p explicit keyword on template - * constructors. In such cases, it is - * easy to accidentally write code that - * can be very inefficient, since the - * compiler starts performing hidden - * conversions. To avoid this, this - * function is disabled if we have - * detected a broken compiler during - * configuration. + * Older versions of gcc did not honor the @p explicit keyword on template + * constructors. In such cases, it is easy to accidentally write code that + * can be very inefficient, since the compiler starts performing hidden + * conversions. To avoid this, this function is disabled if we have detected + * a broken compiler during configuration. */ template explicit @@ -211,164 +188,111 @@ public: #ifdef DEAL_II_WITH_PETSC /** - * Another copy constructor: copy the - * values from a sequential PETSc wrapper - * vector class. This copy constructor is - * only available if PETSc was detected - * during configuration time. + * Another copy constructor: copy the values from a sequential PETSc wrapper + * vector class. This copy constructor is only available if PETSc was + * detected during configuration time. */ Vector (const PETScWrappers::Vector &v); /** - * Another copy constructor: copy the - * values from a parallel PETSc wrapper - * vector class. This copy constructor is - * only available if PETSc was detected - * during configuration time. + * Another copy constructor: copy the values from a parallel PETSc wrapper + * vector class. This copy constructor is only available if PETSc was + * detected during configuration time. * - * Note that due to the communication - * model used in MPI, this operation can - * only succeed if all processes do it at - * the same time. I.e., it is not - * possible for only one process to - * obtain a copy of a parallel vector - * while the other jobs do something - * else. + * Note that due to the communication model used in MPI, this operation can + * only succeed if all processes do it at the same time. I.e., it is not + * possible for only one process to obtain a copy of a parallel vector while + * the other jobs do something else. */ Vector (const PETScWrappers::MPI::Vector &v); #endif #ifdef DEAL_II_WITH_TRILINOS /** - * Another copy constructor: copy - * the values from a Trilinos - * wrapper vector. This copy - * constructor is only available if - * Trilinos was detected during - * configuration time. + * Another copy constructor: copy the values from a Trilinos wrapper + * vector. This copy constructor is only available if Trilinos was detected + * during configuration time. * - * Note that due to the - * communication model used in MPI, - * this operation can only succeed - * if all processes do it at the - * same time. This means that it is - * not possible for only one - * process to obtain a copy of a - * parallel vector while the other - * jobs do something else. This - * call will rather result in a - * copy of the vector on all - * processors. + * Note that due to the communication model used in MPI, this operation can + * only succeed if all processes do it at the same time. This means that it + * is not possible for only one process to obtain a copy of a parallel + * vector while the other jobs do something else. This call will rather + * result in a copy of the vector on all processors. */ Vector (const TrilinosWrappers::MPI::Vector &v); /** - * Another copy constructor: copy - * the values from a localized - * Trilinos wrapper vector. This - * copy constructor is only - * available if Trilinos was - * detected during configuration - * time. + * Another copy constructor: copy the values from a localized Trilinos + * wrapper vector. This copy constructor is only available if Trilinos was + * detected during configuration time. */ Vector (const TrilinosWrappers::Vector &v); #endif /** - * Constructor. Set dimension to - * @p n and initialize all - * elements with zero. + * Constructor. Set dimension to @p n and initialize all elements with zero. * - * The constructor is made - * explicit to avoid accidents - * like this: - * v=0;. Presumably, the user - * wants to set every element of - * the vector to zero, but - * instead, what happens is this - * call: - * v=Vector@(0);, - * i.e. the vector is replaced by - * one of length zero. + * The constructor is made explicit to avoid accidents like this: + * v=0;. Presumably, the user wants to set every element of the + * vector to zero, but instead, what happens is this call: + * v=Vector@(0);, i.e. the vector is replaced by one of + * length zero. */ explicit Vector (const size_type n); /** - * Initialize the vector with a - * given range of values pointed - * to by the iterators. This - * function is there in analogy - * to the @p std::vector class. + * Initialize the vector with a given range of values pointed to by the + * iterators. This function is there in analogy to the @p std::vector class. */ template Vector (const InputIterator first, const InputIterator last); /** - * Destructor, deallocates - * memory. Made virtual to allow - * for derived classes to behave - * properly. + * Destructor, deallocates memory. Made virtual to allow for derived classes + * to behave properly. */ virtual ~Vector (); /** - * This function does nothing but is - * there for compatibility with the - * @p PETScWrappers::Vector class. + * This function does nothing but is there for compatibility with the @p + * PETScWrappers::Vector class. * - * For the PETSc vector wrapper class, - * this function compresses the - * underlying representation of the PETSc - * object, i.e. flushes the buffers of - * the vector object if it has any. This - * function is necessary after writing - * into a vector element-by-element and - * before anything else can be done on - * it. + * For the PETSc vector wrapper class, this function compresses the + * underlying representation of the PETSc object, i.e. flushes the buffers + * of the vector object if it has any. This function is necessary after + * writing into a vector element-by-element and before anything else can be + * done on it. * - * However, for the implementation of - * this class, it is immaterial and thus + * However, for the implementation of this class, it is immaterial and thus * an empty function. */ void compress (::dealii::VectorOperation::values operation =::dealii::VectorOperation::unknown) const; /** - * Change the dimension of the vector to - * @p N. The reserved memory for this - * vector remains unchanged if possible, - * to make things faster; this may waste - * some memory, so keep this in mind. - * However, if N==0 all memory is - * freed, i.e. if you want to resize the - * vector and release the memory not - * needed, you have to first call - * reinit(0) and then - * reinit(N). This cited behaviour is - * analogous to that of the STL + * Change the dimension of the vector to @p N. The reserved memory for this + * vector remains unchanged if possible, to make things faster; this may + * waste some memory, so keep this in mind. However, if N==0 all + * memory is freed, i.e. if you want to resize the vector and release the + * memory not needed, you have to first call reinit(0) and then + * reinit(N). This cited behaviour is analogous to that of the STL * containers. * - * If @p fast is false, the vector is - * filled by zeros. Otherwise, the - * elements are left an unspecified - * state. + * If @p fast is false, the vector is filled by zeros. Otherwise, the + * elements are left an unspecified state. * - * This function is virtual in - * order to allow for derived - * classes to handle memory - * separately. + * This function is virtual in order to allow for derived classes to handle + * memory separately. */ virtual void reinit (const size_type N, const bool fast=false); /** - * Change the dimension to that of the - * vector @p V. The same applies as for + * Change the dimension to that of the vector @p V. The same applies as for * the other @p reinit function. * - * The elements of @p V are not copied, - * i.e. this function is the same as + * The elements of @p V are not copied, i.e. this function is the same as * calling reinit (V.size(), fast). */ template @@ -376,105 +300,78 @@ public: const bool fast=false); /** - * Swap the contents of this - * vector and the other vector - * @p v. One could do this - * operation with a temporary - * variable and copying over the - * data elements, but this - * function is significantly more - * efficient since it only swaps - * the pointers to the data of - * the two vectors and therefore - * does not need to allocate - * temporary storage and move - * data around. + * Swap the contents of this vector and the other vector @p v. One could do + * this operation with a temporary variable and copying over the data + * elements, but this function is significantly more efficient since it only + * swaps the pointers to the data of the two vectors and therefore does not + * need to allocate temporary storage and move data around. * - * This function is analog to the - * the @p swap function of all C++ - * standard containers. Also, - * there is a global function - * swap(u,v) that simply calls - * u.swap(v), again in analogy - * to standard functions. + * This function is analog to the the @p swap function of all C++ standard + * containers. Also, there is a global function swap(u,v) that + * simply calls u.swap(v), again in analogy to standard functions. * - * This function is virtual in - * order to allow for derived - * classes to handle memory - * separately. + * This function is virtual in order to allow for derived classes to handle + * memory separately. */ virtual void swap (Vector &v); /** - * Set all components of the vector to - * the given number @p s. Simply pass - * this down to the individual block - * objects, but we still need to declare - * this function to make the example - * given in the discussion about making + * Set all components of the vector to the given number @p s. Simply pass + * this down to the individual block objects, but we still need to declare + * this function to make the example given in the discussion about making * the constructor explicit work. * - * Since the semantics of assigning a - * scalar to a vector are not - * immediately clear, this operator - * should really only be used if you - * want to set the entire vector to - * zero. This allows the intuitive - * notation v=0. Assigning - * other values is deprecated and may - * be disallowed in the future. + * Since the semantics of assigning a scalar to a vector are not immediately + * clear, this operator should really only be used if you want to set the + * entire vector to zero. This allows the intuitive notation + * v=0. Assigning other values is deprecated and may be disallowed + * in the future. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator = (const Number s); /** - * Copy the given vector. Resize the - * present vector if necessary. + * Copy the given vector. Resize the present vector if necessary. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator= (const Vector &v); /** - * Copy the given vector. Resize the - * present vector if necessary. + * Copy the given vector. Resize the present vector if necessary. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ template Vector &operator= (const Vector &v); /** - * Copy operator for assigning a - * block vector to a regular - * vector. + * Copy operator for assigning a block vector to a regular vector. */ Vector &operator= (const BlockVector &v); #ifdef DEAL_II_WITH_PETSC /** - * Another copy operator: copy the - * values from a sequential PETSc - * wrapper vector class. This - * operator is only available if - * PETSc was detected during - * configuration time. + * Another copy operator: copy the values from a sequential PETSc wrapper + * vector class. This operator is only available if PETSc was detected + * during configuration time. */ Vector & operator = (const PETScWrappers::Vector &v); /** - * Another copy operator: copy the - * values from a parallel PETSc - * wrapper vector class. This - * operator is only available if - * PETSc was detected during - * configuration time. + * Another copy operator: copy the values from a parallel PETSc wrapper + * vector class. This operator is only available if PETSc was detected + * during configuration time. * - * Note that due to the - * communication model used in MPI, - * this operation can only succeed - * if all processes do it at the - * same time. I.e., it is not - * possible for only one process to - * obtain a copy of a parallel - * vector while the other jobs do - * something else. + * Note that due to the communication model used in MPI, this operation can + * only succeed if all processes do it at the same time. I.e., it is not + * possible for only one process to obtain a copy of a parallel vector while + * the other jobs do something else. */ Vector & operator = (const PETScWrappers::MPI::Vector &v); @@ -483,126 +380,122 @@ public: #ifdef DEAL_II_WITH_TRILINOS /** - * Another copy operator: copy - * the values from a (sequential - * or parallel, depending on the - * underlying compiler) Trilinos - * wrapper vector class. This - * operator is only available if - * Trilinos was detected during - * configuration time. + * Another copy operator: copy the values from a (sequential or parallel, + * depending on the underlying compiler) Trilinos wrapper vector class. This + * operator is only available if Trilinos was detected during configuration + * time. * - * Note that due to the - * communication model used in MPI, - * this operation can only succeed - * if all processes do it at the - * same time. I.e., it is not - * possible for only one process to - * obtain a copy of a parallel - * vector while the other jobs do - * something else. + * Note that due to the communication model used in MPI, this operation can + * only succeed if all processes do it at the same time. I.e., it is not + * possible for only one process to obtain a copy of a parallel vector while + * the other jobs do something else. */ Vector & operator = (const TrilinosWrappers::MPI::Vector &v); /** - * Another copy operator: copy the - * values from a sequential - * Trilinos wrapper vector - * class. This operator is only - * available if Trilinos was - * detected during configuration - * time. + * Another copy operator: copy the values from a sequential Trilinos wrapper + * vector class. This operator is only available if Trilinos was detected + * during configuration time. */ Vector & operator = (const TrilinosWrappers::Vector &v); #endif /** - * Test for equality. This function - * assumes that the present vector - * and the one to compare with have - * the same size already, since - * comparing vectors of different - * sizes makes not much sense - * anyway. + * Test for equality. This function assumes that the present vector and the + * one to compare with have the same size already, since comparing vectors + * of different sizes makes not much sense anyway. */ template bool operator == (const Vector &v) const; /** - * Test for inequality. This function - * assumes that the present vector and - * the one to compare with have the same - * size already, since comparing vectors - * of different sizes makes not much - * sense anyway. + * Test for inequality. This function assumes that the present vector and + * the one to compare with have the same size already, since comparing + * vectors of different sizes makes not much sense anyway. */ template bool operator != (const Vector &v) const; /** - * Return the scalar product of - * two vectors. The return type - * is the underlying type of - * @p this vector, so the return - * type and the accuracy with - * which it the result is - * computed depend on the order - * of the arguments of this - * vector. + * Return the scalar product of two vectors. The return type is the + * underlying type of @p this vector, so the return type and the accuracy + * with which it the result is computed depend on the order of the arguments + * of this vector. + * + * For complex vectors, the scalar product is implemented as + * $\left=\sum_i v_i \bar{w_i}$. * - * For complex vectors, the - * scalar product is implemented - * as $\left=\sum_i - * v_i \bar{w_i}$. + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ template Number operator * (const Vector &V) const; /** * Return square of the $l_2$-norm. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ real_type norm_sqr () const; /** - * Mean value of the elements of - * this vector. + * Mean value of the elements of this vector. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ Number mean_value () const; /** - * $l_1$-norm of the vector. - * The sum of the absolute values. + * $l_1$-norm of the vector. The sum of the absolute values. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ real_type l1_norm () const; /** - * $l_2$-norm of the vector. The - * square root of the sum of the - * squares of the elements. + * $l_2$-norm of the vector. The square root of the sum of the squares of + * the elements. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ real_type l2_norm () const; /** - * $l_p$-norm of the vector. The - * pth root of the sum of the pth - * powers of the absolute values - * of the elements. + * $l_p$-norm of the vector. The pth root of the sum of the pth powers of + * the absolute values of the elements. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. The algorithm uses pairwise + * summation with the same order of summation in every run, which gives + * fully repeatable results from one run to another. */ real_type lp_norm (const real_type p) const; /** - * Maximum absolute value of the - * elements. + * Maximum absolute value of the elements. */ real_type linfty_norm () const; /** - * Returns true if the given global index is - * in the local range of this processor. - * Since this is not a distributed - * vector the method always returns true. + * Returns true if the given global index is in the local range of this + * processor. Since this is not a distributed vector the method always + * returns true. */ bool in_local_range (const size_type global_index) const; @@ -632,55 +525,43 @@ public: std::size_t size () const; /** - * Return whether the vector contains only - * elements with value zero. This function - * is mainly for internal consistency - * checks and should seldom be used when - * not in debug mode since it uses quite - * some time. + * Return whether the vector contains only elements with value zero. This + * function is mainly for internal consistency checks and should seldom be + * used when not in debug mode since it uses quite some time. */ bool all_zero () const; /** - * Return @p true if the vector has no - * negative entries, i.e. all entries are - * zero or positive. This function is - * used, for example, to check whether - * refinement indicators are really all - * positive (or zero). + * Return @p true if the vector has no negative entries, i.e. all entries + * are zero or positive. This function is used, for example, to check + * whether refinement indicators are really all positive (or zero). * - * The function obviously only makes - * sense if the template argument of this - * class is a real type. If it is a - * complex type, then an exception is + * The function obviously only makes sense if the template argument of this + * class is a real type. If it is a complex type, then an exception is * thrown. */ bool is_non_negative () const; /** - * Make the @p Vector class a bit like - * the vector<> class of the C++ - * standard library by returning - * iterators to the start and end of the + * Make the @p Vector class a bit like the vector<> class of the + * C++ standard library by returning iterators to the start and end of the * elements of this vector. */ iterator begin (); /** - * Return constant iterator to the start of - * the vectors. + * Return constant iterator to the start of the vectors. */ const_iterator begin () const; /** - * Return an iterator pointing to the - * element past the end of the array. + * Return an iterator pointing to the element past the end of the array. */ iterator end (); /** - * Return a constant iterator pointing to - * the element past the end of the array. + * Return a constant iterator pointing to the element past the end of the + * array. */ const_iterator end () const; //@} @@ -691,50 +572,42 @@ public: */ //@{ /** - * Access the value of the @p ith - * component. + * Access the value of the @p ith component. */ Number operator() (const size_type i) const; /** - * Access the @p ith component - * as a writeable reference. + * Access the @p ith component as a writeable reference. */ Number &operator() (const size_type i); /** - * Access the value of the @p ith - * component. + * Access the value of the @p ith component. * * Exactly the same as operator(). */ Number operator[] (const size_type i) const; /** - * Access the @p ith component - * as a writeable reference. + * Access the @p ith component as a writeable reference. * * Exactly the same as operator(). */ Number &operator[] (const size_type i); /** - * A collective get operation: instead - * of getting individual elements of a - * vector, this function allows to get - * a whole set of elements at once. The - * indices of the elements to be read - * are stated in the first argument, - * the corresponding values are returned in the - * second. + * A collective get operation: instead of getting individual elements of a + * vector, this function allows to get a whole set of elements at once. The + * indices of the elements to be read are stated in the first argument, the + * corresponding values are returned in the second. */ template void extract_subvector_to (const std::vector &indices, std::vector &values) const; /** - * Just as the above, but with pointers. - * Useful in minimizing copying of data around. + * Just as the above, but with pointers. Useful in minimizing copying of + * data around. */ template void extract_subvector_to (ForwardIterator indices_begin, @@ -749,48 +622,41 @@ public: //@{ /** - * Add the given vector to the present - * one. + * Add the given vector to the present one. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator += (const Vector &V); /** - * Subtract the given vector from the - * present one. + * Subtract the given vector from the present one. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator -= (const Vector &V); /** - * A collective add operation: - * This funnction adds a whole - * set of values stored in @p - * values to the vector - * components specified by @p - * indices. + * A collective add operation: This funnction adds a whole set of values + * stored in @p values to the vector components specified by @p indices. */ template void add (const std::vector &indices, const std::vector &values); /** - * This is a second collective - * add operation. As a - * difference, this function - * takes a deal.II vector of - * values. + * This is a second collective add operation. As a difference, this function + * takes a deal.II vector of values. */ template void add (const std::vector &indices, const Vector &values); /** - * Take an address where - * n_elements are stored - * contiguously and add them into - * the vector. Handles all cases - * which are not covered by the - * other two add() - * functions above. + * Take an address where n_elements are stored contiguously and add + * them into the vector. Handles all cases which are not covered by the + * other two add() functions above. */ template void add (const size_type n_elements, @@ -798,42 +664,53 @@ public: const OtherNumber *values); /** - * Addition of @p s to all - * components. Note that @p s is a - * scalar and not a vector. + * Addition of @p s to all components. Note that @p s is a scalar and not a + * vector. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void add (const Number s); /** - * Simple vector addition, equal to the - * operator +=. + * Simple vector addition, equal to the operator +=. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void add (const Vector &V); /** - * Simple addition of a multiple of a - * vector, i.e. *this += a*V. + * Simple addition of a multiple of a vector, i.e. *this += a*V. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void add (const Number a, const Vector &V); /** - * Multiple addition of scaled vectors, - * i.e. *this += a*V+b*W. + * Multiple addition of scaled vectors, i.e. *this += a*V+b*W. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void add (const Number a, const Vector &V, const Number b, const Vector &W); /** - * Scaling and simple vector addition, - * i.e. - * *this = s*(*this)+V. + * Scaling and simple vector addition, i.e. *this = s*(*this)+V. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void sadd (const Number s, const Vector &V); /** - * Scaling and simple addition, i.e. - * *this = s*(*this)+a*V. + * Scaling and simple addition, i.e. *this = s*(*this)+a*V. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void sadd (const Number s, const Number a, @@ -841,6 +718,9 @@ public: /** * Scaling and multiple addition. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void sadd (const Number s, const Number a, @@ -849,8 +729,11 @@ public: const Vector &W); /** - * Scaling and multiple addition. - * *this = s*(*this)+a*V + b*W + c*X. + * Scaling and multiple addition. *this = s*(*this)+a*V + b*W + + * c*X. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void sadd (const Number s, const Number a, @@ -861,14 +744,10 @@ public: const Vector &X); /** - * Scale each element of the - * vector by the given factor. + * Scale each element of the vector by the given factor. * - * @deprecated This function is deprecated - * and will be removed in a - * future version. Use - * operator *= and - * operator /= instead. + * @deprecated This function is deprecated and will be removed in a future + * version. Use operator *= and operator /= instead. */ void scale (const Number factor) DEAL_II_DEPRECATED { @@ -877,44 +756,44 @@ public: /** - * Scale each element of the - * vector by a constant - * value. + * Scale each element of the vector by a constant value. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator *= (const Number factor); /** - * Scale each element of the - * vector by the inverse of the - * given value. + * Scale each element of the vector by the inverse of the given value. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ Vector &operator /= (const Number factor); /** - * Scale each element of this - * vector by the corresponding - * element in the argument. This - * function is mostly meant to - * simulate multiplication (and - * immediate re-assignment) by a - * diagonal scaling matrix. + * Scale each element of this vector by the corresponding element in the + * argument. This function is mostly meant to simulate multiplication (and + * immediate re-assignment) by a diagonal scaling matrix. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void scale (const Vector &scaling_factors); /** - * Scale each element of this - * vector by the corresponding - * element in the argument. This - * function is mostly meant to - * simulate multiplication (and - * immediate re-assignment) by a - * diagonal scaling matrix. + * Scale each element of this vector by the corresponding element in the + * argument. This function is mostly meant to simulate multiplication (and + * immediate re-assignment) by a diagonal scaling matrix. */ template void scale (const Vector &scaling_factors); /** * Assignment *this = a*u. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void equ (const Number a, const Vector &u); @@ -926,49 +805,48 @@ public: /** * Assignment *this = a*u + b*v. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void equ (const Number a, const Vector &u, const Number b, const Vector &v); /** * Assignment *this = a*u + b*v + b*w. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void equ (const Number a, const Vector &u, const Number b, const Vector &v, const Number c, const Vector &w); /** - * Compute the elementwise ratio of the - * two given vectors, that is let - * this[i] = a[i]/b[i]. This is - * useful for example if you want to - * compute the cellwise ratio of true to - * estimated error. + * Compute the elementwise ratio of the two given vectors, that is let + * this[i] = a[i]/b[i]. This is useful for example if you want to + * compute the cellwise ratio of true to estimated error. * - * This vector is appropriately - * scaled to hold the result. + * This vector is appropriately scaled to hold the result. * - * If any of the b[i] is - * zero, the result is - * undefined. No attempt is made - * to catch such situations. + * If any of the b[i] is zero, the result is undefined. No attempt + * is made to catch such situations. + * + * @note If deal.II is configured with threads, this operation will run + * multi-threaded over subranges of the vector. */ void ratio (const Vector &a, const Vector &b); /** - * This function does nothing but is - * there for compatibility with the - * @p PETScWrappers::Vector class. + * This function does nothing but is there for compatibility with the @p + * PETScWrappers::Vector class. * - * For the PETSc vector wrapper class, - * this function updates the ghost - * values of the PETSc vector. This - * is necessary after any modification + * For the PETSc vector wrapper class, this function updates the ghost + * values of the PETSc vector. This is necessary after any modification * before reading ghost values. * - * However, for the implementation of - * this class, it is immaterial and thus + * However, for the implementation of this class, it is immaterial and thus * an empty function. */ void update_ghost_values () const; @@ -980,27 +858,16 @@ public: */ //@{ /** - * Output of vector in user-defined - * format. For complex-valued vectors, - * the format should include specifiers - * for both the real and imaginary - * parts. + * Output of vector in user-defined format. For complex-valued vectors, the + * format should include specifiers for both the real and imaginary parts. */ void print (const char *format = 0) const; /** - * Print to a - * stream. @p precision denotes - * the desired precision with - * which values shall be printed, - * @p scientific whether - * scientific notation shall be - * used. If @p across is - * @p true then the vector is - * printed in a line, while if - * @p false then the elements - * are printed on a separate line - * each. + * Print to a stream. @p precision denotes the desired precision with which + * values shall be printed, @p scientific whether scientific notation shall + * be used. If @p across is @p true then the vector is printed in a line, + * while if @p false then the elements are printed on a separate line each. */ void print (std::ostream &out, const unsigned int precision = 3, @@ -1008,71 +875,52 @@ public: const bool across = true) const; /** - * Print to a - * LogStream. width is - * used as argument to the - * std::setw manipulator, if - * printing across. If @p - * across is @p true then the - * vector is printed in a line, - * while if @p false then the - * elements are printed on a - * separate line each. + * Print to a LogStream. width is used as argument to the std::setw + * manipulator, if printing across. If @p across is @p true then the vector + * is printed in a line, while if @p false then the elements are printed on + * a separate line each. */ void print (LogStream &out, const unsigned int width = 6, const bool across = true) const; /** - * Write the vector en bloc to a - * file. This is done in a binary - * mode, so the output is neither - * readable by humans nor - * (probably) by other computers - * using a different operating - * system or number format. + * Write the vector en bloc to a file. This is done in a binary mode, so the + * output is neither readable by humans nor (probably) by other computers + * using a different operating system or number format. */ void block_write (std::ostream &out) const; /** - * Read a vector en block from a - * file. This is done using the - * inverse operations to the - * above function, so it is - * reasonably fast because the + * Read a vector en block from a file. This is done using the inverse + * operations to the above function, so it is reasonably fast because the * bitstream is not interpreted. * - * The vector is resized if - * necessary. + * The vector is resized if necessary. * - * A primitive form of error - * checking is performed which - * will recognize the bluntest - * attempts to interpret some - * data as a vector stored - * bitwise to a file, but not - * more. + * A primitive form of error checking is performed which will recognize the + * bluntest attempts to interpret some data as a vector stored bitwise to a + * file, but not more. */ void block_read (std::istream &in); /** - * Determine an estimate for the - * memory consumption (in bytes) - * of this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; //@} /** - * Write the data of this object to - * a stream for the purpose of serialization. + * Write the data of this object to a stream for the purpose of + * serialization. */ template void save (Archive &ar, const unsigned int version) const; /** - * Read the data of this object - * from a stream for the purpose of serialization. + * Read the data of this object from a stream for the purpose of + * serialization. */ template void load (Archive &ar, const unsigned int version); @@ -1082,48 +930,36 @@ public: protected: /** - * Dimension. Actual number of - * components contained in the - * vector. Get this number by - * calling size(). + * Dimension. Actual number of components contained in the vector. Get this + * number by calling size(). */ size_type vec_size; /** - * Amount of memory actually - * reserved for this vector. This - * number may be greater than - * @p vec_size if a @p reinit was - * called with less memory - * requirements than the vector - * needed last time. At present - * @p reinit does not free - * memory when the number of - * needed elements is reduced. + * Amount of memory actually reserved for this vector. This number may be + * greater than @p vec_size if a @p reinit was called with less memory + * requirements than the vector needed last time. At present @p reinit does + * not free memory when the number of needed elements is reduced. */ size_type max_vec_size; /** - * Pointer to the array of - * elements of this vector. + * Pointer to the array of elements of this vector. */ Number *val; /** - * Make all other vector types - * friends. + * Make all other vector types friends. */ template friend class Vector; /** - * LAPACK matrices need access to - * the data. + * LAPACK matrices need access to the data. */ friend class LAPACKFullMatrix; /** - * VectorView will access the - * pointer. + * VectorView will access the pointer. */ friend class VectorView; }; @@ -1154,9 +990,8 @@ Vector::Vector (const InputIterator first, const InputIterator last) max_vec_size (0), val (0) { - // allocate memory. do not - // initialize it, as we will copy - // over to it in a second + // allocate memory. do not initialize it, as we will copy over to it in a + // second reinit (std::distance (first, last), true); std::copy (first, last, begin()); } @@ -1486,8 +1321,7 @@ inline void Vector::save (Archive &ar, const unsigned int) const { - // forward to serialization - // function in the base class. + // forward to serialization function in the base class. ar &static_cast(*this); ar &vec_size &max_vec_size ; @@ -1502,8 +1336,7 @@ inline void Vector::load (Archive &ar, const unsigned int) { - // forward to serialization - // function in the base class. + // forward to serialization function in the base class. ar &static_cast(*this); ar &vec_size &max_vec_size ; -- 2.39.5