Merge pull request #219 from sdiazpier/v3.3

Changes in the documentation for synaptic elements and growth curve

nestkernel/growth_curve.h

@@ -77,11 +77,66 @@ class GrowthCurve
   const Name name_;
 };
 
+/* BeginDocumentation
+  Name: growth_curve_linear - Linear version of a growth curve
+
+  Description:
+   This class represents a linear growth rule for the number of synaptic
+  elements
+   inside a neuron. The creation and deletion of synaptic elements when
+  structural
+   plasticity is enabled, allows the dynamic rewiring of the network during the
+   simulation.
+   This type of growth curve uses an exact integration method to update the
+   number of synaptic elements: dz/dt = nu (1 - (1/eps) * Ca(t)),
+   where nu is the growth rate [elements/ms] and eps is the desired average
+  calcium
+   concentration. The growth rate nu is defined in the SynapticElement class.
+
+  Parameters:
+   eps          double -  The target calcium concentration that
+                          the neuron should look to achieve by creating or
+  deleting
+                          synaptic elements. It should always be a positive
+  value.
+                          It is important to note that the calcium concentration
+                          is linearly proportional to the firing rate. This is
+                          because dCa/dt = - Ca(t)/tau_Ca + beta_Ca if the
+  neuron
+                          fires and dCa/dt = - Ca(t)/tau_Ca otherwise, where
+  tau_Ca
+                          is the calcium concentration decay constant and
+  beta_Ca
+                          is the calcium intake constant (see SynapticElement
+  class).
+                          This means that eps also defines
+                          the desired firing rate that the neuron should
+                          achieve.
+                          For example, an eps = 0.05 [Ca2+] with tau_Ca =
+  10000.0
+                          and beta_Ca = 0.001 for a synaptic element means a
+  desired
+                          firing rate of 5Hz.
+
+  References:
+   [1] Butz, Markus, Florentin Wörgötter, and Arjen van Ooyen.
+   "Activity-dependent structural plasticity." Brain research reviews 60.2
+   (2009): 287-305.
+
+   [2] Butz, Markus, and Arjen van Ooyen. "A simple rule for dendritic spine
+   and axonal bouton formation can account for cortical reorganization after
+   focal retinal lesions." PLoS Comput Biol 9.10 (2013): e1003259.
+
+  FirstVersion: July 2013
+  Author: Mikael Naveau
+  SeeAlso: SynapticElement, SPManager, SPBuilder, GrowthCurveLinear,
+           GrowthCurveGaussian
+*/
 /**
  * \class GrowthCurveLinear
  * Uses an exact integration method to update the number of synaptic elements:
- * dz/dt = nu (1 - (1/epsilon) * Ca(t)), where nu is the growth rate and
- * epsilon is the desired average calcium concentration.
+ * dz/dt = nu (1 - (1/eps) * Ca(t)), where nu is the growth rate and
+ * eps is the desired average calcium concentration.
  */
 class GrowthCurveLinear : public GrowthCurve
 {
@@ -100,15 +155,87 @@ class GrowthCurveLinear : public GrowthCurve
   double_t eps_;
 };
 
+/* BeginDocumentation
+  Name: growth_curve_gaussian - Gaussian version of a growth curve
+
+  Description:
+   This class represents a Gaussian growth rule for the number of synaptic
+  elements
+   inside a neuron. The creation and deletion of synaptic elements when
+  structural
+   plasticity is enabled, allows the dynamic rewiring of the network during the
+   simulation.
+   This type of growth curve  uses a forward Euler integration method to update
+   the number of synaptic elements:
+   dz/dt = nu (2 * e^(- ((Ca(t) - xi)/z)^2 ) - 1)
+   where xi = (eta  + eps)/2,
+   zeta = (eps - eta)/2 * sqrt(ln(2))),
+   eta is the minimum calcium concentration required for any synaptic element
+   to be created, eps is the target mean calcium concentration in the
+   neuron and nu is the growth rate in elements/ms. The growth rate nu is
+   defined in the SynapticElement class.
+
+  Parameters:
+   eta          double -  Minimum amount of calcium concentration that the
+                          neuron needs to start creating synaptic elements.
+                          eta can have a negative value, making the growth curve
+                          move its maximum to the left. For example, if eta=-0.5
+                          and eps=0.5 [Ca2+], the maximum growth rate
+  (elements/ms) will
+                          be achieved at 0.0 [Ca2+]. If eta=0.0 [Ca2+] and
+  eps=0.5 [Ca2+]
+                          the maximum growth rate will be achieved at 0.25
+  [Ca2+] while at
+                          0.0 [Ca+2] no new elements will be created.
+   eps          double -  The target calcium concentration that
+                          the neuron should look to achieve by creating or
+  deleting
+                          synaptic elements. It should always be a positive
+  value.
+                          It is important to note that the calcium concentration
+                          is linearly proportional to the firing rate. This is
+                          because dCa/dt = - Ca(t)/tau_Ca + beta_Ca if the
+  neuron
+                          fires and dCa/dt = - Ca(t)/tau_Ca otherwise, where
+  tau_Ca
+                          is the calcium concentration decay constant and
+  beta_Ca
+                          is the calcium intake constant (see SynapticElement
+  class).
+                          This means that eps can also be
+                          seen as the desired firing rate that the neuron should
+                          achieve.
+                          For example, an eps = 0.05 [Ca2+] with tau_Ca =
+  10000.0
+                          and beta_Ca = 0.001 for a synaptic element means a
+  desired
+                          firing rate of 5Hz.
+   nu           double -  Growth rate in elements/ms. The growth rate nu is
+                          defined in the SynapticElement class. Can be negative.
+
+  References:
+   [1] Butz, Markus, Florentin Wörgötter, and Arjen van Ooyen.
+   "Activity-dependent structural plasticity." Brain research reviews 60.2
+   (2009): 287-305.
+
+   [2] Butz, Markus, and Arjen van Ooyen. "A simple rule for dendritic spine
+   and axonal bouton formation can account for cortical reorganization after
+   focal retinal lesions." PLoS Comput Biol 9.10 (2013): e1003259.
+
+  FirstVersion: July 2013
+  Author: Mikael Naveau
+  SeeAlso: SynapticElement, SPManager, SPBuilder, GrowthCurveLinear,
+           GrowthCurveGaussian
+*/
 /**
  * \class GrowthCurveGaussian
  * Uses a forward Euler integration method to update the number of synaptic
  * elements:
  * dz/dt = nu (2 * e^(- ((Ca(t) - xi)/zeta)^2 ) - 1)
- * where xi = (eta  + epsilon)/2,
- * zeta = (epsilon - eta)/2 * sqrt(ln(2))),
+ * where xi = (eta  + eps)/2,
+ * zeta = (eps - eta)/2 * sqrt(ln(2))),
  * eta is the minimum calcium concentration required for any synaptic element
- * to be created, epsilon is the target mean calcium concentration in the
+ * to be created, eps is the target mean calcium concentration in the
  * neuron and nu is the growth rate.
  */
 class GrowthCurveGaussian : public GrowthCurve

nestkernel/synaptic_element.h

@@ -31,6 +31,57 @@
 #ifndef SYNAPTIC_ELEMENT_H
 #define SYNAPTIC_ELEMENT_H
 
+/* BeginDocumentation
+  Name: synaptic_element - Contact point element for the dynamic creation
+   and deletion of synapses.
+
+  Description:
+   This class represents synaptic element of a node (like Axonl boutons or
+   dendritic spines) used for structural plasticity.
+   The synaptic elements represent connection points between two neurons. They
+   grow according to a homeostatic growth rule. The dynamics of the
+   number of synaptic elements is driven by the average electrical activity of
+   the neuron (indirectly measured through the Calcium concentration of the
+   node). The probability of two neurons creating a new synapse between them,
+   depends on the number of available synaptic elements of each neuron.
+
+  Parameters:
+   z                double  - Current number of synaptic elements. Stored as a
+                              double variable but the actual usable number of
+                              synaptic elements is an integer truncated from
+  this
+                              double value. An standard value for the growth of
+  a
+                              synaptic element is around 0.0001 elements/ms.
+   continuous       boolean - Defines if the number of synaptic elements should
+                              be treated as a continuous double number or as an
+                              integer value. Default is false.
+   growth_rate      double  - The maximum amount by which the synaptic elements
+  will
+                              change between time steps. In elements/ms.
+   tau_vacant       double  - Rate at which vacant synaptic elements will decay.
+                              Typical is 0.1 which represents a
+                              loss of 10% of the vacant synaptic elements each
+  time
+                              the structural_plasticity_update_interval is
+                              reached by the simulation time.
+   growth_curve     GrowthCurve* - Rule which defines the dynamics of this
+  synaptic element.
+
+  References:
+   [1] Butz, Markus, Florentin Wörgötter, and Arjen van Ooyen.
+   "Activity-dependent structural plasticity." Brain research reviews 60.2
+   (2009): 287-305.
+
+   [2] Butz, Markus, and Arjen van Ooyen. "A simple rule for dendritic spine
+   and axonal bouton formation can account for cortical reorganization after
+   focal retinal lesions." PLoS Comput Biol 9.10 (2013): e1003259.
+
+  FirstVersion: July 2013
+  Author: Mikael Naveau, Sandra Diaz
+  SeeAlso: GrowthCurve, SPManager, SPBuilder, Node, ArchivingNode.
+*/
+
 // C++ includes:
 #include <cmath>
 
@@ -166,7 +217,7 @@ class SynapticElement
   }
 
   /*
-   * Retrieves the current value of the growth rate, this is
+   * Retrieves the current value of the growth rate
    */
   double_t
   get_growth_rate() const