Merge pull request #944 from heplesser/fix-hh-cond-exp-traub-tref

Better documentation of hh_cond_exp_traub and Brette-2007-compatible refractory time

doc/quickref.html

@@ -485,15 +485,15 @@ <h3>Neuron Models</h3>
     </tr>
     <tr>
       <td width="25%"><a href="help/cc/hh_psc_alpha.html">hh_psc_alpha</a></td>
-      <td>Hodgkin Huxley neuron model.</td>
+      <td>Hodgkin-Huxley neuron model.</td>
     </tr>
     <tr>
       <td width="25%"><a href="help/cc/hh_psc_alpha_gap.html">hh_psc_alpha_gap</a></td>
-      <td>Hodgkin Huxley neuron model with gap-junction support.</td>
+      <td>Hodgkin-Huxley neuron model with gap-junction support.</td>
     </tr>
     <tr>
       <td width="25%"><a href="help/cc/hh_cond_exp_traub.html">hh_cond_exp_traub</a></td>
-      <td>Hodgkin Huxley based model, Traub modified.</td>
+      <td>Hodgkin-Huxley model for Brette et al (2007) review.</td>
     </tr>
   </tbody>
 </table>

models/hh_cond_exp_traub.cpp

@@ -148,7 +148,7 @@ nest::hh_cond_exp_traub::Parameters_::Parameters_()
   , E_in( -80.0 )
   , tau_synE( 5.0 )  // Synaptic Time Constant Excitatory Synapse (ms)
   , tau_synI( 10.0 ) // Synaptic Time Constant Excitatory Synapse (ms)
-  , t_ref_( 0.0 )    // Refractory time in ms
+  , t_ref_( 2.0 )    // Refractory time in ms
   , I_e( 0.0 )       // Stimulus Current (pA)
 {
 }

models/hh_cond_exp_traub.h

@@ -57,25 +57,37 @@ extern "C" int
 hh_cond_exp_traub_dynamics( double, const double*, double*, void* );
 
 /* BeginDocumentation
-Name: hh_cond_exp_traub - Hodgkin Huxley based model, Traub modified.
+Name: hh_cond_exp_traub - Hodgkin-Huxley model for Brette et al (2007) review
 
 Description:
 
  hh_cond_exp_traub is an implementation of a modified Hodgkin-Huxley model
 
- (1) Post-synaptic currents
- Incoming spike events induce a post-synaptic change of conductance modeled
- by an exponential function. The exponential function is normalized such that an
- event of weight 1.0 results in a peak current of 1 nS.
+ This model was specifically developed for a major review of simulators [1],
+ based on a model of hippocampal pyramidal cells by Traub and Miles[2].
+ The key differences between the current model and the model in [2] are:
 
- (2) Spike Detection
- Spike detection is done by a combined threshold-and-local-maximum search: if
- there is a local maximum above a certain threshold of the membrane potential,
- it is considered a spike.
+ - This model is a point neuron, not a compartmental model.
+ - This model includes only I_Na and I_K, with simpler I_K dynamics than
+   in [2], so it has only three instead of eight gating variables;
+   in particular, all Ca dynamics have been removed.
+ - Incoming spikes induce an instantaneous conductance change followed by
+   exponential decay instead of activation over time.
 
-Problems/Todo:
-Only the channel variables m,h,n are implemented. The original
-contains variables called y,s,r,q and \chi.
+ This model is primarily provided as reference implementation for hh_coba
+ example of the Brette et al (2007) review. Default parameter values are chosen
+ to match those used with NEST 1.9.10 when preparing data for [1]. Code for all
+ simulators covered is available from ModelDB [3].
+
+Note:
+ In this model, a spike is emitted if
+
+          V_m >= V_T + 30 mV and V_m has fallen during the current time step
+
+ To avoid that this leads to multiple spikes during the falling flank of a
+ spike, it is essential to chose a sufficiently long refractory period.
+ Traub and Miles used t_ref = 3 ms [2, p 118], while we used t_ref = 2 ms
+ in [2].
 
 Parameters:
 
@@ -92,7 +104,7 @@ contains variables called y,s,r,q and \chi.
                      function in ms.
  tau_syn_in double - Time constant of the inhibitory synaptic exponential
                      function in ms.
- t_ref      double - Duration of refractory period in ms.
+ t_ref      double - Duration of refractory period in ms (see Note).
  E_ex       double - Excitatory synaptic reversal potential in mV.
  E_in       double - Inhibitory synaptic reversal potential in mV.
  E_Na       double - Sodium reversal potential in mV.
@@ -103,8 +115,12 @@ contains variables called y,s,r,q and \chi.
 
 References:
 
-Traub, R.D. and Miles, R. (1991) Neuronal Networks of the Hippocampus.
-Cambridge University Press, Cambridge UK.
+[1] Brette R et al (2007) Simulation of networks of spiking neurons: A review
+    of tools and strategies. J Comp Neurosci 23:349-98.
+    doi 10.1007/s10827-007-0038-6
+[2] Traub RD and Miles R (1991) Neuronal Networks of the Hippocampus.
+    Cambridge University Press, Cambridge UK.
+[3] http://modeldb.yale.edu/83319
 
 Sends: SpikeEvent
 

models/hh_psc_alpha.h

@@ -58,7 +58,7 @@ namespace nest
 extern "C" int hh_psc_alpha_dynamics( double, const double*, double*, void* );
 
 /* BeginDocumentation
-Name: hh_psc_alpha - Hodgkin Huxley neuron model.
+Name: hh_psc_alpha - Hodgkin-Huxley neuron model.
 
 Description:
 

models/hh_psc_alpha_gap.h

@@ -60,7 +60,7 @@ extern "C" int
 hh_psc_alpha_gap_dynamics( double, const double*, double*, void* );
 
 /* BeginDocumentation
-Name: hh_psc_alpha_gap - Hodgkin Huxley neuron model with gap-junction support.
+Name: hh_psc_alpha_gap - Hodgkin-Huxley neuron model with gap-junction support.
 
 Description:
 

testsuite/unittests/test_hh_cond_exp_traub.sli

@@ -61,11 +61,11 @@ ResetKernel
    /E_Na    40.0
    /E_K    -80.0   
    /E_L	   -70.0
-   %/U_tr   -60.0
    /E_ex     1.0
    /E_in   -90.0
    /tau_syn_ex 0.3
    /tau_syn_in 3.0
+   /t_ref    3.5
    /I_e	     1.0
 >> /hh_params Set
 
@@ -85,6 +85,7 @@ neuron GetStatus /result Set
   result /E_in get 6 ToUnitTestPrecision -90 eq and
   result /tau_syn_ex get 6 ToUnitTestPrecision 0.3 eq and
   result /tau_syn_in get 6 ToUnitTestPrecision 3 eq and
+  result /t_ref get 6 ToUnitTestPrecision 3.5 eq and
   result /I_e get 6 ToUnitTestPrecision 1 eq and
 } assert_or_die
 
@@ -115,7 +116,7 @@ vm neuron Connect
 mm neuron Connect
 neuron sp_det Connect
 
-%% Test: Simulation
+%% Test: Simulation --- check that implementation provides consistent results
 5 Simulate
 
 {
@@ -150,5 +151,5 @@ neuron sp_det Connect
 
 {
   sp_det [/events /times] get cva dup ==
-  [2 3 4 5 6 7] eq 
+  [2] eq 
 } assert_or_die