Reference documentation for deal.II version GIT 29f9da0a34 2023-12-07 10:00:01+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 - 2023 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 
31 
32 #include <boost/serialization/split_member.hpp>
33 
34 #include <algorithm>
35 #include <initializer_list>
36 #include <iosfwd>
37 #include <vector>
38 
40 
41 
42 // Forward declarations
43 #ifndef DOXYGEN
44 # ifdef DEAL_II_WITH_PETSC
45 namespace PETScWrappers
46 {
47  class VectorBase;
48 }
49 # endif
50 
51 # ifdef DEAL_II_WITH_TRILINOS
52 namespace TrilinosWrappers
53 {
54  namespace MPI
55  {
56  class Vector;
57  }
58 } // namespace TrilinosWrappers
59 # endif
60 
61 template <typename number>
62 class LAPACKFullMatrix;
63 
64 template <typename>
65 class BlockVector;
66 
67 namespace parallel
68 {
69  namespace internal
70  {
71  class TBBPartitioner;
72  }
73 } // namespace parallel
74 #endif
75 
76 
108 template <typename Number>
109 class Vector : public Subscriptor, public ReadVector<Number>
110 {
111 public:
119  static_assert(
120  std::is_arithmetic<
122  "The Vector class only supports basic numeric types. In particular, it "
123  "does not support automatically differentiated numbers.");
124 
129  using value_type = Number;
130  using pointer = value_type *;
131  using const_pointer = const value_type *;
132  using iterator = value_type *;
133  using const_iterator = const value_type *;
135  using const_reference = const value_type &;
137 
148 
157 
168 
173  Vector(Vector<Number> &&v) noexcept = default;
174 
183  template <typename OtherNumber>
184  explicit Vector(const Vector<OtherNumber> &v);
185 
201  template <typename OtherNumber>
202  explicit Vector(const std::initializer_list<OtherNumber> &v);
203 
204 #ifdef DEAL_II_WITH_PETSC
216  explicit Vector(const PETScWrappers::VectorBase &v);
217 #endif
218 
219 #ifdef DEAL_II_WITH_TRILINOS
235 #endif
236 
246  explicit Vector(const size_type n);
247 
252  template <typename InputIterator>
253  Vector(const InputIterator first, const InputIterator last);
254 
259  virtual ~Vector() override = default;
260 
274  void
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 
669  virtual void
671  ArrayView<Number> &elements) const override;
672 
700  template <typename ForwardIterator, typename OutputIterator>
701  void
702  extract_subvector_to(ForwardIterator indices_begin,
703  const ForwardIterator indices_end,
704  OutputIterator values_begin) const;
720 
728 
733  template <typename OtherNumber>
734  void
735  add(const std::vector<size_type> &indices,
736  const std::vector<OtherNumber> &values);
737 
742  template <typename OtherNumber>
743  void
744  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
745 
751  template <typename OtherNumber>
752  void
753  add(const size_type n_elements,
754  const size_type *indices,
755  const OtherNumber *values);
756 
763  void
764  add(const Number s);
765 
771  void
772  add(const Number a,
773  const Vector<Number> &V,
774  const Number b,
775  const Vector<Number> &W);
776 
782  void
783  add(const Number a, const Vector<Number> &V);
784 
790  void
791  sadd(const Number s, const Vector<Number> &V);
792 
798  void
799  sadd(const Number s, const Number a, const Vector<Number> &V);
800 
807  operator*=(const Number factor);
808 
815  operator/=(const Number factor);
816 
824  void
825  scale(const Vector<Number> &scaling_factors);
826 
832  template <typename Number2>
833  void
834  scale(const Vector<Number2> &scaling_factors);
835 
841  void
842  equ(const Number a, const Vector<Number> &u);
843 
847  template <typename Number2>
848  void
849  equ(const Number a, const Vector<Number2> &u);
850 
855  void
870  void
871  print(std::ostream &out,
872  const unsigned int precision = 3,
873  const bool scientific = true,
874  const bool across = true) const;
875 
881  void
882  block_write(std::ostream &out) const;
883 
895  void
896  block_read(std::istream &in);
897 
903  template <class Archive>
904  void
905  save(Archive &ar, const unsigned int version) const;
906 
912  template <class Archive>
913  void
914  load(Archive &ar, const unsigned int version);
915 
916 #ifdef DOXYGEN
922  template <class Archive>
923  void
924  serialize(Archive &archive, const unsigned int version);
925 #else
926  // This macro defines the serialize() method that is compatible with
927  // the templated save() and load() method that have been implemented.
928  BOOST_SERIALIZATION_SPLIT_MEMBER()
929 #endif
930 
945  bool
947 
963  IndexSet
965 
969  virtual size_type
970  size() const override;
971 
979  size_type
981 
987  bool
988  all_zero() const;
989 
999  bool
1001 
1006  std::size_t
1008 
1014  bool
1016 
1022  void
1026 private:
1031 
1037  void
1039 
1043  void
1044  do_reinit(const size_type new_size,
1045  const bool omit_zeroing_entries,
1046  const bool reset_partitioner);
1047 
1052  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
1054 
1055  // Make all other vector types friends.
1056  template <typename Number2>
1057  friend class Vector;
1058 };
1059 
1061 /*----------------------- Inline functions ----------------------------------*/
1062 
1063 
1064 #ifndef DOXYGEN
1065 
1066 
1067 //------------------------ declarations for explicit specializations
1068 template <>
1070 Vector<int>::lp_norm(const real_type) const;
1071 
1072 
1073 //------------------------ inline functions
1074 
1075 template <typename Number>
1076 inline Vector<Number>::Vector()
1077 {
1078  // virtual functions called in constructors and destructors never use the
1079  // override in a derived class
1080  // for clarity be explicit on which function is called
1082 }
1083 
1084 
1085 
1086 template <typename Number>
1087 template <typename OtherNumber>
1088 Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
1089  : Vector(v.begin(), v.end())
1090 {}
1091 
1092 
1093 
1094 template <typename Number>
1095 template <typename InputIterator>
1096 Vector<Number>::Vector(const InputIterator first, const InputIterator last)
1097 {
1098  // allocate memory. do not initialize it, as we will copy over to it in a
1099  // second
1100  reinit(std::distance(first, last), true);
1101  std::copy(first, last, begin());
1102 }
1103 
1104 
1105 
1106 template <typename Number>
1107 inline Vector<Number>::Vector(const size_type n)
1108 {
1109  // virtual functions called in constructors and destructors never use the
1110  // override in a derived class
1111  // for clarity be explicit on which function is called
1112  Vector<Number>::reinit(n, false);
1113 }
1114 
1115 
1116 
1117 template <typename Number>
1118 inline typename Vector<Number>::size_type
1119 Vector<Number>::size() const
1120 {
1121  return values.size();
1122 }
1123 
1124 
1125 
1126 template <typename Number>
1127 inline typename Vector<Number>::size_type
1129 {
1130  return values.size();
1131 }
1132 
1133 
1134 
1135 template <typename Number>
1136 inline bool
1138 {
1139  return true;
1140 }
1141 
1142 
1143 
1144 template <typename Number>
1145 inline typename Vector<Number>::pointer
1147 {
1148  return values.data();
1149 }
1150 
1151 
1152 
1153 template <typename Number>
1154 inline typename Vector<Number>::const_pointer
1155 Vector<Number>::data() const
1156 {
1157  return values.data();
1158 }
1159 
1160 
1161 
1162 template <typename Number>
1163 inline typename Vector<Number>::iterator
1165 {
1166  return values.begin();
1167 }
1168 
1169 
1170 
1171 template <typename Number>
1172 inline typename Vector<Number>::const_iterator
1173 Vector<Number>::begin() const
1174 {
1175  return values.begin();
1176 }
1177 
1178 
1179 
1180 template <typename Number>
1181 inline typename Vector<Number>::iterator
1183 {
1184  return values.end();
1185 }
1186 
1187 
1188 
1189 template <typename Number>
1190 inline typename Vector<Number>::const_iterator
1191 Vector<Number>::end() const
1192 {
1193  return values.end();
1194 }
1195 
1196 
1197 
1198 template <typename Number>
1199 inline Number
1201 {
1202  AssertIndexRange(i, size());
1203  return values[i];
1204 }
1205 
1206 
1207 
1208 template <typename Number>
1209 inline Number &
1211 {
1212  AssertIndexRange(i, size());
1213  return values[i];
1214 }
1215 
1216 
1217 
1218 template <typename Number>
1219 inline Number
1221 {
1222  return operator()(i);
1223 }
1224 
1225 
1226 
1227 template <typename Number>
1228 inline Number &
1230 {
1231  return operator()(i);
1232 }
1233 
1234 
1235 
1236 template <typename Number>
1237 template <typename OtherNumber>
1238 inline void
1239 Vector<Number>::extract_subvector_to(const std::vector<size_type> &indices,
1240  std::vector<OtherNumber> &values) const
1241 {
1242  for (size_type i = 0; i < indices.size(); ++i)
1243  values[i] = operator()(indices[i]);
1244 }
1245 
1246 
1247 
1248 template <typename Number>
1249 template <typename ForwardIterator, typename OutputIterator>
1250 inline void
1251 Vector<Number>::extract_subvector_to(ForwardIterator indices_begin,
1252  const ForwardIterator indices_end,
1253  OutputIterator values_begin) const
1254 {
1255  while (indices_begin != indices_end)
1256  {
1257  *values_begin = operator()(*indices_begin);
1258  indices_begin++;
1259  values_begin++;
1260  }
1261 }
1262 
1263 
1264 
1265 template <typename Number>
1266 inline Vector<Number> &
1267 Vector<Number>::operator/=(const Number factor)
1268 {
1269  AssertIsFinite(factor);
1270  Assert(factor != Number(0.), ExcZero());
1271 
1272  this->operator*=(Number(1.) / factor);
1273  return *this;
1274 }
1275 
1276 
1277 
1278 template <typename Number>
1279 template <typename OtherNumber>
1280 inline void
1281 Vector<Number>::add(const std::vector<size_type> &indices,
1282  const std::vector<OtherNumber> &values)
1283 {
1284  Assert(indices.size() == values.size(),
1285  ExcDimensionMismatch(indices.size(), values.size()));
1286  add(indices.size(), indices.data(), values.data());
1287 }
1288 
1289 
1290 
1291 template <typename Number>
1292 template <typename OtherNumber>
1293 inline void
1294 Vector<Number>::add(const std::vector<size_type> &indices,
1295  const Vector<OtherNumber> &values)
1296 {
1297  Assert(indices.size() == values.size(),
1298  ExcDimensionMismatch(indices.size(), values.size()));
1299  add(indices.size(), indices.data(), values.values.begin());
1300 }
1301 
1302 
1303 
1304 template <typename Number>
1305 template <typename OtherNumber>
1306 inline void
1307 Vector<Number>::add(const size_type n_indices,
1308  const size_type *indices,
1309  const OtherNumber *values)
1310 {
1311  for (size_type i = 0; i < n_indices; ++i)
1312  {
1313  AssertIndexRange(indices[i], size());
1314  Assert(
1316  ExcMessage(
1317  "The given value is not finite but either infinite or Not A Number (NaN)"));
1318 
1319  this->values[indices[i]] += values[i];
1320  }
1321 }
1322 
1323 
1324 
1325 template <typename Number>
1326 template <typename Number2>
1327 inline bool
1329 {
1330  return !(*this == v);
1331 }
1332 
1333 
1334 
1335 template <typename Number>
1336 inline void
1338 {}
1339 
1340 
1341 
1342 template <typename Number>
1343 inline bool
1345 {
1346  return false;
1347 }
1348 
1349 
1350 
1351 template <typename Number>
1352 inline void
1354 {}
1355 
1356 
1357 
1358 template <typename Number>
1359 inline void
1361 {}
1362 
1363 
1364 
1365 template <typename Number>
1366 template <typename Number2>
1367 inline void
1369  const bool omit_zeroing_entries)
1370 {
1371  // go to actual reinit functions in case we need to change something with
1372  // the vector, else there is nothing to be done
1373  if (!omit_zeroing_entries || size() != v.size())
1374  {
1375  do_reinit(v.size(), omit_zeroing_entries, false);
1377  }
1378 }
1379 
1380 
1381 
1382 // Moved from vector.templates.h as an inline function by Luca Heltai
1383 // on 2009/04/12 to prevent strange compiling errors, after making
1384 // swap virtual.
1385 template <typename Number>
1386 inline void
1388 {
1389  values.swap(v.values);
1391 }
1392 
1393 
1394 
1395 template <typename Number>
1396 template <class Archive>
1397 inline void
1398 Vector<Number>::save(Archive &ar, const unsigned int) const
1399 {
1400  // forward to serialization function in the base class.
1401  ar &static_cast<const Subscriptor &>(*this);
1402  ar &values;
1403 }
1404 
1405 
1406 
1407 template <typename Number>
1408 template <class Archive>
1409 inline void
1410 Vector<Number>::load(Archive &ar, const unsigned int)
1411 {
1412  // the load stuff again from the archive
1413  ar &static_cast<Subscriptor &>(*this);
1414  ar &values;
1416 }
1417 
1418 #endif
1419 
1420 
1434 template <typename Number>
1435 inline void
1437 {
1438  u.swap(v);
1439 }
1440 
1441 
1449 template <typename number>
1450 inline std::ostream &
1451 operator<<(std::ostream &out, const Vector<number> &v)
1452 {
1453  Assert(v.size() != 0, ExcEmptyObject());
1454  AssertThrow(out.fail() == false, ExcIO());
1455 
1456  for (typename Vector<number>::size_type i = 0; i < v.size() - 1; ++i)
1457  out << v(i) << ' ';
1458  out << v(v.size() - 1);
1459 
1460  AssertThrow(out.fail() == false, ExcIO());
1461 
1462  return out;
1463 }
1464 
1473 template <typename Number>
1474 struct is_serial_vector<Vector<Number>> : std::true_type
1475 {};
1476 
1477 
1479 
1480 #endif
OutputOperator< VectorType > & operator<<(OutputOperator< VectorType > &out, unsigned int step)
Definition: operator.h:165
types::global_dof_index size_type
Definition: read_vector.h:44
Definition: vector.h:110
typename numbers::NumberTraits< Number >::real_type real_type
Definition: vector.h:147
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:131
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:133
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:135
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:1053
void block_read(std::istream &in)
types::global_dof_index size_type
Definition: vector.h:136
Vector< Number > & operator=(const BlockVector< Number > &v)
Number operator[](const size_type i) const
Vector< Number > & operator=(const Vector< Number > &v)
virtual size_type size() const override
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()
friend class Vector
Definition: vector.h:1057
real_type l2_norm() const
value_type * pointer
Definition: vector.h:130
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)
virtual void extract_subvector_to(const ArrayView< const types::global_dof_index > &indices, ArrayView< Number > &elements) const override
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:1030
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:132
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:134
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:129
iterator begin()
Vector(const InputIterator first, const InputIterator last)
Vector(const std::initializer_list< OtherNumber > &v)
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:477
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:478
Point< 2 > first
Definition: grid_out.cc:4614
static ::ExceptionBase & ExcZero()
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
#define Assert(cond, exc)
Definition: exceptions.h:1631
#define AssertIsFinite(number)
Definition: exceptions.h:1915
static ::ExceptionBase & ExcEmptyObject()
#define AssertIndexRange(index, range)
Definition: exceptions.h:1888
static ::ExceptionBase & ExcIO()
static ::ExceptionBase & ExcMessage(std::string arg1)
#define AssertThrow(cond, exc)
Definition: exceptions.h:1732
void swap(Vector< Number > &u, Vector< Number > &v)
Definition: vector.h:1436
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:539
unsigned int global_dof_index
Definition: types.h:82