So far doxygen did not process this file since
`HAVE_SUITESPARSE_CHOLMOD` was missing.
This also adds the missing editor hints.

CHOLMOD supports this, it just wasn't exposed in the interface.
It is needed for large problems.

Using `std::uint_least32_t` instead of `std::size_t` halves the required memory
and thus also improves performance.
Notice that `std::uint32_t` is optional and `std::uint_fast32_t` is intended to be
fast in terms of computations and may have 64 bits. Here we're interested in reducing
memory and thus bandwith. Hence `std::uint_least32_t`, which is the smallest sufficient
type is most appropriate.

This replaces the `std::set` used to store the column indices for each
rows by a `std::vector` based implementation. The `std::vector` is
kept sorted when inserting such that we can avoid duplicates. This
can improve assembly time of matrices significantly (if `MatrixIndexSet` is used).

In the worst case (insertion in reverse) this may lead to O(n^2) complexity
when inserting n entries in a row compared to O(n log(n)) for `std::set`.
However, the sorted `std::vector` implementation still wins for relatively
large n. To avoid the worst case complexity when using very dense rows,
the implementation is switched to `std::set` if the size exceeds the threshold
value `maxVectorSize`. The default `maxVectorSize=2048` was selected based
on benchmark results.

The CMAKE_GUARD for multiple guarding variables requires a
porper boolean statement.

Robert K authored 2 years ago and Andreas Dedner committed 2 years ago

use using and SizeType to size_type to adhere to istl conventions

Notice that this also fixes an incorrect `MultiTypeBlockMatrix::field_type`
in a special setting: If you have a nested matrix
`MultiTypeBlockMatrix< MultiTypeBlockVector<MultiTypeBlockMatrix<...>>>`,
the outer `MultiTypeBlockMatrix::field_type` forwards to the `MultiTypeBlockVector::field_type`
which forwards to the inner `FieldTraits<MultiTypeBlockMatrix>::field_type`.

And fix all spelling errors that codespell currently finds.

... because we also specialize `std::tuple_element` and
it derives from `std::tuple` after all.

Corner case that sometimes happens and produced a segmentation fault.

Unused variable warning indicated this oversight

See https://reuse.software/ for a description.

Nested sparse matrices were not allowed to have empty rows/cols. By choosing the minimum offset of other blocks, we get an educated guess for these cases.

Before this commit, the pattern was deallocated with the wrong size that created a huge memory leak.

The current behavior (allocating each row separately ) is rather
surprising and unnecessary as the matrix market file stores the
number of nonzeros anyway. Hence we now pass this number to
BCRSMatrix::SetSize to get the most efficient behavior