/**********************************************************************
** This documentation is part of kinetikit and is
**           copyright (C) 1995-1997 Upinder S. Bhalla.
** It is made available under the terms of the GNU General Public License. 
** See the file COPYRIGHT for the full notice.
** Alternatively, use the 'Help' menu for information on authorship and
** copyright.
**********************************************************************/
KINETIKIT: a Genesis/Xodus tool for developing simulations of
chemical kinetics.
	By Upinder S. Bhalla National Centre for Biological Sciences,
		Bangalore, INDIA. 1995-1997

Manual last modified Feb 6 1997.

=============================================================================
	This help manual is under construction.
=============================================================================
Sections:
1. Introduction
2. Tutorial: Building a model
3. Tutorial: Saving models
4. Tutorial: Experiments on model
5. Tutorial: Techniques for complex models.
5.1	Groups
5.2	Merging
5.3	Complex stimulus paradigms
6. Menu Options
6.1	File menu
6.2	Edit menu
6.3	Tools menu
6.4	Options menu
6.5	Graphs menu
6.6	Help menu
7. Objects in kkit
7.1	Groups
7.2	Pools
7.3	Reacs
7.4	Enzymes
7.5	Channels
7.6	Stims
7.7	Tables
7.8	Plots
8. Library of models
9. Customizing
10. Future plans
11. Acknowledgements




=============================================================================
1. Introduction

Kinetikit is an interface and utility for developing simulations of chemical
kinetics. It is designed to be 'click and drag' and is (hopefully), 
intuitive to use.

1.1 Starting Kinetikit
To run it: 
1. Obtain and install a copy of Genesis which includes the kinetics library.
2. Obtain and install kinetikit.
3. Add the kinetikit directory to your SIMPATH in .simrc
4. Type 
	genesis kkit
from the UNIX prompt.
or, if you already have a model foo.g saved from kinetikit, just type
	genesis foo

1.2 Kinetikit basics: modules

Available modules are displayed in the 'library' window. Instances of
these modules are created by dragging them
onto the edit window. They are interconnected (in the edit window) by
dragging them onto each other, and graphed by dragging them onto the graph
window. Their parameters may be changed by double-clicking on the icons
representing the modules. The basic modules are :
pools - representing available pools of reactants
reactions - representing standard chemical reactions between pools
enzymes - representing Michaelis-Menten enzyme kinetics
channels - representing ligand-gated channels
stims - representing simple two-level stimulus generators.
tables - representing more complex stimulus generators
groups - providing an organizational basis for complex models

There is also a little representation of a toothy dinosaur in the library,
affectionately known as 'Barney', who eats (deletes) any of the above
modules.


1.3 Kinetikit basics: reactions
Kinetikit models standard chemical kinetics of the form:

	A + B <---kb---kf---> C + D

For convenience, it also provides special modules for modeling Michaelis-
Menten enzyme kinetics:

	Enz + Sub <---kb---kf---> Complex ---kcat---> Prd + Enz

or, in terms of the rate constants used in kkit:

	Enz + Sub <---k1---k2---> Complex ---k3---> Prd + Enz


and ion channels which at this point are driven purely by concentration
gradients. The stim and xtab modules provide inputs to the model, typically
by controlling the concentration of one or more pools.

kkit uses a graphical representation of all interactions, which is fairly
close to common illustrative representations used in describing chemical
pathways. 


1.4 Kinetikit basics: running
Models are run using the fairly obvious start-stop-reset buttons in
appropriate colors on the control panel.
1.4.1 Start.
	When you hit the 'start' button,
the simulation starts running for a runtime specified by the Runtime dialog.
Note that the runtime is calculated from the current state of the model.
While the simulation is running, the Current time dialog monitors the
simulation time. A side-effect of changing the runtime is that the graph
x-axes are updated so that the runtime is the x maximum.
1.4.2 Stop.
	This stops the currently running simulation gracefully. The
simulator will stop at the end of the current timestep, and will be 
ready to start up where you left off if you hit the start button again.
1.4.3 Reset.
	This is drawn in red because it irreversibly halts and
wipes out the current state of the simulation. It also sets the current
time to 0.

1.5 Kinetikit basics: Editing
Everything in the edit window is edited by the simple process of double-
clicking on it. This will cause an edit panel for that element to pop up
to the right. Most fields except the 'Path' are editable. Changes made in
the dialogs are not passed on to the element until you hit 'return' on
the dialog, or until you click on the button on the dialog. The UPDATE
button refreshes the values of all dialogs, and the HIDE button does what
it says. There is a NOTES window in most edit panels. You can enter text here,
but it will not be stored till you click on the NOTES button beside it. At
this time there is a stupid limitation on the number of characters that
Genesis can handle in a text string, so try it out to see how far you get:
type in something, hit the NOTES button, and then hit UPDATE. It should be
at least 5 lines in the NOTES window.

1.6 Kinetikit basics: Rearranging
All the items in the edit window can be repositioned by click-and-drag
operations. Some items (e.g., enzymes and channels) are always attached
to pools, so if you move the pool these children also change position.
All the children of groups also move with them by default, but this 
behavior can be toggled using the appropriate button on the edit panel for
the group. Of course, the whole edit window can be panned around using the
arrow keys, and zoomed in and out using the angle bracket keys. If you
zoom too far out then the arrows interconnecting items will vanish in
the distance, but they will reappear when you zoom back in.

1.7 Kinetikit basics: Connecting
Most of the modules can be connected to each other. For example, if you
drag a pool onto a reac, then a green arrow will appear representing the
connection. If you repeat this operation, the original connection is 
removed. We will go into much more detail on setting up models below.

1.8 Kinetikit basics: Grouping
Groups are an organizational feature. Any element, including other groups,
can be dragged into a group. To remove it from the group, drag it onto
the group again. We will discuss the uses of grouping later.

1.9 Kinetikit basics: Graphing
Pools can be dragged into any of the graph windows to set up a plot.
This plot has its own little edit panel, which can be recalled by
double-clicking the plot label in the graph. Likewise, a plot can be deleted
by dragging the plot label onto Barney (the toothy dinosaur icon). The
graphs themselves have numerous features which are described in various
manual pages for Genesis. One of the useful ones is the ability to drag on
the axis labels to rescale the graph.

1.10 Kinetikit basics: Saving
Hit the 'File' option in the title bar. Type in any notes that you
want to keep for this particular model, then enter the filename
you want to use for the model in the 'save' dialog. When you hit
return or click the 'save' button, the model will be saved.

1.11 Kinetikit basics: Quitting
Hit the 'File' option in the title bar, and then the 'quit' button on the menu.
It will ask for confirmation before quitting. 


=============================================================================
2. Tutorial.
As a simple example we will go through the process of building, saving, and
editing a model. We will use most of the library components while
building this model.
The model is a simple simulation of end-product inhibition. We assume that
the product 'prd' of an enzymatic reaction interacts with the enzyme to produce
an inactive form. 

2.0.
Start up Genesis, and kinetikit. If all your simpaths are set correctly it
should be possible to type
genesis kkit
to get going.
At this point you may wish to click the 'Help' menu item to open the help
window, which displays this file.

2.1 Setting up the enzyme reaction
2.1.1 Creating the 'enz' pool.
	To start off, lets make the pool of molecules for the enzyme. Click on
	the blue 'kpool' icon in the library window, and drag it into the 
	edit window in a central-ish location. A new 'kpool' icon appears in
	the edit window, and an edit panel pops up on the right. Go to the
	edit panel, and enter the values:
	Field	  Value
        ---------------
	color	: red
	CoInit	: 1
	Name	: enz
	If you are really neat, you can hit the 'HIDE' button at this point
	to get rid of the edit panel.
2.1.2 Creating the Michaelis-Menten reaction for the enzyme pool.
	The 'enz' pool on its own is just a bunch of molecules. So we need
	to add the catalytic activity to this pool. We do so by clicking on
	the 'kenz' icon in the library window, and dragging it onto the 'enz'
	icon in the edit window. If it works, then a 'kenz' icon appears
	above the 'enz' pool icon. and the edit panel for the enzyme
	pops up. We'll use the defaults without changing.
		Note that enzyme activity _must_ be associated with a pool,
	since enzymatic activity is associated with specific molecular species.
	Try creating a new 'kenz' by dragging from the library to a blank part
	of the edit window, and it will tell you off. Also note that if you
	move the parent pool of a kenz on the edit window, the kenz will tag
	along as well. Finally, you can move the enzyme with respect to the
	parent pool by dragging it to a different place on the screen. This
	new relative position will be maintained when the parent pool is moved.
2.1.3 Create pools for substrate and product.
	Follow the same steps as for the enz pool in 2.1.1.
        Field             Substrate pool               Product pool
        -----------------------------------------------------------
        color             green                        pink
        CoInit            1                            0
        Name              sub                          prd

2.1.4 Connect up the enzyme reaction.
        This is easy. Just drag 'sub' to 'kenz', i.e., to the Michaelis-Menten
        enzyme icon attached to the icon for 'enz'. An arrow should appear
        to display this reaction. Now drag 'kenz' to 'prd', and you should
        get another arrow.
2.1.5 Graphing the reaction progress.
	Now we put in some plots. Drag each of the pools 'sub', 'enz', 'prd'
	one by one to the graph widgets. A color-coded little text icon
	will appear in the graph window to indicate the specified plot. This
	text icon can be double-clicked to put up an edit panel for the plot.
	You may prefer to put the plots in different graph windows to reduce
	clutter.
2.1.6 Initial trial run
	Just hit the 'reset', and then the 'start' buttons. If all went well
	you will see the concentrations of the reactions being plotted as a
	function of time. If open the edit panel for one of the pools,
	you can click on the 'UPDATE' button to display the current
	values for 'n' and 'Co' as the simulation is running.



2.2 Adding in a chemical reaction for the inhibition.
2.2.1 Creating the chemical reaction.
	Drag the 'kreac' icon onto a convenient spot in the edit window.
	Note that reactions, unlike enzymes, are not located on a specific
	pool.
	Change the following fields:
        Field             new value
        ---------------------------
        kf                10
        kb                1
        Name              inhib

2.2.2 Adding the final inhibited form of the product
	Drag in another pool for the inhibited form. Set the following
	fields:
        Field             Value
        ---------------------------
        color             white
        Name              inhib-enz

2.2.3 Connect up the end-product inhibition pathway.
	Click on the 'enz' pool and drag onto the reac named 'inhib' 
	Click on the 'prd' pool and drag onto the reac named 'inhib' 
	Click on the reac named 'inhib' and drag it to the 'inhib-enz' pool.

2.2.4 Graphing the inhib-enz
	This should be obvious by now. Drag the inhib-enz pool to a graph.

2.2.5 Second trial run
	Hit 'reset' again, and 'start', and off you go. See the
	difference when the inhibition is present ?

2.3 Stimulus for model
2.3.1 Creating the xtab
	Drag in the xtab from the library. As usual, an edit panel appears.
	This is quite complicated, and we won't go into the details of what
	it can do. For illustration, we will just use the xtab to generate
	a linear ramp:
	Select the stimulus waveform options.
	Click on the upper right corner of the graph to get a position
		around (100,1).
	Then click the 'interpolate' button.
	You should now have a nice line from 0 to this point. This will be
	your stimulus ramp. Flip back to the stimulus run
	options.  Now click the 'Stimulus Off: click to start' toggle to
	activate the table for delivering stimuli.

2.3.2 Connecting the xtab
	Easy. Click and drag xtab onto the 'sub' pool.

2.3.3 Third trial run
	This should be obvious by now: 
		Hit 'reset' again, and 'start', and off you go.
	For kkit < 1.1, you may find that the table is a bit temperamental.
	It is sensitive to timestep, and to whether or not the tab-loop
	mode is selected. So play around with these. Better yet, since
	you are reading this, you must have access to a more recent version
	of kkit, so why not upgrade ?

=============================================================================
3 Tutorial: Saving and restoring model
3.1	Saving
	What, you mean you haven't been saving yet ? You should know better!
	Go to the 'File' menu, open it. Enter some useful comments into 
	the text area under the NOTES sign. Then enter a filename like 
	epi.g into the 'save' dialog, and hit return. Phew! Your model
	is now safe. Use the UNIX shell to examine the file if you are 
	curious. epi.g is a text file, and in fact is a perfectly legal
	Genesis script file. The simundump commands are rather
	cryptic and meant for machine consumption, but the rest
	are fairly straightforward.
	Be warned that the saves overwrite existing files. As a general
	organizational rule and as an electronic equivalent of a page in
	a lab notebook, I normally type in a version number as part of
	each filename.
		
3.2	Restoring.
	Quit your simulation (from the 'File' menu).
	There are two ways to restore the model. The obvious one is to first
	load in kkit, and then go to the command line and type the name of
	the model file ('epi' in our example). For convenience, the saved
	files will load in kkit themselves if they are invoked directly:

	genesis epi

	will start kkit and then load in the model 'epi', without further
	user intervention. This assumes that kinetikit is set up properly
	in your Genesis SIMPATH (check your .simrc). Note
	that the state of the model is restored, but not the data in the plots.
	The plot values can be saved separately. The reason for this is
	that the plot data occupies a lot of space, and is not used often
	enough to justify saving it every time.

3.3	Restoring from the interface
	Due to an oft-lamented peculiarity of the Genesis parser, it is
	not possible to load in a file specified in a dialog. So, if you
	have already started up kkit, you will have to go to the command
	prompt to load in the model file.

3.4	Saving plots
	Plots can be individually saved using the dialog in the pop-up panel
	for the plot. The format is standard x-y format, one coordinate pair
	per line, separated by spaces. One can also save all the plots at
	once using the "Save all plots to file:" dialog in the Graphs menu
	item. This saves all the plots in a single file in xplot format,
	which is basically the same x-y format with one coordinate pair per
	line. Different plots in the same file are identified by '/newplot'
	and '/plotname ...', and it should be easy to extract the plots you
	want from this file.


=============================================================================
4 Tutorial: Experiments on model
4.1	Overlays
	For the following sections we will probably want to compare the
	progress of the reactions in time. This is done by selecting the
	overlay for the plots. In the overlay mode, the previous plots are
	retained. Run your reference reaction, and then BEFORE
	hitting reset, go to the 'graphs' item on the menu bar. Change the
	toggle from "Do not overlay plots" to "Overlay all plots". Now make
	the changes in the model, hit the 'Reset' button, and start over.
	You will now have a new set of plots which can be compared with the
	old curves. When you have enough plots piled up on each other, just
	go back to the 'graphs' menu item and change the toggle back again.
	The next Reset will clean out all the plots.

4.2	Buffering
	Lets buffer the substrate. Double click on the 'sub' icon. Flip the
	"BUFFERING OFF" toggle on the substrate pool to 'BUFFERING ON'. Now
	run the model again. You will find that the concentration of 'sub'
	is held fixed at CoInit. If your simulation is running slowly, you
	can even change CoInit on the fly by entering a new value in the 
	dialog. Turn the buffering off for the next stage.

4.3	Slope of plot
	The 'prd' in this model rises continuously. Let us see if the
	production rate approaches steady-state. One way of doing this is to
	plot the slope of the 'prd' concentration.
	Double-click on the 'prd' label in
	the graph window. An editor panel for the stim appears. Hit the toggle
	"Slope calculation mode" to change it from 'off' to 'on'. The new
	points for the prd will be displayed as slope. The time units are per
	second. This is too small to see easily, so scale it up by changing
	the Y-scale value. When scaled to 100, the plot lies almost exactly
	over the inhib-enz plot. Hmm. Can you explain this ?
	Exercise for the reader: Can you come up with another way of deriving
	the rate of production of 'prd' (the slope) ? Hint: contemplate the
	rate equations for a reac.

4.4	Second-order kinetics
	Lets say we want to change the order of the inhibition of the enz
	by the prd from first order to second. Try the obvious method: drag in
	the 'prd' to the 'inhib' reac a second time. Oops, this turns out to be
	the procedure for _removing_ an existing reac. To do this right, start
	out by replacing the first arrow from 'prd' and then going to the
	'Options' menu. Flip the toggle saying "Cooperative reacs disabled",
	and then drag the prd to the inhib reac again. This time you should get
	a second arrow parallel to the first. (Older versions of Xodus have a
	bug in which the second arrow is not displayed under some conditions.)
	You can make the reaction as high-order as you like. Mechanistically,
	be warned that true higher-order reactions are rare and should
	be considered an approximation to multi-stage reactions. As an
	exercise, build and compare nominally equivalent examples of a
	high-order reaction implemented as 
	1. a cooperative reac
	2. as a sequential multi-stage reaction (First one specific
		intermediate is formed, then the other).
	3. as a parallel multi-stage reaction (where either intermediate form
		can be formed at the fist step)

4.5	Accuracy/speed
	This is where graph overlays are specially useful.
	- Start out with a clean graph, and run the model normally.
	- Now go to the 'options' menu and change the dt from 0.01 to 0.001.
	- Then in the graph menu, turn overlays on.
	- Reset and run the model again.
	The output should be nearly identical,
	which is reassuring. It shows us that the original dt was pretty
	reasonable. See how long a dt you can get away with. Surprising, eh,
	for such a simple integration scheme?
	Frequently one encounters steeply changing transients in these models,
	for example, when you start the model up or deliver a stimulus. In
	such cases it sometimes helps to reduce the timestep to get over the
	transient, and then go to a longer timestep for speed once the 
	numerically difficult part is over. In a future version of the kinetics
	library there will be a higher-order integration solver (ksolve)
	which will use variable timestep.

4.6	Set up a degradation pathway for the prd.
	This should be a simple enough exercise for the reader, and can
	be done with what you already know.
	Hint: assume that the degradation end-product is held at a fixed level.
	Blatant hint: You can do this by buffering it.

=============================================================================

5 Tutorial: Techniques for complex models
	This section is relevant only when you have a complex enough model
	that managing it becomes a major issue. As a rough guide, when the
	icons in your model start to become really crammed together when you
	try to see them all at the same time, you can be pretty sure you
	need to start using the techniques described here.

5.1	Groups
	A group is a container for other kinetic elements, including other
	groups. These are a useful basis for modularization. Typically,
	each signaling pathway should be represented by a separate group.
	They perform no numerical operations, so be liberal in their use.
5.1.1	Creation of groups
	Creating a group element is trivial - drag it into the edit window, as
	should be obvious by now. Lets call this group epi, and color it blue.
	Other elements (including other groups) are placed
	into the group by dragging them in. For our example, try this out
	with all the elements in the current model. Note that the position
	of the elements does not change, but the color of their text labels
	changes to that of the group.
5.1.2	Color matching
	It is advisable to set the foreground color of each of the
	elements in a group to some common base color, for example, shades
	of green. In complex models this (along with the textcolor) helps
	to identify members of a group.
5.1.3 Hiding and showing (contracting and expanding)
	There are controls for this in the pop up panel for the group. The
	purpose is straightforward enough: to reduce clutter in a complex
	model. I actually find that I prefer to have all the elements of
	all the groups visible in all their glory, because this helps me to
	keep track of all the relationships. 
5.1.4 Moving
	The children of a group normally will move along with their parent
	group when it is shifted in the edit window. This behavior can
	be toggled using the "Move..." toggle in the group edit panel.
5.1.5 Saving
	Rather than saving an entire model, one can save the contents of a
	particular group. This will try to also save all elements which are
	connected to that group, even if they are not in the group itself.
	This last feature is a little temperamental at this point (kkit1.1)
	Try it out, saving the file as group_epi.g.
	We will use it later.
5.1.6	Initializing
	The 'Initialize all children to current levels' button is useful for
	models which need to start at an equilibrium level which takes a
	while to attain. Just click the 'Initialize' button, once the model
	has equilibrated. Now the 'CoInit' fields are set to the equil value,
	and the model will be equilibrated at reset. This button should be
	used with caution, however. Make sure that you have saved the version
	used to derive the equilibrium, in case you wish to change conditions
	later. This is specially applicable to models which you later wish
	to merge, since any change to the model will change equilibrium levels.

5.2	Merging
	This is one of the most important facilities for developing large,
	complex models in kkit. Basically, it allows you to simply load in
	independently developed modules (your own or from a library) in
	succession. The loading routines will hook up most things
	automatically while avoiding overlap.
5.2.1	Loading new files in
	I assume that at this point you have a group called epi, with all
	the elements moved into it as children. (If not, you can quit, start
	over, and reload the file group_epi.g). Lets now merge this with the
	original epi.g which we saved in section 2.4. To make things
	interesting, lets remove the 'prd' from the group (by dragging it
	into the group again). The idea is that the original epi.g overlaps
	with the current model on this element. We would like the merging
	process to connect up with it without duplication.
	Go to the command line and type epi.g. Amazing - it loads right in.
	(You may need to move the group 'epi' around a bit to see the newly
	loaded elements.)
	In particular, the 'prd' pool should now be connected both to the 
	group 'epi' and to the elements in the original model. This facility
	makes it very easy to hook up different signaling pathways through
	common messengers such as Ca and AA.

5.2.2 Interconnecting groups (messenger pools)
	You have just seen an example where the 'prd' pool was used as a
	common messenger which automatically got hooked up during merging.
	For this to work well, it helps to keep the
	common messengers as children of the base group /kinetics (where
	everything goes by default). 

5.2.3 Future development
	The merging facility is slated for considerable development. Some
	of the items to look forward to include:
	- Saving a complex merged model as a collection of file references
		to individual modules
	- Automatic selection of most recent version of library module.
	- Improvements to the common messenger facility
	- Automatic positioning of merged-in modules to lessen overlap.
	The long term objective is to make it possible to think in terms of
	pathways without having to worry about the details of merging and
	managing libraries.
	
5.3	Complex stimulus paradigms.
	One can manage pretty complex stimuli with the 'stim' and the
	'xtab', but these have limitations. For example, one may wish to
	reduce the timestep for computing the transients accurately during
	a large stimulus. At this time the best way for doing this is
	to write a script function. Regretfully, there is no API at this
	point for conveniently specifying calls within kkit that one may
	wish to use for writing such a stimulus function. In practice the
	one function call that I frequently use is
	do_save_all_plots(filename)
	which does just what it says.


=============================================================================

6. Menu Options
Menus are opened and closed by clicking on the menu button. In some cases
menu commands will close the menu, leaving the menu button in a depressed
state. If so, it will take two (rather than one) clicks to redisplay the menu.

6.1 File menu.
----------------------
6.1.1	Open file...
	This item pops open a panel with various loading options.
	As this item indicates, this version of Genesis will not allow
files to be loaded in from the GUI, and you have to type in the filename
at the command prompt.
6.1.2	Save [filename]
	This dialog saves the model to the specified filename. This _can_
	be done from the GUI.
6.1.3	NOTES
	This is a text entry area, for typing notes that will be saved
	along with the model.
6.1.4	Clear entire simulation
	Well, that should be clear enough !
6.1.5	quit
	Another obvious button. It pops up a further panel asking for
	confirmation in case you hit it in error.

6.2 Edit menu.
----------------------
	This space reserved for future expansion

6.3 Tools menu.
----------------------
6.3.1	Postscript...
	This provides various options for helping one to dump the contents
	of the edit window in postscript format. Oddly enough, there is
	no command for doing the actual dump. You must go to the edit window
	and type ^P (control-P) to cause the dump to happen.
6.3.2	Plot...
	This just pops up the Graphs menu, which is described below.
6.3.3	Compare models...
	This option lets one compare the kinetic parameters of a model. Simple
	'diffs' of model files do not work well for this task.
	The option pops up a self-documented window to help one compare all
	or part of a loaded model with a model in a file, or part of another
	loaded model, or part of the same model.

6.4 Options menu.
----------------------
6.4.1	Clock 0 dt for simulation
	This is the fastest clock for the simulation. It is reserved for
	special situations where one needs to run some other part of a
	combined model (e.g., a compartmental model) at a much
	shorter timestep than the kinetic model. In most cases it
	should be set to the same value as clock 1.
6.4.2	Clock 1 dt for simulation
	This is the clock for most of the kinetic components except tables.
6.4.3	Clock dt for plots
	Says what it is. One saves CPU time as well as memory if this
	is set to a value substantially larger than the simulation dt.
6.4.4	Clock dt for control
	This is the clock used for updating the 'Current time' dialog.
	This should usually be set to a value well over the fast timestep to
	avoid wasting CPU cycles.

6.4.5	Higher order reacs disabled/enabled
	This toggle allows one to build higher-order reactions. Consider
	pool A, and reac R. Normally, the first time you drag A to R you
	set up a reaction pathway, and the second time you drag A to R
	you remove it. To create a reaction with an order of 2,
	you need to flip this toggle to

		Higher order reacs enabled

	before dragging A to R a second time. Note that the toggle reverts
	to the 'disabled' state each time it is used, to avoid confusion.

	This toggle also works for dragging pools to enzymes.

6.4.6 pool-to-pool uses CONSERVE / pool-to-pool uses SUMTOTAL
	This toggle flips between using CONSERVE and SUMTOTAL when
	connecting pools to each other. Each case is described below.

	The CONSERVE message is used when you wish to explicitly set up
	conservation relationships between a group of pools. Suppose a
	molecule A can exist alone, bound to B as AB, and bound to C as
	AC. If you wish to have A calculated by conservation relationships,
	just drag AB to A and AC to A. This bypasses the normal calculations
	for A, and assures that the conservation relationships will be
	satisfied.
	Normally the differential equations for each reactant provide
	sufficient accuracy to ensure that the conservation relationships
	are satisfied.
	In some cases (e.g., very fast rates for one reaction step)
	you may prefer to use conservation instead to improve stability
	and accuracy. Be sure to check on stability - you can get
	interesting numerical oscillations in some cases. The conservation
	facility should not be used lightly, as it is easy to leave out
	something that should be part of the conservation scheme. For
	example, enzymes may contribute to the conservation scheme too.
	You may also find that you get better stability by arranging the
	conservation scheme differently: e.g., AB as the conserved
	quantity rather than A.

	The SUMTOTAL message is used when several pools have an
	identical activity, for instance a common enzyme site
	activated in several different ways.  Each of the contributing
	pools in this example would send a SUMTOTAL message to the pool
	representing the enzyme. The summed pool would behave as a
	normal enzyme except that its nTotal is now the sum of the
	SUMTOTAL messages.  It is assumed that the activity site is
	independent of the regulation site(s). In other words, the
	contributing pools do not care how much of the summed pool
	is in an enzyme complex or even taking part in other reactions.
	Thus, if one were to take a single pool A, and send a SUMTOTAL
	to another pool B, and hang an enzyme off B, this would NOT be
	the same as having the same enzyme attached to A.
	In the first case all of A would always be available for other
	reactions.
	In the second case the amount of A available for other reactions
	would be determined by how much was busy complexing with the enzyme.

6.4.7	Normal enz-to-pool: not CONSERVE / Enz-to-pool uses nComplex for
	CONSERVE
	This toggle is used when you wish to set up conservation relationships
	involving enzyme complexes. Although the number of molecules in
	the enzyme complex is usually small, you can't just ignore them
	when doing conservation relationships. See the previous
	section (6.4.6).

6.4.8	Normal enz-to-pool: not SUMTOTAL / Enz-to-pool uses nComplex for
	SUMTOTAL
	This toggle is used when you wish to use the SUMTOTAL message
	involving enzyme complexes.

6.4.9	Normal pool-to-enz: not INTRAMOL / pool-to-enz uses n for INTRAMOL
	This toggle is used when you wish to set up intra-molecular reactions.
	In this situation, the number of enzyme sites available per substrate
	is _not_ a function of concentration of the enzyme. So we need to
	divide out the enzyme conc by the concentration of the entire
	pool of enzymes. Hence the INTRAMOL message.
6.4.10	Normal pool-to-reac : not KF / pool-to-reac uses Co for kf
	This toggle allows you to add messages that specify the kf of a 
	reaction. This provides a great deal of flexibility in designing 
	models, at the expense of some rigor. As a philosophical point, I feel
	that most biological reactions do not work by directly modifying rates,
	but rather by forming different molecular species wich react at 
	different rates.
	The source of the kf message is Co from a pool, rather than
	n. The idea is that the Co field can be scaled (by the volume field)
	which lets one put in scale factors.
	As soon as this option has been used in creating a message, the toggle
	is turned off again so that the usual messaging can be resumed.
	Removal of the KF message requires that this toggle again be activated,
	otherwise the usual pool-to-reac operations will be assumed.
6.4.11	Normal pool-to-reac : not KB / pool-to-reac uses Co for kb
	This toggle controls the kb rate constant in the same manner as
	described above. Note that the KF and KB toggles are exclusive, you
	cannot have both of them on at the same time.

6.5 Graphs menu
----------------------
6.5.1	Show More graphs
	This toggle causes the display/hiding of an extra couple of graph
	widgets. These may be useful in models where there are so many
	interesting reactions that the default two are not enough.
6.5.2	X-axis Max 
	X-axis Min 
	Y-axis Max 
	Y-axis Min 
	These four dialogs do the obvious thing. The changes affect all
	graphs, including the 'moregraphs'
6.5.3	Clock dt for plots
	This sets the timestep for all the plots.
6.5.4	Do not overlay plots / Overlay all plots
	This toggle lets you flip between overlay and usual modes. In the usual
	mode, all previous points in a graph are erased on reset. In the
	overlay mode, each existing plot is retained and a new plot started
	when the reset button is hit.
6.5.5	Plots enabled / Plots disabled
	This toggle allows one to run a model with or without the plots
	active. Useful if you are using some other way of monitoring a
	simulation and wish to avoid the overhead of plotting.
	This toggle requires a reset in order to become effective.
6.5.6	Delete all plots
	Does what it says.
6.5.7	Save all plots to file:
	This saves all the plots in a single file in xplot format,
	in which each line has a pair of x,y  coordinates.
	Different plots in the same file are identified by '/newplot'
	and '/plotname ...' at the start of the coordinate list. It should
	be easy to extract the plots you want from this file.
	
6.6 Help menu
----------------------
This pops up the Help form. Most of the Help form is a text widget with the
contents of this kkit help file displayed. There is also a button for
redisplaying the 'About kkit' notice that appears on startup.

=============================================================================
7. Objects in kkit
Each kkit object has three facets: the computational entity, the icon,
and the edit panel.
The first does the actual work, and takes the form of an instance of a
Genesis object such as a pool, or a reaction, etc.
The icon represents this object and provides
a convenient handle for manipulations.
The edit panel (which pops up on double-clicking the icon) is used to
change values for the computational entity. The edit panel has several
fields which are common to all objects:

Parent:	This is the full path of the parent of the current element.
	It is a read-only field
Name:	The name of the current element. Editable.
Color:	Color of the icon.
NOTES:	There is a text widget for entering notes, and a big NOTES button
	beside it for storing the contents of the widget to the element.
	A common mistake is to forget to click the NOTES button after
	changing the text for the notes.
UPDATE:	This button refreshes the value of the dialogs. It is mainly used
	when the simulation is running, if you want to get an exact
	numerical value for the variables in an element.
HIDE:	Gets rid of the edit panel.

Note that there is only one edit panel for all elements of a given class.
In other words, when you look at the values for two different pools, you
are actually using the same edit panel, just with different values inserted.
This arrangement is nice because it saves memory (imagine having a complete
edit panel stored for each pool in a big model). However, it is annoying
when you wish to look at the values for two or more pools at the same time.
Various solutions to this problem are being considered, and ideas are welcome.

------------------------------------------------------------------
7.1	Object:		Groups

	Computation:
			Groups do not perform any calculations.
			They are the basis for organizing complex models.

	Icon:		A star

	Icon manipulations:
			Moving self and children of group.
			Dragging onto other groups

	Edit panel:	
		- Expanded/Contracted toggle
		This displays / hides the children of the group.
		When contracted the group looks overlaid.

		- Move children.../Move group alone
		The group normally pulls its children along when moved. This
		toggle lets you move the group without disturbing its kids.

		- Initialize all children to current amounts
		This button is useful for models which need to start at
		an equilibrium level which takes a while to attain. Just
		click the 'Initialize' button, once the model has
		equilibrated. Now the 'CoInit' fields are set to the
		equil value, and the model will be equilibrated at reset.
		This button should be used with caution, however. Make sure
		that you have saved the version used to derive the
		equilibrium, in case you wish to change conditions
		later. This is specially applicable to models which
		you later wish to merge, since any change to the model
		will change equilibrium levels.  

		- save_group
		This dialog lets you save the specific group and all its
		children, while leaving the rest of the model alone. The
		save routine attempts to also save all elements which 
		are directly linked to the kids of this group via messages.
		It is recommended that all such linked-in elements be on
		the /kinetics element, rather than on other groups.
------------------------------------------------------------------
7.2	Object:		Pool
	Computation:	Solves the actual differential equations. All
		computations are in terms of 'n', the number of molecules
		of the chemical species. As a useful facility, the
		concentration Co is also computed by dividing n by the volume.
		Note that one usually works out a sensible scaling factor
		to use for the 'volume', so that the units for Co are
		sensible. I typically use micro-molar.
			The pool equations use the _changes_ computed
		by the reacs, enzymes, etc. So the pools are the only
		element in the kinetics code which actually solves
		differential equations. The others provide the rates.
			Pools have numerous other numerical facilities.
		The most important of these is buffering, in which the
		pool does not compute at all, and just stays at the level
		of its nInit. Be warned that buffering and stimulus inputs
		violate conservation of mass in the reaction system,
		because they represent processes not being directly modeled.
			Conservation of mass is normally represented
		implicitly in the differential equations. There is
		provision for explicitly setting up mass conservation,
		but this can be numerically tricky. See section 6.4.
			All computations are carried out using the
		exponential Euler form. This turns out to be remarkably
		efficient and accurate, but is far from the best. There
		is some ongoing work on a fast, accurate solver 'ksolve',
		which will take over the computations in a kinetic model
		in much the same way that the hsolve does in a cell model.

	Icon:		A filled rectangle
	Icon manipulations:
		Moving self
		Dragging onto reacs - hooking up and disconnecting reactions.
		Dragging onto enzymes - hooking up and disconnecting.
		Dragging onto groups - grouping
		Dragging onto other pools - conservation
		Dragging onto other pools - SUMTOTAL. This is used when
			one wishes to have a pool whose level is the sum of
			several others. If one has numerous enzyme isoforms
			with the same activity this is one way to go about
			implementing it.
		Dragging onto graph - plot conc of pool
		Dragging from table or stim: override pool levels by table
			or stim output. Does NOT override buffering, though.
	Edit panel:
		- n fixed, conc changes/ Conc fixed, n changes toggle
		This toggle lets you choose which set of values to treat
		as a reference when changing the volume. It rarely matters
		once the volume is settled.
		- n dialog
		Set/display the current number of molecules of the pool
		- nInit dialog
		Set/display the number of molecules to which pool will be
		initialized, or buffered if buffering is ion.
		- nTotal dialog
		Set/display the total number of molecules (including in
		compounds with other pools) of this species. Used mainly for
		conservation conditions.
		- nRemaining dialog
		nRemaining = nTotal - n
		- Co, CoInit, CoTotal, CoRemaining dialogs
		Equivalents to the corresponding 'n' based dialogs, scaled by
		volume.
		- vol dialog
		Volume to use for scaling Co from n. Co = n / vol
		- Buffering OFF/ Buffering ON toggle
		Toggle for buffering by this pool. Buffering holds the 
		Co/n fixed at CoInit/nInit. It overrides all other inputs
		to pool.



------------------------------------------------------------------
7.3	Object:		Reacs
	Computation:	Computes the product of kf with 'n's for forward
		reactions, and kb with 'n's for backward reactions, and sends
		this info on to the pool for the integration. Higher order
		reactions are somewhat inefficiently represented simply as
		multiple incoming messages for the 'n's.
	Icon:	Bidirectional arrow.
	Icon manipulations: 
		Moving self
		Dragging onto pools for products
		Dragging reactant pools onto reac.
	Edit panel:
		- kf dialog: Forward rate constant
		- kb dialog: Backward rate constant

------------------------------------------------------------------
7.4	Object:		Enzymes
	Computation:
		Consider the Michaelis - Menten formulation of an
		enzymatic reaction:

		Enz + Sub <---k1---k2---> Complex ---k3---> Prd + Enz

		Given the enzyme, substrate, and product pools, this
		could be implemented as two reacs and a pool for the complex.
		The enz object does all this for you, i.e., it represents
		the reacs and the enzyme complex pool. 
		Since the enzyme object only makes sense in conjunction
		with an enzyme pool, we require that it be created on a pool.
	Icon:
		Text on black background.
	Icon manipulations:
		Movement with respect to parent pool. Note that if the pool
			is moved, the enzyme does too.
		Dragging substrates into enzyme
		Dragging enzyme onto products
		Dragging enzyme onto graph to plot CoComplex
	Edit panel:
		- k1, k2, k3 dialogs: rate constants.
		- vol dialog :
			Volume to use as scaling factor to calculate Co from n
		- Enz complex is hidden / Enz complex is available (toggle): 
			In most cases the enzyme complex is a distinct
			molecular species that cannot undergo all the same
			reactions as the free enzyme pool. So the portion of
			the enzyme pool that is bound as complex is 'hidden'
			from other reactions. Occasionally one wishes to
			make the complex form undergo the same reactions as the
			parent pool, hence this toggle.
			Note that the conc of the enz complex is usually
			vanishingly small.

		- nComplex dialog: Number of molecules of the complex
		- nComplexInit dialog: Number of molecules of the complex to
			initialize the enzyme with.
		- CoCompex, CoComplexInit: Same as above 'n' values, scaled by
			vol.
------------------------------------------------------------------
7.5	Object:		Channels
	Computation:
		Calculates concentration gradient and scales by the
		permeability to give flux of molecules through the channel.
		The number of channel molecules is determined by the
		parent pool, so we require that it be created on a pool.
		Note that at this point we do not consider any electrical
		properties of the channel. This development is under 
		consideration.

	Icon:	Figure meant to represent a ligand gated channel
	Icon manipulations:
		Movement with respect to parent pool. Note that if the pool
			is moved, the channel does too.
		Dragging conducted ions to and from channel. 
	Edit panel:
		n dialog: 
		Duplicate of value of n of parent pool.
		perm dialog: Scale factor for permeability.
		gmax : Not currently used.
------------------------------------------------------------------
7.6	Object:		Stims
	Computation:
		Generates repetitive step stimuli. Composite
		object subclassed from the on the pulsegen object.
	Icon:		Lightning bolt.
	Icon manipulations:
		Moving self
		Dragging onto pools for setting up stim
		Dragging onto graph to monitor activity.
	Edit panel:
		Stim width dialog: Specifies duration of 'on' phase of
			stimulus pulse.
		Level uses # units / Level uses concentration units toggle:
			The title says it all
		Baseline level: Specifies level of 'off' phase of stimulus.
		Stim level: Specifies level of 'on' phase of stimulus.
		Interpulse delay: Specifies duration of 'off' phase of pulse.
		Stimlus OFF: click to start / Stimlus ON: click to stop toggle:
			The title says it.
------------------------------------------------------------------
7.7	Object:		Tables
	Computation:
		Reads out a stored waveform for use as a stimulus. The
		waveform can be read in from a file, or specified graphically
		through the edit panel. The waveform can loop, i.e., 
		repeat cyclically, or go through once only. It can
		start at a specified time. Although the waveform values
		are stored in a discrete table, the output is interpolated
		on every timestep so that transitions are smooth.
		Normally 100 data points are available for graphical
		specification, but any number of points can be read in
		from a file in xplot format (x y coords, separated  by spaces,
		1 x y pair per line).
		Assorted scaling operations are also available.
	Icon:	A table, as in furniture. Pun intended.
	Icon manipulations:
		Moving self
		Dragging onto pools for setting up stimulus
		Dragging onto graph to monitor activity.
	Edit panel:
		This is a two-page panel, because there are so many options.
		Page 1:
				Stimulus run options
		Open stimulus waveform options button: pops up the
			waveform page (2).
		Looping disabled/Looping enabled: Toggles whether the
			waveform will be generated once, or cycle when
			finished.
		loop_duration: Specifies the length of the waveform in
			simulation time. No matter how many points the
			table has, it will run through them with this
			duration. Interpolation is used if the time steps
			do not fall exactly on table entries.
		loop_start: Simulation time at which to start generating
			output for the table. For example, if one
			wished to let the model equilibrate for 50 sec
			before delivering a stimulus, one would set this
			value to 50
		Stimlus OFF: click to start / Stimlus ON: click to stop toggle:
			The title says it.
		
				File loading info:
		load_xplot_file: This dialog specifies and reads in
			a file in xplot format for the data points in the
			table.
		skip_lines: This dialog tells the loading routine how
			many lines to skip from the top of the file
			when loading it.
		xdivs: Specifies the number of divisions to allocate for
			the file. The file data will be squashed or
			stretched using interpolation, to fit into exactly
			this number of _divisions_, so the number of
			points = xdivs+1.

		Page 2: 
				Stimulus waveform options
		Open stimulus run options button: pops up the run page (1).
		Graph window: This window is for displaying and editing
			the stimulus waveform. Clicking on the window
			will cause the clicked point to be entered in the
			table. The displayed waveform will change accordingly.
			In addition, the clicked coords are displayed in the
			X1, Y1, X2, Y2 dialogs in the Interpolation options
			section.
		Flat line button: Clears all the data points in the table 
			and sets them to the value in the Baseline level 
			dialog.
		Baseline level: see above.
		Output is #/ Output is conc: This toggle determines whether
			the output value is treated as # of molecules,
			or concentration.

				Interpolation options
		X1: First X coord for steps and interpolation. Normally
			set by the location of the mouse click in the
			graph window. Can be incremented/decremented by
			the adjoining + and - buttons.
		Y1: First Y coord.
		X2: This takes the previous value of X1, every time there
			is a new mouse click. Can also be explicitly set
			from the keyboard, or adjusted using the neighboring
			+ and - buttons.
		Y2: Second Y coord. 
		Step: This button causes all table entries between X1 and X2
			to be filled with the value in Y1.
		Interpolate: This button causes all table entries between
			X1 and X2 to be interpolated between Y1 and Y2.
		Smooth: This is not yet implemented. Someday it will do
			smoothing of the curve in the table.
		
				Scaling options
		General: There are two entities involved in all these
		operations. First, the table itself, which is used in 
		the simulation. Second, the plot used to display it. Normally
		the plot entries are set to the same values as the table
		entries. However, when scaling, the operations are all 
		carried out on the plot only, so as to give the user a 
		chance to reconsider. If you are sure that the waveform
		has been suitably mutated for your needs, then you can
		hit the 'Apply' button to copy the modified entries into the
		table.
		y_scale_factor: Multiplies all Y entries by factor.
		y_offset: adds offset to all Y entries.
		x_scale_factor: Multiplies all X entries in plot by factor.
			When the changes to the plot are applied to the
			original table, then the limits of the table are
			adjusted to match these changes.
		x_offset: Adds offset to all X entries.
			When the changes to the plot are applied to the
			original table, then the limits of the table are
			adjusted to match these changes.
		Log, Exp, Log10, Exp10: Performs the specified operations
			on the Y entries in the table.
		Apply: Write the changes in the plot to the original table.
		Undo: Write the entries from the original table into the
			plot, erasing any changes that may have been made to
			the plot.
------------------------------------------------------------------
7.8	Object:		Plots
	Computation:	Displays and stores simulated values. Can 
			perform compression, slope calculations and scaling
			on the data points.
	Icon:		The name of the plot in the graph window, but nothing
			on the edit window.
	Icon manipulations:
			Dragging to Barney (the delete icon) to delete the plot
			Double-clicking for manipulating the plot.
	Edit panel:
		Compression cutoff: The plot uses lossy compression: it only
			stores data points whose y values differ from the
			last stored value by more than a predefined amount.
			This dialog specifies the amount. It defaults to zero,
			which means no compression. For long simulations,
			it is a good idea to use compression as plots can
			use up enormous amounts of memory.
		Slope calculation mode OFF/ON: This toggles the 'slope' mode
			of plotting. In slope mode, the y values are
			differentiated with respect to time.
				plotval = (y(t) - y(t-1))/dt
		Y Offset: Offsets plot by specified amount in Y axis.
		Y Scale: Scales plot by specified amount in Y axis.
		Save to file: Stores plot data in specified filename. The
			format is
				x1 y1
				x2 y2
				x3 y3
			etc; i.e, one coordinate pair per line separated by
			spaces.

=============================================================================

8. Library of models
A library of 'modules' of signaling pathways developed using kinetikit
are available. These modules include
PKC
MAPK
Ras
Gq
PLC-beta
PLA2
Ca
and many others. Please contact me at bhalla@ncbs.tifrbng.res.in to get
hold of them. They will also make their way onto Babel and the ncbs and
Genesis www sites sometime in 1997.

=============================================================================
9.  Customizing
	The first and main bit of customizing you are likely to do has
to do with the default size of the windows. These are defined in
PARMS.g, with commented out values for common screen sizes.
	Most of the other user-configurable settings are also
in PARMS.g, but are unlikely to be very useful since all the info is
stored when you save a model.

=============================================================================
10. Future plans

10.0	HTML-izing this document

10.1	Embedded modules.

10.2	Merging in with the suite of 'kits' under development.

10.3	Bug reports:
Please send bug reports relating to kinetikit (and only to kinetikit) to

bhalla@ncbs.tifrbng.res.in

I cannot guarantee a quick reply, but I will try to fix things as they
turn up. Please do _not_ send me general questions regarding Genesis and
its installation. These are more appropriately addressed to the Genesis
and Babel addresses:
genesis@bbb.caltech.edu
babel@bbb.caltech.edu


=============================================================================
11. Acknowledgements

This project owes its existence to many people and organizations, of whom I
can only mention a few.

The Aaron Diamond Foundation. Part of this project was developed while I was an
Aaron Diamond Foundation Fellow at Mt. Sinai, and this work was supported
in part by a grant from the Aaron Diamond Foundation.

Ravi Iyengar, my mentor at Mt. Sinai, who encouraged me with this
modeling project while making sure I got my hands wet with experiments, too.

The Genesis development team, for providing the coding foundation, and
specially Dave Bilitch and Dave Beeman, who imposed higher
standards on my compulsively relaxed concept of a 'release' version.

Various alpha testers, including Francis Horber and Bruce Graham, who
provided valuable feedback.

The Linux, XFree86 and GNU projects, for building an amazing free OS on which
much of the development was done.

My wife and son, for quietly/vocally putting up with this distraction from
other responsibilities.

=============================================================================