conn_builder.h

Go to the documentation of this file.

/*
 *  conn_builder.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 CONN_BUILDER_H
#define CONN_BUILDER_H
 
// C++ includes:
#include <map>
#include <set>
#include <stdexcept>
#include <vector>
 
// Includes from libnestutil
#include "block_vector.h"
 
// Includes from nestkernel:
#include "conn_parameter.h"
#include "nest_time.h"
#include "node_collection.h"
#include "parameter.h"
 
 
namespace nest
{
class Node;
class ConnParameter;
class SparseNodeArray;
class BipartiteConnBuilder;
class ThirdInBuilder;
class ThirdOutBuilder;
 
 
class BipartiteConnBuilder
{
public:
  virtual void connect();
 
  virtual void disconnect();
 
  BipartiteConnBuilder( NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    ThirdOutBuilder* third_out,
    const Dictionary& conn_spec,
    const std::vector< Dictionary >& syn_specs );
  virtual ~BipartiteConnBuilder();
 
  size_t
  get_synapse_model() const
  {
    if ( synapse_model_id_.size() > 1 )
    {
      throw KernelException( "Can only retrieve synapse model when one synapse per connection is used." );
    }
    assert( not synapse_model_id_.empty() );
    return synapse_model_id_[ 0 ];
  }
 
  bool
  get_default_delay() const
  {
    if ( synapse_model_id_.size() > 1 )
    {
      throw KernelException( "Can only retrieve default delay when one synapse per connection is used." );
    }
    assert( not default_delay_.empty() );
    return default_delay_[ 0 ];
  }
 
  void set_synaptic_element_names( const std::string& pre_name, const std::string& post_name );
 
  bool change_connected_synaptic_elements( size_t snode_id, size_t tnode_id, const size_t tid, int update );
 
  virtual bool
  supports_symmetric() const
  {
    return false;
  }
 
  virtual bool
  is_symmetric() const
  {
    return false;
  }
 
  bool
  allows_autapses() const
  {
    return allow_autapses_;
  }
 
  bool
  allows_multapses() const
  {
    return allow_multapses_;
  }
 
  virtual bool
  requires_proxies() const
  {
    return true;
  }
 
protected:
  virtual void connect_() = 0;
 
  bool all_parameters_scalar_() const;
 
  virtual void
  sp_connect_()
  {
    throw NotImplemented( "This connection rule is not implemented for structural plasticity." );
  }
 
  virtual void
  disconnect_()
  {
    throw NotImplemented( "This disconnection rule is not implemented." );
  }
 
  virtual void
  sp_disconnect_()
  {
    throw NotImplemented( "This connection rule is not implemented for structural plasticity." );
  }
 
  void update_param_dict_( size_t snode_id, Node& target, size_t target_thread, RngPtr rng, size_t indx );
 
  void single_connect_( size_t, Node&, size_t, RngPtr );
  void single_disconnect_( size_t, Node&, size_t );
 
  void skip_conn_parameter_( size_t, size_t n_skip = 1 );
 
  bool loop_over_targets_() const;
 
  NodeCollectionPTR sources_;  
  NodeCollectionPTR targets_;  
 
  ThirdOutBuilder* third_out_;  
 
  bool allow_autapses_;
  bool allow_multapses_;
  bool make_symmetric_;
  bool creates_symmetric_connections_;
 
  std::vector< std::exception_ptr > exceptions_raised_;
 
  // Name of the pre synaptic and postsynaptic elements for this connection builder
  std::string pre_synaptic_element_name_;
  std::string post_synaptic_element_name_;
 
  bool use_structural_plasticity_;
 
  std::vector< ConnParameter* > parameters_requiring_skipping_;
 
  std::vector< size_t > synapse_model_id_;
 
  std::vector< std::vector< Dictionary > > param_dicts_;
 
private:
  typedef std::map< std::string, ConnParameter* > ConnParameterMap;
 
  std::vector< bool > default_weight_and_delay_;
 
  std::vector< bool > default_weight_;
 
  std::vector< bool > default_delay_;
 
  // null-pointer indicates that default be used
  std::vector< ConnParameter* > weights_;
  std::vector< ConnParameter* > delays_;
 
  std::vector< ConnParameterMap > synapse_params_;
 
  std::set< std::string > skip_syn_params_;
 
  void register_parameters_requiring_skipping_( ConnParameter& param );
 
  void set_synapse_model_( const Dictionary& syn_params, const size_t indx );
  void set_default_weight_or_delay_( const Dictionary& syn_params, const size_t indx );
  void set_synapse_params( const Dictionary& syn_defaults, const Dictionary& syn_params, const size_t indx );
 
  void set_structural_plasticity_parameters( const std::vector< Dictionary >& syn_specs );
 
  void reset_weights_();
  void reset_delays_();
};
 
 
class ThirdInBuilder final : public BipartiteConnBuilder
{
public:
  ThirdInBuilder( NodeCollectionPTR sources,
    NodeCollectionPTR third,
    const Dictionary& third_conn_spec,
    const std::vector< Dictionary >& syn_specs );
  ~ThirdInBuilder();
 
  void register_connection( size_t primary_source_id, size_t third_node_id );
 
private:
  void connect_() override;
 
  struct SourceThirdInfo_
  {
    SourceThirdInfo_()
      : source_gid( 0 )
      , third_gid( 0 )
      , third_rank( 0 )
    {
    }
    SourceThirdInfo_( size_t src, size_t trd, size_t rank )
      : source_gid( src )
      , third_gid( trd )
      , third_rank( rank )
    {
    }
 
    size_t source_gid;  
    size_t third_gid;   
    size_t third_rank;  
  };
 
  std::vector< BlockVector< SourceThirdInfo_ >* > source_third_gids_;
 
  std::vector< std::vector< size_t >* > source_third_counts_;
};
 
 
class ThirdOutBuilder : public BipartiteConnBuilder
{
public:
  ThirdOutBuilder( const NodeCollectionPTR third,
    const NodeCollectionPTR targets,
    ThirdInBuilder* third_in,
    const Dictionary& third_conn_spec,
    const std::vector< Dictionary >& syn_specs );
 
  void
  connect() override final
  {
    assert( false );
  }
 
  virtual void third_connect( size_t source_gid, Node& target ) = 0;
 
protected:
  ThirdInBuilder* third_in_;
};
 
 
class ConnBuilder
{
public:
  ConnBuilder( const std::string& primary_rule,
    NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    const Dictionary& conn_spec,
    const std::vector< Dictionary >& syn_specs );
 
  ConnBuilder( const std::string& primary_rule,
    const std::string& third_rule,
    NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    NodeCollectionPTR third,
    const Dictionary& conn_spec,
    const Dictionary& third_conn_spec,
    const std::map< std::string, std::vector< Dictionary > >& syn_specs );
 
  ~ConnBuilder();
 
  void connect();
 
  void disconnect();
 
private:
  // Order of declarations based on dependencies, do not change.
  ThirdInBuilder* third_in_builder_;
  ThirdOutBuilder* third_out_builder_;
  BipartiteConnBuilder* primary_builder_;
};
 
class ThirdBernoulliWithPoolBuilder : public ThirdOutBuilder
{
public:
  ThirdBernoulliWithPoolBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdInBuilder*,
    const Dictionary&,
    const std::vector< Dictionary >& );
  ~ThirdBernoulliWithPoolBuilder();
 
  void third_connect( size_t source_gid, Node& target ) override;
 
private:
  void
  connect_() override
  {
    assert( false );
  }  
 
  size_t get_first_pool_index_( const size_t target_index ) const;
 
  double p_;                  
  bool random_pool_;          
  size_t pool_size_;          
  size_t targets_per_third_;  
 
  typedef std::vector< NodeIDTriple > PoolType_;
 
  typedef std::map< size_t, PoolType_ > TgtPoolMap_;
 
  std::vector< TgtPoolMap_* > pools_;  // outer: threads
};
 
 
class OneToOneBuilder : public BipartiteConnBuilder
{
public:
  OneToOneBuilder( NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    ThirdOutBuilder* third_out,
    const Dictionary& conn_spec,
    const std::vector< Dictionary >& syn_specs );
 
  bool
  supports_symmetric() const override
  {
    return true;
  }
 
  bool
  requires_proxies() const override
  {
    return false;
  }
 
protected:
  void connect_() override;
 
  void sp_connect_() override;
 
  void disconnect_() override;
 
  void sp_disconnect_() override;
};
 
class AllToAllBuilder : public BipartiteConnBuilder
{
public:
  AllToAllBuilder( NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    ThirdOutBuilder* third_out,
    const Dictionary& conn_spec,
    const std::vector< Dictionary >& syn_specs )
    : BipartiteConnBuilder( sources, targets, third_out, conn_spec, syn_specs )
  {
  }
 
  bool
  is_symmetric() const override
  {
    return sources_ == targets_ and all_parameters_scalar_();
  }
 
  bool
  requires_proxies() const override
  {
    return false;
  }
 
protected:
  void connect_() override;
 
  void sp_connect_() override;
 
  void disconnect_() override;
 
  void sp_disconnect_() override;
 
private:
  void inner_connect_( const int, RngPtr, Node*, size_t, bool );
};
 
 
class FixedInDegreeBuilder : public BipartiteConnBuilder
{
public:
  FixedInDegreeBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
protected:
  void connect_() override;
 
private:
  void inner_connect_( const int, RngPtr, Node*, size_t, bool, long );
  ParameterPTR indegree_;
};
 
class FixedOutDegreeBuilder : public BipartiteConnBuilder
{
public:
  FixedOutDegreeBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
protected:
  void connect_() override;
 
private:
  ParameterPTR outdegree_;
};
 
class FixedTotalNumberBuilder : public BipartiteConnBuilder
{
public:
  FixedTotalNumberBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
protected:
  void connect_() override;
 
private:
  long N_;
};
 
class BernoulliBuilder : public BipartiteConnBuilder
{
public:
  BernoulliBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
protected:
  void connect_() override;
 
private:
  void inner_connect_( const int, RngPtr, Node*, size_t );
  ParameterPTR p_;  
};
 
class PoissonBuilder : public BipartiteConnBuilder
{
public:
  PoissonBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
protected:
  void connect_() override;
 
private:
  void inner_connect_( const int, RngPtr, Node*, size_t );
  ParameterPTR pairwise_avg_num_conns_;  
};
 
class SymmetricBernoulliBuilder : public BipartiteConnBuilder
{
public:
  SymmetricBernoulliBuilder( NodeCollectionPTR,
    NodeCollectionPTR,
    ThirdOutBuilder* third_out,
    const Dictionary&,
    const std::vector< Dictionary >& );
 
  bool
  supports_symmetric() const override
  {
    return true;
  }
 
protected:
  void connect_() override;
 
private:
  double p_;  
};
 
class SPBuilder : public BipartiteConnBuilder
{
public:
  SPBuilder( NodeCollectionPTR sources,
    NodeCollectionPTR targets,
    ThirdOutBuilder* third_out,
    const Dictionary& conn_spec,
    const std::vector< Dictionary >& syn_spec );
 
  const std::string&
  get_pre_synaptic_element_name() const
  {
    return pre_synaptic_element_name_;
  }
 
  const std::string&
  get_post_synaptic_element_name() const
  {
    return post_synaptic_element_name_;
  }
 
  void
  set_name( const std::string& name )
  {
    name_ = name;
  }
 
  std::string
  get_name() const
  {
    return name_;
  }
 
  void update_delay( long& d ) const;
 
  void sp_connect( const std::vector< size_t >& sources, const std::vector< size_t >& targets );
 
protected:
  std::string name_;
 
  using BipartiteConnBuilder::connect_;
  void connect_() override;
  void connect_( NodeCollectionPTR sources, NodeCollectionPTR targets );
 
  void connect_( const std::vector< size_t >& sources, const std::vector< size_t >& targets );
};
 
inline void
BipartiteConnBuilder::register_parameters_requiring_skipping_( ConnParameter& param )
{
  if ( param.is_array() )
  {
    parameters_requiring_skipping_.push_back( &param );
  }
}
 
inline void
BipartiteConnBuilder::skip_conn_parameter_( size_t target_thread, size_t n_skip )
{
  for ( std::vector< ConnParameter* >::iterator it = parameters_requiring_skipping_.begin();
    it != parameters_requiring_skipping_.end();
    ++it )
  {
    ( *it )->skip( target_thread, n_skip );
  }
}
 
}  // namespace nest
 
#endif