ctml Namespace Reference

The ctml namespace adds functionality to the XML object, by providing standard functions that read, write, and interpret XML files and object trees. More...

Functions
void	ct2ctml (const char *file, const int debug=0)
	Convert a cti file into a ctml file.
void	get_CTML_Tree (Cantera::XML_Node *node, const std::string file, const int debug=0)
	Read an ctml file from a file and fill up an XML tree.
void	addBool (Cantera::XML_Node &node, const std::string &titleString, const bool value)
	This function adds a child node with the name, "bool", with a value consisting of a single bool.
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, "integer", with a value consisting of a single integer.
void	addIntegerArray (Cantera::XML_Node &node, const std::string &titleString, const int 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, "intArray", with a value consisting of a comma separated list of integers.
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, "float", with a value consisting of a single floating point number.
void	addFloatArray (Cantera::XML_Node &node, const std::string &titleString, const int n, const doublereal *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.
void	addString (Cantera::XML_Node &node, const std::string &titleString, const std::string &valueString, const std::string typeString="")
	This function adds a child node with the name string with a string value to the current node.
XML_Node *	getByTitle (const Cantera::XML_Node &node, const std::string &title)
	Search the child nodes of the current node for an XML Node with a Title attribute of a given name.
std::string	getChildValue (const Cantera::XML_Node &parent, const std::string &nameString)
	This function reads a child node with the name, nameString, and returns its xml value as the return string.
void	getString (const Cantera::XML_Node &node, const std::string &titleString, std::string &valueString, std::string &typeString)
	This function reads a child node with the name string with a specific title attribute named titleString.
void	getIntegers (const Cantera::XML_Node &node, std::map< std::string, int > &v)
	Get a vector of integer values from a child element.
void	getFloats (const Cantera::XML_Node &node, std::map< std::string, double > &v, const bool convert=true)
	Get a vector of floating-point values from a child element.
doublereal	getFloat (const Cantera::XML_Node &parent, const std::string &name, const std::string type="")
	Get a floating-point value from a child element.
doublereal	getFloatCurrent (const Cantera::XML_Node &currXML, const std::string type="")
	Get a floating-point value from the current XML element.
bool	getOptionalFloat (const Cantera::XML_Node &parent, const std::string &name, doublereal &fltRtn, const std::string type="")
	Get an optional floating-point value from a child element.
doublereal	getFloatDefaultUnits (const Cantera::XML_Node &parent, std::string name, std::string defaultUnits, std::string type="toSI")
	Get a floating-point value from a child element with a defined units field.
bool	getOptionalModel (const Cantera::XML_Node &parent, const std::string nodeName, std::string &modelName)
	Get an optional model name from a named child node.
int	getInteger (const Cantera::XML_Node &parent, std::string name)
	Get an integer value from a child element.
int	getFloatArray (const Cantera::XML_Node &node, Cantera::vector_fp &v, const bool convert=true, const std::string unitsString="", const std::string nodeName="floatArray")
	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.
void	getMap (const Cantera::XML_Node &node, std::map< std::string, std::string > &m)
	This routine is used to interpret the value portions of XML elements that contain colon separated pairs.
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 "Pairs" separated by white space.
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)
	This function interprets the value portion of an XML element as a series of "Matrix ids and entries" separated by white space.
void	getStringArray (const Cantera::XML_Node &node, std::vector< std::string > &v)
	This function interprets the value portion of an XML element as a string.
void	getFunction (const Cantera::XML_Node &node, std::string &typeString, doublereal &xmin, doublereal &xmax, Cantera::vector_fp &v)
	This function reads a child node with the default name, "floatArray", with a value consisting of a comma separated list of floats.
Variables
const std::string	CTML_Version = "1.4.1"
	const Specifying the CTML version number

---

Detailed Description

The ctml namespace adds functionality to the XML object, by providing standard functions that read, write, and interpret XML files and object trees.

---

Function Documentation

void addBool	(	Cantera::XML_Node &	node,
		const std::string &	titleString,
		const bool	value
	)

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 snipet:

     const XML_Node &node;
     std::string titleString = "doSpecialOp";
     bool value = true;
     addBool(node, titleString, value);
     

Creates the following the snippet in the XML file:

     <parentNode>
       <bool title="doSpecialOp" type="optional">
          true
       <\integer>
     <\parentNode>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute
	value	Value - single bool

Todo:

I don't think this is used. Figure out what is used for writing bools, and codify that.

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, "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 snipet:

     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);
     

Creates the following the snippet in the XML file:

     <parentNode>
       <float title="activationEnergy" type="optional" units="kcal/gmol" min="0.0" max="1.0E3">
          50.3
       <\float>
     <\parentNode>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute
	value	Value - single integer
	unitsString	String name of the Units attribute. The default is to have an empty string.
	typeString	String type. This is an optional parameter. The default is to have an empty string.
	minval	Minimum allowed value of the float. The default is the special double, Cantera::Undef, which means to ignore the entry.
	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 addFloatArray	(	Cantera::XML_Node &	node,
		const std::string &	titleString,
		const int	n,
		const doublereal *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 snipet:

     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);
     

Creates the following the snippet in the XML file:

     <parentNode>
       <floatArray title="additionalTemperatures" type="optional" units="Kelvin">
          273.15, 298.15, 373.15
       <\floatArray>
     <\parentNode>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute
	n	Length of the doubles vector.
	values	Pointer to a vector of doubles
	unitsString	String name of the Units attribute. This is an optional parameter. The default is to have an empty string.
	typeString	String type. This is an optional parameter. The default is to have an empty string.
	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.
	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 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, "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 snipet:

     const XML_Node &node;
     std::string titleString = "maxIterations";
     int  value = 1000;
     std::string typeString = "optional";
     std::string units = "";
     addInteger(node, titleString, value, typeString, units);
     

Creates the following the snippet in the XML file:

     <parentNode>
       <integer title="maxIterations" type="optional">
          100
       <\integer>
     <\parentNode>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute
	value	Value - single integer
	unitsString	String name of the Units attribute. The default is to have an empty string.
	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 addIntegerArray	(	Cantera::XML_Node &	node,
		const std::string &	titleString,
		const int	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, "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 snipet:

     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);
     

Creates the following the snippet in the XML file:

     <parentNode>
       <intArray title="additionalCases" type="optional">
          3, 6, 10
       <\intArray>
     <\parentNode>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute
	n	Length of the integer vector.
	values	Pointer to a vector of integers
	unitsString	String name of the Units attribute. This is an optional parameter. The default is to have an empty string.
	typeString	String type. This is an optional parameter. The default is to have an empty string.
	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.
	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 addString	(	Cantera::XML_Node &	node,
		const std::string &	titleString,
		const std::string &	valueString,
		const std::string	typeString = ""
	)

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 snipet:

   const XML_Node &node;
   addString(XML_Node& node, std::string titleString, std::string valueString, 
   std::string typeString);
   

Creates the following the snippet in the XML file:

   <string title="titleString" type="typeString">
     valueString
   <\string>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	valueString	Value string to be used in the new XML node.
	titleString	String name of the title attribute
	typeString	String type. This is an optional parameter.

void get_CTML_Tree	(	Cantera::XML_Node *	node,
		const std::string	file,
		const int	debug = 0
	)

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

Parameters:

	node	Root of the tree
	file	Name of the file
	debug	Turn on debugging printing

Cantera::XML_Node * getByTitle	(	const Cantera::XML_Node &	node,
		const std::string &	title
	)

Search the child nodes of the current node for an XML Node with a Title attribute of a given name.

Parameters:

	node	Current node from which to conduct the search
	title	Name of the title attribute

Returns:

Returns a pointer to the matched child node. Returns 0 if no node is found.

std::string getChildValue	(	const Cantera::XML_Node &	parent,
		const std::string &	nameString
	)

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 snipet:

   const XML_Node &parent;
   string nameString = "vacency_species";
   string valueString = getChildValue(parent, nameString
   std::string typeString);
   

returns valueString = "O(V)"

from the following the snippet in the XML file:

   <vacencySpecies>
     O(V)
   <\vancencySpecies>
   

Parameters:

	parent	parent reference to the XML_Node object of the parent XML element
	nameString	Name of the childe XML_Node to read the value from.

Returns:

String value of the child XML_Node

Referenced by HMWSoln::initThermoXML(), DebyeHuckel::initThermoXML(), ThermoPhase::setStateFromXML(), SurfPhase::setStateFromXML(), and MolalityVPSSTP::setStateFromXML().

doublereal getFloat	(	const Cantera::XML_Node &	parent,
		const std::string &	name,
		const std::string	type = ""
	)

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 snipet:

   const XML_Node &State_XMLNode;
   doublereal pres = OneAtm;
   if (state_XMLNode.hasChild("pressure")) {
     pres = getFloat(State_XMLNode, "pressure", "toSI");
   }
   

reads the corresponding XML file:

   <state>
     <pressure units="Pa"> 101325.0 </pressure>
   <\state>
   

Parameters:

	parent	reference to the XML_Node object of the parent XML element
	name	Name of the XML child element
	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.

Referenced by PDSS_SSVol::constructPDSSXML(), PDSS_HKFT::constructPDSSXML(), PDSS_ConstVol::constructPDSSXML(), VPSSMgr_Water_ConstVol::createInstallPDSS(), VPSSMgr_ConstVol::createInstallPDSS(), VPSSMgr_Water_ConstVol::initThermoXML(), VPSSMgr_ConstVol::initThermoXML(), MineralEQ3::initThermoXML(), IdealSolidSolnPhase::initThermoXML(), IdealMolalSoln::initThermoXML(), HMWSoln::initThermoXML(), DebyeHuckel::initThermoXML(), EdgePhase::setParametersFromXML(), SurfPhase::setParametersFromXML(), StoichSubstanceSSTP::setParametersFromXML(), MetalSHEelectrons::setParametersFromXML(), ThermoPhase::setStateFromXML(), and MolalityVPSSTP::setStateFromXML().

int getFloatArray	(	const Cantera::XML_Node &	node,
		Cantera::vector_fp &	v,
		const bool	convert = true,
		const std::string	unitsString = "",
		const std::string	nodeName = "floatArray"
	)

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 snipet:

     const XML_Node &State_XMLNode;
     vector_fp v;
     bool convert = true;
     unitsString = "";
     nodeName="floatArray";
     getFloatArray(State_XMLNode, v, convert, unitsString, nodeName);
   

reads the corresponding XML file:

   <state>
     <floatArray  units="m3">   32.4, 1, 100. <\floatArray>
   <\state>
   

Will produce the vector

v[0] = 32.4 v[1] = 1.0 v[2] = 100.

Parameters:

	node	XML parent node of the floatArray
	v	Output vector of floats containing the floatArray information.
	convert	Conversion to SI is carried out if this boolean is True. The default is true.
	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.
	nodeName	XML Name of the XML node to read. The default value for the node name is floatArray

Returns:

Returns the number of floats read into v.

Referenced by PDSS_SSVol::constructPDSSXML(), HMWSoln::readXMLBinarySalt(), HMWSoln::readXMLLambdaNeutral(), HMWSoln::readXMLMunnnNeutral(), HMWSoln::readXMLPsiCommonAnion(), HMWSoln::readXMLPsiCommonCation(), HMWSoln::readXMLThetaAnion(), HMWSoln::readXMLThetaCation(), and HMWSoln::readXMLZetaCation().

doublereal getFloatCurrent	(	const Cantera::XML_Node &	currXML,
		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 snipet:

   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");
   }
   

reads the corresponding XML file:

   <state>
     <pressure units="Pa"> 101325.0 </pressure>
   <\state>
   

Parameters:

	currXML	reference to the current XML_Node object
	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 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 snipet:

   const XML_Node &State_XMLNode;
   doublereal pres = OneAtm;
   if (state_XMLNode.hasChild("pressure")) {
   pres = getFloatDefaultUnits(State_XMLNode, "pressure", "Pa", "toSI");
   }
   

reads the corresponding XML file:

   <state>
     <pressure units="Pa"> 101325.0 </pressure>
   <\state>
   

Parameters:

	parent	reference to the XML_Node object of the parent XML element
	name	Name of the XML child element
	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.
	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.

Referenced by StoichSubstanceSSTP::initThermoXML(), MineralEQ3::initThermoXML(), and MetalSHEelectrons::initThermoXML().

void getFloats	(	const Cantera::XML_Node &	node,
		std::map< std::string, double > &	v,
		const bool	convert = true
	)

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 snipet:

     const XML_Node &State_XMLNode;
     std::map<std::string,double> v;
     bool convert = true;
     getFloats(State_XMLNode, v, convert);
   

reads the corresponding XML file:

   <state>
     <float title="a1" units="m3">   32.4 <\float>
     <float title="a2" units="cm3">   1.  <\float>
     <float title="a3">             100.  <\float>
   <\state>
   

Will produce the mapping:

v["a1"] = 32.4 v["a2"] = 1.0E-6 v["a3"] = 100.

Parameters:

	node	Current XML node to get the values from
	v	Output map of the results.
	convert	Turn on conversion to SI units

void getFunction	(	const Cantera::XML_Node &	node,
		std::string &	typeString,
		doublereal &	xmin,
		doublereal &	xmax,
		Cantera::vector_fp &	v
	)

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 snipet:

     const XML_Node &State_XMLNode;
     vector_fp v;
     bool convert = true;
     unitsString = "";
     nodeName="floatArray";
     getFloatArray(State_XMLNode, v, convert, unitsString, nodeName);
   

reads the corresponding XML file:

   <state>
     <floatArray  units="m3">   32.4, 1, 100. <\floatArray>
   <\state>
   

Will produce the vector

v[0] = 32.4 v[1] = 1.0 v[2] = 100.

Parameters:

	node	XML parent node of the floatArray
	typeString	Returns the type attribute of the current node.
	xmin	Returns the minimum value attribute of the current node.
	xmax	Returns the maximum value attribute of the current node.
	v	Output vector of floats containing the floatArray information.

int getInteger	(	const Cantera::XML_Node &	parent,
		std::string	name
	)

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 snipet:

   const XML_Node &State_XMLNode;
   int number = 1;
   if (state_XMLNode.hasChild("NumProcs")) {
   number = getInteger(State_XMLNode, "numProcs");
   }
   

reads the corresponding XML file:

   <state>
     <numProcs> 10 <numProcs/>
   <\state>
   

Parameters:

	parent	reference to the XML_Node object of the parent XML element
	name	Name of the XML child element

void getIntegers	(	const Cantera::XML_Node &	node,
		std::map< std::string, int > &	v
	)

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 snipet:

     const XML_Node &State_XMLNode;
     std::map<std::string, integer> v;
     getinteger(State_XMLNode, v);
   

reads the corresponding XML file:

   <state>
     <integer title="i1">   1  <\integer>
     <integer title="i2">   2  <\integer>
     <integer title="i3">   3  <\integer>
   <\state>
   

Will produce the mapping:

v["i1"] = 1 v["i2"] = 2 v["i3"] = 3

Parameters:

	node	Current XML node to get the values from
	v	Output map of the results.

void getMap	(	const Cantera::XML_Node &	node,
		std::map< std::string, std::string > &	m
	)

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.

          <atomArray> H:4 C:1 <atomArray\>
     

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.

Parameters:

	node	Current node
	m	Output Map containing the pairs of values found in the XML Node

Referenced by HMWSoln::initThermoXML(), and DebyeHuckel::initThermoXML().

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
	)

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

       <xmlNode>
           red:green:112
           blue:black:3.3E-23
   
       </xmlNode>
   

Returns: retnValues(0, 3) = 112 retnValues(1, 2) = 3.3E-23

Parameters:

	node	XML Node containing the information for the matrix
	keyStringRow	Key string for the row
	keyStringCol	Key string for the column entries
	returnValues	Return Matrix.
	convert	If this is true, and if the node has a units attribute, then conversion to si units is carried out. Default is true.
	matrixSymmetric	If true entries are made so that the matrix is always symmetric. Default is false.

Referenced by DebyeHuckel::initThermoXML().

bool getOptionalFloat	(	const Cantera::XML_Node &	parent,
		const std::string &	name,
		doublereal &	fltRtn,
		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 snipet:

   const XML_Node &State_XMLNode;
   doublereal pres = OneAtm;
   bool exists = getOptionalFloat(State_XMLNode, "pressure", pres, "toSI");
   

reads the corresponding XML file:

   <state>
     <pressure units="Pa"> 101325.0 </pressure>
   <\state>
   

Parameters:

	parent	reference to the XML_Node object of the parent XML element
	name	Name of the XML child element
	fltRtn	Float Return. It will be overridden if the XML element exists.
	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.

Returns:

returns true if the child element named "name" exists

Referenced by HMWSoln::initThermoXML(), HMWSoln::readXMLCroppingCoefficients(), and SurfPhase::setStateFromXML().

bool getOptionalModel	(	const Cantera::XML_Node &	parent,
		const std::string	nodeName,
		std::string &	modelName
	)

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 snipet:

   std::string modelName = "";
   bool exists = getOptionalModel(transportNode, "compositionDependence",
			          modelName);
   

reads the corresponding XML file:

    <transport model="Simple">
      <compositionDependence model="Solvent_Only"/>
    </transport>
   

On return modelName is set to "Solvent_Only".

Parameters:

	parent	reference to the XML_Node object of the parent XML element
	nodeName	Name of the XML child element
	modelName	On return this contains the contents of the model attribute

Returns:

True if the nodeName XML node exists. False otherwise

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 "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:

       <xmlNode> 
          red:112    blue:34
          green:banana
       </xmlNode> 
              

Returns: key val 0: "red" "112" 1: "blue" "34" 2: "green" "banana"

Parameters:

	node	XML Node
	key	Vector of keys for each entry
	val	Vector of values for each entry

Returns:

Returns the number of pairs found

void getString	(	const Cantera::XML_Node &	node,
		const std::string &	titleString,
		std::string &	valueString,
		std::string &	typeString
	)

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 snipet:

   const XML_Node &node;
   getString(XML_Node& node, std::string titleString, std::string valueString, 
   std::string typeString);
   

Reads the following the snippet in the XML file:

   <string title="titleString" type="typeString">
     valueString
   <\string>
   

Parameters:

	node	reference to the XML_Node object of the parent XML element
	titleString	String name of the title attribute of the child node
	valueString	Value string that is found in the child node. output variable
	typeString	String type. This is an optional output variable

void getStringArray	(	const Cantera::XML_Node &	node,
		std::vector< std::string > &	v
	)

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

Parameters:

	node	Node to get the value from
	v	Output vector containing the string tokens

Referenced by Elements::addElementsFromXML(), HMWSoln::constructPhaseXML(), DebyeHuckel::constructPhaseXML(), IdealMolalSoln::initThermoXML(), HMWSoln::initThermoXML(), and DebyeHuckel::initThermoXML().

---

Variable Documentation

const std::string CTML_Version = "1.4.1"

const Specifying the CTML version number

Todo:

Codify what the CTML_Version number means.

Definition at line 31 of file ctml.h.