Reference documentation for deal.II version Git b3b9f019ec 2021-07-26 17:39:47 -0400
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
vector.h
Go to the documentation of this file.
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1999 - 2021 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE.md at
12 // the top level directory of deal.II.
13 //
14 // ---------------------------------------------------------------------
15 
16 #ifndef dealii_vector_h
17 #define dealii_vector_h
18 
19 
20 #include <deal.II/base/config.h>
21 
24 #include <deal.II/base/index_set.h>
26 
28 
31 
32 #include <boost/serialization/split_member.hpp>
33 
34 #include <algorithm>
35 #include <initializer_list>
36 #include <iosfwd>
37 #include <iterator>
38 #include <vector>
39 
41 
42 
43 // Forward declarations
44 #ifndef DOXYGEN
45 # ifdef DEAL_II_WITH_PETSC
46 namespace PETScWrappers
47 {
48  class VectorBase;
49 }
50 # endif
51 
52 # ifdef DEAL_II_WITH_TRILINOS
53 namespace TrilinosWrappers
54 {
55  namespace MPI
56  {
57  class Vector;
58  }
59 } // namespace TrilinosWrappers
60 # endif
61 
62 template <typename number>
63 class LAPACKFullMatrix;
64 
65 template <typename>
66 class BlockVector;
67 
68 namespace parallel
69 {
70  namespace internal
71  {
72  class TBBPartitioner;
73  }
74 } // namespace parallel
75 #endif
76 
77 
108 template <typename Number>
109 class Vector : public Subscriptor
110 {
111 public:
112  // The assertion in vector.templates.h for whether or not a number is
113  // finite is not compatible for AD number types.
114  static_assert(
116  "The Vector class does not support auto-differentiable numbers.");
117 
122  using value_type = Number;
123  using pointer = value_type *;
124  using const_pointer = const value_type *;
125  using iterator = value_type *;
126  using const_iterator = const value_type *;
128  using const_reference = const value_type &;
130 
141 
149  Vector();
150 
160  Vector(const Vector<Number> &v);
161 
166  Vector(Vector<Number> &&v) noexcept = default;
167 
176  template <typename OtherNumber>
177  explicit Vector(const Vector<OtherNumber> &v);
178 
194  template <typename OtherNumber>
195  explicit Vector(const std::initializer_list<OtherNumber> &v);
196 
197 #ifdef DEAL_II_WITH_PETSC
198 
209  explicit Vector(const PETScWrappers::VectorBase &v);
210 #endif
211 
212 #ifdef DEAL_II_WITH_TRILINOS
213 
227  explicit Vector(const TrilinosWrappers::MPI::Vector &v);
228 #endif
229 
239  explicit Vector(const size_type n);
240 
245  template <typename InputIterator>
246  Vector(const InputIterator first, const InputIterator last);
247 
252  virtual ~Vector() override = default;
253 
267  void
268  compress(::VectorOperation::values operation =
269  ::VectorOperation::unknown) const;
270 
286  virtual void
287  reinit(const size_type N, const bool omit_zeroing_entries = false);
288 
312  void
313  grow_or_shrink(const size_type N);
314 
322  void
323  apply_givens_rotation(const std::array<Number, 3> &csr,
324  const size_type i,
325  const size_type k);
326 
334  template <typename Number2>
335  void
336  reinit(const Vector<Number2> &V, const bool omit_zeroing_entries = false);
337 
353  virtual void
354  swap(Vector<Number> &v);
355 
366  Vector<Number> &
367  operator=(const Number s);
368 
374  Vector<Number> &
375  operator=(const Vector<Number> &v);
376 
382  Vector<Number> &
383  operator=(Vector<Number> &&v) noexcept = default;
384 
390  template <typename Number2>
391  Vector<Number> &
392  operator=(const Vector<Number2> &v);
393 
397  Vector<Number> &
398  operator=(const BlockVector<Number> &v);
399 
400 #ifdef DEAL_II_WITH_PETSC
401 
412  Vector<Number> &
413  operator=(const PETScWrappers::VectorBase &v);
414 #endif
415 
416 
417 #ifdef DEAL_II_WITH_TRILINOS
418 
433  Vector<Number> &
434  operator=(const TrilinosWrappers::MPI::Vector &v);
435 #endif
436 
442  template <typename Number2>
443  bool
444  operator==(const Vector<Number2> &v) const;
445 
451  template <typename Number2>
452  bool
453  operator!=(const Vector<Number2> &v) const;
454 
456 
457 
462 
476  template <typename Number2>
477  Number operator*(const Vector<Number2> &V) const;
478 
486  real_type
487  norm_sqr() const;
488 
496  Number
497  mean_value() const;
498 
506  real_type
507  l1_norm() const;
508 
517  real_type
518  l2_norm() const;
519 
528  real_type
529  lp_norm(const real_type p) const;
530 
534  real_type
535  linfty_norm() const;
536 
561  Number
562  add_and_dot(const Number a, const Vector<Number> &V, const Vector<Number> &W);
563 
565 
566 
571 
575  pointer
576  data();
577 
582  data() const;
583 
589  iterator
590  begin();
591 
596  begin() const;
597 
601  iterator
602  end();
603 
609  end() const;
610 
614  Number
615  operator()(const size_type i) const;
616 
620  Number &
621  operator()(const size_type i);
622 
628  Number operator[](const size_type i) const;
629 
635  Number &operator[](const size_type i);
636 
652  template <typename OtherNumber>
653  void
654  extract_subvector_to(const std::vector<size_type> &indices,
655  std::vector<OtherNumber> & values) const;
656 
684  template <typename ForwardIterator, typename OutputIterator>
685  void
686  extract_subvector_to(ForwardIterator indices_begin,
687  const ForwardIterator indices_end,
688  OutputIterator values_begin) const;
690 
691 
696 
702  Vector<Number> &
703  operator+=(const Vector<Number> &V);
704 
710  Vector<Number> &
711  operator-=(const Vector<Number> &V);
712 
717  template <typename OtherNumber>
718  void
719  add(const std::vector<size_type> & indices,
720  const std::vector<OtherNumber> &values);
721 
726  template <typename OtherNumber>
727  void
728  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
729 
735  template <typename OtherNumber>
736  void
737  add(const size_type n_elements,
738  const size_type * indices,
739  const OtherNumber *values);
740 
747  void
748  add(const Number s);
749 
755  void
756  add(const Number a,
757  const Vector<Number> &V,
758  const Number b,
759  const Vector<Number> &W);
760 
766  void
767  add(const Number a, const Vector<Number> &V);
768 
774  void
775  sadd(const Number s, const Vector<Number> &V);
776 
782  void
783  sadd(const Number s, const Number a, const Vector<Number> &V);
784 
790  Vector<Number> &
791  operator*=(const Number factor);
792 
798  Vector<Number> &
799  operator/=(const Number factor);
800 
808  void
809  scale(const Vector<Number> &scaling_factors);
810 
816  template <typename Number2>
817  void
818  scale(const Vector<Number2> &scaling_factors);
819 
825  void
826  equ(const Number a, const Vector<Number> &u);
827 
831  template <typename Number2>
832  void
833  equ(const Number a, const Vector<Number2> &u);
834 
839  void
840  update_ghost_values() const;
842 
843 
854  void
855  print(std::ostream & out,
856  const unsigned int precision = 3,
857  const bool scientific = true,
858  const bool across = true) const;
859 
865  void
866  block_write(std::ostream &out) const;
867 
879  void
880  block_read(std::istream &in);
881 
887  template <class Archive>
888  void
889  save(Archive &ar, const unsigned int version) const;
890 
896  template <class Archive>
897  void
898  load(Archive &ar, const unsigned int version);
899 
900 #ifdef DOXYGEN
901 
906  template <class Archive>
907  void
908  serialize(Archive &archive, const unsigned int version);
909 #else
910  // This macro defines the serialize() method that is compatible with
911  // the templated save() and load() method that have been implemented.
912  BOOST_SERIALIZATION_SPLIT_MEMBER()
913 #endif
914 
923 
929  bool
930  in_local_range(const size_type global_index) const;
931 
947  IndexSet
948  locally_owned_elements() const;
949 
953  size_type
954  size() const;
955 
963  size_type
964  locally_owned_size() const;
965 
971  bool
972  all_zero() const;
973 
983  bool
984  is_non_negative() const;
985 
990  std::size_t
991  memory_consumption() const;
992 
998  bool
999  has_ghost_elements() const;
1001 
1002 private:
1007 
1013  void
1014  maybe_reset_thread_partitioner();
1015 
1019  void
1020  do_reinit(const size_type new_size,
1021  const bool omit_zeroing_entries,
1022  const bool reset_partitioner);
1023 
1028  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
1030 
1031  // Make all other vector types friends.
1032  template <typename Number2>
1033  friend class Vector;
1034 };
1035 
1037 /*----------------------- Inline functions ----------------------------------*/
1038 
1039 
1040 #ifndef DOXYGEN
1041 
1042 
1043 //------------------------ declarations for explicit specializations
1044 template <>
1046 Vector<int>::lp_norm(const real_type) const;
1047 
1048 
1049 //------------------------ inline functions
1050 
1051 template <typename Number>
1052 inline Vector<Number>::Vector()
1053 {
1054  // virtual functions called in constructors and destructors never use the
1055  // override in a derived class
1056  // for clarity be explicit on which function is called
1058 }
1059 
1060 
1061 
1062 template <typename Number>
1063 template <typename OtherNumber>
1064 Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
1065  : Vector(v.begin(), v.end())
1066 {}
1067 
1068 
1069 
1070 template <typename Number>
1071 template <typename InputIterator>
1072 Vector<Number>::Vector(const InputIterator first, const InputIterator last)
1073 {
1074  // allocate memory. do not initialize it, as we will copy over to it in a
1075  // second
1076  reinit(std::distance(first, last), true);
1077  std::copy(first, last, begin());
1078 }
1079 
1080 
1081 
1082 template <typename Number>
1083 inline Vector<Number>::Vector(const size_type n)
1084 {
1085  // virtual functions called in constructors and destructors never use the
1086  // override in a derived class
1087  // for clarity be explicit on which function is called
1088  Vector<Number>::reinit(n, false);
1089 }
1090 
1091 
1092 
1093 template <typename Number>
1094 inline typename Vector<Number>::size_type
1095 Vector<Number>::size() const
1096 {
1097  return values.size();
1098 }
1099 
1100 
1101 
1102 template <typename Number>
1103 inline typename Vector<Number>::size_type
1105 {
1106  return values.size();
1107 }
1108 
1109 
1110 
1111 template <typename Number>
1112 inline bool
1114 {
1115  return true;
1116 }
1117 
1118 
1119 
1120 template <typename Number>
1121 inline typename Vector<Number>::pointer
1123 {
1124  return values.data();
1125 }
1126 
1127 
1128 
1129 template <typename Number>
1130 inline typename Vector<Number>::const_pointer
1131 Vector<Number>::data() const
1132 {
1133  return values.data();
1134 }
1135 
1136 
1137 
1138 template <typename Number>
1139 inline typename Vector<Number>::iterator
1141 {
1142  return values.begin();
1143 }
1144 
1145 
1146 
1147 template <typename Number>
1148 inline typename Vector<Number>::const_iterator
1149 Vector<Number>::begin() const
1150 {
1151  return values.begin();
1152 }
1153 
1154 
1155 
1156 template <typename Number>
1157 inline typename Vector<Number>::iterator
1159 {
1160  return values.end();
1161 }
1162 
1163 
1164 
1165 template <typename Number>
1166 inline typename Vector<Number>::const_iterator
1167 Vector<Number>::end() const
1168 {
1169  return values.end();
1170 }
1171 
1172 
1173 
1174 template <typename Number>
1175 inline Number
1177 {
1178  AssertIndexRange(i, size());
1179  return values[i];
1180 }
1181 
1182 
1183 
1184 template <typename Number>
1185 inline Number &
1187 {
1188  AssertIndexRange(i, size());
1189  return values[i];
1190 }
1191 
1192 
1193 
1194 template <typename Number>
1195 inline Number Vector<Number>::operator[](const size_type i) const
1196 {
1197  return operator()(i);
1198 }
1199 
1200 
1201 
1202 template <typename Number>
1203 inline Number &Vector<Number>::operator[](const size_type i)
1204 {
1205  return operator()(i);
1206 }
1207 
1208 
1209 
1210 template <typename Number>
1211 template <typename OtherNumber>
1212 inline void
1213 Vector<Number>::extract_subvector_to(const std::vector<size_type> &indices,
1214  std::vector<OtherNumber> & values) const
1215 {
1216  for (size_type i = 0; i < indices.size(); ++i)
1217  values[i] = operator()(indices[i]);
1218 }
1219 
1220 
1221 
1222 template <typename Number>
1223 template <typename ForwardIterator, typename OutputIterator>
1224 inline void
1225 Vector<Number>::extract_subvector_to(ForwardIterator indices_begin,
1226  const ForwardIterator indices_end,
1227  OutputIterator values_begin) const
1228 {
1229  while (indices_begin != indices_end)
1230  {
1231  *values_begin = operator()(*indices_begin);
1232  indices_begin++;
1233  values_begin++;
1234  }
1235 }
1236 
1237 
1238 
1239 template <typename Number>
1240 inline Vector<Number> &
1241 Vector<Number>::operator/=(const Number factor)
1242 {
1243  AssertIsFinite(factor);
1244  Assert(factor != Number(0.), ExcZero());
1245 
1246  this->operator*=(Number(1.) / factor);
1247  return *this;
1248 }
1249 
1250 
1251 
1252 template <typename Number>
1253 template <typename OtherNumber>
1254 inline void
1255 Vector<Number>::add(const std::vector<size_type> & indices,
1256  const std::vector<OtherNumber> &values)
1257 {
1258  Assert(indices.size() == values.size(),
1259  ExcDimensionMismatch(indices.size(), values.size()));
1260  add(indices.size(), indices.data(), values.data());
1261 }
1262 
1263 
1264 
1265 template <typename Number>
1266 template <typename OtherNumber>
1267 inline void
1268 Vector<Number>::add(const std::vector<size_type> &indices,
1269  const Vector<OtherNumber> & values)
1270 {
1271  Assert(indices.size() == values.size(),
1272  ExcDimensionMismatch(indices.size(), values.size()));
1273  add(indices.size(), indices.data(), values.values.begin());
1274 }
1275 
1276 
1277 
1278 template <typename Number>
1279 template <typename OtherNumber>
1280 inline void
1281 Vector<Number>::add(const size_type n_indices,
1282  const size_type * indices,
1283  const OtherNumber *values)
1284 {
1285  for (size_type i = 0; i < n_indices; ++i)
1286  {
1287  AssertIndexRange(indices[i], size());
1288  Assert(
1289  numbers::is_finite(values[i]),
1290  ExcMessage(
1291  "The given value is not finite but either infinite or Not A Number (NaN)"));
1292 
1293  this->values[indices[i]] += values[i];
1294  }
1295 }
1296 
1297 
1298 
1299 template <typename Number>
1300 template <typename Number2>
1301 inline bool
1302 Vector<Number>::operator!=(const Vector<Number2> &v) const
1303 {
1304  return !(*this == v);
1305 }
1306 
1307 
1308 
1309 template <typename Number>
1311 {}
1312 
1313 
1314 template <typename Number>
1315 inline bool
1317 {
1318  return false;
1319 }
1320 
1321 template <typename Number>
1322 inline void
1324 {}
1325 
1326 
1327 
1328 // Moved from vector.templates.h as an inline function by Luca Heltai
1329 // on 2009/04/12 to prevent strange compiling errors, after making
1330 // swap virtual.
1331 template <typename Number>
1332 inline void
1333 Vector<Number>::swap(Vector<Number> &v)
1334 {
1335  values.swap(v.values);
1336  std::swap(thread_loop_partitioner, v.thread_loop_partitioner);
1337 }
1338 
1339 
1340 
1341 template <typename Number>
1342 template <class Archive>
1343 inline void
1344 Vector<Number>::save(Archive &ar, const unsigned int) const
1345 {
1346  // forward to serialization function in the base class.
1347  ar &static_cast<const Subscriptor &>(*this);
1348  ar &values;
1349 }
1350 
1351 
1352 
1353 template <typename Number>
1354 template <class Archive>
1355 inline void
1356 Vector<Number>::load(Archive &ar, const unsigned int)
1357 {
1358  // the load stuff again from the archive
1359  ar &static_cast<Subscriptor &>(*this);
1360  ar &values;
1362 }
1363 
1364 #endif
1365 
1366 
1379 template <typename Number>
1380 inline void
1381 swap(Vector<Number> &u, Vector<Number> &v)
1382 {
1383  u.swap(v);
1384 }
1385 
1386 
1394 template <typename number>
1395 inline std::ostream &
1396 operator<<(std::ostream &out, const Vector<number> &v)
1397 {
1398  Assert(v.size() != 0, ExcEmptyObject());
1399  AssertThrow(out, ExcIO());
1400 
1401  for (typename Vector<number>::size_type i = 0; i < v.size() - 1; ++i)
1402  out << v(i) << ' ';
1403  out << v(v.size() - 1);
1404 
1405  AssertThrow(out, ExcIO());
1406 
1407  return out;
1408 }
1409 
1418 template <typename Number>
1419 struct is_serial_vector<Vector<Number>> : std::true_type
1420 {};
1421 
1422 
1424 
1425 #endif
void update_ghost_values() const
void reinit(MatrixBlock< MatrixType > &v, const BlockSparsityPattern &p)
Definition: matrix_block.h:618
Number operator[](const size_type i) const
bool operator!=(const Vector< Number2 > &v) const
void load(Archive &ar, const unsigned int version)
void extract_subvector_to(const std::vector< size_type > &indices, std::vector< OtherNumber > &values) const
Number operator()(const size_type i) const
static ::ExceptionBase & ExcIO()
typename numbers::NumberTraits< typename VectorType::value_type >::real_type real_type
Definition: vector.h:140
bool operator!=(const AlignedVector< T > &lhs, const AlignedVector< T > &rhs)
std::vector< value_type > l2_norm(const typename ::Triangulation< dim, spacedim >::cell_iterator &parent, const value_type parent_value)
void scale(const double scaling_factor, Triangulation< dim, spacedim > &triangulation)
Definition: grid_tools.cc:2040
#define AssertIndexRange(index, range)
Definition: exceptions.h:1722
pointer data()
void swap(VectorBase &u, VectorBase &v)
__global__ void add_and_dot(Number *res, Number *v1, const Number *v2, const Number *v3, const Number a, const size_type N)
static const char V
#define AssertThrow(cond, exc)
Definition: exceptions.h:1575
pointer data()
iterator end()
bool operator==(const AlignedVector< T > &lhs, const AlignedVector< T > &rhs)
bool is_finite(const double x)
Definition: numbers.h:537
void add(const std::vector< size_type > &indices, const std::vector< OtherNumber > &values)
static ::ExceptionBase & ExcMessage(std::string arg1)
bool has_ghost_elements() const
std::string compress(const std::string &input)
Definition: utilities.cc:392
typename VectorType::value_type value_type
Definition: vector.h:122
bool in_local_range(const size_type global_index) const
void maybe_reset_thread_partitioner()
#define Assert(cond, exc)
Definition: exceptions.h:1465
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
real_type lp_norm(const real_type p) const
Number linfty_norm(const Tensor< 2, dim, Number > &t)
Definition: tensor.h:2939
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:401
VectorType::value_type * end(VectorType &V)
Vector< Number > & operator*=(const Number factor)
iterator begin()
__global__ void equ(Number *val, const Number a, const Number *V_val, const size_type N)
__global__ void sadd(const Number s, Number *val, const Number a, const Number *V_val, const size_type N)
SymmetricTensor< 2, dim, Number > b(const Tensor< 2, dim, Number > &F)
Point< 2 > first
Definition: grid_out.cc:4587
void swap(Vector< Number > &u, Vector< Number > &v)
Definition: vector.h:1381
unsigned int global_dof_index
Definition: types.h:76
virtual void swap(Vector< Number > &v)
Vector< Number > & operator/=(const Number factor)
void save(Archive &ar, const unsigned int version) const
iterator end()
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:400
VectorType::value_type * begin(VectorType &V)
iterator begin()
size_type locally_owned_size() const
Number l1_norm(const Tensor< 2, dim, Number > &t)
Definition: tensor.h:2913
static const char N
static ::ExceptionBase & ExcEmptyObject()
void compress(::VectorOperation::values operation=::VectorOperation::unknown) const
size_type size() const
virtual void reinit(const size_type N, const bool omit_zeroing_entries=false)
AlignedVector< Number > values
Definition: vector.h:1006
size_type size() const
std::shared_ptr< parallel::internal::TBBPartitioner > thread_loop_partitioner
Definition: vector.h:1029
TrilinosWrappers::types::int_type global_index(const Epetra_BlockMap &map, const ::types::global_dof_index i)
std::enable_if< std::is_floating_point< T >::value &&std::is_floating_point< U >::value, typename ProductType< std::complex< T >, std::complex< U > >::type >::type operator*(const std::complex< T > &left, const std::complex< U > &right)
types::global_dof_index size_type
Definition: vector.h:129
static ::ExceptionBase & ExcZero()
void copy(const T *begin, const T *end, U *dest)
#define AssertIsFinite(number)
Definition: exceptions.h:1748
std::enable_if< std::is_fundamental< T >::value, std::size_t >::type memory_consumption(const T &t)