trilinos_helpers.h
Go to the documentation of this file.
1 // LIC// ====================================================================
2 // LIC// This file forms part of oomph-lib, the object-oriented,
3 // LIC// multi-physics finite-element library, available
4 // LIC// at http://www.oomph-lib.org.
5 // LIC//
6 // LIC// Copyright (C) 2006-2023 Matthias Heil and Andrew Hazel
7 // LIC//
8 // LIC// This library is free software; you can redistribute it and/or
9 // LIC// modify it under the terms of the GNU Lesser General Public
10 // LIC// License as published by the Free Software Foundation; either
11 // LIC// version 2.1 of the License, or (at your option) any later version.
12 // LIC//
13 // LIC// This library is distributed in the hope that it will be useful,
14 // LIC// but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // LIC// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 // LIC// Lesser General Public License for more details.
17 // LIC//
18 // LIC// You should have received a copy of the GNU Lesser General Public
19 // LIC// License along with this library; if not, write to the Free Software
20 // LIC// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 // LIC// 02110-1301 USA.
22 // LIC//
23 // LIC// The authors may be contacted at oomph-lib@maths.man.ac.uk.
24 // LIC//
25 // LIC//====================================================================
26 #ifndef OOMPH_TRILINOS_HELPERS_HEADER
27 #define OOMPH_TRILINOS_HELPERS_HEADER
28 
29 
30 // Config header generated by autoconfig
31 #ifdef HAVE_CONFIG_H
32 #include <oomph-lib-config.h>
33 #endif
34 
35 #ifdef OOMPH_HAS_MPI
36 #include "mpi.h"
37 #endif
38 
39 
40 // trilinos headers
41 #include "Epetra_Map.h"
42 #include "Epetra_LocalMap.h"
43 #include "Epetra_Vector.h"
44 #include "Epetra_CrsMatrix.h"
45 #include "EpetraExt_MatrixMatrix.h"
46 #include "ml_epetra_utils.h"
47 
48 #ifdef OOMPH_HAS_MPI
49 #include "Epetra_MpiComm.h"
50 #else
51 #include "Epetra_SerialComm.h"
52 #endif
53 
54 // oomph-lib headers
55 #include "matrices.h"
56 
57 // mpi includes
58 #ifdef OOMPH_HAS_MPI
59 #include "double_vector.h"
61 #endif
62 
63 namespace oomph
64 {
65  /// / forward declaration of oomph-lib compressed row matrix
66  class CRDoubleMatrix;
67 
68 
69  //=============================================================================
70  /// Helper namespace for use with the Trilinos Epetra package.
71  /// Contains functions to generate two Epetra containers (Epetra_Vector and
72  /// Epetra_CrsMatrix) and provides access to the trilinos matrix-matrix
73  /// and matrix-vector product routines.
74  //=============================================================================
75  namespace TrilinosEpetraHelpers
76  {
77  // VECTOR METHODS
78  // ============================================================
79 
80  /// create an Epetra_Vector from an oomph-lib DoubleVector.
81  /// If oomph_vec is NOT distributed (i.e. locally replicated) and
82  /// on more than one processor, then the returned Epetra_Vector will be
83  /// uniformly distributed. If the oomph_vec is distributed then the
84  /// Epetra_Vector returned will have the same distribution as oomp_vec.
85  Epetra_Vector* create_distributed_epetra_vector(
86  const DoubleVector& oomph_vec);
87 
88  /// create an Epetra_Vector based on the argument oomph-lib
89  /// LinearAlgebraDistribution
90  /// If dist is NOT distributed and
91  /// on more than one processor, then the returned Epetra_Vector will be
92  /// uniformly distributed. If dist is distributed then the Epetra_Vector
93  /// returned will have the same distribution as dist.
94  /// The coefficient values are not set.
95  Epetra_Vector* create_distributed_epetra_vector(
96  const LinearAlgebraDistribution* dist_pt);
97 
98  /// create an Epetra_Vector equivalent of DoubleVector
99  /// The argument DoubleVector must be built.
100  /// The Epetra_Vector will point to, and NOT COPY the underlying data in the
101  /// DoubleVector.
102  /// The oomph-lib DoubleVector and the returned Epetra_Vector will have the
103  /// the same distribution.
104  Epetra_Vector* create_epetra_vector_view_data(DoubleVector& oomph_vec);
105 
106  /// Helper function to copy the contents of a Trilinos vector to an
107  /// oomph-lib distributed vector. The distribution of the two vectors must
108  /// be identical
109  void copy_to_oomphlib_vector(const Epetra_Vector* epetra_vec_pt,
110  DoubleVector& oomph_vec);
111 
112  // MATRIX METHODS
113  // ============================================================
114 
115  /// create an Epetra_CrsMatrix from an oomph-lib CRDoubleMatrix.
116  /// If oomph_matrix_pt is NOT distributed (i.e. locally replicated) and
117  /// on more than one processor, then the returned Epetra_Vector will be
118  /// uniformly distributed. If the oomph_matrix_pt is distributed then the
119  /// Epetra_CrsMatrix returned will have the same distribution as
120  /// oomph_matrix_pt.
121  /// The LinearAlgebraDistribution argument dist_pt should specify the
122  /// distribution of the object this matrix will operate on.
123  Epetra_CrsMatrix* create_distributed_epetra_matrix(
124  const CRDoubleMatrix* oomph_matrix_pt,
125  const LinearAlgebraDistribution* dist_pt);
126 
127  /// create and Epetra_CrsMatrix from an oomph-lib CRDoubleMatrix.
128  /// Specialisation for Trilinos AztecOO.
129  /// If oomph_matrix_pt is NOT distributed (i.e. locally replicated) and
130  /// on more than one processor, then the returned Epetra_Vector will be
131  /// uniformly distributed. If the oomph_matrix_pt is distributed then the
132  /// Epetra_CrsMatrix returned will have the same distribution as
133  /// oomph_matrix_pt.
134  /// For AztecOO, the column map is ordered such that the local rows are
135  /// first.
137  CRDoubleMatrix* oomph_matrix_pt);
138 
139  // MATRIX OPERATION METHODS
140  // ==================================================
141 
142  /// Function to perform a matrix-vector multiplication on a
143  /// oomph-lib matrix and vector using Trilinos functionality.
144  /// NOTE 1. the matrix and the vectors must have the same communicator.
145  /// NOTE 2. The vector will be returned with the same distribution
146  /// as the matrix, unless a distribution is predefined in the solution
147  /// vector in which case the vector will be returned with that distribution.
148  void multiply(const CRDoubleMatrix* matrix,
149  const DoubleVector& x,
150  DoubleVector& soln);
151 
152  /// Function to perform a matrix-matrix multiplication on oomph-lib
153  /// matrices by using Trilinos functionality.
154  /// \b NOTE 1. There are two Trilinos matrix-matrix multiplication methods
155  /// available, using either the EpetraExt::MatrixMatrix class (if use_ml ==
156  /// false) or using ML (Epetra_MatrixMult method)
157  /// \b NOTE 2. the solution matrix (matrix_soln) will be returned with the
158  /// same distribution as matrix1
159  /// \b NOTE 3. All matrices must share the same communicator.
160  void multiply(const CRDoubleMatrix& matrix_1,
161  const CRDoubleMatrix& matrix_2,
162  CRDoubleMatrix& matrix_soln,
163  const bool& use_ml = false);
164 
165  // HELPER METHODS
166  // ============================================================
167 
168  /// create an Epetra_Map corresponding to the LinearAlgebraDistribution
169  Epetra_Map* create_epetra_map(const LinearAlgebraDistribution* const dist);
170  }; // namespace TrilinosEpetraHelpers
171 } // namespace oomph
172 #endif
A class for compressed row matrices. This is a distributable object.
Definition: matrices.h:888
A vector in the mathematical sense, initially developed for linear algebra type applications....
Definition: double_vector.h:58
Describes the distribution of a distributable linear algebra type object. Typically this is a contain...
Epetra_CrsMatrix * create_distributed_epetra_matrix(const CRDoubleMatrix *oomph_matrix_pt, const LinearAlgebraDistribution *dist_pt)
create an Epetra_CrsMatrix from an oomph-lib CRDoubleMatrix. If oomph_matrix_pt is NOT distributed (i...
Epetra_CrsMatrix * create_distributed_epetra_matrix_for_aztecoo(CRDoubleMatrix *oomph_matrix_pt)
create and Epetra_CrsMatrix from an oomph-lib CRDoubleMatrix. Specialisation for Trilinos AztecOO....
void copy_to_oomphlib_vector(const Epetra_Vector *epetra_vec_pt, DoubleVector &oomph_vec)
Helper function to copy the contents of a Trilinos vector to an oomph-lib distributed vector....
void multiply(const CRDoubleMatrix *matrix, const DoubleVector &x, DoubleVector &soln)
Function to perform a matrix-vector multiplication on a oomph-lib matrix and vector using Trilinos fu...
Epetra_Map * create_epetra_map(const LinearAlgebraDistribution *const dist)
create an Epetra_Map corresponding to the LinearAlgebraDistribution
Epetra_Vector * create_distributed_epetra_vector(const DoubleVector &oomph_vec)
create an Epetra_Vector from an oomph-lib DoubleVector. If oomph_vec is NOT distributed (i....
Epetra_Vector * create_epetra_vector_view_data(DoubleVector &oomph_vec)
create an Epetra_Vector equivalent of DoubleVector The argument DoubleVector must be built....
//////////////////////////////////////////////////////////////////// ////////////////////////////////...