global.h

Go to the documentation of this file.

/**
 * @file global.h
 * This file contains definitions for utility functions and text for modules,
 * inputfiles, logs, textlogs, HTML_logs (see \ref inputfiles, \ref logs,
 * \ref textlogs and \ref HTML_logs).
 *
 * @ingroup utils
 *
 * These functions store 
 * some parameters in  global storage that are accessible at all times
 * from the calling application.
 * Contains module definitions for
 *     -  inputfiles  (see \ref inputfiles)
 *     -  logs        (see \ref logs)
 *     -  textlogs    (see \ref textlogs)
 *     -  HTML_logs   (see \ref HTML_logs)
 */

/* 
 * $Revision: 368 $
 * $Date: 2010-01-03 19:46:26 -0500 (Sun, 03 Jan 2010) $
 */

// Copyright 2001  California Institute of Technology

#ifndef CT_GLOBAL_H
#define CT_GLOBAL_H

#include "ct_defs.h"

namespace Cantera {

    class XML_Node;
    class Logger;

  //! Return the number of errors that have been encountered so far
  /*!
   * @ingroup errorhandling
   */
  int nErrors();

  //! Returns the last error message
  /*!
   * @return String containing the description of the last error 
   *         message.
   *
   * @ingroup errorhandling
   */
  std::string lastErrorMessage();

  //! Set an error condition in the application class without throwing an exception.
  /*!
   * This routine adds an error message to the end of the stack
   * of errors that Cantera accumulates in the Application
   * class.
   * @param r Procedure name which is generating the error condition
   * @param msg Descriptive message of the error condition.
   *
   * @ingroup errorhandling
   */
  void setError(std::string r, std::string msg);

  //!  Prints all of the error messages to an ostream
  /*!
   * Write out all of the saved error messages to the ostream f
   * using the member function writelog of class logger.
   * Cantera saves a stack of exceptions that it
   * has caught in the Application class. This routine writes
   * out all of the error messages to the ostream
   * and then clears them from internal storage.
   *
   * @param f ostream which will receive the error messages
   *
   * \ingroup errorhandling
   */
   void showErrors(std::ostream& f);

  //! Print all of the error messages using function writelog of class logger.
  /*!
   * Print all of the error messages 
   * using the member function writelog of class logger.
   * Write out all of the saved error messages to the log device.
   * Cantera saves a stack of exceptions that it
   * has caught in the Application class. This routine writes
   * out all of the error messages to the log, usually stdout,
   * and then clears them from internal storage.
   *
   * \ingroup errorhandling
   */
  void showErrors();

  //! Discard the last error message
  /*!
   * %Cantera saves a stack of exceptions that it
   * has caught in the Application class. This routine eliminates
   * the last exception to be added to that stack.
   *
   * \ingroup errorhandling
   */
  void popError();

  /*!
   * @defgroup inputfiles Input File Handling
   *
   * The properties of phases and interfaces are specified in 
   * text files. These procedures handle various aspects of reading
   * these files.
   *
   * For input files not specified by an absolute pathname,
   * %Cantera searches
   * for input files along a path that includes platform-specific
   * default locations, and possibly user-specified locations. 
   *
   * The current directory (".") is always searched first. Then, on
   * Windows platforms, if environment variable COMMONPROGRAMFILES
   * is set (which it should be on Win XP or Win 2000), then
   * directories under this one will be added to the search
   * path. The %Cantera Windows installer installs data files to this
   * location.
   * 
   * On the Mac, directory '/Applications/Cantera/data' is added to the
   * search path. 
   * 
   * On any platform, if environment variable CANTERA_DATA is set to a 
   * directory name, then this directory is added to the search path. 
   *
   * Finally, the location where the data files were installed when
   * %Cantera was built is added to the search path.
   * 
   * Additional directories may be added by calling function addDirectory.
   *
   * There are two different types of input files within %Cantera:
   *    ctml: This is an xml file layed out in such a way that %Cantera can 
   *          interpret the contents.
   *    cti:  A human-readable ascii format for information that %Cantera
   *          will read.
   *
   *   %Cantera can take its input from both types of files. However, given
   *   a file in cti format, the initial operation that %Cantera will perform
   *   is to translate the cti file into a ctml file. 
   *   The translation is carried out via a system call to a python interpretor
   *   program that actually carries out the translation. In general, a new
   *   ctml file is created by the translation that is written to the current
   *   local directory. 
   *   The ctml file is then read back into %Cantera as the input.
   *
   * Other input routines in other modules:
   *   @see importKinetics()
   *
   * @{
   */

  //! Find an input file.
  /*!
   *    This routine will search for a file in the default
   *    locations specified for the application.
   *    See the routine setDefaultDirectories() listed above.
   *
   *    The default set of directories specified for the application
   *    will be searched if a '/' or an '\\' is found in the
   *    name. If either is found then a relative path name is
   *    presumed, and the default directories are not searched.
   *
   *    The presence of the file is determined by whether the file
   *    can be opened for reading by the current user.
   *
   *  @param name Name of the input file to be searched for
   *
   *    @return
   *    
   *      The absolute path name of the first matching
   *      file is returned. If a relative path name
   *      is indicated, the relative path name is returned.
   *  
   *      If the file is not found, a message is written to 
   *      stdout and  a CanteraError exception is thrown.
   *
   * @ingroup inputfiles
   */
  std::string findInputFile(std::string name);

  //!  Add a directory to the input file search path.
  /*!
   * @ingroup inputfiles
   *
   * @param dir  String name for the directory to be added to the search path
   */
  void addDirectory(std::string dir);

  //@}

  //! Delete and free all memory associated with the application
  /*!
   * Delete all global data.  It should be called at the end of the
   * application if leak checking is to be done.
   */
  void appdelete();

  //! Delete and free memory allocated per thread in multithreaded applications
  /*!
   * Delete the memory allocated per thread by Cantera.  It should be called from
   * within the thread just before the thread terminates.  If your version of Cantera has not
   * been specifically compiled for thread safety this function does nothing.
   */
  void thread_complete() ;

  //! Returns root directory where %Cantera where installed
  /*!
   * @return
   *  Returns a string containing the name of the base directory where %Cantera is installed.
   *  If the environmental variable CANTERA_ROOT is defined, this function will
   *  return its value, preferentially.
   *
   * @ingroup inputfiles
   */
  std::string canteraRoot();

  //! Sets the temporary file directory.
  /*!
   *  The default is to use the 
   *  directory specified by enviroment variable TMP or TEMP. If neither 
   *  of these are defined, then the current working directory will be 
   *  used for temporary files. Call this function to specify some other
   *  place to put temporary files.
   *
   * @ingroup inputfiles
   *
   * @param tmp String name for the temporary directory
   */
  void setTmpDir(std::string tmp);

  //! Retrieves the  directory name where temporary files are created
  /*!
   * @ingroup inputfiles
   * @return
   *    Returns a string containing the directory name
   */
  std::string tmpDir();

  //! Delay time in seconds.
  /*!
   * @return
   *     Returns the length of time in seconds for calls to the
   *     sleep function.
   * @ingroup inputfiles
   */
  std::string sleep();

  /*!
   * @defgroup logs Diagnostic Output
   *
   * Writing diagnostic information to the screen or to a file.
   * It is often useful to be able to write diagnostic messages to
   * the screen or to a file. Cantera provides two sets of
   * procedures for this purpose. The first set is designed to
   * write text messages to the screen to document the progress of
   * a complex calculation, such as a flame simulation.The second
   * set writes nested lists in HTML format. This is useful to
   * print debugging output for a complex calculation that calls
   * many different procedures.
   */

  /*!
   * @defgroup textlogs Writing messages to the screen
   * @ingroup logs
   */

 
  //!  Write a message to the screen. 
  /*!
   * The string may be of any
   * length, and may contain end-of-line characters. This method is
   * used throughout Cantera to write log messages. It can also be
   * called by user programs.  The advantage of using writelog over
   * writing directly to the standard output is that messages
   * written with writelog will display correctly even when Cantera
   * is used from MATLAB or other application that do not have a
   * standard output stream.
   *
   *  This routine is part of the interface suite whose behavior changes
   *  with the interface. The interface suite has been moved to the
   *  class logger and inherited classes of logger.
   *
   * @param msg  String message to be written to the screen 
   * @ingroup textlogs
   */
  void writelog(const std::string& msg);


  //!  Write a message to the screen. 
  /*!
   * The string may be of any
   * length, and may contain end-of-line characters. This method is
   * used throughout %Cantera to write log messages.
   *
   *  This routine is part of the interface suite whose behavior changes
   *  with the interface. The interface suite has been moved to the
   *  class logger and inherited classes of logger.
   *
   * @param msg  c character string to be written to the screen 
   * @ingroup textlogs
   */
  void writelog(const char* msg);

  //! Write a formatted message to the screen
  /*!
   * Using the printf formatting of C, write a message to the screen
   * with variable values.
   *
   * Here, we format an internal string with the correct values
   * and then feed it into writelog().
   *
   * @param fmt  c format string for the following arguments
   * @ingroup textlogs
   */
  void writelogf(const char* fmt,...);

  //! Write an end of line character to the screen and flush output
  /*!
   * Some implementations differentiate between \n and endl in
   * terms of when the output is flushed.
   */
  void writelogendl();

  //! Write an error message and terminate execution.
  /*!
   *  This routine is part of the interface suite whose behavior changes
   *  with the interface. The interface suite has been moved to the
   *  class logger and inherited classes of logger.
   *
   *  @param msg Error message to be written to the screen.
   *  @ingroup textlogs
   */
  void error(const std::string& msg);

  //! returns 1 for MATLAB, 2 for Python, and 0 for C++ or Fortran.
  /*!
   *  This routine is part of the interface suite whose behavior changes
   *  with the interface. The interface suite has been moved to the
   *  class logger and inherited classes of logger.
   *
   *   @ingroup textlogs
   */ 
  int userInterface();

  //! Install a logger. 
  /*!
   *  Called by the language interfaces to install an appropriate logger. 
   *  The logger is used for the writelog() function
   *
   * @param logwriter Pointer to a logger object
   * @see Logger.
   * @ingroup textlogs
   */
  void setLogger(Logger* logwriter);

  //! Return the conversion factor to convert unit std::string 'unit' 
  //! to SI units.
  /*!
   * @param unit String containing the units
   */
  doublereal toSI(std::string unit);
  
  /// Return the conversion factor to convert activation energy unit
  /// std::string 'unit' to Kelvin.
  /*!
   * @param unit  String containing the activation energy units
   */
  doublereal actEnergyToSI(std::string unit);
  
  /// Return a pointer to the XML tree for a Cantera input file. 
  /*!
   *  This routine will find the file and read the XML file into an
   *  XML tree structure. Then, a pointer will be returned. If the
   *  file has already been processed, then just the pointer will
   *  be returned.
   *
   * @param file String containing the relative or absolute file name
   * @param debug Debug flag
   */
  XML_Node* get_XML_File(std::string file, int debug = 0);
  
  /// Close a Cantera input file.
  /*!
   * @param file String containing the relative or absolute file name
   */
  void close_XML_File(std::string file);


#ifdef WITH_HTML_LOGS

  /*!
   * @defgroup HTML_logs Writing HTML Logfiles
   * @ingroup logs
   * 
   *  These functions are designed to allow writing HTML diagnostic
   *  messages in a manner that allows users to control how much
   *  diagnostic output to print. It works like this: Suppose you
   *  have function A that invokes function B that invokes function
   *  C. You want to be able to print diagnostic messages just from
   *  function A, or from A and B, or from A, B, and C, or to turn
   *  off printing diagnostic messages altogether. All you need to
   *  do is call 'beginLogGroup' within function A, and specify a
   *  loglevel value. Then in B, call beginLogGroup again, but
   *  without an explicit value for loglevel. By default, the
   *  current level is decremented by one in beginLogGroup. If it
   *  is <= 0, no log messages are written. Thus, if each function
   *  begins with beginLogGroup and calls endLogGroup before
   *  returning, then setting loglevel = 3 will cause messages from
   *  A, B, and C to be written (in nested HTML lists), loglevel =
   *  2 results in messages only being written from A and B, etc.
   */
  //@{
  //@}


  //!Create a new group for log messages.
  /*!
   *  Usually this is called
   *  upon entering the function, with the title parameter equal to
   *  the name of the function or method. Subsequent messages
   *  written with addLogEntry will appear grouped under this
   *  heading, until endLogGroup() is called.
   *
   *  @param title String name of the LogGroup
   *  @param loglevel loglevel of the group. 
   *  @ingroup HTML_logs
   */
  void beginLogGroup(std::string title, int loglevel=-99);

  //! Add an entry to an HTML log file.
  /*!
   *  Entries appear in the form "tag:value".
   *
   * @param tag      tag
   * @param value    string value
   *
   * @ingroup HTML_logs
   */
  void addLogEntry(std::string tag, std::string value);

  //! Add an entry to an HTML log file.
  /*!
   *  Entries appear in the form "tag:value".
   *
   * @param tag      tag
   * @param value    double value
   *
   * @ingroup HTML_logs
   */
  void addLogEntry(std::string tag, doublereal value);

  //! Add an entry to an HTML log file.
  /*!
   *  Entries appear in the form "tag:value".
   *
   * @param tag      tag
   * @param value    int value
   *
   * @ingroup HTML_logs
   */
  void addLogEntry(std::string tag, int value);

  //! Add an entry msg string to an HTML log file.
  /*!
   * Add a message string to the HTML log file
   *
   * @param msg      string mesg
   *
   * @ingroup HTML_logs
   */
  void addLogEntry(std::string msg);

  //! Close the current group of log messages. 
  /*!
   *  This is typically
   *  called just before leaving a function or method, to close the
   *  group of messages that were output from this
   *  function. Subsequent messages written with addLogEntry() will
   *  appear at the next-higher level in the outline, unless
   *  beginLogGroup() is called first to create a new group.  
   *
   * @param title Name of the log group. It defaults to the most recent
   *              log group created.
   * @ingroup HTML_logs
   */
    void endLogGroup(std::string title="");

  //! Write the HTML log file.
  /*!
   *  Log entries are stored in memory in
   *  an XML tree until this function is called, which writes the
   *  tree to a file and clears the entries stored in memory.  The
   *  output file will have the name specified in the 'file'
   *  argument.  If this argument has no extension, the extension
   *  '.html' will be appended. Also, if the file already exists, an
   *  integer will be appended to the name so that no existing log
   *  file will be overwritten. 
   *  WITH_HTML_LOGS must be defined.
   *
   *  @param  file Name of the file to be written
   *  @ingroup HTML_logs
   */
  void write_logfile(std::string file = "log.html");

#else
  inline void beginLogGroup(std::string title, int loglevel=-99) {}
  inline void addLogEntry(std::string tag, std::string value) {}
  inline void addLogEntry(std::string tag, doublereal value) {}
  inline void addLogEntry(std::string tag, int value) {}
  inline void addLogEntry(std::string msg) {}
  inline void endLogGroup(std::string title="") {}
  inline void write_logfile(std::string file = "log.html") {}
#endif

 
  //! This routine will locate an XML node in either the input
  //! XML tree or in another input file specified by the file
  //! part of the file_ID string.
  /*!
   *    Searches are based on the
   *    ID attribute of the XML element only.
   *
   * @param file_ID This is a concatenation of two strings seperated
   *                by the "#" character. The string before the
   *                pound character is the file name of an xml
   *                file to carry out the search. The string after
   *                the # character is the ID attribute
   *                of the xml element to search for.
   *                The string is interpreted as a file string if
   *                no # character is in the string.
   *
   * @param root    If the file string is empty, searches for the
   *                xml element with matching ID attribute are
   *                carried out from this XML node.
   *
   * @return 
   *    Returns the XML_Node, if found. Returns null if not found.
   */
  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 by the file
  //! part of the file_ID string.
  /*!
   * Searches are based on the
   * XML element name and the ID attribute of the XML element.
   * An exact match of both is usually required. However, the
   * ID attribute may be set to "", in which case the first
   * xml element with the correct element name will be returned.
   *
   * @param nameTarget This is the XML element name to look for.
   *
   * @param file_ID This is a concatenation of two strings seperated
   *                by the "#" character. The string before the
   *                pound character is the file name of an xml
   *                file to carry out the search. The string after
   *                the # character is the ID attribute
   *                of the xml element to search for.
   *                The string is interpreted as a file string if
   *                no # character is in the string.
   *
   * @param root    If the file string is empty, searches for the
   *                xml element with matching ID attribute are
   *                carried out from this XML node.
   *
   * @return 
   *    Returns the XML_Node, if found. Returns null if not found.
   */
  XML_Node* get_XML_NameID(const std::string& nameTarget,
                           const std::string& file_ID, 
                           XML_Node* root);
}

#endif