Notes on the conjugate gradient parameter search demo
-----------------------------------------------------

This demo is an extremely simple example of how to use the conjugate
gradient-descent parameter search object (paramtableCG) to run a parameter
search.  The process is as follows:

1) We take a very simple one-compartment model with three active
   conductances: fast Na, delayed-rectifier K (Kdr) and slow,
   noninactivating K (M-current; KM).  We generate a target data set
   and pretend that this is our experimental data set that we have to
   match.

2) We vary several of the starting parameters of the model:

   a) Gbar (maximal conductance) of the Na channel
   b) Gbar of the Kdr channel
   c) Gbar of the KM channel
   d) Scaling factor for the time constant of the KM channel activation
   e) Midpoint of the activation curve of the KM channel

   The Gbar values are varied in the cell parameter file (cell.p); the
   original (correct) values are in the file origcell.p.  The time
   constants are varied by uniformly scaling the tau(V) values of the KM X
   gate using the scaletabchan function.  The midpoint of the activation
   curve is varied by offsetting the minf(V) values of the KM X gate, again
   using the scaletabchan function.  Both of these scalings are done in the
   channels.g file.

   The resulting model is our starting point for the parameter search.  We
   refer to it as the initial model.

3) We choose some reasonable range inside of which we are going to search
   for the correct parameters.  The correct parameters are those that
   "undo" the variations we introduced in (2).  They are the parameters
   that will change the initial model into a model that can generate the
   same output as our target data set.  In this case, we know that there is
   a correct parameter set inside of the ranges we have chosen.

4) We run the parameter search, which will chug along until it finds a
   parameter set that is very close to the correct set (if all goes well).

The main purpose of this demo is to show you, with working GENESIS scripts,
how to set up and run a parameter search using the paramtableCG object.  We
encourage you to rip off parts of this code and adapt it for your own use.
In particular, the params.g and search.g file can often be used in new
simulations with a slight amount of adaptation (mostly in params.g).

The parameter search is run from a Makefile using the Unix "make" command.
This is mainly for convenience; make just calls other commands to do the
real work.  Here are the commands:

    make clean      -- cleans up all output files generated by the parameter
                       search
    make ultraclean -- also removes all the target data files
    make orig       -- regenerates the target data files
    make search     -- runs a parameter search
    make resume     -- resumes a partially-completed parameter search
    make view       -- displays the output from the parameter search
                       (requires xplot; see below)

The command "make ultraclean" is really for us, the developers of the
demo; you shouldn't have to use them unless you have messed up the Vm.data
and/or Vm.spk.data files.  The command "make orig" needs to be run once in
order to generate the Vm.data file, which is not provided here, in order
to save space.  It also regenerates the Vm.spk.data file, so you may use
it should you accidentally delete the Vm.data and/or Vm.spk.data files.

We recommend that you use two terminal windows for the search; in one
window type "make search" to get the search running while in the other type
"make view" periodically to see how well the simulation results compare to
the data.  This assumes that you have installed the xplot program, and that
you have generated the Vm.data file, which is used only for this
comparison.

The best parameter values obtained so far are saved in the file
"best.params" while the correct parameters are in the file "goal.params".
A list of the best match values as a function of simulation number is kept
in the file "match.values" and is updated every 100 iterations.  While the
search is running, GENESIS will output some data such as the simulation
number, the current match, the best match so far, etc. and will also
output the best parameter set every time a new one is found.  You can
periodically compare "best.params" with "goal.params" as the search is
running to get an idea of how far the best parameters are from the correct
values.  As the search proceeds, they should get closer and closer.

Typing "make search" invokes GENESIS indirectly by invoking the "CG_run"
shell script.  CG_run starts GENESIS, which goes on for 1000 more
simulation iterations or until the parameter search is finished.  Once it's
done, GENESIS exits, leaving a number in the file "sim_status".  If the
number is 1, the search isn't finished and GENESIS will automatically be
restarted and the search will be restored to where it left off.  If the
number is 2, the search is finished.  The number is 0 at the very beginning
of the search only.

Why, you are no doubt asking, do we go to all this trouble?  The reason is
that in real production-quality parameter searches, the searches often go
on for days or even a couple of weeks.  As GENESIS runs and objects are
created and deleted, small memory leaks build up and will eventually crash
the program (and maybe your computer!).  By restarting GENESIS every 1000
iterations we ensure that this will never happen.  But, you ask, why not
just remove all the memory leaks from GENESIS?  Well, this is easier said
than done for a number of reasons.  Even if we can remove 99% of the memory
leaks, what's left will still eat up all the memory if the simulation runs
long enough.  If you want to live dangerously you can hack the scripts
slightly so that the search keeps running until it's done without ever
exiting GENESIS, but you have been warned.

To halt the parameter search while it's running, hit control-C.  This will
get you back into GENESIS, but (unfortunately) you won't see the prompt,
because the search runs in "silent" mode for a variety of reasons.  You
can get the prompt back by typing "silent 0" and then hitting return.
You can also just type "quit" to exit GENESIS.  Since GENESIS is being
invoked by a shell script, it's a good idea to also do a "ps" at the shell
prompt to make sure that the script (CG_run) has also halted, and if not,
to manually halt it by doing a "kill -9" or similar command.  If you want
to resume the search from the last point that was saved (remember, the
search object is only saved every 1000 iterations), type "make resume".

To learn more details about the conjugate gradient-descent algorithm being
used by GENESIS, type "help paramtableCG | more" from the GENESIS prompt,
or see the description in the printed or hypertext GENESIS Reference
Manual.  One unusual feature of this demo is that prior to beginning the
conjugate-gradient search we simulate 100 random points in the parameter
space and then pick the best point as the starting point for the CG
search.  This is done because when matching on spike times (as we do here)
there are large volumes of parameter space where the gradient is zero;
these generally correspond to regions where no spikes are generated.  The
CG method doesn't work in such regions, so we have to find a region where
there is a gradient.  In general, unless you are incredibly unlucky, the
100 random simulations will give you a point where a gradient can be
calculated.

Why no graphics?
----------------

Those of you who are used to using GENESIS with XODUS graphics e.g. with
Neurokit, may be disappointed that this demo doesn't have any graphics at
all.  This is not an accident.  Graphics are the enemy of the
parameter-searcher.  Graphics waste precious machine cycles that are better
spent doing the actual simulations.  Graphics in general are mainly useful
for highly interactive simulations (like Neurokit) where many parameters
can be tweaked by hand.  However, our view is that a parameter search is
not much use unless it is fully automated, so that it can run for several
days or even weeks with no user intervention.  In this situation, graphics
are of no benefit, and this demo reflects that.
