Line data Source code
1 : // The libMesh Finite Element Library.
2 : // Copyright (C) 2002-2025 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_base.h"
26 : #include "libmesh/libmesh_common.h"
27 : #include "libmesh/libmesh_config.h"
28 :
29 : // C++ includes
30 : #include <string>
31 : #include <vector>
32 :
33 : // Forward declarations
34 : // For dealing with MPI stuff in VTK.
35 : #if defined(LIBMESH_HAVE_MPI) && defined(LIBMESH_HAVE_VTK)
36 : class vtkMPIController;
37 : #endif
38 :
39 : namespace TIMPI {
40 : class TIMPIInit;
41 : }
42 :
43 : #ifdef GETPOT_NAMESPACE
44 : namespace GETPOT_NAMESPACE {
45 : #endif
46 : class GetPot;
47 : #ifdef GETPOT_NAMESPACE
48 : }
49 : #endif
50 :
51 : /**
52 : * The \p libMesh namespace provides an interface to certain functionality
53 : * in the library. Here, it provides a LibMeshInit class which uses
54 : * the RAII (Resource Acquisition Is Initialization) idiom to ensure
55 : * initialization of any other dependent libraries (e.g. MPI or PETSC),
56 : * and to close those libraries when it goes out of scope. It also
57 : * provides a centralized place for performance logging and other
58 : * functionality.
59 : */
60 : namespace libMesh
61 : {
62 :
63 : // Forward declarations
64 : namespace Parallel {
65 : class Communicator;
66 : }
67 :
68 : enum SolverPackage : int;
69 :
70 : /**
71 : * The \p LibMeshInit class, when constructed, initializes
72 : * the dependent libraries (e.g. MPI or PETSC) and does the
73 : * command line parsing needed by libMesh. The LibMeshInit
74 : * destructor closes those libraries properly.
75 : *
76 : * For most users, a single LibMeshInit object should be created at
77 : * the start of your main() function.
78 : *
79 : * All libMesh functionality should be used only when a LibMeshInit
80 : * object exists. Dependent library functionality, likewise, except
81 : * in codes which manually initialize those libraries before
82 : * LibMeshInit creation and finalize them after LibMeshInit
83 : * destruction.
84 : *
85 : * Since "it is best not to perform much more than a return rc after
86 : * calling MPI_Finalize", applications which want to do anything after
87 : * LibMeshInit destruction should manage MPI initialization and
88 : * finalization manually.
89 : */
90 : class LibMeshInit
91 : {
92 : public:
93 : #ifdef LIBMESH_HAVE_MPI
94 : /**
95 : * Initialize the library for use, with the command line options
96 : * provided. This will e.g. call MPI_Init if MPI is available and
97 : * enabled and has not already been initialized; similar
98 : * initialization may take place for Petsc, Slepc, multithreading
99 : * support, libMesh Singleton objects, the libMesh::out/err IO
100 : * streams, and any libMesh handlers for floating-point exceptions,
101 : * signals, and/or C++ aborts.
102 : *
103 : * You must create a LibMeshInit object before using any
104 : * of the library functionality. This method may take an optional
105 : * parameter to use a user-specified MPI communicator.
106 : */
107 : LibMeshInit(int argc, const char * const * argv,
108 : MPI_Comm COMM_WORLD_IN=MPI_COMM_WORLD, int n_threads=-1);
109 : #else
110 : LibMeshInit(int argc, const char * const * argv,
111 : int COMM_WORLD_IN=0, int n_threads=-1);
112 : #endif
113 :
114 : /**
115 : * Destructor. Cleans up libMesh Singleton objects, and thread
116 : * manager if threading is in use. Prints reference count and
117 : * performance logging information if enabled. Restores
118 : * pre-LibMeshInit terminate handler and floating-point-exception
119 : * handling. Finalizes any of Slepc, Petsc, and MPI which were
120 : * initialized by LibMeshInit.
121 : */
122 : virtual ~LibMeshInit();
123 :
124 : /**
125 : * Returns a Communicator created from the TIMPIInit object we hold,
126 : * which will be a compatibility shim if MPI is not enabled.
127 : */
128 : const Parallel::Communicator & comm() const { return *_comm; }
129 :
130 31094 : Parallel::Communicator & comm() { return *_comm; }
131 :
132 : private:
133 : // Should we just bite the bullet, use unique_ptr here, and bring an
134 : // #include <memory> into everything?
135 : TIMPI::TIMPIInit * _timpi_init;
136 :
137 : // Or should we keep this around so we can still inline its
138 : // accessors despite forward declaring _timpi_init?
139 : //
140 : // This is constructed from the TIMPI::Communicator, for backwards
141 : // compatibility.
142 : Parallel::Communicator * _comm;
143 :
144 : #if defined(LIBMESH_HAVE_MPI) && defined(LIBMESH_HAVE_VTK)
145 : // VTK object for dealing with MPI stuff in VTK.
146 : // This can't be a std::unique_ptr because VTK makes the destructor
147 : // protected and forces us to use a named destructor manually
148 : vtkMPIController * _vtk_mpi_controller;
149 : #endif
150 : };
151 :
152 : /**
153 : * Checks that library initialization has been done. If it
154 : * hasn't an error message is printed and the code aborts.
155 : * It is useful to \p libmesh_assert(libMesh::initialized()) in library
156 : * object constructors.
157 : */
158 : bool initialized ();
159 :
160 : /**
161 : * Checks that the library has been closed. This should
162 : * always return false when called from a library object.
163 : * It is useful to \p libmesh_assert(!libMesh::closed()) in library
164 : * object destructors.
165 : */
166 : bool closed ();
167 :
168 : /**
169 : * A terminate handler. libMesh sets this to handle uncaught
170 : * exceptions; it can also be called manually to print stack traces
171 : * and perf logs and call MPI
172 : */
173 : void libmesh_terminate_handler();
174 :
175 : /**
176 : * Toggle hardware trap floating point exceptions
177 : */
178 : void enableFPE(bool on);
179 :
180 : /**
181 : * Toggle libMesh reporting of segmentation faults
182 : */
183 : void enableSEGV(bool on);
184 :
185 : /**
186 : * \returns \p true if the argument \p arg was specified on the command line,
187 : * \p false otherwise.
188 : *
189 : * For backwards compatibility with past option naming conventions,
190 : * libMesh searches for the given argument first in its original form,
191 : * then with all underscores changed to dashes, then with all dashes
192 : * (except any leading dashes) changed to underscores, and returns
193 : * true if any of the above finds a match.
194 : *
195 : * This routine manipulates the command_line cursor and should not be
196 : * called concurrently with similar utilities in multiple threads.
197 : */
198 : bool on_command_line (std::string arg);
199 :
200 : /**
201 : * \returns The value associated with name on the command line if it is specified,
202 : * otherwise return the default, provided value. A second template function is provided
203 : * to support recognizing multiple variations of a given option
204 : *
205 : * This routine manipulates the command_line cursor and should not be
206 : * called concurrently with similar utilities in multiple threads.
207 : */
208 : template <typename T>
209 : T command_line_value (const std::string &, T);
210 : template <typename T>
211 : T command_line_value (const std::vector<std::string> &, T);
212 :
213 : /**
214 : * Use GetPot's search()/next() functions to get following arguments
215 : * from the command line.
216 : *
217 : * For backwards compatibility with past option naming conventions,
218 : * libMesh searches for the given argument first in its original form,
219 : * then with all underscores changed to dashes, then with all dashes
220 : * (except any leading dashes) changed to underscores, and returns
221 : * true if any of the above finds a match.
222 : *
223 : * This routine manipulates the command_line cursor and should not be
224 : * called concurrently with similar utilities in multiple threads.
225 : */
226 : template <typename T>
227 : T command_line_next (std::string name, T default_value);
228 :
229 : /**
230 : * \returns The array of values associated with name on the command line if it is specified,
231 : * otherwise return the default, provided array.
232 : *
233 : * This routine manipulates the command_line cursor and should not be
234 : * called concurrently with similar utilities in multiple threads.
235 : */
236 : template <typename T>
237 : void command_line_vector (const std::string &, std::vector<T> &);
238 :
239 : /**
240 : * \returns The set of names which this program has queried or
241 : * expected to query via the libMesh command line interface.
242 : *
243 : * This is useful for detecting any future conflicts with other
244 : * packages (such as PETSc) which manage command line values, and for
245 : * avoiding UFO warnings from such packages.
246 : */
247 : std::vector<std::string> command_line_names();
248 :
249 : /**
250 : * Add a name to the set of queried command-line names
251 : */
252 : void add_command_line_name(const std::string & name);
253 :
254 : /**
255 : * Merge a GetPot object's requested names into the set of queried
256 : * command-line names
257 : */
258 : void add_command_line_names(const GetPot & getpot);
259 :
260 :
261 : /**
262 : * The imaginary unit, \f$ \sqrt{-1} \f$.
263 : */
264 : #ifdef LIBMESH_USE_COMPLEX_NUMBERS
265 : extern const Number imaginary;
266 : #endif
267 :
268 : /**
269 : * \returns The default solver interface to use. The value depends on
270 : * which solver packages were available when the library was configured.
271 : * The command-line is also checked, allowing the user to override the
272 : * compiled default. For example, \p --use-petsc will force the use of
273 : * PETSc solvers, and \p --use-laspack will force the use of LASPACK
274 : * solvers.
275 : */
276 : SolverPackage default_solver_package ();
277 :
278 : /**
279 : * The C++ standard doesn't support literals at higher than long
280 : * double precision, so if we're in quadruple precision we need our
281 : * own user-defined literal operator.
282 : *
283 : * If we're not in quadruple precision then we just need a
284 : * zero-overhead passthrough.
285 : *
286 : * We'll use a simple _R since we're already qualified by the libMesh
287 : * namespace here.
288 : */
289 : #ifdef LIBMESH_DEFAULT_QUADRUPLE_PRECISION
290 : constexpr Real operator ""_R(const char * r) { return Real(r); }
291 : #else
292 456129 : constexpr Real operator ""_R(long double r) { return r; }
293 : constexpr Real operator ""_R(unsigned long long r) { return Real(r); }
294 : #endif
295 :
296 : /**
297 : * \f$ \pi=3.14159... \f$.
298 : */
299 : const Real pi = 3.1415926535897932384626433832795029_R;
300 :
301 : /**
302 : * \f$ zero=0. \f$.
303 : */
304 : const Number zero = 0.;
305 :
306 : /**
307 : * A number which is used quite often to represent
308 : * an invalid or uninitialized value for an unsigned integer.
309 : */
310 : const unsigned int invalid_uint = static_cast<unsigned int>(-1);
311 :
312 : /**
313 : * A number which is used quite often to represent
314 : * an invalid or uninitialized value for an integer.
315 : */
316 : const int invalid_int = std::numeric_limits<int>::max();
317 :
318 : } // namespace libMesh
319 :
320 : #endif // LIBMESH_LIBMESH_H
|
