From e8716a69aab9c05dd950f2db3c85d500f70e0fa6 Mon Sep 17 00:00:00 2001 From: kronbichler Date: Mon, 26 Jan 2009 09:11:27 +0000 Subject: [PATCH] Update comments in Trilinos AMG preconditioner. git-svn-id: https://svn.dealii.org/trunk@18300 0785d39b-7218-0410-832d-ea1e28bc413d --- .../lac/include/lac/trilinos_precondition.h | 199 +++++++++--------- deal.II/lac/source/trilinos_precondition.cc | 18 +- 2 files changed, 105 insertions(+), 112 deletions(-) diff --git a/deal.II/lac/include/lac/trilinos_precondition.h b/deal.II/lac/include/lac/trilinos_precondition.h index 1d0aef06c2..a9f2cc93cb 100755 --- a/deal.II/lac/include/lac/trilinos_precondition.h +++ b/deal.II/lac/include/lac/trilinos_precondition.h @@ -1249,26 +1249,24 @@ namespace TrilinosWrappers /** - * This class implements an algebraic multigrid (AMG) preconditioner - * based on the Trilinos ML implementation, which is a black-box - * preconditioner that works well for many PDE-based linear problems. - * What this class does is twofold. When the initialize() function is - * invoked, a ML preconditioner object is created based on the matrix - * that we want the preconditioner to be based on. A call of the - * respective vmult function does call the respective - * operation in the Trilinos package, where it is called - * ApplyInverse. Use of this class is explained in the - * @ref step_31 "step-31" tutorial program. + * This class implements an algebraic multigrid (AMG) preconditioner based + * on the Trilinos ML implementation, which is a black-box preconditioner + * that works well for many PDE-based linear problems. What this class does + * is twofold. When the initialize() function is invoked, a ML + * preconditioner object is created based on the matrix that we want the + * preconditioner to be based on. A call of the respective + * vmult function does call the respective operation in the + * Trilinos package, where it is called ApplyInverse. Use of + * this class is explained in the @ref step_31 "step-31" tutorial program. * - * There are a few pecularities in initialize(). Since the Trilinos - * objects we want to use are heavily dependent on Epetra objects, the - * fundamental construction routines for vectors and matrices in - * Trilinos, we do a copy of our deal.II preconditioner matrix to a - * Epetra matrix. This is of course not optimal, but for the time - * being there is no direct support for our data interface. When - * doing this time-consuming operation, we can still profit from the - * fact that some of the entries in the preconditioner matrix are zero - * and hence can be neglected. + * Since the Trilinos objects we want to use are heavily dependent on Epetra + * objects, we recommend using this class in conjunction with Trilinos + * (Epetra) sparse matrices and vectors. There is support for use with + * matrices of the deal.II::SparseMatrix class and corresponding vectors, + * too, but this requires generating a copy of the matrix, which is slower + * and takes (much) more memory. When doing such a copy operation, we can + * still profit from the fact that some of the entries in the preconditioner + * matrix are zero and hence can be neglected. * * The implementation is able to distinguish between matrices from elliptic * problems and convection dominated problems. We use the standard options @@ -1277,7 +1275,16 @@ namespace TrilinosWrappers * most elliptic problems, Chebyshev provides a better damping of high * frequencies (in the algebraic sense) than Gauss-Seidel (SSOR), and is * faster (Chebyshev requires only some matrix-vector products, whereas SSOR - * requires substitutions which are more expensive). + * requires substitutions which are more expensive). Moreover, Chebyshev is + * perfectly parallel in the sense that it does not degenerate when used on + * many processors. SSOR, on the other hand, gets more Jacobi-like on many + * processors. + * + * For proper functionality of this class we recommend using Trilinos v9.0 + * and higher. Older versions may have problems with generating the + * coarse-matrix structure when using matrices with many nonzero entries per + * row (i.e., matrices stemming from higher order finite element + * discretizations). * * @ingroup TrilinosWrappers * @ingroup Preconditioners @@ -1293,8 +1300,7 @@ namespace TrilinosWrappers * Constructor. By default, we * pretend to work on elliptic * problems with linear finite - * elements on a scalar - * equation. + * elements on a scalar equation. */ AdditionalData (const bool elliptic = true, const bool higher_order_elements = false, @@ -1306,57 +1312,51 @@ namespace TrilinosWrappers /** * Determines whether the AMG - * preconditioner should be - * optimized for elliptic - * problems (ML option smoothed - * aggregation SA, using a + * preconditioner should be optimized + * for elliptic problems (ML option + * smoothed aggregation SA, using a * Chebyshev smoother) or for - * non-elliptic problems (ML - * option non-symmetric - * smoothed aggregation NSSA, - * smoother is SSOR with + * non-elliptic problems (ML option + * non-symmetric smoothed aggregation + * NSSA, smoother is SSOR with * underrelaxation). */ bool elliptic; /** - * Determines whether the - * matrix that the - * preconditioner is built upon + * Determines whether the matrix that + * the preconditioner is built upon * is generated from linear or * higher-order elements. */ bool higher_order_elements; /** - * This threshold tells the AMG - * setup how the coarsening - * should be performed. In the - * AMG used by ML, all points - * that strongly couple with - * the tentative coarse-level - * point form one - * aggregate. The term + * This threshold tells the AMG setup + * how the coarsening should be + * performed. In the AMG used by ML, + * all points that strongly couple + * with the tentative coarse-level + * point form one aggregate. The term * strong coupling is * controlled by the variable * aggregation_threshold, - * meaning that all elements - * that are not smaller than + * meaning that all elements that are + * not smaller than * aggregation_threshold - * times the diagonal element - * do couple strongly. + * times the diagonal element do + * couple strongly. */ double aggregation_threshold; /** - * Specifies the constant modes - * (near null space) of the - * matrix. This parameter tells - * AMG whether we work on a - * scalar equation (where the - * near null space only - * consists of ones) or on a - * vector-valued equation. + * Specifies the constant modes (near + * null space) of the matrix. This + * parameter tells AMG whether we + * work on a scalar equation (where + * the near null space only consists + * of ones) or on a vector-valued + * equation. */ std::vector > constant_modes; @@ -1368,7 +1368,10 @@ namespace TrilinosWrappers * elliptic or almost elliptic * problems, the polynomial degree of * the Chebyshev smoother is set to - * smoother_sweeps. In the + * smoother_sweeps. The term + * sweeps refers to the number of + * matrix-vector products performed + * in the Chebyshev case. In the * non-elliptic case, * smoother_sweeps sets the * number of SSOR relaxation sweeps @@ -1378,10 +1381,9 @@ namespace TrilinosWrappers unsigned int smoother_sweeps; /** - * Determines the overlap in - * the SSOR/Chebyshev error - * smoother when run in - * parallel. + * Determines the overlap in the + * SSOR/Chebyshev error smoother when + * run in parallel. */ unsigned int smoother_overlap; @@ -1390,80 +1392,73 @@ namespace TrilinosWrappers * true, then internal * information from the ML * preconditioner is printed to - * screen. This can be useful - * when debugging the - * preconditioner. + * screen. This can be useful when + * debugging the preconditioner. */ bool output_details; }; /** - * Let Trilinos compute a - * multilevel hierarchy for the - * solution of a linear system - * with the given matrix. The - * function uses the matrix - * format specified in + * Let Trilinos compute a multilevel + * hierarchy for the solution of a + * linear system with the given + * matrix. The function uses the + * matrix format specified in * TrilinosWrappers::SparseMatrix. */ void initialize (const SparseMatrix &matrix, const AdditionalData &additional_data = AdditionalData()); /** - * Let Trilinos compute a - * multilevel hierarchy for the - * solution of a linear system - * with the given matrix. This - * function takes a deal.ii - * matrix and copies the - * content into a Trilinos - * matrix, so the function can - * be considered rather - * inefficient. + * Let Trilinos compute a multilevel + * hierarchy for the solution of a + * linear system with the given + * matrix. This function takes a + * deal.ii matrix and copies the + * content into a Trilinos matrix, so + * the function can be considered + * rather inefficient. */ void initialize (const ::dealii::SparseMatrix &deal_ii_sparse_matrix, const AdditionalData &additional_data = AdditionalData(), const double drop_tolerance = 1e-13); /** - * This function can be used - * for a faster recalculation - * of the preconditioner - * construction when the matrix - * entries underlying the - * preconditioner have changed, - * but the matrix sparsity - * pattern has remained the - * same. What this function - * does is taking the already - * generated coarsening + * This function can be used for a + * faster recalculation of the + * preconditioner construction when + * the matrix entries underlying the + * preconditioner have changed, but + * the matrix sparsity pattern has + * remained the same. What this + * function does is taking the + * already generated coarsening * structure, computing the AMG * prolongation and restriction * according to a smoothed - * aggregation strategy and - * then building the whole - * multilevel hiearchy. This - * function can be considerably - * faster than the initialize - * function, since the - * coarsening pattern is - * usually the most difficult - * thing to do when setting up - * the AMG ML preconditioner. + * aggregation strategy and then + * building the whole multilevel + * hiearchy. This function can be + * considerably faster than the + * initialize function, since the + * coarsening pattern is usually the + * most difficult thing to do when + * setting up the AMG ML + * preconditioner. */ void reinit (); private: /** - * A pointer to the - * preconditioner object. + * A pointer to the preconditioner + * object. */ Teuchos::RCP multilevel_operator; /** - * A copy of the deal.II matrix - * into Trilinos format. + * A copy of the deal.II matrix into + * Trilinos format. */ std_cxx0x::shared_ptr Matrix; }; diff --git a/deal.II/lac/source/trilinos_precondition.cc b/deal.II/lac/source/trilinos_precondition.cc index 73a94722ca..bdcde138f0 100755 --- a/deal.II/lac/source/trilinos_precondition.cc +++ b/deal.II/lac/source/trilinos_precondition.cc @@ -108,11 +108,8 @@ namespace TrilinosWrappers Epetra_Vector RHS (View, preconditioner->OperatorRangeMap(), const_cast(src.begin())); - const int res = preconditioner->ApplyInverse (RHS, LHS); - - Assert (res == 0, - ExcMessage ("Trilinos AMG MultiLevel preconditioner returned " - "with an error!")); + const int ierr = preconditioner->ApplyInverse (RHS, LHS); + AssertThrow (ierr == 0, ExcTrilinosError(ierr)); } @@ -602,9 +599,9 @@ namespace TrilinosWrappers } parameter_list.set("smoother: sweeps", - (int)additional_data.smoother_sweeps); + static_cast(additional_data.smoother_sweeps)); parameter_list.set("smoother: ifpack overlap", - (int)additional_data.smoother_overlap); + static_cast(additional_data.smoother_overlap)); parameter_list.set("aggregation: threshold", additional_data.aggregation_threshold); @@ -623,12 +620,13 @@ namespace TrilinosWrappers Assert (n_rows == additional_data.constant_modes[0].size(), ExcDimensionMismatch(n_rows, additional_data.constant_modes[0].size())); - Assert (n_rows == (unsigned int)distributed_constant_modes.GlobalLength(), + Assert (n_rows == + static_cast(distributed_constant_modes.GlobalLength()), ExcDimensionMismatch(n_rows, distributed_constant_modes.GlobalLength())); const unsigned int my_size = domain_map.NumMyElements(); - Assert (my_size == (unsigned int)domain_map.MaxLID()+1, + Assert (my_size == static_cast(domain_map.MaxLID()+1), ExcDimensionMismatch (my_size, domain_map.MaxLID()+1)); // Reshape null space as a @@ -640,7 +638,7 @@ namespace TrilinosWrappers { int global_row_id = domain_map.GID(row); distributed_constant_modes.ReplaceMyValue(row, d, - (double)additional_data.constant_modes[d][global_row_id]); + static_cast(additional_data.constant_modes[d][global_row_id])); } parameter_list.set("null space: type", "pre-computed"); -- 2.39.5