Merge pull request #41 from akorgor/wip-eprop-doxygen

Add doxygen comments

models/eprop_iaf_psc_delta.h

@@ -104,10 +104,10 @@ The following parameters can be set in the status dictionary.
 
 ================== ==== ======================= ================ =============================================
 **Neuron parameters**
-------------------------------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------
 Parameter          Unit Math equivalent         Default          Description
 ================== ==== ======================= ================ =============================================
-C_m                pF   :math:`C_\text{m}`                 250.0 Capacity of the membrane
+C_m                pF   :math:`C_\text{m}`                 250.0 Capacitance of the membrane
 c_reg                   :math:`c_\text{reg}`                 0.0 Prefactor of firing rate regularization
 E_L                mV   :math:`E_\text{L}`                 -70.0 Leak membrane potential
 f_target           Hz   :math:`f^\text{target}`             10.0 Target firing rate of rate regularization
@@ -122,8 +122,8 @@ surrogate_gradient      :math:`\psi`            piecewise_linear Surrogate gradi
 t_ref              ms   :math:`t_\text{ref}`                 2.0 Duration of the refractory period
 tau_m              ms   :math:`\tau_\text{m}`               10.0 Time constant of the membrane
 V_m                mV   :math:`v_j^0`                      -70.0 Initial value of the membrane voltage
-V_min              mV   :math:`v_\text{min}`          -1.79e+308 Absolute lower value of the membrane voltage
-V_th               mV   :math:`v_\text{th}`                -55.0 Spike threshold
+V_min              mV   :math:`v_\text{min}`          -1.79e+308 Absolute lower bound of the membrane voltage
+V_th               mV   :math:`v_\text{th}`                -55.0 Spike threshold voltage
 ================== ==== ======================= ================ =============================================
 
 Recordables
@@ -177,7 +177,10 @@ class eprop_iaf_psc_delta : public EpropArchivingNode
 {
 
 public:
+  //! Default constructor.
   eprop_iaf_psc_delta();
+
+  //! Copy constructor.
   eprop_iaf_psc_delta( const eprop_iaf_psc_delta& );
 
   using Node::handle;
@@ -211,101 +214,170 @@ class eprop_iaf_psc_delta : public EpropArchivingNode
 
   void update( Time const&, const long, const long ) override;
 
-  friend class RecordablesMap< eprop_iaf_psc_delta >;
-  friend class UniversalDataLogger< eprop_iaf_psc_delta >;
-
+  //! Compute the piecewise linear surrogate gradient.
   double compute_piecewise_linear_derivative();
 
+  //! Compute the surrogate gradient.
   double ( eprop_iaf_psc_delta::*compute_surrogate_gradient )();
 
+  //! Map for storing a static set of recordables.
+  friend class RecordablesMap< eprop_iaf_psc_delta >;
+
+  //! Logger for universal data supporting the data logging request / reply mechanism. Populated with a recordables map.
+  friend class UniversalDataLogger< eprop_iaf_psc_delta >;
+
+  //! Structure of parameters.
   struct Parameters_
   {
-    double C_m_;                     //!< membrane capacitance (pF)
-    double c_reg_;                   //!< prefactor of firing rate regularization
-    double E_L_;                     //!< leak potential (mV)
-    double f_target_;                //!< target firing rate of rate regularization (spikes/s)
-    double gamma_;                   //!< scaling of pseudo-derivative of membrane voltage
-    double I_e_;                     //!< external DC current (pA)
-    std::string psc_scale_factor_;   //!< scale factor of presynaptic current "unity" (1.0)
-                                     //!< or "alpha_complement" (1.0 - alpha))
-    std::string surrogate_gradient_; //!< surrogate gradient method / pseudo-derivative
-    double t_ref_;                   //!< refractory period (ms)
-    double tau_m_;                   //!< membrane time constant (ms)
-    double V_min_;                   //!< lower membrane voltage bound relative to leak potential (mV)
-    double V_th_;                    //!< spike treshold voltage relative to leak potential (mV)
 
+    //! Capacitance of the membrane (pF).
+    double C_m_;
+
+    //! Prefactor of firing rate regularization.
+    double c_reg_;
+
+    //! Leak membrane potential (mV).
+    double E_L_;
+
+    //! Target firing rate of rate regularization (spikes/s).
+    double f_target_;
+
+    //! Scaling of pseudo-derivative of membrane voltage.
+    double gamma_;
+
+    //! Constant external input current (pA).
+    double I_e_;
+
+    //! Scale factor for presynaptic current ["unity", "alpha_complement"]
+    std::string psc_scale_factor_;
+
+    //! Surrogate gradient method / pseudo-derivative ["piecewise_linear"].
+    std::string surrogate_gradient_;
+
+    //! Duration of the refractory period (ms).
+    double t_ref_;
+
+    //! Time constant of the membrane (ms).
+    double tau_m_;
+
+    //! Absolute lower bound of the membrane voltage relative to the leak membrane potential (mV).
+    double V_min_;
+
+    //! Spike threshold voltage relative to the leak membrane potential (mV).
+    double V_th_;
+
+    //! Default constructor.
     Parameters_();
 
+    //! Get the parameters and their values.
     void get( DictionaryDatum& ) const;
+
+    //! Set the parameters and throw errors in case of invalid values.
     double set( const DictionaryDatum&, Node* );
   };
 
+  //! Structure of state variables.
   struct State_
   {
-    double learning_signal_;    //!< weighted error signal
-    int r_;                     //!< number of remaining refractory steps
-    double surrogate_gradient_; //!< pseudo derivative of the membrane voltage
-    double y0_;                 //!< current (pA)
-    double y3_;                 //!< membrane voltage relative to leak potential (mV)
-    double z_; //!< binary variable indicating by the value 1.0 that the neuron has spiked in the previous time step and
-               //!< 0.0 otherwise
+    //! Learning signal. Sum of weighted error signals coming from the readout neurons.
+    double learning_signal_;
+
+    //! Number of remaining refractory steps.
+    int r_;
+
+    //! Surrogate gradient / pseudo-derivative of the membrane voltage.
+    double surrogate_gradient_;
+
+    //! Input current (pA).
+    double y0_;
 
+    //! Membrane voltage relative to the leak membrane potential (mV).
+    double y3_;
+
+    //! Binary spike variable - 1.0 if the neuron has spiked in the previous time step and 0.0 otherwise.
+    double z_;
+
+    //! Default constructor.
     State_();
 
+    //! Get the state variables and their values.
     void get( DictionaryDatum&, const Parameters_& ) const;
+
+    //! Set the state variables.
     void set( const DictionaryDatum&, const Parameters_&, double, Node* );
   };
 
+  //! Structure of buffers.
   struct Buffers_
   {
+    //! Default constructor.
     Buffers_( eprop_iaf_psc_delta& );
+
+    //! Copy constructor.
     Buffers_( const Buffers_&, eprop_iaf_psc_delta& );
 
+    //! Buffer for incoming spikes.
     RingBuffer spikes_;
+
+    //! Buffer for incoming currents.
     RingBuffer currents_;
 
+    //! Logger for universal data.
     UniversalDataLogger< eprop_iaf_psc_delta > logger_;
   };
 
+  //! Structure of general variables.
   struct Variables_
   {
-    double P30_;
+    //! Propagator matrix entry for evolving the membrane voltage.
     double P33_;
+
+    //! Propagator matrix entry for evolving the incoming spike variables.
     double P33_complement_;
+
+    //! Propagator matrix entry for evolving the incoming currents.
+    double P30_;
+
+    //! Total refractory steps.
     int RefractoryCounts_;
   };
 
+  //! Get the current value of the membrane voltage.
   double
   get_V_m_() const
   {
     return S_.y3_ + P_.E_L_;
   }
 
+  //! Get the current value of the surrogate gradient.
   double
   get_surrogate_gradient_() const
   {
     return S_.surrogate_gradient_;
   }
 
+  //! Get the current value of the learning signal.
   double
   get_learning_signal_() const
   {
     return S_.learning_signal_;
   }
 
-  /**
-   * @defgroup eprop_iaf_psc_delta_data
-   * Instances of private data structures for the different types
-   * of data pertaining to the model.
-   * @note The order of definitions is important for speed.
-   * @{
-   */
+  // the order in which the structure instances are defined is important for speed
+
+  //!< Structure of parameters.
   Parameters_ P_;
+
+  //!< Structure of state variables.
   State_ S_;
+
+  //!< Structure of general variables.
   Variables_ V_;
+
+  //!< Structure of buffers.
   Buffers_ B_;
-  /** @} */
 
+  //! Map storing a static set of recordables.
   static RecordablesMap< eprop_iaf_psc_delta > recordablesMap_;
 };