
immi  mmmi mmmi mmi    mm mmmmmmmmmi immmmmmmmmi   ,mmm_ I mmm     mm   gmms . 
 @[   iP    @[  ]YW.   ]  P  ]@[   [  '@@      ` ,Z!    V[ ]@      ]  ,A    V[ 
 @[  gf     @[  ]'@b   ]     ]@[       @@       ]@`      ! ]@      ]  W      ! 
 @[ gf      @[  ] Y@.  ]     ]@[       @@       W@         ]@      ]  MW.      
 @[d!       @[  ] !@W  ]     ]@[       @@   ,   @A         ]@      ]  !M@s_    
 @@b        @[  ]  ]@I ]     ]@[       @@mmmW   @[         ]@      ]    VM@W.  
 @PMm       @[  ]  '@W ]     ]@[       @@   '   @[         ]@      ]      ~M@m 
 @['MW.     @[  ]   V@I]     ]@[       @@       M@         ]@      ]        Y@I
 @[  M@.    @[  ]    M@]     ]@[       @@       ]@.        !@.     ]         @[
 @[   Y@.   @[  ]    ]@@     ]@[       @@        ]b     I`  MW     [  ]      @ 
,@b.  ,@W_ mmmi d_    M@    ,d@b.    ,g@@______I  V+___=/   '*+___/   !=c___/f 

          "The Kinetics Program Module for the Ultimate Lazy Scientist"


                 Kintecus (c) Copyright 1995,96 James C. Ianni.
                            All Rights Reserved.


License Statement

	This software is protected by both United States Copyright Law and
International Treaty provisions.  Therefore, all conditions pertaining to
other publications also apply to this software, with the following exceptions.
The licensee of this software may make archival copies of this software for
the sole purpose of backing up this software and protecting the licensee's
investment from loss.

	This shareware version of this software (the version which is not 
registered in the licensee's name) is released as "Shareware". As such, the 
user may also make copies of the software and relating documentation and 
distribute those copies freely as long as no changes are made to either the 
software or documentation and as long as no amount above the cost of producing 
the physical copy (not to exceed $7.50) is charged for the copy of the 
software and documentation, and the software must also be distributed with the 
relating documentation attached and the package must be distributed as a 
single package.

	If the user uses the software regularly, then that user is required 
to register directly with the owner of the Copyright, James C. Ianni. 
Registration includes a free update to the latest version of the software, 
free support (through E-mail) for one month or more (the extension of the time 
depends on the author).  Unregistered users do not get any support.

Warranty

	James C. Ianni specifically disclaims all warranties, expressed or 
implied, including but not limited to implied warranties of merchantability 
and fitness for a particular purpose, and the program license granted herein 
in particular and without limiting operation of the program license with 
respect to any particular application, use or purpose.  In no event shall 
James C. Ianni or employees or agents of James C. Ianni be liable for any loss 
of profit or any other commercial damage, including, but not limited to, 
special, incidental, consequential or other damages.


[  Introduction  ]
=============================================================================

        Kintecus is a program to model the reactions of chemical, biological, 
nuclear and atmospheric processes using two input spreadsheet files: a 
reaction spreadsheet and a species description spreadsheet. Kintecus has been 
designed with ease of use in mind. Absolutely no compiling nor linking 
required.
 A quick overview of the main features: 

	1) the ability to model over 4,000 reactions (over 8,000 in the 
workstation versions) in less than 8 megabytes of RAM running in pure high 
speed 32-bit under DOS! Also, because of the incredible demand, Kintecus is 
NOW available for many popular workstations and supercomputers: Sun 
Sparcstations, IBM RISC/6000 series, Silicon Graphics, Cray YMP/J90's.

	2) Full output of normalized sensitivity coefficients selectable at 
any specified time or times. Normalized sensitivity coefficients are used in 
accurate mechanism reduction, determining which reactions are the main sources 
and sinks (network analysis) and which also shows which reactions require 
accurate rate constants and which ones can have essentially guessed rate 
constants. 

	3) the ability to use concentration profiles of any wave pattern for 
any species or laser profile for any hv. This is very useful for studying very 
complicated external perturbation affects or using your own experimentally 
recorded concentration profile in your model.

	4) a powerful parser with mass & charge balance checker for those 
reactions that the OCR or the graduate student "supposedly" entered in 
correctly but the model is yielding incorrect results or is divergent. Do you 
know a kinetics program that can completely parse and check for mass/charge 
balance on a reaction like this:

#
# Rate Constants ,  REACTIONS:
#
1.234e-20        , CH3(((NO2)3(CO)93)3 (CH2)9)+23.30H2O+ + Co2 = A--- + B++++ 

Or how about this:

#
# Rate Constants ,  REACTIONS:
#
5.043e+20        , 3.43234 (CH4(N(PO342)43(CH3)3)34)(Os(S7)8)34++++ + 199.432 
X++++  5CH5+ ==>
5.434Some_Really_Funky_Enzyme_Name_But_I_Just_don't_Remember_IT_This_Name_Is_J
ust_Too_Long_It_Seems_to_go_on_and_on_like_that_a n n o y i n g Rabbit???---- 
+ 8 HCl + HCO3-

Kintecus is able to accurately check the above reaction for mass and charge 
balance because you can create an optional name file containing common names 
for species and then their mass representation. This smart mass balance can be 
used for biological and nuclear reactions! Also duplicate reaction and species 
checking.

	5) As you can see in the above reaction, *FRACTIONAL* coefficients 
for species! Now you can finally model that last step in the Oregonator or 
crunch 100 elementary reaction steps in one reaction step!

	6) Quickly and easily hold one or more concentrations of any species 
at a constant level just by typing the value in the field of the species.

	7) Built in support for photochemical reactions involving hv and 
Loseschmidt's number.

	8) Model reactions from femtoseconds to years! A special switch in 
Kintecus allows it to output the concentration of the species that are 
displayed only if its concentration has changed significantly from its past 
values. This may seem like no big deal, but if you model reactions that last 
from days to years you can easily generate files that are dozens of megabytes 
in size or more. Such a file is nearly impossible or extremely time consuming 
to plot or print, but in Kintecus a special option turns a 100-multimeg file  
into a 100 kilobyte file without any loss in data!

	9) Automatic generation of the species spreadsheet file using the 
reaction spreadsheet file. Why waste time finding, entering and initializing 
all the different species in your kinetic scheme?

	10) The ability to do reactions in a continuous stirred tank reactor 
(CSTR) with multiple inlets and outlets. 

	11) A switch that computes all internal Jacobians analytically. This 
is very useful for simulating very large kinetic mechanisms (more than 1,000). 
Finite difference methods can cause underflow or overflow errors in 
approximately such large Jacobians during the simulation

	12) Support for Excel and Lotus spreadsheet programs.





[  Running Kintecus  ]
=============================================================================

 	You will need a '386 or higher PC running DOS 3.3 or higher with 8 
megabytes of RAM. The file DOSXMSF.EXE must be in the same directory as 
Kintecus. (NOTE to workstation users: the explanation below on using Kintecus  
also applies to operation on all workstations except for setting program 
switches on the command line see below under Kintecus Switches section.) 
You can run Kintecus as:
"Kintecus (any switches you may want to use) > view.txt". 
This will output any errors, warnings and information to the file view.txt 
which can be viewed with any text editor.
 	For your reactions, you must first create a spreadsheet file. Load up 
your favorite spreadsheet program. If you don't use a spreadsheet, it's 
recommended to use a text editor (such as MS-DOS's "EDIT" or OS/2's "qbasic 
/EDITOR" ) and use a comma to separate the fields in the spreadsheets. In the 
first column enter the reaction constants, and in the second column enter the 
reaction. If you start a line with, "#', or double quotes, ' " ', the line 
will be taken as a comment. End the reaction sheet with END + RETURN on one 
line. Use "==>' to represent yields and "=" to represent a reaction that can 
go forward and backward (with the backward step having a rate constant of 
one).
An example ( "|" and "-" represents the cell boundaries in the spreadsheet, 
you DON'T type these! )

#                    | 
------------------------------------------------------------------------------
# My first reaction..|
------------------------------------------------------------------------------
#                    |
------------------------------------------------------------------------------
1.754e-5             | CH3C00H + H2O = H3O+ + CH3COO-
------------------------------------------------------------------------------
 END                 |

When entering reactions do not use the following characters: $,` (the 
character under the ~ ), @ , | , the comma, TAB, semi-colon or the colon 
unless you are using a text editor in which case you can use the comma, semi-
colon or colon to separate fields in the spreadsheet, just be sure to pick one 
separator, do not randomly switch from the comma to the colon on the same 
line. You can name the reaction file anything you want and Kintecus will read 
it, but for now save the spreadsheet file as an ASCII (or plain text) file 
under the name, "MODEL.DAT". This is the default reaction filename Kintecus 
looks for. As a side note, anything after the END is ignored, so you can have 
equations entered below the "END" as you modify your model or place a # to 
comment one whole reaction line out of the model.

	Make sure the reaction text file (MODEL.DAT) and a parameter 
description file (PARM.DAT) are now in the same directory as Kintecus and run 
it with the following line: KINTECUS -c . This will automatically create the 
species spreadsheet file, ADDSPEC.TXT with all values and switches set to 0.0 
and "No" respectively. 

	Go back in your favorite spreadsheet program and load this file.  

# Species |Residence | Initial |Display |External| SSA ?| Constant File?
------------------------------------------------------------------------------
#         |Time      | Conc.   |Output  |        |      |   
------------------------------------------------------------------------------
#         |in CSTR(s)|         | (Y/N) ?| Conc.  |(Y/N) |(Filename/#/No)
------------------------------------------------------------------------------
CH3COOH   |  .0      |   .0    | No     |  .0    |  No  |     No
------------------------------------------------------------------------------
  H2O     |  .0      |   .0    | No     |  .0    |  No  |     No
------------------------------------------------------------------------------
  H3O+    |  .0      |   .0    | No     |  .0    |  No  |     No
------------------------------------------------------------------------------
CH3COO-   |  .0      |   .0    | No     |  .0    |  No  |     No
------------------------------------------------------------------------------
 END
  
Enter 1.0 and 55.56 in the initial concentration fields (Initial Conc.) for 
CH3COOH and H2O respectively. Also enter "Y" in all the display output fields, 
this allows you to view the concentration of the species at selected time 
intervals as the simulation runs. You can name the species description file 
anything you want and Kintecus will read it, but for now save the spreadsheet 
file as an ASCII (or plan text) file under the name, "SPECIES.DAT", be sure to 
save it in the same directory as Kintecus. That's it! Now run Kintecus. An 
output file containing the concentration profile of all the species that are 
being displayed are saved in this file. You can now view the concentration 
profile of all the displayed species by loading this file in your favorite 
spreadsheet program and plotting it!

If you wish to alter the time of the simulation. Load in the PARM.DAT file and 
where you see the line "Simulation Length", there are five fields: DAYS, 
HOURS, MINUTES, SECONDS, PICOSECONDS under that. If you want the simulation to 
run for one hour, just enter "1" below the Hours field and make sure there are 
zeroes in the other fields. For now, don't worry what the other fields are 
for.
















[  Advanced  ]
=============================================================================


// The Parameter Description Spreadsheet //
*******************************************

	Parameter Description SpreadSheet			
			
  Minimum  | Maximum   |X99  |Units (0/1/2)|X0
Integration|Integration|     |             |
  Time(s)  |  Time(s)  |     |             |
-----------+-----------+-----+-------------+-------
1.00E-10   |   10      | 0   |     0       | 0  
 				
 Temperature | Pressure | X0 | X0  | X0
     (K)     |   (kPa)  |    |     |    
-------------+----------+----+-----+------------
     298     |    101   | 0  |   0 |  0

 Simulation Length:				
       DAYS|Hours|Minutes|Seconds|PicoSeconds
-----------+-----+-------+-------+--------------
        0  |  0  |  10   |  0    |    0
	                                                     	
		
 hv(filename)|Sampling Interval (s)|Percent(%)|Accuracy|X9
-------------+---------------------+----------+--------+--
None1        |         1           |    1     |1.00E-08|0
				
        X10 | X98 | X12 | X13 | X43
---------------------------------------------------
	0      0    0      0     0
				
END							

	Most of the settings in the parameter description spreadsheet usually 
do not have to be changed, but it's a good idea to know what exactly each 
field is for.
 	It's obvious what should be entered in the Temperature and Pressure 
fields, just be sure the values for those two fields are in Kelvin and 
kiloPascals respectively. These two fields will be used to calculate 
Loseschmidt's Number, M.
	The length of the simulation is controlled by the DAYS, Hours, 
Minutes, Seconds and PicoSecond fields. This allows for easy setting of the 
total time of the simulation during a run from yearly events to femtosecond 
laser experiments. 
	The Units field allows you to use different concentration units 
during a run. Possible values and their respective concentration units in this 
field are:
0, moles/Liter (M); 1, molecules/cm^3 (can also be used as particles/cm^3); 
2, ppm (parts per million). 
	The hv(filename) and Sampling Interval(s) are used together and are 
mainly for the use of hv in your equations (i.e. M + hv ==> M+ + e- ). The 
hv(filename) can be one of three things: if None1 is entered then hv=0 always, 
if None2 then hv=1 always, if anything else then the field will hold the name 
of a file containing data that represents a profile for hv. The Sampling 
Interval holds the spacing in time (in seconds) between each data point. The 
number of data points in the filename and the sampling interval determine the 
total length of the hv profile. If the time of your run goes beyond the total 
computed time of the hv profile, then the data will repeat itself from the 
beginning of the profile (time 0).
	The Percent (%) field is used to limit the size of the output 
concentration file (whose default name is CONC.TXT) without causing 
distortion. Kintecus will only output the concentration of all the species 
only when one or more Displayed species (see below in the Species Description 
Sheet) has changed more than Percent*Previously_Outputted_Value. Through the 
author's personal experience, using 1% as a default doesn't distort the 
outputted concentration profile too much and keeps an okay file size. There is 
slight distortion at 20% but can drastically reduced the size of the 
concentration file. This field is extremely useful for cutting the size of 
models that run for simulated years. A value of 7% is good for knowing how 
high certain peaks in concentrations you might be interested in.  A value of 
0% will output all values.
 	The Minimum Integration Time, Maximum Integration Time and Accuracy 
fields determine how fast Kintecus can integrate your model and the error in 
the final concentrations.
	Accuracy determines how far out in the decimal place to keep the 
concentration accurately known and consequently any fine detail a 
concentration profile might have. So, a value of 1.0E-9 will keep the first 
nine digits of the integrated concentration accurately computed. The smaller 
you make the accuracy field the slower Kintecus runs your model. If you have a 
huge model, you may want to increase this to 1.0E-5 or larger. Of course, if 
you have really stiff reactions and Kintecus can't seem to integrate your 
model, you should decrease this field to 1.0e-10 or so. See the Errors.txt 
file for a further description.
	The Minimum Integration Time (in seconds) determines the starting 
delta-t to integrate your model. After the first integration, this will change 
and grow larger if your accuracy is large and/or the stiffness of your model 
is low (meaning a decrease in execution -time of the program) , or grow 
smaller if your accuracy is very small and/or the stiffness of your model is 
high (meaning an increase in execution time of the program). You should not 
have to change this! 
	The Maximum Integration Time has a few uses in Kintecus. If you are 
not using a concentration profile on any species (see below in the Species 
Description Sheet), then this field is only used to determine the minimum 
timing threshold which has to be exceeded before outputting the concentration 
of displayed species by default Kintecus will output at least 30 integration 
points. In this case a value of 1 to 10 seconds is fine for simulations 
lasting from 10 minutes to a few days respectively, but if you are doing 
simulation which only last a few nanoseconds, then a value of a few 
femtoseconds (1 x 10(-15) ) should suffice. If you only have some species 
loaded as a concentration profile (see below in the Species Description Sheet) 
then this will determine how often the data is retrieved from the 
concentration profile files. In this case, the Maximum Integration Time field 
should NOT be set to a time interval that is larger than a species that has 
the smallest time interval between consecutive concentration values in a 
concentration profile. Kintecus 1.2 or higher will automatically check and 
correct for this. Reducing the maximum integration time will most likely 
output more concentration values.
	

Kintecus will look for the Parameter Description SpreadSheet under PARM.DAT as 
the default filename. This can be overided see KINTECUS Switches Section 
setting below.

// The Species Description Spreadsheet //
*****************************************

Here is a detailed description of how exactly each field in the species 
description spreadsheet is used by Kintecus.

The fields in the Species Description Spreadsheet are:
								
Species | Residence Time    | Initial      | Display     | (cont' ===>)
        | in CSTR (s)       | Concentration| Output (Y/N)| 

External|  SSA ? |Constant File ?  |Optional Comment
Conc.   | (Y/N)  |(FileName/No/# ) |
.
.
.
.
END

The Species, Initial Concentration and Display Output fields are obvious in 
what they represent. The Species field holds the name of a species that will 
show up in a chemical reaction and can be up to 240 characters long. An 
important note is that the charge of the species is only computed for species 
name if a "+" or "-" is appended at the end of the name.
 	The Initial Concentration field holds the starting concentration of 
each species in the reaction.
	 The Display Output field can hold either a Yes or No ("Y" and "N" 
also work). If Yes the respective species' concentration will be stored in the 
default output file, "CONC.TXT", if no then the species' concentration will 
not be stored.
 	The Constant File field can hold one of three things: "No" ("N" 
works), a number such as 4.234E-4 (in which case that species will always have 
that concentration of 4.23E-4 ) or the name of a file that contains values in 
a special format. The format is that the very first line that contains the 
time spacing (in seconds) between each data point. The lines that follow  
contain the data. Please make sure the very last data point has a carriage 
return or enter! Kintecus will place the respective data point at the 
respective time of the simulation from the constant file into the respective 
species. If the time in the simulation goes beyond the time of the very last 
data point in the constant file, Kintecus will start over in the constant file 
using the very first data point and continue onward. If the very first line 
(the time spacing) has a minus sign in front of it, Kintecus will go through 
the entire data series once then automatically place the very last value in 
the datafile for the rest of the simulation time.






Examples:

In the Profile_A.TXT file contains these values:
43200
2
1

For a species that has the filename Profile_A.TXT in it's "CONSTANT FILE ?" 
field, Kintecus will load this concentration pulse step profile. Assuming 
Molar units, Kintecus will force the species to have a concentration of 2 
Molar until at 43201 seconds where then the species concentration will drop to 
1 Molar, at 86401 seconds the species will go back up to 2 Molar and this will 
repeat. Now, if the 43200 was -43200, then at time 86401 the concentration of 
the species will goto 1 and stay there for the entire simulation. If "-ADD" 
was appended to the file name (in this example "Profile_A.TXT-ADD" ), the 
species will NOT be a constant, but a variable with perturbations added to it 
during the simulation:

In the Profile_A.TXT file contains these values:
-500
0
0
1

When the simulation is running, the instant the time goes over 1000 seconds, 1 
Molar will be added to the species containing the "Profile_A.TXT-ADD" in the 
"Constant File ?" field, Kintecus will not perform any more perturbations to 
the respective species. Another example: Suppose one wished to add 2 Molar 
after 1000 seconds, then add 4 Molar after 1030 seconds, then REMOVE -3 Molar 
after 1034 seconds the Profile_A.txt file would look like this:

-1
(999 zeroes)
2
(29 zeroes)
4
0
0
0 
-3

As one can see, this is indeed a very powerful technique to study various 
perturbation methods to kinetic systems with the slightest of ease!
Of course, you can have very long perturbation files (upto 25,000 points for 
any species and 32,000 points for the hv file)!

	The Residence Time in CSTR and the External Concentration fields are 
used together for the modeling of Continuous Stirred Tank Reactors (CSTR) or 
any other process that contains well mixed, isothermal reactions with external 
flux in and flux out:


    | External     |
    | Concentration|
    | Tank         |
    \______________/
          |   | 
          | | | 
          | V |                     <--d-->
          |   |                     _______  
           \   \___________________/       \___________________
            \___In_Velocity________  CSTR   ____Out_Velocity___ 
                                   \_______/

	Naturally the External Concentration field does not contain the 
actual concentration of the external tank but the concentration that it will 
become once it is diluted in the CSTR before any reactions take place. A rough 
approximation of the residence time in a CSTR can be calculated as follows:
2 x d (the distance across the CSTR parallel to the in/out flow) / 
(In_Velocity+Out_Velocity). You can have different residence times for 
different species. This allows simulation of species that might interact more 
in the CSTR than other species (it's obvious that a few versions away when 
Kintecus is 3D using MiniCad/AutoCad with full mass/heat/viscous/sonic 
transport properties, that the ability to do chromatographic and mass spectrum 
simulations can be done.).

 	The SSA field stands for Steady-State Approximation and it is not 
used in this version. One might ask why allow a SSA for a species when the 
exact solution can be calculated? There are two reasons: One is political and 
the other for speed. Political in that even today there are scientists that 
blindly insist in using an SSA for their kinetics simulation, but it has been 
shown repeatedly [2,3] that doing SSA's without knowing the actual output can 
result in disastrous results. You can feed on these disastrous results by 
setting all the appropriate species to "Yes" in the SSA field and obtaining 
the exact results as your competitor this will show that all your conditions 
are exactly set-up like your competitor's. Now turn off the SSA's and re-run 
the simulation, if you obtain different results, you can now bash away that 
your competitor's conclusion is all wrong and you should get the grant money 
because you know what you are doing. The other reason mentioned to use SSA's 
is speed, but you should only use it if the very beginning of your exact 
solution matched the very beginning of the SSA, then the rest of the SSA 
should be correct in most cases. 
At the end of the species description spreadsheet make sure there is an END + 
carriage return.		 		
Kintecus will look for SPECIES.DAT at the default filename. This can be 
overided see KINTECUS Switches Section setting below.
		
// The Model Description Spreadsheet //
****************************************

Here is a detailed description of how exactly each field in the model 
description spreadsheet is used by Kintecus.

The fields in the Model Description Spreadsheet are:
								
# Reaction Constant	|Reaction	| Optional Comment
1.323E-13		|A+B==>C		| A made up reaction.

It's obvious what the Reaction constant field holds. The reaction field holds 
either a reversible (represented by a single "=" ) or an irreversible 
(represented by "==>" ) reaction. Although you can have only three reactants 
and three products per reaction line, you can represent the multiplicity of a 
species by using numerical coefficients such as 5A to represent A+A+A+A+A or 
98H2O or even 4.2343E-23H2O. Please be sure to use this convention to 
represent multiplicity of a species in a reaction, DO NOT ENTER A+A+A+A+A to 
represent 5A! Signs can be postfixed to a species such as Cl------- or H3O+ 
and even ylides and zwitterions such as C8H15P+- (which will have no overall 
charge.). All reactions are checked for mass and charge balance (which can be 
turned off).

At the end of the model description spreadsheet make sure there is an END + 
carriage return.	

Kintecus will look for MODEL.DAT as the default filename. This can be overided 
see KINTECUS Switches Section setting below.
	

// The Species Name Spreadsheet //
**********************************

This spreadsheet is optional. The main reason for this spreadsheet is to keep 
Kintecus checking for mass balance without typing long molecular, empirical or 
mass formulae in the reaction spreadsheet. The fields in this spreadsheet are:

Common Name   | Molecular/Empirical/Mass formula
H+            |  H3O

Common Name can contain any name upto 240 characters long. The 
Molecular/Empirical/Mass formula field must contain any valid molecular, 
empirical or mass formula such as
CH3CH2CH3 or CH3(CH2CH2O2)90000CH3 or Pu2U3Pr43 or C100000H200002.
The following characters are ignored if they are contained in the molecular, 
empirical or mass formula: ".", "=", "_", "*", "^", "&", "/", "\", "-", "+". 
An important note is that the charge of the species is only computed for the 
common name if a "+" or "-" is appended at the end and the charges are 
completely ignored if they appear in the molecular, empirical or mass 
formula.  
An example:

The reaction:
Enzyme_B + 5H2O ==> Enzyme_hydrate.

The SpecName.dat file:

#
# My nicknames for my own kinetics simulation
#
Enzyme_B  | C43H70N10S2
Enzyme_hydrate | C43H70N10S2(H2O)5
END

Kintecus will look for SPECNAME.DAT as the default filename. This can be 
overided see KINTECUS Switches Section setting below.




// Sensitivity Analysis //
**************************

	Kintecus can generate normalized sensitivity coefficients at any time 
or times during a simulation run. What the heck are normalized sensitivity 
coefficients (NSC) and why should I care? Well, first of all, normalized 
sensitivity coefficients are the partial derivatives of each species with 
respect to each reaction constant normalized by multiplying by 
Rate_Constant/Concentration_of_Species, or in other words a matrix with signed 
numbers which indicate the reactions that have the biggest influence on what 
species. By examining the matrix and sorting the largest NSC's by reactions 
for each species one can see that the large positive NSC's are the major 
sources and the large negative NSC's are the major sinks[10]. A reaction that 
has a very small NSC for a species indicates that reaction has almost no 
influence on the species no matter what the rate constant or the reaction's 
concentration of reactant species. The method to make Kintecus actually output 
the NSC matrix, S, is by using the -SENSIT:1 switch on the command line. 
Currently there is one NSC matrix producing method and to use it just enter 
-SENSIT:1 on the command line. This will output three NSC matrices at three 
times:the beginning of the simulation, the middle and the end. If you wish to 
produce more S matrices then simply append the number you want at the end of 
the SENSIT switch. For example, if I want 25 S matrices calculated over an 
evenly spaced time period during my simulation, just place  
-SENSIT:1:25 on the command line. Kintecus will output 25 files with the names 
SENSIT01.TXT to SENSIT25.TXT. Please note that Kintecus actually outputs the 
transpose of the NSC matrix (S^T). If you wish for unevenly spaced timed 
periods to output S matrices, you must use this form of the SENSIT switch: 
-SENSIT:1:TIMES,n1,n2,n3.....nn with TIMES in UPPERCASE and commas to delimit 
the times you wish to output time periods.
	One might think that, "Hey, if I just sum up the squares of the NSC's 
for each reaction then I'll know what reaction to drop because the reactions 
with very small NSC's should have no affect on any of the species". This might 
be true for some kinetic mechanisms, but in most cases this is not the case. 
NSC only tests for direct routes of influence of species X, it does not 
directly show strongly interacting reactions. A very simple method to see 
which reactions can actually be "thrown out the window" is a method of 
principal component analysis used by Turanyi, Vajda and Valko[9] applied to 
the normalized sensitivity analysis matrix, S. The steps described by this 
paper can easily be done in MATLAB or Lotus 1-2-3.
It involves finding NSC matrices, S1, S2 ,S3...Sn , at various times in the 
simulation, for example at ten evenly spaced periods (use -SENSIT:1:10 switch 
). By using a spreadsheet program or MATLAB you must concatenate all the S's 
at each calculated time into one big matrix, BS. Once again, don't forget to 
transpose each S before concatenating all of them into BS. Now multiply BS by 
it's transpose, BS^T * BS = D. Determine the eigenvalues, e,  and 
eigenvectors, v, of D. Now, calculate the lower threshold for the eigenvalues 
by multiplying the number of NSC matrices calculated by the number of species 
(which are NOT constants) by 1 x 10^(-4), call this L. Note all the 
eigenvalues that are equal or under L, call these LL.  Now the last step, for 
all the elements of each eigenvector of each respective LL that are greater 
than 0.2 mark those. Those elements of the eigenvectors correspond to 
reactions that have no affect on the whole kinetics scheme and can be safely 
"thrown out the window". The author has tried this with the formaldehyde 
oxidation mechanism and obtained similar results that the paper[9] has 
computed. 



// Jacobians //
***************

	The integration method used in Kintecus[1] requires the calculation 
of Jacobians. By default the Jacobians are calculated by a finite difference 
method. The earlier versions of Kintecus calculated the Jacobian analytically, 
that is, exactly. It was found that the analytical method was 2-5% slower than 
the finite difference method for kinetic mechanisms of less than 200 reactions 
so the finite difference method was selected to be used as the default method 
for calculating Jacobians. If you happen to experience underflow or overflow 
errors during the integration process (especially for large stiff systems 
composed of more than 1,500 reactions), switching to analytically calculated 
Jacobians will alleviate this problem. To switch to analytically calculated 
Jacobians use the -anjac switch on the command line (i.e. > kintecus -anjac ). 



[  Kintecus Switches  ]
=============================================================================

You can override many default settings in Kintecus by supplying the 
appropriate switch on the command line when you run the program. The available 
switches in Kintecus are:

The following command line options are:
 
-QUIET Don't display output nor warnings.
-PARM:filename (Parameter Description Input File)
-SPNAME:filename (Species Common_Name/Mass Input File)
-SPEC:filename (Species Description Input File)
-MOD:filename (Model Description Input File)
-OUT:filename (Concentration Output File)
-d### Where ### is the ASCII code of the data
delimiter used in the input files.
-c Create SPECIES.DAT file from model, then stop.
-y Set the lower threshold for the concentration.
  
-show Display to screen the concentration of species,
      time and dt's.
-ig:mass Ignore Mass Balance.
-ig:charge Ignore Charge Balance.
-ig:warn Ignore all warnings.
-SENSIT:  Output Sensitivity Analysis Output File
 -SENSIT:1(:n1 (:n2) ) Use sensitivity analysis #1 with
 the following optional numeric entries: 
 n1 :perform analysis at various parts in the simulation
 (default is three: beginning, middle and the end)
 -OR- n1=TIMES,t1,t2,tn... where t1,t2 and tn are
 times(in sec.) to perform the sensitivity analysis.
 n2 = percent difference in k's used (5% default) 
 just typing -SENSIT:1 is equal to -SENSIT:1:3:5 
-anjac Use analytically calculated jacobians.
-h or ? You get this list.
 
Make sure you type the command exactly the way it
appears.


***** NOTE FOR WORKSTATION USERS:

To set switches you must create a file named, "COMMAND.DAT". On the very first 
line is where you type in the switches separated by an ampersand, "&".
Example:
To ignore mass balance warnings, output a sensitivity analysis at times 0.001, 
10 and 100 seconds and see the concentrations as Kintecus integrates them, 
create a file named COMMAND.DAT (using vi, emacs or pico, I'm going to assume 
vi). 
1) Enter, "vi COMMAND.DAT" (Note: All UPPERCASE LETTERS!) <ENTER>.
2) Type an upper case O (for Open line).
3) Type, "-ig:mass & -SENSIT:1:TIMES,0.001,10,100 & -show" <ENTER>.
4) Press the escape key.
5) Type an uppercase Q.
6) Type a w <ENTER>.
7) Type q <ENTER>.
8) Run Kintecus.

**** OR ****

at the command prompt just enter:

$ echo "kintecus switches" > COMMAND.DAT

for example: to ignore mass balance warnings, output a sensitivity analysis at 
times 0.001, 10 and 100 seconds and see the concentrations as Kintecus 
integrates them enter:

$ echo "-ig:mass & -SENSIT:1:TIMES,0.001,10,100 & -show" > COMMAND.DAT
$ kintecus.exe


[ Sample Kinetics Files ]
=============================================================================

There are some sample kinetics files included:

The 81 smog reaction [3]
The output concentration file matches Figure 1 in the paper.

MODSMOG.TX2 - The kinetics reactions
SPECSMOG.TX2 - The species involved
PARMSMOG.TX2 - The parameters used
CONCSMOG.TXT - A simulation run.
SMOG.BAT - A very simple one line batch file that will run the above model 
producing the concentration profile equal to CONCSMOG.TXT.

The Cesium Flare [4]
The output concentration file matches Table II in the paper.

NAMECES.TX2 - A species name file containing common names and their MW.
MODCES.TX2 - The kinetics reactions
SPECCES.TX2 - The species involved
PARMCES.TX2 - The parameters used
CONCCES.TXT - A simulation run.
CES.BAT - A very simple one line batch file that will run the above model 
producing the concentration profile equal to CONCCES.TXT.

The Oscillating Oregonator [5]
The output concentration file matches Figure 1 in the paper.

MODOREG.TX2 - The kinetics reactions
SPECOREG.TX2 - The species involved
PARMOREG.TX2 - The parameters used
CONCOREG.TXT - A simulation run.
OREG.BAT - A very simple one line batch file that will run the above model 
producing the concentration profile equal to CONCOREG.TXT.

The Stiff Test [6]
The output concentration file matches the results on page 89.

MODSTIF.TX2 - The kinetics reactions
SPECSTIF.TX2 - The species involved
PARMSTIF.TX2 - The parameters used
CONCSTIF.TXT - A simulation run.
STIFF.BAT - A very simple one line batch file that will run the above model 
producing the concentration profile equal to CONCSTIF.TXT.

The Oregonator in a CSTR [7]
The output concentration file matches figures 5 and 6.

MODFORG.TX2 - The kinetics reactions
SPECFORG.TX2 - The species involved
PARMFORG.TX2 - The parameters used
CONCFORG.TXT - A simulation run.
OREGFLOW.BAT - A very simple one line batch file that will run the above model 
producing the concentration profile equal to CONCFORG.TXT.

Sensitivity Analysis of Ethane Pyrolysis[8]
Output sensitivity analysis files 1SENSIT1.TXT and 1SENSIT2.TXT match TABLES I 
& II in the paper.

MODSEN1.TX2 - The kinetics reactions
SPECSEN1.TX2 - The species involved
PARMSEN1.TX2- The parameters used

SENSIT1.BAT - A very simple one line batch file that will run the above model 
producing the normalized sensitivity coefficient files equal to 1SENSIT1.TXT 
and 1SENSIT2.TXT.

Sensitivity Analysis of the Oxidation of Formaldehyde Mechanism[8]
Output sensitivity analysis file 2SENSIT1.TXT matches TABLE IV in the paper.

MODSEN2.TX2 - The kinetics reactions
SPECSEN2.TX2 - The species involved
PARMSEN2.TX2- The parameters used

SENSIT2.BAT - A very simple one line batch file that will run the above model 
producing the normalized sensitivity coefficient file equal to 2SENSIT1.TXT.


[ Support Programs ]
============================================================================

	Most of these programs listed below are designed to help you transfer 
your experimental data into concentration profiles or convert text files from 
another platform (such as the Mac, UNIX or Amiga) to MS-DOS or the other way 
around.
To run the programs just type at the MS-DOS prompt >qbasic /run program.bas.

PROGRAM NAME: INTERPOL.BAS

"Program to convert scattered data file of time,data to"
"a sequential list of data spaced exactly at an "
"entered timing interval."
"(Values in-between are linearly interpolated...)"

PROGRAM NAME: CRADD.BAS

This program converts text files from another platform (such as the Mac, Unix 
or Amiga) to MS-DOS.


PROGRAM NAME: CONC-123.BAS

"Concentration File (CONC.TXT) to Lotus 1-2-3 Import File Converter"

 LOTUS 1-2-3 can not import numbers/text characters beyond 320 chars it will 
not load the file, not even a partial load. This will allow lotus to load up 
to at least the 320 character limit.

PROGRAM NAME: LOOK.BAS

A program to look at the ASCII values in a file.

PROGRAM NAME: FILTER.BAS

This will convert MS-DOS text files to Mac/Unix text files.

  


[ References ]
============================================================================


[1] Vetterling, W.,T.; Flannery, B.P.; Teukolsky, S.A; Press, W.H., "Numerical 
Recipes in FORTRAN", Second Edition, Cambridge University Press, Cambridge, 
1992.

[2] Frei, K.; Hs. H. Gunthard, Hel. Chim. Act., 50(132), 1967, pp1294-1304.

[3] Farrow, L.A.; Edelson, D., Int. J. Chem. Kin., 6, 1974, pp787-800.

[4] Kennealy, J.P.; Moore, W.M.; J. Phys. Chem., 81(25), 1977, pp2413-2419.

[5] Field, R.J.; Noyes, R.M., J. Chem. Phys., 60(5), 1974, pp1877-1884.

[6] Edsberg, L., "International Symposium on Stiff Differential Systems", 
Plenum Press, 1974. 

[7] Showalter, K.; Noyes, Richard M.; Eli-Bar, Kedma, J. Chem. Phys., 69(6), 
1978, pp2514-2524.

[8] Dunker, A.M., J. Chem. Phys., 81(5), 1985, pp2385-2393.

[9] Vajda, S.; Valko, P.; Turanyi, T, Int. J. Chem. Kin., 17, 1985, pp55-81.

[10] Gautier, O.; Carr JR., R. W.; Seigneur, C., Int. J. Chem. Kin., 17, 
1985, pp1347-1364.

 
