network.h

Go to the documentation of this file.

/*
 *  network.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 NETWORK_H
#define NETWORK_H
#include "config.h"
#include <vector>
#include <string>
#include <typeinfo>
#include "nest.h"
#include "model.h"
#include "scheduler.h"
#include "exceptions.h"
#include "proxynode.h"
#include "connection_manager.h"
#include "event.h"
#include "modelrangemanager.h"
#include "compose.hpp"
#include "dictdatum.h"
#include <ostream>
#include <cmath>

#include "dirent.h"
#include "errno.h"

#include "sparse_node_array.h"

#ifdef M_ERROR
#undef M_ERROR
#endif

#ifdef _OPENMP
#include <omp.h>
#endif

#ifdef HAVE_MUSIC
#include "music_event_handler.h"
#endif

class TokenArray;
class SLIInterpreter;

namespace nest
{
  class Subnet;
  class SiblingContainer;
  class Event;
  class Node;
  class GenericConnBuilderFactory;
  class GIDCollection;

/* BeginDocumentation
Name: kernel - Global properties of the simulation kernel.

Description:
(start here.)

Parameters:
  The following parameters can be set in the status dictionary.

  communicate_allgather    booltype    - Whether to use MPI_Allgather for communication (otherwise use CPEX)
  data_path                stringtype  - A path, where all data is written to (default is the current directory)
  data_prefix              stringtype  - A common prefix for all data files
  dict_miss_is_error       booltype    - Whether missed dictionary entries are treated as errors
  local_num_threads        integertype - The local number of threads (cf. global_num_virt_procs)
  max_delay                doubletype  - The maximum delay in the network
  min_delay                doubletype  - The minimum delay in the network
  ms_per_tic               doubletype  - The number of miliseconds per tic (cf. tics_per_ms, tics_per_step)
  network_size             integertype - The number of nodes in the network
  num_connections          integertype - The number of connections in the network
  num_processes            integertype - The number of MPI processes
  num_rec_processes        integertype - The number of MPI processes reserved for recording spikes
  num_sim_processes        integertype - The number of MPI processes reserved for simulating neurons
  off_grid_spiking         booltype    - Whether to transmit precise spike times in MPI communicatio
  overwrite_files          booltype    - Whether to overwrite existing data files
  print_time               booltype    - Whether to print progress information during the simulation
  resolution               doubletype  - The resolution of the simulation (in ms)
  rng_buffsize             integertype - The buffer size of the random number generators
  tics_per_ms              doubletype  - The number of tics per milisecond (cf. ms_per_tic, tics_per_step)
  tics_per_step            integertype - The number of tics per simulation time step (cf. ms_per_tic, tics_per_ms)
  time                     doubletype  - The current simulation time
  total_num_virtual_procs  integertype - The total number of virtual processes (cf. local_num_threads)
  to_do                    integertype - The number of steps yet to be simulated
  T_max                    doubletype  - The largest representable time value
  T_min                    doubletype  - The smallest representable time value
SeeAlso: Simulate, Node
*/
  
  class Network
  {
    friend class Scheduler;

  public:

    Network(SLIInterpreter&);
    ~Network();

    void reset();

    void reset_kernel();    
    
    void reset_network();
    
    void register_basis_model(Model& m, bool private_model = false);

    index register_model(Model& m, bool private_model = false);

    void unregister_model(index m_id);

    void try_unregister_model(index m_id);

    index copy_model(index old_id, std::string new_name);

    synindex register_synapse_prototype(ConnectorModel * cf);

    int copy_synapse_prototype(index sc, std::string);

    template <typename ConnBuilder>
    void register_conn_builder(const std::string& name);

    int get_model_id(const char []) const;

    Model * get_model(index) const;

    Model * get_model_of_gid(index);

    index get_model_id_of_gid(index);

    const modelrange& get_contiguous_gid_range(index gid) const;

    index add_node(index m, long_t n = 1);

    void restore_nodes(ArrayDatum &);

    void init_state(index);

    index size() const;

    void connect(index s, Node* target, thread target_thread,
         index syn, double_t d=NAN, double_t w=NAN); 

    void connect(index s, Node* target, thread target_thread,
         index syn, DictionaryDatum& params, double_t d=NAN, double_t w=NAN);   

    bool connect(index s, index r, DictionaryDatum& params, index syn);

    void subnet_connect(Subnet &, Subnet &, int, index syn);

    void connect(ArrayDatum& connectome);

    void divergent_connect(index s, const TokenArray r, const TokenArray weights, const TokenArray delays, index syn);
    void divergent_connect(index s,  DictionaryDatum d, index syn);
    
    void random_divergent_connect(index s, const TokenArray r, index n, const TokenArray w, const TokenArray d, bool, bool, index syn);
    
    void convergent_connect(const TokenArray s, index r, const TokenArray weights, const TokenArray delays, index syn);

    void convergent_connect(const std::vector<index> &s_id, index r, const TokenArray &weight, const TokenArray &delays, index syn);

    void random_convergent_connect(const TokenArray s, index t, index n, const TokenArray w, const TokenArray d, bool, bool, index syn);

    void random_convergent_connect(TokenArray s, TokenArray t, TokenArray n, TokenArray w, TokenArray d, bool, bool, index syn);

    void connect(const GIDCollection&, const GIDCollection&,
             const DictionaryDatum&, const DictionaryDatum&);

    DictionaryDatum get_connector_defaults(index sc);
    void set_connector_defaults(index sc, DictionaryDatum& d);

    DictionaryDatum get_synapse_status(index gid, index syn, port p, thread tid);
    void set_synapse_status(index gid, index syn, port p, thread tid, DictionaryDatum& d);

    ArrayDatum get_connections(DictionaryDatum dict);

    Subnet * get_root() const;        
    Subnet * get_cwn() const;         

    void go_to(index);

    void simulate(Time const &);
    void resume();

    void terminate();

    bool quit_by_error() const;
    
    int get_exitcode() const;

    void memory_info();

    void print(index, int);

    void trigger_update_weight(const long_t vt_gid, const vector<spikecounter>& dopa_spikes, const double_t t_trig);

    template <class EventT>
    void send(Node& source, EventT& e, const long_t lag = 0);
    
    void send_local(thread t, Node& source, Event& e);

    void send_to_node(Event& e);

    delay get_min_delay() const;

    delay get_max_delay() const;
 
    Time const& get_slice_origin() const;

    Time get_previous_slice_origin() const;

    Time const get_time() const;

    librandom::RngPtr get_rng(thread thrd = 0) const;

    librandom::RngPtr get_grng() const;

    thread get_num_threads() const;

    thread suggest_vp(index) const;
    
    thread suggest_rec_vp(index) const;

    thread vp_to_thread(thread vp) const;

    thread thread_to_vp(thread t) const;

    thread get_num_processes() const;

    thread get_num_rec_processes() const;

    thread get_num_sim_processes() const;

    void set_num_rec_processes(int nrp);

    bool is_local_node(Node*) const;

    bool is_local_gid(index gid) const;

    bool is_local_vp(thread) const;

    bool get_simulated() const;
    
    Node*  get_node(index, thread thr = 0);

    const SiblingContainer* get_thread_siblings(index n) const;

    bool model_in_use(index i);

    const std::string& get_data_prefix() const;

    const std::string& get_data_path() const;
    
    bool overwrite_files() const;
    
    bool get_off_grid_communication() const;

    void set_status(index, const DictionaryDatum&);

    DictionaryDatum get_status(index);

    int execute_sli_protected(DictionaryDatum, Name);

    const Dictionary &get_modeldict();
    
    const Dictionary &get_synapsedict() const;
    
    void calibrate_clock();
    
    size_t write_toggle() const;

    size_t read_toggle() const;  

    bool has_user_models() const;

    void ensure_valid_thread_local_ids() { scheduler_.ensure_valid_thread_local_ids(); }

    void message(int level, const char from[], const char text[]);
    void message(int level, const std::string& loc, const std::string& msg);

    bool dict_miss_is_error() const;

#ifdef HAVE_MUSIC
  public:  
    void register_music_in_port(std::string portname);

    void unregister_music_in_port(std::string portname);

    void register_music_event_in_proxy(std::string portname, int channel, nest::Node *mp);

    void set_music_in_port_acceptable_latency(std::string portname, double_t latency);
    void set_music_in_port_max_buffered(std::string portname, int_t maxbuffered);
    struct MusicPortData {
      MusicPortData (size_t n, double_t latency, int_t m)
      : n_input_proxies (n), acceptable_latency (latency), max_buffered (m)
      { }
      MusicPortData () { }
      size_t   n_input_proxies;    // Counter for number of music_input proxies
                                   // connected to this port
      double_t acceptable_latency;
      int_t    max_buffered;
    };

    std::map< std::string, MusicPortData > music_in_portlist_;
    
    std::map< std::string, MusicEventHandler > music_in_portmap_;

    void publish_music_in_ports_();

    void update_music_event_handlers_(Time const &, const long_t, const long_t);
#endif
 
    int get_thread_id() const;

    void set_model_defaults_modified() { model_defaults_modified_= true; }
    bool model_defaults_modified() const { return model_defaults_modified_; }
    
    Node *thread_lid_to_node(thread t, targetindex thread_local_id) const;

  private:
    void init_();
    void destruct_nodes_();
    void clear_models_(bool called_from_destructor=false);
        
    void set_status_single_node_(Node&, const DictionaryDatum&, bool clear_flags = true);  

    void set_data_path_prefix_(const DictionaryDatum& d);

    SLIInterpreter &interpreter_;
    SparseNodeArray local_nodes_;  
    Scheduler scheduler_;
    ConnectionManager connection_manager_;
    
    Subnet *root_;               
    Subnet *current_;            

    /* BeginDocumentation
       Name: synapsedict - Dictionary containing all synapse models.
       Description:
       'synapsedict info' shows the contents of the dictionary
       FirstVersion: October 2005
       Author: Jochen Martin Eppler
       SeeAlso: info
    */
    Dictionary* synapsedict_;      

    /* BeginDocumentation
       Name: modeldict - dictionary containing all devices and models of NEST
       Description:
       'modeldict info' shows the contents of the dictionary
       SeeAlso: info, Device, RecordingDevice, iaf_neuron, subnet
    */
    Dictionary* modeldict_;        

    /* BeginDocumentation
       Name: connruledict - dictionary containing all connectivity rules
       Description:
       This dictionary provides the connection rules that can be used
       in Connect.
       'connruledict info' shows the contents of the dictionary.
       SeeAlso: Connect
    */
    Dictionary* connruledict_;    

    Model* siblingcontainer_model; 
    
    std::string data_path_;        
    std::string data_prefix_;      
    bool        overwrite_files_;  

    std::vector< std::pair<Model *, bool> > pristine_models_;

    std::vector<Model *> models_;                    
    std::vector< std::vector<Node*> > proxy_nodes_;  
    std::vector<Node*> dummy_spike_sources_;         

    std::vector<GenericConnBuilderFactory*> connbuilder_factories_;  

    Modelrangemanager node_model_ids_;   
    
    bool dict_miss_is_error_;  

    bool model_defaults_modified_; 
  };

  inline 
  void Network::terminate()
  {
    scheduler_.terminate();
  }

  inline
  bool Network::quit_by_error() const
  {    
    Token t = interpreter_.baselookup(Name("systemdict"));
    DictionaryDatum systemdict = getValue<DictionaryDatum>(t);
    t = systemdict->lookup(Name("errordict"));
    DictionaryDatum errordict = getValue<DictionaryDatum>(t);
    return getValue<bool>(errordict, "quitbyerror");
  }

  inline
  int Network::get_exitcode() const
  {
    Token t = interpreter_.baselookup(Name("statusdict"));
    DictionaryDatum statusdict = getValue<DictionaryDatum>(t);
    return getValue<long>(statusdict, "exitcode");
  }

  inline
  index Network::size() const
  {
    return local_nodes_.get_max_gid() + 1;
  }

  inline
  Node *Network::thread_lid_to_node(thread t, targetindex thread_local_id) const
  { 
    return scheduler_.thread_lid_to_node(t, thread_local_id);
  }

  inline
  void Network::connect(ArrayDatum &connectome)
  {
    connection_manager_.connect(connectome);
  }

  inline
  DictionaryDatum Network::get_synapse_status(index gid, index syn, port p, thread tid)
  {
    return connection_manager_.get_synapse_status(gid, syn, p, tid);
  }

  inline
  void Network::set_synapse_status(index gid, index syn, port p, thread tid, DictionaryDatum& d)
  {
    connection_manager_.set_synapse_status(gid, syn, p, tid, d);
  }

  inline
  ArrayDatum Network::get_connections(DictionaryDatum params)
  {
    return connection_manager_.get_connections(params);
  }
  
  inline
  void Network::set_connector_defaults(index sc, DictionaryDatum& d)
  {
    connection_manager_.set_prototype_status(sc, d);
  }

  inline
  DictionaryDatum Network::get_connector_defaults(index sc)
  {
    return connection_manager_.get_prototype_status(sc);
  }
  
  inline
  synindex Network::register_synapse_prototype(ConnectorModel * cm)
  {
    return connection_manager_.register_synapse_prototype(cm);
  }
  
  inline
  int Network::copy_synapse_prototype(index sc, std::string name)
  {
    return connection_manager_.copy_synapse_prototype(sc, name);
  }
  
  inline
  Time const & Network::get_slice_origin() const
  {
    return scheduler_.get_slice_origin();
  }

  inline
  Time Network::get_previous_slice_origin() const
  {
    return scheduler_.get_previous_slice_origin();
  }

  inline
  Time const Network::get_time() const
  {
    return scheduler_.get_time();
  }

  inline
  Subnet * Network::get_root() const
  {
    return root_;
  }

  inline
  Subnet* Network::get_cwn(void) const
  {
    return current_;
  }

  inline
  thread Network::get_num_threads() const
  {
    return scheduler_.get_num_threads();
  }

  inline
  thread Network::get_num_processes() const
  {
    return scheduler_.get_num_processes();
  }
  
  inline
  thread Network::get_num_rec_processes() const
  {
    return scheduler_.get_num_rec_processes();
  }

  inline
  thread Network::get_num_sim_processes() const
  {
    return scheduler_.get_num_sim_processes();
  }

  inline
  void Network::set_num_rec_processes(int nrp) 
  {
    scheduler_.set_num_rec_processes(nrp);
  }

  inline
  bool Network::is_local_node(Node* n) const
  {
    return !(n->is_proxy());
  }

  inline
  bool Network::is_local_gid(index gid) const
  {
    return local_nodes_.get_node_by_gid(gid) != 0;
  }

  inline
  bool Network::is_local_vp(thread t) const
  {
    return scheduler_.is_local_vp(t);
  }

  inline
  int Network::suggest_vp(index gid) const
  {
    return scheduler_.suggest_vp(gid);
  }
  
  inline
  int Network::suggest_rec_vp(index gid) const
  {
    return scheduler_.suggest_rec_vp(gid);
  }

  inline
  thread Network::vp_to_thread(thread vp) const
  {
    return scheduler_.vp_to_thread(vp);
  }

  inline
  thread Network::thread_to_vp(thread t) const
  {
    return scheduler_.thread_to_vp(t);
  }

  inline
  bool Network::get_simulated() const
  {
    return scheduler_.get_simulated();
  }

  inline
  delay Network::get_min_delay() const
  {
    return scheduler_.get_min_delay();
  }

  inline
  delay Network::get_max_delay() const
  {
    return scheduler_.get_max_delay();
  }

  inline
  void Network::trigger_update_weight(const long_t vt_gid, const vector<spikecounter>& dopa_spikes, const double_t t_trig)
  {
    connection_manager_.trigger_update_weight(vt_gid, dopa_spikes, t_trig);
  }

  template <class EventT>
  inline
  void Network::send(Node& source, EventT& e, const long_t lag)
  {
    e.set_stamp(get_slice_origin() + Time::step(lag + 1));
    e.set_sender(source);
    thread t = source.get_thread();
    index gid = source.get_gid();

    assert(!source.has_proxies());
    connection_manager_.send(t, gid, e);
  }

  template <>
  inline
  void Network::send<SpikeEvent>(Node& source, SpikeEvent& e, const long_t lag)
  {
    e.set_stamp(get_slice_origin() + Time::step(lag + 1));
    e.set_sender(source);
    thread t = source.get_thread();

    if (source.has_proxies())
    {
      if ( source.is_off_grid() )
        scheduler_.send_offgrid_remote(t, e, lag);
      else
        scheduler_.send_remote(t, e, lag);
    }
    else
      send_local(t, source, e);
  }

  template <>
  inline
  void Network::send<DSSpikeEvent>(Node& source, DSSpikeEvent& e, const long_t lag)
  {
    e.set_stamp(get_slice_origin() + Time::step(lag + 1));
    e.set_sender(source);
    thread t = source.get_thread();

    assert(!source.has_proxies());
    send_local(t, source, e);
  } 

  inline
  void Network::send_local(thread t, Node& source, Event& e)
  {
    index sgid = source.get_gid();
    e.set_sender_gid(sgid);
    connection_manager_.send(t, sgid, e);
  }

  inline
  void Network::send_to_node(Event& e)
  {
    e();
  }

  inline
  void Network::calibrate_clock() 
  {
    scheduler_.calibrate_clock();
  }

  inline
  size_t Network::write_toggle() const
  {
    return scheduler_.get_slice() % 2;
  } 

  inline
  size_t Network::read_toggle() const
  {
    // define in terms of write_toggle() to ensure consistency
    return 1 - write_toggle();
  } 

  inline
  librandom::RngPtr Network::get_rng(thread t) const
  {
    return scheduler_.get_rng(t);
  }

  inline
  librandom::RngPtr Network::get_grng() const
  {
    return scheduler_.get_grng();
  }

  inline
  Model* Network::get_model(index m) const
  {
    if (m >= models_.size() || models_[m] == 0)
      throw UnknownModelID(m);

    return models_[m];
  }

  inline 
  Model* Network::get_model_of_gid(index gid)
  {
     return models_[get_model_id_of_gid(gid)];
  }

  inline
  index Network::get_model_id_of_gid(index gid)
  {
    if (not node_model_ids_.is_in_range(gid))
      throw UnknownNode(gid);

    return node_model_ids_.get_model_id(gid);
  }

  inline 
  const modelrange& Network::get_contiguous_gid_range(index gid) const
  {
    return node_model_ids_.get_range(gid);
  }

  inline
  const std::string& Network::get_data_path() const
  {
    return data_path_;
  }

  inline
  const std::string& Network::get_data_prefix() const
  {
    return data_prefix_;
  }

  inline
  bool Network::overwrite_files() const
  {
    return overwrite_files_;
  }

  inline
  bool Network::get_off_grid_communication() const
  {
    return scheduler_.get_off_grid_communication();
  }
  
  inline
  const Dictionary& Network::get_modeldict()
  {
    assert(modeldict_ != 0);
    return *modeldict_;
  }
  
  inline
  const Dictionary& Network::get_synapsedict() const
  {
    assert(synapsedict_ != 0);
    return *synapsedict_;
  }

  inline
  bool Network::has_user_models() const
  {
    return models_.size() > pristine_models_.size();
  }

  inline
  bool Network::dict_miss_is_error() const
  {
    return dict_miss_is_error_;
  }

  typedef lockPTR<Network> NetPtr;

  class ModelComp : public std::binary_function<int, int, bool>
  {
    const std::vector<Model*> &models;

    public:
      ModelComp(const vector<Model*> &nmodels) : models(nmodels) {}
      bool operator()(int a, int b)
      {
        return models[a]->get_name() < models[b]->get_name();
      }
  };

  inline
  int Network::get_thread_id() const
  {
#ifdef _OPENMP
    return omp_get_thread_num();
#else
    return 0;
#endif
  }

} // namespace

#endif