Better document operator= for parallel vectors.

diff --git a/include/deal.II/lac/block_vector.h b/include/deal.II/lac/block_vector.h
index 46a7739c9ecb2acf3637d6c9d837625b244e0a8d..aa1001f687f4433d1a52c66d76527e3fa4877e59 100644 (file)
--- 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<Number> &
   operator=(const BlockVector<Number> &v);

diff --git a/include/deal.II/lac/la_parallel_block_vector.h b/include/deal.II/lac/la_parallel_block_vector.h
index e9231a6c90c14a1a9f1e0be74032c31d95d581cd..d4b2b41e42f6f066f865c7ae3602f099b78cce51 100644 (file)
--- 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 <class Number2>
       BlockVector &

diff --git a/include/deal.II/lac/la_parallel_vector.h b/include/deal.II/lac/la_parallel_vector.h
index 69956963eaaeeb65fb4850db7a6c5e54c4cae5f3..31e591622254806425f17a433d7cbd3fe3392254 100644 (file)
--- 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<Number, MemorySpace> &
       operator=(const Vector<Number, MemorySpace> &in_vector);

diff --git a/include/deal.II/lac/petsc_block_vector.h b/include/deal.II/lac/petsc_block_vector.h
index a6209ea95eab2786b9acf5567c88b992a54f891b..801997ed38e04785b25d1a7ce488c9f967666e7e 100644 (file)
--- 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 706d23cd4cd763c9290fcc2d95d44e97164748de..d2747a07547e355fed3462b7b97c60a693e988c6 100644 (file)
--- 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 53fa509a3cb38a06e4f107d35e83563300b320b6..3a67af3f32b2e0582dbcea1ae699fd4b234d60ae 100644 (file)
--- 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 6175aff9101c1a52e4d6d3642f30fbd4915b65b1..f1278eb9cf5c472c10b4f6550ac36c7f134cbf71 100644 (file)
--- 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 c23fa5c6df5560b3b639ef96ac0053cc26c3c29b..7d9f73132a63b5eef596a4326200aad3be69f45a 100644 (file)
--- 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<Number, MemorySpace> &
       operator=(const BlockVector<Number, MemorySpace> &v);

diff --git a/include/deal.II/lac/trilinos_tpetra_vector.h b/include/deal.II/lac/trilinos_tpetra_vector.h
index 2990a8646983b5bdc034bfea9ee7a6ab08d4c70f..f6a1091b1d2b00be486d935905e30944b2c933ed 100644 (file)
--- 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 9af84431a7988376f616c75078f4c3d0e8275733..62ffb35102cb8faf1a715a4e44cae71f22d3f385 100644 (file)
--- 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);