Merge pull request #2853 from jougs/models

Allow setting volume_transmitter via NodeCollection, instead of naked ID

doc/htmldoc/whats_new/v3.6/index.rst

@@ -0,0 +1,40 @@
+.. _release_3.6:
+
+What's new in NEST 3.6
+======================
+
+This page contains a summary of important breaking and non-breaking
+changes from NEST 3.5 to NEST 3.6. In addition to the `release notes
+on GitHub <https://github.com/nest/nest-simulator/releases/>`_, this
+page also contains transition information that helps you to update
+your simulation scripts when you come from an older version of NEST.
+
+If you transition from an earlier version, please see our extensive
+:ref:`transition guide from NEST 2.x to 3.0 <refguide_2_3>` and the
+:ref:`list of updates for previous releases in the 3.x series
+<whats_new>`.
+
+
+New way to set the volume transmitter on STDP dopamine synapse
+--------------------------------------------------------------
+
+Previously, the :doc:`volume transmitter <../../../../models/volume_transmitter>`
+for the :doc:`STDP dopamine synapse <../../../../models/stdp_dopamine_synapse>` was
+set by supplying it with the "naked" node ID of the volume transmitter using its
+property `vt`. As it was rather inconvenient to obtain this ID and the procedure was
+inconsistent with how nodes are usually passed around in NEST, this is now no longer
+possible. Instead, the volume transmitter is now set by supplying a NodeCollection to
+the property `volume_transmitter` of the synapse's common properties:
+
++--------------------------------------------------+--------------------------------------------------+
+| Up to NEST 3.5                                   | from NEST 3.6 on                                 |
++==================================================+==================================================+
+|  ::                                              |  ::                                              |
+|                                                  |                                                  |
+|     vt = nest.Create("volume_tranmitter")        |     vt = nest.Create("volume_tranmitter")        |
+|     nest.SetDefaults(                            |     nest.SetDefaults(                            |
+|         "stdp_dopamine_synapse",                 |         "stdp_dopamine_synapse",                 |
+|         {"vt": vol.get("global_id")}             |          {"volume_transmitter": vt}              |
+|     )                                            |     )                                            |
+|                                                  |                                                  |
++--------------------------------------------------+--------------------------------------------------+

models/CMakeLists.txt

@@ -40,6 +40,7 @@ target_include_directories(models PRIVATE
     ${PROJECT_SOURCE_DIR}/thirdparty
     ${PROJECT_SOURCE_DIR}/libnestutil
     ${PROJECT_BINARY_DIR}/libnestutil
+    ${PROJECT_SOURCE_DIR}/models
     ${PROJECT_SOURCE_DIR}/sli
     ${PROJECT_SOURCE_DIR}/models
     ${PROJECT_SOURCE_DIR}/nestkernel

models/stdp_dopamine_synapse.cpp

@@ -39,7 +39,7 @@ namespace nest
 
 STDPDopaCommonProperties::STDPDopaCommonProperties()
   : CommonSynapseProperties()
-  , vt_( nullptr )
+  , volume_transmitter_( nullptr )
   , A_plus_( 1.0 )
   , A_minus_( 1.5 )
   , tau_plus_( 20.0 )
@@ -55,14 +55,9 @@ void
 STDPDopaCommonProperties::get_status( DictionaryDatum& d ) const
 {
   CommonSynapseProperties::get_status( d );
-  if ( vt_ )
-  {
-    def< long >( d, names::vt, vt_->get_node_id() );
-  }
-  else
-  {
-    def< long >( d, names::vt, -1 );
-  }
+
+  const NodeCollectionDatum vt = NodeCollectionDatum( NodeCollection::create( volume_transmitter_ ) );
+  def< NodeCollectionDatum >( d, names::volume_transmitter, vt );
 
   def< double >( d, names::A_plus, A_plus_ );
   def< double >( d, names::A_minus, A_minus_ );
@@ -79,16 +74,23 @@ STDPDopaCommonProperties::set_status( const DictionaryDatum& d, ConnectorModel&
 {
   CommonSynapseProperties::set_status( d, cm );
 
-  long vtnode_id;
-  if ( updateValue< long >( d, names::vt, vtnode_id ) )
+  NodeCollectionDatum vt_datum;
+  if ( updateValue< NodeCollectionDatum >( d, names::volume_transmitter, vt_datum ) )
   {
+    if ( vt_datum->size() != 1 )
+    {
+      throw BadProperty( "Property volume_transmitter must be a single element NodeCollection" );
+    }
+
     const size_t tid = kernel().vp_manager.get_thread_id();
-    Node* vt = kernel().node_manager.get_node_or_proxy( vtnode_id, tid );
-    vt_ = dynamic_cast< volume_transmitter* >( vt );
-    if ( not vt_ )
+    Node* vt_node = kernel().node_manager.get_node_or_proxy( ( *vt_datum )[ 0 ], tid );
+    volume_transmitter* vt = dynamic_cast< volume_transmitter* >( vt_node );
+    if ( not vt )
     {
-      throw BadProperty( "Dopamine source must be volume transmitter" );
+      throw BadProperty( "Property volume_transmitter must be set to a node of type volume_transmitter" );
     }
+
+    volume_transmitter_ = vt;
   }
 
   updateValue< double >( d, names::A_plus, A_plus_ );
@@ -101,17 +103,4 @@ STDPDopaCommonProperties::set_status( const DictionaryDatum& d, ConnectorModel&
   updateValue< double >( d, names::Wmax, Wmax_ );
 }
 
-Node*
-STDPDopaCommonProperties::get_node()
-{
-  if ( not vt_ )
-  {
-    throw BadProperty( "No volume transmitter has been assigned to the dopamine synapse." );
-  }
-  else
-  {
-    return vt_;
-  }
-}
-
 } // of namespace nest

models/stdp_dopamine_synapse.h

@@ -64,42 +64,40 @@ dopaminergic dynamics is calculated in the synapse itself.
 Parameters
 ++++++++++
 
-=========  ======= ======================================================
+=================== ============== ======================================================
 **Common properties**
--------------------------------------------------------------------------
- vt        integer ID of volume_transmitter collecting the spikes
-                   from the pool of dopamine releasing neurons and
-                   transmitting the spikes to the synapse. A value of
-                   -1 indicates that no volume transmitter has been
-                   assigned.
- A_plus    real    Multiplier applied to weight changes caused by
-                   pre-before-post spike pairings. If b (dopamine
-                   baseline concentration) is zero, then A_plus
-                   is simply the multiplier for facilitation (as in the
-                   stdp_synapse model). If b is not zero, then A_plus
-                   will be the multiplier for facilitation only if n - b
-                   is positive, where n is the instantenous dopamine
-                   concentration in the volume transmitter. If n - b is
-                   negative, A_plus will be the multiplier for
-                   depression.
- A_minus   real    Multiplier applied to weight changes caused by
-                   post-before-pre spike pairings. If b (dopamine
-                   baseline concentration) is zero, then A_minus
-                   is simply the multiplier for depression (as in the
-                   stdp_synapse model). If b is not zero, then A_minus
-                   will be the multiplier for depression only if n - b
-                   is positive, where n is the instantenous dopamine
-                   concentration in the volume transmitter. If n - b is
-                   negative, A_minus will be the multiplier for
-                   facilitation.
- tau_plus  ms      STDP time constant for weight changes caused by
-                   pre-before-post spike pairings.
- tau_c     ms      Time constant of eligibility trace
- tau_n     ms      Time constant of dopaminergic trace
- b         real    Dopaminergic baseline concentration
- Wmin      real    Minimal synaptic weight
- Wmax      real    Maximal synaptic weight
-=========  ======= ======================================================
+-----------------------------------------------------------------------------------------
+ volume_transmitter NodeCollection volume_transmitter collecting the spikes from the
+                                   pool of dopamine releasing neurons and transmitting
+                                   the spikes to the synapse.
+ A_plus              real          Multiplier applied to weight changes caused by
+                                   pre-before-post spike pairings. If b (dopamine
+                                   baseline concentration) is zero, then A_plus
+                                   is simply the multiplier for facilitation (as in the
+                                   stdp_synapse model). If b is not zero, then A_plus
+                                   will be the multiplier for facilitation only if n - b
+                                   is positive, where n is the instantenous dopamine
+                                   concentration in the volume transmitter. If n - b is
+                                   negative, A_plus will be the multiplier for
+                                   depression.
+ A_minus             real          Multiplier applied to weight changes caused by
+                                   post-before-pre spike pairings. If b (dopamine
+                                   baseline concentration) is zero, then A_minus
+                                   is simply the multiplier for depression (as in the
+                                   stdp_synapse model). If b is not zero, then A_minus
+                                   will be the multiplier for depression only if n - b
+                                   is positive, where n is the instantenous dopamine
+                                   concentration in the volume transmitter. If n - b is
+                                   negative, A_minus will be the multiplier for
+                                   facilitation.
+ tau_plus            ms            STDP time constant for weight changes caused by
+                                   pre-before-post spike pairings.
+ tau_c               ms            Time constant of eligibility trace
+ tau_n               ms            Time constant of dopaminergic trace
+ b                   real          Dopaminergic baseline concentration
+ Wmin                real          Minimal synaptic weight
+ Wmax                real          Maximal synaptic weight
+==================== ============= ======================================================
 
 The common properties can only be set by :py:func:`.SetDefaults` and apply
 to all instances of the synapse model.
@@ -157,11 +155,9 @@ class STDPDopaCommonProperties : public CommonSynapseProperties
    */
   void set_status( const DictionaryDatum& d, ConnectorModel& cm );
 
-  Node* get_node();
-
   long get_vt_node_id() const;
 
-  volume_transmitter* vt_;
+  volume_transmitter* volume_transmitter_;
   double A_plus_;
   double A_minus_;
   double tau_plus_;
@@ -175,9 +171,9 @@ class STDPDopaCommonProperties : public CommonSynapseProperties
 inline long
 STDPDopaCommonProperties::get_vt_node_id() const
 {
-  if ( vt_ )
+  if ( volume_transmitter_ )
   {
-    return vt_->get_node_id();
+    return volume_transmitter_->get_node_id();
   }
   else
   {
@@ -284,7 +280,7 @@ class stdp_dopamine_synapse : public Connection< targetidentifierT >
   void
   check_connection( Node& s, Node& t, size_t receptor_type, const CommonPropertiesType& cp )
   {
-    if ( not cp.vt_ )
+    if ( not cp.volume_transmitter_ )
     {
       throw BadProperty( "No volume transmitter has been assigned to the dopamine synapse." );
     }
@@ -390,7 +386,7 @@ template < typename targetidentifierT >
 void
 stdp_dopamine_synapse< targetidentifierT >::check_synapse_params( const DictionaryDatum& syn_spec ) const
 {
-  if ( syn_spec->known( names::vt ) )
+  if ( syn_spec->known( names::volume_transmitter ) )
   {
     throw NotImplemented(
       "Connect doesn't support the direct specification of the "
@@ -550,7 +546,7 @@ stdp_dopamine_synapse< targetidentifierT >::send( Event& e, size_t t, const STDP
   double t_spike = e.get_stamp().get_ms();
 
   // get history of dopamine spikes
-  const std::vector< spikecounter >& dopa_spikes = cp.vt_->deliver_spikes();
+  const std::vector< spikecounter >& dopa_spikes = cp.volume_transmitter_->deliver_spikes();
 
   // get spike history in relevant range (t_last_update, t_spike] from
   // postsynaptic neuron

nestkernel/CMakeLists.txt

@@ -152,6 +152,7 @@ target_include_directories( nestkernel PRIVATE
     ${PROJECT_SOURCE_DIR}/thirdparty
     ${PROJECT_SOURCE_DIR}/libnestutil
     ${PROJECT_BINARY_DIR}/libnestutil
+    ${PROJECT_SOURCE_DIR}/models
     ${PROJECT_SOURCE_DIR}/sli
     ${PROJECT_SOURCE_DIR}/nestkernel
     ${PROJECT_SOURCE_DIR}/nestkernel/spatial

nestkernel/common_synapse_properties.cpp

@@ -28,6 +28,9 @@
 #include "nest_types.h"
 #include "node.h"
 
+// Includes from models:
+#include "weight_recorder.h"
+
 // Includes from sli:
 #include "dictdatum.h"
 
@@ -36,7 +39,6 @@ namespace nest
 
 CommonSynapseProperties::CommonSynapseProperties()
   : weight_recorder_()
-  , wr_node_id_( 0 )
 {
 }
 
@@ -47,35 +49,31 @@ CommonSynapseProperties::~CommonSynapseProperties()
 void
 CommonSynapseProperties::get_status( DictionaryDatum& d ) const
 {
-  if ( weight_recorder_.get() )
-  {
-    def< NodeCollectionDatum >( d, names::weight_recorder, weight_recorder_ );
-  }
-  else
-  {
-    ArrayDatum ad;
-    def< ArrayDatum >( d, names::weight_recorder, ad );
-  }
+  const NodeCollectionDatum wr = NodeCollectionDatum( NodeCollection::create( weight_recorder_ ) );
+  def< NodeCollectionDatum >( d, names::weight_recorder, wr );
 }
 
 void
 CommonSynapseProperties::set_status( const DictionaryDatum& d, ConnectorModel& )
 {
-  const bool update_wr = updateValue< NodeCollectionDatum >( d, names::weight_recorder, weight_recorder_ );
-  if ( update_wr and weight_recorder_->size() > 1 )
-  {
-    throw BadProperty( "weight_recorder must be a single element NodeCollection" );
-  }
-  else if ( update_wr )
+  NodeCollectionDatum wr_datum;
+  if ( updateValue< NodeCollectionDatum >( d, names::weight_recorder, wr_datum ) )
   {
-    wr_node_id_ = ( *weight_recorder_ )[ 0 ];
-  }
-}
+    if ( wr_datum->size() != 1 )
+    {
+      throw BadProperty( "Property weight_recorder must be a single element NodeCollection" );
+    }
 
-Node*
-CommonSynapseProperties::get_node()
-{
-  return nullptr;
+    const size_t tid = kernel().vp_manager.get_thread_id();
+    Node* wr_node = kernel().node_manager.get_node_or_proxy( ( *wr_datum )[ 0 ], tid );
+    weight_recorder* wr = dynamic_cast< weight_recorder* >( wr_node );
+    if ( not wr )
+    {
+      throw BadProperty( "Property weight_recorder must be set to a node of type weight_recorder" );
+    }
+
+    weight_recorder_ = wr;
+  }
 }
 
 void

nestkernel/common_synapse_properties.h

@@ -37,6 +37,7 @@ namespace nest
 {
 
 // forward declarations
+class weight_recorder;
 class ConnectorModel;
 class TimeConverter;
 
@@ -76,30 +77,19 @@ class CommonSynapseProperties
    */
   void calibrate( const TimeConverter& );
 
-  /**
-   * Get reference to registering node
-   */
-  Node* get_node();
-
   /**
    * Get node ID of volume transmitter
    */
   long get_vt_node_id() const;
 
-  /**
-   * Get node ID of weight_recorder
-   */
-  size_t get_wr_node_id() const;
-
   /**
    * Get weight_recorder
    */
-  NodeCollectionDatum get_weight_recorder() const;
+  weight_recorder* get_weight_recorder() const;
 
 
 private:
-  NodeCollectionDatum weight_recorder_;
-  long wr_node_id_;
+  weight_recorder* weight_recorder_;
 };
 
 inline long
@@ -108,13 +98,7 @@ CommonSynapseProperties::get_vt_node_id() const
   return -1;
 }
 
-inline size_t
-CommonSynapseProperties::get_wr_node_id() const
-{
-  return wr_node_id_;
-}
-
-inline NodeCollectionDatum
+inline weight_recorder*
 CommonSynapseProperties::get_weight_recorder() const
 {
   return weight_recorder_;