Cantera 2.6.0

application.h
Go to the documentation of this file.
1//! @file application.h
2
3// This file is part of Cantera. See License.txt in the top-level directory or
4// at https://cantera.org/license.txt for license and copyright information.
5
6#ifndef CT_BASE_APPLICATION_H
7#define CT_BASE_APPLICATION_H
8
9#include "cantera/base/config.h"
10#include "cantera/base/logger.h"
11
12#include <boost/algorithm/string/join.hpp>
13
14#include <set>
15#include <thread>
16
17 namespace Cantera
18{
19
20 class XML_Node;
21
22 int get_modified_time(const std::string& path);
23
24/*!
25 * @defgroup globalData Global Data
26 *
27 * Global data are available anywhere. There are two kinds. Cantera has an
28 * assortment of constant values for physical parameters. Also, Cantera
29 * maintains a collection of global data which is specific to each process that
30 * invokes Cantera functions. This process-specific data is stored in the class
31 * Application.
32 */
33
34
35//! Class to hold global data.
36/*!
37 * Class Application is the top-level class that stores data that should persist
38 * for the duration of the process. The class should not be instantiated
39 * directly; instead, it is instantiated as needed by the functions declared
40 * here. At most one instance is created, and it is not destroyed until the
41 * process terminates.
42 *
43 * @ingroup textlogs
44 * @ingroup globalData
45 */
46 class Application
47{
48 protected:
49 //! Class to carry out messages
50 class Messages
51 {
52 public:
53 Messages();
54
55 Messages(const Messages& r) = delete;
56 Messages& operator=(const Messages& r) = delete;
57
58 //! Set an error condition in the application class without
59 //! throwing an exception.
60 /*!
61 * This routine adds an error message to the end of the stack of errors
62 * that Cantera accumulates in the Application class.
63 * @param r Procedure name which is generating the error condition
64 * @param msg Descriptive message of the error condition.
65 *
66 * If only one argument is specified, that string is used as the
67 * entire message.
68 * @ingroup errorhandling
69 */
70 void addError(const std::string& r, const std::string& msg="");
71
72 //! Return the number of errors that have been encountered so far.
73 /*!
74 * @ingroup errorhandling
75 */
76 int getErrorCount();
77
78 //! Discard the last error message
79 /*!
80 * %Cantera saves a stack of exceptions that it has caught in the
81 * Application class. This routine eliminates the last exception to be
82 * added to that stack.
83 *
84 * @ingroup errorhandling
85 */
86 void popError();
87
88 //! Retrieve the last error message in a string
89 /*!
90 * This routine will retrieve the last error message and return it in
91 * the return string.
92 *
93 * @ingroup errorhandling
94 */
95 std::string lastErrorMessage();
96
97 //! Prints all of the error messages to an ostream
98 /*!
99 * Write out all of the saved error messages to the ostream f using
100 * the function Logger::writelog. Cantera saves a stack of exceptions
101 * that it has caught in the Application class. This routine writes
102 * out all of the error messages to the ostream and then clears them
103 * from internal storage.
104 *
105 * @param f ostream which will receive the error messages
106 *
107 * @ingroup errorhandling
108 */
109 void getErrors(std::ostream& f);
110
111 //! Prints all of the error messages using writelog
112 /*!
113 * Print all of the error messages using function writelog. Cantera
114 * saves a stack of exceptions that it has caught in the Application
115 * class. This routine writes out all of the error messages and then
116 * clears them from internal storage.
117 *
118 * @ingroup errorhandling
119 */
120 void logErrors();
121
122 //! Write a message to the screen.
123 /*!
124 * The string may be of any length, and may contain end-of-line
125 * characters. This method is used throughout Cantera to write log
126 * messages. It can also be called by user programs. The advantage of
127 * using writelog over writing directly to the standard output is that
128 * messages written with writelog will display correctly even when
129 * Cantera is used from MATLAB or other application that do not have a
130 * standard output stream.
131 *
132 * @param msg c++ string to be written to the screen
133 * @ingroup textlogs
134 */
135 void writelog(const std::string& msg);
136
137 //! Write an end of line character to the screen and flush output
138 void writelogendl();
139
140 //! Write a warning message to the screen.
141 /*!
142 * @param warning String specifying type of warning; @see Logger::warn
143 * @param msg String to be written to the screen
144 * @ingroup textlogs
145 */
146 void warnlog(const std::string& warning, const std::string& msg);
147
148 //! Install a logger.
149 /*!
150 * Called by the language interfaces to install an appropriate logger.
151 * The logger is used for the writelog() function
152 *
153 * @param logwriter Pointer to a logger object
154 * @see Logger.
155 * @ingroup textlogs
156 */
157 void setLogger(Logger* logwriter);
158
159 protected:
160 //! Current list of error messages
161 std::vector<std::string> errorMessage;
162
163 //! Current pointer to the logwriter
164 std::unique_ptr<Logger> logwriter;
165 };
166
167 //! Typedef for thread specific messages
168 typedef shared_ptr<Messages> pMessages_t;
169
170 //! Class that stores thread messages for each thread, and retrieves them
171 //! based on the thread id.
172 class ThreadMessages
173 {
174 public:
175 //! Constructor
176 ThreadMessages() {}
177
178 //! Provide a pointer dereferencing overloaded operator
179 /*!
180 * @returns a pointer to Messages
181 */
182 Messages* operator->();
183
184 //! Remove a local thread message
185 void removeThreadMessages();
186
187 //! Typedef for map between a thread and the message
188 typedef std::map<std::thread::id, pMessages_t> threadMsgMap_t;
189
190 private:
191 //! Thread Msg Map
192 threadMsgMap_t m_threadMsgMap;
193 };
194
195 protected:
196 //! Constructor for class sets up the initial conditions
197 //! Protected ctor access thru static member function Instance
198 Application();
199
200 public:
201 //! Return a pointer to the one and only instance of class Application
202 /*!
203 * If the Application object has not yet been created, it is created
204 */
205 static Application* Instance();
206
207 //! Destructor for class deletes global data
208 /*!
209 * Deletes any open XML trees.
210 */
211 virtual ~Application();
212
213 //! Static function that destroys the application class's data
214 static void ApplicationDestroy();
215
216 //! @copydoc Messages::addError
217 void addError(const std::string& r, const std::string& msg="") {
218 pMessenger->addError(r, msg);
219 }
220
221 //! @copydoc Messages::getErrorCount
222 int getErrorCount() {
223 return pMessenger->getErrorCount();
224 }
225
226 //! @copydoc Messages::popError
227 void popError() {
228 pMessenger->popError();
229 }
230
231 //! @copydoc Messages::lastErrorMessage
232 std::string lastErrorMessage() {
233 return pMessenger->lastErrorMessage();
234 }
235
236 //! @copydoc Messages::getErrors
237 void getErrors(std::ostream& f) {
238 pMessenger->getErrors(f);
239 }
240
241 //! @copydoc Messages::logErrors
242 void logErrors() {
243 pMessenger->logErrors();
244 }
245
246 //! Add a directory to the data file search path.
247 /*!
248 * @ingroup inputfiles
249 *
250 * @param dir String name for the directory to be added to the search path
251 */
252 void addDataDirectory(const std::string& dir);
253
254 //! Find an input file.
255 /*!
256 * This routine will search for a file in the default locations specified
257 * for the application. See the routine setDefaultDirectories() listed
258 * above. The first directory searched is usually the current working
259 * directory.
260 *
261 * The default set of directories will not be searched if an absolute path
262 * (for example, one starting with `/` or `C:\`) or a path relative to the
263 * user's home directory (for example, starting with `~/`) is specified.
264 *
265 * The presence of the file is determined by whether the file can be
266 * opened for reading by the current user.
267 *
268 * @param name Name of the input file to be searched for
269 * @return The absolute path name of the first matching file
270 *
271 * If the file is not found a CanteraError exception is thrown.
272 *
273 * @ingroup inputfiles
274 */
275 std::string findInputFile(const std::string& name);
276
277 //! Get the Cantera data directories
278 /*!
279 * This routine returns a string including the names of all the
280 * directories searched by Cantera for data files.
281 *
282 * @param sep Separator to use between directories in the string
283 * @return A string of directories separated by the input sep
284 *
285 * @ingroup inputfiles
286 */
287 std::string getDataDirectories(const std::string& sep) {
288 return boost::algorithm::join(inputDirs, sep);
289 }
290
291 //! Return a pointer to the XML tree for a Cantera input file.
292 /*!
293 * This routine will find the file and read the XML file into an XML tree
294 * structure. Then, a pointer will be returned. If the file has already been
295 * processed, then just the pointer will be returned.
296 *
297 * @param file String containing the relative or absolute file name
298 * @param debug Debug flag
299 *
300 * @deprecated The XML input format is deprecated and will be removed in
301 * Cantera 3.0.
302 */
303 XML_Node* get_XML_File(const std::string& file, int debug=0);
304
305 //! Read a CTI or CTML string and fill up an XML tree.
306 /*!
307 * Return a pointer to the XML tree corresponding to the specified CTI or
308 * XML string. If the given string has been processed before, the cached XML
309 * tree will be returned. Otherwise, the XML tree will be generated and
310 * stored in the cache.
311 * @param text CTI or CTML string
312 * @return Root of the corresponding XML tree
313 *
314 * @deprecated The XML input format is deprecated and will be removed in
315 * Cantera 3.0.
316 */
317 XML_Node* get_XML_from_string(const std::string& text);
318
319 //! Close an XML File
320 /*!
321 * Close a file that is opened by this application object
322 *
323 * @param file String containing the relative or absolute file name
324 */
325 void close_XML_File(const std::string& file);
326
327#ifdef _WIN32
328 long int readStringRegistryKey(const std::string& keyName, const std::string& valueName,
329 std::string& value, const std::string& defaultValue);
330#endif
331
332 //! @copydoc Messages::writelog
333 void writelog(const std::string& msg) {
334 pMessenger->writelog(msg);
335 }
336
337 //! Write an endl to the screen and flush output
338 void writelogendl() {
339 pMessenger->writelogendl();
340 }
341
342 //! @copydoc Messages::warnlog
343 void warnlog(const std::string& warning, const std::string& msg) {
344 pMessenger->warnlog(warning, msg);
345 }
346
347 //! Print a warning indicating that *method* is deprecated. Additional
348 //! information (removal version, alternatives) can be specified in
349 //! *extra*. Deprecation warnings are printed once per method per
350 //! invocation of the application.
351 void warn_deprecated(const std::string& method, const std::string& extra="");
352
353 //! Globally disable printing of deprecation warnings. Used primarily to
354 //! prevent certain tests from failing.
355 void suppress_deprecation_warnings() {
356 m_suppress_deprecation_warnings = true;
357 m_fatal_deprecation_warnings = false;
358 }
359
360 //! Turns deprecation warnings into exceptions. Activated within the test
361 //! suite to make sure that no deprecated methods are being used.
362 void make_deprecation_warnings_fatal() {
363 m_fatal_deprecation_warnings = true;
364 }
365
366 //! Generate a general purpose warning; repeated warnings are not suppressed
367 //! @param warning Warning type; @see Logger::warn
368 //! @param method Name of method triggering the warning
369 //! @param extra Additional information printed for the warning
370 void warn(const std::string& warning,
371 const std::string& method, const std::string& extra="");
372
373 //! Globally disable printing of (user) warnings. Used primarily to
374 //! prevent certain tests from failing.
375 void suppress_warnings() {
376 m_suppress_warnings = true;
377 m_fatal_warnings = false;
378 }
379
380 //! Returns `true` if warnings should be suppressed.
381 bool warnings_suppressed() {
382 return m_suppress_warnings;
383 }
384
385 //! Turns Cantera warnings into exceptions. Activated within the test
386 //! suite to make sure that your warning message are being raised.
387 void make_warnings_fatal() {
388 m_fatal_warnings = true;
389 }
390
391 //! Globally disable printing of warnings about problematic thermo data,
392 //! such as NASA polynomials with discontinuities at the midpoint temperature.
393 void suppress_thermo_warnings(bool suppress=true) {
394 m_suppress_thermo_warnings = suppress;
395 }
396
397 //! Returns `true` if thermo warnings should be suppressed.
398 bool thermo_warnings_suppressed() {
399 return m_suppress_thermo_warnings;
400 }
401
402 //! Set definition used for rate constant calculation.
403 //! @see Kinetics::getFwdRateConstants()
404 /*!
405 * If set to 'false', rate constants of three-body reactions are consistent with
406 * conventional definitions. If set to 'true', output for rate constants of
407 * three-body reactions is multipied by third-body concentrations (legacy
408 * behavior). For the pre-compiled Cantera 2.6 distribution, the default value is
409 * set to 'true', which implies no change compared to previous behavior. For
410 * user-compiled Cantera, the default behavior can be changed by the SCons flag
411 * 'legacy_rate_constants'.
412 *
413 * @deprecated Behavior to change after Cantera 2.6; for Cantera 2.6, rate
414 * constants of three-body reactions are multiplied with third-body
415 * concentrations (no change to legacy behavior). After Cantera 2.6,
416 * results will no longer include third-body concentrations and be
417 * consistent with conventional definitions (see Eq. 9.75 in
418 * Kee, Coltrin and Glarborg, 'Chemically Reacting Flow', Wiley
419 * Interscience, 2003).
420 */
421 void use_legacy_rate_constants(bool legacy=true) {
422 m_use_legacy_rate_constants = legacy;
423 }
424
425 //! Returns `true` if legacy rate constant definition should be used
426 bool legacy_rate_constants_used() {
427 return m_use_legacy_rate_constants;
428 }
429
430 //! @copydoc Messages::setLogger
431 void setLogger(Logger* logwriter) {
432 pMessenger->setLogger(logwriter);
433 }
434
435 //! Delete and free memory allocated per thread in multithreaded applications
436 /*!
437 * Delete the memory allocated per thread by Cantera. It should be called
438 * from within the thread just before the thread terminates. If your
439 * version of Cantera has not been specifically compiled for thread safety
440 * this function does nothing.
441 */
442 void thread_complete();
443
444 protected:
445 //! Set the default directories for input files.
446 /*!
447 * %Cantera searches for input files along a path that includes platform-
448 * specific default locations, and possibly user-specified locations.
449 * This function installs the platform-specific directories on the search
450 * path. It is invoked at startup by appinit(), and never should need to
451 * be called by user programs.
452 *
453 * The current directory (".") is always searched first. Then, on Windows
454 * platforms, if environment variable COMMONPROGRAMFILES is set (which it
455 * should be on Win XP or Win 2000), then directories under this one will
456 * be added to the search path. The %Cantera Windows installer installs
457 * data files to this location.
458 *
459 * On the Mac, directory '/Applications/Cantera/data' is added to the
460 * search path.
461 *
462 * On any platform, if environment variable CANTERA_DATA is set to a
463 * directory name, then this directory is added to the search path.
464 *
465 * Finally, the location where the data files were installed when
466 * %Cantera was built is added to the search path.
467 *
468 * Additional directories may be added by calling function addDirectory.
469 * @ingroup inputfiles
470 */
471 void setDefaultDirectories();
472
473 //! Current vector of input directories to search for input files
474 std::vector<std::string> inputDirs;
475
476 //! Current vector of XML file trees that have been previously parsed
477 //! The second element of the value is used to store the last-modified time
478 //! for the file, to enable change detection.
479 //!
480 //! @deprecated The XML input format is deprecated and will be removed in
481 //! Cantera 3.0.
482 std::map<std::string, std::pair<XML_Node*, int> > xmlfiles;
483 //! Vector of deprecation warnings that have been emitted (to suppress
484 //! duplicates)
485 std::set<std::string> warnings;
486
487 bool m_suppress_deprecation_warnings;
488 bool m_fatal_deprecation_warnings;
489 bool m_suppress_thermo_warnings;
490 bool m_suppress_warnings;
491 bool m_fatal_warnings;
492 bool m_use_legacy_rate_constants;
493
494 ThreadMessages pMessenger;
495
496 private:
497 //! Pointer to the single Application instance
498 static Application* s_app;
499};
500
501}
502
503#endif
Cantera::Application::Messages
Class to carry out messages.
Definition: application.h:51
Cantera::Application::Messages::errorMessage
std::vector< std::string > errorMessage
Current list of error messages.
Definition: application.h:161
Cantera::Application::Messages::logwriter
std::unique_ptr< Logger > logwriter
Current pointer to the logwriter.
Definition: application.h:164
Cantera::Application::Messages::writelogendl
void writelogendl()
Write an end of line character to the screen and flush output.
Definition: application.cpp:95
Cantera::Application::ThreadMessages
Class that stores thread messages for each thread, and retrieves them based on the thread id.
Definition: application.h:173
Cantera::Application::ThreadMessages::threadMsgMap_t
std::map< std::thread::id, pMessages_t > threadMsgMap_t
Typedef for map between a thread and the message.
Definition: application.h:188
Cantera::Application::ThreadMessages::ThreadMessages
ThreadMessages()
Constructor.
Definition: application.h:176
Cantera::Application::ThreadMessages::operator->
Messages * operator->()
Provide a pointer dereferencing overloaded operator.
Definition: application.cpp:108
Cantera::Application::ThreadMessages::m_threadMsgMap
threadMsgMap_t m_threadMsgMap
Thread Msg Map.
Definition: application.h:192
Cantera::Application::ThreadMessages::removeThreadMessages
void removeThreadMessages()
Remove a local thread message.
Definition: application.cpp:121
Cantera::Application
Class to hold global data.
Definition: application.h:47
Cantera::Application::warnings_suppressed
bool warnings_suppressed()
Returns true if warnings should be suppressed.
Definition: application.h:381
Cantera::Application::warn
void warn(const std::string &warning, const std::string &method, const std::string &extra="")
Generate a general purpose warning; repeated warnings are not suppressed.
Definition: application.cpp:188
Cantera::Application::warnings
std::set< std::string > warnings
Vector of deprecation warnings that have been emitted (to suppress duplicates)
Definition: application.h:485
Cantera::Application::use_legacy_rate_constants
void use_legacy_rate_constants(bool legacy=true)
Set definition used for rate constant calculation.
Definition: application.h:421
Cantera::Application::get_XML_File
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: application.cpp:205
Cantera::Application::s_app
static Application * s_app
Pointer to the single Application instance.
Definition: application.h:498
Cantera::Application::suppress_deprecation_warnings
void suppress_deprecation_warnings()
Globally disable printing of deprecation warnings.
Definition: application.h:355
Cantera::Application::writelog
void writelog(const std::string &msg)
Write a message to the screen.
Definition: application.h:333
Cantera::Application::inputDirs
std::vector< std::string > inputDirs
Current vector of input directories to search for input files.
Definition: application.h:474
Cantera::Application::addError
void addError(const std::string &r, const std::string &msg="")
Set an error condition in the application class without throwing an exception.
Definition: application.h:217
Cantera::Application::thermo_warnings_suppressed
bool thermo_warnings_suppressed()
Returns true if thermo warnings should be suppressed.
Definition: application.h:398
Cantera::Application::make_warnings_fatal
void make_warnings_fatal()
Turns Cantera warnings into exceptions.
Definition: application.h:387
Cantera::Application::setLogger
void setLogger(Logger *logwriter)
Install a logger.
Definition: application.h:431
Cantera::Application::warnlog
void warnlog(const std::string &warning, const std::string &msg)
Write a warning message to the screen.
Definition: application.h:343
Cantera::Application::make_deprecation_warnings_fatal
void make_deprecation_warnings_fatal()
Turns deprecation warnings into exceptions.
Definition: application.h:362
Cantera::Application::Instance
static Application * Instance()
Return a pointer to the one and only instance of class Application.
Definition: application.cpp:149
Cantera::Application::logErrors
void logErrors()
Prints all of the error messages using writelog.
Definition: application.h:242
Cantera::Application::~Application
virtual ~Application()
Destructor for class deletes global data.
Definition: application.cpp:158
Cantera::Application::get_XML_from_string
XML_Node * get_XML_from_string(const std::string &text)
Read a CTI or CTML string and fill up an XML tree.
Definition: application.cpp:242
Cantera::Application::lastErrorMessage
std::string lastErrorMessage()
Retrieve the last error message in a string.
Definition: application.h:232
Cantera::Application::legacy_rate_constants_used
bool legacy_rate_constants_used()
Returns true if legacy rate constant definition should be used.
Definition: application.h:426
Cantera::Application::close_XML_File
void close_XML_File(const std::string &file)
Close an XML File.
Definition: application.cpp:262
Cantera::Application::suppress_warnings
void suppress_warnings()
Globally disable printing of (user) warnings.
Definition: application.h:375
Cantera::Application::thread_complete
void thread_complete()
Delete and free memory allocated per thread in multithreaded applications.
Definition: application.cpp:200
Cantera::Application::xmlfiles
std::map< std::string, std::pair< XML_Node *, int > > xmlfiles
Current vector of XML file trees that have been previously parsed The second element of the value is ...
Definition: application.h:482
Cantera::Application::suppress_thermo_warnings
void suppress_thermo_warnings(bool suppress=true)
Globally disable printing of warnings about problematic thermo data, such as NASA polynomials with di...
Definition: application.h:393
Cantera::Application::pMessages_t
shared_ptr< Messages > pMessages_t
Typedef for thread specific messages.
Definition: application.h:168
Cantera::Application::getErrors
void getErrors(std::ostream &f)
Prints all of the error messages to an ostream.
Definition: application.h:237
Cantera::Application::warn_deprecated
void warn_deprecated(const std::string &method, const std::string &extra="")
Print a warning indicating that method is deprecated.
Definition: application.cpp:176
Cantera::Application::getErrorCount
int getErrorCount()
Return the number of errors that have been encountered so far.
Definition: application.h:222
Cantera::Application::Application
Application()
Constructor for class sets up the initial conditions Protected ctor access thru static member functio...
Definition: application.cpp:131
Cantera::Application::writelogendl
void writelogendl()
Write an endl to the screen and flush output.
Definition: application.h:338
Cantera::Application::ApplicationDestroy
static void ApplicationDestroy()
Static function that destroys the application class's data.
Definition: application.cpp:167
Cantera::Application::popError
void popError()
Discard the last error message.
Definition: application.h:227
Cantera::Logger
Base class for 'loggers' that write text messages to log files.
Definition: logger.h:41
Cantera::XML_Node
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:103
Cantera::Application::Messages::addError
void addError(const std::string &r, const std::string &msg="")
Set an error condition in the application class without throwing an exception.
Definition: application.cpp:66
Cantera::Application::Messages::logErrors
void logErrors()
Prints all of the error messages using writelog.
Definition: application.cpp:324
Cantera::Application::Messages::lastErrorMessage
std::string lastErrorMessage()
Retrieve the last error message in a string.
Definition: application.cpp:307
Cantera::Application::Messages::getErrors
void getErrors(std::ostream &f)
Prints all of the error messages to an ostream.
Definition: application.cpp:316
Cantera::Application::Messages::getErrorCount
int getErrorCount()
Return the number of errors that have been encountered so far.
Definition: application.cpp:80
Cantera::Application::Messages::popError
void popError()
Discard the last error message.
Definition: application.cpp:300
Cantera::Application::findInputFile
std::string findInputFile(const std::string &name)
Find an input file.
Definition: application.cpp:426
Cantera::Application::getDataDirectories
std::string getDataDirectories(const std::string &sep)
Get the Cantera data directories.
Definition: application.h:287
Cantera::Application::addDataDirectory
void addDataDirectory(const std::string &dir)
Add a directory to the data file search path.
Definition: application.cpp:397
Cantera::Application::setDefaultDirectories
void setDefaultDirectories()
Set the default directories for input files.
Definition: application.cpp:333
Cantera::Application::Messages::writelog
void writelog(const std::string &msg)
Write a message to the screen.
Definition: application.cpp:90
Cantera::Application::Messages::setLogger
void setLogger(Logger *logwriter)
Install a logger.
Definition: application.cpp:85
Cantera::Application::Messages::warnlog
void warnlog(const std::string &warning, const std::string &msg)
Write a warning message to the screen.
Definition: application.cpp:100
logger.h
Header for Base class for 'loggers' that write text messages to log files (see Writing messages to th...
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557