===============================================================================
-------------------------------------------------------------------------------
This will reproduce the model figures of peron and gabbiani 2009, which at this
time is "in press" with Nature Neuroscience:

  "Spike Frequency Adaptation Mediates Looming Stimulus Selectivity in a 
	  Collision-Detecting Neuron"

[Eventually, we hope to add a more in-depth exploration of the model which
has been submitted to another journal; for this reason you will see references
to nature neuro.  In the final version, the two will be submitted as one 
package since both use the same underlying model]

-------------------------------------------------------------------------------
  File Summary and General Summary of Model Implementation
-------------------------------------------------------------------------------
In a nutshell, three components are included:

  1. MATLAB scripts that generate simulations to run for both instances.
	2. A MATLAB parallel execution system that runs these simulations.
	3. MATLAB scripts to generate the manuscript figures

All simulations were performed on an 8-core Mac Pro running OS X 10.5.4.  
It shoudl also work well on Linux machines (an earlier though very similar
version of simulations were performed on a Fedora Core 8 box, again with 8
cores).  If you are using Windows, I know a good support group ... (seriously,
it should work with minor tweaks, but why are you doing this to yourself?).

Directories (children of the one you untar scripts in):

nn_par_out: output for nature neuro simulations
nn_par_mat: parallel .mat files (See below) for nature neuro simulations

Here is a detailed description of each file and what it contributes:

acute_synmap.mat, uniform_synmap.mat: used to tell the simulation generator
  where each ommatidium points to in visual space so that the visual stimulus
	activates appropriate ommatidia.  "acute" is based on the realistic sampling
	of visual space by the locust eye as inferred by Krapp and Gabbiani (2005),
	while "uniform" samples space uniformly with the same number of ommatidia 
	(~7500) as the acute map. 
daemon.m: Runs simulations generated by generate.m; run as many instanses of
  MATLAB as you have cores on your computer, invoking the daemon in each one.
generate.m: This generates .mat files that each define INDIVIDUAL simulations
  run by the parallel daemon.
generate_simulations.m: A wrapper for generate.m that calls that generator with
  the specific commands for all simulation classes.
get_curinj_pattern.m: used by simulation generator to obtain current injection
  for pseudotranslation with various accelaration profiles.
get_curinj_vec.m: used by post-simulation analysis script to get current inj.
  shape for pseudolooming stimuli -- for plotting purposes.
get_general_model_settings.m: this is the heart of the parameter definitions;
  you will notice one set of parameters for nature neuroscience and one for
	XXXXX.
get_inst_freq.m: computes instantaneous frequency plot.
get_spikes.m: extract spike timings based on a threshold.
get_synaptic_noise.m: generates a synaptic noise conductance vector.
get_synaptic_pattern.m: generates synaptic input for visual stimuli - much more
  relaistic than current injection vector based simulations.
nn_par_model.sh: Execution of parallelized daemon for nature neuro sims.
plot_nn_sims.m: plots the nature neuroscience figures
readme.txt: a very mysterious file (warning: self-reference detected).
three_cmpt.m: the core of the simulator; this is the script that runs using 
  an ODE solver and actually runs most of the code.
uniform_synmap.mat: see acute_synmap.mat

-------------------------------------------------------------------------------
  Step-by-Step Instructions for Replicating Paper Figures
-------------------------------------------------------------------------------
  
	1. Create the output directories (see above).  They should appear when
	   you untar, but empty.  If not, however, make them.

	2. Run generate_simulations.m.  This should populate nn_par_mat dir.

	3. Run the shell scripts --  nn_par_model.sh -- separately
	   so that you use all your cores.  For instance, if you have 8 cores, I 
		 would suggest running nn_par_model.sh 7 times.  

     WARNING: The shell script makes assumptions about where your matlab is;
     make sure this is correct.  Also, be aware that this uses the UNIX 
		 utility screen, which allows running of processes in background that are
		 login-independent (i.e., you can close terminals and logoff a computer
		 and process will keep running).  Be familiar with screen if you want
		 to use this; otherwise, run the daemons MANUALLY (to figure out how,
		 look at the shell script!).

		 To stop the run (you can do this at the end to kill the processes or you
		 can leave, shut down, come back, and resume by running the shell script
		 again), create a file "stop_par.m" in the xx_par_mat directory.

	4. Run the analysis to plot figures -  plot_nn_sims.m.

-------------------------------------------------------------------------------
  Miscellaneous Notes
-------------------------------------------------------------------------------

  1. The papers included mention of simulations with and without feed-forward
	   inhibition; if you want to run simulations *without* feed-forward inhib.,
		 you should still include spontaneous inhibitory activity.  Go into 
		 get_general_model_settings, and change, for one (or both) of the parameter
		 sets (nature neuro) ps_mod.g_max_syn_inh to 0.