Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the CEPTR usage doc slightly. #499

Merged
merged 3 commits into from
May 21, 2024
Merged

Update the CEPTR usage doc slightly. #499

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5153152
Update the CEPTR usage doc slightly.
EnnaDelfen May 15, 2024
9c2b152
Typo fix
EnnaDelfen May 16, 2024
26fe3ff
Simplify the conda yml file to a minimum + fix the text to reflect th…
EnnaDelfen May 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 63 additions & 49 deletions Docs/sphinx/Ceptr.rst
View file
Open in desktop
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.
Loading