Add infrastructure for generic input backends to feed devices

doc/userdoc/guides/recording_from_simulations.rst

@@ -96,6 +96,7 @@ properties can be obtained from the kernel's status dictionary.
    nest.GetKernelStatus("recording_backends")
    {u'ascii': {},
     u'memory': {},
+    u'mpi': {},
     u'screen': {},
     u'sionlib': {u'buffer_size': 1024,
      u'filename': u'',
@@ -118,3 +119,4 @@ NEST:
 - :ref:`recording_backend_ascii`
 - :ref:`recording_backend_screen`
 - :ref:`recording_backend_sionlib`
+- :ref:`recording_backend_mpi`

doc/userdoc/guides/stimulating_the_network.rst

@@ -22,6 +22,31 @@ stimulating devices (origin is just a global offset):
   recorded at the earliest at time start+h. The last interval during
   which the current affects the target's dynamics is (stop-h, stop].
 
-
-.. doxygengroup:: generator
-   :content-only:
+Common recorder properties
+--------------------------
+.. glossary::
+
+ stimulus_source
+   A string (default: `""`) containing the name of the stimulating
+   backend, where to get the data for updating the stimulating device.
+   By default the device uses only its parameters for updating this stimulus.
+
+ label
+   A string (default: `""`) specifying an arbitrary textual label for
+   the device.
+   The `mpi` use this label to localize the file which contains port description.
+
+How to update stimulating devices with MPI communication?
+---------------------------------------------------------
+
+The stimulating device can be updated between each run of Nest.
+Currently, only `mpi` communication can be used to receive data which can replace the default signals 
+generated internally by stimulating devices. 
+The 'mpi' mackend backend makes use of the label of the device in order to find the port description 
+for the connection with the external software.
+The format of the data received by Nest for updating the stimulating devices depends on the type of device. 
+For more information, please look at the documentation of each device.
+
+For more information on the internal protocol used by the 'mpi' backend for stimulating devices please
+refer to:
+- :ref:`stimulating_backend_mpi`

models/ac_generator.cpp

@@ -139,8 +139,7 @@ nest::ac_generator::Parameters_::set( const DictionaryDatum& d, Node* node )
  * ---------------------------------------------------------------- */
 
 nest::ac_generator::ac_generator()
-  : DeviceNode()
-  , device_()
+  : StimulatingDevice()
   , P_()
   , S_()
   , B_( *this )
@@ -149,8 +148,7 @@ nest::ac_generator::ac_generator()
 }
 
 nest::ac_generator::ac_generator( const ac_generator& n )
-  : DeviceNode( n )
-  , device_( n.device_ )
+  : StimulatingDevice( n )
   , P_( n.P_ )
   , S_( n.S_ )
   , B_( n.B_, *this )
@@ -167,14 +165,14 @@ nest::ac_generator::init_state_( const Node& proto )
 {
   const ac_generator& pr = downcast< ac_generator >( proto );
 
-  device_.init_state( pr.device_ );
+  StimulatingDevice::init_state( pr );
   S_ = pr.S_;
 }
 
 void
 nest::ac_generator::init_buffers_()
 {
-  device_.init_buffers();
+  StimulatingDevice::init_buffers();
   B_.logger_.reset();
 }
 
@@ -183,7 +181,7 @@ nest::ac_generator::calibrate()
 {
   B_.logger_.init();
 
-  device_.calibrate();
+  StimulatingDevice::calibrate();
 
   const double h = Time::get_resolution().get_ms();
   const double t = kernel().simulation_manager.get_time().get_ms();
@@ -221,7 +219,7 @@ nest::ac_generator::update( Time const& origin, const long from, const long to )
     S_.y_1_ = V_.A_10_ * y_0 + V_.A_11_ * S_.y_1_;
 
     S_.I_ = 0.0;
-    if ( device_.is_active( Time::step( start + lag ) ) )
+    if ( StimulatingDevice::is_active( Time::step( start + lag ) ) )
     {
       S_.I_ = S_.y_1_ + P_.offset_;
       ce.set_current( S_.I_ );
@@ -236,3 +234,32 @@ nest::ac_generator::handle( DataLoggingRequest& e )
 {
   B_.logger_.handle( e );
 }
+
+/* ----------------------------------------------------------------
+ * Other functions
+ * ---------------------------------------------------------------- */
+
+void
+nest::ac_generator::set_data_from_stimulating_backend( std::vector< double >& input_param )
+{
+  Parameters_ ptmp = P_; // temporary copy in case of errors
+
+  // For the input backend
+  if ( not input_param.empty() )
+  {
+    if ( input_param.size() != 4 )
+    {
+      throw BadParameterValue(
+        "The size of the data for the ac_generator needs to be 4 [amplitude, offset, frequency, phase]." );
+    }
+    DictionaryDatum d = DictionaryDatum( new Dictionary );
+    ( *d )[ names::amplitude ] = DoubleDatum( input_param[ 0 ] );
+    ( *d )[ names::offset ] = DoubleDatum( input_param[ 1 ] );
+    ( *d )[ names::frequency ] = DoubleDatum( input_param[ 2 ] );
+    ( *d )[ names::phase ] = DoubleDatum( input_param[ 3 ] );
+    ptmp.set( d, this );
+  }
+
+  // if we get here, temporary contains consistent set of properties
+  P_ = ptmp;
+}

models/ac_generator.h

@@ -68,6 +68,18 @@ Parameters
 Setting start and stop only windows the current as defined above. It does not shift
 the time axis. See :doc:`stimulating_the_network` for details.
 
+Update from stimulating backend
++++++++++++++++++++++++++++++++
+
+The parameters in this stimulating device can be updated with input
+coming from a stimulating backend. The data structure used for the update
+holds one value for each of the parameters mentioned in the section above.
+The indexing is as follows:
+amplitude = input_param[ 0 ]
+offset = input_param[ 1 ]
+frequency = input_param[ 2 ]
+phase = input_param[ 3 ]
+
 References
 ++++++++++
 
@@ -83,57 +95,44 @@ CurrentEvent
 See also
 ++++++++
 
-dc_generator, noise_generator, step_current_generator
+dc_generator, noise_generator, step_current_generator, StimulatingDevice,
+Device
 
 EndUserDocs */
 
 namespace nest
 {
-
-class ac_generator : public DeviceNode
+class ac_generator : public StimulatingDevice
 {
 
 public:
   ac_generator();
   ac_generator( const ac_generator& );
 
-  bool
-  has_proxies() const
-  {
-    return false;
-  }
-
   //! Allow multimeter to connect to local instances
-  bool
-  local_receiver() const
-  {
-    return true;
-  }
-
-  Name
-  get_element_type() const
-  {
-    return names::stimulator;
-  }
+  bool local_receiver() const override;
 
-  port send_test_event( Node&, rport, synindex, bool );
+  port send_test_event( Node&, rport, synindex, bool ) override;
 
   using Node::handle;
   using Node::handles_test_event;
 
-  void handle( DataLoggingRequest& );
+  void handle( DataLoggingRequest& ) override;
+
+  port handles_test_event( DataLoggingRequest&, rport ) override;
 
-  port handles_test_event( DataLoggingRequest&, rport );
+  void get_status( DictionaryDatum& ) const override;
+  void set_status( const DictionaryDatum& ) override;
 
-  void get_status( DictionaryDatum& ) const;
-  void set_status( const DictionaryDatum& );
+  StimulatingDevice::Type get_type() const override;
+  void set_data_from_stimulating_backend( std::vector< double >& input_param ) override;
 
 private:
-  void init_state_( const Node& );
-  void init_buffers_();
-  void calibrate();
+  void init_state_( const Node& ) override;
+  void init_buffers_() override;
+  void calibrate() override;
 
-  void update( Time const&, const long, const long );
+  void update( Time const&, const long, const long ) override;
 
 
   // ------------------------------------------------------------
@@ -180,7 +179,7 @@ class ac_generator : public DeviceNode
    */
   struct Buffers_
   {
-    Buffers_( ac_generator& );
+    explicit Buffers_( ac_generator& );
     Buffers_( const Buffers_&, ac_generator& );
     UniversalDataLogger< ac_generator > logger_;
   };
@@ -189,9 +188,6 @@ class ac_generator : public DeviceNode
 
   struct Variables_
   {
-    double omega_;   //!< Angelfrequency i rad/s
-    double phi_rad_; //!< Phase of sine current (0-2Pi rad)
-
     // The exact integration matrix
     double A_00_;
     double A_01_;
@@ -207,7 +203,6 @@ class ac_generator : public DeviceNode
 
   // ------------------------------------------------------------
 
-  StimulatingDevice< CurrentEvent > device_;
   static RecordablesMap< ac_generator > recordablesMap_;
   Parameters_ P_;
   State_ S_;
@@ -218,7 +213,7 @@ class ac_generator : public DeviceNode
 inline port
 ac_generator::send_test_event( Node& target, rport receptor_type, synindex syn_id, bool )
 {
-  device_.enforce_single_syn_type( syn_id );
+  StimulatingDevice::enforce_single_syn_type( syn_id );
 
   CurrentEvent e;
   e.set_sender( *this );
@@ -241,7 +236,7 @@ ac_generator::get_status( DictionaryDatum& d ) const
 {
   P_.get( d );
   S_.get( d );
-  device_.get_status( d );
+  StimulatingDevice::get_status( d );
 
   ( *d )[ names::recordables ] = recordablesMap_.get_list();
 }
@@ -257,12 +252,24 @@ ac_generator::set_status( const DictionaryDatum& d )
   // 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 );
+  StimulatingDevice::set_status( d );
 
   // if we get here, temporaries contain consistent set of properties
   P_ = ptmp;
 }
 
+inline bool
+ac_generator::local_receiver() const
+{
+  return true;
+}
+
+inline StimulatingDevice::Type
+ac_generator::get_type() const
+{
+  return StimulatingDevice::Type::CURRENT_GENERATOR;
+}
+
 } // namespace
 
 #endif // AC_GENERATOR_H

models/dc_generator.cpp

@@ -112,8 +112,7 @@ nest::dc_generator::Parameters_::set( const DictionaryDatum& d, Node* node )
  * ---------------------------------------------------------------- */
 
 nest::dc_generator::dc_generator()
-  : DeviceNode()
-  , device_()
+  : StimulatingDevice()
   , P_()
   , S_()
   , B_( *this )
@@ -122,8 +121,7 @@ nest::dc_generator::dc_generator()
 }
 
 nest::dc_generator::dc_generator( const dc_generator& n )
-  : DeviceNode( n )
-  , device_( n.device_ )
+  : StimulatingDevice( n )
   , P_( n.P_ )
   , S_( n.S_ )
   , B_( n.B_, *this )
@@ -140,14 +138,14 @@ nest::dc_generator::init_state_( const Node& proto )
 {
   const dc_generator& pr = downcast< dc_generator >( proto );
 
-  device_.init_state( pr.device_ );
+  StimulatingDevice::init_state( pr );
   S_ = pr.S_;
 }
 
 void
 nest::dc_generator::init_buffers_()
 {
-  device_.init_buffers();
+  StimulatingDevice::init_buffers();
   B_.logger_.reset();
 }
 
@@ -156,7 +154,7 @@ nest::dc_generator::calibrate()
 {
   B_.logger_.init();
 
-  device_.calibrate();
+  StimulatingDevice::calibrate();
 }
 
 
@@ -177,8 +175,7 @@ nest::dc_generator::update( Time const& origin, const long from, const long to )
   for ( long offs = from; offs < to; ++offs )
   {
     S_.I_ = 0.0;
-
-    if ( device_.is_active( Time::step( start + offs ) ) )
+    if ( StimulatingDevice::is_active( Time::step( start + offs ) ) )
     {
       S_.I_ = P_.amp_;
       kernel().event_delivery_manager.send( *this, ce, offs );
@@ -192,3 +189,24 @@ nest::dc_generator::handle( DataLoggingRequest& e )
 {
   B_.logger_.handle( e );
 }
+
+void
+nest::dc_generator::set_data_from_stimulating_backend( std::vector< double >& input_param )
+{
+  Parameters_ ptmp = P_; // temporary copy in case of errors
+
+  // For the input backend
+  if ( not input_param.empty() )
+  {
+    if ( input_param.size() != 1 )
+    {
+      throw BadParameterValue( "The size of the data for the dc_generator needs to be 1 [amplitude]." );
+    }
+    DictionaryDatum d = DictionaryDatum( new Dictionary );
+    ( *d )[ names::amplitude ] = DoubleDatum( input_param[ 0 ] );
+    ptmp.set( d, this );
+  }
+
+  // if we get here, temporary contains consistent set of properties
+  P_ = ptmp;
+}