Cantera 2.6.0

Classes | Functions
Input File Handling

## Classes
class | Unit
| Unit conversion utility. More...
class | UnitSystem
| Unit conversion utility. More...

## Functions
void | addDataDirectory (const std::string &dir)
| Add a directory to the data file search path. More...
std::string | findInputFile (const std::string &name)
| Find an input file. More...
std::string | getDataDirectories (const std::string &sep)
| Get the Cantera data directories. More...
void | setDefaultDirectories ()
| Set the default directories for input files. More...
void | ct2ctml (const char *file, const int debug=0)
| Convert a cti file into a ctml file. More...
std::string | ct2ctml_string (const std::string &file)
| Get a string with the ctml representation of a cti file. More...
std::string | ct_string2ctml_string (const std::string &cti)
| Get a string with the ctml representation of a cti input string. More...
std::string | findInputFile (const std::string &name)
| Find an input file. More...
void | addDirectory (const std::string &dir)
| Add a directory to the data file search path. More...
std::string | getDataDirectories (const std::string &sep)
| Get the Cantera data directories. More...
string | canteraRoot ()
| Returns root directory where Cantera is installed. More...
bool | buildSolutionFromXML (XML_Node &root, const std::string &id, const std::string &nm, ThermoPhase *th, Kinetics *kin)
| Build a single-phase ThermoPhase object with associated kinetics mechanism. More...
ThermoPhase * | newPhase (XML_Node &phase)
| Create a new ThermoPhase object and initializes it according to the XML tree. More...

## Detailed Description

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, the registry is checked to find the Cantera installation directory, and the 'data' subdirectory of the installation directory will be added to the search path.

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 or a list of directory names separated with the OS-dependent path separator (that is, ";" on Windows, ":" elsewhere), then these directories will be 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 currently three different types of input files within Cantera. The YAML format is new in Cantera 2.5, and replaces both the CTI and CTML (XML) formats, which are deprecated and will be removed in Cantera 3.0. The scripts `cti2yaml.py` and `ctml2yaml.py` can be used to convert legacy input files to the YAML format.

- YAML: A human-readable input file written using YAML syntax which defines species, phases, and reactions, and contains thermodynamic, chemical kinetic, and transport data needed by Cantera.
- CTI: A human-readable input file written using Python syntax. Some options for non-ideal equations of state available in the CTML format have not been implemented for the CTI format.
- CTML: This is an XML file laid out in such a way that Cantera can interpret the contents directly. Given a file in CTI format, Cantera will convert the CTI file into the CTML format on-the-fly using a Python script (ctml_writer). This process is done in-memory without writing any new files to disk. Explicit use of the CTML format is not recommended.

Cantera provides converters (`ck2yaml` and `ckcti`) for converting Chemkin-format mechanisms to the YAML and CTI formats, respectively.

Other input routines in other modules:

See also
  importKinetics()

## Function Documentation

## ◆ addDataDirectory()

void addDataDirectory | ( | const std::string & | dir | ) |

Add a directory to the data file search path.

Parameters

  dir | String name for the directory to be added to the search path

Definition at line 397 of file application.cpp.

References Cantera::dir_mutex, Application::inputDirs, Cantera::npos, Application::setDefaultDirectories(), and Cantera::stripnonprint().

Referenced by Cantera::addDirectory().

## ◆ findInputFile() [1/2]

std::string findInputFile | ( | const std::string & | name | ) |

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 first directory searched is usually the current working directory.

The default set of directories will not be searched if an absolute path (for example, one starting with `/` or `C:\`) or a path relative to the user's home directory (for example, starting with `~/`) is specified.

The presence of the file is determined by whether the file can be opened for reading by the current user.

Parameters

  name | Name of the input file to be searched for

Returns
  The absolute path name of the first matching file

If the file is not found a CanteraError exception is thrown.

Definition at line 426 of file application.cpp.

References Cantera::dir_mutex, Application::inputDirs, and Cantera::npos.

Referenced by Cantera::findInputFile(), and Application::get_XML_File().

## ◆ getDataDirectories() [1/2]

std::string getDataDirectories | ( | const std::string & | sep | ) |
| inline

Get the Cantera data directories.

This routine returns a string including the names of all the directories searched by Cantera for data files.

Parameters

  sep | Separator to use between directories in the string

Returns
  A string of directories separated by the input sep

Definition at line 287 of file application.h.

References Application::inputDirs.

Referenced by Cantera::getDataDirectories().

## ◆ setDefaultDirectories()

void setDefaultDirectories | ( |  | ) |
| protected

Set the default directories for input files.

Cantera searches for input files along a path that includes platform- specific default locations, and possibly user-specified locations. This function installs the platform-specific directories on the search path. It is invoked at startup by appinit(), and never should need to be called by user programs.

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.

Definition at line 333 of file application.cpp.

References Application::inputDirs.

Referenced by Application::addDataDirectory(), and Application::Application().

## ◆ ct2ctml()

void ct2ctml | ( | const char * | file,
|  | const int | debug = `0`
| ) |  |

Convert a cti file into a ctml file.

Parameters

  file | Pointer to the file
  debug | Turn on debug printing

Deprecated:
  The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 58 of file ct2ctml.cpp.

References Cantera::ct2ctml_string(), and Cantera::npos.

## ◆ ct2ctml_string()

std::string ct2ctml_string | ( | const std::string & | file | ) |

Get a string with the ctml representation of a cti file.

Parameters

  file | Path to the input file in CTI format

Returns
  String containing the XML representation of the input file

Deprecated:
  The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 175 of file ct2ctml.cpp.

Referenced by Cantera::ct2ctml().

## ◆ ct_string2ctml_string()

std::string ct_string2ctml_string | ( | const std::string & | cti | ) |

Get a string with the ctml representation of a cti input string.

Parameters

  cti | String containing the cti representation

Returns
  String containing the XML representation of the input

Deprecated:
  The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 180 of file ct2ctml.cpp.

Referenced by Application::get_XML_from_string().

## ◆ findInputFile() [2/2]

std::string findInputFile | ( | const std::string & | name | ) |

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 first directory searched is usually the current working directory.

The default set of directories will not be searched if an absolute path (for example, one starting with `/` or `C:\`) or a path relative to the user's home directory (for example, starting with `~/`) is specified.

The presence of the file is determined by whether the file can be opened for reading by the current user.

Parameters

  name | Name of the input file to be searched for

Returns
  The absolute path name of the first matching file

If the file is not found a CanteraError exception is thrown.

Definition at line 165 of file global.cpp.

References Cantera::app(), and Application::findInputFile().

Referenced by AnyMap::clearCachedFile(), AnyMap::fromYamlFile(), and Cantera::get_XML_Node().

## ◆ addDirectory()

void addDirectory | ( | const std::string & | dir | ) |

Add a directory to the data file search path.

Parameters

  dir | String name for the directory to be added to the search path

Definition at line 155 of file global.cpp.

References Application::addDataDirectory(), and Cantera::app().

## ◆ getDataDirectories() [2/2]

std::string getDataDirectories | ( | const std::string & | sep | ) |

Get the Cantera data directories.

This routine returns a string including the names of all the directories searched by Cantera for data files.

Parameters

  sep | Separator to use between directories in the string

Returns
  A string of directories separated by the input sep

Definition at line 160 of file global.cpp.

References Cantera::app(), and Application::getDataDirectories().

## ◆ canteraRoot()

std::string canteraRoot | ( |  | ) |

Returns root directory where Cantera is installed.

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.

Deprecated:
  Unused within Cantera. To be removed after Cantera 2.6

Definition at line 190 of file global.cpp.

References Cantera::warn_deprecated().

## ◆ buildSolutionFromXML()

bool buildSolutionFromXML | ( | XML_Node & | root,
|  | const std::string & | id,
|  | const std::string & | nm,
|  | ThermoPhase * | th,
|  | Kinetics * | kin
| ) |  |

Build a single-phase ThermoPhase object with associated kinetics mechanism.

In a single call, this routine initializes a ThermoPhase object and a homogeneous kinetics object for a phase. It returns the fully initialized ThermoPhase object pointer and kinetics pointer.

Parameters

  root | pointer to the XML tree which will be searched to find the XML phase element.
  id | Name of the phase to be searched for.
  nm | Name of the XML element. Should be "phase"
  th | Pointer to a bare ThermoPhase object, which will be initialized by this operation.
  kin | Pointer to a bare Kinetics object, which will be initialized by this operation to a homogeneous kinetics manager

Returns
  Returns true if all went well. If there are errors, it will return false.

For Example

ThermoPhase *th = new ThermoPhase();
Kinetics *kin = new Kinetics();
XML_Node *root = get_XML_File("gri30.xml");
ok = buildSolutionFromXML(root, "gri30_mix", "phase", th, kin)
Cantera::Kinetics
Public interface for kinetics managers.
Definition: Kinetics.h:114
Cantera::ThermoPhase
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:102
Cantera::XML_Node
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:103
Cantera::buildSolutionFromXML
bool buildSolutionFromXML(XML_Node &root, const std::string &id, const std::string &nm, ThermoPhase *th, Kinetics *kin)
Build a single-phase ThermoPhase object with associated kinetics mechanism.
Definition: importKinetics.cpp:197
Cantera::get_XML_File
XML_Node * get_XML_File(const std::string &file, int debug)
Return a pointer to the XML tree for a Cantera input file.
Definition: global.cpp:140

Deprecated:
  The XML input format is deprecated and will be removed in Cantera 3.0.

See also
  importKinetics()

Definition at line 197 of file importKinetics.cpp.

References Cantera::get_XML_NameID(), Cantera::importKinetics(), and Cantera::importPhase().

## ◆ newPhase()

ThermoPhase * newPhase | ( | XML_Node & | phase | ) |

Create a new ThermoPhase object and initializes it according to the XML tree.

This routine first looks up the identity of the model for the solution thermodynamics in the model attribute of the thermo child of the XML phase node. Then, it does a string lookup using Cantera's internal ThermoPhase Factory routines on the model to figure out what ThermoPhase derived class should be assigned. It creates a new instance of that class, and then calls importPhase() to populate that class with the correct parameters from the XML tree.

Parameters

  phase | XML_Node reference pointing to the phase XML element.

Returns
  A pointer to the completed and initialized ThermoPhase object.

Deprecated:
  The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 114 of file ThermoFactory.cpp.

References XML_Node::child(), Cantera::importPhase(), and Cantera::newThermoPhase().

Referenced by IonsFromNeutralVPSSTP::initThermo(), LatticeSolidPhase::initThermo(), Cantera::newPhase(), Cantera::newSolution(), LatticeSolidPhase::setParametersFromXML(), and IonsFromNeutralVPSSTP::setParametersFromXML().