| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2016 - 2025 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_la_parallel_block_vector_h |
| 16 |
#define dealii_la_parallel_block_vector_h |
| 17 |
|
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/base/exceptions.h> |
| 22 |
|
| 23 |
#include <deal.II/lac/block_indices.h> |
| 24 |
#include <deal.II/lac/block_vector_base.h> |
| 25 |
#include <deal.II/lac/la_parallel_vector.h> |
| 26 |
#include <deal.II/lac/vector_operation.h> |
| 27 |
#include <deal.II/lac/vector_type_traits.h> |
| 28 |
|
| 29 |
#include <cstdio> |
| 30 |
#include <vector> |
| 31 |
|
| 32 |
DEAL_II_NAMESPACE_OPEN |
| 33 |
|
| 34 |
|
| 35 |
// Forward declarations |
| 36 |
#ifndef DOXYGEN |
| 37 |
# ifdef DEAL_II_WITH_PETSC |
| 38 |
namespace PETScWrappers |
| 39 |
{ |
| 40 |
namespace MPI |
| 41 |
{ |
| 42 |
class BlockVector; |
| 43 |
} |
| 44 |
} // namespace PETScWrappers |
| 45 |
# endif |
| 46 |
|
| 47 |
# ifdef DEAL_II_WITH_TRILINOS |
| 48 |
namespace TrilinosWrappers |
| 49 |
{ |
| 50 |
namespace MPI |
| 51 |
{ |
| 52 |
class BlockVector; |
| 53 |
} |
| 54 |
} // namespace TrilinosWrappers |
| 55 |
# endif |
| 56 |
#endif |
| 57 |
|
| 58 |
namespace LinearAlgebra |
| 59 |
{ |
| 60 |
namespace distributed |
| 61 |
{ |
| 62 |
/** |
| 63 |
* @addtogroup Vectors |
| 64 |
* @{ |
| 65 |
*/ |
| 66 |
|
| 67 |
|
| 68 |
/** |
| 69 |
* An implementation of block vectors based on distributed deal.II |
| 70 |
* vectors. While the base class provides for most of the interface, this |
| 71 |
* class handles the actual allocation of vectors and provides functions |
| 72 |
* that are specific to the underlying vector type. |
| 73 |
* |
| 74 |
* @note Instantiations for this template are provided for <tt>@<float@> |
| 75 |
* and @<double@></tt>; others can be generated in application programs |
| 76 |
* (see the section on |
| 77 |
* @ref Instantiations |
| 78 |
* in the manual). |
| 79 |
* |
| 80 |
* @see |
| 81 |
* @ref GlossBlockLA "Block (linear algebra)" |
| 82 |
*/ |
| 83 |
template <typename Number, typename MemorySpace = MemorySpace::Host> |
| 84 |
class BlockVector : public BlockVectorBase<Vector<Number, MemorySpace>> |
| 85 |
{ |
| 86 |
public: |
| 87 |
/** |
| 88 |
* The chunks size to split communication in update_ghost_values() |
| 89 |
* and compress() calls. |
| 90 |
* |
| 91 |
* Most common MPI implementations will get slow when too many |
| 92 |
* messages/requests are outstanding. Even when messages are small, |
| 93 |
* say 1 kB only, we should collect enough data with @p communication_block_size |
| 94 |
* to cover typical infiniband latencies which are around a few |
| 95 |
* microseconds. Sending 20 kB at a throughput of 5 GB/s takes 4 |
| 96 |
* microseconds, so we should arrive at the bandwidth dominated regime |
| 97 |
* then which is good enough. |
| 98 |
*/ |
| 99 |
static constexpr unsigned int communication_block_size = 20; |
| 100 |
|
| 101 |
/** |
| 102 |
* Typedef the base class for simpler access to its own alias. |
| 103 |
*/ |
| 104 |
using BaseClass = BlockVectorBase<Vector<Number, MemorySpace>>; |
| 105 |
|
| 106 |
/** |
| 107 |
* Typedef the type of the underlying vector. |
| 108 |
*/ |
| 109 |
using BlockType = typename BaseClass::BlockType; |
| 110 |
|
| 111 |
/** |
| 112 |
* Import the alias from the base class. |
| 113 |
*/ |
| 114 |
using value_type = typename BaseClass::value_type; |
| 115 |
using real_type = typename BaseClass::real_type; |
| 116 |
using pointer = typename BaseClass::pointer; |
| 117 |
using const_pointer = typename BaseClass::const_pointer; |
| 118 |
using reference = typename BaseClass::reference; |
| 119 |
using const_reference = typename BaseClass::const_reference; |
| 120 |
using size_type = typename BaseClass::size_type; |
| 121 |
using iterator = typename BaseClass::iterator; |
| 122 |
using const_iterator = typename BaseClass::const_iterator; |
| 123 |
|
| 124 |
/** |
| 125 |
* @name 1: Basic operations |
| 126 |
*/ |
| 127 |
/** @{ */ |
| 128 |
|
| 129 |
/** |
| 130 |
* Constructor. There are three ways to use this constructor. First, |
| 131 |
* without any arguments, it generates an object with no blocks. Given |
| 132 |
* one argument, it initializes <tt>num_blocks</tt> blocks, but these |
| 133 |
* blocks have size zero. The third variant finally initializes all |
| 134 |
* blocks to the same size <tt>block_size</tt>. |
| 135 |
* |
| 136 |
* Confer the other constructor further down if you intend to use blocks |
| 137 |
* of different sizes. |
| 138 |
*/ |
| 139 |
explicit BlockVector(const size_type num_blocks = 0, |
| 140 |
const size_type block_size = 0); |
| 141 |
|
| 142 |
/** |
| 143 |
* Copy-Constructor. Dimension set to that of V, all components are |
| 144 |
* copied from V |
| 145 |
*/ |
| 146 |
BlockVector(const BlockVector<Number, MemorySpace> &V); |
| 147 |
|
| 148 |
/** |
| 149 |
* Copy constructor taking a BlockVector of another data type. This will |
| 150 |
* fail if there is no conversion path from <tt>OtherNumber</tt> to |
| 151 |
* <tt>Number</tt>. Note that you may lose accuracy when copying to a |
| 152 |
* BlockVector with data elements with less accuracy. |
| 153 |
*/ |
| 154 |
template <typename OtherNumber> |
| 155 |
explicit BlockVector(const BlockVector<OtherNumber, MemorySpace> &v); |
| 156 |
|
| 157 |
/** |
| 158 |
* Constructor. Set the number of blocks to <tt>block_sizes.size()</tt> |
| 159 |
* and initialize each block with <tt>block_sizes[i]</tt> zero elements. |
| 160 |
*/ |
| 161 |
BlockVector(const std::vector<size_type> &block_sizes); |
| 162 |
|
| 163 |
/** |
| 164 |
* Construct a block vector with an IndexSet for the local range and |
| 165 |
* ghost entries for each block. |
| 166 |
*/ |
| 167 |
BlockVector(const std::vector<IndexSet> &local_ranges, |
| 168 |
const std::vector<IndexSet> &ghost_indices, |
| 169 |
const MPI_Comm communicator); |
| 170 |
|
| 171 |
/** |
| 172 |
* Same as above but the ghost indices are assumed to be empty. |
| 173 |
*/ |
| 174 |
BlockVector(const std::vector<IndexSet> &local_ranges, |
| 175 |
const MPI_Comm communicator); |
| 176 |
|
| 177 |
/** |
| 178 |
* Construct a block vector with a Utilities::MPI::Partitioner for each |
| 179 |
* block. |
| 180 |
* |
| 181 |
* The optional argument @p comm_sm, which consists of processes on |
| 182 |
* the same shared-memory domain, allows users have read-only access to |
| 183 |
* both locally-owned and ghost values of processes combined in the |
| 184 |
* shared-memory communicator. See the general documentation of the |
| 185 |
* LinearAlgebra::distributed::Vector class for more information about |
| 186 |
* this argument. |
| 187 |
*/ |
| 188 |
BlockVector( |
| 189 |
const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>> |
| 190 |
&partitioners, |
| 191 |
const MPI_Comm &comm_sm = MPI_COMM_SELF); |
| 192 |
|
| 193 |
/** |
| 194 |
* Destructor. |
| 195 |
* |
| 196 |
* @note We need to explicitly provide a destructor, otherwise the |
| 197 |
* linker may think it is unused and discards it, although required |
| 198 |
* in a different section. The Intel compiler is prone to this |
| 199 |
* behavior. |
| 200 |
*/ |
| 201 |
~BlockVector() = default; |
| 202 |
|
| 203 |
/** |
| 204 |
* Copy operator: fill all components of the vector with the given |
| 205 |
* scalar value. |
| 206 |
*/ |
| 207 |
BlockVector & |
| 208 |
operator=(const value_type s); |
| 209 |
|
| 210 |
/** |
| 211 |
* Copy operator for arguments of the same type. Resize the present vector |
| 212 |
* if necessary to the correct number of blocks, then copy the individual |
| 213 |
* blocks from `v` using the copy-assignment operator of the class that |
| 214 |
* represents the individual blocks. |
| 215 |
* |
| 216 |
* Copying the vectors that make up individual blocks can have complex |
| 217 |
* semantics in parallel vector classes. See the information provided |
| 218 |
* by the class used to represent the individual blocks. |
| 219 |
*/ |
| 220 |
BlockVector & |
| 221 |
operator=(const BlockVector &V); |
| 222 |
|
| 223 |
/** |
| 224 |
* Copy operator for arguments of different type. Resize the present |
| 225 |
* vector if necessary to the correct number of blocks, then copy the |
| 226 |
* individual blocks from `v` using the copy-assignment operator of the |
| 227 |
* class that represents the individual blocks. |
| 228 |
* |
| 229 |
* Copying the vectors that make up individual blocks can have complex |
| 230 |
* semantics in parallel vector classes. See the information provided |
| 231 |
* by the class used to represent the individual blocks. |
| 232 |
*/ |
| 233 |
template <class Number2> |
| 234 |
BlockVector & |
| 235 |
operator=(const BlockVector<Number2, MemorySpace> &V); |
| 236 |
|
| 237 |
/** |
| 238 |
* Copy a regular vector into a block vector. |
| 239 |
*/ |
| 240 |
BlockVector & |
| 241 |
operator=(const Vector<Number, MemorySpace> &V); |
| 242 |
|
| 243 |
#ifdef DEAL_II_WITH_PETSC |
| 244 |
/** |
| 245 |
* Copy the content of a PETSc vector into the calling vector. This |
| 246 |
* function assumes that the vectors layouts have already been |
| 247 |
* initialized to match. |
| 248 |
* |
| 249 |
* This operator is only available if deal.II was configured with PETSc. |
| 250 |
*/ |
| 251 |
BlockVector<Number, MemorySpace> & |
| 252 |
operator=(const PETScWrappers::MPI::BlockVector &petsc_vec); |
| 253 |
#endif |
| 254 |
|
| 255 |
#ifdef DEAL_II_WITH_TRILINOS |
| 256 |
/** |
| 257 |
* Copy the content of a Trilinos vector into the calling vector. This |
| 258 |
* function assumes that the vectors layouts have already been |
| 259 |
* initialized to match. |
| 260 |
* |
| 261 |
* This operator is only available if deal.II was configured with |
| 262 |
* Trilinos. |
| 263 |
*/ |
| 264 |
BlockVector<Number, MemorySpace> & |
| 265 |
operator=(const TrilinosWrappers::MPI::BlockVector &trilinos_vec); |
| 266 |
#endif |
| 267 |
|
| 268 |
/** |
| 269 |
* Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of |
| 270 |
* size <tt>block_size</tt> each. |
| 271 |
* |
| 272 |
* If the second argument is left at its default value, then the block |
| 273 |
* vector allocates the specified number of blocks but leaves them at |
| 274 |
* zero size. You then need to later reinitialize the individual blocks, |
| 275 |
* and call collect_sizes() to update the block system's knowledge of |
| 276 |
* its individual block's sizes. |
| 277 |
* |
| 278 |
* If <tt>omit_zeroing_entries==false</tt>, the vector is filled with |
| 279 |
* zeros. |
| 280 |
*/ |
| 281 |
void |
| 282 |
reinit(const size_type num_blocks, |
| 283 |
const size_type block_size = 0, |
| 284 |
const bool omit_zeroing_entries = false); |
| 285 |
|
| 286 |
/** |
| 287 |
* Reinitialize the BlockVector such that it contains |
| 288 |
* <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to |
| 289 |
* dimension <tt>block_sizes[i]</tt>. |
| 290 |
* |
| 291 |
* If the number of blocks is the same as before this function was |
| 292 |
* called, all vectors remain the same and reinit() is called for each |
| 293 |
* vector. |
| 294 |
* |
| 295 |
* If <tt>omit_zeroing_entries==false</tt>, the vector is filled with |
| 296 |
* zeros. |
| 297 |
* |
| 298 |
* Note that you must call this (or the other reinit() functions) |
| 299 |
* function, rather than calling the reinit() functions of an individual |
| 300 |
* block, to allow the block vector to update its caches of vector |
| 301 |
* sizes. If you call reinit() on one of the blocks, then subsequent |
| 302 |
* actions on this object may yield unpredictable results since they may |
| 303 |
* be routed to the wrong block. |
| 304 |
*/ |
| 305 |
void |
| 306 |
reinit(const std::vector<size_type> &block_sizes, |
| 307 |
const bool omit_zeroing_entries = false); |
| 308 |
|
| 309 |
/** |
| 310 |
* Change the dimension to that of the vector <tt>V</tt>. The same |
| 311 |
* applies as for the other reinit() function. |
| 312 |
* |
| 313 |
* The elements of <tt>V</tt> are not copied, i.e. this function is the |
| 314 |
* same as calling <tt>reinit (V.size(), omit_zeroing_entries)</tt>. |
| 315 |
* |
| 316 |
* Note that you must call this (or the other reinit() functions) |
| 317 |
* function, rather than calling the reinit() functions of an individual |
| 318 |
* block, to allow the block vector to update its caches of vector |
| 319 |
* sizes. If you call reinit() of one of the blocks, then subsequent |
| 320 |
* actions of this object may yield unpredictable results since they may |
| 321 |
* be routed to the wrong block. |
| 322 |
*/ |
| 323 |
template <typename Number2> |
| 324 |
void |
| 325 |
reinit(const BlockVector<Number2, MemorySpace> &V, |
| 326 |
const bool omit_zeroing_entries = false); |
| 327 |
|
| 328 |
/** |
| 329 |
* Initialize the block vector. For each block, the local range is |
| 330 |
* specified by the corresponding entry in @p local_ranges (note that this |
| 331 |
* must be a contiguous interval, multiple intervals are not possible). |
| 332 |
* The parameter @p ghost_indices specifies ghost indices for each block, |
| 333 |
* i.e., indices which one might need to read data from or accumulate data |
| 334 |
* from. It is allowed that the set of ghost indices also contains the |
| 335 |
* local range, but it does not need to. |
| 336 |
* |
| 337 |
* This function involves global communication, so it should only be |
| 338 |
* called once for a given layout. Use the @p reinit function with |
| 339 |
* BlockVector<Number, MemorySpace> argument to create additional vectors |
| 340 |
* with the same parallel layout. |
| 341 |
* |
| 342 |
* @see |
| 343 |
* @ref GlossGhostedVector "vectors with ghost elements" |
| 344 |
*/ |
| 345 |
void |
| 346 |
reinit(const std::vector<IndexSet> &local_ranges, |
| 347 |
const std::vector<IndexSet> &ghost_indices, |
| 348 |
const MPI_Comm communicator); |
| 349 |
|
| 350 |
/** |
| 351 |
* Same as above, but without ghost entries. |
| 352 |
*/ |
| 353 |
void |
| 354 |
reinit(const std::vector<IndexSet> &local_ranges, |
| 355 |
const MPI_Comm communicator); |
| 356 |
|
| 357 |
/** |
| 358 |
* Initialize each block with the corresponding parallel partitioning |
| 359 |
* in @p partitioners. The input arguments are shared pointers, which |
| 360 |
* store the partitioner data only once and can be shared between several |
| 361 |
* vectors with the same layout. |
| 362 |
* |
| 363 |
* The optional argument @p comm_sm, which consists of processes on |
| 364 |
* the same shared-memory domain, allows users have read-only access to |
| 365 |
* both locally-owned and ghost values of processes combined in the |
| 366 |
* shared-memory communicator. See the general documentation of the |
| 367 |
* LinearAlgebra::distributed::Vector class for more information about |
| 368 |
* this argument. |
| 369 |
*/ |
| 370 |
void |
| 371 |
reinit( |
| 372 |
const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>> |
| 373 |
&partitioners, |
| 374 |
const MPI_Comm &comm_sm = MPI_COMM_SELF); |
| 375 |
|
| 376 |
/** |
| 377 |
* This function exists purely for reasons of compatibility with the |
| 378 |
* PETScWrappers::MPI::Vector and TrilinosWrappers::MPI::Vector classes. |
| 379 |
* |
| 380 |
* It calls the function above, and ignores the parameter @p make_ghosted. |
| 381 |
*/ |
| 382 |
void |
| 383 |
reinit( |
| 384 |
const std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>> |
| 385 |
&partitioners, |
| 386 |
const bool make_ghosted, |
| 387 |
const MPI_Comm &comm_sm = MPI_COMM_SELF); |
| 388 |
|
| 389 |
/** |
| 390 |
* This function copies the data that has accumulated in the data buffer |
| 391 |
* for ghost indices to the owning processor. For the meaning of the |
| 392 |
* argument @p operation, see the entry on |
| 393 |
* @ref GlossCompress "Compressing distributed vectors and matrices" |
| 394 |
* in the glossary. |
| 395 |
* |
| 396 |
* There are two variants for this function. If called with argument @p |
| 397 |
* VectorOperation::add adds all the data accumulated in ghost elements |
| 398 |
* to the respective elements on the owning processor and clears the |
| 399 |
* ghost array afterwards. If called with argument @p |
| 400 |
* VectorOperation::insert, a set operation is performed. Since setting |
| 401 |
* elements in a vector with ghost elements is ambiguous (as one can set |
| 402 |
* both the element on the ghost site as well as the owning site), this |
| 403 |
* operation makes the assumption that all data is set correctly on the |
| 404 |
* owning processor. Upon call of compress(VectorOperation::insert), all |
| 405 |
* ghost entries are therefore simply zeroed out (using |
| 406 |
* zero_ghost_values()). In debug mode, a check is performed that makes |
| 407 |
* sure that the data set is actually consistent between processors, |
| 408 |
* i.e., whenever a non-zero ghost element is found, it is compared to |
| 409 |
* the value on the owning processor and an exception is thrown if these |
| 410 |
* elements do not agree. |
| 411 |
*/ |
| 412 |
void |
| 413 |
compress(VectorOperation::values operation); |
| 414 |
|
| 415 |
/** |
| 416 |
* Fills the data field for ghost indices with the values stored in the |
| 417 |
* respective positions of the owning processor. This function is needed |
| 418 |
* before reading from ghosts. The function is @p const even though |
| 419 |
* ghost data is changed. This is needed to allow functions with a @p |
| 420 |
* const vector to perform the data exchange without creating |
| 421 |
* temporaries. |
| 422 |
*/ |
| 423 |
void |
| 424 |
update_ghost_values() const; |
| 425 |
|
| 426 |
/** |
| 427 |
* This method zeros the entries on ghost dofs, but does not touch |
| 428 |
* locally owned DoFs. |
| 429 |
* |
| 430 |
* After calling this method, read access to ghost elements of the |
| 431 |
* vector is forbidden and an exception is thrown. Only write access to |
| 432 |
* ghost elements is allowed in this state. |
| 433 |
*/ |
| 434 |
void |
| 435 |
zero_out_ghost_values() const; |
| 436 |
|
| 437 |
/** |
| 438 |
* Return if any of the blocks in this vector contains ghost elements. |
| 439 |
*/ |
| 440 |
bool |
| 441 |
has_ghost_elements() const; |
| 442 |
|
| 443 |
/** |
| 444 |
* Change the ghost state of all blocks in this vector to @p ghosted. |
| 445 |
*/ |
| 446 |
void |
| 447 |
set_ghost_state(const bool ghosted) const; |
| 448 |
|
| 449 |
/** |
| 450 |
* This method copies the data in the locally owned range from another |
| 451 |
* distributed vector @p src into the calling vector. As opposed to |
| 452 |
* operator= that also includes ghost entries, this operation ignores |
| 453 |
* the ghost range. The only prerequisite is that the local range on the |
| 454 |
* calling vector and the given vector @p src are the same on all |
| 455 |
* processors. It is explicitly allowed that the two vectors have |
| 456 |
* different ghost elements that might or might not be related to each |
| 457 |
* other. |
| 458 |
* |
| 459 |
* Since no data exchange is performed, make sure that neither @p src |
| 460 |
* nor the calling vector have pending communications in order to obtain |
| 461 |
* correct results. |
| 462 |
*/ |
| 463 |
template <typename Number2> |
| 464 |
void |
| 465 |
copy_locally_owned_data_from( |
| 466 |
const BlockVector<Number2, MemorySpace> &src); |
| 467 |
|
| 468 |
/** |
| 469 |
* This is a collective add operation that adds a whole set of values |
| 470 |
* stored in @p values to the vector components specified by @p indices. |
| 471 |
*/ |
| 472 |
template <typename OtherNumber> |
| 473 |
void |
| 474 |
add(const std::vector<size_type> &indices, |
| 475 |
const ::dealii::Vector<OtherNumber> &values); |
| 476 |
|
| 477 |
/** |
| 478 |
* Scaling and simple vector addition, i.e. <tt>*this = |
| 479 |
* s*(*this)+V</tt>. |
| 480 |
*/ |
| 481 |
void |
| 482 |
sadd(const Number s, const BlockVector<Number, MemorySpace> &V); |
| 483 |
|
| 484 |
/** |
| 485 |
* Return whether the vector contains only elements with value zero. |
| 486 |
* This function is mainly for internal consistency checks and should |
| 487 |
* seldom be used when not in debug mode since it uses quite some time. |
| 488 |
*/ |
| 489 |
bool |
| 490 |
all_zero() const; |
| 491 |
|
| 492 |
/** |
| 493 |
* Compute the mean value of all the entries in the vector. |
| 494 |
*/ |
| 495 |
Number |
| 496 |
mean_value() const; |
| 497 |
|
| 498 |
/** |
| 499 |
* $l_p$-norm of the vector. The pth root of the sum of the pth powers |
| 500 |
* of the absolute values of the elements. |
| 501 |
*/ |
| 502 |
real_type |
| 503 |
lp_norm(const real_type p) const; |
| 504 |
|
| 505 |
/** |
| 506 |
* Swap the contents of this vector and the other vector <tt>v</tt>. One |
| 507 |
* could do this operation with a temporary variable and copying over |
| 508 |
* the data elements, but this function is significantly more efficient |
| 509 |
* since it only swaps the pointers to the data of the two vectors and |
| 510 |
* therefore does not need to allocate temporary storage and move data |
| 511 |
* around. |
| 512 |
* |
| 513 |
* Limitation: right now this function only works if both vectors have |
| 514 |
* the same number of blocks. If needed, the numbers of blocks should be |
| 515 |
* exchanged, too. |
| 516 |
* |
| 517 |
* This function is analogous to the swap() function of all C++ |
| 518 |
* standard containers. Also, there is a global function swap(u,v) that |
| 519 |
* simply calls <tt>u.swap(v)</tt>, again in analogy to standard |
| 520 |
* functions. |
| 521 |
*/ |
| 522 |
void |
| 523 |
swap(BlockVector<Number, MemorySpace> &v) noexcept; |
| 524 |
/** @} */ |
| 525 |
|
| 526 |
/** |
| 527 |
* @name 2: Vector space operations |
| 528 |
*/ |
| 529 |
/** @{ */ |
| 530 |
|
| 531 |
/** |
| 532 |
* Multiply the entire vector by a fixed factor. |
| 533 |
*/ |
| 534 |
BlockVector<Number, MemorySpace> & |
| 535 |
operator*=(const Number factor); |
| 536 |
|
| 537 |
/** |
| 538 |
* Divide the entire vector by a fixed factor. |
| 539 |
*/ |
| 540 |
BlockVector<Number, MemorySpace> & |
| 541 |
operator/=(const Number factor); |
| 542 |
|
| 543 |
/** |
| 544 |
* Add the vector @p V to the present one. |
| 545 |
*/ |
| 546 |
BlockVector<Number, MemorySpace> & |
| 547 |
operator+=(const BlockVector<Number, MemorySpace> &V); |
| 548 |
|
| 549 |
/** |
| 550 |
* Subtract the vector @p V from the present one. |
| 551 |
*/ |
| 552 |
BlockVector<Number, MemorySpace> & |
| 553 |
operator-=(const BlockVector<Number, MemorySpace> &V); |
| 554 |
|
| 555 |
/** |
| 556 |
* Import all the elements present in the vector's IndexSet from the input |
| 557 |
* vector @p V. VectorOperation::values @p operation is used to decide if |
| 558 |
* the elements in @p V should be added to the current vector or replace the |
| 559 |
* current elements. The last parameter can be used if the same |
| 560 |
* communication pattern is used multiple times. This can be used to |
| 561 |
* improve performance. |
| 562 |
*/ |
| 563 |
void |
| 564 |
import_elements( |
| 565 |
const LinearAlgebra::ReadWriteVector<Number> &V, |
| 566 |
const VectorOperation::values operation, |
| 567 |
const std::shared_ptr<const Utilities::MPI::CommunicationPatternBase> |
| 568 |
&communication_pattern = {}); |
| 569 |
|
| 570 |
/** |
| 571 |
* @deprecated Use import_elements() instead. |
| 572 |
*/ |
| 573 |
DEAL_II_DEPRECATED void |
| 574 |
import(const LinearAlgebra::ReadWriteVector<Number> &V, |
| 575 |
VectorOperation::values operation, |
| 576 |
std::shared_ptr<const Utilities::MPI::CommunicationPatternBase> |
| 577 |
communication_pattern = {}) |
| 578 |
{ |
| 579 |
import_elements(V, operation, communication_pattern); |
| 580 |
} |
| 581 |
|
| 582 |
/** |
| 583 |
* Return the scalar product of two vectors. |
| 584 |
*/ |
| 585 |
Number |
| 586 |
operator*(const BlockVector<Number, MemorySpace> &V) const; |
| 587 |
|
| 588 |
/** |
| 589 |
* Calculate the scalar product between each block of this vector and @p V |
| 590 |
* and store the result in a full matrix @p matrix. This function |
| 591 |
* computes the result by forming $A_{ij}=U_i \cdot V_j$ where $U_i$ |
| 592 |
* and $V_j$ indicate the $i$th block (not element!) of $U$ and the |
| 593 |
* $j$th block of $V$, respectively. If @p symmetric is |
| 594 |
* <code>true</code>, it is assumed that inner product results in a |
| 595 |
* square symmetric matrix and almost half of the scalar products can be |
| 596 |
* avoided. |
| 597 |
* |
| 598 |
* Obviously, this function can only be used if all blocks of both vectors |
| 599 |
* are of the same size. |
| 600 |
* |
| 601 |
* @note Internally, a single global reduction will be called to |
| 602 |
* accumulate scalar product between locally owned degrees of freedom. |
| 603 |
*/ |
| 604 |
template <typename FullMatrixType> |
| 605 |
void |
| 606 |
multivector_inner_product(FullMatrixType &matrix, |
| 607 |
const BlockVector<Number, MemorySpace> &V, |
| 608 |
const bool symmetric = false) const; |
| 609 |
|
| 610 |
/** |
| 611 |
* Calculate the scalar product between each block of this vector and @p V |
| 612 |
* using a metric tensor @p matrix. This function |
| 613 |
* computes the result of $ \sum_{ij} A^{ij} U_i \cdot V_j$ where $U_i$ |
| 614 |
* and $V_j$ indicate the $i$th block (not element) of $U$ and the |
| 615 |
* $j$th block of $V$, respectively. If @p symmetric is |
| 616 |
* <code>true</code>, it is assumed that $U_i \cdot V_j$ and $A^{ij}$ are |
| 617 |
* symmetric matrices and almost half of the scalar products can be |
| 618 |
* avoided. |
| 619 |
* |
| 620 |
* Obviously, this function can only be used if all blocks of both vectors |
| 621 |
* are of the same size. |
| 622 |
* |
| 623 |
* @note Internally, a single global reduction will be called to |
| 624 |
* accumulate the scalar product between locally owned degrees of freedom. |
| 625 |
*/ |
| 626 |
template <typename FullMatrixType> |
| 627 |
Number |
| 628 |
multivector_inner_product_with_metric( |
| 629 |
const FullMatrixType &matrix, |
| 630 |
const BlockVector<Number, MemorySpace> &V, |
| 631 |
const bool symmetric = false) const; |
| 632 |
|
| 633 |
/** |
| 634 |
* Set each block of this vector as follows: |
| 635 |
* $V^i = s V^i + b \sum_{j} U_j A^{ji}$ where $V^i$ |
| 636 |
* and $U_j$ indicate the $i$th block (not element) of $V$ and the |
| 637 |
* $j$th block of $U$, respectively. |
| 638 |
* |
| 639 |
* Obviously, this function can only be used if all blocks of both vectors |
| 640 |
* are of the same size. |
| 641 |
*/ |
| 642 |
template <typename FullMatrixType> |
| 643 |
void |
| 644 |
mmult(BlockVector<Number, MemorySpace> &V, |
| 645 |
const FullMatrixType &matrix, |
| 646 |
const Number s = Number(0.), |
| 647 |
const Number b = Number(1.)) const; |
| 648 |
|
| 649 |
/** |
| 650 |
* Add @p a to all components. Note that @p a is a scalar not a vector. |
| 651 |
*/ |
| 652 |
void |
| 653 |
add(const Number a); |
| 654 |
|
| 655 |
/** |
| 656 |
* Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>. |
| 657 |
*/ |
| 658 |
void |
| 659 |
add(const Number a, const BlockVector<Number, MemorySpace> &V); |
| 660 |
|
| 661 |
/** |
| 662 |
* Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>. |
| 663 |
*/ |
| 664 |
void |
| 665 |
add(const Number a, |
| 666 |
const BlockVector<Number, MemorySpace> &V, |
| 667 |
const Number b, |
| 668 |
const BlockVector<Number, MemorySpace> &W); |
| 669 |
|
| 670 |
/** |
| 671 |
* A collective add operation: This function adds a whole set of values |
| 672 |
* stored in @p values to the vector components specified by @p indices. |
| 673 |
*/ |
| 674 |
void |
| 675 |
add(const std::vector<size_type> &indices, |
| 676 |
const std::vector<Number> &values); |
| 677 |
|
| 678 |
/** |
| 679 |
* Scaling and simple addition of a multiple of a vector, i.e. <tt>*this = |
| 680 |
* s*(*this)+a*V</tt>. |
| 681 |
*/ |
| 682 |
void |
| 683 |
sadd(const Number s, |
| 684 |
const Number a, |
| 685 |
const BlockVector<Number, MemorySpace> &V); |
| 686 |
|
| 687 |
/** |
| 688 |
* Scale each element of this vector by the corresponding element in the |
| 689 |
* argument. This function is mostly meant to simulate multiplication (and |
| 690 |
* immediate re-assignment) by a diagonal scaling matrix. |
| 691 |
*/ |
| 692 |
void |
| 693 |
scale(const BlockVector<Number, MemorySpace> &scaling_factors); |
| 694 |
|
| 695 |
/** |
| 696 |
* Assignment <tt>*this = a*V</tt>. |
| 697 |
*/ |
| 698 |
void |
| 699 |
equ(const Number a, const BlockVector<Number, MemorySpace> &V); |
| 700 |
|
| 701 |
/** |
| 702 |
* Return the l<sub>1</sub> norm of the vector (i.e., the sum of the |
| 703 |
* absolute values of all entries among all processors). |
| 704 |
*/ |
| 705 |
real_type |
| 706 |
l1_norm() const; |
| 707 |
|
| 708 |
/** |
| 709 |
* Return the $l_2$ norm of the vector (i.e., the square root of |
| 710 |
* the sum of the square of all entries among all processors). |
| 711 |
*/ |
| 712 |
real_type |
| 713 |
l2_norm() const; |
| 714 |
|
| 715 |
/** |
| 716 |
* Return the square of the $l_2$ norm of the vector. |
| 717 |
*/ |
| 718 |
real_type |
| 719 |
norm_sqr() const; |
| 720 |
|
| 721 |
/** |
| 722 |
* Return the maximum norm of the vector (i.e., the maximum absolute value |
| 723 |
* among all entries and among all processors). |
| 724 |
*/ |
| 725 |
real_type |
| 726 |
linfty_norm() const; |
| 727 |
|
| 728 |
/** |
| 729 |
* Perform a combined operation of a vector addition and a subsequent |
| 730 |
* inner product, returning the value of the inner product. In other |
| 731 |
* words, the result of this function is the same as if the user called |
| 732 |
* @code |
| 733 |
* this->add(a, V); |
| 734 |
* return_value = *this * W; |
| 735 |
* @endcode |
| 736 |
* |
| 737 |
* The reason this function exists is that this operation involves less |
| 738 |
* memory transfer than calling the two functions separately. This method |
| 739 |
* only needs to load three vectors, @p this, @p V, @p W, whereas calling |
| 740 |
* separate methods means to load the calling vector @p this twice. Since |
| 741 |
* most vector operations are memory transfer limited, this reduces the |
| 742 |
* time by 25\% (or 50\% if @p W equals @p this). |
| 743 |
* |
| 744 |
* For complex-valued vectors, the scalar product in the second step is |
| 745 |
* implemented as |
| 746 |
* $\left<v,w\right>=\sum_i v_i \bar{w_i}$. |
| 747 |
*/ |
| 748 |
Number |
| 749 |
add_and_dot(const Number a, |
| 750 |
const BlockVector<Number, MemorySpace> &V, |
| 751 |
const BlockVector<Number, MemorySpace> &W); |
| 752 |
|
| 753 |
/** |
| 754 |
* Return the global size of the vector, equal to the sum of the number of |
| 755 |
* locally owned indices among all processors. |
| 756 |
*/ |
| 757 |
virtual size_type |
| 758 |
size() const override; |
| 759 |
|
| 760 |
/** |
| 761 |
* Return an index set that describes which elements of this vector are |
| 762 |
* owned by the current processor. As a consequence, the index sets |
| 763 |
* returned on different processors if this is a distributed vector will |
| 764 |
* form disjoint sets that add up to the complete index set. Obviously, if |
| 765 |
* a vector is created on only one processor, then the result would |
| 766 |
* satisfy |
| 767 |
* @code |
| 768 |
* vec.locally_owned_elements() == complete_index_set(vec.size()) |
| 769 |
* @endcode |
| 770 |
*/ |
| 771 |
dealii::IndexSet |
| 772 |
locally_owned_elements() const; |
| 773 |
|
| 774 |
/** |
| 775 |
* Print the vector to the output stream @p out. |
| 776 |
*/ |
| 777 |
void |
| 778 |
print(std::ostream &out, |
| 779 |
const unsigned int precision = 3, |
| 780 |
const bool scientific = true, |
| 781 |
const bool across = true) const; |
| 782 |
|
| 783 |
/** |
| 784 |
* Return the memory consumption of this class in bytes. |
| 785 |
*/ |
| 786 |
std::size_t |
| 787 |
memory_consumption() const; |
| 788 |
/** @} */ |
| 789 |
|
| 790 |
/** |
| 791 |
* @addtogroup Exceptions |
| 792 |
* @{ |
| 793 |
*/ |
| 794 |
|
| 795 |
/** |
| 796 |
* Attempt to perform an operation between two incompatible vector types. |
| 797 |
* |
| 798 |
* @ingroup Exceptions |
| 799 |
*/ |
| 800 |
DeclException0(ExcVectorTypeNotCompatible); |
| 801 |
|
| 802 |
/** |
| 803 |
* Exception |
| 804 |
*/ |
| 805 |
DeclException0(ExcIteratorRangeDoesNotMatchVectorSize); |
| 806 |
/** @} */ |
| 807 |
}; |
| 808 |
|
| 809 |
/** @} */ |
| 810 |
|
| 811 |
} // end of namespace distributed |
| 812 |
|
| 813 |
} // end of namespace LinearAlgebra |
| 814 |
|
| 815 |
|
| 816 |
/** |
| 817 |
* Global function which overloads the default implementation of the C++ |
| 818 |
* standard library which uses a temporary object. The function simply |
| 819 |
* exchanges the data of the two vectors. |
| 820 |
* |
| 821 |
* @relatesalso BlockVector |
| 822 |
*/ |
| 823 |
template <typename Number, typename MemorySpace> |
| 824 |
inline void |
| 825 |
swap(LinearAlgebra::distributed::BlockVector<Number, MemorySpace> &u, |
| 826 |
LinearAlgebra::distributed::BlockVector<Number, MemorySpace> &v) noexcept |
| 827 |
{ |
| 828 |
u.swap(v); |
| 829 |
} |
| 830 |
|
| 831 |
|
| 832 |
/** |
| 833 |
* Declare dealii::LinearAlgebra::distributed::BlockVector as distributed |
| 834 |
* vector. |
| 835 |
*/ |
| 836 |
template <typename Number, typename MemorySpace> |
| 837 |
struct is_serial_vector< |
| 838 |
LinearAlgebra::distributed::BlockVector<Number, MemorySpace>> |
| 839 |
: std::false_type |
| 840 |
{}; |
| 841 |
|
| 842 |
|
| 843 |
DEAL_II_NAMESPACE_CLOSE |
| 844 |
|
| 845 |
#endif |