1 // The libMesh Finite Element Library. 2 // Copyright (C) 2002-2020 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner 3 4 // This library is free software; you can redistribute it and/or 5 // modify it under the terms of the GNU Lesser General Public 6 // License as published by the Free Software Foundation; either 7 // version 2.1 of the License, or (at your option) any later version. 8 9 // This library is distributed in the hope that it will be useful, 10 // but WITHOUT ANY WARRANTY; without even the implied warranty of 11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 // Lesser General Public License for more details. 13 14 // You should have received a copy of the GNU Lesser General Public 15 // License along with this library; if not, write to the Free Software 16 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 17 18 19 20 #ifndef LIBMESH_LIBMESH_H 21 #define LIBMESH_LIBMESH_H 22 23 24 // Local includes 25 #include "libmesh/libmesh_common.h" 26 #include "libmesh/libmesh_base.h" 27 28 #ifdef LIBMESH_FORWARD_DECLARE_ENUMS 29 namespace libMesh 30 { 31 enum SolverPackage : int; 32 } 33 #else 34 #include "libmesh/enum_solver_package.h" 35 #endif 36 37 // C++ includes 38 #include <string> 39 #include <vector> 40 41 // For dealing with MPI stuff in VTK. 42 #if defined(LIBMESH_HAVE_MPI) && defined(LIBMESH_HAVE_VTK) 43 class vtkMPIController; 44 #endif 45 46 /** 47 * The \p libMesh namespace provides an interface to certain functionality 48 * in the library. Here, it provides a LibMeshInit class which uses 49 * the RAII (Resource Acquisition Is Initialization) idiom to ensure 50 * initialization of any other dependent libraries (e.g. MPI or PETSC), 51 * and to close those libraries when it goes out of scope. It also 52 * provides a centralized place for performance logging and other 53 * functionality. 54 */ 55 namespace libMesh 56 { 57 58 // Forward declarations 59 namespace Parallel { 60 class Communicator; 61 } 62 63 /** 64 * The \p LibMeshInit class, when constructed, initializes 65 * the dependent libraries (e.g. MPI or PETSC) and does the 66 * command line parsing needed by libMesh. The LibMeshInit 67 * destructor closes those libraries properly. 68 * 69 * For most users, a single LibMeshInit object should be created at 70 * the start of your main() function. 71 * 72 * All libMesh functionality should be used only when a LibMeshInit 73 * object exists. Dependent library functionality, likewise, except 74 * in codes which manually initialize those libraries before 75 * LibMeshInit creation and finalize them after LibMeshInit 76 * destruction. 77 * 78 * Since "it is best not to perform much more than a return rc after 79 * calling MPI_Finalize", applications which want to do anything after 80 * LibMeshInit destruction should manage MPI initialization and 81 * finalization manually. 82 */ 83 class LibMeshInit 84 { 85 public: 86 #ifdef LIBMESH_HAVE_MPI 87 /** 88 * Initialize the library for use, with the command line options 89 * provided. This will e.g. call MPI_Init if MPI is available and 90 * enabled and has not already been initialized; similar 91 * initialization may take place for Petsc, Slepc, multithreading 92 * support, libMesh Singleton objects, the libMesh::out/err IO 93 * streams, and any libMesh handlers for floating-point exceptions, 94 * signals, and/or C++ aborts. 95 * 96 * You must create a LibMeshInit object before using any 97 * of the library functionality. This method may take an optional 98 * parameter to use a user-specified MPI communicator. 99 */ 100 LibMeshInit(int argc, const char * const * argv, 101 MPI_Comm COMM_WORLD_IN=MPI_COMM_WORLD, int n_threads=-1); 102 #else 103 LibMeshInit(int argc, const char * const * argv, 104 int COMM_WORLD_IN=0, int n_threads=-1); 105 #endif 106 107 /** 108 * Destructor. Cleans up libMesh Singleton objects, and thread 109 * manager if threading is in use. Prints reference count and 110 * performance logging information if enabled. Restores 111 * pre-LibMeshInit terminate handler and floating-point-exception 112 * handling. Finalizes any of Slepc, Petsc, and MPI which were 113 * initialized by LibMeshInit. 114 */ 115 virtual ~LibMeshInit(); 116 117 /** 118 * Returns the Communicator created by this libMesh object, which 119 * will be a compatibility shim if MPI is not enabled, or a wrapper 120 * for the user-input MPI_Comm if we were constructed with one, or a 121 * wrapper for MPI_COMM_WORLD by default. 122 */ comm()123 const Parallel::Communicator & comm() const { return *_comm; } 124 comm()125 Parallel::Communicator & comm() { return *_comm; } 126 127 private: 128 Parallel::Communicator * _comm; 129 130 #if defined(LIBMESH_HAVE_MPI) && defined(LIBMESH_HAVE_VTK) 131 // VTK object for dealing with MPI stuff in VTK. 132 // This can't be a std::unique_ptr because VTK makes the destructor 133 // protected and forces us to use a named destructor manually 134 vtkMPIController * _vtk_mpi_controller; 135 #endif 136 }; 137 138 /** 139 * Checks that library initialization has been done. If it 140 * hasn't an error message is printed and the code aborts. 141 * It is useful to \p libmesh_assert(libMesh::initialized()) in library 142 * object constructors. 143 */ 144 bool initialized (); 145 146 /** 147 * Checks that the library has been closed. This should 148 * always return false when called from a library object. 149 * It is useful to \p libmesh_assert(!libMesh::closed()) in library 150 * object destructors. 151 */ 152 bool closed (); 153 154 /** 155 * Toggle hardware trap floating point exceptions 156 */ 157 void enableFPE(bool on); 158 159 /** 160 * Toggle libMesh reporting of segmentation faults 161 */ 162 void enableSEGV(bool on); 163 164 /** 165 * \returns \p true if the argument \p arg was specified on the command line, 166 * \p false otherwise. 167 * 168 * For backwards compatibility with past option naming conventions, 169 * libMesh searches for the given argument first in its original form, 170 * then with all underscores changed to dashes, then with all dashes 171 * (except any leading dashes) changed to underscores, and returns 172 * true if any of the above finds a match. 173 * 174 * This routine manipulates the command_line cursor and should not be 175 * called concurrently with similar utilities in multiple threads. 176 */ 177 bool on_command_line (std::string arg); 178 179 /** 180 * \returns The value associated with name on the command line if it is specified, 181 * otherwise return the default, provided value. A second template function is provided 182 * to support recognizing multiple variations of a given option 183 * 184 * This routine manipulates the command_line cursor and should not be 185 * called concurrently with similar utilities in multiple threads. 186 */ 187 template <typename T> 188 T command_line_value (const std::string &, T); 189 template <typename T> 190 T command_line_value (const std::vector<std::string> &, T); 191 192 /** 193 * Use GetPot's search()/next() functions to get following arguments 194 * from the command line. 195 * 196 * For backwards compatibility with past option naming conventions, 197 * libMesh searches for the given argument first in its original form, 198 * then with all underscores changed to dashes, then with all dashes 199 * (except any leading dashes) changed to underscores, and returns 200 * true if any of the above finds a match. 201 * 202 * This routine manipulates the command_line cursor and should not be 203 * called concurrently with similar utilities in multiple threads. 204 */ 205 template <typename T> 206 T command_line_next (std::string name, T default_value); 207 208 /** 209 * \returns The array of values associated with name on the command line if it is specified, 210 * otherwise return the default, provided array. 211 * 212 * This routine manipulates the command_line cursor and should not be 213 * called concurrently with similar utilities in multiple threads. 214 */ 215 template <typename T> 216 void command_line_vector (const std::string &, std::vector<T> &); 217 218 /** 219 * The imaginary unit, \f$ \sqrt{-1} \f$. 220 */ 221 #ifdef LIBMESH_USE_COMPLEX_NUMBERS 222 extern const Number imaginary; 223 #endif 224 225 /** 226 * \returns The default solver interface to use. The value depends on 227 * which solver packages were available when the library was configured. 228 * The command-line is also checked, allowing the user to override the 229 * compiled default. For example, \p --use-petsc will force the use of 230 * PETSc solvers, and \p --use-laspack will force the use of LASPACK 231 * solvers. 232 */ 233 SolverPackage default_solver_package (); 234 235 /** 236 * \f$ \pi=3.14159... \f$. 237 */ 238 const Real pi = 239 static_cast<Real>(3.1415926535897932384626433832795029L); 240 241 /** 242 * \f$ zero=0. \f$. 243 */ 244 const Number zero = 0.; 245 246 /** 247 * A number which is used quite often to represent 248 * an invalid or uninitialized value for an unsigned integer. 249 */ 250 const unsigned int invalid_uint = static_cast<unsigned int>(-1); 251 252 /** 253 * A number which is used quite often to represent 254 * an invalid or uninitialized value for an integer. 255 */ 256 const int invalid_int = std::numeric_limits<int>::max(); 257 258 } // namespace libMesh 259 260 #endif // LIBMESH_LIBMESH_H 261