From 8f70cc317cabccd8f09efa3142994e79f5b369a5 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Mon, 28 Dec 2015 12:57:42 +0100 Subject: [PATCH] Update documentation --- doc/doxygen/headers/constraints.h | 23 ++++++----- .../deal.II/lac/constrained_linear_operator.h | 41 +++++++++++++++---- 2 files changed, 47 insertions(+), 17 deletions(-) diff --git a/doc/doxygen/headers/constraints.h b/doc/doxygen/headers/constraints.h index ab9c8179d6..5e1f7943e4 100644 --- a/doc/doxygen/headers/constraints.h +++ b/doc/doxygen/headers/constraints.h @@ -446,16 +446,19 @@ * @f[ * (C^T A C + Id_c) \tilde x = C^T (b - A\,k) * @f] - * instead [1] (M. S. Shephard: Linear multipoint constraints applied via - * transformation as part of a direct stiffness assembly process, 1985). - * - * Here, $A$ is a given (unconstrained) system matrix and $b$ - * the corresponding right hand side of a system of linear equations - * $A\,x=b$. The matrix $C$ describes the homogeneous part of the linear - * constraints stored in a ConstraintMatrix and the vector $k$ is the - * vector of corresponding inhomogeneities. More precisely, the - * ConstraintMatrix::distribute() operation applied on a vector $x$ is the - * operation + * instead [1] (M. S. Shephard. Linear multipoint constraints applied via + * transformation as part of a direct stiffness assembly process. + * International Journal for Numerical Methods in Engineering + * 20(11):2107-2112, 1985). + * + * Here, $A$ is a given (unconstrained) system matrix for wich we only + * assume that we can apply it to a vector but can not necessarily access + * individual matrix entries. $b$ is the corresponding right hand side of a + * system of linear equations $A\,x=b$. The matrix $C$ describes the + * homogeneous part of the linear constraints stored in a ConstraintMatrix + * and the vector $k$ is the vector of corresponding inhomogeneities. More + * precisely, the ConstraintMatrix::distribute() operation applied on a + * vector $x$ is the operation * @f[ x \leftarrow C\,x+k. * @f] diff --git a/include/deal.II/lac/constrained_linear_operator.h b/include/deal.II/lac/constrained_linear_operator.h index be63b086bc..19a1969b25 100644 --- a/include/deal.II/lac/constrained_linear_operator.h +++ b/include/deal.II/lac/constrained_linear_operator.h @@ -34,9 +34,10 @@ DEAL_II_NAMESPACE_OPEN /** * This function takes a ConstraintMatrix @p constraint_matrix and an * operator exemplar @p exemplar (this exemplar is usually a linear - * operator that describes the system matrix) and returns a LinearOperator - * object associated with the "homogeneous action" of the underlying - * ConstraintMatrix object: + * operator that describes the system matrix - it is only used to create + * domain and range vectors of appropriate sizes, its action vmult + * is never used). A LinearOperator object associated with the "homogeneous + * action" of the underlying ConstraintMatrix object is returned: * * Applying the LinearOperator object on a vector u results in * a vector v that stores the result of calling @@ -52,6 +53,9 @@ DEAL_II_NAMESPACE_OPEN * * @author Mauro Bardelloni, Matthias Maier, 2015 * + * @note Currently, this function may not work correctly for distributed data + * structures. + * * @relates LinearOperator * @ingroup constraints */ @@ -64,15 +68,19 @@ LinearOperator distribute_constraints_linear_operator( return_op.vmult_add = [&constraint_matrix](Range &v, const Domain &u) { + Assert(!dealii::PointerComparison::equal(&v, &u), + dealii::ExcMessage("The domain and range vectors must be different " + "storage locations")); + for (auto i : v.locally_owned_elements()) { if (constraint_matrix.is_constrained(i)) { - const auto *entries = constraint_matrix.get_constraint_entries (i); + const auto *entries = constraint_matrix.get_constraint_entries(i); for (types::global_dof_index j = 0; j < entries->size(); ++j) { const auto pos = (*entries)[j].first; - v(i) += u(pos) * (*entries)[j].second; + v(i) += u(pos) * (*entries)[j].second; } } else @@ -82,6 +90,10 @@ LinearOperator distribute_constraints_linear_operator( return_op.Tvmult_add = [&constraint_matrix](Domain &v, const Range &u) { + Assert(!dealii::PointerComparison::equal(&v, &u), + dealii::ExcMessage("The domain and range vectors must be different " + "storage locations")); + for (auto i : v.locally_owned_elements()) { if (constraint_matrix.is_constrained(i)) @@ -120,8 +132,10 @@ LinearOperator distribute_constraints_linear_operator( /** * Given a ConstraintMatrix @p constraint_matrix and an operator exemplar - * @p exemplar, return an LinearOperator that is the projection to the - * subspace of constrained degrees of freedom. + * @p exemplar, return a LinearOperator that is the projection to the + * subspace of constrained degrees of freedom, i.e. all entries of the + * result vector that correspond to unconstrained degrees of freedom are + * set to zero. * * @author Mauro Bardelloni, Matthias Maier, 2015 * @@ -151,6 +165,10 @@ LinearOperator project_to_constrained_linear_operator( return_op.vmult = [&constraint_matrix](Range &v, const Domain &u) { + Assert(!dealii::PointerComparison::equal(&v, &u), + dealii::ExcMessage("The domain and range vectors must be different " + "storage locations")); + v = 0.; for (auto i : v.locally_owned_elements()) if (constraint_matrix.is_constrained(i)) @@ -159,6 +177,9 @@ LinearOperator project_to_constrained_linear_operator( return_op.Tvmult = [&constraint_matrix](Domain &v, const Range &u) { + Assert(!dealii::PointerComparison::equal(&v, &u), + dealii::ExcMessage("The domain and range vectors must be different " + "storage locations")); v = 0.; for (auto i : v.locally_owned_elements()) if (constraint_matrix.is_constrained(i)) @@ -199,6 +220,9 @@ LinearOperator project_to_constrained_linear_operator( * * @author Mauro Bardelloni, Matthias Maier, 2015 * + * @note Currently, this function may not work correctly for distributed data + * structures. + * * @relates LinearOperator * @ingroup constraints */ @@ -243,6 +267,9 @@ constrained_linear_operator(const ConstraintMatrix &constraint_matrix, * * @author Mauro Bardelloni, Matthias Maier, 2015 * + * @note Currently, this function may not work correctly for distributed data + * structures. + * * @relates LinearOperator * @ingroup constraints */ -- 2.39.5