Reference documentation for deal.II version GIT relicensing897g3473bfcca7 20240624 11:40:02+00:00

#include <deal.II/lac/arpack_solver.h>
Classes  
struct  AdditionalData 
Public Types  
enum  WhichEigenvalues { algebraically_largest , algebraically_smallest , largest_magnitude , smallest_magnitude , largest_real_part , smallest_real_part , largest_imaginary_part , smallest_imaginary_part , both_ends } 
using  size_type = types::global_dof_index 
Public Member Functions  
SolverControl &  control () const 
ArpackSolver (SolverControl &control, const AdditionalData &data=AdditionalData())  
template<typename VectorType >  
void  set_initial_vector (const VectorType &vec) 
void  set_shift (const std::complex< double > sigma) 
template<typename VectorType , typename MatrixType1 , typename MatrixType2 , typename INVERSE >  
void  solve (const MatrixType1 &A, const MatrixType2 &B, const INVERSE &inverse, std::vector< std::complex< double > > &eigenvalues, std::vector< VectorType > &eigenvectors, const unsigned int n_eigenvalues=0) 
template<class Archive >  
void  serialize (Archive &ar, const unsigned int version) 
Subscriptor functionality  
Classes derived from Subscriptor provide a facility to subscribe to this object. This is mostly used by the SmartPointer class.  
void  subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const 
void  unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const 
unsigned int  n_subscriptions () const 
template<typename StreamType >  
void  list_subscribers (StreamType &stream) const 
void  list_subscribers () const 
Static Public Member Functions  
static ::ExceptionBase &  ExcInUse (int arg1, std::string arg2, std::string arg3) 
static ::ExceptionBase &  ExcNoSubscriber (std::string arg1, std::string arg2) 
Protected Attributes  
SolverControl &  solver_control 
const AdditionalData  additional_data 
bool  initial_vector_provided 
std::vector< double >  resid 
double  sigmar 
double  sigmai 
Private Types  
using  map_value_type = decltype(counter_map)::value_type 
using  map_iterator = decltype(counter_map)::iterator 
Private Member Functions  
void  check_no_subscribers () const noexcept 
Static Private Member Functions  
static ::ExceptionBase &  ArpackExcInvalidNumberofEigenvalues (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcInvalidEigenvectorSize (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcInvalidEigenvectorSizeNonsymmetric (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcInvalidEigenvalueSize (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcInvalidNumberofArnoldiVectors (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcSmallNumberofArnoldiVectors (int arg1, int arg2) 
static ::ExceptionBase &  ArpackExcArpackIdo (int arg1) 
static ::ExceptionBase &  ArpackExcArpackMode (int arg1) 
static ::ExceptionBase &  ArpackExcArpackInfodsaupd (int arg1) 
static ::ExceptionBase &  ArpackExcArpackInfodnaupd (int arg1) 
static ::ExceptionBase &  ArpackExcArpackInfodseupd (int arg1) 
static ::ExceptionBase &  ArpackExcArpackInfodneupd (int arg1) 
static ::ExceptionBase &  ArpackExcArpackInfoMaxIt (int arg1) 
static ::ExceptionBase &  ArpackExcArpackNoShifts () 
Private Attributes  
std::atomic< unsigned int >  counter 
std::map< std::string, unsigned int >  counter_map 
std::vector< std::atomic< bool > * >  validity_pointers 
const std::type_info *  object_info 
Static Private Attributes  
static std::mutex  mutex 
Interface for using ARPACK. ARPACK is a collection of Fortran77 subroutines designed to solve large scale eigenvalue problems. Here we interface to the routines dnaupd
and dneupd
of ARPACK. If the operator is specified to be symmetric we use the symmetric interface dsaupd
and dseupd
of ARPACK instead. The package is designed to compute a few eigenvalues and corresponding eigenvectors of a general n by n matrix A. It is most appropriate for large sparse matrices A.
In this class we make use of the method applied to the generalized eigenspectrum problem \((A\lambda B)x=0\), for \(x\neq0\); where \(A\) is a system matrix, \(B\) is a mass matrix, and \(\lambda, x\) are a set of eigenvalues and eigenvectors respectively.
The ArpackSolver can be used in application codes with serial objects in the following way:
for the generalized eigenvalue problem \(Ax=B\lambda x\), where the variable size_of_spectrum
tells ARPACK the number of eigenvector/eigenvalue pairs to solve for. Here, lambda
is a vector that will contain the eigenvalues computed, x
a vector that will contain the eigenvectors computed, and OP
is an inverse operation for the matrix A
. Shift and invert transformation around zero is applied.
Through the AdditionalData the user can specify some of the parameters to be set.
For further information on how the ARPACK routines dsaupd
, dseupd
, dnaupd
and dneupd
work and also how to set the parameters appropriately please take a look into the ARPACK manual.
Definition at line 166 of file arpack_solver.h.
Declare the type for container size.
Definition at line 172 of file arpack_solver.h.

privateinherited 
The data type used in counter_map.
Definition at line 229 of file subscriptor.h.

privateinherited 
The iterator type used in counter_map.
Definition at line 234 of file subscriptor.h.
An enum that lists the possible choices for which eigenvalues to compute in the solve() function.
Definition at line 179 of file arpack_solver.h.

inline 
Constructor.
Definition at line 501 of file arpack_solver.h.

inline 
Access to the object that controls convergence.
Definition at line 894 of file arpack_solver.h.

inline 
Set initial vector for building Krylov space.
Definition at line 523 of file arpack_solver.h.

inline 
Set shift sigma
for shiftandinvert spectral transformation.
If this function is not called, the shift is assumed to be zero.
Definition at line 513 of file arpack_solver.h.

inline 
Solve the generalized eigensprectrum problem \(A x=\lambda B x\) by calling the dsaupd
and dseupd
or dnaupd
and dneupd
functions of ARPACK.
The function returns a vector of eigenvalues of length n and a vector of eigenvectors of length n in the symmetric case and of length n+1 in the nonsymmetric case. In the symmetric case all eigenvectors are real. In the nonsymmetric case complex eigenvalues always occur as complex conjugate pairs. Therefore the eigenvector for an eigenvalue with nonzero complex part is stored by putting the real and the imaginary parts in consecutive realvalued vectors. The eigenvector of the complex conjugate eigenvalue does not need to be stored, since it is just the complex conjugate of the stored eigenvector. Thus, if the last nth eigenvalue has a nonzero imaginary part, Arpack needs in total n+1 realvalued vectors to store real and imaginary parts of the eigenvectors.
A  The operator for which we want to compute eigenvalues. Actually, this parameter is entirely unused. 
B  The inner product of the underlying space, typically the mass matrix. For constrained problems, it can be a partial mass matrix, like for instance the velocity mass matrix of a Stokes problem. Only its function vmult() is used. 
inverse  This is the possibly shifted inverse that is actually used instead of A . Only its function vmult() is used. 
eigenvalues  is a vector of complex numbers in which the eigenvalues are returned. 
eigenvectors  is a real vector of eigenvectors, containing the real parts of all eigenvectors and the imaginary parts of the eigenvectors corresponding to complex conjugate eigenvalue pairs. Therefore, its length should be n in the symmetric case and n+1 in the nonsymmetric case. In the nonsymmetric case the storage scheme leads for example to the following pattern. Suppose that the first two eigenvalues are real and the third and fourth are a complex conjugate pair. Asking for three eigenpairs results in [real(v1),real(v2), real(v3),imag(v3)]. Note that we get the same pattern if we ask for four eigenpairs in this example, since the fourth eigenvector is simply the complex conjugate of the third one. 
n_eigenvalues  The purpose of this parameter is not clear, but it is safe to set it to the size of eigenvalues or greater. Leave it at its default zero, which will be reset to the size of eigenvalues internally. 
Definition at line 537 of file arpack_solver.h.

inherited 
Subscribes a user of the object by storing the pointer validity
. The subscriber may be identified by text supplied as identifier
.
Definition at line 135 of file subscriptor.cc.

inherited 
Unsubscribes a user from the object.
identifier
and the validity
pointer must be the same as the one supplied to subscribe(). Definition at line 155 of file subscriptor.cc.

inlineinherited 
Return the present number of subscriptions to this object. This allows to use this class for reference counted lifetime determination where the last one to unsubscribe also deletes the object.
Definition at line 300 of file subscriptor.h.

inlineinherited 
List the subscribers to the input stream
.
Definition at line 317 of file subscriptor.h.

inherited 
List the subscribers to deallog
.
Definition at line 203 of file subscriptor.cc.

inlineinherited 
Read or write the data of this object to or from a stream for the purpose of serialization using the BOOST serialization library.
This function does not actually serialize any of the member variables of this class. The reason is that what this class stores is only who subscribes to this object, but who does so at the time of storing the contents of this object does not necessarily have anything to do with who subscribes to the object when it is restored. Consequently, we do not want to overwrite the subscribers at the time of restoring, and then there is no reason to write the subscribers out in the first place.
Definition at line 309 of file subscriptor.h.

privatenoexceptinherited 
Check that there are no objects subscribing to this object. If this check passes then it is safe to destroy the current object. It this check fails then this function will either abort or print an error message to deallog (by using the AssertNothrow mechanism), but will not throw an exception.
Definition at line 52 of file subscriptor.cc.

protected 
Reference to the object that controls convergence of the iterative solver.
Definition at line 348 of file arpack_solver.h.

protected 
Store a copy of the flags for this particular solver.
Definition at line 353 of file arpack_solver.h.

protected 
Store an initial vector
Definition at line 358 of file arpack_solver.h.

protected 
Definition at line 359 of file arpack_solver.h.

protected 
Real part of the shift
Definition at line 364 of file arpack_solver.h.

protected 
Imaginary part of the shift
Definition at line 369 of file arpack_solver.h.

mutableprivateinherited 
Store the number of objects which subscribed to this object. Initially, this number is zero, and upon destruction it shall be zero again (i.e. all objects which subscribed should have unsubscribed again).
The creator (and owner) of an object is counted in the map below if HE manages to supply identification.
We use the mutable
keyword in order to allow subscription to constant objects also.
This counter may be read from and written to concurrently in multithreaded code: hence we use the std::atomic
class template.
Definition at line 218 of file subscriptor.h.

mutableprivateinherited 
In this map, we count subscriptions for each different identification string supplied to subscribe().
Definition at line 224 of file subscriptor.h.

mutableprivateinherited 
In this vector, we store pointers to the validity bool in the SmartPointer objects that subscribe to this class.
Definition at line 240 of file subscriptor.h.

mutableprivateinherited 
Pointer to the typeinfo object of this object, from which we can later deduce the class name. Since this information on the derived class is neither available in the destructor, nor in the constructor, we obtain it in between and store it here.
Definition at line 248 of file subscriptor.h.

staticprivateinherited 
A mutex used to ensure data consistency when accessing the mutable
members of this class. This lock is used in the subscribe() and unsubscribe() functions, as well as in list_subscribers()
.
Definition at line 271 of file subscriptor.h.