Monsteer  0.3.0
Interactive Supercomputing - Monitoring and Steering for NEST simulations
User Guide

Overview

The Monsteer project is a set of libraries and tools that helps users to visualize, analyse and steer their simulations. Currently, the target community are NEST users who write simulators using the PyNEST interface. These users generally want to visualize the neural activity and and possibly steer the simulation accordingly. The Monsteer library fills this gap, providing the necessary mechanisms to stream and steer the simulation results through user-friendly python modules.

Compilation

Minimum configuration to configure using cmake, compile and run Monsteer:

  • A Linux box,
  • GCC compiler 4.8+,
  • CMake 2.8+,
  • Boost 1.54,
  • MPI (OpenMPI, mvapich2, etc),
  • NEST simulator 2.4.2,
  • MUSIC 1.0.7,
  • Python 2.6,

Setup

After the Monsteer project is compiled and installed, an executable called music_proxy and the Python packages bbp and Monsteer will be present in the installation directory.

Before running music configurations, the environmental variables PATH and PYTHONPATH must be configured to point to the location of the music_proxy binary and the Python packages bbp and Monsteer respectively. To visualize spike activity, the RTNeuron application has to be be installed as well.

Sample scripts and configuration files for steering and streaming are provided in the share/monsteer/examples/nest directory from the installation tree.

Working in BBP Infrastructure

All the visualization tools, including Monsteer, are regularly made available on the 40 node visualization cluster in Lugano, at their latest version by the visualization team. Therefore, it is highly recommended for the users to work with this infrastructure.

After allocation of resources in this cluster, all tools become usable with the command line below:

1 bbpviz023~ % module load BBP/viz/latest

Music Configuration

In the share/monsteer/examples/nest directory there are files with the extension ".music" and there are NEST simulation scripts. MUSIC configuration describes how to launch multiple applications that will communicate using MUSIC, how many MPI processes a MUSIC application will use and what ports should be connected.

Below there is a sample music configuration:

1 # Usage:
2 # - With mpirun, form this directory do:
3 # $ mpirun -np 5 music nest2music_proxy_with_steering.music
4 # - With srun
5 # srun -n 5 music nest2music_proxy_with_steering.music
6 
7 stoptime=10000000
8 
9 [mars]
10  binary=./minimal_steered.py
11  np=4
12 
13 [venus]
14  # This binary is expected to be in the path
15  binary=music_proxy
16  args=--steering
17  np=1
18 
19 mars.spikes_out -> venus.spikesPort [1000]
20 venus.steeringPort -> mars.steering_input [0]

In this configuration:

Sections:

  • "stoptime" is the total simulation time given in seconds,
  • "binary" is an executable name,
  • "np" is the number of MPI processes,
  • "args" contains the command line arguments.

Options:

  • "mars" and "venus" are application definitions which will be executed using MUSIC environment,

Connection definitions:

  • "mars.spikes_out -> venus.spikesPort [1000]" constructs the "spike event" connection from the "mars" application to the "venus" application. "1000" is the number of channels this connection has. In the Monsteer case, there are 1000 neurons that reports their spike activity.
  • "venus.steeringPort -> mars.steering_input [0]" connects "messaging" ports. "0" means, there will be only one channel to communicate. This parameter is used for setting up the messaging ports.

Please refer to the MUSIC documentation for more detailed documentation.

NEST script

The NEST script is responsible for running the neural simulation. For the NEST simulator to communicate to "music_proxy" application, the spike events and steering MUSIC ports should be connected. The script below setups the MUSIC communication ports and runs the simulation.

1 duration = 100000
2 cell_count = 1000
3 
4 import nest
5 
6 neurons = Create("iaf_neuron", cell_count)
7 
8 # Setups music spike output.
9 music_spike_output = Create('music_event_out_proxy', 1)
10 SetStatus(music_spike_output, {'port_name': 'spikes_out'})
11 
12 # Connecting neurons to music event channels.
13 for i in range(0, len(neurons)):
14  Connect([neurons[i]], music_spike_output, 'one_to_one',
15  {'music_channel': i+1})
16 
17 # Setup music steering input.
18 music_steering_input = _nest.Create('music_message_in_proxy', 1)
19 SetStatus(music_steering_input,
20  {'port_name': 'steering_input',
21  "acceptable_latency": 40.0})
22 
23 time = 0
24 while time < duration:
25  Simulate(10)
26  time += 10

The above code lacks parsing the steering messages. Monsteer adds the Nesteer: A Python interface for processing the steering messages python module, to simplify the process of steering.

Nesteer: A Python interface for processing the steering messages

The Nesteer python class helps users to setup MUSIC communication and map BBP circuits to NEST simulations. The example below simplifies the previous NEST script by adding the Nesteer steering message parser.

1 duration = 100000 #In miliseconds.
2 cell_count = 1000
3 
4 from monsteer.Nesteer import Nesteer
5 from nest import *
6 
7 neurons = Create("iaf_neuron", cell_count)
8 
9 monsteer_communicator = Nesteer('spikes_out',
10  'steering_input',
11  neurons,
12  [i + 1 for i in range(cell_count)])
13 
14 def apply_spikes(generator, neurons):
15  Connect(generator, neurons, 'all_to_all', syn_spec={'weight': 40.0})
16 monsteer_communicator.set_apply_generators_to_neurons_function(apply_spikes)
17 
18 time = 0
19 while time < duration:
20  Simulate(10)
21  monsteer_communicator.process_events()
22  time += 10

The parameters of the Nesteer class:

  • 'spikes_out' is MUSIC spike event port name,
  • 'steering_input' is MUSIC messaging port name for steering,
  • 'neurons' is the Nesteer neurons.
  • '[i + 1 for i in range(cell_count)]' is which neurons corresponds to which channel in event port. Here in this example event ports are connected for each of the 1000 neurons. And, they are each of them is mapped to each event channel from 1 to 1000. This corresponds to the MUSIC configuration event channel count.

In case of BBP circuit, it is the mapping of NEST neuron ids too BBP neuron ids, because the NEST and BBP has different ids for cells. For to take BBP circuit into account, the event channels in MUSIC configuration should be set to maximum neuron id.

Working with the Simulation

After having the configuration and script files, the simulation can be executed using either mpirun or srun depending on the MPI environment setup. If there is the MUSIC configuration file named "config.music", and the total number of processes configured in this file is "5", then either it is run with mpirun or srun as below.

1 srun -n 5 music config.music

or

1 mpirun -np 5 music config.music.

This will trigger running of the simulation and sharing information with the "music_proxy" application.

Steering

To send steering commands to the simulation, there is a python NEST helper object. Through this object, injecting different spike generators to neurons, playing and pausing the simulation is possible. In the below example, injecting stimuli to multiple neurons and then pausing the simulation example can be seen.

1 import monsteer.Nesteer
2 import bbp
3 import nest
4 import numpy
5 import time
6 
7 # Creating the steering connection
8 simulator = monsteer.Nesteer.Simulator('monsteer_nesteer://')
9 
10 # Get parameter dictionary for a spike generator
11 params = nest.GetDefaults('poisson_generator')
12 
13 # Modify rate
14 params['rate'] = 50000.0
15 
16 # Define which cells will be effected by the spike generator
17 cells = bbp.Cell_Target()
18 for i in range(1000):
19  cells.insert(i + 1)
20 
21 time.sleep(4) # Waiting for connection
22 
23 # Inject stimulus to the simulator
24 simulator.injectStimulus(params, cells)
25 time.sleep(4) # Waiting for connection
26 
27 # Pause the simulator
28 simulator.pause()

Spike Visualization

To visualize the spikes of a BBP circuit, the RTNeuron circuit visualization tool can be employed. It has the features to connect to a running simulation and visualize spike events in the circuit.

In below example, a BlueBrain circuit is utilized. The configuration file for the circuit can be accessed from the lugano cluster, from path "/gpfs/bbp.cscs.ch/apps/viz/bbp/dev/BBPTestData/master/BBPTestData/Build/include/BlueConfig".

In this circuit there are 1000 neurons. The sample simulation scripts in the source code repository in Monsteer can be employed to run simulations on them.

After running the simulation with MUSIC configuration, a user can launch RTNeuron with below command line ( the –gui parameter activates the gui and connection to a simulator can be run using the "OpenSimulation" button in the gui ):

1 rtneuron-app.py -b "BLUE CONFIG FILE" --target Column soma --neurons 1 1000 soma --shell --gui [ -s monsteer:// ]

If the GUI is enabled, clicking on the "OpenSimulation" button brings a dialog for entering the url for the music proxy spike port. If there is only one simulation running, simply "monsteer://" can be entered, else "monsteer://host:port" should be entered for the right host and port which provides the spikes. If GUI is not enabled, "-s monsteer://" parameter can be added to the RTNeuron execution command line.

Once the connection is established through GUI, spike events should be visible on the screen. Interacting with GUI item "spike tail" slider, changes how long a spike is visible and "simulation delta" changes the the speed of simulation.

If connection is established through command line parameter, soma additional commands should be executed in python shell to start visualizing the spikes, changing spike tails and changing the simulation delta. Those can be seen below:

1 app.player.play()
2 app.player.simulationDelta = 0.1
3 view.attributes.spike_tail = 0.01