Reference documentation for deal.II version GIT 77cf9aa859 2023-06-10 04:00:02+00:00
\(\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 - 2022 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>
25 #include <deal.II/base/numbers.h>
27 
30 
31 #include <boost/serialization/split_member.hpp>
32 
33 #include <algorithm>
34 #include <initializer_list>
35 #include <iosfwd>
36 #include <vector>
37 
39 
40 
41 // Forward declarations
42 #ifndef DOXYGEN
43 # ifdef DEAL_II_WITH_PETSC
44 namespace PETScWrappers
45 {
46  class VectorBase;
47 }
48 # endif
49 
50 # ifdef DEAL_II_WITH_TRILINOS
51 namespace TrilinosWrappers
52 {
53  namespace MPI
54  {
55  class Vector;
56  }
57 } // namespace TrilinosWrappers
58 # endif
59 
60 template <typename number>
61 class LAPACKFullMatrix;
62 
63 template <typename>
64 class BlockVector;
65 
66 namespace parallel
67 {
68  namespace internal
69  {
70  class TBBPartitioner;
71  }
72 } // namespace parallel
73 #endif
74 
75 
107 template <typename Number>
108 class Vector : public Subscriptor
109 {
110 public:
118  static_assert(
119  std::is_arithmetic<
121  "The Vector class only supports basic numeric types. In particular, it "
122  "does not support automatically differentiated numbers.");
123 
128  using value_type = Number;
129  using pointer = value_type *;
130  using const_pointer = const value_type *;
131  using iterator = value_type *;
132  using const_iterator = const value_type *;
134  using const_reference = const value_type &;
136 
147 
156 
167 
172  Vector(Vector<Number> &&v) noexcept = default;
173 
182  template <typename OtherNumber>
183  explicit Vector(const Vector<OtherNumber> &v);
184 
200  template <typename OtherNumber>
201  explicit Vector(const std::initializer_list<OtherNumber> &v);
202 
203 #ifdef DEAL_II_WITH_PETSC
215  explicit Vector(const PETScWrappers::VectorBase &v);
216 #endif
217 
218 #ifdef DEAL_II_WITH_TRILINOS
234 #endif
235 
245  explicit Vector(const size_type n);
246 
251  template <typename InputIterator>
252  Vector(const InputIterator first, const InputIterator last);
253 
258  virtual ~Vector() override = default;
259 
273  void
275 
291  virtual void
292  reinit(const size_type N, const bool omit_zeroing_entries = false);
293 
317  void
319 
327  void
328  apply_givens_rotation(const std::array<Number, 3> &csr,
329  const size_type i,
330  const size_type k);
331 
339  template <typename Number2>
340  void
341  reinit(const Vector<Number2> &V, const bool omit_zeroing_entries = false);
342 
358  virtual void
360 
372  operator=(const Number s);
373 
381 
388  operator=(Vector<Number> &&v) noexcept = default;
389 
395  template <typename Number2>
398 
404 
405 #ifdef DEAL_II_WITH_PETSC
419 #endif
420 
421 
422 #ifdef DEAL_II_WITH_TRILINOS
440 #endif
441 
447  template <typename Number2>
448  bool
449  operator==(const Vector<Number2> &v) const;
450 
456  template <typename Number2>
457  bool
458  operator!=(const Vector<Number2> &v) const;
459 
481  template <typename Number2>
482  Number
483  operator*(const Vector<Number2> &V) const;
484 
492  real_type
493  norm_sqr() const;
494 
502  Number
503  mean_value() const;
504 
512  real_type
513  l1_norm() const;
514 
523  real_type
524  l2_norm() const;
525 
534  real_type
535  lp_norm(const real_type p) const;
536 
540  real_type
541  linfty_norm() const;
542 
567  Number
568  add_and_dot(const Number a, const Vector<Number> &V, const Vector<Number> &W);
569 
581  pointer
582  data();
583 
588  data() const;
589 
595  iterator
596  begin();
597 
602  begin() const;
603 
607  iterator
608  end();
609 
615  end() const;
616 
620  Number
621  operator()(const size_type i) const;
622 
626  Number &
628 
634  Number
635  operator[](const size_type i) const;
636 
642  Number &
644 
660  template <typename OtherNumber>
661  void
662  extract_subvector_to(const std::vector<size_type> &indices,
663  std::vector<OtherNumber> & values) const;
664 
692  template <typename ForwardIterator, typename OutputIterator>
693  void
694  extract_subvector_to(ForwardIterator indices_begin,
695  const ForwardIterator indices_end,
696  OutputIterator values_begin) const;
712 
720 
725  template <typename OtherNumber>
726  void
727  add(const std::vector<size_type> & indices,
728  const std::vector<OtherNumber> &values);
729 
734  template <typename OtherNumber>
735  void
736  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
737 
743  template <typename OtherNumber>
744  void
745  add(const size_type n_elements,
746  const size_type * indices,
747  const OtherNumber *values);
748 
755  void
756  add(const Number s);
757 
763  void
764  add(const Number a,
765  const Vector<Number> &V,
766  const Number b,
767  const Vector<Number> &W);
768 
774  void
775  add(const Number a, const Vector<Number> &V);
776 
782  void
783  sadd(const Number s, const Vector<Number> &V);
784 
790  void
791  sadd(const Number s, const Number a, const Vector<Number> &V);
792 
799  operator*=(const Number factor);
800 
807  operator/=(const Number factor);
808 
816  void
817  scale(const Vector<Number> &scaling_factors);
818 
824  template <typename Number2>
825  void
826  scale(const Vector<Number2> &scaling_factors);
827 
833  void
834  equ(const Number a, const Vector<Number> &u);
835 
839  template <typename Number2>
840  void
841  equ(const Number a, const Vector<Number2> &u);
842 
847  void
862  void
863  print(std::ostream & out,
864  const unsigned int precision = 3,
865  const bool scientific = true,
866  const bool across = true) const;
867 
873  void
874  block_write(std::ostream &out) const;
875 
887  void
888  block_read(std::istream &in);
889 
895  template <class Archive>
896  void
897  save(Archive &ar, const unsigned int version) const;
898 
904  template <class Archive>
905  void
906  load(Archive &ar, const unsigned int version);
907 
908 #ifdef DOXYGEN
914  template <class Archive>
915  void
916  serialize(Archive &archive, const unsigned int version);
917 #else
918  // This macro defines the serialize() method that is compatible with
919  // the templated save() and load() method that have been implemented.
920  BOOST_SERIALIZATION_SPLIT_MEMBER()
921 #endif
922 
937  bool
939 
955  IndexSet
957 
961  size_type
962  size() const;
963 
971  size_type
973 
979  bool
980  all_zero() const;
981 
991  bool
993 
998  std::size_t
1000 
1006  bool
1008 
1014  void
1018 private:
1023 
1029  void
1031 
1035  void
1036  do_reinit(const size_type new_size,
1037  const bool omit_zeroing_entries,
1038  const bool reset_partitioner);
1039 
1044  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
1046 
1047  // Make all other vector types friends.
1048  template <typename Number2>
1049  friend class Vector;
1050 };
1051 
1053 /*----------------------- Inline functions ----------------------------------*/
1054 
1055 
1056 #ifndef DOXYGEN
1057 
1058 
1059 //------------------------ declarations for explicit specializations
1060 template <>
1062 Vector<int>::lp_norm(const real_type) const;
1063 
1064 
1065 //------------------------ inline functions
1066 
1067 template <typename Number>
1068 inline Vector<Number>::Vector()
1069 {
1070  // virtual functions called in constructors and destructors never use the
1071  // override in a derived class
1072  // for clarity be explicit on which function is called
1074 }
1075 
1076 
1077 
1078 template <typename Number>
1079 template <typename OtherNumber>
1080 Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
1081  : Vector(v.begin(), v.end())
1082 {}
1083 
1084 
1085 
1086 template <typename Number>
1087 template <typename InputIterator>
1088 Vector<Number>::Vector(const InputIterator first, const InputIterator last)
1089 {
1090  // allocate memory. do not initialize it, as we will copy over to it in a
1091  // second
1092  reinit(std::distance(first, last), true);
1093  std::copy(first, last, begin());
1094 }
1095 
1096 
1097 
1098 template <typename Number>
1099 inline Vector<Number>::Vector(const size_type n)
1100 {
1101  // virtual functions called in constructors and destructors never use the
1102  // override in a derived class
1103  // for clarity be explicit on which function is called
1104  Vector<Number>::reinit(n, false);
1105 }
1106 
1107 
1108 
1109 template <typename Number>
1110 inline typename Vector<Number>::size_type
1111 Vector<Number>::size() const
1112 {
1113  return values.size();
1114 }
1115 
1116 
1117 
1118 template <typename Number>
1119 inline typename Vector<Number>::size_type
1121 {
1122  return values.size();
1123 }
1124 
1125 
1126 
1127 template <typename Number>
1128 inline bool
1130 {
1131  return true;
1132 }
1133 
1134 
1135 
1136 template <typename Number>
1137 inline typename Vector<Number>::pointer
1139 {
1140  return values.data();
1141 }
1142 
1143 
1144 
1145 template <typename Number>
1146 inline typename Vector<Number>::const_pointer
1147 Vector<Number>::data() const
1148 {
1149  return values.data();
1150 }
1151 
1152 
1153 
1154 template <typename Number>
1155 inline typename Vector<Number>::iterator
1157 {
1158  return values.begin();
1159 }
1160 
1161 
1162 
1163 template <typename Number>
1164 inline typename Vector<Number>::const_iterator
1165 Vector<Number>::begin() const
1166 {
1167  return values.begin();
1168 }
1169 
1170 
1171 
1172 template <typename Number>
1173 inline typename Vector<Number>::iterator
1175 {
1176  return values.end();
1177 }
1178 
1179 
1180 
1181 template <typename Number>
1182 inline typename Vector<Number>::const_iterator
1183 Vector<Number>::end() const
1184 {
1185  return values.end();
1186 }
1187 
1188 
1189 
1190 template <typename Number>
1191 inline Number
1193 {
1194  AssertIndexRange(i, size());
1195  return values[i];
1196 }
1197 
1198 
1199 
1200 template <typename Number>
1201 inline Number &
1203 {
1204  AssertIndexRange(i, size());
1205  return values[i];
1206 }
1207 
1208 
1209 
1210 template <typename Number>
1211 inline Number
1213 {
1214  return operator()(i);
1215 }
1216 
1217 
1218 
1219 template <typename Number>
1220 inline Number &
1222 {
1223  return operator()(i);
1224 }
1225 
1226 
1227 
1228 template <typename Number>
1229 template <typename OtherNumber>
1230 inline void
1231 Vector<Number>::extract_subvector_to(const std::vector<size_type> &indices,
1232  std::vector<OtherNumber> & values) const
1233 {
1234  for (size_type i = 0; i < indices.size(); ++i)
1235  values[i] = operator()(indices[i]);
1236 }
1237 
1238 
1239 
1240 template <typename Number>
1241 template <typename ForwardIterator, typename OutputIterator>
1242 inline void
1243 Vector<Number>::extract_subvector_to(ForwardIterator indices_begin,
1244  const ForwardIterator indices_end,
1245  OutputIterator values_begin) const
1246 {
1247  while (indices_begin != indices_end)
1248  {
1249  *values_begin = operator()(*indices_begin);
1250  indices_begin++;
1251  values_begin++;
1252  }
1253 }
1254 
1255 
1256 
1257 template <typename Number>
1258 inline Vector<Number> &
1259 Vector<Number>::operator/=(const Number factor)
1260 {
1261  AssertIsFinite(factor);
1262  Assert(factor != Number(0.), ExcZero());
1263 
1264  this->operator*=(Number(1.) / factor);
1265  return *this;
1266 }
1267 
1268 
1269 
1270 template <typename Number>
1271 template <typename OtherNumber>
1272 inline void
1273 Vector<Number>::add(const std::vector<size_type> & indices,
1274  const std::vector<OtherNumber> &values)
1275 {
1276  Assert(indices.size() == values.size(),
1277  ExcDimensionMismatch(indices.size(), values.size()));
1278  add(indices.size(), indices.data(), values.data());
1279 }
1280 
1281 
1282 
1283 template <typename Number>
1284 template <typename OtherNumber>
1285 inline void
1286 Vector<Number>::add(const std::vector<size_type> &indices,
1287  const Vector<OtherNumber> & values)
1288 {
1289  Assert(indices.size() == values.size(),
1290  ExcDimensionMismatch(indices.size(), values.size()));
1291  add(indices.size(), indices.data(), values.values.begin());
1292 }
1293 
1294 
1295 
1296 template <typename Number>
1297 template <typename OtherNumber>
1298 inline void
1299 Vector<Number>::add(const size_type n_indices,
1300  const size_type * indices,
1301  const OtherNumber *values)
1302 {
1303  for (size_type i = 0; i < n_indices; ++i)
1304  {
1305  AssertIndexRange(indices[i], size());
1306  Assert(
1308  ExcMessage(
1309  "The given value is not finite but either infinite or Not A Number (NaN)"));
1310 
1311  this->values[indices[i]] += values[i];
1312  }
1313 }
1314 
1315 
1316 
1317 template <typename Number>
1318 template <typename Number2>
1319 inline bool
1321 {
1322  return !(*this == v);
1323 }
1324 
1325 
1326 
1327 template <typename Number>
1329 {}
1330 
1331 
1332 
1333 template <typename Number>
1334 inline bool
1336 {
1337  return false;
1338 }
1339 
1340 
1341 
1342 template <typename Number>
1343 inline void
1345 {}
1346 
1347 
1348 
1349 template <typename Number>
1350 inline void
1352 {}
1353 
1354 
1355 
1356 template <typename Number>
1357 template <typename Number2>
1358 inline void
1360  const bool omit_zeroing_entries)
1361 {
1362  // go to actual reinit functions in case we need to change something with
1363  // the vector, else there is nothing to be done
1364  if (!omit_zeroing_entries || size() != v.size())
1365  {
1366  do_reinit(v.size(), omit_zeroing_entries, false);
1368  }
1369 }
1370 
1371 
1372 
1373 // Moved from vector.templates.h as an inline function by Luca Heltai
1374 // on 2009/04/12 to prevent strange compiling errors, after making
1375 // swap virtual.
1376 template <typename Number>
1377 inline void
1379 {
1380  values.swap(v.values);
1382 }
1383 
1384 
1385 
1386 template <typename Number>
1387 template <class Archive>
1388 inline void
1389 Vector<Number>::save(Archive &ar, const unsigned int) const
1390 {
1391  // forward to serialization function in the base class.
1392  ar &static_cast<const Subscriptor &>(*this);
1393  ar &values;
1394 }
1395 
1396 
1397 
1398 template <typename Number>
1399 template <class Archive>
1400 inline void
1401 Vector<Number>::load(Archive &ar, const unsigned int)
1402 {
1403  // the load stuff again from the archive
1404  ar &static_cast<Subscriptor &>(*this);
1405  ar &values;
1407 }
1408 
1409 #endif
1410 
1411 
1425 template <typename Number>
1426 inline void
1428 {
1429  u.swap(v);
1430 }
1431 
1432 
1440 template <typename number>
1441 inline std::ostream &
1442 operator<<(std::ostream &out, const Vector<number> &v)
1443 {
1444  Assert(v.size() != 0, ExcEmptyObject());
1445  AssertThrow(out.fail() == false, ExcIO());
1446 
1447  for (typename Vector<number>::size_type i = 0; i < v.size() - 1; ++i)
1448  out << v(i) << ' ';
1449  out << v(v.size() - 1);
1450 
1451  AssertThrow(out.fail() == false, ExcIO());
1452 
1453  return out;
1454 }
1455 
1464 template <typename Number>
1465 struct is_serial_vector<Vector<Number>> : std::true_type
1466 {};
1467 
1468 
1470 
1471 #endif
OutputOperator< VectorType > & operator<<(OutputOperator< VectorType > &out, unsigned int step)
Definition: operator.h:165
Definition: vector.h:109
typename numbers::NumberTraits< Number >::real_type real_type
Definition: vector.h:146
void extract_subvector_to(ForwardIterator indices_begin, const ForwardIterator indices_end, OutputIterator values_begin) const
bool operator!=(const Vector< Number2 > &v) const
const value_type * const_pointer
Definition: vector.h:130
void scale(const Vector< Number2 > &scaling_factors)
Vector< Number > & operator+=(const Vector< Number > &V)
bool has_ghost_elements() const
void add(const std::vector< size_type > &indices, const std::vector< OtherNumber > &values)
Number & operator()(const size_type i)
void add(const Number a, const Vector< Number > &V, const Number b, const Vector< Number > &W)
Vector(const TrilinosWrappers::MPI::Vector &v)
bool in_local_range(const size_type global_index) const
Number operator*(const Vector< Number2 > &V) const
const_pointer data() const
void do_reinit(const size_type new_size, const bool omit_zeroing_entries, const bool reset_partitioner)
void add(const Number s)
void sadd(const Number s, const Number a, const Vector< Number > &V)
Vector(const size_type n)
const value_type * const_iterator
Definition: vector.h:132
void block_write(std::ostream &out) const
Number mean_value() const
Number add_and_dot(const Number a, const Vector< Number > &V, const Vector< Number > &W)
void load(Archive &ar, const unsigned int version)
const value_type & const_reference
Definition: vector.h:134
Vector< Number > & operator/=(const Number factor)
pointer data()
void reinit(const Vector< Number2 > &V, const bool omit_zeroing_entries=false)
Vector< Number > & operator=(const TrilinosWrappers::MPI::Vector &v)
void print(std::ostream &out, const unsigned int precision=3, const bool scientific=true, const bool across=true) const
Number & operator[](const size_type i)
Vector< Number > & operator*=(const Number factor)
Vector(const Vector< Number > &v)
std::shared_ptr< parallel::internal::TBBPartitioner > thread_loop_partitioner
Definition: vector.h:1045
void block_read(std::istream &in)
types::global_dof_index size_type
Definition: vector.h:135
Vector< Number > & operator=(const BlockVector< Number > &v)
Number operator[](const size_type i) const
Vector< Number > & operator=(const Vector< Number > &v)
void equ(const Number a, const Vector< Number > &u)
void zero_out_ghost_values() const
Vector< Number > & operator-=(const Vector< Number > &V)
void serialize(Archive &archive, const unsigned int version)
Vector(const PETScWrappers::VectorBase &v)
real_type lp_norm(const real_type p) const
const_iterator begin() const
void sadd(const Number s, const Vector< Number > &V)
Vector< Number > & operator=(const PETScWrappers::VectorBase &v)
bool operator==(const Vector< Number2 > &v) const
iterator end()
size_type size() const
friend class Vector
Definition: vector.h:1049
real_type l2_norm() const
value_type * pointer
Definition: vector.h:129
virtual void swap(Vector< Number > &v)
void grow_or_shrink(const size_type N)
virtual ~Vector() override=default
Vector(const Vector< OtherNumber > &v)
void save(Archive &ar, const unsigned int version) const
Vector< Number > & operator=(const Number s)
real_type linfty_norm() const
Vector< Number > & operator=(const Vector< Number2 > &v)
void scale(const Vector< Number > &scaling_factors)
void maybe_reset_thread_partitioner()
IndexSet locally_owned_elements() const
real_type norm_sqr() const
void add(const Number a, const Vector< Number > &V)
AlignedVector< Number > values
Definition: vector.h:1022
void equ(const Number a, const Vector< Number2 > &u)
void apply_givens_rotation(const std::array< Number, 3 > &csr, const size_type i, const size_type k)
const_iterator end() const
Vector(Vector< Number > &&v) noexcept=default
virtual void reinit(const size_type N, const bool omit_zeroing_entries=false)
value_type * iterator
Definition: vector.h:131
void add(const size_type n_elements, const size_type *indices, const OtherNumber *values)
size_type locally_owned_size() const
Number operator()(const size_type i) const
void compress(VectorOperation::values operation=VectorOperation::unknown) const
bool is_non_negative() const
value_type & reference
Definition: vector.h:133
void extract_subvector_to(const std::vector< size_type > &indices, std::vector< OtherNumber > &values) const
void update_ghost_values() const
Vector< Number > & operator=(Vector< Number > &&v) noexcept=default
bool all_zero() const
std::size_t memory_consumption() const
real_type l1_norm() const
void add(const std::vector< size_type > &indices, const Vector< OtherNumber > &values)
Number value_type
Definition: vector.h:128
iterator begin()
Vector(const InputIterator first, const InputIterator last)
Vector(const std::initializer_list< OtherNumber > &v)
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:475
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:476
Point< 2 > first
Definition: grid_out.cc:4615
static ::ExceptionBase & ExcZero()
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
#define Assert(cond, exc)
Definition: exceptions.h:1614
#define AssertIsFinite(number)
Definition: exceptions.h:1882
static ::ExceptionBase & ExcEmptyObject()
#define AssertIndexRange(index, range)
Definition: exceptions.h:1855
static ::ExceptionBase & ExcIO()
static ::ExceptionBase & ExcMessage(std::string arg1)
#define AssertThrow(cond, exc)
Definition: exceptions.h:1703
void swap(Vector< Number > &u, Vector< Number > &v)
Definition: vector.h:1427
static const char N
static const char V
types::global_dof_index size_type
Definition: cuda_kernels.h:45
SymmetricTensor< 2, dim, Number > b(const Tensor< 2, dim, Number > &F)
VectorType::value_type * begin(VectorType &V)
VectorType::value_type * end(VectorType &V)
TrilinosWrappers::types::int_type global_index(const Epetra_BlockMap &map, const ::types::global_dof_index i)
void copy(const T *begin, const T *end, U *dest)
void reinit(MatrixBlock< MatrixType > &v, const BlockSparsityPattern &p)
Definition: matrix_block.h:618
bool is_finite(const double x)
Definition: numbers.h:538
unsigned int global_dof_index
Definition: types.h:82