ctml.h

Go to the documentation of this file.

/**
 * @file ctml.h
 * CTML ("Cantera Markup Language") is the variant of XML that Cantera uses
 * to store data. These functions read and write it.
 * (see \ref inputfiles and importCTML, ck2ctml)
 */
// Copyright 2002  California Institute of Technology

#ifndef CT_CTML_H
#define CT_CTML_H

#include "ct_defs.h"
#include "xml.h"
#include "Array.h"

//! The ctml namespace adds functionality to the XML object, by providing
//! standard functions that read, write, and interpret XML files and
//! object trees.
/*!
 *  Standardization of reads and write from Cantera files occur here.
 */
namespace ctml
{

//! const Specifying the CTML version number
/*!
 * @todo Codify what the CTML_Version number means.
 */
const std::string CTML_Version = "1.4.1";

extern std::string FP_Format;

extern std::string INT_Format;

//!  This function adds a child node with the name, "bool", with a value
//!  consisting of a single bool
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "bool". It will have a title attribute, and the body
 *   of the XML node will be filled out with a single bool.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string titleString = "doSpecialOp";
   bool value = true;
   addBool(node, titleString, value);
   @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
   <parentNode>
     <bool title="doSpecialOp" type="optional">
        true
     <\integer>
   <\parentNode>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute
 *   @param value         Value - single bool
 *
 * @deprecated never used
 */
DEPRECATED(void addBool(Cantera::XML_Node& node, const std::string& titleString,
             const bool value));

//!  This function adds a child node with the name, "integer", with a value
//!  consisting of a single integer
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "integer". It will have a title attribute, and the body
 *   of the XML node will be filled out with a single integer
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string titleString = "maxIterations";
   int  value = 1000;
   std::string typeString = "optional";
   std::string units = "";
   addInteger(node, titleString, value, typeString, units);
   @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
   <parentNode>
     <integer title="maxIterations" type="optional">
        100
     <\integer>
   <\parentNode>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute
 *   @param value         Value - single integer
 *   @param unitsString   String name of the Units attribute. The default is to
 *                        have an empty string.
 *   @param typeString    String type. This is an optional parameter. The default
 *                        is to have an empty string.
 *
 * @todo I don't think this is used. Figure out what is used for writing integers,
 *       and codify that. unitsString shouldn't be here, since it's an int.
 *       typeString should be codified as to its usage.
 */
void addInteger(Cantera::XML_Node& node, const std::string& titleString,
                const int value, const std::string unitsString="",
                const std::string typeString="");

//!  This function adds a child node with the name, "float", with a value
//!  consisting of a single floating point number
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "float". It will have a title attribute, and the body
 *   of the XML node will be filled out with a single float
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string titleString = "activationEnergy";
   doublereal  value = 50.3;
   doublereal maxval = 1.0E3;
   doublereal minval = 0.0;
   std::string typeString = "optional";
   std::string unitsString = "kcal/gmol";
   addFloat(node, titleString, value, unitsString, typeString, minval, maxval);
   @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
   <parentNode>
     <float title="activationEnergy" type="optional" units="kcal/gmol" min="0.0" max="1.0E3">
        50.3
     <\float>
   <\parentNode>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute
 *   @param value         Value - single integer
 *   @param unitsString   String name of the Units attribute. The default is to
 *                        have an empty string.
 *   @param typeString    String type. This is an optional parameter. The default
 *                        is to have an empty string.
 *   @param minval        Minimum allowed value of the float. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *   @param maxval        Maximum allowed value of the float. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *
 * @todo I don't think this is used. Figure out what is used for writing floats,
 *       and codify that. minval and maxval should be codified.
 *       typeString should be codified as to its usage.
 */
void addFloat(Cantera::XML_Node& node, const std::string& titleString,
              const doublereal value, const std::string unitsString="",
              const std::string typeString="", const doublereal minval = Cantera::Undef,
              const doublereal maxval = Cantera::Undef);

//!  This function adds a child node with the name, "intArray", with a value
//!  consisting of a comma separated list of integers
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "intArray". It will have a title attribute, and the body
 *   of the XML node will be filled out with a comma separated list of
 *   integers
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string titleString = "additionalCases";
   int  n = 3;
   int cases[3] = [3, 6, 10];
   std::string typeString = "optional";
   std::string units = "";
   addIntegerArray(node, titleString, n, &cases[0], typeString, units);
   @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
   <parentNode>
     <intArray title="additionalCases" type="optional">
        3, 6, 10
     <\intArray>
   <\parentNode>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute
 *   @param n             Length of the integer vector.
 *   @param values        Pointer to a vector of integers
 *   @param unitsString   String name of the Units attribute. This is an optional
 *                        parameter. The default is to
 *                        have an empty string.
 *   @param typeString    String type. This is an optional parameter. The default
 *                        is to have an empty string.
 *   @param minval        Minimum allowed value of the int. This is an optional
 *                        parameter. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *   @param maxval        Maximum allowed value of the int. This is an optional
 *                        parameter. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *
 * @todo unitsString shouldn't be here, since it's an int. typeString should
 *       be codified as to its usage.
 *
 * @deprecated Not currently used.
 */
DEPRECATED(void addIntegerArray(Cantera::XML_Node& node, const std::string& titleString,
                     const size_t n, const int* const values,
                     const std::string unitsString="", const std::string typeString="",
                     const doublereal minval=Cantera::Undef,
                     const doublereal maxval=Cantera::Undef));

//!  This function adds a child node with the name, "floatArray", with a value
//!  consisting of a comma separated list of floats
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "floatArray". It will have a title attribute, and the body
 *   of the XML node will be filled out with a comma separated list of
 *   doublereals.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string titleString = "additionalTemperatures";
   int  n = 3;
   int Tcases[3] = [273.15, 298.15, 373.15];
   std::string typeString = "optional";
   std::string units = "Kelvin";
   addFloatArray(node, titleString, n, &cases[0], typeString, units);
   @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
   <parentNode>
     <floatArray title="additionalTemperatures" type="optional" units="Kelvin">
        273.15, 298.15, 373.15
     <\floatArray>
   <\parentNode>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute
 *   @param n             Length of the doubles vector.
 *   @param values        Pointer to a vector of doubles
 *   @param unitsString   String name of the Units attribute. This is an optional
 *                        parameter. The default is to
 *                        have an empty string.
 *   @param typeString    String type. This is an optional parameter. The default
 *                        is to have an empty string.
 *   @param minval        Minimum allowed value of the int. This is an optional
 *                        parameter. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *   @param maxval        Maximum allowed value of the int. This is an optional
 *                        parameter. The default is the
 *                        special double, Cantera::Undef, which means to ignore the
 *                        entry.
 *
 * @todo I don't think this is used. Figure out what is used for writing integers,
 *       and codify that. unitsString shouldn't be here, since it's an int.
 *       typeString should be codified as to its usage.
 */
void addFloatArray(Cantera::XML_Node& node,  const std::string& titleString,
                   const size_t n,  const doublereal* const values,
                   const std::string unitsString="", const std::string typeString="",
                   const doublereal minval = Cantera::Undef,
                   const doublereal maxval = Cantera::Undef);

void addNamedFloatArray(Cantera::XML_Node& parentNode, const std::string& name, const int n,
                        const doublereal* const vals, const std::string units = "",
                        const std::string type = "",
                        const doublereal minval = Cantera::Undef,
                        const doublereal maxval = Cantera::Undef);




//!  This function adds a child node with the name string with a string value
//!  to the current node
/*!
 *   This function will add a child node to the current XML node, with the
 *   name "string". It will have a title attribute, and the body
 *   of the XML node will be filled out with the valueString argument verbatim.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &node;
 addString(XML_Node& node, std::string titleString, std::string valueString,
 std::string typeString);
 @endverbatim
 *
 *  Creates the following the snippet in the XML file:
 *  @verbatim
 <string title="titleString" type="typeString">
   valueString
 <\string>
 @endverbatim
 *
 *   @param node          reference to the XML_Node object of the parent XML element
 *   @param valueString   Value string to be used in the new XML node.
 *   @param titleString   String name of the title attribute
 *   @param typeString    String type. This is an optional parameter.
 */
void addString(Cantera::XML_Node& node,  const std::string& titleString,
               const std::string& valueString, const std::string typeString="");


//!  This function reads the current node or a  child node of the current node
//!  with the default name, "floatArray", with a value field
//!  consisting of a comma separated list of floats
/*!
 *   This function will read either the current XML node or a  child node
 *   to the current XML node, with the
 *   name "floatArray". It will have a title attribute, and the body
 *   of the XML node will be filled out with a comma separated list of
 *   doublereals.
 *     Get an array of floats from the XML Node. The argument field
 *   is assumed to consist of an arbitrary number of comma
 *   separated floats, with an arbitrary amount of white space
 *   separating each field.
 *      If the node array has an units attribute field, then
 *   the units are used to convert the floats, iff convert is true.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &State_XMLNode;
   vector_fp v;
   bool convert = true;
   unitsString = "";
   nodeName="floatArray";
   getFloatArray(State_XMLNode, v, convert, unitsString, nodeName);
 @endverbatim
 *
 *  reads the corresponding XML file:
 *
 *  @verbatim
 <state>
   <floatArray  units="m3">   32.4, 1, 100. <\floatArray>
 <\state>
 @endverbatim
 *
 *  Will produce the vector
 *
 *         v[0] = 32.4
 *         v[1] = 1.0
 *         v[2] = 100.
 *
 *
 *   @param  node         XML parent node of the floatArray
 *   @param  v            Output vector of floats containing the floatArray information.
 *   @param  convert      Conversion to SI is carried out if this boolean is
 *                        True. The default is true.
 *   @param  unitsString  String name of the type attribute. This is an optional
 *                        parameter. The default is to have an empty string.
 *                        The only string that is recognized is actEnergy.
 *                        Anything else has no effect. This affects what
 *                        units converter is used.
 *   @param  nodeName     XML Name of the XML node to read.
 *                        The default value for the node name is floatArray
 *   @return              Returns the number of floats read into v.
 */
size_t getFloatArray(const Cantera::XML_Node& node, std::vector<doublereal> & v,
                     const bool convert=true, const std::string unitsString="",
                     const std::string nodeName = "floatArray");

//! This function interprets the value portion of an XML element
//! as a string. It then separates the string up into tokens
//! according to the location of white space.
/*!
 * The separate tokens are returned in the string vector
 *
 * @param node   Node to get the value from
 * @param v      Output vector containing the string tokens
 */
void getStringArray(const Cantera::XML_Node& node, std::vector<std::string>& v);


//! This routine is used to interpret the value portions of XML
//! elements that contain colon separated pairs.
/*!
 *  These are used, for example, in describing the element
 *  composition of species.
 * @verbatim
        <atomArray> H:4 C:1 <atomArray>
   @endverbatim
 *  The string is first separated into a string vector according
 * to the location of white space. Then each string is again
 * separated into two parts according to the location of a
 * colon in the string. The first part of the string is
 * used as the key, while the second part of the string is
 * used as the value, in the return map.
 * It is an error to not find a colon in each string pair.
 *
 *  @param node Current node
 *  @param m    Output Map containing the pairs of values found
 *              in the XML Node
 */
void getMap(const Cantera::XML_Node& node, std::map<std::string, std::string>& m);

//! This function interprets the value portion of an XML element
//! as a series of "Pairs" separated by white space.
/*!
 * Each pair consists of nonwhite-space characters.
 * The first ":" found in the pair string is used to separate
 * the string into two parts. The first part is called the "key"
 * The second part is called the "val".
 * String vectors of key[i] and val[i] are returned in the
 * argument list.
 * Warning: No spaces are allowed in each pair. Quotes get included as part
 *          of the string.
 *   Example:
 *       @verbatim
     <xmlNode>
        red:112    blue:34
        green:banana
     </xmlNode>
            @endverbatim
 *
 * Returns:
 *          key       val
 *     0:   "red"     "112"
 *     1:   "blue"    "34"
 *     2:   "green"   "banana"
 *
 *
 *  @param node             XML Node
 *  @param key              Vector of keys for each entry
 *  @param val              Vector of values for each entry
 *
 *  @return Returns the number of pairs found
 */
int getPairs(const Cantera::XML_Node& node, std::vector<std::string>& key,
             std::vector<std::string>& val);

//! This function interprets the value portion of an XML element
//! as a series of "Matrix ids and entries" separated by white space.
/*!
 * Each pair consists of nonwhite-space characters.
 * The first two ":" found in the pair string is used to separate
 * the string into three parts. The first part is called the first
 * key. The second part is the second key. Both parts must match
 * an entry in the keyString1 and keyString2, respectively,
 * in order to provide a location to
 * place the object in the matrix.
 * The third part is called the value. It is expected to be
 * a double. It is translated into a double and placed into the
 * correct location in the matrix.
 *
 * Warning: No spaces are allowed in each triplet. Quotes are part
 *          of the string.
 *   Example
 *         keyString = red, blue, black, green
 *
 * @verbatim
     <xmlNode>
         red:green:112
         blue:black:3.3E-23

     </xmlNode>
 @endverbatim
 * Returns:
 *     retnValues(0, 3) = 112
 *     retnValues(1, 2) = 3.3E-23
 *
 *
 *  @param node          XML Node containing the information for the matrix
 *  @param keyStringRow  Key string for the row
 *  @param keyStringCol  Key string for the column entries
 *  @param returnValues  Return Matrix.
 *  @param convert       If this is true, and if the node has a units
 *                       attribute, then conversion to si units is carried
 *                       out. Default is true.
 *  @param matrixSymmetric  If true entries are made so that the matrix
 *                       is always symmetric. Default is false.
 */
void getMatrixValues(const Cantera::XML_Node& node,
                     const std::vector<std::string>& keyStringRow,
                     const std::vector<std::string>& keyStringCol,
                     Cantera::Array2D& returnValues, const bool convert = true,
                     const bool matrixSymmetric = false);


//!  Get a vector of integer values from a child element.
/*!
 *  Returns a std::map containing a keyed values for child XML_Nodes
 *  of the current node with the name, "integer".
 *  In the keyed mapping there will be a list of titles vs. values
 *  for all of the XML nodes.
 *  The integer XML_nodes are expected to be in a particular form created
 *  by the function addInteger(). One value per XML_node is expected.
 *
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &State_XMLNode;
   std::map<std::string, integer> v;
   getinteger(State_XMLNode, v);
 @endverbatim
 *
 *  reads the corresponding XML file:
 *
 *  @verbatim
 <state>
   <integer title="i1">   1  <\integer>
   <integer title="i2">   2  <\integer>
   <integer title="i3">   3  <\integer>
 <\state>
 @endverbatim
 *
 *  Will produce the mapping:
 *
 *         v["i1"] = 1
 *         v["i2"] = 2
 *         v["i3"] = 3
 *
 *
 *   @param node     Current XML node to get the values from
 *   @param v        Output map of the results.
 */
void getIntegers(const Cantera::XML_Node& node, std::map<std::string,int>& v);


//!  Get a floating-point value from a child element.
/*!
 *  Returns a doublereal value for the child named 'name' of element 'parent'. If
 *  'type' is supplied and matches a known unit type, unit
 *  conversion to SI will be done if the child element has an attribute
 *  'units'.
 *
 *  Note, it's an error for the child element not to exist.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &State_XMLNode;
 doublereal pres = OneAtm;
 if (state_XMLNode.hasChild("pressure")) {
   pres = getFloat(State_XMLNode, "pressure", "toSI");
 }
 @endverbatim
 *
 *  reads the corresponding XML file:
 *  @verbatim
 <state>
   <pressure units="Pa"> 101325.0 </pressure>
 <\state>
 @endverbatim
 *
 *   @param parent reference to the XML_Node object of the parent XML element
 *   @param name   Name of the XML child element
 *   @param type   String type. Currently known types are "toSI" and "actEnergy",
 *                 and "" , for no conversion. The default value is "",
 *                 which implies that no conversion is allowed.
 */
doublereal getFloat(const Cantera::XML_Node& parent, const std::string& name,
                    const std::string type="");

//!  Get a floating-point value from the current XML element
/*!
 *  Returns a doublereal value from the current element. If
 *  'type' is supplied and matches a known unit type, unit
 *  conversion to SI will be done if the child element has an attribute  'units'.
 *
 *  Note, it's an error for the child element not to exist.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &State_XMLNode;
 doublereal pres = OneAtm;
 if (state_XMLNode.hasChild("pressure")) {
   XML_Node *pres_XMLNode = State_XMLNode.getChild("pressure");
   pres = getFloatCurrent(pres_XMLNode, "toSI");
 }
 @endverbatim
 *
 *  Reads the corresponding XML file:
 *  @verbatim
 <state>
   <pressure units="Pa"> 101325.0 </pressure>
 <\state>
 @endverbatim
 *
 *   @param currXML reference to the current XML_Node object
 *   @param type   String type. Currently known types are "toSI" and "actEnergy",
 *                 and "" , for no conversion. The default value is "",
 *                 which implies that no conversion is allowed.
 */
doublereal getFloatCurrent(const Cantera::XML_Node& currXML, const std::string type="");

//!  Get an optional floating-point value from a child element.
/*!
 *  Returns a doublereal value for the child named 'name' of element 'parent'. If
 *  'type' is supplied and matches a known unit type, unit
 *  conversion to SI will be done if the child element has an attribute
 *  'units'.
 *
 *
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &State_XMLNode;
 doublereal pres = OneAtm;
 bool exists = getOptionalFloat(State_XMLNode, "pressure", pres, "toSI");
 @endverbatim
 *
 *  reads the corresponding XML file:
 *  @verbatim
 <state>
   <pressure units="Pa"> 101325.0 </pressure>
 <\state>
 @endverbatim
 *
 *   @param parent reference to the XML_Node object of the parent XML element
 *   @param name   Name of the XML child element
 *   @param fltRtn Float Return. It will be overridden if the XML
 *                 element exists.
 *   @param type   String type. Currently known types are "toSI"
 *                 and "actEnergy",
 *                 and "" , for no conversion. The default value is "",
 *                 which implies that no conversion is allowed.
 *
 * @return returns true if the child element named "name" exists
 */
bool getOptionalFloat(const Cantera::XML_Node& parent, const std::string& name,
                      doublereal& fltRtn, const std::string type="");


//!  Get a vector of floating-point values from a child element.
/*!
 *  Returns a std::map containing a keyed values for child XML_Nodes
 *  of the current node with the name, "float".
 *  In the keyed mapping there will be a list of titles vs. values
 *  for all of the XML nodes.
 *  The float XML_nodes are expected to be in a particular form created
 *  by the function addFloat(). One value per XML_node is expected.
 *
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &State_XMLNode;
   std::map<std::string,double> v;
   bool convert = true;
   getFloats(State_XMLNode, v, convert);
 @endverbatim
 *
 *  reads the corresponding XML file:
 *
 *  @verbatim
 <state>
   <float title="a1" units="m3">   32.4 <\float>
   <float title="a2" units="cm3">   1.  <\float>
   <float title="a3">             100.  <\float>
 <\state>
 @endverbatim
 *
 *  Will produce the mapping:
 *
 *         v["a1"] = 32.4
 *         v["a2"] = 1.0E-6
 *         v["a3"] = 100.
 *
 *
 *   @param node     Current XML node to get the values from
 *   @param v        Output map of the results.
 *   @param convert  Turn on conversion to SI units
 */
void getFloats(const Cantera::XML_Node& node, std::map<std::string, double>& v,
               const bool convert=true);

//!  Get an integer value from a child element.
/*!
 *  Returns an integer value for the child named 'name' of element 'parent'.
 *
 *  Note, it's an error for the child element not to exist.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &State_XMLNode;
 int number = 1;
 if (state_XMLNode.hasChild("NumProcs")) {
 number = getInteger(State_XMLNode, "numProcs");
 }
 @endverbatim
 *
 *  reads the corresponding XML file:
 *  @verbatim
 <state>
   <numProcs> 10 <numProcs/>
 <\state>
 @endverbatim
 *
 *   @param parent reference to the XML_Node object of the parent XML element
 *   @param name   Name of the XML child element
 */
int getInteger(const Cantera::XML_Node& parent, std::string name);

//!  Get a floating-point value from a child element with a defined units field
/*!
 *  Returns a doublereal value for the child named 'name' of element 'parent'.
 *  'type' must be supplied and match a known unit type.
 *
 *  Note, it's an error for the child element not to exist.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &State_XMLNode;
 doublereal pres = OneAtm;
 if (state_XMLNode.hasChild("pressure")) {
 pres = getFloatDefaultUnits(State_XMLNode, "pressure", "Pa", "toSI");
 }
 @endverbatim
 *
 *  reads the corresponding XML file:
 *  @verbatim
 <state>
   <pressure units="Pa"> 101325.0 </pressure>
 <\state>
 @endverbatim
 *
 *   @param parent reference to the XML_Node object of the parent XML element
 *   @param name   Name of the XML child element
 *   @param defaultUnits Default units string to be found in the units attribute.
 *                 If the units string in the XML field is equal to defaultUnits,
 *                 no units conversion will be carried out.
 *   @param type   String type. Currently known types are "toSI" and "actEnergy",
 *                 and "" , for no conversion. The default value is "",
 *                 which implies that no conversion is allowed.
 */
doublereal getFloatDefaultUnits(const Cantera::XML_Node& parent, std::string name,
                                std::string defaultUnits, std::string type="toSI");

//!  Get an optional model name from a named child node.
/*!
 *  Returns the model name attribute for the child named 'nodeName' of element 'parent'.
 *  Note, it's optional for the child node to exist
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
 std::string modelName = "";
 bool exists = getOptionalModel(transportNode, "compositionDependence",
                  modelName);
 @endverbatim
 *
 *  reads the corresponding XML file:
 *  @verbatim
  <transport model="Simple">
    <compositionDependence model="Solvent_Only"/>
  </transport>
 @endverbatim
 *
 *   On return modelName is set to "Solvent_Only".
 *
 *   @param parent reference to the XML_Node object of the parent XML element
 *   @param nodeName   Name of the XML child element
 *   @param modelName  On return this contains the contents of the model attribute
 *
 *   @return True if the nodeName XML node exists. False otherwise.
 */
bool getOptionalModel(const Cantera::XML_Node& parent, const std::string nodeName,
                      std::string& modelName);

//!  This function reads a child node with the default name, "floatArray", with a value
//!  consisting of a comma separated list of floats
/*!
 *   This function will read a child node to the current XML node, with the
 *   name "floatArray". It will have a title attribute, and the body
 *   of the XML node will be filled out with a comma separated list of
 *   doublereals.
 *     Get an array of floats from the XML Node. The argument field
 *   is assumed to consist of an arbitrary number of comma
 *   separated floats, with an arbitrary amount of white space
 *   separating each field.
 *      If the node array has an units attribute field, then
 *   the units are used to convert the floats, iff convert is true.
 *      This function is a wrapper around the function getFloatArray().
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &State_XMLNode;
   vector_fp v;
   bool convert = true;
   unitsString = "";
   nodeName="floatArray";
   getFloatArray(State_XMLNode, v, convert, unitsString, nodeName);
 @endverbatim
 *
 *  reads the corresponding XML file:
 *
 *  @verbatim
 <state>
   <floatArray  units="m3">   32.4, 1, 100. <\floatArray>
 <\state>
 @endverbatim
 *
 *  Will produce the vector
 *
 *         v[0] = 32.4
 *         v[1] = 1.0
 *         v[2] = 100.
 *
 *
 *   @param  node         XML parent node of the floatArray
 *   @param  typeString   Returns the type attribute of the current node.
 *   @param  xmin         Returns the minimum value attribute of the
 *                        current node.
 *   @param  xmax         Returns the maximum value attribute of the
 *                        current node.
 *   @param  coeffs       Output vector of floats containing the floatArray information.
 */
void getFunction(const Cantera::XML_Node& node, std::string& typeString,
                 doublereal& xmin, doublereal& xmax, std::vector<doublereal> & coeffs);

//! Search the child nodes of the current node for an XML Node with a Title
//! attribute of a given name.
/*!
 *   @param node   Current node from which to conduct the search
 *   @param title  Name of the title attribute
 *
 *   @return  Returns a pointer to the matched child node. Returns 0 if no node is
 *            found.
 */
Cantera::XML_Node* getByTitle(const Cantera::XML_Node& node, const std::string& title);

//!  This function reads a child node with the name string with a specific
//!  title attribute named titleString
/*!
 *   This function will read a child node to the current XML node with the name "string".
 *   It must have a title attribute, named titleString, and the body
 *   of the XML node will be read into the valueString output argument.
 *
 *   If the child node is not found then the empty string is returned.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   getString(XML_Node& node, std::string titleString, std::string valueString,
   std::string typeString);
 @endverbatim
 *
 *  Reads the following the snippet in the XML file:
 *  @verbatim
   <string title="titleString" type="typeString">
     valueString
   <\string>
 @endverbatim
 *
 *   @param node          Reference to the XML_Node object of the parent XML element
 *   @param titleString   String name of the title attribute of the child node
 *   @param valueString   Value string that is found in the child node. output variable
 *   @param typeString    String type. This is an optional output variable. It is filled
 *                        with the attribute "type" of the XML entry.
 */
void getString(const Cantera::XML_Node& node, const std::string& titleString,
               std::string& valueString, std::string& typeString);

//!  This function attempts to read a named child node and returns with the contents in the value string.
//!  title attribute named "titleString"
/*!
 *   This function will read a child node to the current XML node, with the
 *   name "string". It must have a title attribute, named titleString, and the body
 *   of the XML node will be read into the valueString output argument.
 *
 *   If the child node is not found then the empty string is returned.
 *
 *  Example:
 *
 * Code snippet:
 *       @verbatim
   const XML_Node &node;
   std::string valueString;
   std::string typeString;
   std::string nameString = "timeIncrement";
   getString(XML_Node& node, nameString, valueString, valueString, typeString);
 @endverbatim
 *
 *  Reads the following the snippet in the XML file:
 *
 *  *  @verbatim
 <nameString type="typeString">
   valueString
 <\nameString>
 @endverbatim
 *
 *  or alternatively as a retrofit and special case, it also reads the following case
 *
 *  @verbatim
 <string title="nameString" type="typeString">
   valueString
 <\string>
 @endverbatim
 *
 *   @param node          Reference to the XML_Node object of the parent XML element
 *   @param nameString    Name of the XML Node                               input  variable
 *   @param valueString   Value string that is found in the child node.      output variable
 *   @param typeString    String type. This is an optional output variable. It is filled
 *                        with the attribute "type" of the XML entry.         output variable
 */
void getNamedStringValue(const Cantera::XML_Node& node, const std::string& nameString, std::string& valueString,
                         std::string& typeString);


//!  This function reads a child node with the name, nameString, and returns
//!  its xml value as the return string
/*!
 *   If the child XML_node named "name" doesn't exist, the empty string is returned.
 *
 * Code snippet:
 *       @verbatim
 const XML_Node &parent;
 string nameString = "vacency_species";
 string valueString = getChildValue(parent, nameString
 std::string typeString);
 @endverbatim
 *
 *  returns valueString = "O(V)"
 *
 *  from the following the snippet in the XML file:
 *
 *  @verbatim
 <vacencySpecies>
   O(V)
 <\vancencySpecies>
 @endverbatim
 *
 *   @param parent     parent reference to the XML_Node object of the parent XML element
 *   @param nameString Name of the child XML_Node to read the value from.
 *
 *   @return           String value of the child XML_Node
 */
std::string getChildValue(const Cantera::XML_Node& parent,
                          const std::string& nameString);

//! Read an ctml file from a file and fill up an XML tree
/*!
 *  This is the main routine that reads a ctml file and puts it into
 *  an XML_Node tree
 *
 *  @param node    Root of the tree
 *  @param file    Name of the file
 *  @param debug   Turn on debugging printing
 */
void get_CTML_Tree(Cantera::XML_Node* node, const std::string file,
                   const int debug = 0);

//! Convert a cti file into a ctml file
/*!
 *
 *  @param   file    Pointer to the file
 *  @param   debug   Turn on debug printing
 *
 *  @ingroup inputfiles
 */
void ct2ctml(const char* file, const int debug = 0);
}

#endif