Changes in the documentation for synaptic elements and growth curve

nestkernel/growth_curve.h

@@ -77,6 +77,38 @@ 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/epsilon) * Ca(t)),
+   where nu is the growth rate and epsilon is the desired average calcium
+   concentration.
+
+  Parameters:
+   eps          double -  The target calcium concentration (firing rate) that
+                          the neuron should look to achieve by creating or deleting
+                          synaptic elements.
+
+  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:
@@ -100,6 +132,62 @@ 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)/zeta)^2 ) - 1)
+   where xi = (eta  + epsilon)/2,
+   zeta = (epsilon - 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
+   neuron and nu is the growth rate.
+
+  Parameters:
+   eta          double -  Minimum amount of calcium concentration [Ca2+] 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, the maximum growth rate (elements/ms) will
+                          be achieved at 0.0 [Ca2+]. If eta=0 and eps=0.5 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 [Ca2+] 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.
+
+  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

nestkernel/synaptic_element.h

@@ -31,6 +31,48 @@
 #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
+   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/update.
+   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>
 
@@ -165,7 +207,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