Tutorials

Using a virtual scheme with Cantera

Virtual chemistry mechanisms are provided as Cantera YAML files. Before loading them, some Cantera installations need one small source-code change: the transport-geometry validation has to be relaxed for virtual species.

Virtual species can have artificial elemental compositions. Because of this, Cantera’s default check for geometry: atom, geometry: linear, or geometry: nonlinear may reject a valid virtual mechanism during YAML loading.

In the Cantera source tree, open this file:

src/transport/TransportData.cpp

Find the function:

void GasTransportData::validate(const Species& sp)

Inside this function, comment out only the block that checks whether geometry matches the number of atoms in the species. In an unmodified Cantera source tree, the block starts like this:

if (geometry == "atom") {
    if (nAtoms > 1) {
        throw CanteraError("GasTransportData::validate",
            "invalid geometry for species '{}'. 'atom' specified, but "
            "species contains multiple atoms.", sp.name);
    }
} else if (geometry == "linear") {
    ...
}

After the change, the whole geometry-validation block should be commented out:

// if (geometry == "atom") {
//     if (nAtoms > 1) {
//         throw CanteraError("GasTransportData::validate",
//             "invalid geometry for species '{}'. 'atom' specified, but "
//             "species contains multiple atoms.", sp.name);
//     }
// } else if (geometry == "linear") {
//     if (nAtoms < 2) {
//         throw CanteraError("GasTransportData::validate",
//             "invalid geometry for species '{}'. 'linear' specified, but "
//             "species does not contain multiple atoms.", sp.name);
//     }
// } else if (geometry == "nonlinear") {
//     if (nAtoms < 3) {
//         throw CanteraError("GasTransportData::validate",
//             "invalid geometry for species '{}'. 'nonlinear' specified, but "
//             "species only contains {} atoms.", sp.name, nAtoms);
//     }
// } else {
//     throw CanteraError("GasTransportData::validate",
//         "invalid geometry for species '{}': '{}'.", sp.name, geometry);
// }

Keep the remaining checks for positive transport values, including well_depth, diameter, dipole, polarizability, and rotational_relaxation. Those checks still protect against malformed transport data.

After changing the file, rebuild or reinstall Cantera. Editing the C++ file does not change the Cantera version that Python imports automatically. Cantera must be compiled again, and Python must import this modified build instead of a previous pip, conda, or system installation.

Then unzip the Cantera archive for the scheme and load the YAML file:

import cantera as ct

gas = ct.Solution("scheme.yaml")
print(gas.n_species, gas.n_reactions)

Open the YAML file to find the exact virtual fuel, oxidizer, product, and intermediate names used by the scheme. Use those names when setting the gas state:

gas.TPX = 300.0, ct.one_atm, "F:0.5, Ox:0.5"

The species names above are examples. Replace them with the names defined in the YAML file. Once the mechanism loads and the state is set, it can be used in standard Cantera workflows such as reactors, free flames, and flamelet calculations.

Using a scheme with CHEMKIN-format solvers

The CHEMKIN archive contains the standard file set — kinetics (chem.inp), thermodynamics (therm.dat), and transport (tran.dat) — accepted by CHEMKIN-II-compatible interpreters and by most in-house combustion codes. Point your solver’s mechanism interpreter at these files as you would for any conventional mechanism.

Because the species are virtual, make sure your case setup uses the species names from the scheme files (not real-chemistry names), and set the inlet composition as documented on the scheme’s page.

Coupling to CFD codes

Guides for coupling virtual schemes to specific CFD solvers (LES codes with finite-rate chemistry) are in preparation. In the meantime, the reference publications on each scheme page describe the couplings used for the published validation cases — and if your solver isn’t covered, contact us with your use case.

Something missing?

These tutorials grow with the platform. If a step is unclear or your workflow isn’t covered, reach out — questions tell us what to document next.