Reference documentation for deal.II version GIT 44af803bb8 2022-12-03 23:15: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  ::VectorOperation::unknown) const;
276 
292  virtual void
293  reinit(const size_type N, const bool omit_zeroing_entries = false);
294 
318  void
320 
328  void
329  apply_givens_rotation(const std::array<Number, 3> &csr,
330  const size_type i,
331  const size_type k);
332 
340  template <typename Number2>
341  void
342  reinit(const Vector<Number2> &V, const bool omit_zeroing_entries = false);
343 
359  virtual void
361 
373  operator=(const Number s);
374 
382 
389  operator=(Vector<Number> &&v) noexcept = default;
390 
396  template <typename Number2>
399 
405 
406 #ifdef DEAL_II_WITH_PETSC
420 #endif
421 
422 
423 #ifdef DEAL_II_WITH_TRILINOS
441 #endif
442 
448  template <typename Number2>
449  bool
450  operator==(const Vector<Number2> &v) const;
451 
457  template <typename Number2>
458  bool
459  operator!=(const Vector<Number2> &v) const;
460 
482  template <typename Number2>
483  Number
484  operator*(const Vector<Number2> &V) const;
485 
493  real_type
494  norm_sqr() const;
495 
503  Number
504  mean_value() const;
505 
513  real_type
514  l1_norm() const;
515 
524  real_type
525  l2_norm() const;
526 
535  real_type
536  lp_norm(const real_type p) const;
537 
541  real_type
542  linfty_norm() const;
543 
568  Number
569  add_and_dot(const Number a, const Vector<Number> &V, const Vector<Number> &W);
570 
582  pointer
583  data();
584 
589  data() const;
590 
596  iterator
597  begin();
598 
603  begin() const;
604 
608  iterator
609  end();
610 
616  end() const;
617 
621  Number
622  operator()(const size_type i) const;
623 
627  Number &
629 
635  Number
636  operator[](const size_type i) const;
637 
643  Number &
645 
661  template <typename OtherNumber>
662  void
663  extract_subvector_to(const std::vector<size_type> &indices,
664  std::vector<OtherNumber> & values) const;
665 
693  template <typename ForwardIterator, typename OutputIterator>
694  void
695  extract_subvector_to(ForwardIterator indices_begin,
696  const ForwardIterator indices_end,
697  OutputIterator values_begin) const;
713 
721 
726  template <typename OtherNumber>
727  void
728  add(const std::vector<size_type> & indices,
729  const std::vector<OtherNumber> &values);
730 
735  template <typename OtherNumber>
736  void
737  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
738 
744  template <typename OtherNumber>
745  void
746  add(const size_type n_elements,
747  const size_type * indices,
748  const OtherNumber *values);
749 
756  void
757  add(const Number s);
758 
764  void
765  add(const Number a,
766  const Vector<Number> &V,
767  const Number b,
768  const Vector<Number> &W);
769 
775  void
776  add(const Number a, const Vector<Number> &V);
777 
783  void
784  sadd(const Number s, const Vector<Number> &V);
785 
791  void
792  sadd(const Number s, const Number a, const Vector<Number> &V);
793 
800  operator*=(const Number factor);
801 
808  operator/=(const Number factor);
809 
817  void
818  scale(const Vector<Number> &scaling_factors);
819 
825  template <typename Number2>
826  void
827  scale(const Vector<Number2> &scaling_factors);
828 
834  void
835  equ(const Number a, const Vector<Number> &u);
836 
840  template <typename Number2>
841  void
842  equ(const Number a, const Vector<Number2> &u);
843 
848  void
863  void
864  print(std::ostream & out,
865  const unsigned int precision = 3,
866  const bool scientific = true,
867  const bool across = true) const;
868 
874  void
875  block_write(std::ostream &out) const;
876 
888  void
889  block_read(std::istream &in);
890 
896  template <class Archive>
897  void
898  save(Archive &ar, const unsigned int version) const;
899 
905  template <class Archive>
906  void
907  load(Archive &ar, const unsigned int version);
908 
909 #ifdef DOXYGEN
915  template <class Archive>
916  void
917  serialize(Archive &archive, const unsigned int version);
918 #else
919  // This macro defines the serialize() method that is compatible with
920  // the templated save() and load() method that have been implemented.
921  BOOST_SERIALIZATION_SPLIT_MEMBER()
922 #endif
923 
938  bool
940 
956  IndexSet
958 
962  size_type
963  size() const;
964 
972  size_type
974 
980  bool
981  all_zero() const;
982 
992  bool
994 
999  std::size_t
1001 
1007  bool
1009 
1015  void
1019 private:
1024 
1030  void
1032 
1036  void
1037  do_reinit(const size_type new_size,
1038  const bool omit_zeroing_entries,
1039  const bool reset_partitioner);
1040 
1045  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
1047 
1048  // Make all other vector types friends.
1049  template <typename Number2>
1050  friend class Vector;
1051 };
1052 
1054 /*----------------------- Inline functions ----------------------------------*/
1055 
1056 
1057 #ifndef DOXYGEN
1058 
1059 
1060 //------------------------ declarations for explicit specializations
1061 template <>
1063 Vector<int>::lp_norm(const real_type) const;
1064 
1065 
1066 //------------------------ inline functions
1067 
1068 template <typename Number>
1069 inline Vector<Number>::Vector()
1070 {
1071  // virtual functions called in constructors and destructors never use the
1072  // override in a derived class
1073  // for clarity be explicit on which function is called
1075 }
1076 
1077 
1078 
1079 template <typename Number>
1080 template <typename OtherNumber>
1081 Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
1082  : Vector(v.begin(), v.end())
1083 {}
1084 
1085 
1086 
1087 template <typename Number>
1088 template <typename InputIterator>
1089 Vector<Number>::Vector(const InputIterator first, const InputIterator last)
1090 {
1091  // allocate memory. do not initialize it, as we will copy over to it in a
1092  // second
1093  reinit(std::distance(first, last), true);
1094  std::copy(first, last, begin());
1095 }
1096 
1097 
1098 
1099 template <typename Number>
1100 inline Vector<Number>::Vector(const size_type n)
1101 {
1102  // virtual functions called in constructors and destructors never use the
1103  // override in a derived class
1104  // for clarity be explicit on which function is called
1105  Vector<Number>::reinit(n, false);
1106 }
1107 
1108 
1109 
1110 template <typename Number>
1111 inline typename Vector<Number>::size_type
1112 Vector<Number>::size() const
1113 {
1114  return values.size();
1115 }
1116 
1117 
1118 
1119 template <typename Number>
1120 inline typename Vector<Number>::size_type
1122 {
1123  return values.size();
1124 }
1125 
1126 
1127 
1128 template <typename Number>
1129 inline bool
1131 {
1132  return true;
1133 }
1134 
1135 
1136 
1137 template <typename Number>
1138 inline typename Vector<Number>::pointer
1140 {
1141  return values.data();
1142 }
1143 
1144 
1145 
1146 template <typename Number>
1147 inline typename Vector<Number>::const_pointer
1148 Vector<Number>::data() const
1149 {
1150  return values.data();
1151 }
1152 
1153 
1154 
1155 template <typename Number>
1156 inline typename Vector<Number>::iterator
1158 {
1159  return values.begin();
1160 }
1161 
1162 
1163 
1164 template <typename Number>
1165 inline typename Vector<Number>::const_iterator
1166 Vector<Number>::begin() const
1167 {
1168  return values.begin();
1169 }
1170 
1171 
1172 
1173 template <typename Number>
1174 inline typename Vector<Number>::iterator
1176 {
1177  return values.end();
1178 }
1179 
1180 
1181 
1182 template <typename Number>
1183 inline typename Vector<Number>::const_iterator
1184 Vector<Number>::end() const
1185 {
1186  return values.end();
1187 }
1188 
1189 
1190 
1191 template <typename Number>
1192 inline Number
1194 {
1195  AssertIndexRange(i, size());
1196  return values[i];
1197 }
1198 
1199 
1200 
1201 template <typename Number>
1202 inline Number &
1204 {
1205  AssertIndexRange(i, size());
1206  return values[i];
1207 }
1208 
1209 
1210 
1211 template <typename Number>
1212 inline Number
1214 {
1215  return operator()(i);
1216 }
1217 
1218 
1219 
1220 template <typename Number>
1221 inline Number &
1223 {
1224  return operator()(i);
1225 }
1226 
1227 
1228 
1229 template <typename Number>
1230 template <typename OtherNumber>
1231 inline void
1232 Vector<Number>::extract_subvector_to(const std::vector<size_type> &indices,
1233  std::vector<OtherNumber> & values) const
1234 {
1235  for (size_type i = 0; i < indices.size(); ++i)
1236  values[i] = operator()(indices[i]);
1237 }
1238 
1239 
1240 
1241 template <typename Number>
1242 template <typename ForwardIterator, typename OutputIterator>
1243 inline void
1244 Vector<Number>::extract_subvector_to(ForwardIterator indices_begin,
1245  const ForwardIterator indices_end,
1246  OutputIterator values_begin) const
1247 {
1248  while (indices_begin != indices_end)
1249  {
1250  *values_begin = operator()(*indices_begin);
1251  indices_begin++;
1252  values_begin++;
1253  }
1254 }
1255 
1256 
1257 
1258 template <typename Number>
1259 inline Vector<Number> &
1260 Vector<Number>::operator/=(const Number factor)
1261 {
1262  AssertIsFinite(factor);
1263  Assert(factor != Number(0.), ExcZero());
1264 
1265  this->operator*=(Number(1.) / factor);
1266  return *this;
1267 }
1268 
1269 
1270 
1271 template <typename Number>
1272 template <typename OtherNumber>
1273 inline void
1274 Vector<Number>::add(const std::vector<size_type> & indices,
1275  const std::vector<OtherNumber> &values)
1276 {
1277  Assert(indices.size() == values.size(),
1278  ExcDimensionMismatch(indices.size(), values.size()));
1279  add(indices.size(), indices.data(), values.data());
1280 }
1281 
1282 
1283 
1284 template <typename Number>
1285 template <typename OtherNumber>
1286 inline void
1287 Vector<Number>::add(const std::vector<size_type> &indices,
1288  const Vector<OtherNumber> & values)
1289 {
1290  Assert(indices.size() == values.size(),
1291  ExcDimensionMismatch(indices.size(), values.size()));
1292  add(indices.size(), indices.data(), values.values.begin());
1293 }
1294 
1295 
1296 
1297 template <typename Number>
1298 template <typename OtherNumber>
1299 inline void
1300 Vector<Number>::add(const size_type n_indices,
1301  const size_type * indices,
1302  const OtherNumber *values)
1303 {
1304  for (size_type i = 0; i < n_indices; ++i)
1305  {
1306  AssertIndexRange(indices[i], size());
1307  Assert(
1309  ExcMessage(
1310  "The given value is not finite but either infinite or Not A Number (NaN)"));
1311 
1312  this->values[indices[i]] += values[i];
1313  }
1314 }
1315 
1316 
1317 
1318 template <typename Number>
1319 template <typename Number2>
1320 inline bool
1322 {
1323  return !(*this == v);
1324 }
1325 
1326 
1327 
1328 template <typename Number>
1330 {}
1331 
1332 
1333 
1334 template <typename Number>
1335 inline bool
1337 {
1338  return false;
1339 }
1340 
1341 
1342 
1343 template <typename Number>
1344 inline void
1346 {}
1347 
1348 
1349 
1350 template <typename Number>
1351 inline void
1353 {}
1354 
1355 
1356 
1357 template <typename Number>
1358 template <typename Number2>
1359 inline void
1361  const bool omit_zeroing_entries)
1362 {
1363  // go to actual reinit functions in case we need to change something with
1364  // the vector, else there is nothing to be done
1365  if (!omit_zeroing_entries || size() != v.size())
1366  {
1367  do_reinit(v.size(), omit_zeroing_entries, false);
1369  }
1370 }
1371 
1372 
1373 
1374 // Moved from vector.templates.h as an inline function by Luca Heltai
1375 // on 2009/04/12 to prevent strange compiling errors, after making
1376 // swap virtual.
1377 template <typename Number>
1378 inline void
1380 {
1381  values.swap(v.values);
1383 }
1384 
1385 
1386 
1387 template <typename Number>
1388 template <class Archive>
1389 inline void
1390 Vector<Number>::save(Archive &ar, const unsigned int) const
1391 {
1392  // forward to serialization function in the base class.
1393  ar &static_cast<const Subscriptor &>(*this);
1394  ar &values;
1395 }
1396 
1397 
1398 
1399 template <typename Number>
1400 template <class Archive>
1401 inline void
1402 Vector<Number>::load(Archive &ar, const unsigned int)
1403 {
1404  // the load stuff again from the archive
1405  ar &static_cast<Subscriptor &>(*this);
1406  ar &values;
1408 }
1409 
1410 #endif
1411 
1412 
1426 template <typename Number>
1427 inline void
1429 {
1430  u.swap(v);
1431 }
1432 
1433 
1441 template <typename number>
1442 inline std::ostream &
1443 operator<<(std::ostream &out, const Vector<number> &v)
1444 {
1445  Assert(v.size() != 0, ExcEmptyObject());
1446  AssertThrow(out.fail() == false, ExcIO());
1447 
1448  for (typename Vector<number>::size_type i = 0; i < v.size() - 1; ++i)
1449  out << v(i) << ' ';
1450  out << v(v.size() - 1);
1451 
1452  AssertThrow(out.fail() == false, ExcIO());
1453 
1454  return out;
1455 }
1456 
1465 template <typename Number>
1466 struct is_serial_vector<Vector<Number>> : std::true_type
1467 {};
1468 
1469 
1471 
1472 #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:1046
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
void compress(::VectorOperation::values operation=::VectorOperation::unknown) const
friend class Vector
Definition: vector.h:1050
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:1023
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
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:458
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:459
Point< 2 > first
Definition: grid_out.cc:4605
static ::ExceptionBase & ExcZero()
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
#define Assert(cond, exc)
Definition: exceptions.h:1501
#define AssertIsFinite(number)
Definition: exceptions.h:1786
static ::ExceptionBase & ExcEmptyObject()
#define AssertIndexRange(index, range)
Definition: exceptions.h:1760
static ::ExceptionBase & ExcIO()
static ::ExceptionBase & ExcMessage(std::string arg1)
#define AssertThrow(cond, exc)
Definition: exceptions.h:1611
void swap(Vector< Number > &u, Vector< Number > &v)
Definition: vector.h:1428
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:553
unsigned int global_dof_index
Definition: types.h:81