Reference documentation for deal.II version Git cb0bd54b52 2019-09-21 16:31:22 -0400
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
vector.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1999 - 2019 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 
22 #include <deal.II/base/aligned_vector.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/index_set.h>
25 #include <deal.II/base/logstream.h>
26 #include <deal.II/base/subscriptor.h>
27 
28 #include <deal.II/differentiation/ad/ad_number_traits.h>
29 
30 #include <deal.II/lac/vector_operation.h>
31 #include <deal.II/lac/vector_type_traits.h>
32 
33 #include <boost/serialization/split_member.hpp>
34 
35 #include <algorithm>
36 #include <initializer_list>
37 #include <iosfwd>
38 #include <iterator>
39 #include <vector>
40 
41 DEAL_II_NAMESPACE_OPEN
42 
43 
44 // Forward declarations
45 #ifndef DOXYGEN
46 # ifdef DEAL_II_WITH_PETSC
47 namespace PETScWrappers
48 {
49  class VectorBase;
50 }
51 # endif
52 
53 # ifdef DEAL_II_WITH_TRILINOS
54 namespace TrilinosWrappers
55 {
56  namespace MPI
57  {
58  class Vector;
59  }
60 } // namespace TrilinosWrappers
61 # endif
62 
63 template <typename number>
64 class LAPACKFullMatrix;
65 
66 template <typename>
67 class BlockVector;
68 
69 namespace parallel
70 {
71  namespace internal
72  {
73  class TBBPartitioner;
74  }
75 } // namespace parallel
76 #endif
77 
78 
111 template <typename Number>
112 class Vector : public Subscriptor
113 {
114 public:
115  // The assertion in vector.templates.h for whether or not a number is
116  // finite is not compatible for AD number types.
117  static_assert(
119  "The Vector class does not support auto-differentiable numbers.");
120 
125  using value_type = Number;
126  using pointer = value_type *;
127  using const_pointer = const value_type *;
128  using iterator = value_type *;
129  using const_iterator = const value_type *;
130  using reference = value_type &;
131  using const_reference = const value_type &;
132  using size_type = types::global_dof_index;
133 
144 
152  Vector();
153 
163  Vector(const Vector<Number> &v);
164 
169  Vector(Vector<Number> &&v) noexcept = default;
170 
179  template <typename OtherNumber>
180  explicit Vector(const Vector<OtherNumber> &v);
181 
197  template <typename OtherNumber>
198  explicit Vector(const std::initializer_list<OtherNumber> &v);
199 
200 #ifdef DEAL_II_WITH_PETSC
201 
212  explicit Vector(const PETScWrappers::VectorBase &v);
213 #endif
214 
215 #ifdef DEAL_II_WITH_TRILINOS
216 
230  explicit Vector(const TrilinosWrappers::MPI::Vector &v);
231 #endif
232 
242  explicit Vector(const size_type n);
243 
248  template <typename InputIterator>
249  Vector(const InputIterator first, const InputIterator last);
250 
255  virtual ~Vector() override = default;
256 
270  void
271  compress(::VectorOperation::values operation =
272  ::VectorOperation::unknown) const;
273 
289  virtual void
290  reinit(const size_type N, const bool omit_zeroing_entries = false);
291 
315  void
316  grow_or_shrink(const size_type N);
317 
325  void
326  apply_givens_rotation(const std::array<Number, 3> &csr,
327  const size_type i,
328  const size_type k);
329 
337  template <typename Number2>
338  void
339  reinit(const Vector<Number2> &V, const bool omit_zeroing_entries = false);
340 
356  virtual void
357  swap(Vector<Number> &v);
358 
369  Vector<Number> &
370  operator=(const Number s);
371 
377  Vector<Number> &
378  operator=(const Vector<Number> &v);
379 
385  Vector<Number> &
386  operator=(Vector<Number> &&v) noexcept = default;
387 
393  template <typename Number2>
394  Vector<Number> &
395  operator=(const Vector<Number2> &v);
396 
400  Vector<Number> &
401  operator=(const BlockVector<Number> &v);
402 
403 #ifdef DEAL_II_WITH_PETSC
404 
415  Vector<Number> &
416  operator=(const PETScWrappers::VectorBase &v);
417 #endif
418 
419 
420 #ifdef DEAL_II_WITH_TRILINOS
421 
436  Vector<Number> &
437  operator=(const TrilinosWrappers::MPI::Vector &v);
438 #endif
439 
445  template <typename Number2>
446  bool
447  operator==(const Vector<Number2> &v) const;
448 
454  template <typename Number2>
455  bool
456  operator!=(const Vector<Number2> &v) const;
457 
459 
460 
465 
479  template <typename Number2>
480  Number operator*(const Vector<Number2> &V) const;
481 
489  real_type
490  norm_sqr() const;
491 
499  Number
500  mean_value() const;
501 
509  real_type
510  l1_norm() const;
511 
520  real_type
521  l2_norm() const;
522 
531  real_type
532  lp_norm(const real_type p) const;
533 
537  real_type
538  linfty_norm() const;
539 
564  Number
565  add_and_dot(const Number a, const Vector<Number> &V, const Vector<Number> &W);
566 
568 
569 
574 
578  pointer
579  data();
580 
584  const_pointer
585  data() const;
586 
592  iterator
593  begin();
594 
598  const_iterator
599  begin() const;
600 
604  iterator
605  end();
606 
611  const_iterator
612  end() const;
613 
617  Number
618  operator()(const size_type i) const;
619 
623  Number &
624  operator()(const size_type i);
625 
631  Number operator[](const size_type i) const;
632 
638  Number &operator[](const size_type i);
639 
655  template <typename OtherNumber>
656  void
657  extract_subvector_to(const std::vector<size_type> &indices,
658  std::vector<OtherNumber> & values) const;
659 
687  template <typename ForwardIterator, typename OutputIterator>
688  void
689  extract_subvector_to(ForwardIterator indices_begin,
690  const ForwardIterator indices_end,
691  OutputIterator values_begin) const;
693 
694 
699 
705  Vector<Number> &
706  operator+=(const Vector<Number> &V);
707 
713  Vector<Number> &
714  operator-=(const Vector<Number> &V);
715 
720  template <typename OtherNumber>
721  void
722  add(const std::vector<size_type> & indices,
723  const std::vector<OtherNumber> &values);
724 
729  template <typename OtherNumber>
730  void
731  add(const std::vector<size_type> &indices, const Vector<OtherNumber> &values);
732 
738  template <typename OtherNumber>
739  void
740  add(const size_type n_elements,
741  const size_type * indices,
742  const OtherNumber *values);
743 
750  void
751  add(const Number s);
752 
758  void
759  add(const Number a,
760  const Vector<Number> &V,
761  const Number b,
762  const Vector<Number> &W);
763 
769  void
770  add(const Number a, const Vector<Number> &V);
771 
777  void
778  sadd(const Number s, const Vector<Number> &V);
779 
785  void
786  sadd(const Number s, const Number a, const Vector<Number> &V);
787 
793  Vector<Number> &
794  operator*=(const Number factor);
795 
801  Vector<Number> &
802  operator/=(const Number factor);
803 
811  void
812  scale(const Vector<Number> &scaling_factors);
813 
819  template <typename Number2>
820  void
821  scale(const Vector<Number2> &scaling_factors);
822 
828  void
829  equ(const Number a, const Vector<Number> &u);
830 
834  template <typename Number2>
835  void
836  equ(const Number a, const Vector<Number2> &u);
837 
850  DEAL_II_DEPRECATED
851  void
852  ratio(const Vector<Number> &a, const Vector<Number> &b);
853 
858  void
859  update_ghost_values() const;
861 
862 
873  DEAL_II_DEPRECATED
874  void
875  print(const char *format = nullptr) const;
876 
883  void
884  print(std::ostream & out,
885  const unsigned int precision = 3,
886  const bool scientific = true,
887  const bool across = true) const;
888 
897  DEAL_II_DEPRECATED
898  void
899  print(LogStream & out,
900  const unsigned int width = 6,
901  const bool across = true) const;
902 
908  void
909  block_write(std::ostream &out) const;
910 
922  void
923  block_read(std::istream &in);
924 
929  template <class Archive>
930  void
931  save(Archive &ar, const unsigned int version) const;
932 
937  template <class Archive>
938  void
939  load(Archive &ar, const unsigned int version);
940 
941  BOOST_SERIALIZATION_SPLIT_MEMBER()
942 
943 
951 
957  bool
958  in_local_range(const size_type global_index) const;
959 
975  IndexSet
976  locally_owned_elements() const;
977 
981  size_type
982  size() const;
983 
989  bool
990  all_zero() const;
991 
1001  bool
1002  is_non_negative() const;
1003 
1008  std::size_t
1009  memory_consumption() const;
1011 
1012 private:
1016  AlignedVector<Number> values;
1017 
1023  void
1024  maybe_reset_thread_partitioner();
1025 
1029  void
1030  do_reinit(const size_type new_size,
1031  const bool omit_zeroing_entries,
1032  const bool reset_partitioner);
1033 
1038  mutable std::shared_ptr<parallel::internal::TBBPartitioner>
1039  thread_loop_partitioner;
1040 
1041  // Make all other vector types friends.
1042  template <typename Number2>
1043  friend class Vector;
1044 };
1045 
1047 /*----------------------- Inline functions ----------------------------------*/
1048 
1049 
1050 #ifndef DOXYGEN
1051 
1052 
1053 //------------------------ declarations for explicit specializations
1054 template <>
1056 Vector<int>::lp_norm(const real_type) const;
1057 
1058 
1059 //------------------------ inline functions
1060 
1061 template <typename Number>
1062 inline Vector<Number>::Vector()
1063 {
1064  // virtual functions called in constructors and destructors never use the
1065  // override in a derived class
1066  // for clarity be explicit on which function is called
1068 }
1069 
1070 
1071 
1072 template <typename Number>
1073 template <typename OtherNumber>
1074 Vector<Number>::Vector(const std::initializer_list<OtherNumber> &v)
1075  : Vector(v.begin(), v.end())
1076 {}
1077 
1078 
1079 
1080 template <typename Number>
1081 template <typename InputIterator>
1082 Vector<Number>::Vector(const InputIterator first, const InputIterator last)
1083 {
1084  // allocate memory. do not initialize it, as we will copy over to it in a
1085  // second
1086  reinit(std::distance(first, last), true);
1087  std::copy(first, last, begin());
1088 }
1089 
1090 
1091 
1092 template <typename Number>
1093 inline Vector<Number>::Vector(const size_type n)
1094 {
1095  // virtual functions called in constructors and destructors never use the
1096  // override in a derived class
1097  // for clarity be explicit on which function is called
1098  Vector<Number>::reinit(n, false);
1099 }
1100 
1101 
1102 
1103 template <typename Number>
1104 inline typename Vector<Number>::size_type
1105 Vector<Number>::size() const
1106 {
1107  return values.size();
1108 }
1109 
1110 
1111 template <typename Number>
1112 inline bool
1113 Vector<Number>::in_local_range(const size_type) const
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
1176 Vector<Number>::operator()(const size_type i) const
1177 {
1178  Assert(i < size(), ExcIndexRange(i, 0, size()));
1179  return values[i];
1180 }
1181 
1182 
1183 
1184 template <typename Number>
1185 inline Number &
1186 Vector<Number>::operator()(const size_type i)
1187 {
1188  Assert(i < size(), ExcIndexRangeType<size_type>(i, 0, 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  Assert(indices[i] < size(), ExcIndexRange(indices[i], 0, 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 
1315 template <typename Number>
1316 inline void
1318 {}
1319 
1320 
1321 
1322 // Moved from vector.templates.h as an inline function by Luca Heltai
1323 // on 2009/04/12 to prevent strange compiling errors, after making
1324 // swap virtual.
1325 template <typename Number>
1326 inline void
1327 Vector<Number>::swap(Vector<Number> &v)
1328 {
1329  values.swap(v.values);
1330  std::swap(thread_loop_partitioner, v.thread_loop_partitioner);
1331 }
1332 
1333 
1334 
1335 template <typename Number>
1336 template <class Archive>
1337 inline void
1338 Vector<Number>::save(Archive &ar, const unsigned int) const
1339 {
1340  // forward to serialization function in the base class.
1341  ar &static_cast<const Subscriptor &>(*this);
1342  ar &values;
1343 }
1344 
1345 
1346 
1347 template <typename Number>
1348 template <class Archive>
1349 inline void
1350 Vector<Number>::load(Archive &ar, const unsigned int)
1351 {
1352  // the load stuff again from the archive
1353  ar &static_cast<Subscriptor &>(*this);
1354  ar &values;
1356 }
1357 
1358 #endif
1359 
1360 
1374 template <typename Number>
1375 inline void
1376 swap(Vector<Number> &u, Vector<Number> &v)
1377 {
1378  u.swap(v);
1379 }
1380 
1381 
1385 template <typename number>
1386 inline std::ostream &
1387 operator<<(std::ostream &os, const Vector<number> &v)
1388 {
1389  v.print(os);
1390  return os;
1391 }
1392 
1396 template <typename number>
1397 inline LogStream &
1398 operator<<(LogStream &os, const Vector<number> &v)
1399 {
1400  v.print(os);
1401  return os;
1402 }
1403 
1412 template <typename Number>
1413 struct is_serial_vector<Vector<Number>> : std::true_type
1414 {};
1415 
1416 
1417 DEAL_II_NAMESPACE_CLOSE
1418 
1419 #endif
void update_ghost_values() const
Number operator[](const size_type i) const
bool operator!=(const Vector< Number2 > &v) const
void load(Archive &ar, const unsigned int version)
DEAL_II_CONSTEXPR SymmetricTensor< rank_, dim, Number > operator*(const SymmetricTensor< rank_, dim, Number > &t, const Number &factor)
void extract_subvector_to(const std::vector< size_type > &indices, std::vector< OtherNumber > &values) const
Number operator()(const size_type i) const
typename numbers::NumberTraits< typename VectorType::value_type >::real_type real_type
Definition: vector.h:143
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)
STL namespace.
pointer data()
static ::ExceptionBase & ExcIndexRange(int arg1, int arg2, int arg3)
iterator end()
LinearAlgebra::distributed::Vector< Number > Vector
bool is_finite(const double x)
Definition: numbers.h:555
__global__ void scale(Number *val, const Number *V_val, const size_type N)
void add(const std::vector< size_type > &indices, const std::vector< OtherNumber > &values)
static ::ExceptionBase & ExcMessage(std::string arg1)
typename VectorType::value_type value_type
Definition: vector.h:125
bool in_local_range(const size_type global_index) const
void maybe_reset_thread_partitioner()
#define Assert(cond, exc)
Definition: exceptions.h:1407
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
real_type lp_norm(const real_type p) const
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)
void swap(Vector< Number > &u, Vector< Number > &v)
Definition: vector.h:1376
unsigned int global_dof_index
Definition: types.h:89
virtual void swap(Vector< Number > &v)
Vector< Number > & operator/=(const Number factor)
void save(Archive &ar, const unsigned int version) const
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:1016
std::shared_ptr< parallel::internal::TBBPartitioner > thread_loop_partitioner
Definition: vector.h:1039
static ::ExceptionBase & ExcZero()
#define AssertIsFinite(number)
Definition: exceptions.h:1669