stimulation_device.h

Go to the documentation of this file.

/*
 *  stimulation_device.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 STIMULATION_DEVICE_H
#define STIMULATION_DEVICE_H
 
// Includes from nestkernel:
#include "device.h"
#include "device_node.h"
#include "nest_types.h"
 
// Includes from libnestutil:
#include "compose.hpp"
 
// From standard library:
#include <string>
 
namespace nest
{
 
/* BeginUserDocs: NOINDEX
 
Short description
+++++++++++++++++
 
Stimulation device
 
Description
+++++++++++
 
All stimulation devices share the parameters ``start`` and ``stop``,
which control the stimulation period. The property ``origin`` is a
global offset that shifts the stimulation period. All three values are
set as times in ms.
 
- For spike-emitting devices, only spikes with times `t` that fulfill
  :math:`\mathrm{start} < t \leq \mathrm{stop}` are emitted. Spikes
  that have timestamp of :math:`t = \mathrm{start}` are not emitted.
 
- For current-emitting devices, the current is activated and
  deactivated such that the current first affects the target dynamics
  during the update step :math:`(\mathrm{start}, \mathrm{start}+h]`,
  that is, an effect can be recorded at the earliest at time
  :math:`\mathrm{start}+h`. The last interval during which the current
  affects the target's dynamics is :math:`(\textrm{stop}-h, \textrm{stop}]`.
 
The property ``stimulus_source`` defaults to an empty string. It can
be set to the name of a stimulation backend, in which case it will
take its parameters from the configured backend instead of from the
internally stored values. More details on available backends and their
properties can be found in the :ref:`guide to stimulating the network
<sec_stimulation_backends>`.
 
Parameters
++++++++++
 
label
    A string specifying an arbitrary textual label for the device.
    Stimulation backends might use the label to generate device specific
    identifiers like filenames and such. Default: ``""``.
 
origin
    A positive floating point number used as the reference time in ms
    for ``start`` and ``stop``. Default: ``0.0``.
 
start
    A positive floating point number specifying the activation time in ms,
    relative to ``origin``. Default: ``0.0``.
 
stimulus_source
    A string specifying the name of the stimulation backend from which to
    get the data for updating the stimulus parameters of the device.
    By default, the device uses its internally stored parameters for updating
    the stimulus. Default: ``""``.
 
stop
    A floating point number specifying the deactivation time in ms, relative
    to ``origin``. The value of ``stop`` must be greater than or equal to
    ``start``. Default: ``infinity``.
 
EndUserDocs */
 
class StimulationDevice : public DeviceNode, public Device
{
public:
  StimulationDevice();
  StimulationDevice( StimulationDevice const& );
  ~StimulationDevice() override = default;
 
  bool is_active( const Time& ) const override;
  void get_status( Dictionary& d ) const override;
  void set_status( const Dictionary& ) override;
 
  bool has_proxies() const override;
  std::string get_element_type() const override;
 
  using Device::init_buffers;
  using Device::init_state;
  using Device::pre_run_hook;
  using Node::pre_run_hook;
 
  void pre_run_hook() override;
 
  void enforce_single_syn_type( synindex );
 
  enum Type
  {
    CURRENT_GENERATOR,
    SPIKE_GENERATOR,
    DOUBLE_DATA_GENERATOR,
    DELAYED_RATE_CONNECTION_GENERATOR,
  };
 
  virtual Type
  get_type() const
  {
    throw KernelException( "WORNG TYPE" );
  };
  const std::string& get_label() const;
  virtual void set_data_from_stimulation_backend( std::vector< double >& ) {};
  void update( Time const&, const long, const long ) override {};
 
protected:
  void set_initialized_() final;
 
  struct Parameters_
  {
    std::string label_;            
    std::string stimulus_source_;  
 
    Parameters_();
    Parameters_( const Parameters_& ) = default;
    Parameters_& operator=( const Parameters_& ) = default;
    void get( Dictionary& ) const;
    void set( const Dictionary& );
  } P_;
 
private:
  synindex first_syn_id_;
 
  Dictionary backend_params_;
};
 
inline std::string
StimulationDevice::get_element_type() const
{
  return names::stimulator;
}
 
inline bool
StimulationDevice::has_proxies() const
{
  return false;
}
 
}  // namespace nest
 
#endif /* #ifndef STIMULATION_DEVICE_H */