From ddba084637ea6605d07bd0633fb35811f3ca3ea0 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 17 Jan 2018 21:03:47 -0700 Subject: [PATCH] Update documentation of *::Vector::add_and_dot for complex vectors. --- include/deal.II/lac/block_vector_base.h | 3 +++ include/deal.II/lac/cuda_vector.h | 3 +++ include/deal.II/lac/la_parallel_block_vector.h | 3 +++ include/deal.II/lac/la_parallel_vector.h | 6 +++++- include/deal.II/lac/la_vector.h | 10 ++++++++++ include/deal.II/lac/petsc_vector_base.h | 3 +++ include/deal.II/lac/trilinos_epetra_vector.h | 3 +++ include/deal.II/lac/trilinos_vector.h | 3 +++ include/deal.II/lac/vector.h | 10 +++++++--- include/deal.II/lac/vector_space_vector.h | 3 +++ 10 files changed, 43 insertions(+), 4 deletions(-) diff --git a/include/deal.II/lac/block_vector_base.h b/include/deal.II/lac/block_vector_base.h index 99a446afe6..f1936311db 100644 --- a/include/deal.II/lac/block_vector_base.h +++ b/include/deal.II/lac/block_vector_base.h @@ -823,6 +823,9 @@ public: * means to load the calling vector @p this twice. Since most vector * operations are memory transfer limited, this reduces the time by 25\% (or * 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ value_type add_and_dot (const value_type a, const BlockVectorBase &V, diff --git a/include/deal.II/lac/cuda_vector.h b/include/deal.II/lac/cuda_vector.h index 95292245c0..6370afe42b 100644 --- a/include/deal.II/lac/cuda_vector.h +++ b/include/deal.II/lac/cuda_vector.h @@ -214,6 +214,9 @@ namespace LinearAlgebra * calling separate methods means to load the calling vector @p this * twice. Since most vector operations are memory transfer limited, this * reduces the time by 25\% (or 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual Number add_and_dot(const Number a, const VectorSpaceVector &V, diff --git a/include/deal.II/lac/la_parallel_block_vector.h b/include/deal.II/lac/la_parallel_block_vector.h index 2dd164b7a9..b257286e60 100644 --- a/include/deal.II/lac/la_parallel_block_vector.h +++ b/include/deal.II/lac/la_parallel_block_vector.h @@ -549,6 +549,9 @@ namespace LinearAlgebra * separate methods means to load the calling vector @p this twice. Since * most vector operations are memory transfer limited, this reduces the * time by 25\% (or 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual Number add_and_dot(const Number a, const VectorSpaceVector &V, diff --git a/include/deal.II/lac/la_parallel_vector.h b/include/deal.II/lac/la_parallel_vector.h index f10736a373..6bf234994f 100644 --- a/include/deal.II/lac/la_parallel_vector.h +++ b/include/deal.II/lac/la_parallel_vector.h @@ -665,6 +665,9 @@ namespace LinearAlgebra * separate methods means to load the calling vector @p this twice. Since * most vector operations are memory transfer limited, this reduces the * time by 25\% (or 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual Number add_and_dot(const Number a, const VectorSpaceVector &V, @@ -1095,7 +1098,8 @@ namespace LinearAlgebra /** * Local part of the addition followed by an inner product of two - * vectors. + * vectors. The same applies for complex-valued vectors as for + * the add_and_dot() function. */ Number add_and_dot_local (const Number a, const Vector &V, diff --git a/include/deal.II/lac/la_vector.h b/include/deal.II/lac/la_vector.h index 08c27c47e3..f0198e0c90 100644 --- a/include/deal.II/lac/la_vector.h +++ b/include/deal.II/lac/la_vector.h @@ -262,6 +262,16 @@ namespace LinearAlgebra * this->add(a, V); * return_value = *this * W; * @endcode + * + * The reason this function exists is that this operation involves less + * memory transfer than calling the two functions separately. This method + * only needs to load three vectors, @p this, @p V, @p W, whereas calling + * separate methods means to load the calling vector @p this twice. Since + * most vector operations are memory transfer limited, this reduces the time + * by 25\% (or 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual Number add_and_dot(const Number a, const VectorSpaceVector &V, diff --git a/include/deal.II/lac/petsc_vector_base.h b/include/deal.II/lac/petsc_vector_base.h index 96209c8af2..9d55dac143 100644 --- a/include/deal.II/lac/petsc_vector_base.h +++ b/include/deal.II/lac/petsc_vector_base.h @@ -547,6 +547,9 @@ namespace PETScWrappers * transfer. However, for PETSc vectors such a combined operation is not * natively supported and thus the cost is completely equivalent as * calling the two methods separately. + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ PetscScalar add_and_dot (const PetscScalar a, const VectorBase &V, diff --git a/include/deal.II/lac/trilinos_epetra_vector.h b/include/deal.II/lac/trilinos_epetra_vector.h index 53faf8da1e..b381858183 100644 --- a/include/deal.II/lac/trilinos_epetra_vector.h +++ b/include/deal.II/lac/trilinos_epetra_vector.h @@ -229,6 +229,9 @@ namespace LinearAlgebra * reduces the time by 25\% (or 50\% if @p W equals @p this). * * The vectors need to have the same layout. + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual double add_and_dot(const double a, const VectorSpaceVector &V, diff --git a/include/deal.II/lac/trilinos_vector.h b/include/deal.II/lac/trilinos_vector.h index 261e77833b..384ac93138 100644 --- a/include/deal.II/lac/trilinos_vector.h +++ b/include/deal.II/lac/trilinos_vector.h @@ -839,6 +839,9 @@ namespace TrilinosWrappers * transfer. However, for Trilinos vectors such a combined operation is * not natively supported and thus the cost is completely equivalent as * calling the two methods separately. + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ TrilinosScalar add_and_dot (const TrilinosScalar a, const Vector &V, diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h index 7e712c095b..8d3f4d5cfa 100644 --- a/include/deal.II/lac/vector.h +++ b/include/deal.II/lac/vector.h @@ -494,13 +494,17 @@ public: * most vector operations are memory transfer limited, this reduces the time * by 25\% (or 50\% if @p W equals @p this). * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. + * * @dealiiOperationIsMultithreaded 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 add_and_dot (const Number a, - const Vector &V, - const Vector &W); + Number + add_and_dot (const Number a, + const Vector &V, + const Vector &W); //@} diff --git a/include/deal.II/lac/vector_space_vector.h b/include/deal.II/lac/vector_space_vector.h index 337de25b0d..4b109b532b 100644 --- a/include/deal.II/lac/vector_space_vector.h +++ b/include/deal.II/lac/vector_space_vector.h @@ -184,6 +184,9 @@ namespace LinearAlgebra * separate methods means to load the calling vector @p this twice. Since * most vector operations are memory transfer limited, this reduces the * time by 25\% (or 50\% if @p W equals @p this). + * + * For complex-valued vectors, the scalar product in the second step is implemented as + * $\left=\sum_i v_i \bar{w_i}$. */ virtual Number add_and_dot(const Number a, const VectorSpaceVector &V, -- 2.39.5