diff --git a/Docs/sphinx/Ceptr.rst b/Docs/sphinx/Ceptr.rst index 2bed1fef3..a91a72128 100644 --- a/Docs/sphinx/Ceptr.rst +++ b/Docs/sphinx/Ceptr.rst @@ -5,7 +5,7 @@ CEPTR: Chemistry Evaluation for Pele Through Recasting ====================================================== -We use CEPTR to generate C++ mechanism files from `Cantera `_ yaml chemistry files. CEPTR is a python package part of the PelePhysics source code. +We use CEPTR to generate C++ mechanism files from `Cantera `_ YAML chemistry files. CEPTR is a python package part of the PelePhysics source code. .. _sec_ceptr_software: @@ -19,13 +19,27 @@ To install CEPTR dependencies:: $ cd ${PELE_PHYSICS_HOME}/Support/ceptr $ poetry update +.. note:: Note that the install requires a specific Python version, which is specified in the ``Support/ceptr/pyproject.toml``. If a compatible version exists in your system then poetry will try to find and use it. Otherwise, think about using a `conda `_ environment to manage packages and their dependencies without tampering with your system. + Usage ----- -Generating for a single chemistry -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Generating YAML chemistry files: converting from CHEMKIN files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _sec_convertCK: + +We rely on Cantera's ``ck2yaml`` utility to convert CHEMKIN files to the Cantera YAML format:: + + $ cd ${PELE_PHYSICS_HOME}/Support/ceptr + $ poetry run ck2yaml --input=${PATH_TO_CHEMKIN_DIR}/mechanism.inp --thermo=${PATH_TO_CHEMKIN_DIR}/therm.dat --transport=${PATH_TO_CHEMKIN_DIR}/tran.dat --permissive + +Of course, the files ``tran.dat`` and ``therm.dat`` are optional if already included in the ``mechanism.inp`` file. + -There are three ways to use CEPTR to generate C++ mechanism files for a given chemistry +Generating Pele-compatible mechanisms for a single chemistry +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are three ways to use CEPTR to generate C++ mechanism files for a given chemistry. 1. Using CEPTR directly: @@ -36,11 +50,11 @@ There are three ways to use CEPTR to generate C++ mechanism files for a given ch --gas_name {gas-name} \ --interface_name {interface-name} - The ``--chemistry``, or equivalently ``-c``, argument allows users to convey if the ``${chemistry}`` of interest is either one of two valid options, namely, ``homogeneous`` or ``heterogeneous``. - Similarly, the ``--gas_name`` and ``--interface_name`` arguments allow users to specify the names of the homogeneous phase and gas-solid interface prescribed in the corresponding ``mechanism.yaml`` file. + The ``--chemistry`` (or ``-c``) argument allows users to convey if the ``${chemistry}`` of interest is either one of two valid options, namely, ``homogeneous`` or ``heterogeneous``. The default value for ``{chemistry-type}`` is ``homogeneous``. + The ``--gas_name`` argument allows users to specify the names of the homogeneous phase to use, as several different ones can be defined in the corresponding ``mechanism.yaml`` file (under the ``phases:`` item). The default value for ``{gas-name}`` is ``gas``. + Finally, the ``--interface_name`` arguments allow users to specify the name of the gas-solid interface, also prescribed in the corresponding ``mechanism.yaml`` file. The default value for ``{interface-name}`` is ``None``. - The default ``chemistry-type``, ``gas-name`` are ``homogeneous`` and ``gas`` respectively while that for ``interface-name`` is ``None``. - Note that if a ``heterogeneous`` ``chemistry-type`` is specified, the user must necessarily specify a corresponding ``interface-name``. + Note that if ``--chemistry heterogeneous`` is specified, the user must necessarily specify a corresponding ``{interface-name}``. An example of directly using CEPTR for homogeneous mechanisms is:: @@ -53,13 +67,51 @@ There are three ways to use CEPTR to generate C++ mechanism files for a given ch $ ./convert.sh -3. Using a helper script in the ``Models`` directory:: + .. note:: It is possible that using this option will require for you to have a valid Cantera installed somewhere. Again, we strongly suggest using a `conda `_ environment to install all required package. A simple ceptr environment can be generated using the following yaml script:: + + $ name: ceptr + $ channels: + $ - conda-forge + $ dependencies: + $ - python=3.10 + $ - cantera + +3. Using a helper script in the ``Mechanisms`` directory:: $ bash ${PELE_PHYSICS_HOME}/Mechanisms/converter.sh -f ./LiDryer/mechanism.yaml -Batched generation -^^^^^^^^^^^^^^^^^^ +Generating a reduced, QSS chemistry file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first step consists in generating a QSS chemistry YAML file from a skeletal or a detailed YAML file. To do so, one needs: the mechanism YAML file ``skeletal.yaml``, as well as a list of non-QSS species, ``non_qssa_list.yaml``. The following command will generate a QSS YAML file, ``qssa.yaml``:: + + $ cd ${PELE_PHYSICS_HOME}/Support/ceptr + $ poetry run qssa -f ${PATH_TO_YAML}/skeletal.yaml -n ${PATH_TO_YAML}/non_qssa_list.yaml + +The full list of options is:: + + $ poetry run qssa -h + usage: qssa [-h] -f FNAME -n NQSSA [-m {0,1,2}] [-v] + + Mechanism converter + + optional arguments: + -h, --help show this help message and exit + -f FNAME, --fname FNAME + Mechanism file + -n NQSSA, --nqssa NQSSA + Non-QSSA species list + -m {0,1,2}, --method {0,1,2} + QSSA method (default: 2) + -v, --visualize Visualize quadratic coupling and QSSA dependencies + +For a detailed description of these options and a further information on the way QSS mechanism are treated in CEPTR the reader may consult :ref:`the QSS section `. + +To generate a QSS C++ mechanism from the ``.yaml`` file thus created, tailored to your needs, please refer to Tutorials :ref:`Generating NC12H26 QSS mechanism with analytical jacobian ` and :ref:`Generating NC12H26 QSS mechanism without analytical jacobian `. + +Batched generation of Pele-compatible mechanisms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -88,41 +140,3 @@ To generate all mechanisms:: $ poetry run convert -lq ${PELE_PHYSICS_HOME}/Mechanisms/list_qss_mech -Converting CHEMKIN files ------------------------- -.. _sec_convertCK: - -We rely on Cantera's ``ck2yaml`` utility to convert CHEMKIN files to the Cantera yaml format (and proceed as above with CEPTR on the resulting yaml file):: - - $ cd ${PELE_PHYSICS_HOME}/Support/ceptr - $ poetry run ck2yaml --input=${PATH_TO_CHEMKIN_DIR}/mechanism.inp --thermo=${PATH_TO_CHEMKIN_DIR}/therm.dat --transport=${PATH_TO_CHEMKIN_DIR}/tran.dat --permissive - -The files ``tran.dat`` and ``therm.dat`` are optional if already included in the ``.inp`` file. - -Generating a QSS chemistry file -------------------------------- - -To generate a QSS chemistry yaml file from another yaml file, one executes:: - - $ poetry run qssa -f ${PATH_TO_YAML}/skeletal.yaml -n ${PATH_TO_YAML}/non_qssa_list.yaml - -The full list of options is:: - - $ poetry run qssa -h - usage: qssa [-h] -f FNAME -n NQSSA [-m {0,1,2}] [-v] - - Mechanism converter - - optional arguments: - -h, --help show this help message and exit - -f FNAME, --fname FNAME - Mechanism file - -n NQSSA, --nqssa NQSSA - Non-QSSA species list - -m {0,1,2}, --method {0,1,2} - QSSA method (default: 2) - -v, --visualize Visualize quadratic coupling and QSSA dependencies - -For a detailed description of these options and a further information on the way QSS mechanism are treated in `CEPTR` the reader may consult :ref:`the QSS section `. - -See Tutorials (:ref:`Generating NC12H26 QSS mechanism with analytical jacobian ` and :ref:`Generating NC12H26 QSS mechanism without analytical jacobian `) for generating QSS mechanisms from the ``.yaml`` files.