File Formats

The usage of pykinetic through the provided command line apps requires various text files following a specific formatting. The "Compounds" file and the "Reactions" file are always required.

Compounds File

In this file the user specifies the compounds as well as their energies.

General format:

Each line of the compounds file follows the format:

# Line that starts with "#" is considered as comment and ignored
compound_label    energy    unit    scan

The label and the energy columns are always required.
The unit may be specified as command line argument.
The "scan" keyword allows to mark a certain compound to produce several models while changing the energy of everything that is marked by the scan keyword.
The number of empty spaces or tabs is not strict as long as all the columns are separated by at least one (tab or empty space).

Compound label rules:

The compound's label is relatively free. The only exceptions are those that include any symbol used in the reactions file to specify the reactions:

must not have emtpy spaces within the label.
"!" symbol must not be used.
"+" may be included as long as it is not surrounded by empty spaces or tabs.
Any reaction symbol surrounded by empty spaces or tabs.

Accepted Labels	Non-Valid Labels
[H2O···H2O]	[H2O H2O]
H2O+H2O	H2O + H2O
[LCu(OTf)2]Na+	[LCu(OTf)2]Na +
Enz=>inactive	Enz => inactive
花火	!

Compounds file example:

A                0.0 kcal/mol
B                0.0 kcal/mol
Cat              0.0 kcal/mol
[A···B]          2.0 kcal/mol
[A···B···Cat]    4.0 kcal/mol
[C···Cat]        3.0 kcal/mol
C               -2.0 kcal/mol

Reactions File

In this file the user specifies the reactions and the Transition States (TS) or a manner of calculating the energy of the associated TS.

General format:

# Line that starts with "#" is considered as comment and ignored
reactants    symbol    products    !energy    unit    scan
reactants2   symbol    products2   !TSLabel
reactants3   symbol    products3   !TSLabel
TSLabel    energy    unit    scan

The first three examples after the comment correspond to the format of lines that indicate a reaction. The last one corresponds to the specification of a transition state, that can be either shared bewteen different reactions or just specified at the end for simplicity.

Symbols:

Symbol	Description
=>	Forward reaction
<=	Reverse reaction (When the --relative flag is specified it uses as reference the left side).
<=>	Forward and reverse reaction sharing the same TS.
<d>	Forward and reverse "diffusion" reaction. Both share the TS. The specified energy is used as: G(specified) = G(TS) - max(G(reactants),G(products))

All symbols must be surrounded by empty spaces or tabs and should be used only once per reaction.

Reversible reactions are automatically converted into 2 reactions, the forward and the reverse reactions sharing the same TS. This is only important when setting up scans since:

A  => B  !2.0 scan
B  => A  !2.0

Does not behave as:

A <=> B !2.0 scan

However, the following reactions do have the same behaviour:

A  => B  !TS1
B  => A  !TS1
TS1  2.0  scan

Reactions file example:

# Adduct Formation
 A         +    B     <d>    [A···B]                !2.0 kcal/mol
[A···B]    +    Cat   <d>    [A···B···Cat]          !2.0 kcal/mol

# Uncatalyzed reaction upon collision
 A         +    B     <=>     C                     !TS1

# Uncatalyzed reaction with preformation of adduct
[A···B]               <=>     C                     !TS1

# Catalyzed reaction
[A···B···Cat]         <=>    [C···Cat]              !10.0 kcal/mol scan

# Product Diffusion
[C···Cat]             <d>     C      +     Cat      !2.0 kcal/mol

TS1     20.0 kcal/mol    scan

Note

The --relative of pykinetic-model.py and pykinetic-scan.py will assume that the energies specified are relative to the energy of the reactants. In this example, enabling the --relative flag will result in the catalyzed reaction having direct barrier of 10 kcal/mol (assuming a scan value of 0 kcal/mol). Not enabling the --relative flag will result in a barrier of 10.0 - E([A···B···Cat]) kcal/mol, with the Compounds file example it would result in a barrier of 6.0 kcal/mol.

Simulation Parameters File

This file is optional and is generally useful when you already have a model and are going to generate different versions of the model and you don not want to keep the tedious task of re-writing these parameters onto the generated file.

Example file:

dt          1E-12
tfin        1E+02
trep        0.1
concentrations    0,1.0 ; 1,1.0 ; 2,0.1

The order may be changed.
Not all the parameters need to be specified in this file.
dt is the solver timestep for calculating the solution. Some solvers require it and others no.
trep corresponds to the time step for reporting the concentrations of all the species.
tfin is the final time. Both number notations, 1E+02 and 100, are valid.
dt, trep and tfin are specified in seconds.
In the concentrations keyword only the non-zero initial concentrations in M need to be included. In this example, the compounds 0 and 1 start with 1M and compound 2 with 0.1 M. (The number that corresponds to each compound corresponds to the order in which they appear at the compounds file, starting from 0)