vector.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 1999 - 2024 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Part of the source code is dual licensed under Apache-2.0 WITH
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
// governing the source code and code contributions can be found in
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
//
// ------------------------------------------------------------------------
 
#ifndef dealii_vector_h
#define dealii_vector_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/aligned_vector.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/index_set.h>
#include <deal.II/base/numbers.h>
#include <deal.II/base/subscriptor.h>
 
#include <deal.II/lac/read_vector.h>
#include <deal.II/lac/vector_operation.h>
#include <deal.II/lac/vector_type_traits.h>
 
#include <boost/serialization/split_member.hpp>
 
#include <algorithm>
#include <initializer_list>
#include <iosfwd>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
 
// Forward declarations
#ifndef DOXYGEN
#  ifdef DEAL_II_WITH_PETSC
namespace PETScWrappers
{
  class VectorBase;
}
#  endif
 
#  ifdef DEAL_II_WITH_TRILINOS
namespace TrilinosWrappers
{
  namespace MPI
  {
    class Vector;
  }
} // namespace TrilinosWrappers
#  endif
 
#  ifdef DEAL_II_TRILINOS_WITH_TPETRA
namespace LinearAlgebra
{
  namespace TpetraWrappers
  {
    template <typename Number, typename MemorySpace>
    class Vector;
  }
} // namespace LinearAlgebra
#  endif
 
template <typename number>
class LAPACKFullMatrix;
 
template <typename>
class BlockVector;
 
namespace parallel
{
  namespace internal
  {
    class TBBPartitioner;
  }
} // namespace parallel
#endif
 
 
template <typename Number>
class Vector : public Subscriptor, public ReadVector<Number>
{
public:
  static_assert(
    std::is_arithmetic_v<typename numbers::NumberTraits<Number>::real_type>,
    "The Vector class only supports basic numeric types. In particular, it "
    "does not support automatically differentiated numbers.");
 
  using value_type      = Number;
  using pointer         = value_type *;
  using const_pointer   = const value_type *;
  using iterator        = value_type *;
  using const_iterator  = const value_type *;
  using reference       = value_type &;
  using const_reference = const value_type &;
  using size_type       = types::global_dof_index;
 
  using real_type = typename numbers::NumberTraits<Number>::real_type;
 
  Vector();
 
  Vector(const Vector<Number> &v);
 
  Vector(Vector<Number> &&v) noexcept = default;
 
  template <typename OtherNumber>
  explicit Vector(const Vector<OtherNumber> &v);
 
  template <typename OtherNumber>
  explicit Vector(const std::initializer_list<OtherNumber> &v);
 
#ifdef DEAL_II_WITH_PETSC
  explicit Vector(const PETScWrappers::VectorBase &v);
#endif
 
#ifdef DEAL_II_WITH_TRILINOS
  explicit Vector(const TrilinosWrappers::MPI::Vector &v);
#endif
 
#ifdef DEAL_II_TRILINOS_WITH_TPETRA
  template <typename OtherNumber, typename MemorySpace>
  explicit Vector(
    const LinearAlgebra::TpetraWrappers::Vector<OtherNumber, MemorySpace> &v);
#endif
 
  explicit Vector(const size_type n);
 
  template <typename InputIterator>
  Vector(const InputIterator first, const InputIterator last);
 
  virtual ~Vector() override = default;
 
 
  bool
  empty() const;
 
  void
  compress(VectorOperation::values operation = VectorOperation::unknown) const;
 
  virtual void
  reinit(const size_type N, const bool omit_zeroing_entries = false);
 
  void
  grow_or_shrink(const size_type N);
 
  void
  apply_givens_rotation(const std::array<Number, 3> &csr,
                        const size_type              i,
                        const size_type              k);
 
  template <typename Number2>
  void
  reinit(const Vector<Number2> &V, const bool omit_zeroing_entries = false);
 
  virtual void
  swap(Vector<Number> &v) noexcept;
 
  Vector<Number> &
  operator=(const Number s);
 
  Vector<Number> &
  operator=(const Vector<Number> &v);
 
  Vector<Number> &
  operator=(Vector<Number> &&v) noexcept = default;
 
  template <typename Number2>
  Vector<Number> &
  operator=(const Vector<Number2> &v);
 
  Vector<Number> &
  operator=(const BlockVector<Number> &v);
 
#ifdef DEAL_II_WITH_PETSC
  Vector<Number> &
  operator=(const PETScWrappers::VectorBase &v);
#endif
 
 
#ifdef DEAL_II_WITH_TRILINOS
  Vector<Number> &
  operator=(const TrilinosWrappers::MPI::Vector &v);
#endif
 
#ifdef DEAL_II_TRILINOS_WITH_TPETRA
  template <typename OtherNumber, typename MemorySpace>
  Vector<Number> &
  operator=(
    const LinearAlgebra::TpetraWrappers::Vector<OtherNumber, MemorySpace> &v);
#endif
 
  template <typename Number2>
  bool
  operator==(const Vector<Number2> &v) const;
 
  template <typename Number2>
  bool
  operator!=(const Vector<Number2> &v) const;
 
  template <typename Number2>
  Number
  operator*(const Vector<Number2> &V) const;
 
  real_type
  norm_sqr() const;
 
  Number
  mean_value() const;
 
  real_type
  l1_norm() const;
 
  real_type
  l2_norm() const;
 
  real_type
  lp_norm(const real_type p) const;
 
  real_type
  linfty_norm() const;
 
  Number
  add_and_dot(const Number a, const Vector<Number> &V, const Vector<Number> &W);
 
  pointer
  data();
 
  const_pointer
  data() const;
 
  iterator
  begin();
 
  const_iterator
  begin() const;
 
  iterator
  end();
 
  const_iterator
  end() const;
 
  Number
  operator()(const size_type i) const;
 
  Number &
  operator()(const size_type i);
 
  Number
  operator[](const size_type i) const;
 
  Number &
  operator[](const size_type i);
 
  template <typename OtherNumber>
  void
  extract_subvector_to(const std::vector<size_type> &indices,
                       std::vector<OtherNumber>     &values) const;
 
  virtual void
  extract_subvector_to(const ArrayView<const types::global_dof_index> &indices,
                       ArrayView<Number> &elements) const override;
 
  template <typename ForwardIterator, typename OutputIterator>
  void
  extract_subvector_to(ForwardIterator       indices_begin,
                       const ForwardIterator indices_end,
                       OutputIterator        values_begin) const;
  Vector<Number> &
  operator+=(const Vector<Number> &V);
 
  Vector<Number> &
  operator-=(const Vector<Number> &V);
 
  template <typename OtherNumber>
  void
  add(const std::vector<size_type>   &indices,
      const std::vector<OtherNumber> &values);
 
  template <typename OtherNumber>
  void
  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
 
  template <typename OtherNumber>
  void
  add(const size_type    n_elements,
      const size_type   *indices,
      const OtherNumber *values);
 
  void
  add(const Number s);
 
  void
  add(const Number          a,
      const Vector<Number> &V,
      const Number          b,
      const Vector<Number> &W);
 
  void
  add(const Number a, const Vector<Number> &V);
 
  void
  sadd(const Number s, const Vector<Number> &V);
 
  void
  sadd(const Number s, const Number a, const Vector<Number> &V);
 
  Vector<Number> &
  operator*=(const Number factor);
 
  Vector<Number> &
  operator/=(const Number factor);
 
  void
  scale(const Vector<Number> &scaling_factors);
 
  template <typename Number2>
  void
  scale(const Vector<Number2> &scaling_factors);
 
  void
  equ(const Number a, const Vector<Number> &u);
 
  template <typename Number2>
  void
  equ(const Number a, const Vector<Number2> &u);
 
  void
  update_ghost_values() const;
  void
  print(std::ostream      &out,
        const unsigned int precision  = 3,
        const bool         scientific = true,
        const bool         across     = true) 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
 
  bool
  in_local_range(const size_type global_index) const;
 
  IndexSet
  locally_owned_elements() const;
 
  virtual size_type
  size() const override;
 
  size_type
  locally_owned_size() const;
 
  bool
  all_zero() const;
 
  bool
  is_non_negative() const;
 
  std::size_t
  memory_consumption() const;
 
  bool
  has_ghost_elements() const;
 
  void
  zero_out_ghost_values() const;
 
  MPI_Comm
  get_mpi_communicator() const;
private:
  AlignedVector<Number> values;
 
  void
  maybe_reset_thread_partitioner();
 
  void
  do_reinit(const size_type new_size,
            const bool      omit_zeroing_entries,
            const bool      reset_partitioner);
 
  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
    thread_loop_partitioner;
 
  // Make all other vector types friends.
  template <typename Number2>
  friend class Vector;
};
 
/*----------------------- Inline functions ----------------------------------*/
 
 
#ifndef DOXYGEN
 
 
//------------------------ declarations for explicit specializations
template <>
Vector<int>::real_type
Vector<int>::lp_norm(const real_type) const;
 
 
//------------------------ inline functions
 
template <typename Number>
inline Vector<Number>::Vector()
{
  // virtual functions called in constructors and destructors never use the
  // override in a derived class
  // for clarity be explicit on which function is called
  Vector<Number>::reinit(0);
}
 
 
 
template <typename Number>
template <typename OtherNumber>
Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
  : Vector(v.begin(), v.end())
{}
 
 
 
template <typename Number>
template <typename InputIterator>
Vector<Number>::Vector(const InputIterator first, const InputIterator last)
{
  // allocate memory. do not initialize it, as we will copy over to it in a
  // second
  reinit(std::distance(first, last), true);
  std::copy(first, last, begin());
}
 
 
 
template <typename Number>
inline Vector<Number>::Vector(const size_type n)
{
  // virtual functions called in constructors and destructors never use the
  // override in a derived class
  // for clarity be explicit on which function is called
  Vector<Number>::reinit(n, false);
}
 
 
 
template <typename Number>
inline typename Vector<Number>::size_type
Vector<Number>::size() const
{
  return values.size();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::size_type
Vector<Number>::locally_owned_size() const
{
  return values.size();
}
 
 
 
template <typename Number>
inline bool
Vector<Number>::in_local_range(const size_type) const
{
  return true;
}
 
 
 
template <typename Number>
inline typename Vector<Number>::pointer
Vector<Number>::data()
{
  return values.data();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::const_pointer
Vector<Number>::data() const
{
  return values.data();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::iterator
Vector<Number>::begin()
{
  return values.begin();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::const_iterator
Vector<Number>::begin() const
{
  return values.begin();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::iterator
Vector<Number>::end()
{
  return values.end();
}
 
 
 
template <typename Number>
inline typename Vector<Number>::const_iterator
Vector<Number>::end() const
{
  return values.end();
}
 
 
 
template <typename Number>
inline Number
Vector<Number>::operator()(const size_type i) const
{
  AssertIndexRange(i, size());
  return values[i];
}
 
 
 
template <typename Number>
inline Number &
Vector<Number>::operator()(const size_type i)
{
  AssertIndexRange(i, size());
  return values[i];
}
 
 
 
template <typename Number>
inline Number
Vector<Number>::operator[](const size_type i) const
{
  return operator()(i);
}
 
 
 
template <typename Number>
inline Number &
Vector<Number>::operator[](const size_type i)
{
  return operator()(i);
}
 
 
 
template <typename Number>
template <typename OtherNumber>
inline void
Vector<Number>::extract_subvector_to(const std::vector<size_type> &indices,
                                     std::vector<OtherNumber>     &values) const
{
  for (size_type i = 0; i < indices.size(); ++i)
    values[i] = operator()(indices[i]);
}
 
 
 
template <typename Number>
template <typename ForwardIterator, typename OutputIterator>
inline void
Vector<Number>::extract_subvector_to(ForwardIterator       indices_begin,
                                     const ForwardIterator indices_end,
                                     OutputIterator        values_begin) const
{
  while (indices_begin != indices_end)
    {
      *values_begin = operator()(*indices_begin);
      ++indices_begin;
      ++values_begin;
    }
}
 
 
 
template <typename Number>
inline Vector<Number> &
Vector<Number>::operator/=(const Number factor)
{
  AssertIsFinite(factor);
  Assert(factor != Number(0.), ExcZero());
 
  this->operator*=(Number(1.) / factor);
  return *this;
}
 
 
 
template <typename Number>
template <typename OtherNumber>
inline void
Vector<Number>::add(const std::vector<size_type>   &indices,
                    const std::vector<OtherNumber> &values)
{
  Assert(indices.size() == values.size(),
         ExcDimensionMismatch(indices.size(), values.size()));
  add(indices.size(), indices.data(), values.data());
}
 
 
 
template <typename Number>
template <typename OtherNumber>
inline void
Vector<Number>::add(const std::vector<size_type> &indices,
                    const Vector<OtherNumber>    &values)
{
  Assert(indices.size() == values.size(),
         ExcDimensionMismatch(indices.size(), values.size()));
  add(indices.size(), indices.data(), values.values.begin());
}
 
 
 
template <typename Number>
template <typename OtherNumber>
inline void
Vector<Number>::add(const size_type    n_indices,
                    const size_type   *indices,
                    const OtherNumber *values)
{
  for (size_type i = 0; i < n_indices; ++i)
    {
      AssertIndexRange(indices[i], size());
      Assert(
        numbers::is_finite(values[i]),
        ExcMessage(
          "The given value is not finite but either infinite or Not A Number (NaN)"));
 
      this->values[indices[i]] += values[i];
    }
}
 
 
 
template <typename Number>
template <typename Number2>
inline bool
Vector<Number>::operator!=(const Vector<Number2> &v) const
{
  return !(*this == v);
}
 
 
template <typename Number>
inline bool
Vector<Number>::empty() const
{
  return this->size() == 0;
}
 
template <typename Number>
inline void
Vector<Number>::compress(VectorOperation::values) const
{}
 
 
 
template <typename Number>
inline bool
Vector<Number>::has_ghost_elements() const
{
  return false;
}
 
 
 
template <typename Number>
inline void
Vector<Number>::zero_out_ghost_values() const
{}
 
 
 
template <typename Number>
inline void
Vector<Number>::update_ghost_values() const
{}
 
 
 
template <typename Number>
inline MPI_Comm
Vector<Number>::get_mpi_communicator() const
{
  return MPI_COMM_SELF;
}
 
 
template <typename Number>
template <typename Number2>
inline void
Vector<Number>::reinit(const Vector<Number2> &v,
                       const bool             omit_zeroing_entries)
{
  // go to actual reinit functions in case we need to change something with
  // the vector, else there is nothing to be done
  if (!omit_zeroing_entries || size() != v.size())
    {
      do_reinit(v.size(), omit_zeroing_entries, false);
      thread_loop_partitioner = v.thread_loop_partitioner;
    }
}
 
 
 
// Moved from vector.templates.h as an inline function by Luca Heltai
// on 2009/04/12 to prevent strange compiling errors, after making
// swap virtual.
template <typename Number>
inline void
Vector<Number>::swap(Vector<Number> &v) noexcept
{
  values.swap(v.values);
  std::swap(thread_loop_partitioner, v.thread_loop_partitioner);
}
 
 
 
template <typename Number>
template <class Archive>
inline void
Vector<Number>::save(Archive &ar, const unsigned int) const
{
  // forward to serialization function in the base class.
  ar &static_cast<const Subscriptor &>(*this);
  ar &values;
}
 
 
 
template <typename Number>
template <class Archive>
inline void
Vector<Number>::load(Archive &ar, const unsigned int)
{
  // the load stuff again from the archive
  ar &static_cast<Subscriptor &>(*this);
  ar &values;
  maybe_reset_thread_partitioner();
}
 
#endif
 
 
template <typename Number>
inline void
swap(Vector<Number> &u, Vector<Number> &v) noexcept
{
  u.swap(v);
}
 
 
template <typename number>
inline std::ostream &
operator<<(std::ostream &out, const Vector<number> &v)
{
  Assert(v.size() != 0, ExcEmptyObject());
  AssertThrow(out.fail() == false, ExcIO());
 
  for (typename Vector<number>::size_type i = 0; i < v.size() - 1; ++i)
    out << v(i) << ' ';
  out << v(v.size() - 1);
 
  AssertThrow(out.fail() == false, ExcIO());
 
  return out;
}
 
template <typename Number>
struct is_serial_vector<Vector<Number>> : std::true_type
{};
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif