Cantera  2.5.1
Modules | Classes | Functions
Input File Handling
Collaboration diagram for Input File Handling:

Modules

 Diagnostic Output
 
 Writing messages to the screen
 

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...
 
void appdelete ()
 Delete and free all memory associated with the application. More...
 
void thread_complete ()
 Delete and free memory allocated per thread in multithreaded applications. More...
 
std::string gitCommit ()
 Returns the hash of the git commit from which Cantera was compiled, if known. More...
 
string canteraRoot ()
 Returns root directory where Cantera is installed. More...
 
void writelog_direct (const std::string &msg)
 Write a message to the screen. More...
 
void debuglog (const std::string &msg, int loglevel)
 Write a message to the log only if loglevel > 0. More...
 
void writelogendl ()
 Write an end of line character to the screen and flush output. More...
 
void writeline (char repeat, size_t count, bool endl_after, bool endl_before)
 
void warn_deprecated (const std::string &method, const std::string &extra="")
 Print a warning indicating that method is deprecated. More...
 
void suppress_deprecation_warnings ()
 Globally disable printing of deprecation warnings. More...
 
void _warn_user (const std::string &method, const std::string &extra)
 helper function passing user warning to global handler More...
 
template<typename... Args>
void warn_user (const std::string &method, const std::string &msg, const Args &... args)
 
void make_deprecation_warnings_fatal ()
 Turns deprecation warnings into exceptions. More...
 
void suppress_thermo_warnings (bool suppress=true)
 Globally disable printing of warnings about problematic thermo data, e.g. More...
 
bool thermo_warnings_suppressed ()
 Returns true if thermo warnings should be suppressed. More...
 
void setLogger (Logger *logwriter)
 Install a logger. More...
 
doublereal toSI (const std::string &unit)
 Return the conversion factor to convert unit std::string 'unit' to SI units. More...
 
doublereal actEnergyToSI (const std::string &unit)
 Return the conversion factor to convert activation energy unit std::string 'unit' to Kelvin. More...
 
XML_Nodeget_XML_File (const std::string &file, int debug=0)
 Return a pointer to the XML tree for a Cantera input file. More...
 
XML_Nodeget_XML_from_string (const std::string &text)
 Read a CTI or CTML string and fill up an XML tree. More...
 
void close_XML_File (const std::string &file)
 Close an XML File. More...
 
XML_Nodeget_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. More...
 
XML_Nodeget_XML_NameID (const std::string &nameTarget, 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. More...
 
template<class T >
clip (const T &value, const T &lower, const T &upper)
 Clip value such that lower <= value <= upper. More...
 
template<typename T >
int sign (T x)
 Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0. 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...
 
ThermoPhasenewPhase (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 (i.e. ";" 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.

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
dirString name for the directory to be added to the search path

Definition at line 381 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
nameName 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 410 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
sepSeparator to use between directories in the string
Returns
A string of directories separated by the input sep

Definition at line 279 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 317 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
filePointer to the file
debugTurn on debug printing
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 56 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
filePath 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 173 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
ctiString 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 178 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
nameName 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 135 of file global.cpp.

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

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

◆ addDirectory()

void addDirectory ( const std::string &  dir)

Add a directory to the data file search path.

Parameters
dirString name for the directory to be added to the search path

Definition at line 125 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
sepSeparator to use between directories in the string
Returns
A string of directories separated by the input sep

Definition at line 130 of file global.cpp.

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

◆ appdelete()

void appdelete ( )

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.

Definition at line 89 of file global.cpp.

◆ thread_complete()

void thread_complete ( )

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.

Definition at line 96 of file global.cpp.

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

◆ gitCommit()

std::string gitCommit ( )

Returns the hash of the git commit from which Cantera was compiled, if known.

Definition at line 101 of file global.cpp.

◆ 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.

Definition at line 160 of file global.cpp.

◆ writelog_direct()

void writelog_direct ( 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. 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.

Parameters
msgc++ string to be written to the screen

Definition at line 33 of file global.cpp.

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

Referenced by Cantera::debuglog(), Cantera::writelog(), and Cantera::writelogf().

◆ debuglog()

void Cantera::debuglog ( const std::string &  msg,
int  loglevel 
)
inline

◆ writelogendl()

void writelogendl ( )

Write an end of line character to the screen and flush output.

Definition at line 38 of file global.cpp.

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

Referenced by FuncEval::eval_nothrow(), VCS_SOLVE::vcs_basopt(), VCS_SOLVE::vcs_dfe(), and VCS_SOLVE::vcs_inest().

◆ warn_deprecated()

void warn_deprecated ( const std::string &  method,
const std::string &  extra = "" 
)

Print a warning indicating that method is deprecated.

Additional information (removal version, alternatives) can be specified in extra. Deprecation warnings are printed once per method per invocation of the application.

Definition at line 54 of file global.cpp.

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

Referenced by Cantera::absmax(), Factory< T, Args >::canonicalize(), StFlow::componentIndex(), ConstDensityThermo::ConstDensityThermo(), Cantera::divide_each(), FixedChemPotSSTP::FixedChemPotSSTP(), AnyMap::fromYamlFile(), WallBase::getArea(), Falloff::getType(), Troe::getType(), SRI::getType(), Phase::id(), Cantera::importInterface(), Interface::Interface(), FlowDevice::massFlowRate(), Cantera::multiply_each(), TransportFactory::newTransport(), Cantera::normalize(), IdealSolidSolnPhase::potentialEnergy(), Cantera::scatter_copy(), Cantera::scatter_mult(), DebyeHuckel::setDensity(), HMWSoln::setDensity(), IdealMolalSoln::setDensity(), IdealSolidSolnPhase::setDensity(), MaskellSolidSolnPhase::setDensity(), StFlow::setFixedPoint(), FlowDevice::setFunction(), IdealSolnGasVPSS::setGasMode(), Phase::setID(), Integrator::setIterator(), FlowDevice::setMassFlowRate(), DebyeHuckel::setMolarDensity(), HMWSoln::setMolarDensity(), IdealMolalSoln::setMolarDensity(), IdealSolidSolnPhase::setMolarDensity(), MaskellSolidSolnPhase::setMolarDensity(), FlowDevice::setParameters(), IdealSolidSolnPhase::setPotentialEnergy(), Valve::setPressureCoeff(), PDSS_SSVol::setState_TR(), Cantera::setupPhase(), Phase::speciesIndex(), Cantera::sum_each(), Cantera::sum_xlogQ(), Cantera::sum_xlogx(), TransportDBError::TransportDBError(), Arrhenius::type(), SurfaceArrhenius::type(), Plog::type(), ChebyshevRate::type(), ConstPressureReactor::type(), FlowDevice::type(), FlowReactor::type(), IdealGasConstPressureReactor::type(), IdealGasReactor::type(), Reactor::type(), and ReactorBase::type().

◆ suppress_deprecation_warnings()

void suppress_deprecation_warnings ( )

Globally disable printing of deprecation warnings.

Used primarily to prevent certain tests from failing.

Definition at line 64 of file global.cpp.

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

◆ _warn_user()

void _warn_user ( const std::string &  method,
const std::string &  extra 
)

helper function passing user warning to global handler

Definition at line 59 of file global.cpp.

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

Referenced by Cantera::warn_user().

◆ warn_user()

void Cantera::warn_user ( const std::string &  method,
const std::string &  msg,
const Args &...  args 
)

Print a user warning raised from method.

Parameters
methodmethod name
msgPython-style format string with the following arguments
argsarguments for the format string

Definition at line 206 of file global.h.

References Cantera::_warn_user().

Referenced by ChemEquil::equilibrate(), Troe::init(), ChemEquil::initialize(), PDSS_HKFT::initThermo(), Sim1D::restore(), Domain1D::restore(), StFlow::restore(), vcs_VolPhase::setPtrThermoPhase(), and NasaPoly2::validate().

◆ make_deprecation_warnings_fatal()

void make_deprecation_warnings_fatal ( )

Turns deprecation warnings into exceptions.

Activated within the test suite to make sure that no deprecated methods are being used.

Definition at line 69 of file global.cpp.

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

◆ suppress_thermo_warnings()

void suppress_thermo_warnings ( bool  suppress = true)

Globally disable printing of warnings about problematic thermo data, e.g.

NASA polynomials with discontinuities at the midpoint temperature.

Definition at line 74 of file global.cpp.

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

◆ thermo_warnings_suppressed()

bool thermo_warnings_suppressed ( )

Returns true if thermo warnings should be suppressed.

Definition at line 79 of file global.cpp.

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

Referenced by NasaPoly2::validate().

◆ setLogger()

void setLogger ( Logger logwriter)

Install a logger.

Called by the language interfaces to install an appropriate logger. The logger is used for the writelog() function

Parameters
logwriterPointer to a logger object
See also
Logger.

Definition at line 24 of file global.cpp.

References Cantera::app(), Logger::error(), and Application::setLogger().

◆ toSI()

doublereal toSI ( const std::string &  unit)

◆ actEnergyToSI()

doublereal actEnergyToSI ( const std::string &  unit)

Return the conversion factor to convert activation energy unit std::string 'unit' to Kelvin.

Parameters
unitString containing the activation energy units

Definition at line 151 of file global.cpp.

Referenced by Cantera::getFloatArray().

◆ get_XML_File()

XML_Node * get_XML_File ( const std::string &  file,
int  debug = 0 
)

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.

Parameters
fileString containing the relative or absolute file name
debugDebug flag
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 110 of file global.cpp.

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

Referenced by Phase::addElement(), Cantera::get_XML_NameID(), Cantera::get_XML_Node(), RedlichKwongMFTP::getCoeff(), IdealSolnGasVPSS::IdealSolnGasVPSS(), ThermoPhase::initThermoFile(), Cantera::installElements(), Interface::Interface(), Cantera::newKinetics(), and Cantera::newPhase().

◆ get_XML_from_string()

XML_Node * get_XML_from_string ( const std::string &  text)

Read a CTI or CTML string and fill up an XML tree.

Return a pointer to the XML tree corresponding to the specified CTI or XML string. If the given string has been processed before, the cached XML tree will be returned. Otherwise, the XML tree will be generated and stored in the cache.

Parameters
textCTI or CTML string
Returns
Root of the corresponding XML tree
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 115 of file global.cpp.

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

◆ close_XML_File()

void close_XML_File ( const std::string &  file)

Close an XML File.

Close a file that is opened by this application object

Parameters
fileString containing the relative or absolute file name

Definition at line 120 of file global.cpp.

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

◆ get_XML_Node()

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 ID attribute of the XML element only.

Parameters
file_IDThis is a concatenation of two strings separated 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.
rootIf the file string is empty, searches for the XML element with matching ID attribute are carried out from this XML node.
Returns
the XML_Node, if found. Returns null if not found.
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 194 of file global.cpp.

References XML_Node::findID(), Cantera::findInputFile(), Cantera::get_XML_File(), and Cantera::split_at_pound().

Referenced by Cantera::importPhase(), Cantera::installReactionArrays(), Interface::Interface(), and IonsFromNeutralVPSSTP::setParametersFromXML().

◆ get_XML_NameID()

XML_Node * get_XML_NameID ( const std::string &  nameTarget,
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.

Parameters
nameTargetThis is the XML element name to look for.
file_IDThis is a concatenation of two strings separated 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.
rootIf the file string is empty, searches for the XML element with matching ID attribute are carried out from this XML node.
Returns
the XML_Node, if found. Returns null if not found.
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.

Definition at line 232 of file global.cpp.

References XML_Node::findNameID(), Cantera::get_XML_File(), and Cantera::split_at_pound().

Referenced by Cantera::buildSolutionFromXML(), IdealSolnGasVPSS::IdealSolnGasVPSS(), Cantera::newKinetics(), and Cantera::newPhase().

◆ clip()

T Cantera::clip ( const T &  value,
const T &  lower,
const T &  upper 
)
inline

◆ sign()

int Cantera::sign ( x)

Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0.

Definition at line 306 of file global.h.

◆ 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
rootpointer to the XML tree which will be searched to find the XML phase element.
idName of the phase to be searched for.
nmName of the XML element. Should be "phase"
thPointer to a bare ThermoPhase object, which will be initialized by this operation.
kinPointer 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)
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:110
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.
Deprecated:
The XML input format is deprecated and will be removed in Cantera 3.0.
See also
importKinetics()

Definition at line 195 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
phaseXML_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 104 of file ThermoFactory.cpp.

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

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