39. Linear Algebra Abstractions

Occasionally TAO users will have to interact directly with the linear algebra objects used by the solvers. Solvers within TAO use vector, matrix, index set, and linear solver objects that have no native data structures. Instead they have methods whose implementation is uses structures and routines provided by PETSc or other external software packages.

Given a PETSc Vec object X, the user can create a TaoVec object. By declaring the variables

   TaoVec *xx; 
the routine
   TaoWrapPetscVec(Vec,TaoVec **);  
takes the Vec x and creates and sets TaoVec *xx equal to a new TaoVec object. This object actually has the derived type TaoVecPetsc. Given a TaoVec whose underlying representation is a PETSc Vec, the command
   TaoVecGetPetscVec( TaoVec *, Vec *); 
will retrieve the underlying vector. The routine TaoVecDestroy() will destroy the TaoVec object, but the Vec object must also be destroyed.

The routine

   TaoWrapPetscMat(Mat,TaoMat **);  
takes the Mat H and creates and sets TaoMat *HH equal to the new TaoMat object. The second argument specifies whether the Mat object should be destroyed when the TaoVec object is destroy. This object actually has the derived type TaoMatPetsc. Given a TaoMat whose underlying representation is a PETSc Vec, the command
   TaoMatGetPetscMat( TaoMat *, Mat *); 
will retrieve the underlying matrix. The routine TaoMatDestroy() will destroy the TaoMat object, but the Mat object must also be destroyed.

Similarly, the routine

   TaoWrapKSP( KSP, TaoLinearSolver **); 
takes a KSP object and creates a TaoLinearSolver object. The
   TaoLinearSolverGetKSP( TaoLinearSolver *, KSP *); 
gets the underlying KSP object from the TaoLinearSolver object.

For index sets, the routine

   TaoWrapPetscIS( IS, int, TaoIndexSet **); 
creates a TaoIndexSet object. In this routine, however, the second argument is the local size of the vectors that this object will describe. For instance, this object may describe with elements of a vector are positive. The second argument should be be local length of the vector. The IS object will be destroyed when the TaoIndexSet is destroyed. The routine
   TaoIndexSetGetPetscIS( TaoIndexSet *, IS *); 
will return the underlying IS object.