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
 
// Generated includes:
#include "config.h"
 
#ifdef HAVE_GSL
 
// C++ includes:
#include <vector>
 
// Includes from nestkernel:
#include "connection.h"
#include "device_node.h"
#include "event.h"
#include "nest_types.h"
#include "stimulation_device.h"
#include "universal_data_logger.h"
 
namespace nest
{
 
/* BeginUserDocs: device, generator
 
Short description
+++++++++++++++++
 
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
 
.. math::
 
 f(t) = \mathrm{rate} + \mathrm{amplitude} \cdot \sin \left(
    2 \pi \cdot \mathrm{frequency} \cdot t + \mathrm{phase} \cdot
    \frac{\pi}{180} \right)
 
.. note::
 
   - The gamma generator requires
     :math:`0 \leq \mathrm{amplitude} \leq \mathrm{rate}`.
   - 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.
 
By default, the generator sends a different spike train to each of its
targets. If ``individual_spike_trains`` is set to ``False`` using either
:py:func:`.SetDefaults` or :py:func:`.CopyModel` before a generator node
is created, the generator will send the same spike train to all of its targets.
 
.. include:: ../models/stimulation_device.rst
 
rate
    Mean firing rate in spikes/second. Default: ``0.0``.
 
amplitude
    Firing rate modulation amplitude in spikes/second. Default: ``0.0``.
 
frequency
    Modulation frequency in Hz. Default: ``0.0``.
 
phase
    Modulation phase in degree [0-360]. Default: ``0.0``.
 
order
    Gamma order (>= 1). Default: ``1``.
 
individual_spike_trains
    See note above. Default: ``True``.
 
See also :footcite:p:`Barbieri2001`.
 
Setting parameters from a stimulation backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
The parameters in this stimulation device can be updated with input
coming from a stimulation backend. The data structure used for the
update holds one value for each of the parameters mentioned above.
The indexing is as follows:
 
 0. frequency
 1. phase
 2. order
 3. rate
 4. amplitude
 5. individual_spike_trains
 
Receives
++++++++
 
DataLoggingRequest
 
Sends
+++++
 
SpikeEvent
 
References
++++++++++
 
.. footbibliography::
 
See also
++++++++
 
sinusoidal_poisson_generator, gamma_sup_generator
 
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: sinusoidal_gamma_generator
 
EndUserDocs */
 
void register_sinusoidal_gamma_generator( const std::string& name );
 
class sinusoidal_gamma_generator : public StimulationDevice
{
 
public:
  sinusoidal_gamma_generator();
  sinusoidal_gamma_generator( const sinusoidal_gamma_generator& );
 
  size_t send_test_event( Node&, size_t, synindex, bool ) override;
 
  using Node::event_hook;
  using Node::handle;
  using Node::handles_test_event;
 
  void handle( DataLoggingRequest& ) override;
 
  size_t handles_test_event( DataLoggingRequest&, size_t ) override;
 
  void get_status( Dictionary& ) const override;
  void set_status( const Dictionary& ) override;
 
  bool has_proxies() const override;
 
  bool local_receiver() const override;
 
  StimulationDevice::Type get_type() const override;
  void set_data_from_stimulation_backend( std::vector< double >& input_param ) override;
 
private:
  void init_state_() override;
  void init_buffers_() override;
  void pre_run_hook() override;
  void event_hook( DSSpikeEvent& ) override;
 
  void update( Time const&, const long, const long ) override;
 
  struct Parameters_
  {
    double om_;
 
    double phi_;
 
    double order_;
 
    double rate_;
 
    double amplitude_;
 
    bool individual_spike_trains_;
 
    size_t num_trains_;
 
    Parameters_();  
    Parameters_( const Parameters_& );
    Parameters_& operator=( const Parameters_& p );
 
    void get( Dictionary& ) const;  
 
    void set( const Dictionary&, const sinusoidal_gamma_generator&, Node* );
  };
 
  struct State_
  {
    double rate_;  
 
    State_();  
  };
 
  // ------------------------------------------------------------
 
  // The next two classes need to be friends to access the State_ class/member.
  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 h_;     
    double t_ms_;  
    long t_steps_;
    RngPtr rng_;  
  };
 
  double
  get_rate_() const
  {
    return 1000.0 * S_.rate_;
  }
 
  double deltaLambda_( const Parameters_&, double, double ) const;
 
  double hazard_( size_t ) const;
 
  static RecordablesMap< sinusoidal_gamma_generator > recordablesMap_;
 
  Parameters_ P_;
  State_ S_;
  Variables_ V_;
  Buffers_ B_;
};
 
inline size_t
sinusoidal_gamma_generator::send_test_event( Node& target, size_t receptor_type, synindex syn_id, bool dummy_target )
{
  StimulationDevice::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 size_t 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 size_t
sinusoidal_gamma_generator::handles_test_event( DataLoggingRequest& dlr, size_t 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( Dictionary& d ) const
{
  P_.get( d );
  StimulationDevice::get_status( d );
  d[ names::recordables ] = recordablesMap_.get_list();
}
 
inline void
sinusoidal_gamma_generator::set_status( const Dictionary& d )
{
  Parameters_ ptmp = P_;  // temporary copy in case of errors
 
  ptmp.set( d, *this, 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.
  StimulationDevice::set_status( d );
 
  // if we get here, temporaries contain consistent set of properties
  P_ = ptmp;
}
 
inline bool
sinusoidal_gamma_generator::has_proxies() const
{
  return not P_.individual_spike_trains_;
}
 
inline bool
sinusoidal_gamma_generator::local_receiver() const
{
  return true;
}
 
inline StimulationDevice::Type
sinusoidal_gamma_generator::get_type() const
{
  return StimulationDevice::Type::SPIKE_GENERATOR;
}
 
}  // namespace
 
#endif  // SINUSOIDAL_GAMMA_GENERATOR_H
 
#endif  // HAVE_GSL