Cantera  2.3.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 
33 //! Return the number of errors that have been encountered so far
34 /*!
35  * @ingroup errorhandling
36  * @deprecated Unused. To be removed after Cantera 2.3.
37  */
38 int nErrors();
39 
40 //! @copydoc Application::Messages::lastErrorMessage
41 //! @deprecated Unused. To be removed after Cantera 2.3.
42 std::string lastErrorMessage();
43 
44 //! @copydoc Application::Messages::addError
45 //! @deprecated Unused. To be removed after Cantera 2.3.
46 void setError(const std::string& r, const std::string& msg);
47 
48 //! @copydoc Application::Messages::getErrors
49 //! @deprecated Unused. To be removed after Cantera 2.3.
50 void showErrors(std::ostream& f);
51 
52 //! @copydoc Application::Messages::logErrors
53 //! @deprecated Unused. To be removed after Cantera 2.3.
54 void showErrors();
55 
56 //! @copydoc Application::Messages::popError
57 //! @deprecated Unused. To be removed after Cantera 2.3.
58 void popError();
59 
60 /*!
61  * @defgroup inputfiles Input File Handling
62  *
63  * The properties of phases and interfaces are specified in text files. These
64  * procedures handle various aspects of reading these files.
65  *
66  * For input files not specified by an absolute pathname, %Cantera searches
67  * for input files along a path that includes platform-specific default
68  * locations, and possibly user-specified locations.
69  *
70  * The current directory (".") is always searched first. Then, on Windows, the
71  * registry is checked to find the Cantera installation directory, and the
72  * 'data' subdirectory of the installation directory will be added to the search
73  * path.
74  *
75  * On the Mac, directory '/Applications/Cantera/data' is added to the
76  * search path.
77  *
78  * On any platform, if environment variable CANTERA_DATA is set to a directory
79  * name or a list of directory names separated with the OS-dependent path
80  * separator (i.e. ";" on Windows, ":" elsewhere), then these directories will
81  * be added to the search path.
82  *
83  * Finally, the location where the data files were installed when
84  * %Cantera was built is added to the search path.
85  *
86  * Additional directories may be added by calling function addDirectory.
87  *
88  * There are currently two different types of input files within %Cantera:
89  * - CTI: A human-readable input file written using Python syntax which
90  * defines species, phases, and reactions, and contains thermodynamic,
91  * chemical kinetic, and transport data needed by %Cantera. Some options for
92  * non-ideal equations of state available in the CTML format have not yet
93  * been implemented for the CTI format.
94  *
95  * - CTML: This is an XML file laid out in such a way that %Cantera can
96  * interpret the contents directly. Given a file in CTI format, %Cantera will
97  * convert the CTI file into the CTML format on-the-fly using a Python script
98  * (ctml_writer). This process is done in-memory without writing any new
99  * files to disk. Explicit use of the CTML format is not recommended unless
100  * using features not available in CTI or working on a computer where Python
101  * is not available.
102  *
103  * %Cantera provides a converter (ck2cti) for converting Chemkin-format
104  * gas-phase mechanisms to the CTI format.
105  *
106  * Other input routines in other modules:
107  * @see importKinetics()
108  *
109  * @{
110  */
111 
112 //! @copydoc Application::findInputFile
113 std::string findInputFile(const std::string& name);
114 
115 //! @copydoc Application::addDataDirectory
116 void addDirectory(const std::string& dir);
117 
118 //! @copydoc Application::getDataDirectories
119 std::string getDataDirectories(const std::string& sep);
120 //@}
121 
122 //! Delete and free all memory associated with the application
123 /*!
124  * Delete all global data. It should be called at the end of the
125  * application if leak checking is to be done.
126  */
127 void appdelete();
128 
129 //! @copydoc Application::thread_complete
130 void thread_complete();
131 
132 //! Returns root directory where %Cantera is installed
133 /*!
134  * @returns a string containing the name of the base directory where %Cantera is
135  * installed. If the environmental variable CANTERA_ROOT is defined, this
136  * function will return its value, preferentially.
137  *
138  * @ingroup inputfiles
139  */
140 std::string canteraRoot();
141 
142 /*!
143  * @defgroup logs Diagnostic Output
144  *
145  * Writing diagnostic information to the screen or to a file. It is often
146  * useful to be able to write diagnostic messages to the screen or to a file.
147  * Cantera a set of procedures for this purpose designed to write text messages
148  * to the screen to document the progress of a complex calculation, such as a
149  * flame simulation.
150  */
151 
152 /*!
153  * @defgroup textlogs Writing messages to the screen
154  * @ingroup logs
155  */
156 
157 //! @copydoc Application::Messages::writelog(const std::string&)
158 void writelog_direct(const std::string& msg);
159 
160 //! Write a message to the log only if loglevel > 0
161 inline void debuglog(const std::string& msg, int loglevel)
162 {
163  if (loglevel > 0) {
164  writelog_direct(msg);
165  }
166 }
167 
168 //! Write a formatted message to the screen.
169 //!
170 //! This function passes its arguments to the fmt library 'format' function to
171 //! generate a formatted string from a Python-style (curly braces) format
172 //! string. This method is used throughout Cantera to write log messages. It can
173 //! also be called by user programs. The advantage of using writelog over
174 //! writing directly to the standard output is that messages written with
175 //! writelog will display correctly even when Cantera is used from MATLAB or
176 //! other application that do not have a standard output stream.
177 //! @ingroup textlogs
178 template <typename... Args>
179 void writelog(const std::string& fmt, const Args&... args) {
180  if (sizeof...(args) == 0) {
181  writelog_direct(fmt);
182  } else {
183  writelog_direct(fmt::format(fmt, args...));
184  }
185 }
186 
187 //! Write a formatted message to the screen
188 /*!
189  * Using the printf formatting of C, write a message to the screen
190  * with variable values.
191  *
192  * Here, we format an internal string with the correct values
193  * and then feed it into writelog().
194  *
195  * @param fmt c format string for the following arguments
196  * @param args arguments used to interpolate the format string
197  * @ingroup textlogs
198  */
199 template <typename... Args>
200 void writelogf(const char* fmt, const Args& ... args) {
201  writelog_direct(fmt::sprintf(fmt, args...));
202 }
203 
204 //! Write an end of line character to the screen and flush output
205 void writelogendl();
206 
207 void writeline(char repeat, size_t count,
208  bool endl_after=true, bool endl_before=false);
209 
210 //! @copydoc Application::warn_deprecated
211 void warn_deprecated(const std::string& method, const std::string& extra="");
212 
213 //! @copydoc Application::suppress_deprecation_warnings
215 
216 //! @copydoc Application::make_deprecation_warnings_fatal
218 
219 //! @copydoc Application::suppress_thermo_warnings
220 void suppress_thermo_warnings(bool suppress=true);
221 
222 //! @copydoc Application::thermo_warnings_suppressed
224 
225 //! @copydoc Application::Messages::setLogger
226 void setLogger(Logger* logwriter);
227 
228 //! Return the conversion factor to convert unit std::string 'unit'
229 //! to SI units.
230 /*!
231  * @param unit String containing the units
232  */
233 doublereal toSI(const std::string& unit);
234 
235 /// Return the conversion factor to convert activation energy unit
236 /// std::string 'unit' to Kelvin.
237 /*!
238  * @param unit String containing the activation energy units
239  */
240 doublereal actEnergyToSI(const std::string& unit);
241 
242 //! @copydoc Application::get_XML_File
243 XML_Node* get_XML_File(const std::string& file, int debug = 0);
244 
245 //! @copydoc Application::get_XML_from_string
246 XML_Node* get_XML_from_string(const std::string& text);
247 
248 //! @copydoc Application::close_XML_File
249 void close_XML_File(const std::string& file);
250 
251 //! This routine will locate an XML node in either the input
252 //! XML tree or in another input file specified by the file
253 //! part of the file_ID string.
254 /*!
255  * Searches are based on the ID attribute of the XML element only.
256  *
257  * @param file_ID This is a concatenation of two strings separated by the "#"
258  * character. The string before the pound character is the file
259  * name of an XML file to carry out the search. The string after
260  * the # character is the ID attribute of the XML element to
261  * search for. The string is interpreted as a file string if no #
262  * character is in the string.
263  * @param root If the file string is empty, searches for the XML element with
264  * matching ID attribute are carried out from this XML node.
265  * @returns the XML_Node, if found. Returns null if not found.
266  */
267 XML_Node* get_XML_Node(const std::string& file_ID, XML_Node* root);
268 
269 
270 //! This routine will locate an XML node in either the input XML tree or in
271 //! another input file specified by the file part of the file_ID string.
272 /*!
273  * Searches are based on the XML element name and the ID attribute of the XML
274  * element. An exact match of both is usually required. However, the ID
275  * attribute may be set to "", in which case the first XML element with the
276  * correct element name will be returned.
277  *
278  * @param nameTarget This is the XML element name to look for.
279  * @param file_ID This is a concatenation of two strings separated by the "#"
280  * character. The string before the pound character is the file
281  * name of an XML file to carry out the search. The string after
282  * the # character is the ID attribute of the XML element to
283  * search for. The string is interpreted as a file string if no #
284  * character is in the string.
285  * @param root If the file string is empty, searches for the XML element with
286  * matching ID attribute are carried out from this XML node.
287  * @returns the XML_Node, if found. Returns null if not found.
288  */
289 XML_Node* get_XML_NameID(const std::string& nameTarget,
290  const std::string& file_ID,
291  XML_Node* root);
292 
293 //! Clip *value* such that lower <= value <= upper
294 template <class T>
295 inline T clip(const T& value, const T& lower, const T& upper)
296 {
297  return std::max(lower, std::min(upper, value));
298 }
299 
300 //! Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.
301 template <typename T> int sign(T x) {
302  return (T(0) < x) - (x < T(0));
303 }
304 
305 }
306 
307 #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:214
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:96
void popError()
Discard the last error message.
Definition: global.cpp:117
string lastErrorMessage()
Retrieve the last error message in a string.
Definition: global.cpp:123
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:171
void showErrors(std::ostream &f)
Prints all of the error messages to an ostream.
Definition: global.cpp:129
std::string findInputFile(const std::string &name)
Find an input file.
Definition: global.cpp:155
doublereal toSI(const std::string &unit)
Return the conversion factor to convert unit std::string &#39;unit&#39; to SI units.
Definition: global.cpp:160
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:179
void setError(const std::string &r, const std::string &msg)
Set an error condition in the application class without throwing an exception.
Definition: global.cpp:140
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:295
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:301
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:101
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:106
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:161
void writelogf(const char *fmt, const Args &... args)
Write a formatted message to the screen.
Definition: global.h:200
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
string canteraRoot()
Returns root directory where Cantera is installed.
Definition: global.cpp:180
Namespace for the Cantera kernel.
Definition: application.cpp:29
int nErrors()
Return the number of errors that have been encountered so far.
Definition: global.cpp:111
void addDirectory(const std::string &dir)
Add a directory to the data file search path.
Definition: global.cpp:145
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:252
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:150