From 47eadc0a0ebbbd5c1d857d35a6a699fe8df3481e Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sat, 24 Oct 2015 12:27:25 -0500 Subject: [PATCH] Write a glossary entry on how to use the new facility --- doc/doxygen/headers/constraints.h | 58 ++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/doc/doxygen/headers/constraints.h b/doc/doxygen/headers/constraints.h index a2d6d1ed90..0a5ed06cb7 100644 --- a/doc/doxygen/headers/constraints.h +++ b/doc/doxygen/headers/constraints.h @@ -1,6 +1,6 @@ // --------------------------------------------------------------------- // -// Copyright (C) 2010 - 2013 by the deal.II authors +// Copyright (C) 2010 - 2015 by the deal.II authors // // This file is part of the deal.II library. // @@ -432,4 +432,60 @@ * Either behavior can also be achieved by building two separate * ConstraintMatrix objects and calling ConstraintMatrix::merge function with * a particular second argument. + * + * + *

Applying constraints indirectly with a LinearOperator

+ * + * Sometimes it is either not desirable, or not possible to directly + * condensate, or eliminate constraints from a system of linear equations. + * In particular if there is no underlying matrix object that could be + * condensed (or taken care of constraints during assembly). This is + * usually the case if the system is described by a LinearOperator. + * + * In this case we can solve the modified system + * @f[ + * (C^T \cdot A \cdot C + Id_c) \tilde x = C^T (b - A\,k) + * @f] + * instead [1]. Here, $A$ is a given (unconstrained) system matrix $A$ 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 + * @f[ + $x$ \leftarrow C\,x+k. + * @f] + * And finally, $Id_c$ denotes the identity on the subspace of constrained + * degrees of freedom. + * + * The corresponding solution of $A\,x=b$ that obeys boundary conditions is + * then recovered by distributing constraints to $\tilde x$: $x=C\tilde + * x+k$. + * + * The whole system can be set up and solved with the following snippet of + * code: + * @code + * #include + * + * // ... + * + * // system_matrix - unconstrained and assembled system matrix + * // right_hand_side - unconstrained and assembled right hand side + * // constraint_matrix - a ConstraintMatrix object + * // solver - an appropriate, iterative solver + * // preconditioner - a preconditioner + * + * const auto op_a = linear_operator(system_matrix); + * const auto op_amod = constrained_linear_operator(constraint_matrix, op_a); + * Vector rhs_mod = constrained_right_hand_side(constraint_matrix, + * op_a, + * right_hand_side); + * + * solver.solve(op_amod, solution, rhs_mod, preconditioner); + * constraint_matrix.distribute(solution); + * @endcode + * + * [1] M. S. Shephard: Linear multipoint constraints applied via + * transformation as part of a direct stiffness assembly process, 1985. */ -- 2.39.5