
Classes | |
| struct | ConstraintLine |
Public Types | |
| enum | MergeConflictBehavior { no_conflicts_allowed, left_object_wins, right_object_wins } |
Public Member Functions | |
| ConstraintMatrix (const IndexSet &local_constraints=IndexSet()) | |
| ConstraintMatrix (const ConstraintMatrix &constraint_matrix) | |
| void | reinit (const IndexSet &local_constraints=IndexSet()) |
| bool | can_store_line (const unsigned int line_index) const |
| void | add_selected_constraints (const ConstraintMatrix &constraints_in, const IndexSet &filter) |
Adding constraints | |
| void | add_line (const unsigned int line) |
| void | add_lines (const std::vector< bool > &lines) |
| void | add_lines (const std::set< unsigned int > &lines) |
| void | add_lines (const IndexSet &lines) |
| void | add_entry (const unsigned int line, const unsigned int column, const double value) |
| void | add_entries (const unsigned int line, const std::vector< std::pair< unsigned int, double > > &col_val_pairs) |
| void | set_inhomogeneity (const unsigned int line, const double value) |
| void | close () |
| void | merge (const ConstraintMatrix &other_constraints, const MergeConflictBehavior merge_conflict_behavior=no_conflicts_allowed) |
| void | shift (const unsigned int offset) |
| void | clear () |
Querying constraints | |
| unsigned int | n_constraints () const |
| bool | is_constrained (const unsigned int index) const |
| bool | is_identity_constrained (const unsigned int index) const |
| unsigned int | max_constraint_indirections () const |
| bool | is_inhomogeneously_constrained (const unsigned int index) const |
| bool | has_inhomogeneities () const |
| const std::vector< std::pair < unsigned int, double > > * | get_constraint_entries (const unsigned int line) const |
| double | get_inhomogeneity (const unsigned int line) const |
| void | print (std::ostream &) const |
| void | write_dot (std::ostream &) const |
| std::size_t | memory_consumption () const |
Eliminating constraints from linear systems after their creation | |
| void | condense (const SparsityPattern &uncondensed, SparsityPattern &condensed) const |
| void | condense (SparsityPattern &sparsity) const |
| void | condense (BlockSparsityPattern &sparsity) const |
| void | condense (CompressedSparsityPattern &sparsity) const |
| void | condense (CompressedSetSparsityPattern &sparsity) const |
| void | condense (CompressedSimpleSparsityPattern &sparsity) const |
| void | condense (BlockCompressedSparsityPattern &sparsity) const |
| void | condense (BlockCompressedSetSparsityPattern &sparsity) const |
| void | condense (BlockCompressedSimpleSparsityPattern &sparsity) const |
| template<typename number > | |
| void | condense (const SparseMatrix< number > &uncondensed, SparseMatrix< number > &condensed) const |
| template<typename number > | |
| void | condense (SparseMatrix< number > &matrix) const |
| template<typename number > | |
| void | condense (BlockSparseMatrix< number > &matrix) const |
| template<class VectorType > | |
| void | condense (const VectorType &uncondensed, VectorType &condensed) const |
| template<class VectorType > | |
| void | condense (VectorType &vec) const |
| template<typename number , class VectorType > | |
| void | condense (const SparseMatrix< number > &uncondensed_matrix, const VectorType &uncondensed_vector, SparseMatrix< number > &condensed_matrix, VectorType &condensed_vector) const |
| template<typename number , class VectorType > | |
| void | condense (SparseMatrix< number > &matrix, VectorType &vector) const |
| template<typename number , class BlockVectorType > | |
| void | condense (BlockSparseMatrix< number > &matrix, BlockVectorType &vector) const |
| template<class VectorType > | |
| void | set_zero (VectorType &vec) const |
Eliminating constraints from linear systems during their creation | |
| template<class InVector , class OutVector > | |
| void | distribute_local_to_global (const InVector &local_vector, const std::vector< unsigned int > &local_dof_indices, OutVector &global_vector) const |
| template<typename VectorType > | |
| void | distribute_local_to_global (const Vector< double > &local_vector, const std::vector< unsigned int > &local_dof_indices, VectorType &global_vector, const FullMatrix< double > &local_matrix) const |
| template<typename ForwardIteratorVec , typename ForwardIteratorInd , class VectorType > | |
| void | distribute_local_to_global (ForwardIteratorVec local_vector_begin, ForwardIteratorVec local_vector_end, ForwardIteratorInd local_indices_begin, VectorType &global_vector) const |
| template<typename MatrixType > | |
| void | distribute_local_to_global (const FullMatrix< double > &local_matrix, const std::vector< unsigned int > &local_dof_indices, MatrixType &global_matrix) const |
| template<typename MatrixType > | |
| void | distribute_local_to_global (const FullMatrix< double > &local_matrix, const std::vector< unsigned int > &row_indices, const std::vector< unsigned int > &col_indices, MatrixType &global_matrix) const |
| template<typename MatrixType , typename VectorType > | |
| void | distribute_local_to_global (const FullMatrix< double > &local_matrix, const Vector< double > &local_vector, const std::vector< unsigned int > &local_dof_indices, MatrixType &global_matrix, VectorType &global_vector, bool use_inhomogeneities_for_rhs=false) const |
| template<typename SparsityType > | |
| void | add_entries_local_to_global (const std::vector< unsigned int > &local_dof_indices, SparsityType &sparsity_pattern, const bool keep_constrained_entries=true, const Table< 2, bool > &dof_mask=default_empty_table) const |
| template<typename SparsityType > | |
| void | add_entries_local_to_global (const std::vector< unsigned int > &row_indices, const std::vector< unsigned int > &col_indices, SparsityType &sparsity_pattern, const bool keep_constrained_entries=true, const Table< 2, bool > &dof_mask=default_empty_table) const |
| template<typename ForwardIteratorVec , typename ForwardIteratorInd , class VectorType > | |
| void | get_dof_values (const VectorType &global_vector, ForwardIteratorInd local_indices_begin, ForwardIteratorVec local_vector_begin, ForwardIteratorVec local_vector_end) const |
Dealing with constraints after solving a linear system | |
| template<class VectorType > | |
| void | distribute (const VectorType &condensed, VectorType &uncondensed) const |
| template<class VectorType > | |
| void | distribute (VectorType &vec) const |
Static Public Member Functions | |
| ::ExceptionBase & | ExcMatrixIsClosed () |
| ::ExceptionBase & | ExcMatrixNotClosed () |
| ::ExceptionBase & | ExcLineInexistant (unsigned int arg1) throw (errortext << "The specified line " << arg1 << " does not exist." ) |
| ::ExceptionBase & | ExcEntryAlreadyExists (int arg1, int arg2, double arg3, double arg4) throw (errortext << "The entry for the indices " << arg1 << " and " << arg2 << " already exists, but the values " << arg3 << " (old) and " << arg4 << " (new) differ " << "by " << (arg4-arg3) << "." ) |
| ::ExceptionBase & | ExcDoFConstrainedToConstrainedDoF (int arg1, int arg2) throw (errortext << "You tried to constrain DoF " << arg1 << " to DoF " << arg2 << ", but that one is also constrained. This is not allowed!" ) |
| ::ExceptionBase & | ExcDoFIsConstrainedFromBothObjects (int arg1) throw (errortext << "Degree of freedom " << arg1 << " is constrained from both object in a merge operation." ) |
| ::ExceptionBase & | ExcDoFIsConstrainedToConstrainedDoF (int arg1) throw (errortext << "In the given argument a degree of freedom is constrained " << "to another DoF with number " << arg1 << ", which however is constrained by this object. This is not" << " allowed." ) |
| ::ExceptionBase & | ExcRowNotStoredHere (int arg1) throw (errortext << "The index set given to this constraint matrix indicates " << "constraints for degree of freedom " << arg1 << " should not be stored by this object, but a constraint " << "is being added." ) |
Private Member Functions | |
| unsigned int | calculate_line_index (const unsigned int line) const |
| template<typename MatrixType , typename VectorType > | |
| void | distribute_local_to_global (const FullMatrix< double > &local_matrix, const Vector< double > &local_vector, const std::vector< unsigned int > &local_dof_indices, MatrixType &global_matrix, VectorType &global_vector, bool use_inhomogeneities_for_rhs, internal::bool2type< false >) const |
| template<typename MatrixType , typename VectorType > | |
| void | distribute_local_to_global (const FullMatrix< double > &local_matrix, const Vector< double > &local_vector, const std::vector< unsigned int > &local_dof_indices, MatrixType &global_matrix, VectorType &global_vector, bool use_inhomogeneities_for_rhs, internal::bool2type< true >) const |
| template<typename SparsityType > | |
| void | add_entries_local_to_global (const std::vector< unsigned int > &local_dof_indices, SparsityType &sparsity_pattern, const bool keep_constrained_entries, const Table< 2, bool > &dof_mask, internal::bool2type< false >) const |
| template<typename SparsityType > | |
| void | add_entries_local_to_global (const std::vector< unsigned int > &local_dof_indices, SparsityType &sparsity_pattern, const bool keep_constrained_entries, const Table< 2, bool > &dof_mask, internal::bool2type< true >) const |
| void | make_sorted_row_list (const std::vector< unsigned int > &local_dof_indices, internals::GlobalRowsFromLocal &global_rows) const |
| void | make_sorted_row_list (const std::vector< unsigned int > &local_dof_indices, std::vector< unsigned int > &active_dofs) const |
| double | resolve_vector_entry (const unsigned int i, const internals::GlobalRowsFromLocal &global_rows, const Vector< double > &local_vector, const std::vector< unsigned int > &local_dof_indices, const FullMatrix< double > &local_matrix) const |
Static Private Member Functions | |
| static bool | check_zero_weight (const std::pair< unsigned int, double > &p) |
Private Attributes | |
| std::vector< ConstraintLine > | lines |
| std::vector< unsigned int > | lines_cache |
| IndexSet | local_lines |
| bool | sorted |
Static Private Attributes | |
| static const Table< 2, bool > | default_empty_table |
This class implements dealing with linear (possibly inhomogeneous) constraints on degrees of freedom. The concept and origin of such constraints is extensively described in the Constraints on degrees of freedom module. The class is meant to deal with a limited number of constraints relative to the total number of degrees of freedom, for example a few per cent up to maybe 30 per cent; and with a linear combination of
other degrees of freedom where
is also relatively small (no larger than at most around the average number of entries per row of a linear system). It is not meant to describe full rank linear systems.
The algorithms used in the implementation of this class are described in some detail in the hp paper. There is also a significant amount of documentation on how to use this class in the Constraints on degrees of freedom module.
Each "line" in objects of this class corresponds to one constrained degree of freedom, with the number of the line being
, and the entries in this line being pairs
. Note that the constraints are linear in the
, and that there might be a constant (non-homogeneous) term in the constraint. This is exactly the form we need for hanging node constraints, where we need to constrain one degree of freedom in terms of others. There are other conditions of this form possible, for example for implementing mean value conditions as is done in the step-11 tutorial program. The name of the class stems from the fact that these constraints can be represented in matrix form as
, and this object then describes the matrix
(as well as, incidentally, the vector
-- originally, the ConstraintMatrix class was only meant to handle homogenous constraints where
, thus the name). The most frequent way to create/fill objects of this type is using the DoFTools::make_hanging_node_constraints() function. The use of these objects is first explained in step-6.
Objects of the present type are organized in lines (rows), but only those lines are stored where constraints are present. New constraints are added by adding new lines using the add_line() function, and then populating it using the add_entry() function to a given line, or add_entries() to add more than one entry at a time. The right hand side element, if nonzero, can be set using the set_inhomogeneity() function. After all constraints have been added, you need to call close(), which compresses the storage format and sorts the entries.
Definition at line 123 of file constraint_matrix.h.
An enum that describes what should happen if the two ConstraintMatrix objects involved in a call to the merge() function happen to have constraints on the same degrees of freedom.
Definition at line 134 of file constraint_matrix.h.
Constructor. The supplied IndexSet defines which indices might be constrained inside this ConstraintMatrix. In a calculation with a parallel::distributed::DoFHandler one should use locally_relevant_dofs. The IndexSet allows the ConstraintMatrix to safe memory. Otherwise internal data structures for all possible indices will be created.
Definition at line 1765 of file constraint_matrix.h.
| ConstraintMatrix::ConstraintMatrix | ( | const ConstraintMatrix & | constraint_matrix ) | [inline] |
Copy constructor
Definition at line 1775 of file constraint_matrix.h.
Reinit the ConstraintMatrix object and supply an IndexSet with lines that may be constrained. This function is only relevant in the distributed case to supply a different IndexSet. Otherwise this routine is equivalent to calling clear(). See the constructor for details.
Determines if we can store a constraint for the given line_index. This routine only matters in the distributed case and checks if the IndexSet allows storage of this line. Always returns true if not in the distributed case.
Definition at line 1962 of file constraint_matrix.h.
References IndexSet::is_element(), local_lines, and IndexSet::size().
| void ConstraintMatrix::add_selected_constraints | ( | const ConstraintMatrix & | constraints_in, |
| const IndexSet & | filter | ||
| ) |
This function copies the content of constraints_in with DoFs that are element of the IndexSet filter. Elements that are not present in the IndexSet are ignored. All DoFs will be transformed to local index space of the filter, both the constrained DoFs and the other DoFs these entries are constrained to. The local index space of the filter is a contiguous numbering of all (global) DoFs that are elements in the filter.
If, for example, the filter represents the range [10,20), and the constraint matrix constraints_in includes the global indices {7,13,14}, the indices {3,4} are added to the calling constraint matrix (since 13 and 14 are elements in the filter and element 13 is the fourth element in the index, and 14 is the fifth).
This function provides an easy way to create a ConstraintMatrix for certain vector components in a vector-valued problem from a full ConstraintMatrix, i.e. extracting a diagonal subblock from a larger ConstraintMatrix. The block is specified by the IndexSet argument.
| void ConstraintMatrix::add_line | ( | const unsigned int | line ) | [inline] |
Add a new line to the matrix. If the line already exists, then the function simply returns without doing anything.
Definition at line 1787 of file constraint_matrix.h.
References Assert, calculate_line_index(), StandardExceptions::ExcInternalError(), ExcMatrixIsClosed(), numbers::invalid_unsigned_int, is_constrained(), lines, lines_cache, Utilities::MPI::max(), and sorted.
| void ConstraintMatrix::add_lines | ( | const std::vector< bool > & | lines ) |
Call the first add_line() function for every index i for which lines[i] is true.
This function essentially exists to allow adding several constraints of the form
all at once, where the set of indices
for which these constraints should be added are given by the argument of this function. On the other hand, just as if the single-argument add_line() function were called repeatedly, the constraints can later be modified to include linear dependencies using the add_entry() function as well as inhomogeneities using set_inhomogeneity().
| void ConstraintMatrix::add_lines | ( | const std::set< unsigned int > & | lines ) |
Call the first add_line() function for every index i that appears in the argument.
This function essentially exists to allow adding several constraints of the form
all at once, where the set of indices
for which these constraints should be added are given by the argument of this function. On the other hand, just as if the single-argument add_line() function were called repeatedly, the constraints can later be modified to include linear dependencies using the add_entry() function as well as inhomogeneities using set_inhomogeneity().
| void ConstraintMatrix::add_lines | ( | const IndexSet & | lines ) |
Call the first add_line() function for every index i that appears in the argument.
This function essentially exists to allow adding several constraints of the form
all at once, where the set of indices
for which these constraints should be added are given by the argument of this function. On the other hand, just as if the single-argument add_line() function were called repeatedly, the constraints can later be modified to include linear dependencies using the add_entry() function as well as inhomogeneities using set_inhomogeneity().
| void ConstraintMatrix::add_entry | ( | const unsigned int | line, |
| const unsigned int | column, | ||
| const double | value | ||
| ) | [inline] |
Add an entry to a given line. The list of lines is searched 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.
If an entry with the same indices as the one this function call denotes 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.
Definition at line 1829 of file constraint_matrix.h.
References Assert, calculate_line_index(), ConstraintMatrix::ConstraintLine::entries, ExcEntryAlreadyExists(), StandardExceptions::ExcInternalError(), ExcMatrixIsClosed(), StandardExceptions::ExcMessage(), numbers::invalid_unsigned_int, ConstraintMatrix::ConstraintLine::line, lines, lines_cache, and sorted.
| void ConstraintMatrix::add_entries | ( | const unsigned int | line, |
| const std::vector< std::pair< unsigned int, double > > & | col_val_pairs | ||
| ) |
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 preceeding function several times, but is faster.
Set an imhomogeneity to the constraint line i, according to the discussion in the general class description. Note: the line needs to be added with one of the add_line() calls first.
Definition at line 1866 of file constraint_matrix.h.
References Assert, calculate_line_index(), StandardExceptions::ExcInternalError(), StandardExceptions::ExcMessage(), numbers::invalid_unsigned_int, lines, and lines_cache.
| void ConstraintMatrix::close | ( | ) |
Close the filling of entries. Since the lines of a matrix of this type are usually filled in an arbitrary order and since we do not want to use associative constainers to store the lines, we need to sort the lines and within the lines the columns before usage of the matrix. This is done through this function.
Also, zero entries are discarded, since they are not needed.
After closing, no more entries are accepted. If the object was already closed, then this function returns immediately.
This function also resolves chains of constraints. For example, degree of freedom 13 may be constrained to
while degree of freedom 7 is itself constrained as
. Then, the resolution will be that
. Note, however, that cycles in this graph of constraints are not allowed, i.e. for example
may not be constrained, directly or indirectly, to
again.
| void ConstraintMatrix::merge | ( | const ConstraintMatrix & | other_constraints, |
| const MergeConflictBehavior | merge_conflict_behavior = no_conflicts_allowed |
||
| ) |
Merge the constraints represented by the object given as argument into the constraints represented by this object. Both objects may or may not be closed (by having their function close called before). If this object was closed before, then it will be closed afterwards as well. Note, however, that if the other argument is closed, then merging may be significantly faster.
Using the default value of the second arguments, the constraints in each of the two objects (the old one represented by this object and the argument) may not refer to the same degree of freedom, i.e. a degree of freedom that is constrained in one object may not be constrained in the second. If this is nevertheless the case, an exception is thrown. However, this behavior can be changed by providing a different value for the second argument.
| void ConstraintMatrix::shift | ( | const unsigned int | offset ) |
Shift all entries of this matrix down offset rows and over offset columns.
This function is useful if you are building block matrices, where all blocks are built by the same DoFHandler object, i.e. the matrix size is larger than the number of degrees of freedom. Since several matrix rows and columns correspond to the same degrees of freedom, you'd generate several constraint objects, then shift them, and finally merge them together again.
| void ConstraintMatrix::clear | ( | ) |
Clear all entries of this matrix. Reset the flag determining whether new entries are accepted or not.
This function may be called also on objects which are empty or already cleared.
| unsigned int ConstraintMatrix::n_constraints | ( | ) | const |
Return number of constraints stored in this matrix.
Return whether the degree of freedom with number index is a constrained one.
Note that if close was called before, then this function is significantly faster, since then the constrained degrees of freedom are sorted and we can do a binary search, while before close was called, we have to perform a linear search through all entries.
Definition at line 1882 of file constraint_matrix.h.
References calculate_line_index(), numbers::invalid_unsigned_int, and lines_cache.
Referenced by add_line(), distribute_local_to_global(), and get_dof_values().
Return whether the dof is constrained, and whether it is constrained to only one other degree of freedom with weight one. The function therefore returns whether the degree of freedom would simply be eliminated in favor of exactly one other degree of freedom.
The function returns false if either the degree of freedom is not constrained at all, or if it is constrained to more than one other degree of freedom, or if it is constrained to only one degree of freedom but with a weight different from one.
| unsigned int ConstraintMatrix::max_constraint_indirections | ( | ) | const |
Return the maximum number of other dofs that one dof is constrained to. For example, in 2d a hanging node is constrained only to its two neighbors, so the returned value would be 2. However, for higher order elements and/or higher dimensions, or other types of constraints, this number is no more obvious.
The name indicates that within the system matrix, references to a constrained node are indirected to the nodes it is constrained to.
Returns true in case the dof is constrained and there is a non-trivial inhomogeneous valeus set to the dof.
Definition at line 1894 of file constraint_matrix.h.
References Assert, calculate_line_index(), StandardExceptions::ExcInternalError(), numbers::invalid_unsigned_int, lines, and lines_cache.
| bool ConstraintMatrix::has_inhomogeneities | ( | ) | const |
Returns false if all constraints in the ConstraintMatrix are homogeneous ones, and true if there is at least one inhomogeneity.
| const std::vector< std::pair< unsigned int, double > > * ConstraintMatrix::get_constraint_entries | ( | const unsigned int | line ) | const [inline] |
Returns a pointer to the the vector of entries if a line is constrained, and a zero pointer in case the dof is not constrained.
Definition at line 1914 of file constraint_matrix.h.
References calculate_line_index(), numbers::invalid_unsigned_int, lines, and lines_cache.
Returns the value of the inhomogeneity stored in the constrained dof line. Unconstrained dofs also return a zero value.
Definition at line 1931 of file constraint_matrix.h.
References calculate_line_index(), numbers::invalid_unsigned_int, lines, and lines_cache.
| void ConstraintMatrix::print | ( | std::ostream & | ) | const |
Print the constraint lines. Mainly for debugging purposes.
This function writes out all entries in the constraint matrix lines with their value in the form row col : value. Unconstrained lines containing only one identity entry are not stored in this object and are not printed.
| void ConstraintMatrix::write_dot | ( | std::ostream & | ) | const |
Write the graph of constraints in 'dot' format. 'dot' is a program that can take a list of nodes and produce a graphical representation of the graph of constrained degrees of freedom and the degrees of freedom they are constrained to.
The output of this function can be used as input to the 'dot' program that can convert the graph into a graphical representation in postscript, png, xfig, and a number of other formats.
This function exists mostly for debugging purposes.
| std::size_t ConstraintMatrix::memory_consumption | ( | ) | const |
Determine an estimate for the memory consumption (in bytes) of this object.
| void ConstraintMatrix::condense | ( | const SparsityPattern & | uncondensed, |
| SparsityPattern & | condensed | ||
| ) | const |
Condense a given sparsity pattern. This function assumes the uncondensed matrix struct to be compressed and the one to be filled to be empty. The condensed structure is compressed afterwards.
The constraint matrix object must be closed to call this function.
condensed. Therefore, the dimension of condensed is the dimension of uncondensed minus the number of constrained degrees of freedom. | void ConstraintMatrix::condense | ( | SparsityPattern & | sparsity ) | const |
This function does much the same as the above one, except that it condenses the matrix struct 'in-place'. It does not remove nonzero entries from the matrix but adds those needed for the process of distribution of the constrained degrees of freedom.
Since this function adds new nonzero entries to the sparsity pattern, the argument must not be compressed. However the constraint matrix must be closed. The matrix struct is compressed at the end of the function.
| void ConstraintMatrix::condense | ( | BlockSparsityPattern & | sparsity ) | const |
Same function as above, but condenses square block sparsity patterns.
| void ConstraintMatrix::condense | ( | CompressedSparsityPattern & | sparsity ) | const |
Same function as above, but condenses square compressed sparsity patterns.
Given the data structure used by CompressedSparsityPattern, this function becomes quadratic in the number of degrees of freedom for large problems and can dominate setting up linear systems when several hundred thousand or millions of unknowns are involved and for problems with many nonzero elements per row (for example for vector-valued problems or hp finite elements). In this case, it is advisable to use the CompressedSetSparsityPattern class instead, see for example step-27, or to use the CompressedSimpleSparsityPattern class, see for example step-31.
| void ConstraintMatrix::condense | ( | CompressedSetSparsityPattern & | sparsity ) | const |
Same function as above, but condenses compressed sparsity patterns, which are based on the std::set container.
| void ConstraintMatrix::condense | ( | CompressedSimpleSparsityPattern & | sparsity ) | const |
Same function as above, but condenses compressed sparsity patterns, which are based on the ''simple'' aproach.
| void ConstraintMatrix::condense | ( | BlockCompressedSparsityPattern & | sparsity ) | const |
Same function as above, but condenses square compressed sparsity patterns.
Given the data structure used by BlockCompressedSparsityPattern, this function becomes quadratic in the number of degrees of freedom for large problems and can dominate setting up linear systems when several hundred thousand or millions of unknowns are involved and for problems with many nonzero elements per row (for example for vector-valued problems or hp finite elements). In this case, it is advisable to use the BlockCompressedSetSparsityPattern class instead, see for example step-27 and step-31.
| void ConstraintMatrix::condense | ( | BlockCompressedSetSparsityPattern & | sparsity ) | const |
Same function as above, but condenses square compressed sparsity patterns.
| void ConstraintMatrix::condense | ( | BlockCompressedSimpleSparsityPattern & | sparsity ) | const |
Same function as above, but condenses square compressed sparsity patterns.
| void ConstraintMatrix::condense | ( | const SparseMatrix< number > & | uncondensed, |
| SparseMatrix< number > & | condensed | ||
| ) | const |
Condense a given matrix. The associated matrix struct should be condensed and compressed. It is the user's responsibility to guarantee that all entries in the condensed matrix be zero!
The constraint matrix object must be closed to call this function.
| void ConstraintMatrix::condense | ( | SparseMatrix< number > & | matrix ) | const |
This function does much the same as the above one, except that it condenses the matrix 'in-place'. See the general documentation of this class for more detailed information.
| void ConstraintMatrix::condense | ( | BlockSparseMatrix< number > & | matrix ) | const |
Same function as above, but condenses square block sparse matrices.
| void ConstraintMatrix::condense | ( | const VectorType & | uncondensed, |
| VectorType & | condensed | ||
| ) | const |
Condense the given vector uncondensed into condensed. It is the user's responsibility to guarantee that all entries of condensed be zero. Note that this function does not take any inhomogeneity into account and throws an exception in case there are any inhomogeneities. Use the function using both a matrix and vector for that case.
The VectorType may be a Vector<float>, Vector<double>, BlockVector<...>, a PETSc or Trilinos vector wrapper class, or any other type having the same interface.
| void ConstraintMatrix::condense | ( | VectorType & | vec ) | const |
Condense the given vector in-place. The VectorType may be a Vector<float>, Vector<double>, BlockVector<...>, a PETSc or Trilinos vector wrapper class, or any other type having the same interface. Note that this function does not take any inhomogeneity into account and throws an exception in case there are any inhomogeneities. Use the function using both a matrix and vector for that case.
| void ConstraintMatrix::condense | ( | const SparseMatrix< number > & | uncondensed_matrix, |
| const VectorType & | uncondensed_vector, | ||
| SparseMatrix< number > & | condensed_matrix, | ||
| VectorType & | condensed_vector | ||
| ) | const |
Condense a given matrix and a given vector. The associated matrix struct should be condensed and compressed. It is the user's responsibility to guarantee that all entries in the condensed matrix and vector be zero! This function is the appropriate choice for applying inhomogeneous constraints.
The constraint matrix object must be closed to call this function.
| void ConstraintMatrix::condense | ( | SparseMatrix< number > & | matrix, |
| VectorType & | vector | ||
| ) | const |
This function does much the same as the above one, except that it condenses matrix and vector 'in-place'. See the general documentation of this class for more detailed information.
| void ConstraintMatrix::condense | ( | BlockSparseMatrix< number > & | matrix, |
| BlockVectorType & | vector | ||
| ) | const |
Same function as above, but condenses square block sparse matrices and vectors.
| void ConstraintMatrix::set_zero | ( | VectorType & | vec ) | const |
Delete hanging nodes in a vector. Sets all hanging node values to zero. The VectorType may be a Vector<float>, Vector<double>, BlockVector<...>, a PETSc or Trilinos vector wrapper class, or any other type having the same interface.
| void ConstraintMatrix::distribute_local_to_global | ( | const InVector & | local_vector, |
| const std::vector< unsigned int > & | local_dof_indices, | ||
| OutVector & | global_vector | ||
| ) | const [inline] |
This function takes a vector of local contributions (local_vector) corresponding to the degrees of freedom indices given in local_dof_indices and distributes them to the global vector. In most cases, these local contributions will be the result of an integration over a cell or face of a cell. However, as long as local_vector and local_dof_indices have the same number of elements, this function is happy with whatever it is given.
In contrast to the similar function in the DoFAccessor class, this function also takes care of constraints, i.e. if one of the elements of local_dof_indices belongs to a constrained node, then rather than writing the corresponding element of local_vector into global_vector, the element is distributed to the entries in the global vector to which this particular degree of freedom is constrained.
Thus, by using this function to distribute local contributions to the global object, one saves the call to the condense function after the vectors and matrices are fully assembled. On the other hand, by consequence, the function does not only write into the entries enumerated by the local_dof_indices array, but also (possibly) others as necessary.
Note that this function will apply all constraints as if they were homogeneous. For correctly setting inhomogeneous constraints, use the similar function with a matrix argument or the function with both matrix and vector arguments.
Note: This function is not thread-safe, so you will need to make sure that only on process at a time calls this function.
Definition at line 1973 of file constraint_matrix.h.
References Assert, and StandardExceptions::ExcDimensionMismatch().
Referenced by distribute_local_to_global().
| void ConstraintMatrix::distribute_local_to_global | ( | const Vector< double > & | local_vector, |
| const std::vector< unsigned int > & | local_dof_indices, | ||
| VectorType & | global_vector, | ||
| const FullMatrix< double > & | local_matrix | ||
| ) | const |
This function takes a vector of local contributions (local_vector) corresponding to the degrees of freedom indices given in local_dof_indices and distributes them to the global vector. In most cases, these local contributions will be the result of an integration over a cell or face of a cell. However, as long as local_vector and local_dof_indices have the same number of elements, this function is happy with whatever it is given.
In contrast to the similar function in the DoFAccessor class, this function also takes care of constraints, i.e. if one of the elements of local_dof_indices belongs to a constrained node, then rather than writing the corresponding element of local_vector into global_vector, the element is distributed to the entries in the global vector to which this particular degree of freedom is constrained.
Thus, by using this function to distribute local contributions to the global object, one saves the call to the condense function after the vectors and matrices are fully assembled. On the other hand, by consequence, the function does not only write into the entries enumerated by the local_dof_indices array, but also (possibly) others as necessary. This includes writing into diagonal elements of the matrix if the corresponding degree of freedom is constrained.
The fourth argument local_matrix is intended to be used in case one wants to apply inhomogeneous constraints on the vector only. Such a situation could be where one wants to assemble of a right hand side vector on a problem with inhomogeneous constraints, but the global matrix has been assembled previously. A typical example of this is a time stepping algorithm where the stiffness matrix is assembled once, and the right hand side updated every time step. Note that, however, the entries in the columns of the local matrix have to be exactly the same as those that have been written into the global matrix. Otherwise, this function will not be able to correctly handle inhomogeneities.
Note: This function is not thread-safe, so you will need to make sure that only on process at a time calls this function.
| void ConstraintMatrix::distribute_local_to_global | ( | ForwardIteratorVec | local_vector_begin, |
| ForwardIteratorVec | local_vector_end, | ||
| ForwardIteratorInd | local_indices_begin, | ||
| VectorType & | global_vector | ||
| ) | const [inline] |
This function takes a pointer to a vector of local contributions (local_vector) corresponding to the degrees of freedom indices given in local_dof_indices and distributes them to the global vector. In most cases, these local contributions will be the result of an integration over a cell or face of a cell. However, as long as the entries in local_dof_indices indicate reasonable global vector entries, this function is happy with whatever it is given.
If one of the elements of local_dof_indices belongs to a constrained node, then rather than writing the corresponding element of local_vector into global_vector, the element is distributed to the entries in the global vector to which this particular degree of freedom is constrained.
Thus, by using this function to distribute local contributions to the global object, one saves the call to the condense function after the vectors and matrices are fully assembled. Note that this function completely ignores inhomogeneous constraints.
Note: This function is not thread-safe, so you will need to make sure that only on process at a time calls this function.
Definition at line 1989 of file constraint_matrix.h.
References Assert, calculate_line_index(), ConstraintMatrix::ConstraintLine::entries, ExcMatrixNotClosed(), is_constrained(), lines, lines_cache, and sorted.
| void ConstraintMatrix::distribute_local_to_global | ( | const FullMatrix< double > & | local_matrix, |
| const std::vector< unsigned int > & | local_dof_indices, | ||
| MatrixType & | global_matrix | ||
| ) | const [inline] |
This function takes a matrix of local contributions (local_matrix) corresponding to the degrees of freedom indices given in local_dof_indices and distributes them to the global matrix. In most cases, these local contributions will be the result of an integration over a cell or face of a cell. However, as long as local_matrix and local_dof_indices have the same number of elements, this function is happy with whatever it is given.
In contrast to the similar function in the DoFAccessor class, this function also takes care of constraints, i.e. if one of the elements of local_dof_indices belongs to a constrained node, then rather than writing the corresponding element of local_matrix into global_matrix, the element is distributed to the entries in the global matrix to which this particular degree of freedom is constrained.
With this scheme, we never write into rows or columns of constrained degrees of freedom. In order to make sure that the resulting matrix can still be inverted, we need to do something with the diagonal elements corresponding to constrained nodes. Thus, if a degree of freedom in local_dof_indices is constrained, we distribute the corresponding entries in the matrix, but also add the absolute value of the diagonal entry of the local matrix to the corresponding entry in the global matrix. Since the exact value of the diagonal element is not important (the value of the respective degree of freedom will be overwritten by the distribute() call later on anyway), this guarantees that the diagonal entry is always non-zero, positive, and of the same order of magnitude as the other entries of the matrix.
Thus, by using this function to distribute local contributions to the global object, one saves the call to the condense function after the vectors and matrices are fully assembled.
Note: This function is not thread-safe, so you will need to make sure that only on process at a time calls this function.
Definition at line 2046 of file constraint_matrix.h.
References distribute_local_to_global().
| void ConstraintMatrix::distribute_local_to_global | ( | const FullMatrix< double > & | local_matrix, |
| const std::vector< unsigned int > & | row_indices, | ||
| const std::vector< unsigned int > & | col_indices, | ||
| MatrixType & | global_matrix | ||
| ) | const |
Does the same as the function above but can treat non quadratic matrices.
| void ConstraintMatrix::distribute_local_to_global | ( | const FullMatrix< double > & | local_matrix, |
| const Vector< double > & | local_vector, | ||
| const std::vector< unsigned int > & | local_dof_indices, | ||
| MatrixType & | global_matrix, | ||
| VectorType & | global_vector, | ||
| bool | use_inhomogeneities_for_rhs = false |
||
| ) | const [inline] |
This function simultaneously writes elements into matrix and vector, according to the constraints specified by the calling ConstraintMatrix. This function can correctly handle inhomogeneous constraints as well. For the parameter use_inhomogeneities_for_rhs see the documentation in Constraints on degrees of freedom module.
Note: This function is not thread-safe, so you will need to make sure that only on process at a time calls this function.
Definition at line 2065 of file constraint_matrix.h.
References distribute_local_to_global().
| void ConstraintMatrix::add_entries_local_to_global | ( | const std::vector< unsigned int > & | local_dof_indices, |
| SparsityType & | sparsity_pattern, | ||
| const bool | keep_constrained_entries = true, |
||
| const Table< 2, bool > & | dof_mask = default_empty_table |
||
| ) | const [inline] |
Do a similar operation as the distribute_local_to_global() function that distributes writing entries into a matrix for constrained degrees of freedom, except that here we don't write into a matrix but only allocate sparsity pattern entries.
As explained in the hp paper and in step-27, first allocating a sparsity pattern and later coming back and allocating additional entries for those matrix entries that will be written to due to the elimination of constrained degrees of freedom (using ConstraintMatrix::condense() ), can be a very expensive procedure. It is cheaper to allocate these entries right away without having to do a second pass over the sparsity pattern object. This function does exactly that.
Because the function only allocates entries in a sparsity pattern, all it needs to know are the degrees of freedom that couple to each other. Unlike the previous function, no actual values are written, so the second input argument is not necessary here.
The third argument to this function, keep_constrained_entries determines whether the function shall allocate entries in the sparsity pattern at all for entries that will later be set to zero upon condensation of the matrix. These entries are necessary if the matrix is built unconstrained, and only later condensed. They are not necessary if the matrix is built using the distribute_local_to_global() function of this class which distributes entries right away when copying a local matrix into a global object. The default of this argument is true, meaning to allocate the few entries that may later be set to zero.
By default, the function adds entries for all pairs of indices given in the first argument to the sparsity pattern (unless keep_constrained_entries is false). However, sometimes one would like to only add a subset of all of these pairs. In that case, the last argument can be used which specifies a boolean mask which of the pairs of indices should be considered. If the mask is false for a pair of indices, then no entry will be added to the sparsity pattern for this pair, irrespective of whether one or both of the indices correspond to constrained degrees of freedom.
This function is not typically called from user code, but is used in the DoFTools::make_sparsity_pattern() function when passed a constraint matrix object.
Definition at line 2087 of file constraint_matrix.h.
| void ConstraintMatrix::add_entries_local_to_global | ( | const std::vector< unsigned int > & | row_indices, |
| const std::vector< unsigned int > & | col_indices, | ||
| SparsityType & | sparsity_pattern, | ||
| const bool | keep_constrained_entries = true, |
||
| const Table< 2, bool > & | dof_mask = default_empty_table |
||
| ) | const |
Similar to the other function, but for non-quadratic sparsity patterns.
| void ConstraintMatrix::get_dof_values | ( | const VectorType & | global_vector, |
| ForwardIteratorInd | local_indices_begin, | ||
| ForwardIteratorVec | local_vector_begin, | ||
| ForwardIteratorVec | local_vector_end | ||
| ) | const [inline] |
This function imports values from a global vector (global_vector) by applying the constraints to a vector of local values, expressed in iterator format. In most cases, the local values will be identified by the local dof values on a cell. However, as long as the entries in local_dof_indices indicate reasonable global vector entries, this function is happy with whatever it is given.
If one of the elements of local_dof_indices belongs to a constrained node, then rather than writing the corresponding element of global_vector into local_vector, the constraints are resolved as the respective distribute function does, i.e., the local entry is constructed from the global entries to which this particular degree of freedom is constrained.
In contrast to the similar function get_dof_values in the DoFAccessor class, this function does not need the constrained values to be correctly set (i.e., distribute to be called).
Definition at line 2016 of file constraint_matrix.h.
References Assert, calculate_line_index(), ConstraintMatrix::ConstraintLine::entries, ExcMatrixNotClosed(), ConstraintMatrix::ConstraintLine::inhomogeneity, is_constrained(), lines, lines_cache, and sorted.
| void ConstraintMatrix::distribute | ( | const VectorType & | condensed, |
| VectorType & | uncondensed | ||
| ) | const |
Re-distribute the elements of the vector condensed to uncondensed. It is the user's responsibility to guarantee that all entries of uncondensed be zero!
This function undoes the action of condense somehow, but it should be noted that it is not the inverse of condense.
The VectorType may be a Vector<float>, Vector<double>, BlockVector<...>, a PETSc or Trilinos vector wrapper class, or any other type having the same interface.
| void ConstraintMatrix::distribute | ( | VectorType & | vec ) | const |
Re-distribute the elements of the vector in-place. The VectorType may be a Vector<float>, Vector<double>, BlockVector<...>, a PETSc or Trilinos vector wrapper class, or any other type having the same interface.
Note that if called with a TrilinosWrappers::MPI::Vector it may not contain ghost elements.
| unsigned int ConstraintMatrix::calculate_line_index | ( | const unsigned int | line ) | const [inline, private] |
Internal function to calculate the index of line line in the vector lines_cache using local_lines.
Definition at line 1947 of file constraint_matrix.h.
References Assert, ExcRowNotStoredHere(), IndexSet::index_within_set(), IndexSet::is_element(), local_lines, and IndexSet::size().
Referenced by add_entry(), add_line(), distribute_local_to_global(), get_constraint_entries(), get_dof_values(), get_inhomogeneity(), is_constrained(), is_inhomogeneously_constrained(), and set_inhomogeneity().
| static bool ConstraintMatrix::check_zero_weight | ( | const std::pair< unsigned int, double > & | p ) | [static, private] |
Return true if the weight of an entry (the second element of the pair) equals zero. This function is used to delete entries with zero weight.
| void ConstraintMatrix::distribute_local_to_global | ( | const FullMatrix< double > & | local_matrix, |
| const Vector< double > & | local_vector, | ||
| const std::vector< unsigned int > & | local_dof_indices, | ||
| MatrixType & | global_matrix, | ||
| VectorType & | global_vector, | ||
| bool | use_inhomogeneities_for_rhs, | ||
| internal::bool2type< false > | |||
| ) | const [private] |
This function actually implements the local_to_global function for standard (non-block) matrices.
| void ConstraintMatrix::distribute_local_to_global | ( | const FullMatrix< double > & | local_matrix, |
| const Vector< double > & | local_vector, | ||
| const std::vector< unsigned int > & | local_dof_indices, | ||
| MatrixType & | global_matrix, | ||
| VectorType & | global_vector, | ||
| bool | use_inhomogeneities_for_rhs, | ||
| internal::bool2type< true > | |||
| ) | const [private] |
This function actually implements the local_to_global function for block matrices.
| void ConstraintMatrix::add_entries_local_to_global | ( | const std::vector< unsigned int > & | local_dof_indices, |
| SparsityType & | sparsity_pattern, | ||
| const bool | keep_constrained_entries, | ||
| const Table< 2, bool > & | dof_mask, | ||
| internal::bool2type< false > | |||
| ) | const [private] |
This function actually implements the local_to_global function for standard (non-block) sparsity types.
| void ConstraintMatrix::add_entries_local_to_global | ( | const std::vector< unsigned int > & | local_dof_indices, |
| SparsityType & | sparsity_pattern, | ||
| const bool | keep_constrained_entries, | ||
| const Table< 2, bool > & | dof_mask, | ||
| internal::bool2type< true > | |||
| ) | const [private] |
This function actually implements the local_to_global function for block sparsity types.
| void ConstraintMatrix::make_sorted_row_list | ( | const std::vector< unsigned int > & | local_dof_indices, |
| internals::GlobalRowsFromLocal & | global_rows | ||
| ) | const [private] |
Internal helper function for distribute_local_to_global function.
Creates a list of affected global rows for distribution, including the local rows where the entries come from. The list is sorted according to the global row indices.
| void ConstraintMatrix::make_sorted_row_list | ( | const std::vector< unsigned int > & | local_dof_indices, |
| std::vector< unsigned int > & | active_dofs | ||
| ) | const [private] |
Internal helper function for add_entries_local_to_global function.
Creates a list of affected rows for distribution without any additional information, otherwise similar to the other make_sorted_row_list function.
| double ConstraintMatrix::resolve_vector_entry | ( | const unsigned int | i, |
| const internals::GlobalRowsFromLocal & | global_rows, | ||
| const Vector< double > & | local_vector, | ||
| const std::vector< unsigned int > & | local_dof_indices, | ||
| const FullMatrix< double > & | local_matrix | ||
| ) | const [private] |
Internal helper function for distribute_local_to_global function.
std::vector<ConstraintLine> ConstraintMatrix::lines [private] |
Store the lines of the matrix. Entries are usually appended in an arbitrary order and insertion into a vector is done best at the end, so the order is unspecified after all entries are inserted. Sorting of the entries takes place when calling the close() function.
We could, instead of using a vector, use an associative array, like a map to store the lines. This, however, would mean a much more fractioned heap since it allocates many small objects, and would additionally make usage of this matrix much slower.
Definition at line 1564 of file constraint_matrix.h.
Referenced by add_entry(), add_line(), distribute_local_to_global(), get_constraint_entries(), get_dof_values(), get_inhomogeneity(), is_inhomogeneously_constrained(), and set_inhomogeneity().
std::vector<unsigned int> ConstraintMatrix::lines_cache [private] |
A list of unsigned integers that contains the position of the ConstraintLine of a constrained degree of freedom, or numbers::invalid_unsigned_int if the degree of freedom is not constrained. The invalid_unsigned int return value returns thus whether there is a constraint line for a given degree of freedom index. Note that this class has no notion of how many degrees of freedom there really are, so if we check whether there is a constraint line for a given degree of freedom, then this vector may actually be shorter than the index of the DoF we check for.
This field exists since when adding a new constraint line we have to figure out whether it already exists. Previously, we would simply walk the unsorted list of constraint lines until we either hit the end or found it. This algorithm is O(N) if N is the number of constraints, which makes it O(N^2) when inserting all constraints. For large problems with many constraints, this could easily take 5-10 per cent of the total run time. With this field, we can save this time since we find any constraint in O(1) time or get to know that it a certain degree of freedom is not constrained.
To make things worse, traversing the list of existing constraints requires reads from many different places in memory. Thus, in large 3d applications, the add_line() function showed up very prominently in the overall compute time, mainly because it generated a lot of cache misses. This should also be fixed by using the O(1) algorithm to access the fields of this array.
The field is useful in a number of other contexts as well, e.g. when one needs random access to the constraints as in all the functions that apply constraints on the fly while add cell contributions into vectors and matrices.
Definition at line 1623 of file constraint_matrix.h.
Referenced by add_entry(), add_line(), distribute_local_to_global(), get_constraint_entries(), get_dof_values(), get_inhomogeneity(), is_constrained(), is_inhomogeneously_constrained(), and set_inhomogeneity().
IndexSet ConstraintMatrix::local_lines [private] |
This IndexSet is used to limit the lines to save in the ContraintMatrix to a subset. This is necessary, because the lines_cache vector would become too big in a distributed calculation.
Definition at line 1633 of file constraint_matrix.h.
Referenced by calculate_line_index(), and can_store_line().
bool ConstraintMatrix::sorted [private] |
Store whether the arrays are sorted. If so, no new entries can be added.
Definition at line 1639 of file constraint_matrix.h.
Referenced by add_entry(), add_line(), distribute_local_to_global(), and get_dof_values().
const Table<2,bool> ConstraintMatrix::default_empty_table [static, private] |
Dummy table that serves as default argument for function add_entries_local_to_global().
Definition at line 1662 of file constraint_matrix.h.
documentation generated on Fri Feb 3 2012 06:04:06 by
doxygen
1.7.2