Instructions for KinSim
Shortcut to this page: http://tinyurl.com/kinsim-help
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
2.2. Using Complex Kinetic Parameters 9
2.3. Using Gas-Particle Partitioning 10
3.2. Cases Using Dilution, Emission, or Condensed Phase 13
Step 4: Time-Dependent Information (Optional) 14
4.2. Using the Translation Table for Time Dependencies 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 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.
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.
General rules in entering species names and stoichiometric coefficients for products into the "Reaction Mechanism Input" table:
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.
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:
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.
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:
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.
(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.
(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.
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.
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.
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.
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.
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:
(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.
(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.
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:
The following items appear in the Igor KinSim menu, a description of each item is below.
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.
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.