Expands reference docs.

Author: stuart-knock

src/configf.h

@@ -46,10 +46,10 @@ class Configf : public std::ifstream { // derived class
   /// Find the next "Check", then returns the next input entry as string
   std::string find( const std::string& Check );
 
-  /// points to next delim, and verify it is "check"+"delim"
+  /// Points to next delim, and verify it is "check"+"delim"
   bool next( const std::string& Check, int delim=':' );
 
-  /// searches and points to next keyword
+  /// Searches and points to next keyword
   void go2( const std::string& keyword );
 
   std::streamsize tell() {

src/coupling.cpp

@@ -1,7 +1,10 @@
 /** @file coupling.cpp
-  @brief A brief, one sentence description.
+  @brief Definition of the main class handling synaptic connections.
 
-  A more detailed multiline description...
+  This class assumes that the synaptic strengths are constant over space and
+  time. The classes: CouplingRamp; CouplingDiffArctan; LongCoupling; and CaDP,
+  which are derived from Coupling, implement temporally varying synaptic
+  strengths or modulation by pre- or postsynaptic activity.
 
   @author Peter Drysdale, Felix Fung,
 */
@@ -24,6 +27,7 @@ using std::endl;
 using std::string;
 using std::vector;
 
+/// Read `.conf` file and initialise synaptic coupling strengths and weighted presynaptic inputs.
 void Coupling::init( Configf& configf ) {
   configf.next("nu");
   vector<double> temp = configf.numbers();
@@ -54,12 +58,14 @@ Coupling::Coupling( size_type nodes, double deltat, size_type index,
 
 Coupling::~Coupling() = default;
 
+/// Calculate next value for synaptic-coupling-strength-weighted-presynaptic-inputs.
 void Coupling::step() {
   for( size_type i=0; i<nodes; i++ ) {
     P[i] = nu[i]*prepropag[i];
   }
 }
 
+/// Read synaptic coupling strength from `.conf` file.
 double Coupling::nuinit( Configf& configf ) const {
   string buffer = configf.find( label("Coupling ",index+1)+"*nu:");
   return atof(buffer.c_str());

src/coupling.h

@@ -1,5 +1,5 @@
 /** @file coupling.h
-  @brief A brief, one sentence description.
+  @brief Declaration of the main class handling synaptic connections.
 
   A more detailed multiline description...
 
@@ -30,12 +30,12 @@ class Coupling : public NF {
 
   const Propagator& prepropag;
   const Population& postpop;
-  std::vector<double> nu; ///< \f$\nu\f$
-  std::vector<double> P;  ///< \f$\nu\phi\f$
+  std::vector<double> nu; ///< Synaptic coupling strength (\f$\nu\f$).
+  std::vector<double> P;  ///< Presynaptic inputs weighted by synaptic coupling strength (\f$\nu\phi\f$).
   int pos = 0;
  public:
-  Coupling() = delete;                // No default constructor allowed.
-  Coupling(const Coupling&) = delete; // No copy constructor allowed.
+  Coupling() = delete;                ///< No default constructor allowed.
+  Coupling(const Coupling&) = delete; ///< No copy constructor allowed.
 
   Coupling( size_type nodes, double deltat, size_type index,
           const Propagator& prepropag, const Population& postpop );

src/de.h

@@ -1,7 +1,10 @@
 /** @file de.h
-  @brief A brief, one sentence description.
+  @brief A collection of classes for differential equations and their integrators.
 
-  A more detailed multiline description...
+  The base differential equation class (DE) requires specific differential
+  equation classes, derived from DE, to specify their equations in DE::rhs.
+  There are currently two integrators derived from the base Integrator class,
+  namely Euler and RK4.
 
   @author Peter Drysdale, Felix Fung,
 */
@@ -14,9 +17,10 @@
 
 using vvd_size_type = std::vector<std::vector<double>>::size_type;
 
+/// Base class for differential equations.
 class DE {
  protected:
-  // if the number of field variables need to be extended, use this function
+  /// if the number of field variables need to be extended, use this function.
   void extend( vvd_size_type extension ) {
     ndim += extension;
     variables.resize(ndim);
@@ -25,12 +29,12 @@ class DE {
     }
   }
  public:
-  DE() = delete;          // No default constructor allowed.
-  DE(const DE&) = delete; // No copy constructor allowed.
-  void operator=(const DE&) = delete;
+  DE() = delete;          ///< No default constructor allowed.
+  DE(const DE&) = delete; ///< No copy constructor allowed.
+  void operator=(const DE&) = delete; ///< No copy assignment allowed.
 
   vvd_size_type nodes; ///< number of nodes in the system.
-  double deltat;       ///< integration timestep size.
+  double deltat;       ///< integration timestep size [s].
   vvd_size_type ndim;  ///< dimension of system == y.size()
   std::vector<std::vector<double> > variables;
 
@@ -48,30 +52,32 @@ class DE {
   virtual const std::vector<double>& operator[] ( vvd_size_type index ) const {
     return variables[index];
   }
-  // define dydt here
+  /// Classes derived from DE, define their specific differential equations here.
   virtual void rhs( const std::vector<double>& y, std::vector<double>& dydt, std::vector<double>::size_type n ) = 0;
 };
 
+/// Base class for bringing together differential equations (DE) and integration schemes Integrator::step().
 class Integrator {
  protected:
   DE& de;
  public:
-  Integrator() = delete;                  // No default constructor allowed.
-  Integrator(const Integrator&) = delete; // No copy constructor allowed.
-  void operator=(const Integrator&) = delete;
+  Integrator() = delete;                  ///< No default constructor allowed.
+  Integrator(const Integrator&) = delete; ///< No copy constructor allowed.
+  void operator=(const Integrator&) = delete; ///< No copy assignment allowed.
 
   explicit Integrator( DE& de ) : de(de) {}
   virtual ~Integrator() = default;
-  virtual void step() = 0;
+  virtual void step() = 0; ///< Scheme for advancing de one step forward in time. Pure virtual, must be overridden.
 };
 
+/// Implements the Euler integration scheme.
 class Euler : public Integrator {
  protected:
   std::vector<double> dydt;
  public:
-  Euler() = delete;             // No default constructor allowed.
-  Euler(const Euler&) = delete; // No copy constructor allowed.
-  void operator=(const Euler&) = delete;
+  Euler() = delete;             ///< No default constructor allowed.
+  Euler(const Euler&) = delete; ///< No copy constructor allowed.
+  void operator=(const Euler&) = delete; ///< No copy assignment allowed.
 
   explicit Euler( DE& de ) : Integrator(de), dydt(de.ndim) {}
   ~Euler() override = default;
@@ -85,6 +91,7 @@ class Euler : public Integrator {
   }
 };
 
+/// Implements the fourth order Runge-Kutta integration scheme.
 class RK4 : public Integrator {
  protected:
   double h6; ///< == deltat/6
@@ -96,14 +103,15 @@ class RK4 : public Integrator {
   std::vector<double> k4;
   std::vector<double> temp;
  public:
-  RK4() = delete;           // No default constructor allowed.
-  RK4(const RK4&) = delete; // No copy constructor allowed.
-  void operator=(const RK4&) = delete;
+  RK4() = delete;           ///< No default constructor allowed.
+  RK4(const RK4&) = delete; ///< No copy constructor allowed.
+  void operator=(const RK4&) = delete; ///< No copy assignment allowed.
 
   explicit RK4( DE& de ) : Integrator(de), h6(de.deltat/6.0), deltat5(de.deltat*0.5),
     k1(de.ndim), k2(de.ndim), k3(de.ndim), k4(de.ndim), temp(de.ndim) {}
   ~RK4() override = default;
 
+  /// Implements the 4th order Runge-Kutta scheme for advancing Integrator::de one step forward in time.
   void step() override {
     for( vvd_size_type j=0; j<de.nodes; j++ ) {
       for( vvd_size_type i=0; i<de.ndim; i++ ) {

src/dendrite.cpp

@@ -1,7 +1,9 @@
 /** @file dendrite.cpp
-  @brief Dendrite handles the dendritic response of the postsynaptic population.
+  @brief Defines the Dendrite class, which handles dendritic dynamics.
 
-  A more detailed multiline description...
+  Dendrite dynamics are applied to incoming activity to postsynaptic Population
+  objects. The differential equation defining the dendritic dynamics are in the
+  member function Dendrite::DendriteDE::rhs.
 
   @author Peter Drysdale, Felix Fung,
 */

src/dendrite.h

@@ -1,7 +1,8 @@
 /** @file dendrite.h
-  @brief Defines the Dendrite class, which handles the response of the postsynaptic population.
+  @brief Declares the Dendrite class, which handles dendritic dynamics.
 
-  A more detailed multiline description...
+  Dendrite dynamics are applied to incoming activity to postsynaptic Population
+  objects.
 
   @author Peter Drysdale, Felix Fung,
 */

src/dendrite_integral.cpp

@@ -1,6 +1,7 @@
 /** @file dendrite_integral.cpp
   @brief DendriteIntegral handles the dendritic response of the postsynaptic
-         population using the integral form for the step() member-function.
+         population using the integral form for the DendriteIntegral::step()
+         member-function.
 
   A more detailed multiline description...
 

src/dendrite_integral.h

@@ -1,6 +1,6 @@
 /** @file dendrite_integral.h
-  @brief Defines the DendriteIntegral class, which handles the response of the
-         postsynaptic population using the integral form for the step()
+  @brief Declares the DendriteIntegral class, which handles the response of the
+         postsynaptic population using the integral form for the DendriteIntegral::step()
          member-function.
 
   A more detailed multiline description...

src/firing_response.cpp

@@ -4,7 +4,8 @@
   Each neural population is associated with a FiringResponse object which produces
   the soma response governed by a specified equation, for example Sigmoid:
   \f[
-    Insert equation 9 from draft nftsim paper here.
+    S_{a}[V_a(\mathbf{r}, t), \theta_{a}(\mathbf{r},t)] = \frac{Q_{a}^{\text{max}}}
+        {1 + \exp[-\{ V_a(\mathbf{r}, t) - \theta_a(\mathbf{r}, t)\}/\sigma'_a(\mathbf{r}, t)]}
   \f]
 
   @author Peter Drysdale, Felix Fung,
@@ -31,6 +32,7 @@ using std::exp;
 using std::string;
 using std::vector;
 
+/// Initialise FiringResponse, reading function and parameters to use from file.
 void FiringResponse::init( Configf& configf ) {
   configf.param("Function", mode);
   if( mode == "Sigmoid" ) {
@@ -62,8 +64,8 @@ FiringResponse::FiringResponse( size_type nodes, double deltat, size_type index
 
 FiringResponse::~FiringResponse() = default;
 
+/// Step through dendrites, then sum up soma potentials.
 void FiringResponse::step() {
-  // step through dendrites, then sum up soma potential
   dendrites.step();
   for( size_type i=0; i<nodes; i++ ) {
     v[i] = 0;

src/firing_response.h

@@ -1,5 +1,5 @@
 /** @file firing_response.h
-  @brief Defines the FiringResponse class, for the soma response of neural populations.
+  @brief Declares the FiringResponse class, for the soma response of neural populations.
 
   Each neural population is associated with a FiringResponse object, which produces
   the soma response.
@@ -43,8 +43,8 @@ class FiringResponse : public NF {
   std::vector<double> v; ///< soma potential for the population
 
  public:
-  FiringResponse(const FiringResponse& ) = delete; // No copy constructor allowed.
-  FiringResponse() = delete;                       // No default constructor allowed.
+  FiringResponse(const FiringResponse& ) = delete; ///< No copy constructor allowed.
+  FiringResponse() = delete;                       ///< No default constructor allowed.
 
   FiringResponse( size_type nodes, double deltat, size_type index );
   ~FiringResponse() override;

src/glutamate_response.h

@@ -1,5 +1,5 @@
 /** @file glutamate_response.h
-  @brief Defines the GlutamateResponse class, for the soma response of neural populations.
+  @brief Declares the GlutamateResponse class, for the soma response of neural populations.
 
   @author Peter Drysdale, Felix Fung,
 */

src/harmonic.cpp

@@ -1,7 +1,8 @@
 /** @file harmonic.cpp
-  @brief A brief, one sentence description.
+  @brief Definition of the Harmonic Propagator class.
 
-  A more detailed multiline description...
+  The Harmonic Propgator is used for spatially homogeneous models, where the
+  Laplacian Operator term is zero and one finds a damped oscillator response.
 
   @author Peter Drysdale, Felix Fung,
 */

src/harmonic.h

@@ -1,7 +1,8 @@
 /** @file harmonic.h
-  @brief A brief, one sentence description.
+  @brief Declaration of the Harmonic Propagator class.
 
-  A more detailed multiline description...
+  The Harmonic Propgator is used for spatially homogeneous models, where the
+  Laplacian Operator term is zero and one finds a damped oscillator response.
 
   @author Peter Drysdale, Felix Fung,
 */

src/random.cpp

@@ -24,7 +24,7 @@ Random::Random(uint_fast64_t seed, double mean, double std) {
 }
 
 void Random::init(uint_fast64_t seed, double mean, double std) {
-  gen = std::mt19937_64(seed); ///< Generator
+  gen = std::mt19937_64(seed); ///< Generator: Mersenne Twister, 64-bit.
   dist = std::normal_distribution<double>(mean,std); ///< Distribution
 }
 

src/solver.h

@@ -90,8 +90,8 @@ class Solver : public NF {
   //virtual void restart( Restartf& restartf );
   //virtual void dump( Dumpf& dumpf ) const;
  public:
-  Solver() = delete;              // No default constructor allowed.
-  Solver(const Solver&) = delete; // No copy constructor allowed.
+  Solver() = delete;              ///< No default constructor allowed.
+  Solver(const Solver&) = delete; ///< No copy constructor allowed.
 
   explicit Solver( Dumpf& dumpf );
   ~Solver() override;

src/stencil.cpp

@@ -1,5 +1,5 @@
 /** @file stencil.cpp
-  @brief A brief, one sentence description.
+  @brief Stencil definition -- spatial neighbourhood used to evaluate \f[{\Delta}x\f].
 
   A more detailed multiline description...
 

src/stencil.h

@@ -1,5 +1,5 @@
 /** @file stencil.h
-  @brief Stencil declaration -- spatial neighbourhood use to evaluate \f[{\Delta}x\f].
+  @brief Stencil declaration -- spatial neighbourhood used to evaluate \f[{\Delta}x\f].
 
   This file contains the Stencil declaration, including a definition of Stencil's
   grid increment operator (ie, ++), and the parentheses operator (ie, ()). The
@@ -27,17 +27,17 @@
 
 class Stencil {
  protected:
-  int nodes;
-  int longside;
-  int shortside;
-  std::string boundary;
+  int nodes;    ///< Number of nodes covering the spatial domain.
+  int longside; ///< Length of the long-side of the spatial domain (in number of nodes).
+  int shortside; ///< Length of the short-side of the spatial domain (in number of nodes).
+  std::string boundary; ///< Type of boundary conditions.
   double* m;
 
   mutable int ptr;
  public:
-  Stencil() = delete;               // No default constructor allowed.
-  Stencil(const Stencil&) = delete; // No copy constructor allowed.
-  Stencil& operator=(const Stencil&) = delete; // No copy assignment operator allowed.
+  Stencil() = delete;               ///< No default constructor allowed.
+  Stencil(const Stencil&) = delete; ///< No copy constructor allowed.
+  Stencil& operator=(const Stencil&) = delete; ///< No copy assignment operator allowed.
 
   enum Neighbours {
        n=-2,
@@ -49,9 +49,9 @@ class Stencil {
   virtual ~Stencil();
 
   const std::vector<double>& operator= ( const std::vector<double>& field );
-  inline void operator++ (int) const; // increment Neighbours grid
-  void set( int node ) const; // point to node
-  int get() const; // get ptr
+  inline void operator++ (int) const; ///< increment Neighbours grid
+  void set( int node ) const; ///< point to node
+  int get() const; ///< get ptr
 
   inline double operator() ( Neighbours neighbour=c ) const {
     int arr[5] = {       ptr-longside-2,

src/stencil_legacy.cpp

@@ -2,7 +2,7 @@
   @brief StencilLegacy, square nine-point stencil definition.
 
   As well as a constructor and destructor, this file defines the set() and
-  get() member functions and a custom equals (=) operator.
+  get() member functions and a custom copy assignment operator(=).
 
   @author Peter Drysdale, Felix Fung.
 */

src/tau.cpp

@@ -1,7 +1,8 @@
 /** @file tau.cpp
-  @brief A brief, one sentence description.
+  @brief Definition of Tau, which handles the activity history.
 
-  A more detailed multiline description...
+  Tau objects are used to retrieve the appropriate delayed activity when the
+  discrete time delay \f$\tau_{ab}\f$ is nonzero.
 
   @author Peter Drysdale, Felix Fung,
 */
@@ -25,6 +26,7 @@ using std::scientific;
 using std::setprecision;
 using std::vector;
 
+/// Initialises Tau::m by reading from a `.conf` file, setting Tau::max accordingly.
 void Tau::init( Configf& configf ) {
   vector<double> temp = configf.numbers();
   if( temp.size() == 1 ) {