Cantera  3.1.0a1
Loading...
Searching...
No Matches
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
21namespace Cantera
22{
23
24class Logger;
25class 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
72string findInputFile(const string& name);
73
74//! @copydoc Application::addDataDirectory
75void addDirectory(const string& dir);
76
77//! @copydoc Application::getDataDirectories
78string getDataDirectories(const string& sep);
79//! @}
80
81//! @copydoc Application::loadExtension
82void 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
88void loadExtensions(const AnyMap& node);
89
90//! @copydoc Application::searchPythonVersions
91void 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 */
98void appdelete();
99
100//! @copydoc Application::thread_complete
101void 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
121string version();
122
123//! Returns the hash of the git commit from which %Cantera was compiled, if known
124string 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.
131bool debugModeEnabled();
132
133//! Returns true if %Cantera was compiled with C++ @c HDF5 support.
134//! @since New in %Cantera 3.0.
135bool 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&)
155void writelog_direct(const string& msg);
156
157//! Write a message to the log only if loglevel > 0
158inline 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.
174template <typename... Args>
175void 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 */
194template <typename... Args>
195void 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
200void writelogendl();
201
202void 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
215void _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 */
226template <typename... Args>
227void 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
238void _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 */
250template <typename... Args>
251void 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 */
266template <typename... Args>
267void 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
291
292//! @copydoc Application::suppress_thermo_warnings
293void suppress_thermo_warnings(bool suppress=true);
294
295//! @copydoc Application::thermo_warnings_suppressed
297
298//! @copydoc Application::suppress_warnings
299void suppress_warnings();
300
301//! @copydoc Application::warnings_suppressed
303
304//! @} End of warning settings
305
306//! @copydoc Application::use_legacy_rate_constants
307void 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
316void 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
328template <class T>
329inline 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
336template <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
343string 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 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 usingSharedLibrary()
Returns true if Cantera was loaded as a shared library in the current application.
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 setLogger(Logger *logwriter)
Install a logger.
Definition global.cpp:27
void debuglog(const string &msg, int loglevel)
Write a message to the log only if loglevel > 0.
Definition global.h:158
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
int sign(T x)
Sign of a number.
Definition global.h:336
T clip(const T &value, const T &lower, const T &upper)
Clip value such that lower <= value <= upper.
Definition global.h:329
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