Introduction to Xpetra

Xpetra is a general interface for both Epetra and Tpetra, the two packages providing parallel (MPI) sparse linear algebra capabilities in Trilinos.

Why Xpetra and not Thyra?

Thyra is another abstract interface to Epetra and Tpetra with a focus on encapsulation and abstraction. Thyra is easy to use in context of blocked systems, if no direct data access is necessary. The Teko block preconditioning package therefore is based on the Thyra layer.

Similar to the Thyra abstract interface package in Trilinos, Xpetra provides logical extensions such as blocked operators, blocked multi-vectors, etc., that are very useful for defining multiphysics objects. Xpetra is Thyra-compatible, that is, you can easily create Xpetra obejcts given a Thyra operator and vice-versa. In contrast to Thyra, Xpetra follows the Tpetra interface and allows for easy data access. Multigrid preconditioners heavily rely on direct data access and therefore Thyra would not be convenient to use.

Xpetra objects

Xpetra has only object for Map, Graph, Matrix and Multivector. It is one to one with Tpetra except for BlockCrsTpetra object that are not available directly but there is an Xpetra wrapper around it. Additional blocked operators are available in Xpetra. These operators are currently used to partition systems of equations based on the physics they represent. This can be extended to partition a system based on different criteria, however no overlapping is currently available.

Write general code

When writing new algorithms for MueLu, use only Xpetra to make your algorithms independent from the underlying concrete linear algebra implementation (Epetra, Tpetra, ??). Use the Xpetra Factory classes to create objects. The reason for this design is that factories have the ability to decide which underlying library has to be used in the instantiation of an object.

Kokkos interface

Xpetra_UseShortNames.hpp is used to define types for Matrix, Map, Multivector, etc… but already templates correctly. However be careful to be consistent if you decide to restrict yourself to a particular type while templating (see Semi-coarsening and Geometric coarsening that use '''double''' instead of '''Scalar''' for multivectors derived from coordinate quantities) as inconsistent templating will most likely generate error when Stokhos and Sacado are enabled.

Xpetra::CrsMatrix represents row matrices, MueLu wants Matrix objects (not CrsMatrix) so we have a wrapper: CrsMatrixWrap that does the conversion.

Description of Xpetra objects

What's in a Map?

Maps can be thought of, in a global sense, as list of triplets (LID, GID, PID), where LID is a local ID, GID is a global ID and PID is a processor ID. Basically it tells you if a given processor owns a GID and how that GID is converted into an LID.
You can print a Map to a file using Xpetra::IO<SC,LO,GO,NO>::Write and you will notice that you get a list pairs (GID, PID), where the pairs are ordered by LID.

As maps describe the parallel layout of your data must be careful while creating maps at mistakes there will results in often non trivial bugs!

Going from map to map: importer/exporter

The importer and exporter objects allow us to change the parallel of layout data such that one object created with mapA can be filled with the data of a source object that was created with mapB. This concept is used in MueLu to obtain ghost data when necessary and also to have algorithm that separate the treatment of data from the treatment of the data layout.