Command-line input format specification

overreact is both a library and a command-line application. In this subsection, we briefly describe the minimal input specification for the command-line application for doing first-principles microkinetic simulations. Don't worry, the input is very simple, yet flexible.

Basically, overreact parses complex reaction schemes with the help of a domain-specific language (DSL) designed to be as flexible and intuitive as possible to any chemist. For instance, as a purely illustrative example, the following Curtin-Hammett system,

\[ \require{mhchem} \ce{ P_{A}(w) <- [A(w)]^{\ddagger} <- A(w) <=> B(w) -> [B(w)]^{\ddagger} -> P_{B}(w) } \]

could be modelled very easily as follows (saved, say, in a curtin_hammett.k file):

// This is a comment and is ignored by overreact.

$scheme
 // Here we define our reactions.
 A(w) <=> B(w)
 A(w) -> A‡(w) -> P_A(w)
 B(w) -> B‡(w) -> P_B(w)
$end

$compounds
 // Here we specify the files for all species.
 A(w):   A@water.out
 B(w):   B@water.out
 A‡(w):  A_TS@water.out
 B‡(w):  B_TS@water.out
 P_A(w): P_A@water.out
 P_B(w): P_B@water.out
$end

Some things to note

  • // indicates a comment. They are ignored until the end of the line.
  • Blank lines are also ignored.
  • Two blocks are required: the $scheme block and the $compounds block.
  • $end indicates the end of a block. It is optional: opening a new block closes the previous one.
  • Compound labels are case-sensitive. They must start with a letter but can contain any character except spaces. Labels in the $scheme block should match the ones in $compounds.
  • Stoichiometric coefficients are specified as multipliers in front of the compound labels, e.g., 2 * A(w), 3 * A(w), etc. A(w) equivalent to 1 * A(w).
  • -> means a forward reaction (listing first reactants, then products).
  • <- means a backward reaction (listing first products, then reactants).
  • <=> means an equilibrium. They are useful when one does not want separately model both forward and backward reactions. Equilibria are assumed to be much faster than any other reaction in the scheme.
  • ‡ indicates a transition state. It is considered part of the compound label. You can also use the easier-to-type # instead. That is, A#(w) is means the same thing as A‡(w).
  • (w) indicates a solvated context. It is considered part of the compound label. It is used to identify whether a concentration correction should be applied. The default is (g), which is understood as gas phase. The actual string is currently ignored: we could have written A(aq), A(l) or even A(dcm) instead, with the same effect. We might use solvent information in the future.
  • Paths to files are relative to the directory where the model file is located.
  • The order of the species in the $compounds block is not important. The same applies to the order of the reactions in the $scheme block.

Multiple reactions in a single line

We can get even closer to the original chemical notation, as overreact accepts multiple reactions in a single line. As such, the following is a $scheme block equivalent to the one above:

$scheme
 P_A(w) <- A‡(w) <- A(w) <=> B(w) -> B‡(w) -> P_B(w)
$end

Multiple logfiles for a single compound

You can provide multiple logfiles for a single compound. This will read the files one by one, updating the data of the previous one with the next. As such, data present on the first file only (e.g., harmonic frequencies) will be preserved, while data shared between files will be overridden by the subsequent files (e.g., electronic energies). This way overreact allows for mixed levels of theory in a very simple way:

$compounds
$compounds
 AcOH(g):  // acetic acid in gas phase
  logfile=UM06-2X/6-311++G(d,p)/acetic_acid.out
  logfile=DLPNO-CCSD(T)/cc-pVTZ/acetic_acid.out 
$end

Extra symmetries

You can provide extra information about the symmetry of a compound to overreact with the symmetry keyword. This is useful in cases such as extra degrees of freedom in weakly-bound complexes or unusually degenerate reaction paths (e.g., a nucleophile being able to attack from both faces of a functional group).

$compounds
 H3CHCl‡:
  logfile=H3CHCl‡.out
  symmetry=4
$end

Observe that this value will multiply the symmetry number found by overreact. You can use floating-point numbers to express fractions too!

Some illustrative examples

  1. A simple model for the synthesis of ammonia:
$scheme
 // Synthesis of ammonia (notice how flexible the DSL is)
 3 * H2(g) + N2(g) -> TS#(g) -> 2 * NH3(g)

$compounds
 // Paths to the files for the species (notice $end is optional)
 H2(g):  h2.out
 N2(g):  n2.out
 TS#(g): ts.out
 NH3(g): nh3.out
  1. A simple Michaelis-Menten-like scheme (with competitive inhibition):
$scheme
 // A simple Michaelis-Menten-like scheme
 C(aq) + S(aq) <=> CS(aq) -> CS‡(aq) -> C(aq) + P(aq)  // C(aq) is the catalyst

 // The inactivation of the catalyst is modeled as competitive inhibition
 C(aq) + I(aq) <=> CI(aq)
$end

$compounds
 C(aq):   c.out
 S(aq):   s.out
 CS(aq):  cs.out
 CS‡(aq): cs_ts.out
 P(aq):   p.out

 // Inactivation
 I(aq):   i.out
 CI(aq):  ci.out
$end