Quoc D. Dang
Washington University School of Medicine
Dept. of Biochemistry and Molecular Biophysics
St. Louis, MO 63110
email: dang_q@caesar.wustl.edu or dang@biochem.wustl.edu
http://www.biochem.wustl.edu/~dang

KINSIM40.EXE and FITSIM40.EXE released Mar. 1997
Please email Dr. Carl Frieden(frieden@biochem.wustl.edu) or me (dang@biochem.wustl.edu)
if you discover any bugs in the programs. We will also notify you of new versions of these
programs as they become available if you want to drop us your email address.

*******************************************************************************

1. INSTALLATION
2. INTRODUCTION
3. SHORT HELP MANUAL

***************************1. INSTALLATION***********************************

1. Copy the self-extracting KFSIM40.EXE file into a directory.  
2. Run KFSIM40.EXE by clicking on the icon from Windows file manager or    
   in Win95 and WinNT.  The program will uncompress itself and the   
   following files will be present.

KINSIM40.EXE    	Program for compiling and simulating a kinetic 
			mechanism.  Real ascii data can also be converted
			to kinsim format (i.e. *.rdf).

FITSIM40.EXE		Program for fitting and viewing fits to a
			kinetic mechanism.

SAMPLE.MEC	  	Sample kinetic mechanism file (needs to be in text
                  		or ascii format--don't save as a word document, etc.).

DOSXMSF.EXE   	32-bit dos extender that allows the programs to access
			memory above conventional memory.

INSTALL.BAT	  	Installation batch file that copies DOSXMSF.EXE to 
			different directories found in the path statement of
			AUTOEXEC.BAT file.

README.TXT		This file which includes a short help manual.


3. Run INSTALL.BAT and the file DOSXMSF.EXE is copied to the c:\,  
   c:\dos, and c:\windows directories. DOSXMSF.EXE needs to be in a 
   directory that is in the path statement in AUTOEXEC.BAT file.

It is convenient to keep KINSIM40.EXE and FITSIM40.EXE in a directory that 
everyone can access. Copy these programs to the directory where your data 
is stored and run from that directory. These programs are best run from 
the Windows (Win3.x, Win95, WinNT) environment, but can also be run in Dos.  
If you want to run these programs from Dos, exit Windows to do so.  Running 
these programs from a Dos Window will not work without a file that I have 
not included.

***************************2. INTRODUCTION******************************

These programs have been recompiled as 32-bit DOS-extended programs using 
the Fortran Powerstation V1.0f.  All programs have been combined into two 
main programs: KINSIM40.EXE and FITSIM40.EXE.  A number of useful features 
have been incorporated, but the structure of the programs are basically 
the same as before.  This version of the programs will now run under DOS, 
Windows 3.x, Windows 95, and Windows NT. I haven't actually tested the 
program under OS2, but it should work as well since Dos and Windows programs 
work in OS2.  Please let me know of major bugs in the program if you 
encounter any. I can also accommodate requests for recompiled versions of 
the programs for those needing larger parameter limits.

Improvements below are not listed in any particular order:

1. The programs are 32-bit dos-extended and can access more memory.
2. The programs can run under multiple operating systems, including: Dos, 
   Windows 3.x, Windows 95, and Windows NT.
3. All modules have been modified so data files with discrete time points 
   can be used, i.e. data points with equally spaced time intervals no 
   longer required.
4. New raw data file conversion program incorporated in KINSIM40.EXE that 
   handles files w/wo headers and comments, 1 or 2 column data, rescaling 
   of data, inversion of data, and batch file conversion of data files.
5. Global fits following the signal from multiple species in a mechanism 
   is possible.
6. The fitsim, fitdata, and fitshow modules are now combined into one 
   program called FITSIM40.EXE.
7. KINSIM40.EXE combines kinsim, kincomp (kinetic mechanism compiler), and 
   a data conversion program.
8. KINSIM40.EXE can simulate data in the log scale.
9. Fitted curves can be displayed individually or simultaneously.
10. Ascii x,y data for fitted curves are generated in *.fxy files for 
    importing into graphics or spreadsheet programs to generate publication 
    quality graphs.
11. The size of the executables are less than half of the older versions. 
12. KINSIM40.EXE can display upto 20 multiple real data files simultaneously.
13. FITSIM40.EXE can fit upto 20 *.rdf (real data files) at a time. 
    Versions with higher limitations are available upon request.
14. These programs currently can handle mechanisms with 100 different species 
    and 100 different reaction steps (1 reaction is 2 kinetic rate constants). 
    These limits can be increased upon request.
15. Fitting of the output factors has also been incorporated.

*************************3. SHORT HELP MANUAL***************************

This a short help file for the latest PC versions (released March, 1997) of 
KINSIM40.EXE and FITSIM40.EXE. More detailed manuals for the original 
versions of Kinsim and Fitsim operation are available from wuarchive.

GETTING STARTED WITH KINSIM

First you will need to set up a mechanism. This can be done with a text
editor such as Windows notepad. If you use a word processing  program such 
as MS Word, you must save the mechanism in a text format.

Example of a mechanism:
 
$Simple mechanism
E+ S == ES == EP == E + P
 
where == defines a reversible step governed by rate constants. ( A single 
equals sign, =, defines a step governed by a dissociation constant). 

Follow the mechanism equations by an *OUTPUT and the desired output equations.

        example 
                        $Simple mechanism
                        E+ S == ES == EP == E + P
                        *OUTPUT
                        F1*S
                        F2*(ES + EP)
where F1 and F2 are just factors to convert observed results from
concentrations to, for example, absorbance. In this example S and (ES + EP) 
will be displayed as separate lines on the graphical output when the factors 
are nonzero. Mathematical operators that can be used in the output expressions 
are ^(exponetial), * (multiplication), / (division), + (addition), 
- (subtraction) and % (logarithm). A $ or ! are for remarks should you wish 
to include them. A  [1 holds the concentration of a species(e.g., S[1) constant.

Species names can be complex. For example  AA or A2 is a dimer of
A, 2AB3O4 is 2 molecules each with 1A, 3B's and 4 O's.

Save the file you have created as filename.mec

Run KINSIM40.EXE by clicking on it and a menu will appear. You will
find an instruction (O) that allows you to compile the filename.mec file to 
a *.sim file necessary for running KINSIM. After compiling the mechanism, 
choose M and load the simulation file, filename.sim. 

From the menu, choose C to enter concentrations. Control E (return
or enter) always returns you to the menu. 

Choose K to put in the rate constants 
Choose F to put in factors
Choose T to put in values of 
  		 	                delta time
                                 	integrations (default = 1)
                                 	run time
                                 	Ymax
                                 	Flux tolerance (default = .02)
                                 	Integral tolerance (default = 1E-6)

Be sure that concentrations, rate constants and run time have the same units.

Again, Control E (return) will take you out the window and back to the menu. 
Delta time requires some explanation. You can put in a relatively large 
value (like 1) and the program searches for the smallest delta time that 
falls within an integral tolerance range. If you start with a very small value
(1e-5), and your data covers a long time, the program may take a long time 
to simulate. Therefore, unless the program crashes, it is best to use a 
relatively large value. The integrations will define how many points are in 
the simulated plot. For example, if delta time is 1 and integrations is 1 and 
the runtime is 100 sec, there will be 100 points. If the integrations is 
set to 5, there will be 20 observed points on the graph and so on. 

Once you have performed a simulation to your liking, you can save values of 
all the parameters for rate constants, concentrations etc., by  choosing S. 
This will create a *.sav file. You can restore these values by choosing R and 
typing in the name of the .sav set when asked. The .sav files will be used 
for FITSIM.

P will change the background color of the graphics between black and white.

To run, choose G. Nothing (except some blinking) will happen until the 
simulation is finished.

To load real data files, they must be in the proper format. Since every 
instrument produces a different ASCII file, you will need to convert that 
file to one that is appropriate. Once you have downloaded the real data 
ASCII file from your equipment to the proper folder, choose A to convert the 
ASCII file to the required  *.rdf file. Follow the directions indicated 
to do the conversion. While this program works well, it is possible that the 
conversion program will not be completely universal. Should you need to 
convert an ASCII file, the structure should be two columns (time, data) with 
no headers or footers.  Save the data as a text file.

If you wish to display the real data you have converted during the simulation, 
choose I. You may load up to 20 data files. A screen will show you the 
parameters. Once the data are accepted the runtime and Ymax for the last file 
chosen will be inserted automatically into the KINSIM program under T (see 
above). To remove the data file(s), type I again. New data files can then be 
loaded by typing I again.

There is a more complete manual currently available from 
wuarchive.wustl.edu/kinsim/packages/.  Docs.w51 is documentation written 
in Word 5.1. The documentation is extensive but slightly different from the 
program you are using since it was written for the original VAX programs.


FOR THE FITSIM PROGRAM

You need to have one .sim file and a .sav set for every data set you fit. 
The .sav set is created from KINSM for each data set. FITSIM globally fits 
many data sets and is fairly self-explanatory. Start by clicking on 
FITSIM40.EXE to run the program. Choose (1) to make a *.fdt file for fitting. 
The default is autosim.ftd but you can use other names.   

You will be provided with a series of options. In a complex mechanism it is 
best to hold as many rate constants as possible constant allowing just a few 
to float. The limits of the varied rate constants are set very large and can 
be decreased without harm. For the most part you can just use default values 
for everything else. This new version of FITSIM contains several new features. 
These include the ability to fit data with uneven as well as fixed time points, 
the ability to fit any of several outputs, the ability to simultaneously view 
up to 20 different real data files and the ability to float the factors, in 
addition to rate constants, in the mechanism. The output factors can be floated
by answering NO in the use default parameters section.  

Choose (2) to start the fitting.

Choose (3) to view the fitted curves to the real data (assuming the fitting was 
successful).

ASCII files (*.fxy) of the fitted curves are generated after the fitting is 
complete. These files can be exported to any spreadsheet or graphics program
for making publication quality plots. ASCII files (*.dxy) of the real data are 
also generated in KINSIM40.EXE during the file conversion and are useful if 
the original ASCII data were transformed.

REFERENCES

For KINSIM: 
B. A. Barshop, R. F. Wrenn and C. Frieden, (1983) Analysis of numerical
methods for computer simulation of kinetic processes: development of
KINSIM--a flexible, portable system. Anal Biochem  130,  134-145

For FITSIM:
C. T. Zimmerle and C. Frieden, (1989) Analysis of progress curves by
simulations generated by numerical integration. Biochem J  258,  381-387

see also
Frieden, C.,  (1993) Numerical integration of rate equations by computer. 
Trends Biochem Sci 18,  58-60

Frieden C. ,(1994) Numerical integration of rate equations by computer: 
an update. Trends Biochem Sci  19,  181-182

Frieden, C., (1994), Analysis of kinetic data: practical applications of
computer simulation and fitting programs. Methods Enzymol  240,  311-322
		
