correlospinmatrix_detector.h

Go to the documentation of this file.

/*
 *  correlospinmatrix_detector.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 CORRELOSPINMATRIX_DETECTOR_H
#define CORRELOSPINMATRIX_DETECTOR_H
 
 
// C++ includes:
#include <deque>
#include <vector>
 
// Includes from nestkernel:
#include "event.h"
#include "nest_timeconverter.h"
#include "nest_types.h"
#include "node.h"
#include "pseudo_recording_device.h"
 
 
namespace nest
{
 
/* BeginUserDocs: device, detector
 
Short description
+++++++++++++++++
 
Device for measuring the covariance matrix from several inputs
 
Description
+++++++++++
 
The ``correlospinmatrix_detector`` is a device that receives input from several
binary neuron sources and calculates the raw auto and cross correlation binned
to bins of duration delta_tau, which defaults to the simulation resolution.
 
The result can be obtained from the node's status dictionary under the key
``count_covariance`` in the format of a tensor of rank 3 of size
``N_channels`` x ``N_channels``, with each entry :math:`C_{ij}` being a vector
of size :math:`2\cdot\tau_{max}/\delta_{\tau} + 1` containing the histogram for
the different time lags.
 
The bins are centered around the time difference they represent, and are
left-closed and right-open in the lower triangular part of the matrix. On the
diagonal and in the upper triangular part the intervals are left-open and
right-closed. This ensures proper counting of events at the border of bins.
 
The ``correlospinmatrix_detector`` has a variable number of inputs which can be
set via SetStatus under the key N_channels. All incoming connections to a
specified receptor will be pooled.
 
Setting either N_channels, Tstart, Tstop, tau_max or delta_tau clears
count_covariance.
 
Correlospinmatrix detectors ignore any connection delays.
 
See :doc:`../auto_examples/correlospinmatrix_detector_two_neuron` for
a script reproducing a setting studied in Fig 1 of Grinzburg &
Sompolinsky (1994) PRE 50(4) p. 3171.
 
Parameters
++++++++++
 
================ ========= ====================================================
Tstart           real      Time when to start counting events. This time should
                           be set to at least start + tau_max in order to avoid
                           edge effects of the correlation counts.
Tstop            real      Time when to stop counting events. This time should
                           be set to at most Tsim - tau_max, where Tsim is the
                           duration of simulation, in order to avoid edge
                           effects of the correlation counts.
delta_tau        ms        Bin width. This has to be an odd multiple of
                           the resolution, to allow the symmetry between
                           positive and negative time-lags. Defaults to the
                           simulation resolution.
tau_max          ms        One-sided width. In the lower triagnular part
                           events with differences in [0, tau_max+delta_tau/2)
                           are counted. On the diagonal and in the upper
                           triangular part events with differences in
                           (0, tau_max+delta_tau/2]. Defaults to 10 times the
                           value of delta_tau.
N_channels       integer   The number of pools. This defines the range of
                           receptor_type. Default is 1.
                           Setting N_channels clears count_covariance,
                           covariance and n_events.
covariance       3D        matrix of read-only -raw, weighted, auto/cross
                 matrix of correlation
                 integers
count_covariance 3D        matrix of read-only -raw, auto/cross correlation
                 matrix of counts
                 integers
================ ========= ====================================================
 
Receives
++++++++
 
SpikeEvent
 
See also
++++++++
 
correlation_detector, correlomatrix_detector, spike_recorder
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: correlospinmatrix_detector
 
EndUserDocs */
 
void register_correlospinmatrix_detector( const std::string& name );
 
class correlospinmatrix_detector : public Node
{
 
public:
  correlospinmatrix_detector();
  correlospinmatrix_detector( const correlospinmatrix_detector& );
 
  bool
  has_proxies() const override
  {
    return true;
  }
 
  std::string
  get_element_type() const override
  {
    return names::recorder;
  }
 
  using Node::handle;
  using Node::handles_test_event;
  using Node::receives_signal;
 
  void handle( SpikeEvent& ) override;
 
  size_t handles_test_event( SpikeEvent&, size_t ) override;
 
  SignalType receives_signal() const override;
 
  void get_status( Dictionary& ) const override;
  void set_status( const Dictionary& ) override;
 
  void calibrate_time( const TimeConverter& tc ) override;
 
private:
  void init_state_() override;
  void init_buffers_() override;
  void pre_run_hook() override;
 
  void update( Time const&, const long, const long ) override;
 
  // ------------------------------------------------------------
 
  struct BinaryPulse_
  {
    long t_on_;
    long t_off_;
    long receptor_channel_;
 
    BinaryPulse_( long timeon, long timeoff, long receptorchannel )
      : t_on_( timeon )
      , t_off_( timeoff )
      , receptor_channel_( receptorchannel )
    {
    }
 
    inline bool
    operator>( const BinaryPulse_& second ) const
    {
      return t_off_ > second.t_off_;
    }
  };
 
  typedef std::deque< BinaryPulse_ > BinaryPulselistType;
 
  // ------------------------------------------------------------
 
  struct State_;
 
  struct Parameters_
  {
    Time delta_tau_;     
    Time tau_max_;       
    Time Tstart_;        
    Time Tstop_;         
    size_t N_channels_;  
 
    Parameters_();                      
    Parameters_( const Parameters_& );  
 
    Parameters_& operator=( const Parameters_& );
 
    void get( Dictionary& ) const;  
 
    bool set( const Dictionary&, const correlospinmatrix_detector&, Node* );
 
    Time get_default_delta_tau();
  };
 
  // ------------------------------------------------------------
 
  struct State_
  {
    BinaryPulselistType incoming_;  
    size_t last_i_;
    Time t_last_in_spike_;
 
    bool tentative_down_;
 
    std::vector< bool > curr_state_;  
 
    std::vector< long > last_change_;
 
    std::vector< std::vector< std::vector< long > > > count_covariance_;
 
    State_();  
 
    void get( Dictionary& ) const;
 
    void set( const Dictionary&, const Parameters_&, bool, Node* );
 
    void reset( const Parameters_& );
  };
 
  // ------------------------------------------------------------
 
  PseudoRecordingDevice device_;
  Parameters_ P_;
  State_ S_;
};
 
inline size_t
correlospinmatrix_detector::handles_test_event( SpikeEvent&, size_t receptor_type )
{
  if ( receptor_type > P_.N_channels_ - 1 )
  {
    throw UnknownReceptorType( receptor_type, get_name() );
  }
  return receptor_type;
}
 
inline void
correlospinmatrix_detector::get_status( Dictionary& d ) const
{
  device_.get_status( d );
  P_.get( d );
  S_.get( d );
}
 
inline void
correlospinmatrix_detector::set_status( const Dictionary& d )
{
  Parameters_ ptmp = P_;
  const bool reset_required = ptmp.set( d, *this, this );
 
  device_.set_status( d );
  P_ = ptmp;
  if ( reset_required )
  {
    S_.reset( P_ );
  }
}
 
 
inline SignalType
correlospinmatrix_detector::receives_signal() const
{
  return BINARY;
}
 
inline Time
correlospinmatrix_detector::Parameters_::get_default_delta_tau()
{
  return Time::get_resolution();
}
 
}  // namespace
 
#endif /* #ifndef CORRELOSPINMATRIX_DETECTOR_H */