stimulation_backend_mpi.h

Go to the documentation of this file.

/*
 *  stimulation_backend_mpi.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 STIMULATION_BACKEND_MPI_H
#define STIMULATION_BACKEND_MPI_H
 
#include "nest_time.h"
#include "nest_types.h"
#include "stimulation_backend.h"
#include <arpa/inet.h>
#include <mpi.h>
#include <netinet/in.h>
#include <set>
#include <sys/socket.h>
#include <unistd.h>
 
/* BeginUserDocs: stimulation backend
 
Short description
+++++++++++++++++
 
Stimulation backend `mpi` - Receive stimulation parameters via MPI
 
Description
+++++++++++
 
.. admonition:: Availability
 
   This stimulation backend is only available if NEST was compiled with
   :ref:`support for MPI <compile-with-mpi>`.
 
The `mpi` stimulation backend collects data from MPI channels and
updates stimulation devices just before each run. This is useful for
co-simulation or for receiving stimuli from external software.
 
There are two ways to set the MPI port. If both are set, option A has precedence
 
1. The address is supplied via the recording backends "mpi_address" status property.
 
2. The name of the MPI port to send data to is read from a file for each
   device configured to use this backend. The file needs to be named
   according to the following pattern:
 
::
 
   {data_path}/{data_prefix}{label}/{node_id}.txt
 
The ``data_path`` and ``data_prefix`` are global kernel properties,
while `label` is a property of the device in question and `node_id`
its node ID. This path can only be set outside of a ``Run`` context
(i.e.  after ``Prepare()`` has been called, but ``Cleanup()`` has
not).
 
Communication Protocol
++++++++++++++++++++++
 
The following protocol is used to exchange information between both
MPI processes. The protocol is described using the following format
for the MPI messages: (value, number, type, source/destination, tag)
 
1) ``Prepare``   : Connection of MPI port include in one file (see below)
2) ``Run`` begin : Send start run (true, 1, CXX_BOOL, 0, 0)
3) ``Run`` begin : Send the id of the device to update (node_id, 1, INT, 0, 0)
4) ``Run`` begin : Receive shape of the data (shape, 1, INT, 0, 0)
5) ``Run`` begin : Receive the data for updating the device (data, shape, DOUBLE, 0, 0)
6) ``Run`` end   : Send at each ending of the run (true, 1, CXX_BOOL, 0, 1)
7) ``Cleanup``   : Send at this en of the simulation (true, 1, CXX_BOOL, 0, 2)
 
Data format
+++++++++++
 
The format of the data depends on the exact type of stimulation
device.
 
EndUserDocs */
 
namespace nest
{
 
class StimulationBackendMPI : public StimulationBackend
{
public:
  StimulationBackendMPI();
 
  ~StimulationBackendMPI() noexcept override;
 
  void initialize() override;
 
  void finalize() override;
 
  void enroll( StimulationDevice& device, const Dictionary& params ) override;
 
  void disenroll( StimulationDevice& device ) override;
 
  void cleanup() override;
 
  void prepare() override;
 
  void pre_run_hook() override;
 
  void post_run_hook() override;
 
private:
  bool enrolled_;
  bool prepared_;
  using device_map = std::vector< std::map< size_t, std::pair< const MPI_Comm*, StimulationDevice* > > >;
  device_map devices_;
  typedef std::map< std::string, std::tuple< MPI_Comm*, std::vector< int >*, int* > > comm_map;
  comm_map commMap_;
 
  std::string mpi_address_;
  void get_port( StimulationDevice* device, std::string* port_name );
  void get_port( size_t index_node, const std::string& label, std::string* port_name );
 
  static std::pair< int*, double* > receive_spike_train( const MPI_Comm& comm, std::vector< int >& device_id );
  void update_device( int* array_index, std::vector< int >& devices_id, std::pair< int*, double* > data );
  void clean_memory_input_data( std::vector< std::pair< int*, double* > >& data );
};
 
}  // namespace
 
#endif /* #ifndef STIMULATION_BACKEND_MPI_H */