Re-organise tripartite connectivity generation to support multiple primary connection rules

nestkernel/conn_builder_conngen.cpp

@@ -35,12 +35,15 @@ namespace nest
 
 ConnectionGeneratorBuilder::ConnectionGeneratorBuilder( NodeCollectionPTR sources,
   NodeCollectionPTR targets,
+  ThirdOutBuilder* third_out,
   const DictionaryDatum& conn_spec,
   const std::vector< DictionaryDatum >& syn_specs )
-  : ConnBuilder( sources, targets, conn_spec, syn_specs )
+  : BipartiteConnBuilder( sources, targets, third_out, conn_spec, syn_specs )
   , cg_( ConnectionGeneratorDatum() )
   , params_map_()
 {
+  assert( third_out == nullptr );
+
   updateValue< ConnectionGeneratorDatum >( conn_spec, "cg", cg_ );
   if ( cg_->arity() != 0 )
   {

nestkernel/conn_builder_conngen.h

@@ -69,14 +69,15 @@ namespace nest
  * interface MPI aware and communicating the masks during connection
  * setup.
  */
-class ConnectionGeneratorBuilder : public ConnBuilder
+class ConnectionGeneratorBuilder : public BipartiteConnBuilder
 {
   typedef std::vector< ConnectionGenerator::ClosedInterval > RangeSet;
   typedef ConnectionGenerator::ClosedInterval Range;
 
 public:
   ConnectionGeneratorBuilder( NodeCollectionPTR,
     NodeCollectionPTR,
+    ThirdOutBuilder*,
     const DictionaryDatum&,
     const std::vector< DictionaryDatum >& );
 

nestkernel/conn_builder_factory.h

@@ -53,105 +53,67 @@ class GenericConnBuilderFactory
   /**
    * Factory method for builders for bipartite connection rules (the default).
    */
-  virtual ConnBuilder* create( NodeCollectionPTR,
+  virtual BipartiteConnBuilder* create( NodeCollectionPTR,
     NodeCollectionPTR,
+    ThirdOutBuilder*,
     const DictionaryDatum&,
     const std::vector< DictionaryDatum >& ) const = 0;
-
-  /**
-   * Factory method for builders for tripartite connection rules.
-   */
-  virtual ConnBuilder* create( NodeCollectionPTR,
-    NodeCollectionPTR,
-    NodeCollectionPTR,
-    const DictionaryDatum&,
-    const std::map< Name, std::vector< DictionaryDatum > >& ) const = 0;
 };
 
 /**
  * Factory class for ConnBuilders
- *
- * This template class provides an interface with bipartite and tripartite `create()` methods.
- * Implementation is delegated to explicit template specialisations below, which only implement
- * the `create()` method with the proper arity depending on the `is_tripartite` flag of
- * the pertaining conn builder.
  */
-template < typename ConnBuilderType, bool is_tripartite = ConnBuilderType::is_tripartite >
+template < typename ConnBuilderType >
 class ConnBuilderFactory : public GenericConnBuilderFactory
 {
 public:
-  ConnBuilder*
+  BipartiteConnBuilder*
   create( NodeCollectionPTR sources,
     NodeCollectionPTR targets,
+    ThirdOutBuilder* third_out,
     const DictionaryDatum& conn_spec,
     const std::vector< DictionaryDatum >& syn_specs ) const override
   {
-    assert( false ); // only specialisations should be called
-  }
-
-  //! create tripartite builder
-  ConnBuilder*
-  create( NodeCollectionPTR sources,
-    NodeCollectionPTR targets,
-    NodeCollectionPTR third,
-    const DictionaryDatum& conn_spec,
-    const std::map< Name, std::vector< DictionaryDatum > >& syn_specs ) const override
-  {
-    assert( false ); // only specialisations should be called
+    return new ConnBuilderType( sources, targets, third_out, conn_spec, syn_specs );
   }
 };
 
-
-// Specialisation for bipartite ConnBuilders
-template < typename ConnBuilderType >
-class ConnBuilderFactory< ConnBuilderType, false > : public GenericConnBuilderFactory
+class GenericThirdConnBuilderFactory
 {
-  ConnBuilder*
-  create( NodeCollectionPTR sources,
-    NodeCollectionPTR targets,
-    const DictionaryDatum& conn_spec,
-    const std::vector< DictionaryDatum >& syn_specs ) const override
+public:
+  virtual ~GenericThirdConnBuilderFactory()
   {
-    return new ConnBuilderType( sources, targets, conn_spec, syn_specs );
   }
 
-  ConnBuilder*
-  create( NodeCollectionPTR sources,
-    NodeCollectionPTR targets,
-    NodeCollectionPTR third,
-    const DictionaryDatum& conn_spec,
-    const std::map< Name, std::vector< DictionaryDatum > >& syn_specs ) const override
-  {
-    throw IllegalConnection( String::compose(
-      "Connection rule '%1' does not support tripartite connections.", ( *conn_spec )[ names::rule ] ) );
-  }
+  /**
+   * Factory method for builders for bipartite connection rules (the default).
+   */
+  virtual ThirdOutBuilder* create( NodeCollectionPTR,
+    NodeCollectionPTR,
+    ThirdInBuilder*,
+    const DictionaryDatum&,
+    const std::vector< DictionaryDatum >& ) const = 0;
 };
 
-// Specialisation for tripartite ConnBuilders
-template < typename ConnBuilderType >
-class ConnBuilderFactory< ConnBuilderType, true > : public GenericConnBuilderFactory
+/**
+ * Factory class for Third-factor ConnBuilders
+ */
+template < typename ThirdConnBuilderType >
+class ThirdConnBuilderFactory : public GenericThirdConnBuilderFactory
 {
-  ConnBuilder*
+public:
+  ThirdOutBuilder*
   create( NodeCollectionPTR sources,
     NodeCollectionPTR targets,
+    ThirdInBuilder* third_in,
     const DictionaryDatum& conn_spec,
     const std::vector< DictionaryDatum >& syn_specs ) const override
   {
-    throw BadProperty(
-      String::compose( "Connection rule %1 only supports tripartite connections.", ( *conn_spec )[ names::rule ] ) );
-  }
-
-  ConnBuilder*
-  create( NodeCollectionPTR sources,
-    NodeCollectionPTR targets,
-    NodeCollectionPTR third,
-    const DictionaryDatum& conn_spec,
-    const std::map< Name, std::vector< DictionaryDatum > >& syn_specs ) const override
-  {
-    return new ConnBuilderType( sources, targets, third, conn_spec, syn_specs );
+    return new ThirdConnBuilderType( sources, targets, third_in, conn_spec, syn_specs );
   }
 };
 
+
 } // namespace nest
 
 #endif

nestkernel/conn_builder_impl.h

@@ -33,7 +33,7 @@ namespace nest
 {
 
 inline void
-ConnBuilder::single_disconnect_( size_t snode_id, Node& target, size_t target_thread )
+BipartiteConnBuilder::single_disconnect_( size_t snode_id, Node& target, size_t target_thread )
 {
   // index tnode_id = target.get_node_id();
   // This is the most simple case in which only the synapse_model_ has been

nestkernel/connection_manager.cpp

@@ -68,6 +68,8 @@
 nest::ConnectionManager::ConnectionManager()
   : connruledict_( new Dictionary() )
   , connbuilder_factories_()
+  , thirdconnruledict_( new Dictionary() )
+  , thirdconnbuilder_factories_()
   , min_delay_( 1 )
   , max_delay_( 1 )
   , keep_source_table_( true )
@@ -104,9 +106,9 @@
     register_conn_builder< FixedOutDegreeBuilder >( "fixed_outdegree" );
     register_conn_builder< BernoulliBuilder >( "pairwise_bernoulli" );
     register_conn_builder< PoissonBuilder >( "pairwise_poisson" );
-    register_conn_builder< TripartiteBernoulliWithPoolBuilder >( "tripartite_bernoulli_with_pool" );
     register_conn_builder< SymmetricBernoulliBuilder >( "symmetric_pairwise_bernoulli" );
     register_conn_builder< FixedTotalNumberBuilder >( "fixed_total_number" );
+    register_third_conn_builder< ThirdBernoulliWithPoolBuilder >( "third_factor_bernoulli_with_pool" );
 #ifdef HAVE_LIBNEUROSIM
     register_conn_builder< ConnectionGeneratorBuilder >( "conngen" );
 #endif
@@ -171,6 +173,13 @@
     }
     connbuilder_factories_.clear();
     connruledict_->clear();
+
+    for ( auto tcbf : thirdconnbuilder_factories_ )
+    {
+      delete tcbf;
+    }
+    thirdconnbuilder_factories_.clear();
+    thirdconnruledict_->clear();
   }
 }
 
@@ -376,29 +385,42 @@
   return user_set_delay_extrema;
 }
 
-nest::ConnBuilder*
+nest::BipartiteConnBuilder*
 nest::ConnectionManager::get_conn_builder( const std::string& name,
   NodeCollectionPTR sources,
   NodeCollectionPTR targets,
+  ThirdOutBuilder* third_out,
   const DictionaryDatum& conn_spec,
   const std::vector< DictionaryDatum >& syn_specs )
 {
+  if ( not connruledict_->known( name ) )
+  {
+    throw IllegalConnection( String::compose( "Unknown connection rule '%1'.", name ) );
+  }
+
   const size_t rule_id = connruledict_->lookup( name );
-  ConnBuilder* cb = connbuilder_factories_.at( rule_id )->create( sources, targets, conn_spec, syn_specs );
+  BipartiteConnBuilder* cb =
+    connbuilder_factories_.at( rule_id )->create( sources, targets, third_out, conn_spec, syn_specs );
   assert( cb );
   return cb;
 }
 
-nest::ConnBuilder*
-nest::ConnectionManager::get_conn_builder( const std::string& name,
+nest::ThirdOutBuilder*
+nest::ConnectionManager::get_third_conn_builder( const std::string& name,
   NodeCollectionPTR sources,
   NodeCollectionPTR targets,
-  NodeCollectionPTR third,
+  ThirdInBuilder* third_in,
   const DictionaryDatum& conn_spec,
-  const std::map< Name, std::vector< DictionaryDatum > >& syn_specs )
+  const std::vector< DictionaryDatum >& syn_specs )
 {
-  const size_t rule_id = connruledict_->lookup( name );
-  ConnBuilder* cb = connbuilder_factories_.at( rule_id )->create( sources, targets, third, conn_spec, syn_specs );
+  if ( not thirdconnruledict_->known( name ) )
+  {
+    throw IllegalConnection( String::compose( "Unknown third-factor connection rule '%1'.", name ) );
+  }
+
+  const size_t rule_id = thirdconnruledict_->lookup( name );
+  ThirdOutBuilder* cb =
+    thirdconnbuilder_factories_.at( rule_id )->create( sources, targets, third_in, conn_spec, syn_specs );
   assert( cb );
   return cb;
 }
@@ -438,14 +460,14 @@
   {
     throw BadProperty( "The connection specification must contain a connection rule." );
   }
-  const std::string rule_name = static_cast< const std::string >( ( *conn_spec )[ names::rule ] );
+  const std::string rule = static_cast< const std::string >( ( *conn_spec )[ names::rule ] );
 
-  if ( not connruledict_->known( rule_name ) )
+  if ( not connruledict_->known( rule ) )
   {
-    throw BadProperty( String::compose( "Unknown connection rule: %1", rule_name ) );
+    throw BadProperty( String::compose( "Unknown connection rule: %1", rule ) );
   }
 
-  ConnBuilder* cb = get_conn_builder( rule_name, sources, targets, conn_spec, syn_specs );
+  ConnBuilder cb( rule, sources, targets, conn_spec, syn_specs );
 
   // at this point, all entries in conn_spec and syn_spec have been checked
   ALL_ENTRIES_ACCESSED( *conn_spec, "Connect", "Unread dictionary entries in conn_spec: " );
@@ -457,8 +479,7 @@
   // Set flag before calling cb->connect() in case exception is thrown after some connections have been created.
   set_connections_have_changed();
 
-  cb->connect();
-  delete cb;
+  cb.connect();
 }
 
 
@@ -784,7 +805,7 @@
 }
 
 void
 nest::ConnectionManager::connect_sonata( const DictionaryDatum& graph_specs, const long hyberslab_size )
 {
 #ifdef HAVE_HDF5
   SonataConnector sonata_connector( graph_specs, hyberslab_size );
@@ -803,6 +824,7 @@
   NodeCollectionPTR targets,
   NodeCollectionPTR third,
   const DictionaryDatum& conn_spec,
+  const DictionaryDatum& third_conn_spec,
   const std::map< Name, std::vector< DictionaryDatum > >& syn_specs )
 {
   if ( sources->empty() )
@@ -831,14 +853,15 @@
   {
     throw BadProperty( "The connection specification must contain a connection rule." );
   }
-  const std::string rule_name = static_cast< const std::string >( ( *conn_spec )[ names::rule ] );
-
-  if ( not connruledict_->known( rule_name ) )
+  if ( not third_conn_spec->known( names::rule ) )
   {
-    throw BadProperty( String::compose( "Unknown connection rule: %1", rule_name ) );
+    throw BadProperty( "The third-factor connection specification must contain a connection rule." );
   }
 
-  ConnBuilder* cb = get_conn_builder( rule_name, sources, targets, third, conn_spec, syn_specs );
+  const std::string primary_rule = static_cast< const std::string >( ( *conn_spec )[ names::rule ] );
+  const std::string third_rule = static_cast< const std::string >( ( *third_conn_spec )[ names::rule ] );
+
+  ConnBuilder cb( primary_rule, third_rule, sources, targets, third, conn_spec, third_conn_spec, syn_specs );
 
   // at this point, all entries in conn_spec and syn_spec have been checked
   ALL_ENTRIES_ACCESSED( *conn_spec, "Connect", "Unread dictionary entries in conn_spec: " );
@@ -853,8 +876,7 @@
   // Set flag before calling cb->connect() in case exception is thrown after some connections have been created.
   set_connections_have_changed();
 
-  cb->connect();
-  delete cb;
+  cb.connect();
 }
 
 

nestkernel/connection_manager.h

@@ -53,6 +53,7 @@
 namespace nest
 {
 class GenericConnBuilderFactory;
+class GenericThirdConnBuilderFactory;
 class spikecounter;
 class Node;
 class Event;
@@ -94,20 +95,27 @@ class ConnectionManager : public ManagerInterface
   template < typename ConnBuilder >
   void register_conn_builder( const std::string& name );
 
+  /**
+   * Add a connectivity rule, i.e. the respective ConnBuilderFactory.
+   */
+  template < typename ThirdConnBuilder >
+  void register_third_conn_builder( const std::string& name );
+
   //! Obtain builder for bipartite connections
-  ConnBuilder* get_conn_builder( const std::string& name,
+  BipartiteConnBuilder* get_conn_builder( const std::string& name,
     NodeCollectionPTR sources,
     NodeCollectionPTR targets,
+    ThirdOutBuilder* third_out,
     const DictionaryDatum& conn_spec,
     const std::vector< DictionaryDatum >& syn_specs );
 
-  //! Obtain builder for tripartite connections
-  ConnBuilder* get_conn_builder( const std::string& name,
+  //! Obtain builder for bipartite connections
+  ThirdOutBuilder* get_third_conn_builder( const std::string& name,
     NodeCollectionPTR sources,
     NodeCollectionPTR targets,
-    NodeCollectionPTR third,
+    ThirdInBuilder* third_in,
     const DictionaryDatum& conn_spec,
-    const std::map< Name, std::vector< DictionaryDatum > >& syn_specs );
+    const std::vector< DictionaryDatum >& syn_specs );
 
   /**
    * Create connections.
@@ -192,6 +200,7 @@ class ConnectionManager : public ManagerInterface
     NodeCollectionPTR targets,
     NodeCollectionPTR third,
     const DictionaryDatum& connectivity,
+    const DictionaryDatum& third_connectivity,
     const std::map< Name, std::vector< DictionaryDatum > >& synapse_specs );
 
   size_t find_connection( const size_t tid, const synindex syn_id, const size_t snode_id, const size_t tnode_id );
@@ -640,6 +649,11 @@ class ConnectionManager : public ManagerInterface
   //! ConnBuilder factories, indexed by connruledict_ elements.
   std::vector< GenericConnBuilderFactory* > connbuilder_factories_;
 
+  DictionaryDatum thirdconnruledict_; //!< Dictionary for third-factor connection rules.
+
+  //! Third-factor ConnBuilder factories, indexed by thirdconnruledict_ elements.
+  std::vector< GenericThirdConnBuilderFactory* > thirdconnbuilder_factories_;
+
   long min_delay_; //!< Value of the smallest delay in the network.
 
   long max_delay_; //!< Value of the largest delay in the network in steps.