Handling Errors in Input Files

During processing of an input file, errors may be encountered. These could be syntax errors, or could be ones that are flagged as errors by Cantera due to some apparent inconsistency in the data—an unphysical value, a species that contains an undeclared element, a reaction that contains an undeclared species, missing species or element definitions, multiple definitions of elements, species, or reactions, and so on. This section is intended to help you understand some causes for these errors and their solutions.

Syntax Errors

Syntax errors are caught by the YAML parser, and must be corrected before proceeding further. If a syntax error is encountered, Cantera will raise an exception which includes the location of the error. Additional information such as a traceback showing where in the code the input file was being read may be printed as well.

For example, consider the following input file, which is intended to create a gas with the species and reactions of GRI-Mech 3.0, but is missing the colon which is needed after the thermo key:

phases:
- name: gas
  thermo ideal-gas
  kinetics: gas
  elements: [H, O]
  species: [{gri30.yaml/species: all}]
  reactions: [gri30.yaml/reactions]

When this definition is imported into an application, an error message like the following would be printed to the screen, and execution of the program or script would terminate:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__
    self._init_yaml(infile, phaseid, phases, yaml)
  File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml
    root = AnyMapFromYamlFile(stringify(infile))
cantera._cantera.CanteraError:
***********************************************************************
InputFileError thrown by AnyMap::fromYamlFile:
Error on line 4 of ./gas.yaml:
illegal map value
|  Line |
|     1 | phases:
|     2 | - name: gas
|     3 |   thermo ideal-gas
>     4 >   kinetics: gas
                    ^
|     5 |   elements: [H, O]
|     6 |   species: [{gri30.yaml/species: all}]
|     7 |   reactions: [gri30.yaml/reactions]
***********************************************************************

The top part of the error message shows the chain of functions that were called before the error was encountered. For the most part, these are internal Cantera functions not of direct concern here. The relevant part of this error message is the part between the lines of asterisks. This message says that the YAML parser ran into a problem on line 4 of gas.yaml. In many cases, including this one, the parser will fail somewhere after the actual problem with the input file, since it must continue parsing until it finds something that cannot possibly be valid YAML syntax. In this case, the problem from the parser’s perspective is that the key which started on line 3 continues across a new line before it finds a colon that can be considered as the separator. Since a key can’t be broken across lines like this, the parser indicates the error at the point where it found the colon. By looking back from the indicated point of the error, we can see that the problem is the missing colon in the previous line.

Cantera Errors

Now let’s consider the other class of errors, ones that Cantera itself detects. Continuing the example above, suppose that the missing colon is corrected, and the input file processed again. Again an error message results, but this time it is from Cantera:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__
    self._init_yaml(infile, phaseid, phases, yaml)
  File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml
    root = AnyMapFromYamlFile(stringify(infile))
cantera._cantera.CanteraError:
***********************************************************************
CanteraError thrown by Phase::addSpecies:
Species 'C' contains an undefined element 'C'.
***********************************************************************

The problem is that the phase definition specifies that all species are to be imported from the gri30 mechanism, but only the elements H and O are declared. The gri30 mechanism contains species composed of the elements H, O, C, N, and Ar. If the definition is modified to declare these additional elements:

phases:
- name: gas
  thermo: ideal-gas
  kinetics: gas
  elements: [H, O, C, N, Ar]
  species: [{gri30.yaml/species: all}]
  reactions: [gri30.yaml/reactions]

it may be imported successfully.