ML ParameterList interpreter

Backwards compatibility

ML [1] is the predecessor multigrid package of MueLu in Trilinos and widely used in the community for smoothed aggregation multigrid methods. ML is implemented in C and known for its good performance properties. However, the disadvantage is that ML is harder to adapt to new applications and non-standard problems. Furthermore, ML uses its own internal data structure and is somewhat limited to the use with Epetra objects only. In contrast, MueLu provides a fully flexible multigrid framework which is designed to be adapted to any kind of new application with non-standard requirements. Furthermore, it is based on Xpetra and therefore can be used both with Epetra or Tpetra. Nevertheless, it is an important point to provide some kind of backwards compatibility to allow ML users to easily migrate to MueLu (or make experiments with MueLu without having to write to much new code).

In this tutorial we present the MueLu::MLParameterListInterpreter which provides support for the most important ML parameters to be used with MueLu.

C++ part

Preparations

In order to use MueLu (instead or aside of ML) you first have to add it to your application. Please refer to the MueLu user guide for information about compilation and linking (see [2]). Basically, if your application is already working with ML, you should only need to compile and install MueLu and make sure that the MueLu libraries are found by the linker.

C++ interface

In the following we assume that the linear operator \(A\) is available as RCP<Xpetra::Matrix> A.

Then we create a parameter list and fill it with ML parameters.

      params = rcp(new Teuchos::ParameterList());

      params->set("ML output", 10);
      params->set("max levels", 2);
      params->set("smoother: type", "symmetric Gauss-Seidel");
      params->set("coarse: type", "Amesos-KLU");

Please refer to the ML guide [1] for a complete list of available parameters.

Note

Be aware that the MLParameterListInterpreter does not support all ML parameters,

but only the most important ones (e.g., smoothers, transfer operators, rebalancing, …).

Instead of defining the ML parameters by hand in the ParameterList, you can also read in XML files with ML parameters using

      params = Teuchos::getParametersFromXmlFile(xmlFileName);

Next, you create a MLParameterListInterpreter object using the parameters and create a new MueLu::Hierarchy from it.

    MLParameterListInterpreter mueLuFactory(*params);
    RCP<Hierarchy> hierarchy = mueLuFactory.CreateHierarchy();

Of course, you have to provide all necessary information for the multigrid setup routine. This does not only include the fine level operator, but also the set of near null space vectors. Assuming that numPDEs stores the number of equations (and near null space vectors), the following code allows to produce piecewise constant standard near null space vectors (which should be valid for many PDE discretizations).

    RCP<MultiVector> nullspace = MultiVectorFactory::Build(A->getDomainMap(), numPDEs);
    for (int i = 0; i < numPDEs; ++i) {
      Teuchos::ArrayRCP<Scalar> nsValues = nullspace->getDataNonConst(i);
      const int numBlocks                = nsValues.size() / numPDEs;

      for (int j = 0; j < numBlocks; ++j)
        nsValues[j * numPDEs + i] = STS::one();
    }

Then, we just feed in the information to the finest level:

    hierarchy->GetLevel(0)->Set("Nullspace", nullspace);
    hierarchy->GetLevel(0)->Set("A", A);

Finally, we call the Setup routine which actually builds the multigrid hierarchy:

    mueLuFactory.SetupHierarchy(*hierarchy);

Once we have the multigrid hierarchy set up, we can use it the same way as described in Iteration Phase.

Exercise 1

Study the source code of ../../../test/tutorial/MLParameterList.cpp and compile it.

Run the executable MueLu_tutorial_MLParameterList.exe with the –help command line parameter to get an overview of all available command line parameters.

Run the example on a 1D mesh with 256 elements using

./MueLu_tutorial_MLParameterList.exe –xml=xml/ml_ParameterList.xml –nx=256

and study the MueLu output.

Note

You will see a warning by the MLParameterListInterpreter, that the parameter list could not be validated. The reason is the follwing: Since this tutorial example runs with the Tpetra backend, ML, which is purely Epetra-based, cannot validate the parameter list.

Exercise 2

Play around with the parameters from MueLu_tutorial_MLParameterList.exe.

Change, e.g., the problem type to a 2D Laplace problem (–matrixType=Laplace2D) and adapt the –nx and –ny parameters accordingly.