Cantera  2.4.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 http://www.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 
25 namespace Cantera
26 {
27 
28 class XML_Node;
29 class 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 (i.e. ";" 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 two different types of input files within %Cantera:
60  * - CTI: A human-readable input file written using Python syntax which
61  * defines species, phases, and reactions, and contains thermodynamic,
62  * chemical kinetic, and transport data needed by %Cantera. Some options for
63  * non-ideal equations of state available in the CTML format have not yet
64  * been implemented for the CTI format.
65  *
66  * - CTML: This is an XML file laid out in such a way that %Cantera can
67  * interpret the contents directly. Given a file in CTI format, %Cantera will
68  * convert the CTI file into the CTML format on-the-fly using a Python script
69  * (ctml_writer). This process is done in-memory without writing any new
70  * files to disk. Explicit use of the CTML format is not recommended unless
71  * using features not available in CTI or working on a computer where Python
72  * is not available.
73  *
74  * %Cantera provides a converter (ck2cti) for converting Chemkin-format
75  * gas-phase mechanisms to the CTI format.
76  *
77  * Other input routines in other modules:
78  * @see importKinetics()
79  *
80  * @{
81  */
82 
83 //! @copydoc Application::findInputFile
84 std::string findInputFile(const std::string& name);
85 
86 //! @copydoc Application::addDataDirectory
87 void addDirectory(const std::string& dir);
88 
89 //! @copydoc Application::getDataDirectories
90 std::string getDataDirectories(const std::string& sep);
91 //@}
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 //! Returns the hash of the git commit from which Cantera was compiled, if known
104 std::string gitCommit();
105 
106 //! Returns root directory where %Cantera is installed
107 /*!
108  * @returns a string containing the name of the base directory where %Cantera is
109  * installed. If the environmental variable CANTERA_ROOT is defined, this
110  * function will return its value, preferentially.
111  *
112  * @ingroup inputfiles
113  */
114 std::string canteraRoot();
115 
116 /*!
117  * @defgroup logs Diagnostic Output
118  *
119  * Writing diagnostic information to the screen or to a file. It is often
120  * useful to be able to write diagnostic messages to the screen or to a file.
121  * Cantera a set of procedures for this purpose designed to write text messages
122  * to the screen to document the progress of a complex calculation, such as a
123  * flame simulation.
124  */
125 
126 /*!
127  * @defgroup textlogs Writing messages to the screen
128  * @ingroup logs
129  */
130 
131 //! @copydoc Application::Messages::writelog(const std::string&)
132 void writelog_direct(const std::string& msg);
133 
134 //! Write a message to the log only if loglevel > 0
135 inline void debuglog(const std::string& msg, int loglevel)
136 {
137  if (loglevel > 0) {
138  writelog_direct(msg);
139  }
140 }
141 
142 //! Write a formatted message to the screen.
143 //!
144 //! This function passes its arguments to the fmt library 'format' function to
145 //! generate a formatted string from a Python-style (curly braces) format
146 //! string. This method is used throughout Cantera to write log messages. It can
147 //! also be called by user programs. The advantage of using writelog over
148 //! writing directly to the standard output is that messages written with
149 //! writelog will display correctly even when Cantera is used from MATLAB or
150 //! other application that do not have a standard output stream.
151 //! @ingroup textlogs
152 template <typename... Args>
153 void writelog(const std::string& fmt, const Args&... args) {
154  if (sizeof...(args) == 0) {
156  } else {
157  writelog_direct(fmt::format(fmt, args...));
158  }
159 }
160 
161 //! Write a formatted message to the screen
162 /*!
163  * Using the printf formatting of C, write a message to the screen
164  * with variable values.
165  *
166  * Here, we format an internal string with the correct values
167  * and then feed it into writelog().
168  *
169  * @param fmt c format string for the following arguments
170  * @param args arguments used to interpolate the format string
171  * @ingroup textlogs
172  */
173 template <typename... Args>
174 void writelogf(const char* fmt, const Args& ... args) {
175  writelog_direct(fmt::sprintf(fmt, args...));
176 }
177 
178 //! Write an end of line character to the screen and flush output
179 void writelogendl();
180 
181 void writeline(char repeat, size_t count,
182  bool endl_after=true, bool endl_before=false);
183 
184 //! @copydoc Application::warn_deprecated
185 void warn_deprecated(const std::string& method, const std::string& extra="");
186 
187 //! @copydoc Application::suppress_deprecation_warnings
189 
190 //! @copydoc Application::make_deprecation_warnings_fatal
192 
193 //! @copydoc Application::suppress_thermo_warnings
194 void suppress_thermo_warnings(bool suppress=true);
195 
196 //! @copydoc Application::thermo_warnings_suppressed
198 
199 //! @copydoc Application::Messages::setLogger
200 void setLogger(Logger* logwriter);
201 
202 //! Return the conversion factor to convert unit std::string 'unit'
203 //! to SI units.
204 /*!
205  * @param unit String containing the units
206  */
207 doublereal toSI(const std::string& unit);
208 
209 /// Return the conversion factor to convert activation energy unit
210 /// std::string 'unit' to Kelvin.
211 /*!
212  * @param unit String containing the activation energy units
213  */
214 doublereal actEnergyToSI(const std::string& unit);
215 
216 //! @copydoc Application::get_XML_File
217 XML_Node* get_XML_File(const std::string& file, int debug = 0);
218 
219 //! @copydoc Application::get_XML_from_string
220 XML_Node* get_XML_from_string(const std::string& text);
221 
222 //! @copydoc Application::close_XML_File
223 void close_XML_File(const std::string& file);
224 
225 //! This routine will locate an XML node in either the input
226 //! XML tree or in another input file specified by the file
227 //! part of the file_ID string.
228 /*!
229  * Searches are based on the ID attribute of the XML element only.
230  *
231  * @param file_ID This is a concatenation of two strings separated by the "#"
232  * character. The string before the pound character is the file
233  * name of an XML file to carry out the search. The string after
234  * the # character is the ID attribute of the XML element to
235  * search for. The string is interpreted as a file string if no #
236  * character is in the string.
237  * @param root If the file string is empty, searches for the XML element with
238  * matching ID attribute are carried out from this XML node.
239  * @returns the XML_Node, if found. Returns null if not found.
240  */
241 XML_Node* get_XML_Node(const std::string& file_ID, XML_Node* root);
242 
243 
244 //! This routine will locate an XML node in either the input XML tree or in
245 //! another input file specified by the file part of the file_ID string.
246 /*!
247  * Searches are based on the XML element name and the ID attribute of the XML
248  * element. An exact match of both is usually required. However, the ID
249  * attribute may be set to "", in which case the first XML element with the
250  * correct element name will be returned.
251  *
252  * @param nameTarget This is the XML element name to look for.
253  * @param file_ID This is a concatenation of two strings separated by the "#"
254  * character. The string before the pound character is the file
255  * name of an XML file to carry out the search. The string after
256  * the # character is the ID attribute of the XML element to
257  * search for. The string is interpreted as a file string if no #
258  * character is in the string.
259  * @param root If the file string is empty, searches for the XML element with
260  * matching ID attribute are carried out from this XML node.
261  * @returns the XML_Node, if found. Returns null if not found.
262  */
263 XML_Node* get_XML_NameID(const std::string& nameTarget,
264  const std::string& file_ID,
265  XML_Node* root);
266 
267 //! Clip *value* such that lower <= value <= upper
268 template <class T>
269 inline T clip(const T& value, const T& lower, const T& upper)
270 {
271  return std::max(lower, std::min(upper, value));
272 }
273 
274 //! Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.
275 template <typename T> int sign(T x) {
276  return (T(0) < x) - (x < T(0));
277 }
278 
279 }
280 
281 #endif
Wrapper for either system-installed or local headers for fmt.
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:189
XML_Node * get_XML_File(const std::string &file, int debug)
Return a pointer to the XML tree for a Cantera input file.
Definition: global.cpp:105
doublereal actEnergyToSI(const std::string &unit)
Return the conversion factor to convert activation energy unit std::string &#39;unit&#39; to Kelvin...
Definition: global.cpp:146
std::string findInputFile(const std::string &name)
Find an input file.
Definition: global.cpp:130
doublereal toSI(const std::string &unit)
Return the conversion factor to convert unit std::string &#39;unit&#39; to SI units.
Definition: global.cpp:135
void thread_complete()
Delete and free memory allocated per thread in multithreaded applications.
Definition: global.cpp:91
void setLogger(Logger *logwriter)
Install a logger.
Definition: global.cpp:24
void writelog(const std::string &fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:153
This file contains definitions of terms that are used in internal routines and are unlikely to need m...
T clip(const T &value, const T &lower, const T &upper)
Clip value such that lower <= value <= upper.
Definition: global.h:269
void warn_deprecated(const std::string &method, const std::string &extra)
Print a warning indicating that method is deprecated.
Definition: global.cpp:54
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:275
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:110
std::string gitCommit()
Returns the hash of the git commit from which Cantera was compiled, if known.
Definition: global.cpp:96
void suppress_thermo_warnings(bool suppress)
Globally disable printing of warnings about problematic thermo data, e.g.
Definition: global.cpp:69
void close_XML_File(const std::string &file)
Close an XML File.
Definition: global.cpp:115
void appdelete()
Delete and free all memory associated with the application.
Definition: global.cpp:84
void debuglog(const std::string &msg, int loglevel)
Write a message to the log only if loglevel > 0.
Definition: global.h:135
void writelogf(const char *fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:174
void writelogendl()
Write an end of line character to the screen and flush output.
Definition: global.cpp:38
bool thermo_warnings_suppressed()
Returns true if thermo warnings should be suppressed.
Definition: global.cpp:74
void suppress_deprecation_warnings()
Globally disable printing of deprecation warnings.
Definition: global.cpp:59
void make_deprecation_warnings_fatal()
Turns deprecation warnings into exceptions.
Definition: global.cpp:64
Definition: fmt.h:29
string canteraRoot()
Returns root directory where Cantera is installed.
Definition: global.cpp:155
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:8
void addDirectory(const std::string &dir)
Add a directory to the data file search path.
Definition: global.cpp:120
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:227
void writelog_direct(const std::string &msg)
Write a message to the screen.
Definition: global.cpp:33
std::string getDataDirectories(const std::string &sep)
Get the Cantera data directories.
Definition: global.cpp:125