sinusoidal_gamma_generator.h

Go to the documentation of this file.

/*
 *  sinusoidal_gamma_generator.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  NEST is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef SINUSOIDAL_GAMMA_GENERATOR_H
#define SINUSOIDAL_GAMMA_GENERATOR_H

#include "config.h"

#ifdef HAVE_GSL

#include "nest.h"
#include "randomgen.h"
#include "event.h"
#include "node.h"
#include "stimulating_device.h"
#include "connection.h"
#include "universal_data_logger.h"

#include <vector>

namespace nest{

  class Network;

  /* BeginDocumentation
     Name: sinusoidal_gamma_generator - Generates sinusoidally modulated gamma spike trains.

     Description:
     sinusoidal_gamma_generator generates sinusoidally modulated gamma spike trains. By default,
     each target of the generator will receive a different spike train.

     The instantaneous rate of the process is given by

         f(t) = dc + ac sin ( 2 pi freq t + phi ) >= 0

     Parameters: 
     The following parameters can be set in the status dictionary:

     dc         double - Mean firing rate in spikes/second, default: 0 s^-1
     ac         double - Firing rate modulation amplitude in spikes/second, default: 0 s^-1
     freq       double - Modulation frequency in Hz, default: 0 Hz
     phi        double - Modulation phase in radian, default: 0
     order      double - Gamma order (>= 1), default: 1
  
     individual_spike_trains   bool - See note below, default: true

     Remarks:
     - The gamma generator requires 0 <= ac <= dc.
     - The state of the generator is reset on calibration.
     - The generator does not support precise spike timing.
     - You can use the multimeter to sample the rate of the generator.
     - The generator will create different trains if run at different
       temporal resolutions.

     - Individual spike trains vs single spike train:
       By default, the generator sends a different spike train to each of its targets.
       If /individual_spike_trains is set to false using either SetDefaults or CopyModel
       before a generator node is created, the generator will send the same spike train
       to all of its targets.

     Receives: DataLoggingRequest

     Sends: SpikeEvent

     References: Barbieri et al, J Neurosci Methods 105:25-37 (2001)
     FirstVersion: October 2007, May 2013
     Author: Hans E Plesser, Thomas Heiberg

     SeeAlso: sinusoidal_poisson_generator, gamma_sup_generator
  */


  class sinusoidal_gamma_generator: public Node
  {
    
  public:        
    
    sinusoidal_gamma_generator();
    sinusoidal_gamma_generator(const sinusoidal_gamma_generator&);

    port send_test_event(Node&, rport, synindex, bool);

    using Node::handle;
    using Node::handles_test_event;
    using Node::event_hook;

    void handle(DataLoggingRequest &);

    port handles_test_event(DataLoggingRequest&, rport);

    void get_status(DictionaryDatum &) const;
    void set_status(const DictionaryDatum &);

    bool has_proxies() const { return not P_.individual_spike_trains_; }

    bool local_receiver() const { return true; } 
    
  private:
    void init_state_(const Node&);
    void init_buffers_();
    void calibrate();
    void event_hook(DSSpikeEvent&);

    void update(Time const &, const long_t, const long_t);

    struct Parameters_ {
      double_t om_;
      
      double_t phi_;
      
      double_t order_;

      double_t dc_;
      
      double_t ac_;

      bool individual_spike_trains_;

      size_t num_trains_;

      Parameters_();  
      Parameters_(const Parameters_& );
      Parameters_& operator=(const Parameters_& p); // Copy constructor EN

      void get(DictionaryDatum&) const;  
      
      void set(const DictionaryDatum&, const sinusoidal_gamma_generator&);
    };

    struct State_ {

      double_t rate_;    

      State_();  

      void get(DictionaryDatum&) const;  
      void set(const DictionaryDatum&, const Parameters_&);  
    };

    // ------------------------------------------------------------

    // These friend declarations must be precisely here.
    friend class RecordablesMap<sinusoidal_gamma_generator>;
    friend class UniversalDataLogger<sinusoidal_gamma_generator>;

    // ----------------------------------------------------------------

    struct Buffers_ {
      Buffers_(sinusoidal_gamma_generator&);
      Buffers_(const Buffers_&, sinusoidal_gamma_generator&);
      UniversalDataLogger<sinusoidal_gamma_generator> logger_;

      std::vector<double> t0_ms_;

      std::vector<double> Lambda_t0_;

      Parameters_ P_prev_;  
    };

    // ------------------------------------------------------------

    struct Variables_ {
      double_t h_;     
      double_t t_ms_;  
      long_t t_steps_; 
      librandom::RngPtr rng_;   
    };

    double_t get_rate_() const { return 1000.0 * S_.rate_; }

    double_t deltaLambda_(const Parameters_&, double_t, double_t) const;

    double_t hazard_(port) const;

    StimulatingDevice<SpikeEvent> device_;
    static RecordablesMap<sinusoidal_gamma_generator> recordablesMap_;

    Parameters_ P_;
    State_      S_;
    Variables_  V_;
    Buffers_    B_;
  };

  inline
  port sinusoidal_gamma_generator::send_test_event(Node& target, rport receptor_type, synindex syn_id, bool dummy_target)
  {
    device_.enforce_single_syn_type(syn_id);

    // to ensure correct overloading resolution, we need explicit event types
    // therefore, we need to duplicate the code here
    if ( P_.individual_spike_trains_ )
    {
      if ( dummy_target )
      {
        DSSpikeEvent e;
        e.set_sender(*this);
        return target.handles_test_event(e, receptor_type);
      }
      else
      {
        SpikeEvent e;
        e.set_sender(*this);
        const rport r = target.handles_test_event(e, receptor_type);
        if ( r != invalid_port_ and not is_model_prototype() )
          ++P_.num_trains_;
        return r;
      }
    }
    else
    {
      // We do not count targets here, since connections may be created through
      // proxies. Instead, we set P_.num_trains_ to 1 in Parameters_::set().
      SpikeEvent e;
      e.set_sender(*this);
      return target.handles_test_event(e, receptor_type);
    }
  }

  inline
  port sinusoidal_gamma_generator::handles_test_event(DataLoggingRequest& dlr, rport receptor_type)
  {
    if (receptor_type != 0)
      throw UnknownReceptorType(receptor_type, get_name());
    return B_.logger_.connect_logging_device(dlr, recordablesMap_);
  }

  inline
  void sinusoidal_gamma_generator::get_status(DictionaryDatum &d) const
  {
    P_.get(d);
    S_.get(d);
    device_.get_status(d);
    (*d)[names::recordables] = recordablesMap_.get_list();
  }

  inline
  void sinusoidal_gamma_generator::set_status(const DictionaryDatum &d)
  {
    Parameters_ ptmp = P_;  // temporary copy in case of errors

    ptmp.set(d, *this);    // throws if BadProperty
    // We now know that ptmp is consistent. We do not write it back
    // to P_ before we are also sure that the properties to be set
    // in the parent class are internally consistent.
    device_.set_status(d);

    // if we get here, temporaries contain consistent set of properties
    P_ = ptmp;
  }

} // namespace

#endif // SINUSOIDAL_GAMMA_GENERATOR_H

#endif //HAVE_GSL