Reference documentation for deal.II version 9.0.0
|
#include <deal.II/lac/petsc_vector_base.h>
Public Types | |
typedef PetscScalar | value_type |
Public Member Functions | |
VectorBase () | |
VectorBase (const VectorBase &v) | |
VectorBase (const Vec &v) | |
virtual | ~VectorBase () |
virtual void | clear () |
void | compress (const VectorOperation::values operation) |
VectorBase & | operator= (const PetscScalar s) |
bool | operator== (const VectorBase &v) const |
bool | operator!= (const VectorBase &v) const |
size_type | size () const |
size_type | local_size () const |
std::pair< size_type, size_type > | local_range () const |
bool | in_local_range (const size_type index) const |
IndexSet | locally_owned_elements () const |
bool | has_ghost_elements () const |
void | update_ghost_values () const |
reference | operator() (const size_type index) |
PetscScalar | operator() (const size_type index) const |
reference | operator[] (const size_type index) |
PetscScalar | operator[] (const size_type index) const |
void | set (const std::vector< size_type > &indices, const std::vector< PetscScalar > &values) |
void | extract_subvector_to (const std::vector< size_type > &indices, std::vector< PetscScalar > &values) const |
template<typename ForwardIterator , typename OutputIterator > | |
void | extract_subvector_to (const ForwardIterator indices_begin, const ForwardIterator indices_end, OutputIterator values_begin) const |
void | add (const std::vector< size_type > &indices, const std::vector< PetscScalar > &values) |
void | add (const std::vector< size_type > &indices, const ::Vector< PetscScalar > &values) |
void | add (const size_type n_elements, const size_type *indices, const PetscScalar *values) |
PetscScalar | operator* (const VectorBase &vec) const |
real_type | norm_sqr () const |
PetscScalar | mean_value () const |
real_type | l1_norm () const |
real_type | l2_norm () const |
real_type | lp_norm (const real_type p) const |
real_type | linfty_norm () const |
PetscScalar | add_and_dot (const PetscScalar a, const VectorBase &V, const VectorBase &W) |
real_type | min () const |
real_type | max () const |
bool | all_zero () const |
bool | is_non_negative () const |
VectorBase & | operator*= (const PetscScalar factor) |
VectorBase & | operator/= (const PetscScalar factor) |
VectorBase & | operator+= (const VectorBase &V) |
VectorBase & | operator-= (const VectorBase &V) |
void | add (const PetscScalar s) |
void | add (const PetscScalar a, const VectorBase &V) |
void | add (const PetscScalar a, const VectorBase &V, const PetscScalar b, const VectorBase &W) |
void | sadd (const PetscScalar s, const VectorBase &V) |
void | sadd (const PetscScalar s, const PetscScalar a, const VectorBase &V) |
void | scale (const VectorBase &scaling_factors) |
void | equ (const PetscScalar a, const VectorBase &V) |
void | ratio (const VectorBase &a, const VectorBase &b) |
void | write_ascii (const PetscViewerFormat format=PETSC_VIEWER_DEFAULT) |
void | print (std::ostream &out, const unsigned int precision=3, const bool scientific=true, const bool across=true) const |
void | swap (VectorBase &v) |
operator const Vec & () const | |
std::size_t | memory_consumption () const |
virtual const MPI_Comm & | get_mpi_communicator () const |
Public Member Functions inherited from Subscriptor | |
Subscriptor () | |
Subscriptor (const Subscriptor &) | |
Subscriptor (Subscriptor &&) noexcept | |
virtual | ~Subscriptor () |
Subscriptor & | operator= (const Subscriptor &) |
Subscriptor & | operator= (Subscriptor &&) noexcept |
void | subscribe (const char *identifier=nullptr) const |
void | unsubscribe (const char *identifier=nullptr) const |
unsigned int | n_subscriptions () const |
void | list_subscribers () const |
template<class Archive > | |
void | serialize (Archive &ar, const unsigned int version) |
Protected Member Functions | |
void | do_set_add_operation (const size_type n_elements, const size_type *indices, const PetscScalar *values, const bool add_values) |
Protected Attributes | |
Vec | vector |
bool | ghosted |
IndexSet | ghost_indices |
VectorOperation::values | last_action |
bool | obtained_ownership |
Private Member Functions | |
VectorBase & | operator= (const VectorBase &)=delete |
Friends | |
class | internal::VectorReference |
Related Functions | |
(Note that these are not member functions.) | |
void | swap (VectorBase &u, VectorBase &v) |
Additional Inherited Members | |
Static Public Member Functions inherited from Subscriptor | |
static ::ExceptionBase & | ExcInUse (int arg1, std::string arg2, std::string arg3) |
static ::ExceptionBase & | ExcNoSubscriber (std::string arg1, std::string arg2) |
Base class for all vector classes that are implemented on top of the PETSc vector types. Since in PETSc all vector types (i.e. sequential and parallel ones) are built by filling the contents of an abstract object that is only referenced through a pointer of a type that is independent of the actual vector type, we can implement almost all functionality of vectors in this base class. As such, this class can also be used as a deal.II-compatible wrapper for a PETSc Vec
object of any type. Derived classes will then only have to provide the functionality to create one or the other kind of vector.
The interface of this class is modeled after the existing Vector class in deal.II. It has almost the same member functions, and is often exchangeable. However, since PETSc only supports a single scalar type (either double, float, or a complex data type), it is not templated, and only works with whatever your PETSc installation has defined the data type PetscScalar
to.
Note that PETSc only guarantees that operations do what you expect if the functions VecAssemblyBegin
and VecAssemblyEnd
have been called after vector assembly. Therefore, you need to call Vector::compress() before you actually use the vector.
Definition at line 233 of file petsc_vector_base.h.
typedef PetscScalar PETScWrappers::VectorBase::value_type |
Declare some of the standard types used in all containers. These types parallel those in the C++
standard libraries vector<...>
class.
Definition at line 241 of file petsc_vector_base.h.
PETScWrappers::VectorBase::VectorBase | ( | ) |
Default constructor. It doesn't do anything, derived classes will have to initialize the data.
Definition at line 112 of file petsc_vector_base.cc.
PETScWrappers::VectorBase::VectorBase | ( | const VectorBase & | v | ) |
Copy constructor. Sets the dimension to that of the given vector, and copies all elements.
Definition at line 126 of file petsc_vector_base.cc.
|
explicit |
Initialize a Vector from a PETSc Vec object. Note that we do not copy the vector and we do not obtain ownership, so we do not destroy the PETSc object in the destructor.
Definition at line 147 of file petsc_vector_base.cc.
|
virtual |
Destructor
Definition at line 162 of file petsc_vector_base.cc.
|
virtual |
Release all memory and return to a state just like after having called the default constructor.
Reimplemented in PETScWrappers::MPI::Vector.
Definition at line 175 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::compress | ( | const VectorOperation::values | operation | ) |
Compress the underlying representation of the PETSc object, i.e. flush the buffers of the vector object if it has any. This function is necessary after writing into a vector element-by-element and before anything else can be done on it.
See Compressing distributed objects for more information.
Definition at line 364 of file petsc_vector_base.cc.
VectorBase & PETScWrappers::VectorBase::operator= | ( | const PetscScalar | s | ) |
Set all components of the vector to the given number s
. Simply pass this down to the individual block objects, but we still need to declare this function to make the example given in the discussion about making the constructor explicit work.
Since the semantics of assigning a scalar to a vector are not immediately clear, this operator should really only be used if you want to set the entire vector to zero. This allows the intuitive notation v=0
. Assigning other values is deprecated and may be disallowed in the future.
Definition at line 192 of file petsc_vector_base.cc.
bool PETScWrappers::VectorBase::operator== | ( | const VectorBase & | v | ) | const |
Test for equality. This function assumes that the present vector and the one to compare with have the same size already, since comparing vectors of different sizes makes not much sense anyway.
Definition at line 220 of file petsc_vector_base.cc.
bool PETScWrappers::VectorBase::operator!= | ( | const VectorBase & | v | ) | const |
Test for inequality. This function assumes that the present vector and the one to compare with have the same size already, since comparing vectors of different sizes makes not much sense anyway.
Definition at line 235 of file petsc_vector_base.cc.
VectorBase::size_type PETScWrappers::VectorBase::size | ( | ) | const |
Return the global dimension of the vector.
Definition at line 250 of file petsc_vector_base.cc.
VectorBase::size_type PETScWrappers::VectorBase::local_size | ( | ) | const |
Return the local dimension of the vector, i.e. the number of elements stored on the present MPI process. For sequential vectors, this number is the same as size(), but for parallel vectors it may be smaller.
To figure out which elements exactly are stored locally, use local_range().
Definition at line 262 of file petsc_vector_base.cc.
std::pair< VectorBase::size_type, VectorBase::size_type > PETScWrappers::VectorBase::local_range | ( | ) | const |
Return a pair of indices indicating which elements of this vector are stored locally. The first number is the index of the first element stored, the second the index of the one past the last one that is stored locally. If this is a sequential vector, then the result will be the pair (0,N), otherwise it will be a pair (i,i+n), where n=local_size()
.
Definition at line 274 of file petsc_vector_base.cc.
bool PETScWrappers::VectorBase::in_local_range | ( | const size_type | index | ) | const |
Return whether index
is in the local range or not, see also local_range().
IndexSet PETScWrappers::VectorBase::locally_owned_elements | ( | ) | const |
Return an index set that describes which elements of this vector are owned by the current processor. Note that this index set does not include elements this vector may store locally as ghost elements but that are in fact owned by another processor. As a consequence, the index sets returned on different processors if this is a distributed vector will form disjoint sets that add up to the complete index set. Obviously, if a vector is created on only one processor, then the result would satisfy
bool PETScWrappers::VectorBase::has_ghost_elements | ( | ) | const |
Return if the vector contains ghost elements.
void PETScWrappers::VectorBase::update_ghost_values | ( | ) | const |
This function only exists for compatibility with the LinearAlgebra::distributed::Vector
class and does nothing: this class implements ghost value updates in a different way that is a better fit with the underlying PETSc vector object.
reference PETScWrappers::VectorBase::operator() | ( | const size_type | index | ) |
Provide access to a given element, both read and write.
PetscScalar PETScWrappers::VectorBase::operator() | ( | const size_type | index | ) | const |
Provide read-only access to an element.
reference PETScWrappers::VectorBase::operator[] | ( | const size_type | index | ) |
Provide access to a given element, both read and write.
Exactly the same as operator().
PetscScalar PETScWrappers::VectorBase::operator[] | ( | const size_type | index | ) | const |
Provide read-only access to an element.
Exactly the same as operator().
void PETScWrappers::VectorBase::set | ( | const std::vector< size_type > & | indices, |
const std::vector< PetscScalar > & | values | ||
) |
A collective set operation: instead of setting individual elements of a vector, this function allows to set a whole set of elements at once. The indices of the elements to be set are stated in the first argument, the corresponding values in the second.
Definition at line 287 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::extract_subvector_to | ( | const std::vector< size_type > & | indices, |
std::vector< PetscScalar > & | values | ||
) | const |
Instead of getting individual elements of a vector via operator(), this function allows getting a whole set of elements at once. The indices of the elements to be read are stated in the first argument, the corresponding values are returned in the second.
If the current vector is called v
, then this function is the equivalent to the code
indices
and values
arrays must be identical. void PETScWrappers::VectorBase::extract_subvector_to | ( | const ForwardIterator | indices_begin, |
const ForwardIterator | indices_end, | ||
OutputIterator | values_begin | ||
) | const |
Instead of getting individual elements of a vector via operator(), this function allows getting a whole set of elements at once. In contrast to the previous function, this function obtains the indices of the elements by dereferencing all elements of the iterator range provided by the first two arguments, and puts the vector values into memory locations obtained by dereferencing a range of iterators starting at the location pointed to by the third argument.
If the current vector is called v
, then this function is the equivalent to the code
values_begin
as there are iterators between indices_begin
and indices_end
. void PETScWrappers::VectorBase::add | ( | const std::vector< size_type > & | indices, |
const std::vector< PetscScalar > & | values | ||
) |
A collective add operation: This function adds a whole set of values stored in values
to the vector components specified by indices
.
Definition at line 298 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::add | ( | const std::vector< size_type > & | indices, |
const ::Vector< PetscScalar > & | values | ||
) |
This is a second collective add operation. As a difference, this function takes a deal.II vector of values.
Definition at line 309 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::add | ( | const size_type | n_elements, |
const size_type * | indices, | ||
const PetscScalar * | values | ||
) |
Take an address where n_elements
are stored contiguously and add them into the vector. Handles all cases which are not covered by the other two add()
functions above.
Definition at line 320 of file petsc_vector_base.cc.
PetscScalar PETScWrappers::VectorBase::operator* | ( | const VectorBase & | vec | ) | const |
Return the scalar product of two vectors. The vectors must have the same size.
For complex valued vector, this gives \(\left(v^\ast,vec\right)\).
Definition at line 330 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::norm_sqr | ( | ) | const |
Return the square of the \(l_2\)-norm.
Definition at line 419 of file petsc_vector_base.cc.
PetscScalar PETScWrappers::VectorBase::mean_value | ( | ) | const |
Return the mean value of the elements of this vector.
Definition at line 428 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::l1_norm | ( | ) | const |
\(l_1\)-norm of the vector. The sum of the absolute values.
Definition at line 482 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::l2_norm | ( | ) | const |
\(l_2\)-norm of the vector. The square root of the sum of the squares of the elements.
Definition at line 495 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::lp_norm | ( | const real_type | p | ) | const |
\(l_p\)-norm of the vector. The pth root of the sum of the pth powers of the absolute values of the elements.
Definition at line 508 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::linfty_norm | ( | ) | const |
\(l_\infty\)-norm of the vector. Return the value of the vector element with the maximum absolute value.
Definition at line 554 of file petsc_vector_base.cc.
PetscScalar PETScWrappers::VectorBase::add_and_dot | ( | const PetscScalar | a, |
const VectorBase & | V, | ||
const VectorBase & | W | ||
) |
Performs a combined operation of a vector addition and a subsequent inner product, returning the value of the inner product. In other words, the result of this function is the same as if the user called
The reason this function exists is for compatibility with deal.II's own vector classes which can implement this functionality with less memory transfer. However, for PETSc vectors such a combined operation is not natively supported and thus the cost is completely equivalent as calling the two methods separately.
For complex-valued vectors, the scalar product in the second step is implemented as \(\left<v,w\right>=\sum_i v_i \bar{w_i}\).
Definition at line 353 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::min | ( | ) | const |
Return the value of the vector element with the largest negative value.
Definition at line 567 of file petsc_vector_base.cc.
VectorBase::real_type PETScWrappers::VectorBase::max | ( | ) | const |
Return the value of the vector element with the largest positive value.
Definition at line 580 of file petsc_vector_base.cc.
bool PETScWrappers::VectorBase::all_zero | ( | ) | const |
Return whether the vector contains only elements with value zero. This is a collective operation. This function is expensive, because potentially all elements have to be checked.
Definition at line 594 of file petsc_vector_base.cc.
bool PETScWrappers::VectorBase::is_non_negative | ( | ) | const |
Return true
if the vector has no negative entries, i.e. all entries are zero or positive. This function is used, for example, to check whether refinement indicators are really all positive (or zero).
Definition at line 647 of file petsc_vector_base.cc.
VectorBase & PETScWrappers::VectorBase::operator*= | ( | const PetscScalar | factor | ) |
Multiply the entire vector by a fixed factor.
Definition at line 679 of file petsc_vector_base.cc.
VectorBase & PETScWrappers::VectorBase::operator/= | ( | const PetscScalar | factor | ) |
Divide the entire vector by a fixed factor.
Definition at line 693 of file petsc_vector_base.cc.
VectorBase & PETScWrappers::VectorBase::operator+= | ( | const VectorBase & | V | ) |
Add the given vector to the present one.
Definition at line 710 of file petsc_vector_base.cc.
VectorBase & PETScWrappers::VectorBase::operator-= | ( | const VectorBase & | V | ) |
Subtract the given vector from the present one.
Definition at line 722 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::add | ( | const PetscScalar | s | ) |
Addition of s
to all components. Note that s
is a scalar and not a vector.
Definition at line 734 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::add | ( | const PetscScalar | a, |
const VectorBase & | V | ||
) |
Simple addition of a multiple of a vector, i.e. *this += a*V
.
Definition at line 746 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::add | ( | const PetscScalar | a, |
const VectorBase & | V, | ||
const PetscScalar | b, | ||
const VectorBase & | W | ||
) |
Multiple addition of scaled vectors, i.e. *this += a*V+b*W
.
Definition at line 759 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::sadd | ( | const PetscScalar | s, |
const VectorBase & | V | ||
) |
Scaling and simple vector addition, i.e. *this = s*(*this)+V
.
Definition at line 778 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::sadd | ( | const PetscScalar | s, |
const PetscScalar | a, | ||
const VectorBase & | V | ||
) |
Scaling and simple addition, i.e. *this = s*(*this)+a*V
.
Definition at line 791 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::scale | ( | const VectorBase & | scaling_factors | ) |
Scale each element of this vector by the corresponding element in the argument. This function is mostly meant to simulate multiplication (and immediate re-assignment) by a diagonal scaling matrix.
Definition at line 809 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::equ | ( | const PetscScalar | a, |
const VectorBase & | V | ||
) |
Assignment *this = a*V
.
Definition at line 820 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::ratio | ( | const VectorBase & | a, |
const VectorBase & | b | ||
) |
Compute the elementwise ratio of the two given vectors, that is let this[i] = a[i]/b[i]
. This is useful for example if you want to compute the cellwise ratio of true to estimated error.
This vector is appropriately scaled to hold the result.
If any of the b[i]
is zero, the result is undefined. No attempt is made to catch such situations.
Definition at line 841 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::write_ascii | ( | const PetscViewerFormat | format = PETSC_VIEWER_DEFAULT | ) |
Prints the PETSc vector object values using PETSc internal vector viewer function VecView
. The default format prints the vector's contents, including indices of vector elements. For other valid view formats, consult http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecView.html
Definition at line 852 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::print | ( | std::ostream & | out, |
const unsigned int | precision = 3 , |
||
const bool | scientific = true , |
||
const bool | across = true |
||
) | const |
Print to a stream. precision
denotes the desired precision with which values shall be printed, scientific
whether scientific notation shall be used. If across
is true
then the vector is printed in a line, while if false
then the elements are printed on a separate line each.
Definition at line 869 of file petsc_vector_base.cc.
void PETScWrappers::VectorBase::swap | ( | VectorBase & | v | ) |
Swap the contents of this vector and the other vector v
. One could do this operation with a temporary variable and copying over the data elements, but this function is significantly more efficient since it only swaps the pointers to the data of the two vectors and therefore does not need to allocate temporary storage and move data around.
This function is analogous to the swap
function of all C++ standard containers. Also, there is a global function swap(u,v)
that simply calls u.swap(v)
, again in analogy to standard functions.
Definition at line 916 of file petsc_vector_base.cc.
PETScWrappers::VectorBase::operator const Vec & | ( | ) | const |
Conversion operator to gain access to the underlying PETSc type. If you do this, you cut this class off some information it may need, so this conversion operator should only be used if you know what you do. In particular, it should only be used for read-only operations into the vector.
Definition at line 924 of file petsc_vector_base.cc.
std::size_t PETScWrappers::VectorBase::memory_consumption | ( | ) | const |
Estimate for the memory consumption (not implemented for this class).
Definition at line 931 of file petsc_vector_base.cc.
|
virtual |
Return a reference to the MPI communicator object in use with this object.
Reimplemented in PETScWrappers::MPI::Vector.
|
protected |
Collective set or add operation: This function is invoked by the collective set
and add
with the add_values
flag set to the corresponding value.
Definition at line 953 of file petsc_vector_base.cc.
|
privatedelete |
Assignment operator. This is currently not implemented, so it is deliberately left as private (and undefined) to prevent accidental usage.
|
friend |
Make the reference class a friend.
Definition at line 744 of file petsc_vector_base.h.
|
related |
Global function swap
which overloads the default implementation of the C++ standard library which uses a temporary object. The function simply exchanges the data of the two vectors.
Definition at line 785 of file petsc_vector_base.h.
|
protected |
A generic vector object in PETSc. The actual type, a sequential vector, is set in the constructor.
Definition at line 718 of file petsc_vector_base.h.
|
protected |
Denotes if this vector has ghost indices associated with it. This means that at least one of the processes in a parallel program has at least one ghost index.
Definition at line 725 of file petsc_vector_base.h.
|
protected |
This vector contains the global indices of the ghost values. The location in this vector denotes the local numbering, which is used in PETSc.
Definition at line 732 of file petsc_vector_base.h.
|
mutableprotected |
Store whether the last action was a write or add operation. This variable is mutable
so that the accessor classes can write to it, even though the vector object they refer to is constant.
Definition at line 739 of file petsc_vector_base.h.
|
protected |
Specifies if the vector is the owner of the PETSc Vec. This is true if it got created by this class and determines if it gets destroyed in the destructor.
Definition at line 751 of file petsc_vector_base.h.