From 1d57f659041e1eec81f36c65eee847e9fbf0f2fe Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 16 Nov 2020 17:34:47 -0700 Subject: [PATCH] Improve the documentation of a couple of AffineConstraints functions. Specifically, improve the naming of the arguments to better reflect what they refer to. While there also use better doxygen markup. --- include/deal.II/lac/affine_constraints.h | 74 +++++++++++++------ .../lac/affine_constraints.templates.h | 28 +++---- 2 files changed, 65 insertions(+), 37 deletions(-) diff --git a/include/deal.II/lac/affine_constraints.h b/include/deal.II/lac/affine_constraints.h index 28b3d427f8..730c6332f6 100644 --- a/include/deal.II/lac/affine_constraints.h +++ b/include/deal.II/lac/affine_constraints.h @@ -704,7 +704,10 @@ public: add_lines(const IndexSet &lines); /** - * Add an entry to a given line. The list of lines is searched from the back + * Add an entry to a given line. In other words, this function adds + * a term $a_{ij} x_j$ to the constraints for the $i$th degree of freedom. + * + * This function searches existing constraints from the back * to the front, so clever programming would add a new line (which is pushed * to the back) and immediately afterwards fill the entries of that line. * This way, no expensive searching is needed. @@ -713,27 +716,41 @@ public: * already exists, then this function simply returns provided that the value * of the entry is the same. Thus, it does no harm to enter a constraint * twice. + * + * @param[in] constrained_dof_index The index $i$ of the degree of freedom + * that is being constrained. + * @param[in] column The index $j$ of the degree of freedom being entered + * into the constraint for degree of freedom $i$. + * @param[in] weight The factor $a_{ij}$ that multiplies $x_j$. */ void - add_entry(const size_type line_n, const size_type column, const number value); + add_entry(const size_type constrained_dof_index, + const size_type column, + const number weight); /** * Add a whole series of entries, denoted by pairs of column indices and - * values, to a line of constraints. This function is equivalent to calling - * the preceding function several times, but is faster. + * weight values, to a line of constraints. This function is equivalent to + * calling the preceding function several times, but is faster. */ void - add_entries(const size_type line_n, - const std::vector> &col_val_pairs); + add_entries( + const size_type constrained_dof_index, + const std::vector> &col_weight_pairs); /** - * Set an inhomogeneity to the constraint line @p line_n, according to the - * discussion in the general class description. + * Set an inhomogeneity to the constraint for a degree of freedom. In other + * words, it adds a constant $b_i$ to the constraint for degree of freedom + * $i$. For this to work, you need to call add_line() first for the given + * degree of freedom. * - * @note the line needs to be added with one of the add_line() calls first. + * @param[in] constrained_dof_index The index $i$ of the degree of freedom + * that is being constrained. + * @param[in] value The right hand side value $b_i$ for the constraint on + * the degree of freedom $i$. */ void - set_inhomogeneity(const size_type line_n, const number value); + set_inhomogeneity(const size_type constrained_dof_index, const number value); /** * Close the filling of entries. Since the lines of a matrix of this type @@ -752,8 +769,9 @@ public: * while degree of freedom 7 is itself constrained as $u_{7} = \frac{u_2}{2} * + \frac{u_4}{2}$. Then, the resolution will be that $u_{13} = * \frac{u_3}{2} + \frac{u_2}{4} + \frac{u_4}{4}$. Note, however, that - * cycles in this graph of constraints are not allowed, i.e. for example - * $u_4$ may not be constrained, directly or indirectly, to $u_{13}$ again. + * cycles in this graph of constraints are not allowed, i.e., for example + * $u_4$ may not itself be constrained, directly or indirectly, to $u_{13}$ + * again. */ void close(); @@ -1974,18 +1992,20 @@ AffineConstraints::add_line(const size_type line_n) lines_cache[line_index] = lines.size() - 1; } + + template inline void -AffineConstraints::add_entry(const size_type line_n, +AffineConstraints::add_entry(const size_type constrained_dof_index, const size_type column, - const number value) + const number weight) { Assert(sorted == false, ExcMatrixIsClosed()); - Assert(line_n != column, + Assert(constrained_dof_index != column, ExcMessage("Can't constrain a degree of freedom to itself")); // Ensure that the current line is present in the cache: - const size_type line_index = calculate_line_index(line_n); + const size_type line_index = calculate_line_index(constrained_dof_index); Assert(line_index < lines_cache.size(), ExcMessage("The current AffineConstraints does not contain the line " "for the current entry. Call AffineConstraints::add_line " @@ -1999,26 +2019,30 @@ AffineConstraints::add_entry(const size_type line_n, Assert(lines_cache[line_index] != numbers::invalid_size_type, ExcInternalError()); Assert(!local_lines.size() || local_lines.is_element(column), - ExcColumnNotStoredHere(line_n, column)); + ExcColumnNotStoredHere(constrained_dof_index, column)); ConstraintLine *line_ptr = &lines[lines_cache[line_index]]; - Assert(line_ptr->index == line_n, ExcInternalError()); + Assert(line_ptr->index == constrained_dof_index, ExcInternalError()); for (const auto &p : line_ptr->entries) if (p.first == column) { - Assert(std::abs(p.second - value) < 1.e-14, - ExcEntryAlreadyExists(line_n, column, p.second, value)); + Assert(std::abs(p.second - weight) < 1.e-14, + ExcEntryAlreadyExists( + constrained_dof_index, column, p.second, weight)); return; } - line_ptr->entries.emplace_back(column, value); + line_ptr->entries.emplace_back(column, weight); } + + template inline void -AffineConstraints::set_inhomogeneity(const size_type line_n, - const number value) +AffineConstraints::set_inhomogeneity( + const size_type constrained_dof_index, + const number value) { - const size_type line_index = calculate_line_index(line_n); + const size_type line_index = calculate_line_index(constrained_dof_index); Assert(line_index < lines_cache.size() && lines_cache[line_index] != numbers::invalid_size_type, ExcMessage("call add_line() before calling set_inhomogeneity()")); @@ -2027,6 +2051,8 @@ AffineConstraints::set_inhomogeneity(const size_type line_n, line_ptr->inhomogeneity = value; } + + template template inline void diff --git a/include/deal.II/lac/affine_constraints.templates.h b/include/deal.II/lac/affine_constraints.templates.h index 8dc3938a11..65f3002a97 100644 --- a/include/deal.II/lac/affine_constraints.templates.h +++ b/include/deal.II/lac/affine_constraints.templates.h @@ -237,40 +237,42 @@ AffineConstraints::add_lines(const IndexSet &lines) template void AffineConstraints::add_entries( - const size_type line_n, - const std::vector> &col_val_pairs) + const size_type constrained_dof_index, + const std::vector> &col_weight_pairs) { Assert(sorted == false, ExcMatrixIsClosed()); - Assert(is_constrained(line_n), ExcLineInexistant(line_n)); + Assert(is_constrained(constrained_dof_index), + ExcLineInexistant(constrained_dof_index)); - ConstraintLine &line = lines[lines_cache[calculate_line_index(line_n)]]; - Assert(line.index == line_n, ExcInternalError()); + ConstraintLine &line = + lines[lines_cache[calculate_line_index(constrained_dof_index)]]; + Assert(line.index == constrained_dof_index, ExcInternalError()); // if in debug mode, check whether an entry for this column already // exists and if its the same as the one entered at present // // in any case: skip this entry if an entry for this column already // exists, since we don't want to enter it twice - for (const std::pair &col_val_pair : col_val_pairs) + for (const std::pair &col_weight_pair : col_weight_pairs) { - Assert(line_n != col_val_pair.first, + Assert(constrained_dof_index != col_weight_pair.first, ExcMessage("Can't constrain a degree of freedom to itself")); bool entry_exists = false; for (const std::pair &entry : line.entries) - if (entry.first == col_val_pair.first) + if (entry.first == col_weight_pair.first) { // entry exists, break innermost loop - Assert(entry.second == col_val_pair.second, - ExcEntryAlreadyExists(line_n, - col_val_pair.first, + Assert(entry.second == col_weight_pair.second, + ExcEntryAlreadyExists(constrained_dof_index, + col_weight_pair.first, entry.second, - col_val_pair.second)); + col_weight_pair.second)); entry_exists = true; break; } if (entry_exists == false) - line.entries.push_back(col_val_pair); + line.entries.push_back(col_weight_pair); } } -- 2.39.5