Skip to content

Commit

Permalink
Update the CEPTR usage doc (#499)
Browse files Browse the repository at this point in the history
  • Loading branch information
@EnnaDelfen
EnnaDelfen authored May 21, 2024
1 parent 6557148 commit 4157d7a
Showing 1 changed file with 63 additions and 49 deletions.
112 changes: 63 additions & 49 deletions Docs/sphinx/Ceptr.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
CEPTR: Chemistry Evaluation for Pele Through Recasting
======================================================

We use CEPTR to generate C++ mechanism files from `Cantera <https://cantera.org>`_ yaml chemistry files. CEPTR is a python package part of the PelePhysics source code.
We use CEPTR to generate C++ mechanism files from `Cantera <https://cantera.org>`_ YAML chemistry files. CEPTR is a python package part of the PelePhysics source code.

.. _sec_ceptr_software:

Expand All @@ -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 <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_ 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:

Expand All @@ -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::

Expand All @@ -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 <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_ 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 <sec_qss>`.

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 <sec_tutqss1>` and :ref:`Generating NC12H26 QSS mechanism without analytical jacobian <sec_tutqss2>`.

Batched generation of Pele-compatible mechanisms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

Expand Down Expand Up @@ -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 <sec_qss>`.

See Tutorials (:ref:`Generating NC12H26 QSS mechanism with analytical jacobian <sec_tutqss1>` and :ref:`Generating NC12H26 QSS mechanism without analytical jacobian <sec_tutqss2>`) for generating QSS mechanisms from the ``.yaml`` files.

0 comments on commit 4157d7a

Please sign in to comment.