<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<htlm lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <link rel="stylesheet" href="style/manual.css" type="text/css">
  <title>KUCRS-chemgen</title>
</head>
<body>

<div class="sign">
 (c) 2002&ndash;2025 by <a href="../index.html.en">A.
  Miyoshi</a><br> All rights reserved.
</div>
<div class="title">KUCRS</div>
<div class="subttl">&ndash; Knowledge-basing Utilities for Complex Reaction
 Systems &ndash;<br clear="right"></div>

<hr> <!-- ------------------------------------------------------------ -->
<div class="lang"><a href="chemgen.htm.ja">Japanese</a></div>
<div class="back"><a href="refman.htm.en">Back</a></div>
<h1 class="cmp">Manual of chemgen<br clear="all"></h1>
<hr> <!-- ------------------------------------------------------------ -->

<div class="main"> <!-- ---------------------------------------------- -->

<div class="ind1mgn">
 &nbsp; The <code>chemgen</code> is a component of the KUCRS and processes
 a list of
 reactions in macro representation and generate a Chemkin format reaction
 input. &nbsp; It is a basic tool to generate a reaction mechanism with
 rule-based rate constants, correctly and efficiently. &nbsp;
 It can be used separately from the KUCRS, or may be used to modify or
 supplement the mechanism generated by the KUCRS.
</div>

<h2>Synopsis</h2>
<div class="ind1mgn">
  <div class="cmdl">
    chemgen <font color="blue">bname</font>_chg.inp bname_thg.dat &gt;
     bname_chg.log
  </div>
  <h3>Input</h3>
  <div class="ind0smgn"><table>
    <tr><td class="iod"></td>
      <td class="iod" align="center"><small>required</small></td></tr>
    <tr><td class="io"><font color="blue">bname</font>_chg.inp</td>
      <td class="iod" align="center">*</td>
      <td class="iod">reaction list in macro representation</td></tr>
    <tr><td class="io">bname_thg.dat</td>
      <td class="iod" align="center">*</td>
      <td class="iod">thermodynamic data</td></tr>
    <tr><td class="io">KUCRS_LIB\bas_rxns.inp</td>
      <td class="iod"></td><td class="iod">(base mechanism)</td></tr>
    <tr><td class="io">KUCRS_LIB\bas_thrm.dat</td>
      <td class="iod"></td><td class="iod">(base thermodata)</td></tr>
    <tr><td class="io">KUCRS_LIB\elm_tbl.dat</td>
      <td class="iod" align="center">*</td>
      <td class="iod">element data</td></tr>
    <tr><td class="io">KUCRS_LIB\rxn_macr.dat</td>
      <td class="iod" align="center">*</td>
      <td class="iod">macro definitions</td></tr>
  </table></div>
  <div class="note">
    KUCRS_LIB\ = Directory pointed by an environment variable
     KUCRS_LIB. (current directory if not defined)
  </div>
  <h3>Output</h3>
  <div class="ind0smgn"><table>
    <tr><td class="io">bname_chg.log</td>
     <td class="iod">diagnostic output of chemgen</td></tr>
    <tr><td class="io"><font color="blue">bname</font>_chm.inp</td>
     <td class="iod">reaction mechanism in Chemkin format</td></tr>
    <tr><td class="io"><font color="blue">bname</font>_rxn.inp</td>
     <td class="iod">do. (reactions block)</td></tr>
    <tr><td class="io"><font color="blue">bname</font>_spc.inp</td>
     <td class="iod">do. (elements/species block)</td></tr>
    <tr><td class="io"><font color="blue">bname</font>_thm.dat</td>
     <td class="iod">do. (thermo block)</td></tr>
  </table></div>
</div>

<h2>Downloading & Executing a Sample (Windows)</h2>

<div class="ind1mgn">
 &nbsp; A <code>chemgen</code> executable (on Windows) and sample input files
 for separate use from KUCRS can be downloaded from below.
 <div class="ind1smgn"><ul class="dsbl">
   <li><a href="chemgen20081222.zip">chemgen20081222.zip</a>
 </ul></div>
</div>
<div class="ind0mgn"><ol>
 <li>Click the link above and save the <code>chemgen20081222.zip</code>.
  &nbsp; The location is assumed to be C:\ in the following instructions.
 <li>Extract the <code>chemgen20081222.zip</code>.&nbsp;
  The following files should be generated in the folder
  <code>chemgen</code>.
  <pre class="txt">
chemgen.exe
elm_tbl.dat
rxn_macr.dat
sample_chg.inp
sample_thg.dat</pre>
 <li>Open the <i>Command Prompt</i>, change directory to where the
  <code>chemgen</code> files have been extracted, and type as follows.
  <div class="cmdl">
    C:\chemgen&gt; <font color="brown">chemgen sample_chg.inp sample_thg.dat &gt; sample_chg.log</font>
  </div>
 <li>The following files should be newly formed.
  <pre class="txt">
sample_chg.log
sample_chm.inp
sample_rxn.inp
sample_spc.inp
sample_thm.dat</pre>
 <li>In this sample, a Chemkin-format mechanism file,
  <code>sample_chm.inp</code>, is generated by processing the reaction list
  in macro representation described in <code>sample_chg.inp</code>.&nbsp;
  The macro's are defined in <code>rxn_macr.dat</code>.&nbsp;
  All the input and output files are text-format files, and can be viewed
  and edited by a text editor such as the <i>Notepad</i> or the
  <i>WordPad</i>.&nbsp;
  See the instructions below for the format of the input files <i>etc</i>.
</ol></div>

<h2>Input Files</h2>

<div class="ind1mgn">
  <h3>Element data <small>(required)</small></h3>
  <ul class="dsgr">
   <li>Not necessary to be edited unless (a) new element(s) is needed to be
    added.&nbsp; Its file name is fixed (<code>elm_tbl.dat</code>) and
    it should reside in the current directory.
    [<a href="#ref1">#1</a>]
  </ul>
</div>

<div class="ind1mgn">
  <h3>Macro definitions <small>(required)</small></h3>
  <ul class="dsgr">
   <li>Place in the current directory [<a href="#ref1">#1</a>] with the
    specified file name: <code>rxn_macr.dat</code>.&nbsp;
    Below is the sample definitions.
    <pre class="txtt">rxn_macr.dat</pre>
    <pre class="txtc">

! sample macro definitions

! ----- H-abstraction by OH
 Habs/by-OH/Prim      8.83E+06    1.80     855.  ! per one CH3 group
 Habs/by-OH/Tert      5.73E+10    0.51      63.  ! per one CH group
!
! ----- decomposition of hydrocarbons
 Rv/Dcmp/C-Me         1.00E+13    0.         0.
!</pre>
   <li>A macro is defined in the following format.
    <div class="frmt">
      &nbsp; <i>macro_name</i> &nbsp; <i>A</i> &nbsp; <i>n</i> &nbsp; <i>E</i><sub>a</sub>
    </div>
    <i>macro_name</i> is the name of the macro. <i>A</i>, <i>n</i>, and
    <i>E</i><sub>a</sub> are the parameters of the modified Arrhenius expression,
    <div class="ind2">
      <i>k</i> = <i>AT<sup> n </sup></i>exp(&minus;<i>E</i><sub>a</sub> / <i>RT</i>).
    </div>
    The unit system for the rate parameters is the default of Chemkin, that is,
    cm<sup>3</sup>-mol-s-cal system.
   <li>From an explanation mark (<code>!</code>) to the line end is a comment.
   <li>A macro with a name beginning with <code>Rv/</code> is treated so
    that the given pameters, <i>A</i>, <i>n</i>, and <i>E</i><sub>a</sub>, are
    for its reverse reaction.&nbsp;
    For example, the last macro in the above example defines the rate constant
    for the reverse of the methyl radical elimination reaction from a
    hydrocarbon to be 1&times;10<sup>13</sup>.&nbsp;
    In general for a reaction such as a decomposition reaction, it is convenient
    to give a rate constant for the reverse reaction.
  </ul>
</div>

<div class="ind1mgn">
  <h3>Reaction list <small>(required)</small></h3>
  <ul class="dsgr">
   <li>The file name must be in the form of
    <code><font color="blue">bname</font>_chg.inp</code>, that is,
    must end with <code>&quot;_chg.inp&quot;</code>.&nbsp;
    The part <code><font color="blue">bname</font></code> is used to determine
    the name of the output files.&nbsp;
    When invoking <code>chemgen</code>, the file name should be specified
    as the first argument of the command line.&nbsp;
    Below is the content of the sample file.
    <pre class="txtt">sample_chg.inp</pre>
    <pre class="txtc">
# sample chemgen input

!
! isobutane reactions with OH

 iC4H10 OH = iC4H9 H2O $ Habs/by-OH/Prim 0 3 Y
 iC4H10 OH = tC4H9 H2O $ Habs/by-OH/Tert 0 1 Y
!
! decomposition of isobutane

 iC4H10 = CH3 iC3H7    $ Rv/Dcmp/C-Me    0 3 Y
 </pre>
   <li>One reaction should be described in one line in the following format.
    <div class="frmt">
      &nbsp; <i>reactant</i><sub>1</sub> ... &nbsp;=&nbsp;
      <i>product</i><sub>1</sub> ... 
      &nbsp;$&nbsp; <i>macro_name</i> &nbsp;&Delta;<i>E</i><sub>a</sub>
      &nbsp;<i>mult_A</i> &nbsp;<i>flag_rev</i>
    </div>
    The reaction equation is written left to the $, and the reactants delimited
    with white spaces are listed left to the = and products to the right.
   <li>The &Delta;<i>E</i><sub>a</sub> may be set other than zero (0) when an
    adjustment to the macro-defined activation energy is needed.
   <li>The <i>mult_A</i> may be used to modify the preexponential factor
    by setting it other than one (1).&nbsp; In the example here,
    it is used to triple the rate constant for the H-abstraction reaction
    from the primary carbon and that for the CH<sub>3</sub> elimination
    reaction since the isobutane has three equivalent methyl groups.
   <li>The last parameter <i>flag_rev</i> is a flag to indicate whether to
    consider the reverse reaction or not.&nbsp;
    Set <code>Y</code> to include, and <code>N</code> to omit the reverse
    reaction.
   <li>Both of the lines beginning with <code>!</code> and <code>#</code>
    are comment lines, though that beginning with <code>!</code> is transferred
    to the Chemkin input as it is as a comment line, while that with
    <code>#</code> is not copied.
  </ul>
</div>

<div class="ind1mgn">
  <h3>Thermodynamic data <small>(required)</small></h3>
  <ul class="dsgr">
   <li>It may have any file name but should be specified as the second argument
    to the command line when invoking <code>chemgen</code>.&nbsp;
    A part of the sample is shown below.&nbsp;
    The format is the same as that for Chemkin thermodata.
    <pre class="txtt">sample_thg.dat</pre>
    <pre class="txtc">
THERMO                                                                          
   300.000  1500.000  5000.000                                                  
iC4H10            thgen C   4H  10          G   300.000  5000.000 1389.00      1
 1.25733188E+01 2.18921034E-02-7.52507819E-06 1.17199470E-09-6.81406454E-14    2
-2.31695053E+04-4.68052242E+01-1.01548278E+00 5.04801838E-02-3.00674447E-05    3
 9.16431647E-09-1.15528714E-12-1.80491562E+04 2.74371619E+01                   4
iC4H9             thgen C   4H   9          G   300.000  5000.000 1389.00      1
 1.21596150E+01 1.97412861E-02-6.79323159E-06 1.05880234E-09-6.15918443E-14    2
 1.89478674E+03-4.06305807E+01-2.60119556E-01 4.59801603E-02-2.76540140E-05    3
 8.55997651E-09-1.10410554E-12 6.56626481E+03 2.71901259E+01                   4
...</pre>
   <li>The thermodynamic data may be generated by using THERM <i>etc</i>.&nbsp;
    Thermodata for all of the reactants and products in the reaction list
    must be in this file or in the optional file <code>bas_thrm.dat</code>
    (see below).
  </ul>
</div>

<div class="ind1mgn">
  <h3>Optional input</h3>
  <ul class="dsgr">
   <li>When a file named <code>bas_rxns.inp</code> or <code>bas_thrm.dat</code>
    <small>(the file name is fixed for either)</small> is found in the current
    directory [<a href="#ref1">#1</a>], <code>chemgen</code> copies its content
    into the last of the reaction list or the thermodata, respectively.&nbsp;
    For example, base machanism for the H<sub>2</sub>-O<sub>2</sub> system
    may be described in these files in order to include them always in the
    mechanism.&nbsp;
    In the KUCRS system, the species up to C<sub>2</sub> and their reactions
    are registered as a base mechanism.
  </ul>
</div>

<h2>Output Files</h2>

<div class="ind1mgn">
  <h3>Chemkin input</h3>
  <ul class="dsgr">
   <li>The output file name is
    <code><font color="blue">bname</font>_chm.inp</code>, where
    <code><font color="blue">bname</font></code> is a base name generated by
    eliminating <code>&quot;_chg.inp&quot;</code> from the tail of the
    reaction list file name.&nbsp; Below is a part of the Chemkin input file
    generated by processing the example input.
    <pre class="txtt">sample_chm.inp</pre>
    <pre class="txtc">
elements
 H C O
end
species
 iC4H10 iC4H9 tC4H9 OH H2O CH3 iC3H7
end
thermo all
   300.000  1000.000  5000.000
iC4H10            thgen C   4H  10          G   300.000  5000.000 1389.00      1
 1.25733188E+01 2.18921034E-02-7.52507819E-06 1.17199470E-09-6.81406454E-14    2
-2.31695053E+04-4.68052242E+01-1.01548278E+00 5.04801838E-02-3.00674447E-05    3
 9.16431647E-09-1.15528714E-12-1.80491562E+04 2.74371619E+01                   4
...(snip)...
end
reactions      cal/mole  moles
!
! isobutane reactions with OH
 iC4H10+OH=iC4H9+H2O                              2.649e+07   1.800     855.0
                                           rev /  2.188e+04   2.313   18689.0 /
 iC4H10+OH=tC4H9+H2O                              5.730e+10   0.510      63.0
                                           rev /  4.536e+06   1.518   22283.5 /
!
! decomposition of isobutane
 iC4H10=CH3+iC3H7                                 4.480e+25  -2.321   89803.0
                                           rev /  3.000e+13   0.000       0.0 /
end</pre>
   <li>In the <i>species</i> block, all the species found in the thermodynamic
    data file specified as the second command-line argument when invoking
    <code>chemgen</code> and the <code>bas_thrm.dat</code> are listed.&nbsp;
    The <i>elements</i> block is generated automatically from the thermodynamic
    data for all the sepcies.&nbsp; When you need the diluent gases such as
    N<sub>2</sub> or Ar, register it in the <code>bas_thrm.dat</code>.&nbsp;
    Then it is automatically described in both <i>elements</i> and
    <i>species</i> blocks.
   <li>Look how the <i>reactions</i> block is generated by macro substitutions
    and reverse rate calculations.&nbsp; For the last reaction described by a
    macro biginning with <code>Rv/</code>, see that the rate parameters
    specified in the macro definition are used for the reverse reaction.
  </ul>
</div>

<div class="ind1mgn">
  <h3>Log</h3>
  <ul class="dsgr">
   <li>The output file name is
    <code><font color="blue">bname</font>_chg.log</code>, which is determined by
    replacing the extension of the reaction list file name by
    <code>.log</code>.&nbsp;
    Part of the log file generated when the sample files are processed is shown
    below.
    <pre class="txtt">sample_chg.log</pre>
    <pre class="txtc">
15 elements loaded from [elm_tbl.dat]
3 rate macros loaded from [rxn_macr.dat]
7 thermodata loaded from [sample_thg.dat]
 reaction                                             delH      delS
                                                  kcal/mol cal/K/mol
 iC4H10+OH=iC4H9+H2O                               -18.288     6.818
---------- rate calculations ----------
 rev /  2.188e+04   2.313   18689.0 /
  T/K        kf         kr         Kc 
  300  1.816e+11  2.798e-04  6.490e+14
  400  4.362e+11  1.434e+00  3.041e+11
  500  8.082e+11  2.650e+02  3.049e+09
  600  1.295e+12  9.207e+03  1.407e+08
  800  2.601e+12  8.867e+05  2.933e+06
 1000  4.327e+12  1.547e+07  2.797e+05
 1500  1.036e+13  9.080e+08  1.141e+04
 2000  1.869e+13  8.533e+09  2.190e+03
 2500  2.915e+13  3.690e+10  7.899e+02
 3000  4.165e+13  1.059e+11  3.934e+02
 3500  5.611e+13  2.372e+11  2.365e+02
 4000  7.246e+13  4.517e+11  1.604e+02
 5000  1.106e+14  1.200e+12  9.219e+01
---------------------------------------
...(snip)...
Copying sample_spc.inp + sample_thm.dat + sample_rxn.inp -> sample_chm.inp - succeeded.</pre>
   <li>The first section includes the diagnostic messages whether the input
    files (including the optional ones) are read correctly or not.
   <li>The lines after the one containing &quot;<code>reaction ...
    delH delS</code>&quot; list the
    &Delta;<i>H</i> (enthalpy change), &Delta;<i>S</i> (entropy change) of
    the reaction at 298 K, the rate constants for forward and reverse reaction,
    and the equilibrium constants from 300 K to 5000 K.
  </ul>
</div>

<div class="ind1mgn">
  <h3>Others</h3>
  <ul class="dsgr">
   <li>The files named as <code><font color="blue">bname</font>_spc.inp</code>,
    <code><font color="blue">bname</font>_thm.dat</code>, and
    <code><font color="blue">bname</font>_rxn.inp</code> are the temporary files
    for generation of Chemkin input, and not needed in usual circumstances.
  </ul>
</div>

</div> <!-- ---------------------------------------------------------- -->
<hr> <!-- ------------------------------------------------------------ -->

<div class="ref"><a name="ref1"></a>[#1] May be placed in another directory
 by setting the environment variable <code>KUCRS_LIB</code>.&nbsp;
 For examble in <code>setenv.bat</code> in KUCRS it is set as:
 <code>set KUCRS_LIB=C:\KUCRS\libdata</code>
</div>

<hr> <!-- ------------------------------------------------------------ -->
</body>
</html>
