Cantera  2.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, HTML_logs (see \ref inputfiles, \ref logs,
5  * \ref textlogs and \ref HTML_logs).
6  *
7  * @ingroup utils
8  *
9  * These functions store
10  * some parameters in global storage that are accessible at all times
11  * from the calling application.
12  * Contains module definitions for
13  * - inputfiles (see \ref inputfiles)
14  * - logs (see \ref logs)
15  * - textlogs (see \ref textlogs)
16  * - HTML_logs (see \ref HTML_logs)
17  */
18 // Copyright 2001 California Institute of Technology
19 
20 #ifndef CT_GLOBAL_H
21 #define CT_GLOBAL_H
22 
23 #include "ct_defs.h"
24 
25 namespace Cantera
26 {
27 
28 class XML_Node;
29 class Logger;
30 
31 //! Return the number of errors that have been encountered so far
32 /*!
33  * @ingroup errorhandling
34  */
35 int nErrors();
36 
37 //! Returns the last error message
38 /*!
39  * @return String containing the description of the last error
40  * message.
41  *
42  * @ingroup errorhandling
43  */
44 std::string lastErrorMessage();
45 
46 //! Set an error condition in the application class without throwing an exception.
47 /*!
48  * This routine adds an error message to the end of the stack
49  * of errors that Cantera accumulates in the Application
50  * class.
51  * @param r Procedure name which is generating the error condition
52  * @param msg Descriptive message of the error condition.
53  *
54  * @ingroup errorhandling
55  */
56 void setError(std::string r, std::string msg);
57 
58 //! Prints all of the error messages to an ostream
59 /*!
60  * Write out all of the saved error messages to the ostream f
61  * using the member function writelog of class logger.
62  * Cantera saves a stack of exceptions that it
63  * has caught in the Application class. This routine writes
64  * out all of the error messages to the ostream
65  * and then clears them from internal storage.
66  *
67  * @param f ostream which will receive the error messages
68  *
69  * \ingroup errorhandling
70  */
71 void showErrors(std::ostream& f);
72 
73 //! Print all of the error messages using function writelog of class logger.
74 /*!
75  * Print all of the error messages
76  * using the member function writelog of class logger.
77  * Write out all of the saved error messages to the log device.
78  * Cantera saves a stack of exceptions that it
79  * has caught in the Application class. This routine writes
80  * out all of the error messages to the log, usually stdout,
81  * and then clears them from internal storage.
82  *
83  * \ingroup errorhandling
84  */
85 void showErrors();
86 
87 //! Discard the last error message
88 /*!
89  * %Cantera saves a stack of exceptions that it
90  * has caught in the Application class. This routine eliminates
91  * the last exception to be added to that stack.
92  *
93  * \ingroup errorhandling
94  */
95 void popError();
96 
97 /*!
98  * @defgroup inputfiles Input File Handling
99  *
100  * The properties of phases and interfaces are specified in
101  * text files. These procedures handle various aspects of reading
102  * these files.
103  *
104  * For input files not specified by an absolute pathname,
105  * %Cantera searches
106  * for input files along a path that includes platform-specific
107  * default locations, and possibly user-specified locations.
108  *
109  * The current directory (".") is always searched first. Then, on
110  * Windows platforms, if environment variable COMMONPROGRAMFILES
111  * is set (which it should be on Win XP or Win 2000), then
112  * directories under this one will be added to the search
113  * path. The %Cantera Windows installer installs data files to this
114  * location.
115  *
116  * On the Mac, directory '/Applications/Cantera/data' is added to the
117  * search path.
118  *
119  * On any platform, if environment variable CANTERA_DATA is set to a
120  * directory name, then this directory is added to the search path.
121  *
122  * Finally, the location where the data files were installed when
123  * %Cantera was built is added to the search path.
124  *
125  * Additional directories may be added by calling function addDirectory.
126  *
127  * There are two different types of input files within %Cantera:
128  * ctml: This is an xml file laid out in such a way that %Cantera can
129  * interpret the contents.
130  * cti: A human-readable ascii format for information that %Cantera
131  * will read.
132  *
133  * %Cantera can take its input from both types of files. However, given
134  * a file in cti format, the initial operation that %Cantera will perform
135  * is to translate the cti file into a ctml file.
136  * The translation is carried out via a system call to a python interpreter
137  * program that actually carries out the translation. In general, a new
138  * ctml file is created by the translation that is written to the current
139  * local directory.
140  * The ctml file is then read back into %Cantera as the input.
141  *
142  * Other input routines in other modules:
143  * @see importKinetics()
144  *
145  * @{
146  */
147 
148 //! Find an input file.
149 /*!
150  * This routine will search for a file in the default
151  * locations specified for the application.
152  * See the routine setDefaultDirectories() listed above.
153  *
154  * The default set of directories specified for the application
155  * will be searched if a '/' or an '\\' is found in the
156  * name. If either is found then a relative path name is
157  * presumed, and the default directories are not searched.
158  *
159  * The presence of the file is determined by whether the file
160  * can be opened for reading by the current user.
161  *
162  * @param name Name of the input file to be searched for
163  *
164  * @return
165  *
166  * The absolute path name of the first matching
167  * file is returned. If a relative path name
168  * is indicated, the relative path name is returned.
169  *
170  * If the file is not found, a message is written to
171  * stdout and a CanteraError exception is thrown.
172  *
173  * @ingroup inputfiles
174  */
175 std::string findInputFile(std::string name);
176 
177 //! Add a directory to the input file search path.
178 /*!
179  * @ingroup inputfiles
180  *
181  * @param dir String name for the directory to be added to the search path
182  */
183 void addDirectory(std::string dir);
184 
185 //@}
186 
187 //! Delete and free all memory associated with the application
188 /*!
189  * Delete all global data. It should be called at the end of the
190  * application if leak checking is to be done.
191  */
192 void appdelete();
193 
194 //! Delete and free memory allocated per thread in multithreaded applications
195 /*!
196  * Delete the memory allocated per thread by Cantera. It should be called from
197  * within the thread just before the thread terminates. If your version of Cantera has not
198  * been specifically compiled for thread safety this function does nothing.
199  */
200 void thread_complete() ;
201 
202 //! Returns root directory where %Cantera where installed
203 /*!
204  * @return
205  * Returns a string containing the name of the base directory where %Cantera is installed.
206  * If the environmental variable CANTERA_ROOT is defined, this function will
207  * return its value, preferentially.
208  *
209  * @ingroup inputfiles
210  */
211 std::string canteraRoot();
212 
213 /*!
214  * @defgroup logs Diagnostic Output
215  *
216  * Writing diagnostic information to the screen or to a file.
217  * It is often useful to be able to write diagnostic messages to
218  * the screen or to a file. Cantera provides two sets of
219  * procedures for this purpose. The first set is designed to
220  * write text messages to the screen to document the progress of
221  * a complex calculation, such as a flame simulation.The second
222  * set writes nested lists in HTML format. This is useful to
223  * print debugging output for a complex calculation that calls
224  * many different procedures.
225  */
226 
227 /*!
228  * @defgroup textlogs Writing messages to the screen
229  * @ingroup logs
230  */
231 
232 
233 //! Write a message to the screen.
234 /*!
235  * The string may be of any
236  * length, and may contain end-of-line characters. This method is
237  * used throughout Cantera to write log messages. It can also be
238  * called by user programs. The advantage of using writelog over
239  * writing directly to the standard output is that messages
240  * written with writelog will display correctly even when Cantera
241  * is used from MATLAB or other application that do not have a
242  * standard output stream.
243  *
244  * This routine is part of the interface suite whose behavior changes
245  * with the interface. The interface suite has been moved to the
246  * class logger and inherited classes of logger.
247  *
248  * @param msg String message to be written to the screen
249  * @ingroup textlogs
250  */
251 void writelog(const std::string& msg);
252 
253 
254 //! Write a message to the screen.
255 /*!
256  * The string may be of any
257  * length, and may contain end-of-line characters. This method is
258  * used throughout %Cantera to write log messages.
259  *
260  * This routine is part of the interface suite whose behavior changes
261  * with the interface. The interface suite has been moved to the
262  * class logger and inherited classes of logger.
263  *
264  * @param msg c character string to be written to the screen
265  * @ingroup textlogs
266  */
267 void writelog(const char* msg);
268 
269 //! Write a formatted message to the screen
270 /*!
271  * Using the printf formatting of C, write a message to the screen
272  * with variable values.
273  *
274  * Here, we format an internal string with the correct values
275  * and then feed it into writelog().
276  *
277  * @param fmt c format string for the following arguments
278  * @ingroup textlogs
279  */
280 void writelogf(const char* fmt,...);
281 
282 //! Write an end of line character to the screen and flush output
283 /*!
284  * Some implementations differentiate between \n and endl in
285  * terms of when the output is flushed.
286  */
287 void writelogendl();
288 
289 //! Write an error message and terminate execution.
290 /*!
291  * This routine is part of the interface suite whose behavior changes
292  * with the interface. The interface suite has been moved to the
293  * class logger and inherited classes of logger.
294  *
295  * @param msg Error message to be written to the screen.
296  * @ingroup textlogs
297  */
298 void error(const std::string& msg);
299 
300 //! returns 1 for MATLAB, 2 for Python, and 0 for C++ or Fortran.
301 /*!
302  * This routine is part of the interface suite whose behavior changes
303  * with the interface. The interface suite has been moved to the
304  * class logger and inherited classes of logger.
305  *
306  * @ingroup textlogs
307  * @deprecated
308  */
309 DEPRECATED(int userInterface());
310 
311 //! Install a logger.
312 /*!
313  * Called by the language interfaces to install an appropriate logger.
314  * The logger is used for the writelog() function
315  *
316  * @param logwriter Pointer to a logger object
317  * @see Logger.
318  * @ingroup textlogs
319  */
320 void setLogger(Logger* logwriter);
321 
322 //! Return the conversion factor to convert unit std::string 'unit'
323 //! to SI units.
324 /*!
325  * @param unit String containing the units
326  */
327 doublereal toSI(std::string unit);
328 
329 /// Return the conversion factor to convert activation energy unit
330 /// std::string 'unit' to Kelvin.
331 /*!
332  * @param unit String containing the activation energy units
333  */
334 doublereal actEnergyToSI(std::string unit);
335 
336 /// Return a pointer to the XML tree for a Cantera input file.
337 /*!
338  * This routine will find the file and read the XML file into an
339  * XML tree structure. Then, a pointer will be returned. If the
340  * file has already been processed, then just the pointer will
341  * be returned.
342  *
343  * @param file String containing the relative or absolute file name
344  * @param debug Debug flag
345  */
346 XML_Node* get_XML_File(std::string file, int debug = 0);
347 
348 /// Close a Cantera input file.
349 /*!
350  * @param file String containing the relative or absolute file name
351  */
352 void close_XML_File(std::string file);
353 
354 
355 #ifdef WITH_HTML_LOGS
356 
357 /*!
358  * @defgroup HTML_logs Writing HTML Logfiles
359  * @ingroup logs
360  *
361  * These functions are designed to allow writing HTML diagnostic
362  * messages in a manner that allows users to control how much
363  * diagnostic output to print. It works like this: Suppose you
364  * have function A that invokes function B that invokes function
365  * C. You want to be able to print diagnostic messages just from
366  * function A, or from A and B, or from A, B, and C, or to turn
367  * off printing diagnostic messages altogether. All you need to
368  * do is call 'beginLogGroup' within function A, and specify a
369  * loglevel value. Then in B, call beginLogGroup again, but
370  * without an explicit value for loglevel. By default, the
371  * current level is decremented by one in beginLogGroup. If it
372  * is <= 0, no log messages are written. Thus, if each function
373  * begins with beginLogGroup and calls endLogGroup before
374  * returning, then setting loglevel = 3 will cause messages from
375  * A, B, and C to be written (in nested HTML lists), loglevel =
376  * 2 results in messages only being written from A and B, etc.
377  */
378 
379 //!Create a new group for log messages.
380 /*!
381  * Usually this is called
382  * upon entering the function, with the title parameter equal to
383  * the name of the function or method. Subsequent messages
384  * written with addLogEntry will appear grouped under this
385  * heading, until endLogGroup() is called.
386  *
387  * @param title String name of the LogGroup
388  * @param loglevel loglevel of the group.
389  * @ingroup HTML_logs
390  */
391 void beginLogGroup(std::string title, int loglevel=-99);
392 
393 //! Add an entry to an HTML log file.
394 /*!
395  * Entries appear in the form "tag:value".
396  *
397  * @param tag tag
398  * @param value string value
399  *
400  * @ingroup HTML_logs
401  */
402 void addLogEntry(std::string tag, std::string value);
403 
404 //! Add an entry to an HTML log file.
405 /*!
406  * Entries appear in the form "tag:value".
407  *
408  * @param tag tag
409  * @param value double value
410  *
411  * @ingroup HTML_logs
412  */
413 void addLogEntry(std::string tag, doublereal value);
414 
415 //! Add an entry to an HTML log file.
416 /*!
417  * Entries appear in the form "tag:value".
418  *
419  * @param tag tag
420  * @param value int value
421  *
422  * @ingroup HTML_logs
423  */
424 void addLogEntry(std::string tag, int value);
425 
426 //! Add an entry msg string to an HTML log file.
427 /*!
428  * Add a message string to the HTML log file
429  *
430  * @param msg string mesg
431  *
432  * @ingroup HTML_logs
433  */
434 void addLogEntry(std::string msg);
435 
436 //! Close the current group of log messages.
437 /*!
438  * This is typically
439  * called just before leaving a function or method, to close the
440  * group of messages that were output from this
441  * function. Subsequent messages written with addLogEntry() will
442  * appear at the next-higher level in the outline, unless
443  * beginLogGroup() is called first to create a new group.
444  *
445  * @param title Name of the log group. It defaults to the most recent
446  * log group created.
447  * @ingroup HTML_logs
448  */
449 void endLogGroup(std::string title="");
450 
451 //! Write the HTML log file.
452 /*!
453  * Log entries are stored in memory in
454  * an XML tree until this function is called, which writes the
455  * tree to a file and clears the entries stored in memory. The
456  * output file will have the name specified in the 'file'
457  * argument. If this argument has no extension, the extension
458  * '.html' will be appended. Also, if the file already exists, an
459  * integer will be appended to the name so that no existing log
460  * file will be overwritten.
461  * WITH_HTML_LOGS must be defined.
462  *
463  * @param file Name of the file to be written
464  * @ingroup HTML_logs
465  */
466 void write_logfile(std::string file = "log.html");
467 
468 #else
469 inline void beginLogGroup(std::string title, int loglevel=-99) {}
470 inline void addLogEntry(std::string tag, std::string value) {}
471 inline void addLogEntry(std::string tag, doublereal value) {}
472 inline void addLogEntry(std::string tag, int value) {}
473 inline void addLogEntry(std::string msg) {}
474 inline void endLogGroup(std::string title="") {}
475 inline void write_logfile(std::string file = "log.html") {}
476 #endif
477 
478 //! This routine will locate an XML node in either the input
479 //! XML tree or in another input file specified by the file
480 //! part of the file_ID string.
481 /*!
482  * Searches are based on the
483  * ID attribute of the XML element only.
484  *
485  * @param file_ID This is a concatenation of two strings separated
486  * by the "#" character. The string before the
487  * pound character is the file name of an xml
488  * file to carry out the search. The string after
489  * the # character is the ID attribute
490  * of the xml element to search for.
491  * The string is interpreted as a file string if
492  * no # character is in the string.
493  *
494  * @param root If the file string is empty, searches for the
495  * xml element with matching ID attribute are
496  * carried out from this XML node.
497  *
498  * @return
499  * Returns the XML_Node, if found. Returns null if not found.
500  */
501 XML_Node* get_XML_Node(const std::string& file_ID, XML_Node* root);
502 
503 
504 //! This routine will locate an XML node in either the input
505 //! XML tree or in another input file specified by the file
506 //! part of the file_ID string.
507 /*!
508  * Searches are based on the
509  * XML element name and the ID attribute of the XML element.
510  * An exact match of both is usually required. However, the
511  * ID attribute may be set to "", in which case the first
512  * xml element with the correct element name will be returned.
513  *
514  * @param nameTarget This is the XML element name to look for.
515  *
516  * @param file_ID This is a concatenation of two strings separated
517  * by the "#" character. The string before the
518  * pound character is the file name of an xml
519  * file to carry out the search. The string after
520  * the # character is the ID attribute
521  * of the xml element to search for.
522  * The string is interpreted as a file string if
523  * no # character is in the string.
524  *
525  * @param root If the file string is empty, searches for the
526  * xml element with matching ID attribute are
527  * carried out from this XML node.
528  *
529  * @return
530  * Returns the XML_Node, if found. Returns null if not found.
531  */
532 XML_Node* get_XML_NameID(const std::string& nameTarget,
533  const std::string& file_ID,
534  XML_Node* root);
535 }
536 
537 #endif
538