From b7c3b2fe1fc997913da450ad50359c0155adde43 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 15 Apr 2024 19:45:21 -0600 Subject: [PATCH] Better document operator= for parallel vectors. --- include/deal.II/lac/block_vector.h | 4 ++- .../deal.II/lac/la_parallel_block_vector.h | 20 ++++++++++--- include/deal.II/lac/la_parallel_vector.h | 29 +++++++++++++++---- include/deal.II/lac/petsc_block_vector.h | 9 +++++- include/deal.II/lac/petsc_vector.h | 24 +++++++++++++++ include/deal.II/lac/trilinos_epetra_vector.h | 24 +++++++++++++++ .../lac/trilinos_parallel_block_vector.h | 9 +++++- .../lac/trilinos_tpetra_block_vector.h | 9 +++++- include/deal.II/lac/trilinos_tpetra_vector.h | 24 +++++++++++++++ include/deal.II/lac/trilinos_vector.h | 26 ++++++++++++++++- 10 files changed, 163 insertions(+), 15 deletions(-) diff --git a/include/deal.II/lac/block_vector.h b/include/deal.II/lac/block_vector.h index 46a7739c9e..aa1001f687 100644 --- a/include/deal.II/lac/block_vector.h +++ b/include/deal.II/lac/block_vector.h @@ -198,7 +198,9 @@ public: /** * Copy operator for arguments of the same type. Resize the present vector - * if necessary. + * if necessary to the correct number of blocks, then copy the individual + * blocks from `v` using the copy-assignment operator of the class that + * represents the individual blocks. */ BlockVector & operator=(const BlockVector &v); diff --git a/include/deal.II/lac/la_parallel_block_vector.h b/include/deal.II/lac/la_parallel_block_vector.h index e9231a6c90..d4b2b41e42 100644 --- a/include/deal.II/lac/la_parallel_block_vector.h +++ b/include/deal.II/lac/la_parallel_block_vector.h @@ -208,15 +208,27 @@ namespace LinearAlgebra operator=(const value_type s); /** - * Copy operator for arguments of the same type. Resize the present - * vector if necessary. + * Copy operator for arguments of the same type. Resize the present vector + * if necessary to the correct number of blocks, then copy the individual + * blocks from `v` using the copy-assignment operator of the class that + * represents the individual blocks. + * + * Copying the vectors that make up individual blocks can have complex + * semantics in parallel vector classes. See the information provided + * by the class used to represent the individual blocks. */ BlockVector & operator=(const BlockVector &V); /** - * Copy operator for template arguments of different types. Resize the - * present vector if necessary. + * Copy operator for arguments of different type. Resize the present + * vector if necessary to the correct number of blocks, then copy the + * individual blocks from `v` using the copy-assignment operator of the + * class that represents the individual blocks. + * + * Copying the vectors that make up individual blocks can have complex + * semantics in parallel vector classes. See the information provided + * by the class used to represent the individual blocks. */ template BlockVector & diff --git a/include/deal.II/lac/la_parallel_vector.h b/include/deal.II/lac/la_parallel_vector.h index 69956963ea..31e5916222 100644 --- a/include/deal.II/lac/la_parallel_vector.h +++ b/include/deal.II/lac/la_parallel_vector.h @@ -467,12 +467,29 @@ namespace LinearAlgebra * Assigns the vector to the parallel partitioning of the input vector * @p in_vector, and copies all the data. * - * If one of the input vector or the calling vector (to the left of the - * assignment operator) had ghost elements set before this operation, - * the calling vector will have ghost values set. Otherwise, it will be - * in write mode. If the input vector does not have any ghost elements - * at all, the vector will also update its ghost values in analogy to - * the respective setting the Trilinos and PETSc vectors. + * The semantics of this operator are complex. If the two vectors have + * the same size, and + * if either the left or right hand side vector of the assignment (i.e., + * either the input vector on the right hand side, or the calling vector + * to the left of the assignment operator) currently has ghost elements, + * then the left hand side vector will also have ghost values and will + * consequently be a read-only vector (see also the + * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the + * left hand vector will be a writable vector after this operation. + * These semantics facilitate having a vector with ghost elements on the + * left hand side of the assignment, and a vector without ghost elements + * on the right hand side, with the resulting left hand side vector + * having the correct values in both its locally owned and its ghost + * elements. + * + * On the other hand, if the left hand side vector does not have the + * correct size yet, or is perhaps an entirely uninitialized vector, + * then the assignment is simply a copy operation in the usual sense: + * In that case, if the right hand side has no ghost elements (i.e., + * is a completely distributed vector), then the left hand side will + * have no ghost elements either. And if the right hand side has + * ghost elements (and is consequently read-only), then the left + * hand side will have these same properties after the operation. */ Vector & operator=(const Vector &in_vector); diff --git a/include/deal.II/lac/petsc_block_vector.h b/include/deal.II/lac/petsc_block_vector.h index a6209ea95e..801997ed38 100644 --- a/include/deal.II/lac/petsc_block_vector.h +++ b/include/deal.II/lac/petsc_block_vector.h @@ -156,7 +156,14 @@ namespace PETScWrappers operator=(const value_type s); /** - * Copy operator for arguments of the same type. + * Copy operator for arguments of the same type. Resize the present vector + * if necessary to the correct number of blocks, then copy the individual + * blocks from `v` using the copy-assignment operator of the class that + * represents the individual blocks. + * + * Copying the vectors that make up individual blocks can have complex + * semantics in parallel vector classes. See the information provided + * by the class used to represent the individual blocks. */ BlockVector & operator=(const BlockVector &V); diff --git a/include/deal.II/lac/petsc_vector.h b/include/deal.II/lac/petsc_vector.h index 706d23cd4c..d2747a0754 100644 --- a/include/deal.II/lac/petsc_vector.h +++ b/include/deal.II/lac/petsc_vector.h @@ -262,6 +262,30 @@ namespace PETScWrappers /** * Copy the given vector. Resize the present vector if necessary. Also * take over the MPI communicator of @p v. + * + * The semantics of this operator are complex. If the two vectors have + * the same size, and + * if either the left or right hand side vector of the assignment (i.e., + * either the input vector on the right hand side, or the calling vector + * to the left of the assignment operator) currently has ghost elements, + * then the left hand side vector will also have ghost values and will + * consequently be a read-only vector (see also the + * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the + * left hand vector will be a writable vector after this operation. + * These semantics facilitate having a vector with ghost elements on the + * left hand side of the assignment, and a vector without ghost elements + * on the right hand side, with the resulting left hand side vector + * having the correct values in both its locally owned and its ghost + * elements. + * + * On the other hand, if the left hand side vector does not have the + * correct size yet, or is perhaps an entirely uninitialized vector, + * then the assignment is simply a copy operation in the usual sense: + * In that case, if the right hand side has no ghost elements (i.e., + * is a completely distributed vector), then the left hand side will + * have no ghost elements either. And if the right hand side has + * ghost elements (and is consequently read-only), then the left + * hand side will have these same properties after the operation. */ Vector & operator=(const Vector &v); diff --git a/include/deal.II/lac/trilinos_epetra_vector.h b/include/deal.II/lac/trilinos_epetra_vector.h index 53fa509a3c..3a67af3f32 100644 --- a/include/deal.II/lac/trilinos_epetra_vector.h +++ b/include/deal.II/lac/trilinos_epetra_vector.h @@ -115,6 +115,30 @@ namespace LinearAlgebra * Copy function. This function takes a Vector and copies all the * elements. The Vector will have the same parallel distribution as @p * V. + * + * The semantics of this operator are complex. If the two vectors have + * the same size, and + * if either the left or right hand side vector of the assignment (i.e., + * either the input vector on the right hand side, or the calling vector + * to the left of the assignment operator) currently has ghost elements, + * then the left hand side vector will also have ghost values and will + * consequently be a read-only vector (see also the + * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the + * left hand vector will be a writable vector after this operation. + * These semantics facilitate having a vector with ghost elements on the + * left hand side of the assignment, and a vector without ghost elements + * on the right hand side, with the resulting left hand side vector + * having the correct values in both its locally owned and its ghost + * elements. + * + * On the other hand, if the left hand side vector does not have the + * correct size yet, or is perhaps an entirely uninitialized vector, + * then the assignment is simply a copy operation in the usual sense: + * In that case, if the right hand side has no ghost elements (i.e., + * is a completely distributed vector), then the left hand side will + * have no ghost elements either. And if the right hand side has + * ghost elements (and is consequently read-only), then the left + * hand side will have these same properties after the operation. */ Vector & operator=(const Vector &V); diff --git a/include/deal.II/lac/trilinos_parallel_block_vector.h b/include/deal.II/lac/trilinos_parallel_block_vector.h index 6175aff910..f1278eb9cf 100644 --- a/include/deal.II/lac/trilinos_parallel_block_vector.h +++ b/include/deal.II/lac/trilinos_parallel_block_vector.h @@ -152,7 +152,14 @@ namespace TrilinosWrappers operator=(const value_type s); /** - * Copy operator for arguments of the same type. + * Copy operator for arguments of the same type. Resize the present vector + * if necessary to the correct number of blocks, then copy the individual + * blocks from `v` using the copy-assignment operator of the class that + * represents the individual blocks. + * + * Copying the vectors that make up individual blocks can have complex + * semantics in parallel vector classes. See the information provided + * by the class used to represent the individual blocks. */ BlockVector & operator=(const BlockVector &v); diff --git a/include/deal.II/lac/trilinos_tpetra_block_vector.h b/include/deal.II/lac/trilinos_tpetra_block_vector.h index c23fa5c6df..7d9f73132a 100644 --- a/include/deal.II/lac/trilinos_tpetra_block_vector.h +++ b/include/deal.II/lac/trilinos_tpetra_block_vector.h @@ -149,7 +149,14 @@ namespace LinearAlgebra operator=(const Number s); /** - * Copy operator for arguments of the same type. + * Copy operator for arguments of the same type. Resize the present vector + * if necessary to the correct number of blocks, then copy the individual + * blocks from `v` using the copy-assignment operator of the class that + * represents the individual blocks. + * + * Copying the vectors that make up individual blocks can have complex + * semantics in parallel vector classes. See the information provided + * by the class used to represent the individual blocks. */ BlockVector & operator=(const BlockVector &v); diff --git a/include/deal.II/lac/trilinos_tpetra_vector.h b/include/deal.II/lac/trilinos_tpetra_vector.h index 2990a86469..f6a1091b1d 100644 --- a/include/deal.II/lac/trilinos_tpetra_vector.h +++ b/include/deal.II/lac/trilinos_tpetra_vector.h @@ -427,6 +427,30 @@ namespace LinearAlgebra * Copy function. This function takes a Vector and copies all the * elements. The Vector will have the same parallel distribution as @p * V. + * + * The semantics of this operator are complex. If the two vectors have + * the same size, and + * if either the left or right hand side vector of the assignment (i.e., + * either the input vector on the right hand side, or the calling vector + * to the left of the assignment operator) currently has ghost elements, + * then the left hand side vector will also have ghost values and will + * consequently be a read-only vector (see also the + * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the + * left hand vector will be a writable vector after this operation. + * These semantics facilitate having a vector with ghost elements on the + * left hand side of the assignment, and a vector without ghost elements + * on the right hand side, with the resulting left hand side vector + * having the correct values in both its locally owned and its ghost + * elements. + * + * On the other hand, if the left hand side vector does not have the + * correct size yet, or is perhaps an entirely uninitialized vector, + * then the assignment is simply a copy operation in the usual sense: + * In that case, if the right hand side has no ghost elements (i.e., + * is a completely distributed vector), then the left hand side will + * have no ghost elements either. And if the right hand side has + * ghost elements (and is consequently read-only), then the left + * hand side will have these same properties after the operation. */ Vector & operator=(const Vector &V); diff --git a/include/deal.II/lac/trilinos_vector.h b/include/deal.II/lac/trilinos_vector.h index 9af84431a7..62ffb35102 100644 --- a/include/deal.II/lac/trilinos_vector.h +++ b/include/deal.II/lac/trilinos_vector.h @@ -672,8 +672,32 @@ namespace TrilinosWrappers /** * Copy the given vector. Resize the present vector if necessary. In - * this case, also the Epetra_Map that designs the parallel partitioning + * this case, also the `Epetra_Map` that designs the parallel partitioning * is taken from the input vector. + * + * The semantics of this operator are complex. If the two vectors have + * the same size, and + * if either the left or right hand side vector of the assignment (i.e., + * either the input vector on the right hand side, or the calling vector + * to the left of the assignment operator) currently has ghost elements, + * then the left hand side vector will also have ghost values and will + * consequently be a read-only vector (see also the + * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the + * left hand vector will be a writable vector after this operation. + * These semantics facilitate having a vector with ghost elements on the + * left hand side of the assignment, and a vector without ghost elements + * on the right hand side, with the resulting left hand side vector + * having the correct values in both its locally owned and its ghost + * elements. + * + * On the other hand, if the left hand side vector does not have the + * correct size yet, or is perhaps an entirely uninitialized vector, + * then the assignment is simply a copy operation in the usual sense: + * In that case, if the right hand side has no ghost elements (i.e., + * is a completely distributed vector), then the left hand side will + * have no ghost elements either. And if the right hand side has + * ghost elements (and is consequently read-only), then the left + * hand side will have these same properties after the operation. */ Vector & operator=(const Vector &v); -- 2.39.5