python_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Cantera Tutorial: Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Open a new Jupyter Notebook. If unfamiliar with Jupyter Notebooks see the [Jupyter Documentation](https://jupyter.readthedocs.io/en/latest/install.html) for installation and basic use instructions. Import the Cantera Python module and NumPy by running:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using Cantera version: 2.6.0a4\n"
     ]
    }
   ],
   "source": [
    "import cantera as ct\n",
    "import numpy as np\n",
    "\n",
    "print(f\"Using Cantera version: {ct.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When using Cantera, the first thing you usually need is an object representing some phase of matter. Here, we'll create a gas mixture:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1 = ct.Solution(\"gri30.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To view the state of the mixture, *call* the `gas1` object as if it were a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "  gri30:\n",
      "\n",
      "       temperature   300 K\n",
      "          pressure   1.0133e+05 Pa\n",
      "           density   0.081894 kg/m^3\n",
      "  mean mol. weight   2.016 kg/kmol\n",
      "   phase of matter   gas\n",
      "\n",
      "                          1 kg             1 kmol     \n",
      "                     ---------------   ---------------\n",
      "          enthalpy             26469             53361  J\n",
      "   internal energy       -1.2108e+06        -2.441e+06  J\n",
      "           entropy             64910        1.3086e+05  J/K\n",
      "    Gibbs function       -1.9447e+07       -3.9204e+07  J\n",
      " heat capacity c_p             14311             28851  J/K\n",
      " heat capacity c_v             10187             20536  J/K\n",
      "\n",
      "                      mass frac. Y      mole frac. X     chem. pot. / RT\n",
      "                     ---------------   ---------------   ---------------\n",
      "                H2                 1                 1           -15.717\n",
      "     [  +52 minor]                 0                 0  \n",
      "\n"
     ]
    }
   ],
   "source": [
    "gas1()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What you have just done is created an object `gas1` that implements GRI-Mech 3.0, the 53-species, 325-reaction natural gas combustion mechanism developed by Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel W. Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald K. Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, and Zhiwei Qin.  See the [GRI-Mech Home Page](http://combustion.berkeley.edu/gri-mech/) for more information.\n",
    "\n",
    "The `gas1` object has properties you would expect for a gas mixture: a temperature, a pressure, species mole and mass fractions, etc. As we will soon see, it has many more properties.\n",
    "\n",
    "The summary of the state of `gas1` that you found above shows that the new objects created from the `gri30.yaml` input file start out with a temperature of 300 K, a pressure of 1 atm, and have a composition that consists of only one species, in this case hydrogen. There is nothing special about H2 - it just happens to be the first species listed in the input file defining GRI-Mech 3.0. In general, whichever species is listed first will initially have a mole fraction of 1.0, and all others will be zero."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting the State"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The state of the object can easily be changed. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.TP = 1200, 101325"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "sets the temperature to 1200 K and the pressure to 101325 Pa (Cantera always uses SI Units). After this statement, calling `gas1()` results in:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "  gri30:\n",
      "\n",
      "       temperature   1200 K\n",
      "          pressure   1.0133e+05 Pa\n",
      "           density   0.020473 kg/m^3\n",
      "  mean mol. weight   2.016 kg/kmol\n",
      "   phase of matter   gas\n",
      "\n",
      "                          1 kg             1 kmol     \n",
      "                     ---------------   ---------------\n",
      "          enthalpy        1.3295e+07        2.6802e+07  J\n",
      "   internal energy        8.3457e+06        1.6825e+07  J\n",
      "           entropy             85222        1.7181e+05  J/K\n",
      "    Gibbs function       -8.8972e+07       -1.7937e+08  J\n",
      " heat capacity c_p             15377             31000  J/K\n",
      " heat capacity c_v             11253             22686  J/K\n",
      "\n",
      "                      mass frac. Y      mole frac. X     chem. pot. / RT\n",
      "                     ---------------   ---------------   ---------------\n",
      "                H2                 1                 1           -17.978\n",
      "     [  +52 minor]                 0                 0  \n",
      "\n"
     ]
    }
   ],
   "source": [
    "gas1()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the temperature has been changed as requested, but the density has changed too. The pressure and the composition have not.\n",
    "\n",
    "Thermodynamics generally requires that *two* properties in addition to composition information be specified to fix the intensive state of a substance (or mixture). The state of the mixture can be set using several combinations of two properties. The following are all equivalent:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.TP = 1200, 101325  # temperature, pressure\n",
    "gas1.TD = 1200, 0.0204723  # temperature, density\n",
    "gas1.HP = 1.32956e7, 101325  # specific enthalpy, pressure\n",
    "gas1.UV = 8.34619e6, 1 / 0.0204723  # specific internal energy, specific volume\n",
    "gas1.SP = 85227.6, 101325  # specific entropy, pressure\n",
    "gas1.SV = 85227.6, 1 / 0.0204723  # specific entropy, specific volume"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In each case, the values of the extensive properties must be entered *per unit mass*.\n",
    "\n",
    "Properties may be read independently, such as"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1200.5188172713504"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gas1.T"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "13302755.250164837"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gas1.h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or together:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(8351530.632807602, 48.84649013545132)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gas1.UV"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The composition can be set in terms of either mole fractions (`X`) or mass fractions (`Y`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.X = \"CH4:1, O2:2, N2:7.52\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mass and mole fractions can also be set using the `dict` object, for cases where the composition is stored in a variable or being computed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "phi = 0.8\n",
    "gas1.X = {\"CH4\": 1, \"O2\": 2 / phi, \"N2\": 2 * 3.76 / phi}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the composition alone is changed, the temperature and density are held constant. This means that the pressure and other intensive properties will change. The composition can also be set in conjunction with the intensive properties of the mixture:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "  gri30:\n",
      "\n",
      "       temperature   1200 K\n",
      "          pressure   1.0133e+05 Pa\n",
      "           density   0.28063 kg/m^3\n",
      "  mean mol. weight   27.633 kg/kmol\n",
      "   phase of matter   gas\n",
      "\n",
      "                          1 kg             1 kmol     \n",
      "                     ---------------   ---------------\n",
      "          enthalpy        8.6193e+05        2.3818e+07  J\n",
      "   internal energy        5.0087e+05        1.3841e+07  J\n",
      "           entropy            8914.2        2.4633e+05  J/K\n",
      "    Gibbs function       -9.8351e+06       -2.7178e+08  J\n",
      " heat capacity c_p            1397.3             38611  J/K\n",
      " heat capacity c_v            1096.4             30296  J/K\n",
      "\n",
      "                      mass frac. Y      mole frac. X     chem. pot. / RT\n",
      "                     ---------------   ---------------   ---------------\n",
      "                O2           0.22014           0.19011           -28.747\n",
      "               CH4          0.055187          0.095057           -35.961\n",
      "                N2           0.72467           0.71483           -25.679\n",
      "     [  +50 minor]                 0                 0  \n",
      "\n"
     ]
    }
   ],
   "source": [
    "gas1.TPX = 1200, 101325, \"CH4:1, O2:2, N2:7.52\"\n",
    "gas1()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The composition above was specified using a string. The format is a comma-separated list of `<species name>:<relative mole numbers>` pairs. The mole numbers will be normalized to produce the mole fractions, and therefore they are \"relative\" mole numbers. Mass fractions can be set this way too by changing `X` to `Y` in the above statements.\n",
    "\n",
    "The composition can also be set using an array, which must have the same size as the number of species. For example, to set all 53 mole fractions to the same value, do this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.X = np.ones(53)  # NumPy array of 53 ones"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, to set all the mass fractions to equal values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.Y = np.ones(53)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When setting the state, you can control what properties are held constant by passing the special value `None` to the property setter. For example, to change the specific volume to 2.1 m<sup>3</sup>/kg while holding entropy constant:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.SV = None, 2.1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or to set the mass fractions while holding temperature and pressure constant:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas1.TPX = None, None, \"CH4:1.0, O2:0.5\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with a Subset of Species"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many properties of a [`Solution`](https://cantera.org/documentation/dev/sphinx/html/cython/importing.html#cantera.Solution) provide values for each species present in the phase. If you want to get values only for a subset of these species, you can use Python's \"slicing\" syntax to select data for just the species of interest. To get the mole fractions of just the major species in `gas1`, in the order specified, you can write:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "Xmajor = gas1[\"CH4\", \"O2\", \"CO2\", \"H2O\", \"N2\"].X"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to use the same set of species repeatedly, you can keep a reference to the sliced phase object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "major = gas1[\"CH4\", \"O2\", \"CO2\", \"H2O\", \"N2\"]\n",
    "cp_major = major.partial_molar_cp\n",
    "wdot_major = major.net_production_rates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The slice object and the original object share the same internal state, so modifications to one will affect the other."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with Mechanism Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the previous example, we created an object that models an ideal gas mixture with the species and reactions of GRI-Mech 3.0, using the `gri30.yaml` input file included with Cantera. Several reaction mechanism files in this format are included with Cantera, including ones that model high-temperature air, a hydrogen/oxygen reaction mechanism, and a few surface reaction mechanisms. These files are usually located in the `data` subdirectory of the Cantera installation directory, e.g. `C:\\\\Program Files\\\\Cantera\\\\data` on Windows or `/usr/local/cantera/data/` on Unix/Linux/Mac OS X machines, depending on how you installed Cantera and the options you specified.\n",
    "\n",
    "If, for some reason, Cantera has difficulty finding where these files are on your system, set environment variable `CANTERA_DATA` to the directory or directories (separated using `;` on Windows or `:` on other operating systems) where they are located. Alternatively, you can call function [`add_directory`](https://cantera.org/documentation/dev/sphinx/html/cython/importing.html#cantera.add_directory) to add a directory to the Cantera search path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "ct.add_directory(\"/usr/local/cantera/my_data_files\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cantera input files are plain text files, and can be created with any text editor. See the guide *[Defining Phases](https://cantera.org/tutorials/yaml/defining-phases.html)* for more information.\n",
    "\n",
    "A Cantera input file may contain more than one phase specification, or may contain specifications of interfaces (surfaces). Here, we import definitions of two bulk phases and the interface between them from the file `diamond.yaml`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas2 = ct.Solution(\"diamond.yaml\", \"gas\")\n",
    "diamond = ct.Solution(\"diamond.yaml\", \"diamond\")\n",
    "diamond_surf = ct.Interface(\"diamond.yaml\", \"diamond_100\", [gas2, diamond])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the bulk (i.e., 3D or homogenous) phases that participate in the surface reactions must also be passed as arguments to [`Interface`](https://cantera.org/documentation/dev/sphinx/html/cython/importing.html#cantera.Interface)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Converting CK-format files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See *[Converting CK-format files](https://cantera.org/tutorials/ck2yaml-tutorial.html)* in the *[Working with Input Files](https://cantera.org/tutorials/input-files.html)* documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to the *[Python Module Documentation](https://cantera.org/documentation/index.html)*, documentation of the Python classes and their methods can be accessed from within the Python interpreter as well.\n",
    "\n",
    "Suppose you have created a Cantera object and want to know what methads are avialable for it, and get help on using the methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = ct.Solution(\"gri30.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get help on the Python class that this object is an instance of, put a question mark `?` after the variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[0;31mCall signature:\u001b[0m \u001b[0mg\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m*\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mType:\u001b[0m           Solution\n",
      "\u001b[0;31mString form:\u001b[0m    <cantera.composite.Solution object at 0xffff81f4eac0>\n",
      "\u001b[0;31mFile:\u001b[0m           /opt/conda/lib/python3.9/site-packages/cantera/composite.py\n",
      "\u001b[0;31mDocstring:\u001b[0m     \n",
      "A class for chemically-reacting solutions. Instances can be created to\n",
      "represent any type of solution -- a mixture of gases, a liquid solution, or\n",
      "a solid solution, for example.\n",
      "\n",
      "Class `Solution` derives from classes `ThermoPhase`, `Kinetics`, and\n",
      "`Transport`.  It defines no methods of its own, and is provided so that a\n",
      "single object can be used to compute thermodynamic, kinetic, and transport\n",
      "properties of a solution.\n",
      "\n",
      "To skip initialization of the Transport object, pass the keyword argument\n",
      "``transport_model=None`` to the `Solution` constructor.\n",
      "\n",
      "The most common way to instantiate `Solution` objects is by using a phase\n",
      "definition, species and reactions defined in an input file::\n",
      "\n",
      "    gas = ct.Solution('gri30.yaml')\n",
      "\n",
      "If an input file defines multiple phases, the corresponding key in the\n",
      "*phases* map (in YAML), *name* (in CTI), or *id* (in XML) can be used\n",
      "to specify the desired phase via the ``name`` keyword argument of\n",
      "the constructor::\n",
      "\n",
      "    gas = ct.Solution('diamond.yaml', name='gas')\n",
      "    diamond = ct.Solution('diamond.yaml', name='diamond')\n",
      "\n",
      "The name of the `Solution` object defaults to the *phase* identifier\n",
      "specified in the input file. Upon initialization of a 'Solution' object,\n",
      "a custom name can assigned via::\n",
      "\n",
      "    gas.name = 'my_custom_name'\n",
      "\n",
      "`Solution` objects can also be constructed using `Species` and `Reaction`\n",
      "objects which can themselves either be imported from input files or defined\n",
      "directly in Python::\n",
      "\n",
      "    spec = ct.Species.listFromFile('gri30.yaml')\n",
      "    spec_gas = ct.Solution(thermo='IdealGas', species=spec)\n",
      "    rxns = ct.Reaction.listFromFile('gri30.yaml', spec_gas)\n",
      "    gas = ct.Solution(thermo='IdealGas', kinetics='GasKinetics',\n",
      "                      species=spec, reactions=rxns, name='my_custom_name')\n",
      "\n",
      "where the ``thermo`` and ``kinetics`` keyword arguments are strings\n",
      "specifying the thermodynamic and kinetics model, respectively, and\n",
      "``species`` and ``reactions`` keyword arguments are lists of `Species` and\n",
      "`Reaction` objects, respectively. Note that importing the reactions from a\n",
      "YAML input file requires a `Kinetics` object containing the species, as\n",
      "shown.\n",
      "\n",
      "Types of underlying models that form the composite `Solution` object are\n",
      "queried using the ``thermo_model``, ``kinetics_model`` and\n",
      "``transport_model`` attributes; further, the ``composite`` attribute is a\n",
      "shorthand returning a tuple containing the types of the three constitutive\n",
      "models.\n",
      "\n",
      "For non-trivial uses cases of this functionality, see the examples\n",
      "`extract_submechanism.py <https://cantera.org/examples/python/kinetics/extract_submechanism.py.html>`_\n",
      "and `mechanism_reduction.py <https://cantera.org/examples/python/kinetics/mechanism_reduction.py.html>`_.\n",
      "\n",
      "In addition, `Solution` objects can be constructed by passing the text of\n",
      "the YAML phase definition in directly, using the ``yaml`` keyword\n",
      "argument::\n",
      "\n",
      "    yaml_def = '''\n",
      "    phases:\n",
      "    - name: gas\n",
      "      thermo: ideal-gas\n",
      "      kinetics: gas\n",
      "      elements: [O, H, Ar]\n",
      "      species:\n",
      "      - gri30.yaml/species: all\n",
      "      reactions:\n",
      "      - gri30.yaml/reactions: declared-species\n",
      "      skip-undeclared-elements: true\n",
      "      skip-undeclared-third-bodies: true\n",
      "      state: {T: 300, P: 1 atm}\n",
      "    '''\n",
      "    gas = ct.Solution(yaml=yaml_def)\n"
     ]
    }
   ],
   "source": [
    "?g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For a simple list of the properties and methods of this object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['CK_mode',\n",
       " 'DP',\n",
       " 'DPX',\n",
       " 'DPY',\n",
       " 'HP',\n",
       " 'HPX',\n",
       " 'HPY',\n",
       " 'P',\n",
       " 'P_sat',\n",
       " 'SP',\n",
       " 'SPX',\n",
       " 'SPY',\n",
       " 'SV',\n",
       " 'SVX',\n",
       " 'SVY',\n",
       " 'T',\n",
       " 'TD',\n",
       " 'TDX',\n",
       " 'TDY',\n",
       " 'TP',\n",
       " 'TPX',\n",
       " 'TPY',\n",
       " 'T_sat',\n",
       " 'Te',\n",
       " 'UV',\n",
       " 'UVX',\n",
       " 'UVY',\n",
       " 'X',\n",
       " 'Y',\n",
       " '__call__',\n",
       " '__class__',\n",
       " '__composition_to_array',\n",
       " '__copy__',\n",
       " '__delattr__',\n",
       " '__dir__',\n",
       " '__doc__',\n",
       " '__eq__',\n",
       " '__format__',\n",
       " '__ge__',\n",
       " '__getattribute__',\n",
       " '__getitem__',\n",
       " '__getstate__',\n",
       " '__gt__',\n",
       " '__hash__',\n",
       " '__init__',\n",
       " '__init_subclass__',\n",
       " '__le__',\n",
       " '__lt__',\n",
       " '__module__',\n",
       " '__ne__',\n",
       " '__new__',\n",
       " '__pyx_vtable__',\n",
       " '__reduce__',\n",
       " '__reduce_cython__',\n",
       " '__reduce_ex__',\n",
       " '__repr__',\n",
       " '__setattr__',\n",
       " '__setstate__',\n",
       " '__setstate_cython__',\n",
       " '__sizeof__',\n",
       " '__slots__',\n",
       " '__str__',\n",
       " '__subclasshook__',\n",
       " '_check_kinetics_species_index',\n",
       " '_check_phase_index',\n",
       " '_check_reaction_index',\n",
       " '_cinit',\n",
       " '_full_states',\n",
       " '_init_cti_xml',\n",
       " '_init_parts',\n",
       " '_init_yaml',\n",
       " '_native_state',\n",
       " '_partial_states',\n",
       " '_references',\n",
       " 'activities',\n",
       " 'activity_coefficients',\n",
       " 'add_reaction',\n",
       " 'add_species',\n",
       " 'add_species_alias',\n",
       " 'atomic_weight',\n",
       " 'atomic_weights',\n",
       " 'basis',\n",
       " 'binary_diff_coeffs',\n",
       " 'case_sensitive_species_names',\n",
       " 'charges',\n",
       " 'chemical_potentials',\n",
       " 'clear_user_data',\n",
       " 'clear_user_header',\n",
       " 'composite',\n",
       " 'concentrations',\n",
       " 'cp',\n",
       " 'cp_mass',\n",
       " 'cp_mole',\n",
       " 'creation_rates',\n",
       " 'critical_density',\n",
       " 'critical_pressure',\n",
       " 'critical_temperature',\n",
       " 'cv',\n",
       " 'cv_mass',\n",
       " 'cv_mole',\n",
       " 'delta_enthalpy',\n",
       " 'delta_entropy',\n",
       " 'delta_gibbs',\n",
       " 'delta_standard_enthalpy',\n",
       " 'delta_standard_entropy',\n",
       " 'delta_standard_gibbs',\n",
       " 'density',\n",
       " 'density_mass',\n",
       " 'density_mole',\n",
       " 'destruction_rates',\n",
       " 'electric_potential',\n",
       " 'electrical_conductivity',\n",
       " 'electrochemical_potentials',\n",
       " 'element_index',\n",
       " 'element_name',\n",
       " 'element_names',\n",
       " 'elemental_mass_fraction',\n",
       " 'elemental_mole_fraction',\n",
       " 'enthalpy_mass',\n",
       " 'enthalpy_mole',\n",
       " 'entropy_mass',\n",
       " 'entropy_mole',\n",
       " 'equilibrate',\n",
       " 'equilibrium_constants',\n",
       " 'equivalence_ratio',\n",
       " 'find_isomers',\n",
       " 'forward_rate_constants',\n",
       " 'forward_rates_of_progress',\n",
       " 'g',\n",
       " 'get_binary_diff_coeffs_polynomial',\n",
       " 'get_collision_integral_polynomials',\n",
       " 'get_thermal_conductivity_polynomial',\n",
       " 'get_viscosity_polynomial',\n",
       " 'gibbs_mass',\n",
       " 'gibbs_mole',\n",
       " 'h',\n",
       " 'has_phase_transition',\n",
       " 'heat_production_rates',\n",
       " 'heat_release_rate',\n",
       " 'input_data',\n",
       " 'input_header',\n",
       " 'int_energy_mass',\n",
       " 'int_energy_mole',\n",
       " 'is_compressible',\n",
       " 'is_pure',\n",
       " 'is_reversible',\n",
       " 'isothermal_compressibility',\n",
       " 'kinetics_model',\n",
       " 'kinetics_species_index',\n",
       " 'kinetics_species_name',\n",
       " 'kinetics_species_names',\n",
       " 'mass_fraction_dict',\n",
       " 'max_temp',\n",
       " 'mean_molecular_weight',\n",
       " 'min_temp',\n",
       " 'mix_diff_coeffs',\n",
       " 'mix_diff_coeffs_mass',\n",
       " 'mix_diff_coeffs_mole',\n",
       " 'mixture_fraction',\n",
       " 'mobilities',\n",
       " 'modify_reaction',\n",
       " 'modify_species',\n",
       " 'mole_fraction_dict',\n",
       " 'molecular_weights',\n",
       " 'multi_diff_coeffs',\n",
       " 'multiplier',\n",
       " 'n_atoms',\n",
       " 'n_elements',\n",
       " 'n_phases',\n",
       " 'n_reactions',\n",
       " 'n_selected_species',\n",
       " 'n_species',\n",
       " 'n_total_species',\n",
       " 'name',\n",
       " 'net_production_rates',\n",
       " 'net_rates_of_progress',\n",
       " 'partial_molar_cp',\n",
       " 'partial_molar_enthalpies',\n",
       " 'partial_molar_entropies',\n",
       " 'partial_molar_int_energies',\n",
       " 'partial_molar_volumes',\n",
       " 'phase_of_matter',\n",
       " 'product_stoich_coeff',\n",
       " 'product_stoich_coeffs',\n",
       " 'product_stoich_coeffs3',\n",
       " 'product_stoich_coeffs_reversible',\n",
       " 'products',\n",
       " 'reactant_stoich_coeff',\n",
       " 'reactant_stoich_coeffs',\n",
       " 'reactant_stoich_coeffs3',\n",
       " 'reactants',\n",
       " 'reaction',\n",
       " 'reaction_equation',\n",
       " 'reaction_equations',\n",
       " 'reaction_phase_index',\n",
       " 'reaction_type',\n",
       " 'reaction_type_str',\n",
       " 'reactions',\n",
       " 'reference_pressure',\n",
       " 'report',\n",
       " 'reverse_rate_constants',\n",
       " 'reverse_rates_of_progress',\n",
       " 's',\n",
       " 'selected_species',\n",
       " 'set_binary_diff_coeffs_polynomial',\n",
       " 'set_collision_integral_polynomial',\n",
       " 'set_equivalence_ratio',\n",
       " 'set_mixture_fraction',\n",
       " 'set_multiplier',\n",
       " 'set_thermal_conductivity_polynomial',\n",
       " 'set_unnormalized_mass_fractions',\n",
       " 'set_unnormalized_mole_fractions',\n",
       " 'set_viscosity_polynomial',\n",
       " 'source',\n",
       " 'species',\n",
       " 'species_index',\n",
       " 'species_name',\n",
       " 'species_names',\n",
       " 'species_viscosities',\n",
       " 'standard_concentration_units',\n",
       " 'standard_cp_R',\n",
       " 'standard_enthalpies_RT',\n",
       " 'standard_entropies_R',\n",
       " 'standard_gibbs_RT',\n",
       " 'standard_int_energies_RT',\n",
       " 'state',\n",
       " 'state_size',\n",
       " 'stoich_air_fuel_ratio',\n",
       " 'thermal_conductivity',\n",
       " 'thermal_diff_coeffs',\n",
       " 'thermal_expansion_coeff',\n",
       " 'thermo_model',\n",
       " 'third_body_concentrations',\n",
       " 'transport_model',\n",
       " 'u',\n",
       " 'update_user_data',\n",
       " 'update_user_header',\n",
       " 'v',\n",
       " 'viscosity',\n",
       " 'volume_mass',\n",
       " 'volume_mole',\n",
       " 'write_yaml']"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dir(g)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get help on a specific method, e.g. the `species_index` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[0;31mDocstring:\u001b[0m\n",
      "ThermoPhase.species_index(self, species) -> int\n",
      "\n",
      "The index of species *species*, which may be specified as a string or\n",
      "an integer. In the latter case, the index is checked for validity and\n",
      "returned. If no such species is present, an exception is thrown.\n",
      "\u001b[0;31mType:\u001b[0m      builtin_function_or_method\n"
     ]
    }
   ],
   "source": [
    "?g.species_index"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For properties, getting the documentation is slightly trickier, as the usual method will give you help for the *result*, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[0;31mType:\u001b[0m        float\n",
      "\u001b[0;31mString form:\u001b[0m 300.0\n",
      "\u001b[0;31mDocstring:\u001b[0m   Convert a string or number to a floating point number, if possible.\n"
     ]
    }
   ],
   "source": [
    "?g.T"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "provides help on Python's `float` class. To get the help for the temperature property, ask for the attribute of the class object itself:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[0;31mType:\u001b[0m        getset_descriptor\n",
      "\u001b[0;31mString form:\u001b[0m <attribute 'T' of 'cantera._cantera.ThermoPhase' objects>\n",
      "\u001b[0;31mDocstring:\u001b[0m   Temperature [K].\n"
     ]
    }
   ],
   "source": [
    "?g.__class__.T"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Help can also be obtained using the `help` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function species_index:\n",
      "\n",
      "species_index(...) method of cantera.composite.Solution instance\n",
      "    ThermoPhase.species_index(self, species) -> int\n",
      "    \n",
      "    The index of species *species*, which may be specified as a string or\n",
      "    an integer. In the latter case, the index is checked for validity and\n",
      "    returned. If no such species is present, an exception is thrown.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(g.species_index)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Chemical Equilibrium"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To set a gas mixture to a state of chemical equilibrium, use the `equilibrate` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = ct.Solution(\"gri30.yaml\")\n",
    "g.TPX = 300.0, ct.one_atm, \"CH4:0.95, O2:2, N2:7.52\"\n",
    "g.equilibrate(\"TP\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above statement sets the state of object `g` to the state of chemical equilibrium holding temperature and pressure fixed. Alternatively, the specific enthalpy and pressure can be held fixed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.TPX = 300.0, ct.one_atm, \"CH4:0.95, O2:2, N2:7.52\"\n",
    "g.equilibrate(\"HP\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other options are:\n",
    "* `'UV'` for fixed specific internal energy and specific volume\n",
    "* `'SV'` for fixed specific entropy and specific volume\n",
    "* `'SP'` for fixed specific entropy and pressure\n",
    "\n",
    "How can you tell if `equilibrate` has correctly found the chemical equilibrium state? One way is to verify that the net rates of progress of all reversible reactions are zero. Here is the code to do this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.TPX = 300.0, ct.one_atm, \"CH4:0.95, O2:2, N2:7.52\"\n",
    "g.equilibrate(\"HP\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     0    3.523e-16  \n",
      "     1    1.851e-16  \n",
      "     2    5.904e-16  \n",
      "     3   -5.209e-15  \n",
      "     4   -5.111e-15  \n",
      "     5    1.052e-14  \n",
      "     6   -3.396e-15  \n",
      "     7    5.229e-15  \n",
      "     8     3.62e-15  \n",
      "     9   -1.904e-15  \n",
      "    10   -3.274e-16  \n",
      "    11    1.891e-15  \n",
      "    12    4.946e-15  \n",
      "    13    3.011e-15  \n",
      "    14    2.147e-16  \n",
      "    15   -6.937e-15  \n",
      "    16   -1.238e-14  \n",
      "    17   -4.378e-15  \n",
      "    18   -1.142e-14  \n",
      "    19    5.548e-15  \n",
      "    20   -8.799e-16  \n",
      "    21    3.269e-15  \n",
      "    22    8.803e-15  \n",
      "    23    1.036e-14  \n",
      "    24    2.055e-15  \n",
      "    25    5.512e-15  \n",
      "    26   -9.727e-15  \n",
      "    27    3.085e-15  \n",
      "    28   -1.346e-14  \n",
      "    29    3.681e-15  \n",
      "    30   -2.105e-15  \n",
      "    31   -9.781e-16  \n",
      "    32    5.225e-15  \n",
      "    33    5.269e-15  \n",
      "    34    5.073e-15  \n",
      "    35    5.276e-15  \n",
      "    37    4.428e-15  \n",
      "    38   -1.423e-15  \n",
      "    39   -1.372e-15  \n",
      "    40   -1.346e-15  \n",
      "    41   -1.215e-15  \n",
      "    42    1.916e-15  \n",
      "    43   -5.255e-15  \n",
      "    44   -4.762e-15  \n",
      "    45   -6.832e-15  \n",
      "    46   -6.133e-15  \n",
      "    47    1.823e-15  \n",
      "    48    1.188e-15  \n",
      "    49   -3.344e-15  \n",
      "    50    1.381e-15  \n",
      "    51   -5.295e-15  \n",
      "    52    5.775e-15  \n",
      "    53   -7.116e-15  \n",
      "    54    5.229e-15  \n",
      "    55    6.705e-15  \n",
      "    56      5.9e-15  \n",
      "    57    5.756e-15  \n",
      "    58    3.869e-15  \n",
      "    59   -1.369e-14  \n",
      "    60   -1.109e-14  \n",
      "    61    -5.98e-15  \n",
      "    62     5.47e-15  \n",
      "    63    9.406e-16  \n",
      "    64   -1.217e-14  \n",
      "    65   -1.042e-14  \n",
      "    66   -5.254e-15  \n",
      "    67   -4.925e-15  \n",
      "    68   -1.191e-14  \n",
      "    69   -4.825e-15  \n",
      "    70   -8.667e-16  \n",
      "    71    8.884e-15  \n",
      "    72    3.002e-16  \n",
      "    73   -1.441e-14  \n",
      "    74   -9.039e-15  \n",
      "    75    9.089e-15  \n",
      "    76    1.466e-14  \n",
      "    77   -1.043e-14  \n",
      "    78    4.353e-15  \n",
      "    79   -1.392e-14  \n",
      "    80    1.979e-15  \n",
      "    81    1.713e-15  \n",
      "    82   -1.059e-14  \n",
      "    83    9.353e-15  \n",
      "    84    5.947e-15  \n",
      "    85    2.374e-15  \n",
      "    86   -3.362e-15  \n",
      "    87    1.012e-14  \n",
      "    88    1.032e-14  \n",
      "    89    1.717e-15  \n",
      "    90    1.973e-15  \n",
      "    91   -3.714e-15  \n",
      "    92    2.446e-15  \n",
      "    93   -1.806e-15  \n",
      "    94    1.628e-14  \n",
      "    95     9.54e-15  \n",
      "    96    4.816e-15  \n",
      "    97    1.516e-14  \n",
      "    98     2.17e-16  \n",
      "    99    6.772e-15  \n",
      "   100    9.103e-15  \n",
      "   101   -1.749e-14  \n",
      "   102    -1.06e-14  \n",
      "   103   -1.988e-15  \n",
      "   104    -8.95e-15  \n",
      "   105   -4.447e-15  \n",
      "   106    6.541e-15  \n",
      "   107     4.58e-15  \n",
      "   108    5.616e-15  \n",
      "   109    8.676e-15  \n",
      "   110    3.261e-15  \n",
      "   111   -6.605e-15  \n",
      "   112   -1.226e-15  \n",
      "   113    1.945e-15  \n",
      "   114    2.154e-16  \n",
      "   115    1.959e-16  \n",
      "   116   -1.045e-14  \n",
      "   117   -5.023e-15  \n",
      "   118    2.657e-15  \n",
      "   119   -1.974e-14  \n",
      "   120   -1.365e-15  \n",
      "   121   -2.128e-15  \n",
      "   122    -3.99e-15  \n",
      "   123   -5.494e-15  \n",
      "   124   -1.666e-15  \n",
      "   125    3.366e-15  \n",
      "   126   -5.315e-15  \n",
      "   127   -9.102e-15  \n",
      "   128   -5.594e-15  \n",
      "   129    1.235e-14  \n",
      "   130   -1.056e-14  \n",
      "   131    3.844e-15  \n",
      "   132    8.666e-15  \n",
      "   133   -2.205e-16  \n",
      "   135   -7.048e-15  \n",
      "   136   -1.049e-14  \n",
      "   137   -1.705e-16  \n",
      "   138    4.856e-15  \n",
      "   139   -2.585e-15  \n",
      "   140   -1.456e-16  \n",
      "   141    5.324e-15  \n",
      "   143     5.06e-15  \n",
      "   144    6.887e-15  \n",
      "   145   -2.147e-15  \n",
      "   146    1.091e-14  \n",
      "   147    5.272e-15  \n",
      "   148     5.05e-15  \n",
      "   149    9.878e-15  \n",
      "   150    5.243e-15  \n",
      "   151    1.168e-14  \n",
      "   152   -5.006e-15  \n",
      "   153   -5.305e-15  \n",
      "   154    7.805e-15  \n",
      "   155   -3.544e-15  \n",
      "   156   -4.948e-15  \n",
      "   157    3.511e-15  \n",
      "   158   -6.326e-15  \n",
      "   159   -1.468e-14  \n",
      "   160    6.922e-15  \n",
      "   161   -1.687e-14  \n",
      "   162   -1.143e-14  \n",
      "   163   -2.135e-14  \n",
      "   164   -2.882e-14  \n",
      "   165    4.389e-15  \n",
      "   166    4.376e-15  \n",
      "   167    1.646e-14  \n",
      "   168   -1.484e-15  \n",
      "   169   -7.223e-15  \n",
      "   170     7.17e-15  \n",
      "   171   -6.001e-15  \n",
      "   172    1.434e-14  \n",
      "   173   -8.055e-15  \n",
      "   174    1.314e-14  \n",
      "   175    3.061e-15  \n",
      "   176    1.012e-14  \n",
      "   177    1.974e-15  \n",
      "   178    1.763e-15  \n",
      "   179            0  \n",
      "   180   -1.403e-15  \n",
      "   181   -1.651e-16  \n",
      "   182   -8.486e-15  \n",
      "   183   -1.662e-15  \n",
      "   184   -2.399e-15  \n",
      "   185    1.562e-15  \n",
      "   186    1.795e-15  \n",
      "   187   -6.896e-15  \n",
      "   188   -8.728e-15  \n",
      "   189   -1.885e-15  \n",
      "   190   -3.324e-15  \n",
      "   191   -1.488e-15  \n",
      "   192   -3.832e-15  \n",
      "   193    3.189e-15  \n",
      "   194   -5.399e-15  \n",
      "   195   -1.687e-15  \n",
      "   196    -1.08e-14  \n",
      "   197     -3.3e-15  \n",
      "   198    4.426e-15  \n",
      "   199    1.355e-15  \n",
      "   200            0  \n",
      "   201    -2.96e-15  \n",
      "   202     6.85e-15  \n",
      "   203    3.539e-15  \n",
      "   204    3.564e-15  \n",
      "   205    8.622e-15  \n",
      "   206    2.127e-15  \n",
      "   207    4.559e-15  \n",
      "   208     2.26e-15  \n",
      "   209    1.063e-14  \n",
      "   210   -1.062e-14  \n",
      "   211    1.261e-15  \n",
      "   212   -7.257e-15  \n",
      "   213   -1.631e-15  \n",
      "   214    6.979e-15  \n",
      "   215   -2.473e-15  \n",
      "   216   -1.854e-15  \n",
      "   217   -3.698e-16  \n",
      "   218   -6.498e-15  \n",
      "   219   -2.673e-15  \n",
      "   220    3.004e-15  \n",
      "   221    8.767e-15  \n",
      "   222    5.136e-15  \n",
      "   223    2.232e-15  \n",
      "   224    1.432e-14  \n",
      "   225     6.59e-15  \n",
      "   226    2.129e-15  \n",
      "   227    3.396e-15  \n",
      "   228            0  \n",
      "   229     1.45e-15  \n",
      "   230    3.614e-15  \n",
      "   231    8.641e-15  \n",
      "   232    4.302e-15  \n",
      "   233   -4.679e-15  \n",
      "   234   -3.606e-15  \n",
      "   235    4.165e-15  \n",
      "   236   -1.526e-15  \n",
      "   237    3.894e-15  \n",
      "   238   -3.914e-16  \n",
      "   239            0  \n",
      "   240    4.629e-15  \n",
      "   241            0  \n",
      "   242    4.775e-15  \n",
      "   243    7.132e-16  \n",
      "   244   -1.869e-16  \n",
      "   245    -1.64e-15  \n",
      "   246     1.73e-15  \n",
      "   247   -7.974e-16  \n",
      "   248   -8.784e-15  \n",
      "   249   -5.175e-15  \n",
      "   250   -1.051e-14  \n",
      "   251   -1.665e-15  \n",
      "   252    2.452e-16  \n",
      "   253   -5.249e-15  \n",
      "   254    3.464e-15  \n",
      "   255    4.452e-15  \n",
      "   256    -1.79e-16  \n",
      "   257     -1.6e-15  \n",
      "   258   -5.137e-15  \n",
      "   259   -8.613e-15  \n",
      "   260    1.983e-15  \n",
      "   261    1.215e-14  \n",
      "   262    3.634e-15  \n",
      "   263    7.056e-15  \n",
      "   264     7.73e-15  \n",
      "   265     6.52e-15  \n",
      "   266    2.526e-15  \n",
      "   267    1.263e-15  \n",
      "   268    1.209e-14  \n",
      "   269    1.793e-15  \n",
      "   270     5.49e-15  \n",
      "   271    8.644e-15  \n",
      "   272    9.561e-16  \n",
      "   273    1.244e-14  \n",
      "   274    1.956e-15  \n",
      "   275     7.73e-15  \n",
      "   276   -2.879e-15  \n",
      "   277   -2.499e-16  \n",
      "   278   -2.247e-15  \n",
      "   279   -7.943e-15  \n",
      "   280   -3.345e-15  \n",
      "   281    7.111e-15  \n",
      "   282    1.079e-14  \n",
      "   284    1.086e-14  \n",
      "   285    1.239e-14  \n",
      "   286   -3.341e-15  \n",
      "   288            0  \n",
      "   290   -5.374e-15  \n",
      "   293    1.725e-14  \n",
      "   294     1.27e-14  \n",
      "   295   -7.339e-16  \n",
      "   298    1.128e-14  \n",
      "   303    5.522e-15  \n",
      "   307   -7.913e-15  \n",
      "   308    -1.25e-14  \n",
      "   309   -3.853e-15  \n",
      "   310    3.072e-15  \n",
      "   311    9.317e-15  \n",
      "   312    1.506e-14  \n",
      "   313    1.429e-14  \n",
      "   314    1.745e-14  \n",
      "   315   -2.027e-14  \n",
      "   316    2.277e-15  \n",
      "   317    9.991e-15  \n",
      "   318   -3.385e-14  \n",
      "   319   -1.377e-14  \n",
      "   320    -2.41e-14  \n",
      "   321   -2.613e-14  \n",
      "   322   -2.009e-14  \n",
      "   324   -3.706e-14  \n"
     ]
    }
   ],
   "source": [
    "rf = g.forward_rates_of_progress\n",
    "rr = g.reverse_rates_of_progress\n",
    "for i in range(g.n_reactions):\n",
    "    if g.is_reversible(i) and rf[i] != 0.0:\n",
    "        print(\"  %4i   %10.4g  \" % (i, (rf[i] - rr[i]) / rf[i]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the magnitudes of the numbers in this list are all very small (which in this case they are), then each reversible reaction is very nearly equilibrated, which only occurs if the gas is in chemical equilibrium.\n",
    "\n",
    "You might be wondering how `equilibrate` works. (Then again, you might not.) Method `equilibrate` invokes Cantera's chemical equilibrium solver, which uses an element potential method. The element potential method is one of a class of equivalent *nonstoichiometric* methods that all have the characteristic that the probelm reduces to solving a set of $M$ nonlinear algebraic equations, where $M$ is the number of elements (not species). The so-called *stoichiometric* methods, on the other hand (including the Gibbs minimization), require solving $K$ nonlinear equations, where $K$ is the number of species (usually $K >> M$). See Smith and Missen's \"Chemical Reaction Equilibrium Analysis\" for more information on the various algorithms and their characteristics.\n",
    "\n",
    "Cantera uses a damped Newton method to solve these equations, and does a few other things to generate a good starting guess and to produce a reasonably robust algorithm. If you want to know more about the details, look at the on-line documentated source code of Cantera C++ class [`ChemEquil`](https://cantera.org/documentation/dev/doxygen/html/da/d0e/classCantera_1_1ChemEquil.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Chemical Kinetics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[`Solution`](https://cantera.org/documentation/dev/sphinx/html/cython/importing.html#cantera.Solution) objects are also [`Kinetics`](https://cantera.org/documentation/dev/sphinx/html/cython/kinetics.html#cantera.Kinetics) objects, and provide all of the methods necessary to compute the thermodynamic quantities associated with each reaction, reaction rates, and species creation and destruction rates. They also provide methods to inspect the quantities that define each reaction, such as the rate constants and the stoichiometric coefficients. The rate calculation functions are used extensively within Cantera's *[reactor network model](https://cantera.org/documentation/dev/sphinx/html/cython/zerodim.html#sec-cython-zerodim)* and *[1D flame model](https://cantera.org/documentation/dev/sphinx/html/cython/onedim.html#sec-cython-onedim)*.\n",
    "\n",
    "Information about individual reactions that are independent of the thermodynamic state can be obtained by accessing [`Reaction`](https://cantera.org/documentation/dev/sphinx/html/cython/kinetics.html#cantera.Reaction) objects with the [`Kinetics.reaction`](https://cantera.org/documentation/dev/sphinx/html/cython/kinetics.html#cantera.Kinetics.reaction) method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<ElementaryReaction: H2 + O <=> H + OH>"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g = ct.Solution(\"gri30.yaml\")\n",
    "r = g.reaction(2)  # get a Reaction object\n",
    "r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'H2': 1.0, 'O': 1.0}"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "r.reactants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'H': 1.0, 'OH': 1.0}"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "r.products"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<ArrheniusRate at ffff81ea1c60>"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "r.rate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we are interested in only certain types of reactions, we can use this information to filter the full list of reactions to find just the ones of interest. For example, here we find the indices of just those reactions which convert `CO` into `CO2`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CO + O (+M) <=> CO2 (+M)\n",
      "CO + O2 <=> CO2 + O\n",
      "CO + OH <=> CO2 + H\n",
      "CO + HO2 <=> CO2 + OH\n"
     ]
    }
   ],
   "source": [
    "II = [\n",
    "    i\n",
    "    for i, r in enumerate(g.reactions())\n",
    "    if \"CO\" in r.reactants and \"CO2\" in r.products\n",
    "]\n",
    "\n",
    "for i in II:\n",
    "    print(g.reaction(i).equation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(Actually, we should also include the reactions where the reaction is written such that `CO2` is a reactant and `CO` is a product, but for this example, we'll just stick to this smaller set of reactions.) Now, let's set the composition to an interesting state:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "g.TPX = 300, 101325, {\"CH4\": 0.6, \"O2\": 1.0, \"N2\": 3.76}\n",
    "g.equilibrate(\"HP\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can verify that this is an equilibrium state by seeing that the net reactions rates are essentially zero:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([-2.64274280e-19, -6.56450534e-21,  0.00000000e+00, -9.82558219e-20])"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g.net_rates_of_progress[II]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's see what happens if we decrease the temperature of the mixture:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([3.18644907e-05, 5.00489883e-08, 1.05964910e-01, 2.89502678e-06])"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g.TP = g.T - 100, None\n",
    "g.net_rates_of_progress[II]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All of the reaction rates are positive, favoring the formation of `CO2` from `CO`, with the third reaction, `CO + OH <=> CO2 + H` proceeding the fastest. If we look at the enthalpy change associated with each of these reactions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([-5.33034690e+08, -2.23248529e+07, -8.76650141e+07, -2.49169644e+08])"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g.delta_enthalpy[II]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "we see that the change is negative in each case, indicating a net release of thermal energy. The total heat release rate can be computed either from the reaction rates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-58013369.59815948"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dot(g.net_rates_of_progress, g.delta_enthalpy)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or from the species production rates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-58013369.598159574"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dot(g.net_production_rates, g.partial_molar_enthalpies)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The contribution from just the selected reactions is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-9307122.692794016"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dot(g.net_rates_of_progress[II], g.delta_enthalpy[II])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or about 16% of the total heat release rate."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}