Merge pull request #1050 from janhahne/update_rate_docu

Update description of rate model neurons and change parameter names
nest · Dec 10, 2018 · 8e52360 · 8e52360
2 parents 91b3fa7 + bac19cd
commit 8e52360
Show file tree

Hide file tree

Showing 17 changed files with 199 additions and 114 deletions.
diff --git a/models/gauss_rate.h b/models/gauss_rate.h
@@ -56,8 +56,8 @@ The following parameters can be set in the status dictionary.
 
 rate                double - Rate (unitless)
 tau                 double - Time constant of rate dynamics in ms.
-mean                double - Mean of Gaussian white noise.
-std                 double - Standard deviation of Gaussian white noise.
+mu                  double - Mean input.
+sigma               double - Noise parameter.
 g                   double - Gain parameter.
 mu                  double - Mean of the Gaussian gain function.
 sigma               double - Standard deviation of Gaussian gain function.

diff --git a/models/lin_rate.h b/models/lin_rate.h
@@ -60,8 +60,8 @@ The following parameters can be set in the status dictionary.
 rate                double - Rate (unitless)
 tau                 double - Time constant of rate dynamics in ms.
 lambda              double - Passive decay rate.
-mean                double - Mean of Gaussian white noise.
-std                 double - Standard deviation of Gaussian white noise.
+mu                  double - Mean input.
+sigma               double - Noise parameter.
 g                   double - Gain parameter
 mult_coupling       bool   - Switch to enable/disable multiplicative coupling.
 g_ex                double - Linear factor in multiplicative coupling.

diff --git a/models/rate_neuron_ipn.h b/models/rate_neuron_ipn.h
@@ -44,30 +44,49 @@
 namespace nest
 {
 
-/**
- * Base class for rate model with input noise.
- *
- * This template class needs to be instantiated with a class
- * containing the following functions:
- *  - input (nonlinearity that is applied to the input)
- *  - mult_coupling_ex (factor of multiplicative coupling for excitatory input)
- *  - mult_coupling_in (factor of multiplicative coupling for inhibitory input)
- *
- * The boolean parameter linear_summation determines whether the input function
- * is applied to the summed up incoming connections (True, default value) or
- * to each input individually (False). In case of multiplicative coupling the
- * nonlinearity is applied separately to the summed excitatory and inhibitory
- * inputs if linear_summation=True.
- *
- * References:
- *
- * Hahne, J., Dahmen, D., Schuecker, J., Frommer, A.,
- * Bolten, M., Helias, M. and Diesmann, M. (2017).
- * Integration of Continuous-Time Dynamics in a
- * Spiking Neural Network Simulator.
- * Front. Neuroinform. 11:34. doi: 10.3389/fninf.2017.00034
- *
- * @see lin_rate, tanh_rate, threshold_lin_rate
+/** @BeginDocumentation
+Name: rate_neuron_ipn - Base class for rate model with input noise.
+
+Description:
+
+Base class for rate model with input noise of the form
+
+$\tau dX_i(t) = [ - \lambda X_i(t) + \mu
+                + \phi( \sum w_{ij} \cdot \psi( X_j(t-d_{ij}) ) ) ] dt
+                + [ \sqrt{\tau} \cdot \sigma ] dW_{i}(t)$
+
+or
+
+$\tau dX_i(t) = [ - \lambda X_i(t) + \mu
+                + \text{mult\_coupling\_ex}( X_i(t) ) \cdot
+                \phi( \sum w^{ > 0 }_{ij} \cdot \psi( X_j(t-d_{ij}) ) )
+                + \text{mult\_coupling\_in}( X_i(t) ) \cdot
+                \phi( \sum w^{ < 0 }_{ij} \cdot \psi( X_j(t-d_{ij}) ) ) ] dt
+                + [ \sqrt{\tau} \cdot \sigma ] dW_{i}(t)$.
+
+This template class needs to be instantiated with a class
+containing the following functions:
+ - input (nonlinearity that is applied to the input, either psi or phi)
+ - mult_coupling_ex (factor of multiplicative coupling for excitatory input)
+ - mult_coupling_in (factor of multiplicative coupling for inhibitory input)
+
+The boolean parameter linear_summation determines whether the input function
+is applied to the summed up incoming connections (True, default value, input
+represents phi) or to each input individually (False, input represents psi).
+In case of multiplicative coupling the nonlinearity is applied separately
+to the summed excitatory and inhibitory inputs if linear_summation=True.
+
+References:
+
+Hahne, J., Dahmen, D., Schuecker, J., Frommer, A.,
+Bolten, M., Helias, M. and Diesmann, M. (2017).
+Integration of Continuous-Time Dynamics in a
+Spiking Neural Network Simulator.
+Front. Neuroinform. 11:34. doi: 10.3389/fninf.2017.00034
+
+Author: David Dahmen, Jan Hahne, Jannis Schuecker
+
+SeeAlso: lin_rate, tanh_rate, threshold_lin_rate
  */
 template < class TNonlinearities >
 class rate_neuron_ipn : public Archiving_Node
@@ -140,11 +159,11 @@ class rate_neuron_ipn : public Archiving_Node
     /** Passive decay rate in ms. */
     double lambda_;
 
-    /** Gaussian white noise standard deviation. */
-    double std_;
+    /** Noise parameter. */
+    double sigma_;
 
-    /** Gaussian white noise mean.*/
-    double mean_;
+    /** Mean input.*/
+    double mu_;
 
     /** Target of non-linearity.
         True (default): Gain function applied to linearly summed input.

diff --git a/models/rate_neuron_ipn_impl.h b/models/rate_neuron_ipn_impl.h
@@ -66,8 +66,8 @@ template < class TNonlinearities >
 nest::rate_neuron_ipn< TNonlinearities >::Parameters_::Parameters_()
   : tau_( 10.0 )   // ms
   , lambda_( 1.0 ) // ms
-  , std_( 1.0 )
-  , mean_( 0.0 )
+  , sigma_( 1.0 )
+  , mu_( 0.0 )
   , linear_summation_( true )
   , rectify_output_( false )
   , mult_coupling_( false )
@@ -93,11 +93,15 @@ nest::rate_neuron_ipn< TNonlinearities >::Parameters_::get(
 {
   def< double >( d, names::tau, tau_ );
   def< double >( d, names::lambda, lambda_ );
-  def< double >( d, names::std, std_ );
-  def< double >( d, names::mean, mean_ );
+  def< double >( d, names::sigma, sigma_ );
+  def< double >( d, names::mu, mu_ );
   def< bool >( d, names::linear_summation, linear_summation_ );
   def< bool >( d, names::rectify_output, rectify_output_ );
   def< bool >( d, names::mult_coupling, mult_coupling_ );
+
+  // Also allow old names (to not break old scripts)
+  def< double >( d, names::std, sigma_ );
+  def< double >( d, names::mean, mu_ );
 }
 
 template < class TNonlinearities >
@@ -107,12 +111,30 @@ nest::rate_neuron_ipn< TNonlinearities >::Parameters_::set(
 {
   updateValue< double >( d, names::tau, tau_ );
   updateValue< double >( d, names::lambda, lambda_ );
-  updateValue< double >( d, names::mean, mean_ );
-  updateValue< double >( d, names::std, std_ );
+  updateValue< double >( d, names::mu, mu_ );
+  updateValue< double >( d, names::sigma, sigma_ );
   updateValue< bool >( d, names::linear_summation, linear_summation_ );
   updateValue< bool >( d, names::rectify_output, rectify_output_ );
   updateValue< bool >( d, names::mult_coupling, mult_coupling_ );
 
+  // Check for old names
+  if ( updateValue< double >( d, names::mean, mu_ ) )
+  {
+    LOG( M_WARNING,
+      "rate_neuron_ipn< TNonlinearities >::Parameters_::set",
+      "The parameter mean has been renamed to mu. Please use the new "
+      "name from now on." );
+  }
+
+  if ( updateValue< double >( d, names::std, sigma_ ) )
+  {
+    LOG( M_WARNING,
+      "rate_neuron_ipn< TNonlinearities >::Parameters_::set",
+      "The parameter std has been renamed to sigma. Please use the new "
+      "name from now on." );
+  }
+
+  // Check for invalid parameters
   if ( tau_ <= 0 )
   {
     throw BadProperty( "Time constant must be > 0." );
@@ -121,9 +143,9 @@ nest::rate_neuron_ipn< TNonlinearities >::Parameters_::set(
   {
     throw BadProperty( "Passive decay rate must be >= 0." );
   }
-  if ( std_ < 0 )
+  if ( sigma_ < 0 )
   {
-    throw BadProperty( "Standard deviation of noise must not be negative." );
+    throw BadProperty( "Noise parameter must not be negative." );
   }
 }
 
@@ -275,9 +297,9 @@ nest::rate_neuron_ipn< TNonlinearities >::update_( Time const& origin,
     // store rate
     new_rates[ lag ] = S_.rate_;
     // get noise
-    S_.noise_ = P_.std_ * B_.random_numbers[ lag ];
+    S_.noise_ = P_.sigma_ * B_.random_numbers[ lag ];
     // propagate rate to new time step (exponential integration)
-    S_.rate_ = V_.P1_ * new_rates[ lag ] + V_.P2_ * P_.mean_
+    S_.rate_ = V_.P1_ * new_rates[ lag ] + V_.P2_ * P_.mu_
       + V_.input_noise_factor_ * S_.noise_;
 
     double delayed_rates_in = 0;

diff --git a/models/rate_neuron_opn.h b/models/rate_neuron_opn.h
@@ -44,30 +44,52 @@
 namespace nest
 {
 
-/**
- * Base class for rate model with output noise.
- *
- * This template class needs to be instantiated with a class
- * containing the following functions:
- *  - input (nonlinearity that is applied to the input)
- *  - mult_coupling_ex (factor of multiplicative coupling for excitatory input)
- *  - mult_coupling_in (factor of multiplicative coupling for inhibitory input)
- *
- * The boolean parameter linear_summation determines whether the input function
- * is applied to the summed up incoming connections (True, default value) or
- * to each input individually (False). In case of multiplicative coupling the
- * nonlinearity is applied separately to the summed excitatory and inhibitory
- * inputs if linear_summation=True.
- *
- * References:
- *
- * Hahne, J., Dahmen, D., Schuecker, J., Frommer, A.,
- * Bolten, M., Helias, M. and Diesmann, M. (2017).
- * Integration of Continuous-Time Dynamics in a
- * Spiking Neural Network Simulator.
- * Front. Neuroinform. 11:34. doi: 10.3389/fninf.2017.00034
- *
- * @see lin_rate, tanh_rate, threshold_lin_rate
+/** @BeginDocumentation
+Name: rate_neuron_opn - Base class for rate model with output noise.
+
+Description:
+
+Base class for rate model with output noise of the form
+
+$\tau dX_i(t) / dt = - X_i(t) + \mu + \phi( \sum w_{ij} \cdot
+                     \psi( X_j(t-d_{ij}) + \sqrt{tau} \cdot
+                     \sigma \cdot \xi_j(t) ) )$
+
+or
+
+$\tau dX_i(t) / dt = - X_i(t) + \mu
+                     + \text{mult\_coupling\_ex}( X_i(t) ) \cdot
+                     \phi( \sum w^{ > 0 }_{ij} \cdot \psi( X_j(t-d_{ij})
+                     + \sqrt{tau} \cdot \sigma \cdot \xi_j(t) ) )
+                     + \text{mult\_coupling\_in}( X_i(t) ) \cdot
+                     \phi( \sum w^{ < 0 }_{ij} \cdot \psi( X_j(t-d_{ij})
+                     + \sqrt{tau} \cdot \sigma \cdot \xi_j(t) ) )$.
+
+Here $\xi_j(t)$ denotes a Gaussian white noise.
+
+This template class needs to be instantiated with a class
+containing the following functions:
+ - input (nonlinearity that is applied to the input, either psi or phi)
+ - mult_coupling_ex (factor of multiplicative coupling for excitatory input)
+ - mult_coupling_in (factor of multiplicative coupling for inhibitory input)
+
+The boolean parameter linear_summation determines whether the input function
+is applied to the summed up incoming connections (True, default value, input
+represents phi) or to each input individually (False, input represents psi).
+In case of multiplicative coupling the nonlinearity is applied separately
+to the summed excitatory and inhibitory inputs if linear_summation=True.
+
+References:
+
+Hahne, J., Dahmen, D., Schuecker, J., Frommer, A.,
+Bolten, M., Helias, M. and Diesmann, M. (2017).
+Integration of Continuous-Time Dynamics in a
+Spiking Neural Network Simulator.
+Front. Neuroinform. 11:34. doi: 10.3389/fninf.2017.00034
+
+Author: David Dahmen, Jan Hahne, Jannis Schuecker
+
+SeeAlso: lin_rate, tanh_rate, threshold_lin_rate
  */
 template < class TNonlinearities >
 class rate_neuron_opn : public Archiving_Node
@@ -137,11 +159,11 @@ class rate_neuron_opn : public Archiving_Node
     /** Time constant in ms. */
     double tau_;
 
-    /** Gaussian white noise standard deviation. */
-    double std_;
+    /** Noise parameter. */
+    double sigma_;
 
-    /** Gaussian white noise mean.*/
-    double mean_;
+    /** Mean input.*/
+    double mu_;
 
     /** Target of non-linearity.
         True (default): Gain function applied to linearly summed input.

diff --git a/models/rate_neuron_opn_impl.h b/models/rate_neuron_opn_impl.h
@@ -66,8 +66,8 @@ RecordablesMap< rate_neuron_opn< TNonlinearities > >
 template < class TNonlinearities >
 nest::rate_neuron_opn< TNonlinearities >::Parameters_::Parameters_()
   : tau_( 10.0 ) // ms
-  , std_( 1.0 )
-  , mean_( 0.0 )
+  , sigma_( 1.0 )
+  , mu_( 0.0 )
   , linear_summation_( true )
   , mult_coupling_( false )
 {
@@ -92,10 +92,14 @@ nest::rate_neuron_opn< TNonlinearities >::Parameters_::get(
   DictionaryDatum& d ) const
 {
   def< double >( d, names::tau, tau_ );
-  def< double >( d, names::std, std_ );
-  def< double >( d, names::mean, mean_ );
+  def< double >( d, names::sigma, sigma_ );
+  def< double >( d, names::mu, mu_ );
   def< bool >( d, names::linear_summation, linear_summation_ );
   def< bool >( d, names::mult_coupling, mult_coupling_ );
+
+  // Also allow old names (to not break old scripts)
+  def< double >( d, names::std, sigma_ );
+  def< double >( d, names::mean, mu_ );
 }
 
 template < class TNonlinearities >
@@ -104,18 +108,36 @@ nest::rate_neuron_opn< TNonlinearities >::Parameters_::set(
   const DictionaryDatum& d )
 {
   updateValue< double >( d, names::tau, tau_ );
-  updateValue< double >( d, names::mean, mean_ );
-  updateValue< double >( d, names::std, std_ );
+  updateValue< double >( d, names::mu, mu_ );
+  updateValue< double >( d, names::sigma, sigma_ );
   updateValue< bool >( d, names::linear_summation, linear_summation_ );
   updateValue< bool >( d, names::mult_coupling, mult_coupling_ );
 
+  // Check for old names
+  if ( updateValue< double >( d, names::mean, mu_ ) )
+  {
+    LOG( M_WARNING,
+      "rate_neuron_ipn< TNonlinearities >::Parameters_::set",
+      "The parameter mean has been renamed to mu. Please use the new "
+      "name from now on." );
+  }
+
+  if ( updateValue< double >( d, names::std, sigma_ ) )
+  {
+    LOG( M_WARNING,
+      "rate_neuron_ipn< TNonlinearities >::Parameters_::set",
+      "The parameter std has been renamed to sigma. Please use the new "
+      "name from now on." );
+  }
+
+  // Check for invalid parameters
   if ( tau_ <= 0 )
   {
     throw BadProperty( "Time constant must be > 0." );
   }
-  if ( std_ < 0 )
+  if ( sigma_ < 0 )
   {
-    throw BadProperty( "Standard deviation of noise must not be negative." );
+    throw BadProperty( "Noise parameter must not be negative." );
   }
 }
 
@@ -255,13 +277,13 @@ nest::rate_neuron_opn< TNonlinearities >::update_( Time const& origin,
   for ( long lag = from; lag < to; ++lag )
   {
     // get noise
-    S_.noise_ = P_.std_ * B_.random_numbers[ lag ];
+    S_.noise_ = P_.sigma_ * B_.random_numbers[ lag ];
     // the noise is added to the noisy_rate variable
     S_.noisy_rate_ = S_.rate_ + V_.output_noise_factor_ * S_.noise_;
     // store rate
     new_rates[ lag ] = S_.noisy_rate_;
     // propagate rate to new time step (exponential integration)
-    S_.rate_ = V_.P1_ * S_.rate_ + V_.P2_ * P_.mean_;
+    S_.rate_ = V_.P1_ * S_.rate_ + V_.P2_ * P_.mu_;
 
     double delayed_rates_in = 0;
     double delayed_rates_ex = 0;

diff --git a/models/sigmoid_rate.h b/models/sigmoid_rate.h
@@ -56,8 +56,8 @@ The following parameters can be set in the status dictionary.
 
 rate                double - Rate (unitless)
 tau                 double - Time constant of rate dynamics in ms.
-mean                double - Mean of Gaussian white noise.
-std                 double - Standard deviation of Gaussian white noise.
+mu                  double - Mean input.
+sigma               double - Noise parameter.
 g                   double - Gain parameter.
 beta                double - Slope parameter.
 theta               double - Threshold.

diff --git a/models/sigmoid_rate_gg_1998.h b/models/sigmoid_rate_gg_1998.h
@@ -56,8 +56,8 @@ The following parameters can be set in the status dictionary.
 
 rate                double - Rate (unitless)
 tau                 double - Time constant of rate dynamics in ms.
-mean                double - Mean of Gaussian white noise.
-std                 double - Standard deviation of Gaussian white noise.
+mu                  double - Mean input.
+sigma               double - Noise parameter.
 g                   double - Gain parameter.
 linear_summation    bool   - Specifies type of non-linearity (see above).
 rectify_output      bool   - Switch to restrict rate to values >= 0.