MFEM  v4.2.0
Finite element discretization library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
handle.hpp
Go to the documentation of this file.
1 // Copyright (c) 2010-2020, Lawrence Livermore National Security, LLC. Produced
2 // at the Lawrence Livermore National Laboratory. All Rights reserved. See files
3 // LICENSE and NOTICE for details. LLNL-CODE-806117.
4 //
5 // This file is part of the MFEM library. For more information and source code
6 // availability visit https://mfem.org.
7 //
8 // MFEM is free software; you can redistribute it and/or modify it under the
9 // terms of the BSD-3 license. We welcome feedback and contributions, see file
10 // CONTRIBUTING.md for details.
11 
12 #ifndef MFEM_HANDLE_HPP
13 #define MFEM_HANDLE_HPP
14 
15 #include "../config/config.hpp"
16 #include "operator.hpp"
17 #ifdef MFEM_USE_MPI
18 #include "hypre.hpp"
19 #endif
20 
21 namespace mfem
22 {
23 
24 /// Pointer to an Operator of a specified type
25 /** This class provides a common interface for global, matrix-type operators to
26  be used in bilinear forms, gradients of nonlinear forms, static condensation,
27  hybridization, etc. The following backends are currently supported:
28  - HYPRE parallel sparse matrix (Hypre_ParCSR)
29  - PETSC globally assembled parallel sparse matrix (PETSC_MATAIJ)
30  - PETSC parallel matrix assembled on each processor (PETSC_MATIS)
31  See also Operator::Type.
32 */
34 {
35 protected:
36  static const char not_supported_msg[];
37 
40  bool own_oper;
41 
43 
44  template <typename OpType>
45  void pSet(OpType *A, bool own_A = true)
46  {
47  oper = A;
48  type_id = A->GetType();
49  own_oper = own_A;
50  }
51 
52 public:
53  /** @brief Create an OperatorHandle with type id = Operator::MFEM_SPARSEMAT
54  without allocating the actual matrix. */
56  : oper(NULL), type_id(Operator::MFEM_SPARSEMAT), own_oper(false) { }
57 
58  /** @brief Create a OperatorHandle with a specified type id, @a tid, without
59  allocating the actual matrix. */
61  : oper(NULL), type_id(CheckType(tid)), own_oper(false) { }
62 
63  /// Create an OperatorHandle for the given OpType pointer, @a A.
64  /** Presently, OpType can be SparseMatrix, HypreParMatrix, or PetscParMatrix.
65 
66  The operator ownership flag is set to the value of @a own_A.
67 
68  It is expected that @a A points to a valid object. */
69  template <typename OpType>
70  explicit OperatorHandle(OpType *A, bool own_A = true) { pSet(A, own_A); }
71 
72  ~OperatorHandle() { if (own_oper) { delete oper; } }
73 
74  /// Shallow copy. The ownership flag of the target is set to false.
76  {
77  Clear(); oper = master.oper; type_id = master.type_id; own_oper = false;
78  return *this;
79  }
80 
81  /// Access the underlying Operator pointer.
82  Operator *Ptr() const { return oper; }
83 
84  /// Support the use of -> to call methods of the underlying Operator.
85  Operator *operator->() const { return oper; }
86 
87  /// Access the underlying Operator.
88  Operator &operator*() { return *oper; }
89 
90  /// Get the currently set operator type id.
91  Operator::Type Type() const { return type_id; }
92 
93  /** @brief Return the Operator pointer statically cast to a specified OpType.
94  Similar to the method Get(). */
95  template <typename OpType>
96  OpType *As() const { return static_cast<OpType*>(oper); }
97 
98  /// Return the Operator pointer dynamically cast to a specified OpType.
99  template <typename OpType>
100  OpType *Is() const { return dynamic_cast<OpType*>(oper); }
101 
102  /// Return the Operator pointer statically cast to a given OpType.
103  /** Similar to the method As(), however the template type OpType can be
104  derived automatically from the argument @a A. */
105  template <typename OpType>
106  void Get(OpType *&A) const { A = static_cast<OpType*>(oper); }
107 
108  /// Return true if the OperatorHandle owns the held Operator.
109  bool OwnsOperator() const { return own_oper; }
110 
111  /// Set the ownership flag for the held Operator.
112  void SetOperatorOwner(bool own = true) { own_oper = own; }
113 
114  /** @brief Clear the OperatorHandle, deleting the held Operator (if owned),
115  while leaving the type id unchanged. */
116  void Clear()
117  {
118  if (own_oper) { delete oper; }
119  oper = NULL;
120  own_oper = false;
121  }
122 
123  /// Invoke Clear() and set a new type id.
125  {
126  Clear();
127  type_id = CheckType(tid);
128  }
129 
130  /// Reset the OperatorHandle to the given OpType pointer, @a A.
131  /** Presently, OpType can be SparseMatrix, HypreParMatrix, or PetscParMatrix.
132 
133  The operator ownership flag is set to the value of @a own_A.
134 
135  It is expected that @a A points to a valid object. */
136  template <typename OpType>
137  void Reset(OpType *A, bool own_A = true)
138  {
139  if (own_oper) { delete oper; }
140  pSet(A, own_A);
141  }
142 
143 #ifdef MFEM_USE_MPI
144  /** @brief Reset the OperatorHandle to hold a parallel square block-diagonal
145  matrix using the currently set type id. */
146  /** The operator ownership flag is set to true. */
147  void MakeSquareBlockDiag(MPI_Comm comm, HYPRE_Int glob_size,
148  HYPRE_Int *row_starts, SparseMatrix *diag);
149 
150  /** @brief Reset the OperatorHandle to hold a parallel rectangular
151  block-diagonal matrix using the currently set type id. */
152  /** The operator ownership flag is set to true. */
153  void MakeRectangularBlockDiag(MPI_Comm comm, HYPRE_Int glob_num_rows,
154  HYPRE_Int glob_num_cols, HYPRE_Int *row_starts,
155  HYPRE_Int *col_starts, SparseMatrix *diag);
156 #endif // MFEM_USE_MPI
157 
158  /// Reset the OperatorHandle to hold the product @a P^t @a A @a P.
159  /** The type id of the result is determined by that of @a A and @a P. The
160  operator ownership flag is set to true. */
162 
163  /** @brief Reset the OperatorHandle to hold the product R @a A @a P, where
164  R = @a Rt^t. */
165  /** The type id of the result is determined by that of @a Rt, @a A, and @a P.
166  The operator ownership flag is set to true. */
168 
169  /// Convert the given OperatorHandle @a A to the currently set type id.
170  /** The operator ownership flag is set to false if the object held by @a A
171  will be held by this object as well, e.g. when the source and destination
172  types are the same; otherwise it is set to true. */
173  void ConvertFrom(OperatorHandle &A);
174 
175  /// Convert the given OpType pointer, @a A, to the currently set type id.
176  /** This method creates a temporary OperatorHandle for @a A and invokes
177  ConvertFrom(OperatorHandle &) with it. */
178  template <typename OpType>
179  void ConvertFrom(OpType *A)
180  {
181  OperatorHandle Ah(A, false);
182  ConvertFrom(Ah);
183  }
184 
185  /** @brief Reset the OperatorHandle to be the eliminated part of @a A after
186  elimination of the essential dofs @a ess_dof_list. */
187  void EliminateRowsCols(OperatorHandle &A, const Array<int> &ess_dof_list);
188 
189  /// Eliminate the rows corresponding to the essential dofs @a ess_dof_list
190  void EliminateRows(const Array<int> &ess_dof_list);
191 
192  /// Eliminate columns corresponding to the essential dofs @a ess_dof_list
193  void EliminateCols(const Array<int> &ess_dof_list);
194 
195  /// Eliminate essential dofs from the solution @a X into the r.h.s. @a B.
196  /** The argument @a A_e is expected to be the result of the method
197  EliminateRowsCols(). */
198  void EliminateBC(const OperatorHandle &A_e, const Array<int> &ess_dof_list,
199  const Vector &X, Vector &B) const;
200 };
201 
202 
203 /// Add an alternative name for OperatorHandle -- OperatorPtr.
205 
206 } // namespace mfem
207 
208 #endif
OperatorHandle()
Create an OperatorHandle with type id = Operator::MFEM_SPARSEMAT without allocating the actual matrix...
Definition: handle.hpp:55
void ConvertFrom(OperatorHandle &A)
Convert the given OperatorHandle A to the currently set type id.
Definition: handle.cpp:200
OpType * As() const
Return the Operator pointer statically cast to a specified OpType. Similar to the method Get()...
Definition: handle.hpp:96
Pointer to an Operator of a specified type.
Definition: handle.hpp:33
Operator::Type Type() const
Get the currently set operator type id.
Definition: handle.hpp:91
void EliminateBC(const OperatorHandle &A_e, const Array< int > &ess_dof_list, const Vector &X, Vector &B) const
Eliminate essential dofs from the solution X into the r.h.s. B.
Definition: handle.cpp:340
void EliminateRows(const Array< int > &ess_dof_list)
Eliminate the rows corresponding to the essential dofs ess_dof_list.
Definition: handle.cpp:303
Operator * oper
Definition: handle.hpp:38
void EliminateCols(const Array< int > &ess_dof_list)
Eliminate columns corresponding to the essential dofs ess_dof_list.
Definition: handle.cpp:321
static const char not_supported_msg[]
Definition: handle.hpp:36
Operator & operator*()
Access the underlying Operator.
Definition: handle.hpp:88
OpType * Is() const
Return the Operator pointer dynamically cast to a specified OpType.
Definition: handle.hpp:100
Data type sparse matrix.
Definition: sparsemat.hpp:46
void EliminateRowsCols(OperatorHandle &A, const Array< int > &ess_dof_list)
Reset the OperatorHandle to be the eliminated part of A after elimination of the essential dofs ess_d...
Definition: handle.cpp:252
Operator::Type CheckType(Operator::Type tid)
Definition: handle.cpp:32
Operator * operator->() const
Support the use of -&gt; to call methods of the underlying Operator.
Definition: handle.hpp:85
Operator * Ptr() const
Access the underlying Operator pointer.
Definition: handle.hpp:82
Type
Enumeration defining IDs for some classes derived from Operator.
Definition: operator.hpp:237
bool OwnsOperator() const
Return true if the OperatorHandle owns the held Operator.
Definition: handle.hpp:109
OperatorHandle OperatorPtr
Add an alternative name for OperatorHandle – OperatorPtr.
Definition: handle.hpp:204
OperatorHandle(Operator::Type tid)
Create a OperatorHandle with a specified type id, tid, without allocating the actual matrix...
Definition: handle.hpp:60
void ConvertFrom(OpType *A)
Convert the given OpType pointer, A, to the currently set type id.
Definition: handle.hpp:179
void Clear()
Clear the OperatorHandle, deleting the held Operator (if owned), while leaving the type id unchanged...
Definition: handle.hpp:116
void SetOperatorOwner(bool own=true)
Set the ownership flag for the held Operator.
Definition: handle.hpp:112
void MakeSquareBlockDiag(MPI_Comm comm, HYPRE_Int glob_size, HYPRE_Int *row_starts, SparseMatrix *diag)
Reset the OperatorHandle to hold a parallel square block-diagonal matrix using the currently set type...
Definition: handle.cpp:60
void pSet(OpType *A, bool own_A=true)
Definition: handle.hpp:45
Operator::Type type_id
Definition: handle.hpp:39
void MakeRectangularBlockDiag(MPI_Comm comm, HYPRE_Int glob_num_rows, HYPRE_Int glob_num_cols, HYPRE_Int *row_starts, HYPRE_Int *col_starts, SparseMatrix *diag)
Reset the OperatorHandle to hold a parallel rectangular block-diagonal matrix using the currently set...
Definition: handle.cpp:91
void Get(OpType *&A) const
Return the Operator pointer statically cast to a given OpType.
Definition: handle.hpp:106
Vector data type.
Definition: vector.hpp:51
OperatorHandle & operator=(const OperatorHandle &master)
Shallow copy. The ownership flag of the target is set to false.
Definition: handle.hpp:75
Abstract operator.
Definition: operator.hpp:24
void MakePtAP(OperatorHandle &A, OperatorHandle &P)
Reset the OperatorHandle to hold the product P^t A P.
Definition: handle.cpp:123
void SetType(Operator::Type tid)
Invoke Clear() and set a new type id.
Definition: handle.hpp:124
void MakeRAP(OperatorHandle &Rt, OperatorHandle &A, OperatorHandle &P)
Reset the OperatorHandle to hold the product R A P, where R = Rt^t.
Definition: handle.cpp:161
OperatorHandle(OpType *A, bool own_A=true)
Create an OperatorHandle for the given OpType pointer, A.
Definition: handle.hpp:70
void Reset(OpType *A, bool own_A=true)
Reset the OperatorHandle to the given OpType pointer, A.
Definition: handle.hpp:137