sparsity_pattern.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 2000 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_sparsity_pattern_h
#define dealii_sparsity_pattern_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/array_view.h>
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/linear_index_iterator.h>
 
#include <deal.II/lac/sparsity_pattern_base.h>
 
// boost::serialization::make_array used to be in array.hpp, but was
// moved to a different file in BOOST 1.64
#include <boost/version.hpp>
#if BOOST_VERSION >= 106400
#  include <boost/serialization/array_wrapper.hpp>
#else
#  include <boost/serialization/array.hpp>
#endif
#include <boost/serialization/split_member.hpp>
 
#include <algorithm>
#include <iostream>
#include <memory>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
class SparsityPattern;
class DynamicSparsityPattern;
class ChunkSparsityPattern;
template <typename number>
class FullMatrix;
template <typename number>
class SparseMatrix;
template <typename number>
class SparseLUDecomposition;
template <typename number>
class SparseILU;
 
namespace ChunkSparsityPatternIterators
{
  class Accessor;
}
#endif
 
namespace internals
{
  namespace SparsityPatternTools
  {
    using size_type = types::global_dof_index;
 
    size_type
    get_column_index_from_iterator(const size_type i);
 
    template <typename value>
    size_type
    get_column_index_from_iterator(const std::pair<size_type, value> &i);
 
    template <typename value>
    size_type
    get_column_index_from_iterator(const std::pair<const size_type, value> &i);
 
  } // namespace SparsityPatternTools
} // namespace internals
 
 
namespace SparsityPatternIterators
{
  // forward declaration
  class Iterator;
 
  using size_type = types::global_dof_index;
 
  class Accessor
  {
  public:
    using size_type = SparsityPatternIterators::size_type;
 
    Accessor(const SparsityPattern *matrix, const std::size_t linear_index);
 
    Accessor(const SparsityPattern *matrix);
 
    Accessor();
 
    size_type
    row() const;
 
    size_type
    index() const;
 
    size_type
    global_index() const;
 
    size_type
    column() const;
 
    bool
    is_valid_entry() const;
 
    bool
    operator==(const Accessor &) const;
 
    bool
    operator<(const Accessor &) const;
 
  protected:
    DeclExceptionMsg(DummyAccessor,
                     "The instance of this class was initialized"
                     " without SparsityPattern object, which"
                     " means that it is a dummy accessor that can"
                     " not do any operations.");
 
    const SparsityPattern *container;
 
    std::size_t linear_index;
 
    void
    advance();
 
    // Grant access to iterator class.
    friend class LinearIndexIterator<Iterator, Accessor>;
 
    // Grant access to accessor class of ChunkSparsityPattern.
    friend class ChunkSparsityPatternIterators::Accessor;
  };
 
 
 
  class Iterator : public LinearIndexIterator<Iterator, Accessor>
  {
  public:
    using size_type = types::global_dof_index;
 
    using container_pointer_type = SparsityPattern *;
 
    Iterator(const SparsityPattern *sp, const std::size_t linear_index);
 
    Iterator(const Accessor &accessor);
  };
} // namespace SparsityPatternIterators
 
class SparsityPattern : public SparsityPatternBase
{
public:
  using size_type = types::global_dof_index;
 
  static constexpr size_type invalid_entry = numbers::invalid_size_type;
 
  using const_iterator = SparsityPatternIterators::Iterator;
 
  using iterator = SparsityPatternIterators::Iterator;
 
  iterator
  begin() const;
 
  iterator
  end() const;
 
  iterator
  begin(const size_type r) const;
 
  iterator
  end(const size_type r) const;
 
  SparsityPattern();
 
  SparsityPattern(const SparsityPattern &);
 
  SparsityPattern(const size_type    m,
                  const size_type    n,
                  const unsigned int max_per_row);
 
 
  SparsityPattern(const size_type                  m,
                  const size_type                  n,
                  const std::vector<unsigned int> &row_lengths);
 
  SparsityPattern(const size_type m, const unsigned int max_per_row);
 
  SparsityPattern(const size_type                  m,
                  const std::vector<unsigned int> &row_lengths);
 
  SparsityPattern(const SparsityPattern &original,
                  const unsigned int     max_per_row,
                  const size_type        extra_off_diagonals);
 
  SparsityPattern &
  operator=(const SparsityPattern &);
 
  void
  reinit(const size_type                      m,
         const size_type                      n,
         const ArrayView<const unsigned int> &row_lengths);
 
  void
  reinit(const size_type                  m,
         const size_type                  n,
         const std::vector<unsigned int> &row_lengths);
 
  void
  reinit(const size_type m, const size_type n, const unsigned int max_per_row);
 
  void
  compress();
 
 
  template <typename ForwardIterator>
  void
  copy_from(const size_type       n_rows,
            const size_type       n_cols,
            const ForwardIterator begin,
            const ForwardIterator end);
 
  void
  copy_from(const DynamicSparsityPattern &dsp);
 
  void
  copy_from(const SparsityPattern &sp);
 
  template <typename number>
  void
  copy_from(const FullMatrix<number> &matrix);
 
  void
  add(const size_type i, const size_type j);
 
  template <typename ForwardIterator>
  void
  add_entries(const size_type row,
              ForwardIterator begin,
              ForwardIterator end,
              const bool      indices_are_sorted = false);
 
  virtual void
  add_row_entries(const size_type                  &row,
                  const ArrayView<const size_type> &columns,
                  const bool indices_are_sorted = false) override;
 
  using SparsityPatternBase::add_entries;
 
  void
  symmetrize();
 
  std::size_t
  n_nonzero_elements() const;
 
  bool
  empty() const;
 
  size_type
  bandwidth() const;
 
  bool
  is_compressed() const;
 
  size_type
  max_entries_per_row() const;
 
  bool
  operator==(const SparsityPattern &) const;
 
  bool
  stores_only_added_elements() const;
 
  unsigned int
  row_length(const size_type row) const;
 
  std::size_t
  memory_consumption() const;
 
  size_type
  operator()(const size_type i, const size_type j) const;
 
  bool
  exists(const size_type i, const size_type j) const;
 
  size_type
  column_number(const size_type row, const unsigned int index) const;
 
  std::pair<size_type, size_type>
  matrix_position(const std::size_t global_index) const;
 
  size_type
  row_position(const size_type i, const size_type j) const;
 
  void
  print(std::ostream &out) const;
 
  void
  print_gnuplot(std::ostream &out) const;
 
  void
  print_svg(std::ostream &out) const;
 
  void
  block_write(std::ostream &out) const;
 
  void
  block_read(std::istream &in);
 
  template <class Archive>
  void
  save(Archive &ar, const unsigned int version) const;
 
  template <class Archive>
  void
  load(Archive &ar, const unsigned int version);
 
#ifdef DOXYGEN
  template <class Archive>
  void
  serialize(Archive &archive, const unsigned int version);
#else
  // This macro defines the serialize() method that is compatible with
  // the templated save() and load() method that have been implemented.
  BOOST_SERIALIZATION_SPLIT_MEMBER()
#endif
 
  DeclException2(ExcIteratorRange,
                 int,
                 int,
                 << "The iterators denote a range of " << arg1
                 << " elements, but the given number of rows was " << arg2);
  DeclException1(ExcInvalidNumberOfPartitions,
                 int,
                 << "The number of partitions you gave is " << arg1
                 << ", but must be greater than zero.");
 
  DeclException2(ExcNotEnoughSpace,
                 int,
                 int,
                 << "Upon entering a new entry to row " << arg1
                 << ": there was no free entry any more. " << std::endl
                 << "(Maximum number of entries for this row: " << arg2
                 << "; maybe the matrix is already compressed?)");
 
  DeclExceptionMsg(
    ExcMatrixIsCompressed,
    "The operation you attempted changes the structure of the SparsityPattern "
    "and is not possible after compress() has been called.");
 
  DeclExceptionMsg(
    ExcNotCompressed,
    "The operation you attempted is only allowed after the SparsityPattern "
    "has been set up and compress() was called.");
 
private:
  bool store_diagonal_first_in_row;
 
  size_type max_dim;
 
  std::size_t max_vec_len;
 
  unsigned int max_row_length;
 
  std::unique_ptr<std::size_t[]> rowstart;
 
  std::unique_ptr<size_type[]> colnums;
 
  bool compressed;
 
  // Make all sparse matrices friends of this class.
  template <typename number>
  friend class SparseMatrix;
  template <typename number>
  friend class SparseLUDecomposition;
  template <typename number>
  friend class SparseILU;
  template <typename number>
  friend class ChunkSparseMatrix;
 
  friend class ChunkSparsityPattern;
  friend class DynamicSparsityPattern;
 
  // Also give access to internal details to the iterator/accessor classes.
  friend class SparsityPatternIterators::Iterator;
  friend class SparsityPatternIterators::Accessor;
  friend class ChunkSparsityPatternIterators::Accessor;
};
 
 
/*---------------------- Inline functions -----------------------------------*/
 
#ifndef DOXYGEN
 
 
namespace SparsityPatternIterators
{
  inline Accessor::Accessor(const SparsityPattern *sparsity_pattern,
                            const std::size_t      i)
    : container(sparsity_pattern)
    , linear_index(i)
  {}
 
 
 
  inline Accessor::Accessor(const SparsityPattern *sparsity_pattern)
    : container(sparsity_pattern)
    , linear_index(container->rowstart[container->rows])
  {}
 
 
 
  inline Accessor::Accessor()
    : container(nullptr)
    , linear_index(numbers::invalid_size_type)
  {}
 
 
 
  inline bool
  Accessor::is_valid_entry() const
  {
    Assert(container != nullptr, DummyAccessor());
    return (linear_index < container->rowstart[container->rows] &&
            container->colnums[linear_index] != SparsityPattern::invalid_entry);
  }
 
 
 
  inline size_type
  Accessor::row() const
  {
    Assert(is_valid_entry() == true, ExcInvalidIterator());
 
    const std::size_t *insert_point =
      std::upper_bound(container->rowstart.get(),
                       container->rowstart.get() + container->rows + 1,
                       linear_index);
    return insert_point - container->rowstart.get() - 1;
  }
 
 
 
  inline size_type
  Accessor::column() const
  {
    Assert(is_valid_entry() == true, ExcInvalidIterator());
 
    return (container->colnums[linear_index]);
  }
 
 
 
  inline size_type
  Accessor::index() const
  {
    Assert(is_valid_entry() == true, ExcInvalidIterator());
 
    return linear_index - container->rowstart[row()];
  }
 
 
 
  inline size_type
  Accessor::global_index() const
  {
    Assert(is_valid_entry() == true, ExcInvalidIterator());
 
    return linear_index;
  }
 
 
 
  inline bool
  Accessor::operator==(const Accessor &other) const
  {
    return (container == other.container && linear_index == other.linear_index);
  }
 
 
 
  inline bool
  Accessor::operator<(const Accessor &other) const
  {
    Assert(container != nullptr, DummyAccessor());
    Assert(other.container != nullptr, DummyAccessor());
    Assert(container == other.container, ExcInternalError());
 
    return linear_index < other.linear_index;
  }
 
 
 
  inline void
  Accessor::advance()
  {
    Assert(container != nullptr, DummyAccessor());
    Assert(linear_index < container->rowstart[container->rows],
           ExcIteratorPastEnd());
    ++linear_index;
  }
 
 
  inline Iterator::Iterator(const SparsityPattern *sp,
                            const std::size_t      linear_index)
    : LinearIndexIterator<Iterator, Accessor>(Accessor(sp, linear_index))
  {}
 
 
  inline Iterator::Iterator(const Accessor &accessor)
    : LinearIndexIterator<Iterator, Accessor>(accessor)
  {}
 
 
} // namespace SparsityPatternIterators
 
 
 
inline std::size_t
SparsityPattern::n_nonzero_elements() const
{
  Assert(compressed, ExcNotCompressed());
 
  if ((rowstart != nullptr) && (colnums != nullptr))
    return rowstart[rows] - rowstart[0];
  else
    // the object is empty or has zero size
    return 0;
}
 
 
 
inline bool
SparsityPattern::is_compressed() const
{
  return compressed;
}
 
 
 
inline bool
SparsityPattern::stores_only_added_elements() const
{
  return (store_diagonal_first_in_row == false);
}
 
 
 
inline unsigned int
SparsityPattern::row_length(const size_type row) const
{
  AssertIndexRange(row, rows);
  return rowstart[row + 1] - rowstart[row];
}
 
 
 
inline SparsityPattern::size_type
SparsityPattern::column_number(const size_type    row,
                               const unsigned int index) const
{
  AssertIndexRange(row, rows);
  AssertIndexRange(index, row_length(row));
 
  return colnums[rowstart[row] + index];
}
 
 
 
inline SparsityPattern::iterator
SparsityPattern::begin() const
{
  if (n_rows() > 0)
    return {this, rowstart[0]};
  else
    return end();
}
 
 
 
inline SparsityPattern::iterator
SparsityPattern::end() const
{
  if (n_rows() > 0)
    return {this, rowstart[rows]};
  else
    return {nullptr, 0};
}
 
 
 
inline SparsityPattern::iterator
SparsityPattern::begin(const size_type r) const
{
  AssertIndexRange(r, n_rows());
 
  return {this, rowstart[r]};
}
 
 
 
inline SparsityPattern::iterator
SparsityPattern::end(const size_type r) const
{
  AssertIndexRange(r, n_rows());
 
  return {this, rowstart[r + 1]};
}
 
 
 
namespace internal
{
  namespace SparsityPatternTools
  {
    using size_type = types::global_dof_index;
 
    inline size_type
    get_column_index_from_iterator(const size_type i)
    {
      return i;
    }
 
 
 
    template <typename value>
    inline size_type
    get_column_index_from_iterator(const std::pair<size_type, value> &i)
    {
      return i.first;
    }
 
 
 
    template <typename value>
    inline size_type
    get_column_index_from_iterator(const std::pair<const size_type, value> &i)
    {
      return i.first;
    }
  } // namespace SparsityPatternTools
} // namespace internal
 
 
 
template <typename ForwardIterator>
void
SparsityPattern::copy_from(const size_type       n_rows,
                           const size_type       n_cols,
                           const ForwardIterator begin,
                           const ForwardIterator end)
{
  Assert(static_cast<size_type>(std::distance(begin, end)) == n_rows,
         ExcIteratorRange(std::distance(begin, end), n_rows));
 
  // first determine row lengths for each row. if the matrix is quadratic,
  // then we might have to add an additional entry for the diagonal, if that
  // is not yet present. as we have to call compress anyway later on, don't
  // bother to check whether that diagonal entry is in a certain row or not
  const bool                is_square = (n_rows == n_cols);
  std::vector<unsigned int> row_lengths;
  row_lengths.reserve(n_rows);
  for (ForwardIterator i = begin; i != end; ++i)
    row_lengths.push_back(std::distance(i->begin(), i->end()) +
                          (is_square ? 1 : 0));
  reinit(n_rows, n_cols, row_lengths);
 
  // now enter all the elements into the matrix. note that if the matrix is
  // quadratic, then we already have the diagonal element preallocated
  //
  // for use in the inner loop, we define an alias to the type of the inner
  // iterators
  size_type row = 0;
  using inner_iterator =
    typename std::iterator_traits<ForwardIterator>::value_type::const_iterator;
  for (ForwardIterator i = begin; i != end; ++i, ++row)
    {
      size_type           *cols = &colnums[rowstart[row]] + (is_square ? 1 : 0);
      const inner_iterator end_of_row = i->end();
      for (inner_iterator j = i->begin(); j != end_of_row; ++j)
        {
          const size_type col =
            internal::SparsityPatternTools::get_column_index_from_iterator(*j);
          AssertIndexRange(col, n_cols);
 
          if ((col != row) || !is_square)
            *cols++ = col;
        }
    }
 
  // finally compress everything. this also sorts the entries within each row
  compress();
}
 
 
 
template <class Archive>
inline void
SparsityPattern::save(Archive &ar, const unsigned int) const
{
  // forward to serialization function in the base class.
  ar &boost::serialization::base_object<const EnableObserverPointer>(*this);
 
  ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed;
 
  if (max_dim != 0)
    ar &boost::serialization::make_array(rowstart.get(), max_dim + 1);
  else
    Assert(rowstart.get() == nullptr, ExcInternalError());
 
  if (max_vec_len != 0)
    ar &boost::serialization::make_array(colnums.get(), max_vec_len);
  else
    Assert(colnums.get() == nullptr, ExcInternalError());
  ar &store_diagonal_first_in_row;
}
 
 
 
template <class Archive>
inline void
SparsityPattern::load(Archive &ar, const unsigned int)
{
  // forward to serialization function in the base class.
  ar &boost::serialization::base_object<EnableObserverPointer>(*this);
 
  ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed;
 
  if (max_dim != 0)
    {
      rowstart = std::make_unique<std::size_t[]>(max_dim + 1);
      ar &boost::serialization::make_array(rowstart.get(), max_dim + 1);
    }
  else
    rowstart.reset();
 
  if (max_vec_len != 0)
    {
      colnums = std::make_unique<size_type[]>(max_vec_len);
      ar &boost::serialization::make_array(colnums.get(), max_vec_len);
    }
  else
    colnums.reset();
  ar &store_diagonal_first_in_row;
}
 
 
#endif // DOXYGEN
 
DEAL_II_NAMESPACE_CLOSE
 
#endif