Published using Google Docs
KinSim General Usage
Updated automatically every 5 minutes

Instructions for KinSim

Shortcut to this page: 

Last updated by Zhe Peng and Jose-Luis Jimenez, 2-March-2023

Applies to v. 3.60 and later.

Other useful links:

Table of Contents

Getting Started        1

Step 1: Key Parameters        4

Step 2: Reaction Mechanism        7

2.1. Basic Usage        7

2.2. Using Complex Kinetic Parameters        9

2.3. Using Gas-Particle Partitioning        10

Step 3: Initial Conditions        12

3.1. Basic Usage        12

3.2. Cases Using Dilution, Emission, or Condensed Phase        13

Step 4: Time-Dependent Information (Optional)        14

4.1. Basic Usage        14

4.2. Using the Translation Table for Time Dependencies        15

Step 5: Running the Model        15

5.1. Basic Usage        15

5.2. Cases with Gas-Particle Partitioning        16

5.3. Cases with Destruction reactions        17

Step 6: Plotting the Balance of a Species        18

Options in the “KinSim” menu        18

KinSim FAQ        20

Getting Started

KinSim is a user-friendly interactive kinetic simulator mainly used for physical and environmental chemistry research and teaching. This manual follows the steps needed to run a case, and provides instructions for key parameters and options. We recommend going through this manual and/or the intro YouTube video as you perform the steps yourself.

KinSim runs within the Igor Pro environment. Igor is a scientific programming and graphing software, similar to Matlab, IDL in many aspects. If you don’t have a copy of Igor Pro, you can download a fully-functional 30-day demo version from this link.

Download the latest version of the KinSim code from the free GitLab repository.

Open a new Igor experiment. Load the KinSim IPF with File → Open → Procedure, and then select the KinSim IPF in your computer. Most users will never have to look at the code. Advanced users can modify the code as needed for their purposes.


To proceed, you need to generate the control panel by selecting "Show_KinSim_Panel" in the KinSim menu. Although using this method is not necessary, it is strongly recommended.

You will be asked to accept the user agreement below. This is just a standard legal protection, and the details are not relevant to most users.

After you accept, the code will show the following dialog and then create the panel:


At this point the code will ask you to SAVE THE FILE AS A NEW EXPERIMENT (PXP). Please do, as if you don't, multiple errors will occur!

The KinSim panel will then appear, as shown below. It has a clear linear structure. In general, to run the model, you just need to click buttons on the control panel in order. If you modify the information you entered in the previous steps, you need to go back and click all the buttons. Do not skip buttons or errors may occur.


Once the control panel is opened, DO NOT CLOSE IT. If you close and reopen it, you will need to redo every step to run the model. If it is hidden or behind other windows, you may use “Show_KinSim_Panel” in the KinSim menu to bring the panel to the front.

If you hit “Step 0”, this file will open. We prefer to keep the help file online, so that users always access the most updated version (compared to the help file being embedded within KinSim). If you are going to work somewhere without internet, you will want to download this help file while you still have internet.


In Steps 1 and 2, after entering information into the tables, NEVER FORGET TO CLICK "Input Parameters into Model" and "Compile Mechanism" BUTTONs to put what you entered into effect. Otherwise, the program DOES NOT consider what you entered and OVERWRITES what you entered by what was previously in use by the model when you click one of the latter buttons.

Step 1: Key Parameters


The key parameter table controls important details about what and how cases are run. You can edit the table within the panel, using the scroll bar to the right in this view:

You can also hit the “Pop the Table” button, which will produce a stand-alone version of the table. Changing a parameter in either format will work. As of v. 4.21 there are 17 key parameters (numbered 0-16 per Igor indexing convention), shown below. After making any changes, you have to hit the “Input Parameters into Model” button, or any changes will be lost.

Description of parameters:


After entering key parameters, CLICK the "Input Parameters into Model" BUTTON. What you entered is NOT taken into account by the program UNTIL you click this button. If what you entered is validated by the program after you click that button, the "Reaction Mechanism Input" table will be created.


Step 2: Reaction Mechanism

2.1. Basic Usage


General rules in entering species names and stoichiometric coefficients for products into the "Reaction Mechanism Input" table:

  1. Species names can be composed of letters ("a"-"z" and "A"-"Z"), numbers ("0"-"9"), and underscore ("_").
  1. Example: you may use "O3P" to represent the species O(3P), as parentheses are not allowed.
  1. The first character of a species name cannot be a number.
  2. Maximum length of species names is 30 characters.
  3. If omitted, product stoichiometric coefficients are set to 1 by the program. If entered, they should be in the format of [stoichiometric coefficient]+A SINGLE SPACE+[product name]. Redundant space(s) will be regarded as a part of product name, which is thus invalid according to Rule 1.
  4. Product stoichiometric coefficients must be non-negative and can be fractional.
  5. If an entered product stoichiometric coefficient is 1, it will be automatically omitted after the program validates the mechanism input. If a ZERO (0) product stoichiometric coefficient is entered into a cell, the program will ignore that cell during the mechanism compilation and empty that cell after the mechanism compilation, whether the product name in that cell is valid or not.


Note that the gas-phase pressure-dependence term, "M", of pressure-dependent reactions does not explicitly appear in the KinSim mechanism, but is implicitly included in the rate coefficient expression.


  1. For NO+O3->NO2+O2, a pressure-independent reaction, what you enter into the "Reaction Mechanism Input" can be: Reactant_1: NO; Reactant_2: O3; Product_1: NO2; Product_2: O2. You should leave "Product_3" as blank.
  2. For NO2+NO3+M->N2O5+M, a pressure-dependent reaction, you need to enter: Reactant_1: NO2; Reactant_2: NO3; Product_1: N2O5. You should IGNORE "M" here and leave "Product_2" and "Product_3" as blank.
  3. For N2O5+M->NO2+NO3+M, the reverse reaction of the previous one and also pressure-dependent, enter: Reactant_1: N2O5; Product_1: NO2; Product_2: NO3. "Reactant_2" and "Product_3" should be left as blank. If you actually enter M into the reaction mechanism, the simulation will NOT perform correctly.


Photolysis reactions, emissions, dilutions, and (v4.02 and later) destructions should be specified by "species names" starting with "hv", "EMISSION", "DILUTION", and (v4.02 and later) "DESTRUCTION" respectively. Multiple photolysis, emissions, dilutions, destructions are allowed in the mechanism. You need to use special formats to include these processes. Examples:

  1. "hv1", "EMISSION_a", and "DILUTIONt" can specify the above-mentioned special process types, while "HV185", "emissionNO", and "Dilution_G" cannot. The latter ones are regarded as regular species by the program.
  2. For O3 photolysis producing O2 and O(3P), you should enter: Reactant_1: O3; Reactant_2: [a valid name for hv]; Product_1: O2; Product_2: O3P; Product_3: leave as blank.
  3. To express the emission of NO, enter a valid name for emission and "NO" into the "Reactant_1" and "Product_1" columns, respectively, and LEAVE THE "Reactant_2" COLUMN AS BLANK.
  4. To specify a dilution, just enter a valid name for dilution into the "Reactant_1" column, leave all other columns as blank.
  5. (v4.02 and later) To specify a destruction, enter a valid name for destruction and the name of a species that is destroyed in this process into the "Reactant_1" and "Reactant_2" columns, leave all product columns as blank.


For example, this is the default mechanism in KinSim, with the NOx-O3 photostationary state. Note that this uses the simple kinetic parameters. If you change this setting in the parameter table (P11), you can enter more complex kinetic expressions (see below).

As another example, the following mechanism specifies the radioactive decay of radon into polonium, together with an emission of radon into the box of 100 molec cm-3 s-1, and a dilution rate of 10-5 s-1.

2.2. Using Complex Kinetic Parameters

When the input of full kinetic parameter sets is selected, KinSim uses the same formalisms as in the latest JPL (2015) and IUPAC (2016) Kinetic Data Evaluations to express gas-phase rate coefficients. General notes:

  1. Rate coefficients of uni- and bimolecular reactions are in s-1 and cm3 molecule-1 s-1, respectively. Pressure-dependent termolecular reactions are treated as pseudo-second-order reactions during integration. Their rate coefficients are thus also in cm3 molecule-1 s-1 in KinSim. Concentrations are in units of molecules cm-3, and time is in s.
  2. The molecularity of pressure-dependent reactions is the number of reactants appearing in the "Reaction Mechanism Input" table PLUS ONE. Example: the pressure-dependent reaction entered as NO2+NO3->N2O5 is a TERMOLECULAR reaction.
  3. To express rate coefficients of pressure-independent reactions, only A_Ainf, E_Einf, and n_ninf are needed, and A0, E0, and n0 should be 0. If a reaction's A0, E0, and/or n0 are NON-ZERO, the program regards it as a PRESSURE-DEPENDENT reaction. For pressure-dependent reactions, A0, E0, and n0 determine the low-pressure limit, and A_Ainf, E_Einf, and n_ninf determine the high-pressure limit.
  4. Pressure-independent rate coefficients and high-/low-pressure limits are all calculated using the modified Arrhenius Equation:

                            k = A * (T/300)-n * exp(-E/T)

where T is temperature in K. Thus, for temperature-independent reactions, just use A_Ainf or both A_Ainf and A0.

  1. If POSITIVE values are inputted into Fc, the IUPAC formalism will be used to calculate pressure-dependent rate coefficients. Otherwise the JPL formalism will be used.
  2. If relevant, enter into A_Ainf J values (in s-1) as photolysis rate coefficients, absolute emission rates (in molecules cm-3 s-1) for emissions, dilution rates (in s-1) for dilutions, (v4.02 and later) ZEROTH-ORDER absolute destruction rates (in molecules cm-3 s-1) for destructions (in the integration, destructions will be turned off when concentrations of species that are destroyed in destructions are close to 0 (smaller than error tolerance)).
  3. f0 and g are parameters related to rate coefficient uncertainty and not used in this version.
  4. “Disabled” is an option for enabling/disabling reactions in the mechanism. Only if the value of an element of this text wave is “Y”, will the corresponding rate constant (in the KK wave) be set to 0 during the mechanism compilation; all other values entered (even a string “Yes”) will lead to the reaction being enabled and the “Disabled” wave element being set to “N”.
  1. Special expressions are applied to calculate the rate coefficients of 2 gas-phase reactions, i.e., OH+HNO3->H2O+NO3 and 2HO2->H2O2+O2. See the JPL (2015) database for more details.

(v3.90 and later) For condensed-phase rate coefficients, the parameters for the standard Arrhenius Equation can be entered in A_Ainf and E_Einf. The units of rate coefficients of zeroth- (emission), first- (unimolecular reaction, photolysis, and dilution), second-order (bimolecular reaction) processes are now mol L-1 s-1, s-1, and L mol-1 s-1, respectively.

When the simple format for rate-coefficient input is selected, there will be only one column (RateCoeff) for rate coefficient input. You just need to enter the rate coefficient for the corresponding reaction. For special processes and the use of “Disabled”, see Rules 6 and 8 for the full kinetic parameter input above, respectively.

After entering the reaction mechanism, CLICK the "Compile Mechanism" BUTTON. What you entered is NOT taken into account by the program UNTIL you click this button. After you click it, if the program validates the mechanism you entered, mechanism compilation will proceed. It may take a while for more complex mechanisms. After compilation, the wave "KK" should be populated in the table "Reaction Mechanism Input". The table "Species concentration" will be created. In this table, the wave "Names" should be populated with the names of all species that the model will integrate in time.

The wave "Names" includes the names of all species that appear in the mechanism you entered. The wave "KK" is the first order or equivalent second order reaction rate coefficients that the program finally uses to integrate the model.

2.3. Using Gas-Particle Partitioning

(v3.70 and later): WHEN PARTITIONING CALCULATIONS ARE ACTIVATED, follow the rules below to specify aerosol and (v4.11 and later) wall species and relevant processes:

WHEN PARTITIONING CALCULATIONS ARE NOT ACTIVATED, NONE of the above-mentioned rules for aerosol species and relevant processes APPLIES. All of those species and processes are treated as normal ones.


Step 3: Initial Conditions


3.1. Basic Usage

The waves "InitConc" (for initial concentrations), "InitMixingR" (for initial mixing ratios), "Constr" (for concentration constraining), “PlotSpecies” (for enabling/disabling plotting certain species in the output plot) are populated in the table "Species Concentration" when this table is created. The wave "InitConc" is the initial concentrations of species (in molecules cm-3) that the program finally uses to integrate the model. The recommended procedure is to edit “InitMixingR” and let the program change “InitConc”.


The wave “Constr” is used to specify if a species concentration is constrained in integration. Enter “Y” to completely constrain species concentrations (i.e., their variations are exclusively controlled by the corresponding time-dependent scaling factor waves, see Step 4). Enter “N” if species concentrations are not constrained at all (i.e., their variations are solely determined by the reactions involving these species during integration). “Constr” may also be set to “D”. This option makes species dilution-exempt (i.e., they cannot be diluted, but may still be affected by other reactions). Any strings other than these options entered in “Constr” will be regarded as “N” by the program. “Constr” is set to “N” by default except species names to declare special processes, whose default value is “Y” and MUST NOT be changed.

The wave “PlotSpecies” is used to specify if a species time series is plotted in the output. “Y” (default value) for an element of this wave will allow the corresponding species time series to be plotted if the species average concentration is no less than 100 ppm or plotting major species is not forbidden in the key parameter table. However, if plotting major species IS forbidden and a species has an average concentration above 100 ppm, even if its corresponding value in the wave “PlotSpecies” is “Y”, it will NOT be plotted. When “PlotSpecies” has “N” or other non-“Y” values (even “Yes”), corresponding species will not be plotted.

Once you hit the “Make Model Ready to Run” button, the values in the InitConc wave will be updated. Do NOT change these values by hand, as discussed above.


3.2. Cases Using Dilution, Emission, or Condensed Phase

For each dilution, two waves named “Comp_[species name for dilution]” and “Conc_[species name for dilution]”, respectively, are created in the “Species Concentration” table to specify the composition of each dilute air. “Comp_[species name for dilution]” can be entered in the same format as “InitMixingR”, while “Conc_[species name for dilution]” contains concentrations of species in dilute air used for integration.


For gas-phase (including aerosol) species, enter initial mixing ratios into the columns "InitMixingR" and “Comp_[species name for dilution]” in the table "Species Concentration". Allowed units are: %, ppth, ppm, ppb, ppt, ppq, and (v3.70 and later) ug/m3, ng/m3 for aerosol speices. “ug/m3” and “ng/m3”, apparently standing for μg m-3 and ng m-3, respectively, are recognized by the program rather than their corresponding standard forms for typing convenience. An average organic aerosol molar mass is needed for the conversion from μg m-3 or ng m-3 to molecules cm-3. This quantity is defined as a constant of 250 g/mol at the beginning of the code and can be changed by modifying the code. A space-separated number-unit pair is required for the inputs with units (v4.01 and later: input with no space before “%” is also allowed). A direct input of concentration without a unit is also allowed and will be considered as in molecules cm-3 by the program. An empty input will be regarded as zero concentration.

(v3.90 and later) For condensed-phase species, automatic unit conversion for mixing ratios is disabled and units such as %, ppm, ppt etc. are no longer allowed. A direct input of concentration is considered as in mol L-1 by the program.

If names to declare special processes (photolysis, emission, and dilution) exist in the species list, their "InitMixingR" are set to 1 by default. Although possible, it is strongly recommended to NOT MODIFY these values. Otherwise, you need to adjust J values, emission rates, and/or dilution rates accordingly.

In the “Comp_[species name for dilution]” wave(s), elements corresponding to constrained species, including those for special processes, are set to “N/A” by default. Although those values can be changed, this causes no effect on the calculation, as those species are constrained.


Step 4: Time-Dependent Information (Optional)


4.1. Basic Usage

If no constrained species is in the reaction list or all required time-dependence information on constrained species is available, this step is not necessary. However, if new constrained species are entered in the mechanism or more points in time-dependence waves are required, this step cannot be skipped.


After the click of the button “Make model ready to run”, if “Use translation table” is set to 0 (no), the Step 4 button can be clicked. Then the table "Time-Dependence of Constrained Species" will be created or brought to the front. The wave "CalTime" in this table shows the times when the outputs will be saved during integration. By default, it is linearly populated. Although not recommended, if necessary, you may modify it or replace it by an exponentially populated wave.

For example, in the default NOx-O3 example case the left default table will appear. The table in the right has been edited to zero the photolysis reaction (representing a dark situation) for the first 8 time steps of the solution:


Scaling factor waves in the table "Time-Dependence of Constrained Species" represent time-dependent RELATIVE photolysis rates, emission rates, dilution rates, and/or concentrations of constrained species, and, if real-time T & P change is enabled, RELATIVE pressure and RELATIVE (THERMODYNAMIC) temperature. (v4.15 or later) the scaling factors for T and P at t =0 should be 1, or a warning will be issued when you click the Step 5 button. (v3.70 and later) When "Do partitioning calculations?" is set to 1 (using prescribed CS & OA), the waves “CS (s-1)”, and “COA (ug m-3)” will also be shown in this table. However, they are time series of the ABSOLUTE values of condensational sink (at 298 K) and organic aerosol concentration, but not those of relative values. These scaling factor waves, together with “CS (s-1)”, and “COA (ug m-3)”, are interpolated if values at times in between two adjacent points of “CalTime” are required during integration.

4.2. Using the Translation Table for Time Dependencies

If “Use translation table” is set to 1 (yes), “Translation Table for Time-Dependences of Constrained Species” will be prompted after the click of the button “Make model ready to run”. The structure of the table and the meaning of the columns are the same as the table "Time-Dependence of Constrained Species". However, the translation table is inputted in a stepwise manner. Inputs at only a few times in this table are needed to construct the corresponding time-dependence waves in the table "Time-Dependence of Constrained Species". After the click of the Step 4 button, time-dependences at times without an input will be assigned i) by interpolation if they are located between two times with inputs or ii) to the first/last inputted value if no times before/after them have an inputted value. Note that the translation table is only to aid the construction of time-dependence waves and only the waves in the table "Time-Dependence of Constrained Species" will be used in integration.

Step 5: Running the Model

5.1. Basic Usage

After the model run, each species has a concentration time-evolution wave under its own name. If "Plot outputs?" is set to 1 (yes), concentration evolutions will be plotted vs. the time wave "CalTime" in a single graph. If “Plot major species?” is set to 0 (no), species with a mixing ratio larger than 100 ppm will not be plotted. Also, if a species has a non-“Y” value in the wave “PlotSpecies”, it will not be plotted. If names for special processes (photolysis, emission, and dilution) exist in the species name list and/or if T & P and/or CS and COA (v3.70 and later) time series are involved in integration, they will be plotted on the right axis and in the upper part of the plot.

For example after running the default NOx-O3 photostationary state example, the following graph will appear:

5.2. Cases with Gas-Particle Partitioning

(v3.70 and later): When "Do partitioning calculations?" is set to 1 (using prescribed CS & OA):

When "Do partitioning calculations?" is set to 2 (calculating real-time CS & OA):

When "Do partitioning calculations?" is set to 3 (gas-wall partitioning calculations only):

(v3.70 and later) Note that when "Do partitioning calculations?" is set to 2 (calculating real-time CS & OA), CS is not plotted, for it is proportional to COA and their relative time series curves will always completely overlap under this option. (v4.15 and later) If "Real-time T & P change?" is set to 1, the time series of the air number density corresponding to the T & P change will also be plotted in the upper part of the plot.

5.3. Cases with Destruction reactions

(v4.02 and later): While the default integration method is backward differential formula, 5th-order Runge-Kutta method is used for the integration of systems containing destruction processes for better system stability. Note that Runge-Kutta may be much slower than backward differential formula for stiff systems. If the system both contains destruction(s) and is stiff, please refer to the Igor Pro help file for IntegrateODE for more information about the integration method options.

Step 6: Plotting the Balance of a Species

This is an optional step after the integration is done. To execute it, you need to enter the species whose balance you want to plot. After execution, the rates of reactions producing and consuming this species specified in the mechanism input table (v4.15 and later) and, if "Real-time T & P change?" is on, the rate of a special (unspecified) “dilution” process that accounts for the air number density variations due to the T & P change), as well as its total rate will be plotted vs. the time wave “CalTime” in a single graph. This species’ concentration time-evolution will be plotted on the right axis and in the upper part of the plot.

For example, the balance of NO2 for the default example will show the following plot:

Options in the “KinSim” menu

The following items appear in the Igor KinSim menu, a description of each item is below.

KinSim FAQ

We summarize frequently asked questions by users here in hope to help other users who have similar questions.

Q: What is the difference between files with ".pxp" and ".itx" extensions?

PXP means packed experiment file. It is an Igor binary file, which may contain code, data (waves and variables), graphs, panels, etc. It can only be opened with Igor.

ITX means Igor text file. It is a text file, and it can be opened with any text editor (e.g. Notepad). It typically contains data, e.g. of a chemical mechanism or other information.


Q: Is it possible to delete one or more reactions from a reaction mechanism input file? And adding reactions?

A: You can delete reactions, but it is easier to just disable them, by changing the value on the disabled column from N to Y.

You can also add reactions, by just typing the reactants, products, and rate coefficients on the next empty line in the mechanism.


Q: I put D + D -> E in the mechanism and, when compiling it, I got a duplicate name error “** Make gave error: name already exists as a function”. Why?

A: “E” is an Igor built-in function (for Euler’s number), so a duplicate name error is reported. We recommend NOT using single letters as species names, as many of them (e.g., e/E, i/I, p/P, and x/X) are Igor built-in function names or keywords.


Q: I put 2 A1 + A2 -> A3 in the mechanism and, when compiling it, I was told that “The first character of Reactant_1[x] (“2 A1”) cannot be a number.” Why?

A: KinSim currently only supports stoichiometric input for products, but not for reactants. Reactant names starting with a number are considered invalid by KinSim. This implies that up to 2 molecules of reactants are allowed in the reactions entered in KinSim. It is in line with the common chemical sense that elementary reactions involving 3 or more molecules (except pressure-dependent ones involving bath gas, which KinSim can implicitly handle) are extremely rare. Third- or higher-order reactions that make chemical sense are not elementary and can be divided into several unimolecular and/or bimolecular elementary reactions to conform to the mechanism input rules of KinSim.

For example,

2 A1 + A2 -> A3,        k

can be divided into the following reactions:

2 A1 -> A4,                k1

A4 -> 2 A1,                k-1

A2 + A4 -> A3,        k2

where k-1 >> k1 >> k2 and k = k1*k2/k-1.