Cantera 2.6.0
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, logs, textlogs, (see \ref inputfiles, \ref logs, and
5 * \ref textlogs).
6 *
7 * @ingroup utils
8 *
9 * These functions store some parameters in global storage that are accessible
10 * at all times from the calling application. Contains module definitions for
11 * - inputfiles (see \ref inputfiles)
12 * - logs (see \ref logs)
13 * - textlogs (see \ref textlogs)
14 */
15
16// This file is part of Cantera. See License.txt in the top-level directory or
17// at https://cantera.org/license.txt for license and copyright information.
18
19#ifndef CT_GLOBAL_H
20#define CT_GLOBAL_H
21
22#include "ct_defs.h"
23#include "cantera/base/fmt.h"
24
25namespace Cantera
26{
27
28class XML_Node;
29class Logger;
30
31/*!
32 * @defgroup inputfiles Input File Handling
33 *
34 * The properties of phases and interfaces are specified in text files. These
35 * procedures handle various aspects of reading these files.
36 *
37 * For input files not specified by an absolute pathname, %Cantera searches
38 * for input files along a path that includes platform-specific default
39 * locations, and possibly user-specified locations.
40 *
41 * The current directory (".") is always searched first. Then, on Windows, the
42 * registry is checked to find the Cantera installation directory, and the
43 * 'data' subdirectory of the installation directory will be added to the search
44 * path.
45 *
46 * On the Mac, directory '/Applications/Cantera/data' is added to the
47 * search path.
48 *
49 * On any platform, if environment variable CANTERA_DATA is set to a directory
50 * name or a list of directory names separated with the OS-dependent path
51 * separator (that is, ";" on Windows, ":" elsewhere), then these directories will
52 * be added to the search path.
53 *
54 * Finally, the location where the data files were installed when
55 * %Cantera was built is added to the search path.
56 *
57 * Additional directories may be added by calling function addDirectory.
58 *
59 * There are currently three different types of input files within %Cantera. The
60 * YAML format is new in Cantera 2.5, and replaces both the CTI and CTML (XML)
61 * formats, which are deprecated and will be removed in Cantera 3.0. The scripts
62 * `cti2yaml.py` and `ctml2yaml.py` can be used to convert legacy input files to
63 * the YAML format.
64 *
65 * - YAML: A human-readable input file written using YAML syntax which
66 * defines species, phases, and reactions, and contains thermodynamic,
67 * chemical kinetic, and transport data needed by %Cantera.
68 *
69 * - CTI: A human-readable input file written using Python syntax. Some options
70 * for non-ideal equations of state available in the CTML format have not
71 * been implemented for the CTI format.
72 *
73 * - CTML: This is an XML file laid out in such a way that %Cantera can
74 * interpret the contents directly. Given a file in CTI format, %Cantera will
75 * convert the CTI file into the CTML format on-the-fly using a Python script
76 * (ctml_writer). This process is done in-memory without writing any new
77 * files to disk. Explicit use of the CTML format is not recommended.
78 *
79 * %Cantera provides converters (`ck2yaml` and `ckcti`) for converting
80 * Chemkin-format mechanisms to the YAML and CTI formats, respectively.
81 *
82 * Other input routines in other modules:
83 * @see importKinetics()
84 *
85 * @{
86 */
87
88//! @copydoc Application::findInputFile
89std::string findInputFile(const std::string& name);
90
91//! @copydoc Application::addDataDirectory
92void addDirectory(const std::string& dir);
93
94//! @copydoc Application::getDataDirectories
95std::string getDataDirectories(const std::string& sep);
96//! @}
97
98//! Delete and free all memory associated with the application
99/*!
100 * Delete all global data. It should be called at the end of the
101 * application if leak checking is to be done.
102 */
103void appdelete();
104
105//! @copydoc Application::thread_complete
106void thread_complete();
107
108//! Returns the hash of the git commit from which Cantera was compiled, if known
109std::string gitCommit();
110
111//! Returns root directory where %Cantera is installed
112/*!
113 * @returns a string containing the name of the base directory where %Cantera is
114 * installed. If the environmental variable CANTERA_ROOT is defined, this
115 * function will return its value, preferentially.
116 * @deprecated Unused within Cantera. To be removed after Cantera 2.6
117 *
118 * @ingroup inputfiles
119 */
120std::string canteraRoot();
121
122//! Returns true if Cantera was compiled in debug mode. Used for handling some cases
123//! where behavior tested in the test suite changes depending on whether the `NDEBUG`
124//! preprocessor macro is defined.
125bool debugModeEnabled();
126
127/*!
128 * @defgroup logs Diagnostic Output
129 *
130 * Writing diagnostic information to the screen or to a file. It is often
131 * useful to be able to write diagnostic messages to the screen or to a file.
132 * Cantera a set of procedures for this purpose designed to write text messages
133 * to the screen to document the progress of a complex calculation, such as a
134 * flame simulation.
135 */
136
137/*!
138 * @defgroup textlogs Writing messages to the screen
139 * @ingroup logs
140 */
141
142//! @copydoc Application::Messages::writelog(const std::string&)
143void writelog_direct(const std::string& msg);
144
145//! Write a message to the log only if loglevel > 0
146inline void debuglog(const std::string& msg, int loglevel)
147{
148 if (loglevel > 0) {
149 writelog_direct(msg);
150 }
151}
152
153//! Write a formatted message to the screen.
154//!
155//! This function passes its arguments to the fmt library 'format' function to
156//! generate a formatted string from a Python-style (curly braces) format
157//! string. This method is used throughout Cantera to write log messages. It can
158//! also be called by user programs. The advantage of using writelog over
159//! writing directly to the standard output is that messages written with
160//! writelog will display correctly even when Cantera is used from MATLAB or
161//! other application that do not have a standard output stream.
162//! @ingroup textlogs
163template <typename... Args>
164void writelog(const std::string& fmt, const Args&... args) {
165 if (sizeof...(args) == 0) {
167 } else {
168 writelog_direct(fmt::format(fmt, args...));
169 }
170}
171
172//! Write a formatted message to the screen
173/*!
174 * Using the printf formatting of C, write a message to the screen
175 * with variable values.
176 *
177 * Here, we format an internal string with the correct values
178 * and then feed it into writelog().
179 *
180 * @param fmt c format string for the following arguments
181 * @param args arguments used to interpolate the format string
182 * @ingroup textlogs
183 */
184template <typename... Args>
185void writelogf(const char* fmt, const Args& ... args) {
186 writelog_direct(fmt::sprintf(fmt, args...));
187}
188
189//! Write an end of line character to the screen and flush output
190void writelogendl();
191
192void writeline(char repeat, size_t count,
193 bool endl_after=true, bool endl_before=false);
194
195//! helper function passing deprecation warning to global handler
196void _warn_deprecated(const std::string& method, const std::string& extra="");
197
198//! Print a deprecation warning raised from *method*. @see Application::warn_deprecated
199/*!
200 * @param method method name
201 * @param msg Python-style format string with the following arguments
202 * @param args arguments for the format string
203 */
204template <typename... Args>
205void warn_deprecated(const std::string& method, const std::string& msg,
206 const Args&... args) {
207 if (sizeof...(args) == 0) {
208 _warn_deprecated(method, msg);
209 } else {
210 _warn_deprecated(method, fmt::format(msg, args...));
211 }
212}
213
214//! @copydoc Application::suppress_deprecation_warnings
216
217//! helper function passing generic warning to global handler
218void _warn(const std::string& warning,
219 const std::string& method, const std::string& extra);
220
221//! Print a generic warning raised from *method*. @see Application::warn
222/*!
223 * @param warning type of warning; @see Logger::warn
224 * @param method method name
225 * @param msg Python-style format string with the following arguments
226 * @param args arguments for the format string
227 */
228template <typename... Args>
229void warn(const std::string& warning, const std::string& method,
230 const std::string& msg, const Args&... args) {
231 if (sizeof...(args) == 0) {
232 _warn(warning, method, msg);
233 } else {
234 _warn(warning, method, fmt::format(msg, args...));
235 }
236}
237
238//! Print a user warning raised from *method* as `CanteraWarning`.
239/*!
240 * @param method method name
241 * @param msg Python-style format string with the following arguments
242 * @param args arguments for the format string
243 */
244template <typename... Args>
245void warn_user(const std::string& method, const std::string& msg,
246 const Args&... args) {
247 if (sizeof...(args) == 0) {
248 _warn("Cantera", method, msg);
249 } else {
250 _warn("Cantera", method, fmt::format(msg, args...));
251 }
252}
253
254//! @copydoc Application::make_deprecation_warnings_fatal
256
257//! @copydoc Application::make_warnings_fatal
259
260//! @copydoc Application::suppress_thermo_warnings
261void suppress_thermo_warnings(bool suppress=true);
262
263//! @copydoc Application::thermo_warnings_suppressed
265
266//! @copydoc Application::suppress_warnings
267void suppress_warnings();
268
269//! @copydoc Application::warnings_suppressed
271
272//! @copydoc Application::use_legacy_rate_constants
273void use_legacy_rate_constants(bool legacy=true);
274
275//! @copydoc Application::legacy_rate_constants_used
277
278//! @copydoc Application::Messages::setLogger
279void setLogger(Logger* logwriter);
280
281//! Return the conversion factor to convert unit std::string 'unit'
282//! to SI units.
283/*!
284 * @param unit String containing the units
285 * @deprecated To be removed after Cantera 2.6. Used only with XML input.
286 */
287doublereal toSI(const std::string& unit);
288
289/// Return the conversion factor to convert activation energy unit
290/// std::string 'unit' to Kelvin.
291/*!
292 * @param unit String containing the activation energy units
293 * @deprecated To be removed after Cantera 2.6. Used only with XML input.
294 */
295doublereal actEnergyToSI(const std::string& unit);
296
297//! @copydoc Application::get_XML_File
298XML_Node* get_XML_File(const std::string& file, int debug = 0);
299
300//! @copydoc Application::get_XML_from_string
301XML_Node* get_XML_from_string(const std::string& text);
302
303//! @copydoc Application::close_XML_File
304void close_XML_File(const std::string& file);
305
306//! This routine will locate an XML node in either the input
307//! XML tree or in another input file specified by the file
308//! part of the file_ID string.
309/*!
310 * Searches are based on the ID attribute of the XML element only.
311 *
312 * @param file_ID This is a concatenation of two strings separated by the "#"
313 * character. The string before the pound character is the file
314 * name of an XML file to carry out the search. The string after
315 * the # character is the ID attribute of the XML element to
316 * search for. The string is interpreted as a file string if no #
317 * character is in the string.
318 * @param root If the file string is empty, searches for the XML element with
319 * matching ID attribute are carried out from this XML node.
320 * @returns the XML_Node, if found. Returns null if not found.
321 *
322 * @deprecated The XML input format is deprecated and will be removed in
323 * Cantera 3.0.
324 */
325XML_Node* get_XML_Node(const std::string& file_ID, XML_Node* root);
326
327
328//! This routine will locate an XML node in either the input XML tree or in
329//! another input file specified by the file part of the file_ID string.
330/*!
331 * Searches are based on the XML element name and the ID attribute of the XML
332 * element. An exact match of both is usually required. However, the ID
333 * attribute may be set to "", in which case the first XML element with the
334 * correct element name will be returned.
335 *
336 * @param nameTarget This is the XML element name to look for.
337 * @param file_ID This is a concatenation of two strings separated by the "#"
338 * character. The string before the pound character is the file
339 * name of an XML file to carry out the search. The string after
340 * the # character is the ID attribute of the XML element to
341 * search for. The string is interpreted as a file string if no #
342 * character is in the string.
343 * @param root If the file string is empty, searches for the XML element with
344 * matching ID attribute are carried out from this XML node.
345 * @returns the XML_Node, if found. Returns null if not found.
346 *
347 * @deprecated The XML input format is deprecated and will be removed in
348 * Cantera 3.0.
349 */
350XML_Node* get_XML_NameID(const std::string& nameTarget,
351 const std::string& file_ID,
352 XML_Node* root);
353
354//! Clip *value* such that lower <= value <= upper
355template <class T>
356inline T clip(const T& value, const T& lower, const T& upper)
357{
358 return std::max(lower, std::min(upper, value));
359}
360
361//! Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.
362template <typename T> int sign(T x) {
363 return (T(0) < x) - (x < T(0));
364}
365
366//! Convert a type name to a human readable string, using `boost::core::demangle` if
367//! available. Also has a set of short names for some common types.
368//! @internal Mainly for use by AnyMap and Delegator
369std::string demangle(const std::type_info& type);
370
371}
372
373#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.
std::string findInputFile(const std::string &name)
Find an input file.
Definition: global.cpp:165
void addDirectory(const std::string &dir)
Add a directory to the data file search path.
Definition: global.cpp:155
std::string getDataDirectories(const std::string &sep)
Get the Cantera data directories.
Definition: global.cpp:160
std::string canteraRoot()
Returns root directory where Cantera is installed.
Definition: global.cpp:190
void writelog(const std::string &fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:164
void writelogf(const char *fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:185
Namespace for the Cantera kernel.
Definition: AnyMap.h:29
bool warnings_suppressed()
Returns true if warnings should be suppressed.
Definition: global.cpp:84
void _warn(const std::string &warning, const std::string &method, const std::string &extra)
helper function passing generic warning to global handler
Definition: global.cpp:63
void use_legacy_rate_constants(bool legacy=true)
Set definition used for rate constant calculation.
Definition: global.cpp:104
XML_Node * get_XML_File(const std::string &file, int debug=0)
Return a pointer to the XML tree for a Cantera input file.
Definition: global.cpp:140
bool debugModeEnabled()
Returns true if Cantera was compiled in debug mode.
Definition: global.cpp:206
void suppress_deprecation_warnings()
Globally disable printing of deprecation warnings.
Definition: global.cpp:69
bool thermo_warnings_suppressed()
Returns true if thermo warnings should be suppressed.
Definition: global.cpp:99
void make_warnings_fatal()
Turns Cantera warnings into exceptions.
Definition: global.cpp:89
void setLogger(Logger *logwriter)
Install a logger.
Definition: global.cpp:28
XML_Node * get_XML_Node(const std::string &file_ID, XML_Node *root)
This routine will locate an XML node in either the input XML tree or in another input file specified ...
Definition: global.cpp:235
void make_deprecation_warnings_fatal()
Turns deprecation warnings into exceptions.
Definition: global.cpp:74
void warn_deprecated(const std::string &source, const AnyBase &node, const std::string &message)
A deprecation warning for syntax in an input file.
Definition: AnyMap.cpp:1901
void debuglog(const std::string &msg, int loglevel)
Write a message to the log only if loglevel > 0.
Definition: global.h:146
XML_Node * get_XML_from_string(const std::string &text)
Read a CTI or CTML string and fill up an XML tree.
Definition: global.cpp:145
void warn(const std::string &warning, const std::string &method, const std::string &msg, const Args &... args)
Print a generic warning raised from method.
Definition: global.h:229
doublereal actEnergyToSI(const std::string &unit)
Return the conversion factor to convert activation energy unit std::string 'unit' to Kelvin.
Definition: global.cpp:181
bool legacy_rate_constants_used()
Returns true if legacy rate constant definition should be used.
Definition: global.cpp:109
std::string gitCommit()
Returns the hash of the git commit from which Cantera was compiled, if known.
Definition: global.cpp:131
void close_XML_File(const std::string &file)
Close an XML File.
Definition: global.cpp:150
void suppress_warnings()
Globally disable printing of (user) warnings.
Definition: global.cpp:79
void _warn_deprecated(const std::string &method, const std::string &extra="")
helper function passing deprecation warning to global handler
Definition: global.cpp:58
T clip(const T &value, const T &lower, const T &upper)
Clip value such that lower <= value <= upper.
Definition: global.h:356
void warn_user(const std::string &method, const std::string &msg, const Args &... args)
Print a user warning raised from method as CanteraWarning.
Definition: global.h:245
void thread_complete()
Delete and free memory allocated per thread in multithreaded applications.
Definition: global.cpp:126
doublereal toSI(const std::string &unit)
Return the conversion factor to convert unit std::string 'unit' to SI units.
Definition: global.cpp:170
void writelog_direct(const std::string &msg)
Write a message to the screen.
Definition: global.cpp:37
void suppress_thermo_warnings(bool suppress=true)
Globally disable printing of warnings about problematic thermo data, such as NASA polynomials with di...
Definition: global.cpp:94
int sign(T x)
Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.
Definition: global.h:362
void appdelete()
Delete and free all memory associated with the application.
Definition: global.cpp:119
XML_Node * get_XML_NameID(const std::string &nameTarget, const std::string &file_ID, XML_Node *root)
This routine will locate an XML node in either the input XML tree or in another input file specified ...
Definition: global.cpp:273
void writelogendl()
Write an end of line character to the screen and flush output.
Definition: global.cpp:42
std::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:297
Versions 6.2.0 and 6.2.1 of fmtlib do not include this define before they include windows....
Definition: fmt.h:31