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.

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:

P0: (v3.90 and later) "Phase? (1: condensed; 0: gas)" is used to define the main phase of the simulated reaction system. Enter "0" for this parameter to simulate gas-phase reactions (including those in aerosols), or "1" to simulate systems mainly in the condensed phase.
P1-P3: pressure, temperature, and relative humidity in the specified units.
P4: "Total time" is the length of the period over which the model performs integration.
P5: "Number of times to output" is only for outputs, and irrelevant to time steps for integration, which are determined solely by the integrator and will typically be many more steps than used for display purposes.
P6: If you want the program to show the graphs of species time-evolutions automatically after the model run, enter "1" for the parameter "Plot outputs? (1: yes; 0: no)". Otherwise, enter "0". If you are doing many runs of the same case, it is useful to turn P6 to 0 after the first run, to avoid cluttering from many copies of the same graph.
P7: If you want to use the pre-loaded example (NOx-O3 photostationary state) in Steps 2-3, enter "1" for the parameter "Load example? (1: yes; 0: no)". Otherwise, enter "0".
P8: If you want to avoid most abundant GAS-PHASE species (>100 ppm, e.g., N2, O2, H2O in most applications) in the results plot, enter "0" for "Plot major species? (1: yes; 0: no)". Otherwise, enter "1". (v3.90 and later) This parameter cannot be set to "1" if the simulated system is set to be in the condensed-phase.
P9: "Max number of reactions" is the number of lines in the table "Reaction Mechanism Input", where you enter the reactions of your mechanism. It is NOT the actual number of your system’s reactions. "Max number of reactions" must be no less than the actual number of reactions PLUS ONE.
P10: "Error tolerance (typically in molec cm-3)" defines the absolute error tolerance of the species concentrations. The default value (10000) thus limits errors in species concentrations within 10000 molecules cm-3 if molecules cm-3 is adopted as concentration unit. When running cases in which some important species have lower concentrations (e.g. O(1D), O(3P), radon atoms) this parameter needs to be set to a lower number.
P11: cochaIf you want to enter rate coefficients directly rather than kinetic parameters in Step 2, enter "1" for the parameter "Simple kinetic parameters? (1: yes; 0: no)". Otherwise, enter "0".
P12: If you want to use a "translation table" to set up time-dependence waves in Step 4, enter "1" for the parameter "Use translation table? (1: yes; 0: no)". Otherwise, enter "0".
P13: If you want to enable the real-time T & P change during integration, enter "1" for the parameter "Real-time T & P change? (1: yes; 0: no)". Otherwise, enter "0".
P14: (v3.70 and later) If partitioning processes between the gas and other phases are not involved, enter "0" for the parameter "Do partitioning calculations? (0: no; 1: using prescribed CS & OA; 2: calculating real-time CS & OA; (v4.12 and later) 3: gas-wall only)". Otherwise, enter "1" if condensational sink and organic aerosol concentration can be prescribed, "2" if they need to be calculated from particle-phase species concentrations during integration, (v4.12 and later) or “3” if only gas-wall partitioning calculations are needed (no gas-aerosol partitioning).

"Simple kinetic parameters? (1: yes; 0: no)" and "Do partitioning calculations? (0: no; 1: using prescribed CS & OA; 2: calculating real-time CS & OA; 3: gas-wall only)" cannot be set to nonzero values at the same time, as partitioning calculations will use parameters entered in the full-format kinetic parameter table.

P15: (v4.07 and later) If you are using the oxidation flow reactor mechanism/case, enter "1" for the parameter "Special case? (0: no; 1: OFR)" to activate the special treatments necessary for this case. Otherwise, enter "0".
P16: (v4.19 and later) If you want to limit the maximal time step the differential equation solver will use to 1/10 of the output time step (see Step 4) during the integration, enter "1" for the parameter "Smaller integration time step? (0: no; 1: yes)". Otherwise, enter "0". Activation of smaller integration time steps can avoid false integration results obtained by the solver for cases where species have no reactive fluxes during most of a simulation but have substantial reactive fluxes during one or a few short periods. In this situation, if the integration time step is not limited, the solver may use very large time steps for mostly trivial species and miss the short period(s) with non-zero reactive fluxes (none of the times selected for integration evaluations are within the periods with non-zero reactive fluxes).

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:

Species names can be composed of letters ("a"-"z" and "A"-"Z"), numbers ("0"-"9"), and underscore ("_").

Example: you may use "O3P" to represent the species O(3P), as parentheses are not allowed.

The first character of a species name cannot be a number.
Maximum length of species names is 30 characters.
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.
Product stoichiometric coefficients must be non-negative and can be fractional.
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.

Examples:

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.
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.
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:

"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.
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.
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.
To specify a dilution, just enter a valid name for dilution into the "Reactant_1" column, leave all other columns as blank.
(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:

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.
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.
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.
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.

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.
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)).
f0 and g are parameters related to rate coefficient uncertainty and not used in this version.
“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”.

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:

Particle-phase species names start with lowercase “p_” (e.g., “p_IEPOX” and “p_C10H18O4”), while those starting with uppercase “P_” will be considered as normal species.
(v4.11 and later) Names of species on the wall start with “w_” (e.g., “w_SVOC”), while those starting with “W_” will be considered as normal species.
To specify condensations and evaporations, Reactant_2, Product_2, and Product_3 must be LEFT AS BLANK.

[A valid normal species name] -> p_[the same name] is the input format of condensation onto particles (e.g., C10H18O4 -> p_C10H18O4), while C10H18O4 -> p_C10H20O5 will be considered as a normal reaction.
Similarly, p_[a valid normal species name] -> [the same name] is the input format of evaporations from particles.
(v4.11 and later) [A valid normal species name] -> w_[the same name] and w_[a valid normal species name] -> [the same name] (e.g., C10H18O2 -> w_C10H18O2 and w_C10H18O2 -> C10H18O2) are the input formats of condensations onto walls and evaporation from walls, respectively.

Rate coefficients of condensation and evaporation are calculated in a DIFFERENT manner than for normal reactions shown above. A_Ainf and E_Einf are used to enter some THERMODYNAMIC (not kinetic) parameters for condensation and evaporation.

Saturated vapor concentration at 298 K (C*(298 K), in μg m-3) is entered in A_Ainf for both condensation and evaporation.
Enthalpy of vaporization divided by the ideal gas constant (ΔHvap/R, in K) is entered in E_Einf for evaporation.
Using these parameters, the program will calculate REAL-TIME condensation and evaporation rate coefficients during integration. Rate coefficients in the wave “KK” for gas-particle partitioning processes are calculated as for normal reactions, will NOT be used in integration, and should be disregarded.
(v4.11 and later) For gas-wall partitioning, in addition to C*(298 K) and ΔHvap/R inputs, condensation rate constants should be entered in n_ninf. Even for evaporation from walls, corresponding CONDENSATION rate constants should still be entered in n_ninf, as both condensation and evaporation rate constants will be calculated during integration if gas-particle partitioning is activated (v4.12 and later) or during mechanism compilation if only gas-wall partitioning is activated. (v4.12 and later) If these rate constants are calculated during mechanism compilation, their values WILL be assigned to KK and used in integration.

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):

Condensational sink and organic aerosol concentration are read and possibly interpolated from the corresponding time-dependence waves.
Note that prescribed condensational sinks are values at 298 K and they are proportional to the square root of thermodynamic temperature. Real-time condensational sinks are calculated from real-time temperature and serve as the rate coefficient of all condensations.
Evaporation rate coefficient is calculated as the equilibrium constant (saturated vapor concentration) divided by the reverse reaction (condensation) rate coefficient. Saturated vapor concentration at real-time temperatures is given by Clausius-Claperyon equation.
See formulae in “5. SOA Modeling” at http://tinyurl.com/ac-cheat2.
(v4.11 and later) In this option, gas-wall partitioning is also activated and treated in a real-time way in integration as for gas-particle partitioning. Gas-wall partitioning rate constants are calculated according to Liu et al. Comm. Chem. 2019.

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

Organic aerosol concentration is calculated as the sum of all particle-phase species concentrations and converted into μg m-3 (using the average organic aerosol molar mass, defined as a constant in the code).
Condensational sink is calculated using Fuchs-Sutugin corrections under the assumption of unity mass accommodation coefficient, monodisperse aerosols with a diameter of 150 nm (defined as a constant in the code) and a density of 1.25 g cm-3 (defined as a constant in the code), and a condensable-gas diffusion coefficient of 6x10-6 m2 s-1 (defined as a constant in the code and corresponding to a molar mass of ~250 g/mol).
Knudsen number for Fuchs-Sutugin corrections is calculated from air mean free path (68 nm at STP, defined as a constant in the code) and particle diameter by taking the changes in T, P, and gas molar mass (air: 29 g/mol; condensable gas: 250 g/mol; both defined as constants in the code) into account.
For more details, see “5. SOA Modeling” at http://tinyurl.com/ac-cheat2 and Palm et al. ACP 2016.
The values of all quantities defined as constants in the code can be changed by modifying the constant definition at the beginning of the code to adapt to different types of aerosols.
An initial/background organic aerosol concentration is NECESSARY to allow the simulation to proceed, since a zero organic aerosol concentration (i.e., no condensational sink) cannot condense any gas, which halts the integration. There are simple ways to specify a background organic aerosol concentration: for example, adding a reaction p_background -> p_background at any rate coefficient or p_background -> [any species] at a rate coefficient of 0.
(v4.11 and later) In this option, gas-wall partitioning is also activated and treated in a real-time way in integration as for gas-particle partitioning. Gas-wall partitioning rate constants are calculated according to Liu et al. Comm. Chem. 2019.

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

As no aerosol is involved, no real-time treatment is needed for partitioning rate constants. Instead, they are calculated during mechanism compilation and assigned to KK (see Step 2) according to Liu et al. Comm. Chem. 2019.

(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.

Plot_Balance:

Same functionality as Step 6.

Mechanism_Export:

This functionality exports the mechanism currently IN USE. This may NOT be the same as what you entered into the “Reaction Mechanism Input”. It saves all reactant and product name waves and all kinetic parameter waves, as well as the “Notes” wave as an Igor text (.itx) data file.

Mechanism_Import:

This functionality imports a mechanism from an Igor text file to the “Reaction Mechanism Input” table. Before proceeding with calculations, you need to put the imported mechanism into effect by clicking “Compile Mechanism”.

(v3.93 and later) Export_Case:

This functionality exports all inputs before the model run (Step 5), including key parameters IN USE, mechanism IN USE, initial concentration and dilution air composition inputs, output time wave (CalTime), and all scaling factors. All exported waves are saved as an Igor text data file. (v4.05 and later) The KinSim version number is also saved in the case file.

(v3.93 and later) Load_Case:

This functionality imports inputs of a whole model case (with the same format exported by “Export_Case”) from an Igor text file. If the import is successful, all existing inputs will be overwritten, Steps 1–4 will be automatically passed, and the “Run Model & Plot Results” button (Step 5) will be directly enabled. (v4.14 and later) If the case version number is newer than that of the KinSim code, users will be notified of potential compatibility issues.

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.

------------------------------------------------------