Cantera  3.1.0a1
global.h
Go to the documentation of this file.
1 /**
2  * @file global.h
3  * This file contains definitions for utility functions and text for modules,
4  * inputfiles and logging, (see @ref inputGroup, and @ref logGroup).
5  *
6  * These functions store some parameters in global storage that are accessible
7  * at all times from the calling application. Contains module definitions for
8  * - inputfiles (see @ref inputGroup)
9  * - text logs (see @ref logGroup)
10  */
11 
12 // This file is part of Cantera. See License.txt in the top-level directory or
13 // at https://cantera.org/license.txt for license and copyright information.
14 
15 #ifndef CT_GLOBAL_H
16 #define CT_GLOBAL_H
17 
18 #include "ct_defs.h"
19 #include "cantera/base/fmt.h"
20 
21 namespace Cantera
22 {
23 
24 class Logger;
25 class AnyMap;
26 
27 //! @defgroup ioGroup File Input/Output
28 //! @details Classes and functions used for reading and writing of %Cantera input files.
29 
30 /**
31  * @defgroup inputGroup Input File Handling
32  * @brief Handling of %Cantera input files.
33  *
34  * The properties of phases and interfaces are specified in text files. These
35  * procedures handle various aspects of reading these files. Input files should be read
36  * using the newSolution() or newInterface() service functions (see @ref solnGroup).
37  *
38  * For input files not specified by an absolute pathname, %Cantera searches
39  * for input files along a path that includes platform-specific default
40  * locations, and possibly user-specified locations:
41  *
42  * - The current directory @c "." is always searched first. Then, on Windows, the
43  * registry is checked to find the %Cantera installation directory, and the
44  * @c data subdirectory of the installation directory will be added to the search
45  * path.
46  * - On any platform, if environment variable @c CANTERA_DATA is set to a directory
47  * name or a list of directory names separated with the OS-dependent path
48  * separator (that is, @c ";" on Windows, @c ":" elsewhere), then these directories
49  * will be added to the search path.
50  * - Finally, the location where the data files were installed when %Cantera was
51  * built is added to the search path.
52  * - Additional directories may be added dynamically by calling the addDirectory()
53  * function.
54  *
55  * %Cantera input files are written using YAML syntax. For more information on using
56  * YAML files in %Cantera, see the
57  * [YAML Users' Guide](https://cantera.org/tutorials/yaml/defining-phases.html)
58  * or the [YAML Input File API Reference](../../../../sphinx/html/yaml/index.html).
59  * %Cantera provides the
60  * [`ck2yaml`](https://cantera.org/tutorials/ck2yaml-tutorial.html)
61  * tool for converting Chemkin-format mechanisms to the YAML format. The utilities
62  * [`cti2yaml`](https://cantera.org/tutorials/legacy2yaml.html#cti2yaml) and
63  * [`ctml2yaml`](https://cantera.org/tutorials/legacy2yaml.html#ctml2yaml) should be
64  * used to convert legacy CTI and XML input files (from %Cantera 2.6 and earlier) to the
65  * YAML format.
66  *
67  * @ingroup ioGroup
68  * @{
69  */
70 
71 //! @copydoc Application::findInputFile
72 string findInputFile(const string& name);
73 
74 //! @copydoc Application::addDataDirectory
75 void addDirectory(const string& dir);
76 
77 //! @copydoc Application::getDataDirectories
78 string getDataDirectories(const string& sep);
79 //! @}
80 
81 //! @copydoc Application::loadExtension
82 void loadExtension(const string& extType, const string& name);
83 
84 //! Load extensions providing user-defined models from the `extensions` section of the
85 //! given node. @see Application::loadExtension
86 //!
87 //! @since New in %Cantera 3.0
88 void loadExtensions(const AnyMap& node);
89 
90 //! @copydoc Application::searchPythonVersions
91 void searchPythonVersions(const string& versions);
92 
93 //! Delete and free all memory associated with the application
94 /*!
95  * Delete all global data. It should be called at the end of the
96  * application if leak checking is to be done.
97  */
98 void appdelete();
99 
100 //! @copydoc Application::thread_complete
101 void thread_complete();
102 
103 //! @defgroup globalSettings Global Cantera Settings
104 //! @brief Functions for accessing global %Cantera settings.
105 //! @ingroup globalData
106 
107 //! @addtogroup globalSettings
108 //! @{
109 
110 //! Returns `true` if %Cantera was loaded as a shared library in the current
111 //! application. Returns `false` if it was statically linked.
112 //! @since New in %Cantera 3.0
114 
115 //! @name %Cantera Version Information
116 //! @{
117 
118 //! Returns the %Cantera version. This function is used to access the version from a
119 //! library, rather than the @c CANTERA_VERSION macro that is available at compile time.
120 //! @since New in %Cantera 3.0
121 string version();
122 
123 //! Returns the hash of the git commit from which %Cantera was compiled, if known
124 string gitCommit();
125 
126 //! @}
127 
128 //! Returns true if %Cantera was compiled in debug mode. Used for handling some cases
129 //! where behavior tested in the test suite changes depending on whether the `NDEBUG`
130 //! preprocessor macro is defined.
131 bool debugModeEnabled();
132 
133 //! Returns true if %Cantera was compiled with C++ @c HDF5 support.
134 //! @since New in %Cantera 3.0.
135 bool usesHDF5();
136 
137 //! @}
138 
139 /**
140  * @defgroup logGroup Logging
141  * @brief Logging and generation of diagnostic output.
142  *
143  * Writing diagnostic information to the screen or to a file. It is often
144  * useful to be able to write diagnostic messages to the screen or to a file.
145  * %Cantera defines a set of procedures for this purpose designed to write text messages
146  * to the screen to document the progress of a complex calculation, such as a
147  * flame simulation.
148  * @ingroup debugGroup
149  */
150 
151 //! @addtogroup logGroup
152 //! @{
153 
154 //! @copydoc Application::Messages::writelog(const string&)
155 void writelog_direct(const string& msg);
156 
157 //! Write a message to the log only if loglevel > 0
158 inline void debuglog(const string& msg, int loglevel)
159 {
160  if (loglevel > 0) {
161  writelog_direct(msg);
162  }
163 }
164 
165 //! Write a formatted message to the screen.
166 //!
167 //! This function passes its arguments to the fmt library 'format' function to
168 //! generate a formatted string from a Python-style (curly braces) format
169 //! string. This method is used throughout %Cantera to write log messages. It can
170 //! also be called by user programs. The advantage of using writelog over
171 //! writing directly to the standard output is that messages written with
172 //! writelog will display correctly even when %Cantera is used from MATLAB or
173 //! other application that do not have a standard output stream.
174 template <typename... Args>
175 void writelog(const string& fmt, const Args&... args) {
176  if (sizeof...(args) == 0) {
177  writelog_direct(fmt);
178  } else {
179  writelog_direct(fmt::format(fmt, args...));
180  }
181 }
182 
183 //! Write a formatted message to the screen
184 /*!
185  * Using the printf formatting of C, write a message to the screen
186  * with variable values.
187  *
188  * Here, we format an internal string with the correct values
189  * and then feed it into writelog().
190  *
191  * @param fmt c format string for the following arguments
192  * @param args arguments used to interpolate the format string
193  */
194 template <typename... Args>
195 void writelogf(const char* fmt, const Args& ... args) {
196  writelog_direct(fmt::sprintf(fmt, args...));
197 }
198 
199 //! Write an end of line character to the screen and flush output
200 void writelogendl();
201 
202 void writeline(char repeat, size_t count,
203  bool endl_after=true, bool endl_before=false);
204 
205 //! @} End of logging group
206 
207 //! @defgroup warnGroup Warnings
208 //! @ingroup debugGroup
209 //! @brief Warnings raised by %Cantera
210 //! @{
211 
212 //! @cond
213 
214 //! helper function passing deprecation warning to global handler
215 void _warn_deprecated(const string& method, const string& extra="");
216 
217 //! @endcond
218 
219 //! Print a deprecation warning raised from *method*.
220 /*!
221 * @see Application::warn_deprecated
222  * @param method method name
223  * @param msg Python-style format string with the following arguments
224  * @param args arguments for the format string
225  */
226 template <typename... Args>
227 void warn_deprecated(const string& method, const string& msg, const Args&... args) {
228  if (sizeof...(args) == 0) {
229  _warn_deprecated(method, msg);
230  } else {
231  _warn_deprecated(method, fmt::format(msg, args...));
232  }
233 }
234 
235 //! @cond
236 
237 //! helper function passing generic warning to global handler
238 void _warn(const string& warning, const string& method, const string& extra);
239 
240 //! @endcond
241 
242 //! Print a generic warning raised from *method*.
243 /*!
244  * @see Application::warn
245  * @param warning type of warning; See Logger::warn
246  * @param method method name
247  * @param msg Python-style format string with the following arguments
248  * @param args arguments for the format string
249  */
250 template <typename... Args>
251 void warn(const string& warning, const string& method,
252  const string& msg, const Args&... args) {
253  if (sizeof...(args) == 0) {
254  _warn(warning, method, msg);
255  } else {
256  _warn(warning, method, fmt::format(msg, args...));
257  }
258 }
259 
260 //! Print a user warning raised from *method* as `CanteraWarning`.
261 /*!
262  * @param method method name
263  * @param msg Python-style format string with the following arguments
264  * @param args arguments for the format string
265  */
266 template <typename... Args>
267 void warn_user(const string& method, const string& msg, const Args&... args) {
268  if (sizeof...(args) == 0) {
269  _warn("Cantera", method, msg);
270  } else {
271  _warn("Cantera", method, fmt::format(msg, args...));
272  }
273 }
274 
275 //! @} End of warnings group
276 
277 //! @addtogroup globalSettings
278 //! @{
279 
280 //! @name Global Warning Settings
281 //! @{
282 
283 //! @copydoc Application::suppress_deprecation_warnings
285 
286 //! @copydoc Application::make_deprecation_warnings_fatal
288 
289 //! @copydoc Application::make_warnings_fatal
290 void make_warnings_fatal();
291 
292 //! @copydoc Application::suppress_thermo_warnings
293 void suppress_thermo_warnings(bool suppress=true);
294 
295 //! @copydoc Application::thermo_warnings_suppressed
297 
298 //! @copydoc Application::suppress_warnings
299 void suppress_warnings();
300 
301 //! @copydoc Application::warnings_suppressed
302 bool warnings_suppressed();
303 
304 //! @} End of warning settings
305 
306 //! @copydoc Application::use_legacy_rate_constants
307 void use_legacy_rate_constants(bool legacy=true);
308 
309 //! @copydoc Application::legacy_rate_constants_used
311 
312 // @} End of globalSettings group
313 
314 //! @copydoc Application::Messages::setLogger
315 //! @ingroup logGroup
316 void setLogger(Logger* logwriter);
317 
318 //! Enables printing a stacktrace to `std::err` if a segfault occurs. The Boost
319 //! documentation says doing this from an error handler is not safe on all platforms
320 //! and risks deadlocking. However, it can be useful for debugging and is therefore
321 //! enabled when running tests.
322 //! @since New in %Cantera 3.0
323 //! @ingroup globalSettings
325 
326 //! Clip *value* such that lower <= value <= upper
327 //! @ingroup mathTemplates
328 template <class T>
329 inline T clip(const T& value, const T& lower, const T& upper)
330 {
331  return std::max(lower, std::min(upper, value));
332 }
333 
334 //! Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.
335 //! @ingroup mathTemplates
336 template <typename T> int sign(T x) {
337  return (T(0) < x) - (x < T(0));
338 }
339 
340 //! Convert a type name to a human readable string, using `boost::core::demangle` if
341 //! available. Also has a set of short names for some common types.
342 //! @note Mainly for internal use by AnyMap and Delegator
343 string demangle(const std::type_info& type);
344 
345 }
346 
347 #endif
This file contains definitions of constants, types and terms that are used in internal routines and a...
Wrapper for either system-installed or local headers for fmt.
bool warnings_suppressed()
Returns true if warnings should be suppressed.
Definition: global.cpp:82
void use_legacy_rate_constants(bool legacy)
Set definition used for rate constant calculation.
Definition: global.cpp:102
bool debugModeEnabled()
Returns true if Cantera was compiled in debug mode.
Definition: global.cpp:193
string demangle(const std::type_info &type)
Convert a type name to a human readable string, using boost::core::demangle if available.
Definition: global.cpp:213
void suppress_deprecation_warnings()
Globally disable printing of deprecation warnings.
Definition: global.cpp:67
void printStackTraceOnSegfault()
Enables printing a stacktrace to std::err if a segfault occurs.
Definition: global.cpp:125
bool thermo_warnings_suppressed()
Returns true if thermo warnings should be suppressed.
Definition: global.cpp:97
void make_warnings_fatal()
Turns Cantera warnings into exceptions.
Definition: global.cpp:87
string version()
Returns the Cantera version.
Definition: global.cpp:145
void make_deprecation_warnings_fatal()
Turns deprecation warnings into exceptions.
Definition: global.cpp:72
bool usingSharedLibrary()
Returns true if Cantera was loaded as a shared library in the current application.
bool legacy_rate_constants_used()
Returns true if legacy rate constant definition is used.
Definition: global.cpp:107
void suppress_warnings()
Globally disable printing of (user) warnings.
Definition: global.cpp:77
void suppress_thermo_warnings(bool suppress)
Globally disable printing of warnings about problematic thermo data, such as NASA polynomials with di...
Definition: global.cpp:92
string gitCommit()
Returns the hash of the git commit from which Cantera was compiled, if known.
Definition: global.cpp:150
bool usesHDF5()
Returns true if Cantera was compiled with C++ HDF5 support.
Definition: global.cpp:202
string getDataDirectories(const string &sep)
Get the Cantera data directories.
Definition: global.cpp:164
string findInputFile(const string &name)
Find an input file.
Definition: global.cpp:169
void addDirectory(const string &dir)
Add a directory to the data file search path.
Definition: global.cpp:159
void writelog_direct(const string &msg)
Write a message to the screen.
Definition: global.cpp:36
void debuglog(const string &msg, int loglevel)
Write a message to the log only if loglevel > 0.
Definition: global.h:158
void setLogger(Logger *logwriter)
Install a logger.
Definition: global.cpp:27
void writelogf(const char *fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:195
void writelog(const string &fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:175
void writelogendl()
Write an end of line character to the screen and flush output.
Definition: global.cpp:41
T clip(const T &value, const T &lower, const T &upper)
Clip value such that lower <= value <= upper.
Definition: global.h:329
int sign(T x)
Sign of a number.
Definition: global.h:336
void warn(const string &warning, const string &method, const string &msg, const Args &... args)
Print a generic warning raised from method.
Definition: global.h:251
void warn_user(const string &method, const string &msg, const Args &... args)
Print a user warning raised from method as CanteraWarning.
Definition: global.h:267
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:564
void loadExtensions(const AnyMap &node)
Load extensions providing user-defined models from the extensions section of the given node.
Definition: global.cpp:179
void loadExtension(const string &extType, const string &name)
Load an extension implementing user-defined models.
Definition: global.cpp:174
void searchPythonVersions(const string &versions)
Set the versions of Python to try when loading user-defined extensions, in order of preference.
Definition: global.cpp:189
void thread_complete()
Delete and free memory allocated per thread in multithreaded applications.
Definition: global.cpp:140
void warn_deprecated(const string &source, const AnyBase &node, const string &message)
A deprecation warning for syntax in an input file.
Definition: AnyMap.cpp:1926
void appdelete()
Delete and free all memory associated with the application.
Definition: global.cpp:134