This research was supported by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).
This project/research has received funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3) and Specific Grant Agreement No. 785907 (Human Brain Project SGA2).

Insite provides a middleware that enables users to acquire data from neural simulators via the in-transit paradigm. In-transit approaches allow users to access data from a running simulation while the simulation is still going on. In the traditional approach data from simulations is written to disk first, and can only be accessed after the simulation has finished. However, this has two main constraints:

1. Data can only be further processed after the whole simulation has finished.
2. Disk speed can be a bottleneck when simulating, as data has to be written out.
3. Data must be completely stored on the machine, leading to large files.

Using Insite allows users to develop data consumer, such as visualizations and analysis tools that allow early insight into the data without storing data with virtually zero dependencies.

Insite was specifically designed to be ease-to-integrate and easy-to-use to allow a wide range of users to take advantage of in-transit approaches in the context of brain simulatiion. Insite uses off-the-shelf dataformats and protocols to make integration as easy as possible. Data can be queried via an HTTP REST API from Insite's access node, which represents a single point of contact for the user.

Insite consists of two main layers. The first part is the Insite access node, an HTTP server that serves as a centralized endpoints.

The access node aggregates data from multiple simulators (NEST, Arbor, TVB) and from multiple simulation instances, respectively. This means, that even distributed simulations, e.g. via MPI, can be access as if it is only one simulation instances. Data is aggregated at the access node and can then be filtered and accessed by the user. Thus, allowing convienent access to multi-node multiscale simulations.

This architecture enables users to easily create in-situ visualizations of neural simulations without the knowledge of the simulation's underlying architecture or any further knowledge about the computational distribution of the simulation. Users can query the HTTP endpoint for different datapoints, such as: spike data, multimeter data, the topology of the neural network and so on (see full API below). The returned data in encoded in JSON, thus allowing processing in a plethora of different languages and systems without Insite specific dependencies.

The access-node provides the full API to the Insite pipeline which is documented below.

The second part are Insite's simulator plugings. The simulator plugin is embedded into the respective simulations and is responsible for collecting simulation data and making it available to the access node. The simulators plugins are designed to be as non-invasive as possible to make integration into new and existing simulations easy. Simulator plugins are available for NEST, Arbor and The Virtual Brain.

Additional information can be found on the following poster:

1. Using Docker
2. Building From Source

To be able to use the Docker images please make sure that the docker engine and docker compose are installed.
(Or docker compatible containerization engines)

There are two different approaches for using Insite with docker:

1. Using Pre-built Images
2. Build Docker Images

Run the example

The docker-compose below provides an example with all three simulators. While in this case each simulator runs their own simulation, all data can be queried via the single access-node nonetheless. Just save the docker-compose as some-name.yaml and then start Insite with docker-compose -f some-name.yaml up. Docker will download all four containers and start the simulations. You can query the data from the examples from the access node via localhost:52056 via your favourite tool, e.g.: curl -L localhost:52056/version/ to retrieve the version.

version: "3"

services:
  insite-access-node:
    image:
      docker-registry.ebrains.eu/insite/access-node
    ports:
      - "52056:52056" # You can change the local part of the port here 
    environment:
      INSITE_NEST_BASE_URL: "insite-nest-example"
      INSITE_ARBOR_BASE_URL: "insite-arbor-example"

  insite-nest-example:
    image:
      docker-registry.ebrains.eu/insite/insite-nest-example
    depends_on:
      - insite-access-node

  insite-tvb-example: 
    image:
      docker-registry.ebrains.eu/insite/insite-tvb-example
    environment:
      INSITE_ACCESS_NODE_URL: "insite-access-node"
    depends_on:
      - insite-access-node

  insite-arbor-example: 
    image:
      docker-registry.ebrains.eu/insite/insite-arbor-example
    depends_on:
    - insite-access-node

Using Pre-built Images

We provide pre-built images for NEST, Arbor, TVB and the Insite access node. These images contain the respective simulator binaries and the Insite simulator module pre-installed:

You can use these images to deploy your own Insite-enabled simulations. For further information on how to that you can refer to our examples.

Build Docker Images

To build the docker containers yourself you can use the provided Dockerfile in the repository.

Dockerfiles are located in the docker with the following structure:

docker
├── Dockerfile_AccessNode
├── examples
│   ├── Dockerfile_ArborRingExample
│   ├── Dockerfile_NestExample
│   └── Dockerfile_TVBExample
└── simulators
    ├── Dockerfile_Arbor
    ├── Dockerfile_NEST
    └── Dockerfile_TVB

Dockerfile_AccessNode builds Insite's access node.
simulators/Dockerfile_* builds the respective simulators with Insite simulator modules integrated.
examples/Dockerfile_* builds the respective examples. They are based on the simulator docker images but add example simulations.

The Dockerfiles refer to relative locations starting at the repository root. Therefore, to build containers please build from the root and refer to the Dockerfiles, e.g.: docker build . -f docker/simulators/Dockerfile_Arbor

1. Clone this repository (git clone https://github.com/VRGroupRWTH/insite.git).

Building the Access Node

The access node is written in C++ and uses the CMake build system. Dependencies are downloaded via CPM during configuration.

cd access-node
mkdir build && cd build
cmake ..
make -j insite-access-node

Access node dependencies:

• https://github.com/jbeder/yaml-cpp
• https://github.com/libcpr/cpr
• https://github.com/zaphoyd/websocketpp
• https://github.com/gabime/spdlog
• https://github.com/google/flatbuffers
• https://github.com/marzer/tomlplusplus
• https://github.com/OlivierLDff/asio.cmake
• https://github.com/TartanLlama/optional
• https://github.com/Tencent/rapidjson
• https://github.com/CrowCpp/Crow

Building the Arbor Module

The arbor module is written in C++ and uses the CMake build system. Dependencies are downloaded via CPM during configuration.

cd arbor-module
mkdir build && cd build
cmake ..
make -j insite-arbor 
make install

Arbor module dependencies:

• https://github.com/arbor-sim/arbor
• https://github.com/gabime/spdlog
• https://github.com/marzer/tomlplusplus
• https://github.com/TartanLlama/optional
• https://github.com/Tencent/rapidjson
• https://github.com/CrowCpp/Crow

Building the NEST Module

The nest module is written in C++ and uses the CMake build system. Dependencies are downloaded via CPM during configuration. First build nest according to the the nest documentation, then build against nest.

cd nest-module
mkdir build && cd build
cmake .. -Dwith-nest=NEST_INSTALL_PATH/bin/nest-config
make -j install 

NEST module dependencies:

• https://github.com/nest/nest-simulator
• https://github.com/zaphoyd/websocketpp
• https://github.com/gabime/spdlog
• https://github.com/google/flatbuffers
• https://github.com/TartanLlama/optional
• https://github.com/Tencent/rapidjson
• https://github.com/CrowCpp/Crow

Building the TVB module

The TVB module is written in Python and involves no compilation process. Dependencies can be installed via pip:

cd tvb-module
pip install -r requirements.txt

Tvb module dependencies:

• https://github.com/ijl/orjson
• https://github.com/numpy/numpy

1. NEST Integration
2. Arbor Integration
3. TVB Integrations

The following sections assumes that the Insite nest module was successfully compiled and installed and is available. Either through using the NEST insite container described above or by manual compilation.
Insite can be integrated into NEST simulation via NEST's Python API. A NEST simulation can be in-transit enabled by adding Insite recording backends into the simulation after activating Insite with:

nest.Install("insitemodule")

Afterwards, a new spike recorder or multimeter can be created with:

# Create spike recorder
insite_spike_recorder = nest.Create("spike_recorder")

#Create multimeter
insite_multimeter = nest.Create("multimeter")

To enable recording to Insite the spikerecorder and multimeter have to be set to the correct recording backend with:

nest.SetStatus(YOUR_DEVICE, [{"record_to":"insite"}])

respectively.

The recording devices act as normal NEST nodes and can be connected to other nodes, e.g., neurons:

nest.Connect(nodes_ex, insite_spike_recorder, syn_spec="excitatory")

All neurons connected to Insite devices are available via the Insite pipeline.
Endpoints for spikerecorders and multimeters provide information about Insite-enabled nodes in the network while the spike and multimeter endpoints return data recorded by the devices.

The following sections assumes that the Insite nest module was successfully compiled and installed and is available. Either through using the Arbor insite container described above or by manual compilation.
Insite can be embedded into Arbor simulations via the Insite arbor C++ module. Therefore, arbor simulations using Insite must link against insite-arbor in their CMakeLists. E.g.:

target_link_libraries(YOUR_SIMULATION PUBLIC insite-arbor)

Afterwards, the simulation can be made Insite-enabled by embedding the Insite pipeline backend into your simulation file.
First include the pipeline backend:

#include <insite/arbor/pipeline_backend.h>

Next, add an Insite HTTP backend in your main code before running the simulation:

    insite::HttpBackend insite_backend(context, recipe, sim, arb::all_probes,
                                   arb::regular_schedule(1.0));

The signature is as follows:

HttpBackend(const arb::context& ctx,
          const arb::recipe& rcp,
          arb::simulation& sim,
          arb::cell_member_predicate cell_pred,
          arb::schedule sched);

The cell_member_predicate can be used to filter the probes that should be made available via Insite. In the example arb::all_probes enables all present probes to be accessed via Insite. The sched describes the sampling rate of the Insite-enabled probes.

The Backend provides information about the cells present in the simulation. Additionally, the spikes of all neurons are recorded by default. Available probes and their data can be queried via the API.

Please refer to the API documentation below for a complete overview.

The following sections assumes that the Insite TVB module is available. Either through using the Arbor insite container described above or by manual installation.

First import the Python TVB modules:

from insite_websocketmanager import InsiteWebSocketManager, InsiteOpcode
from insite_monitor_wrapper import InsiteMonitorWrapper

afterwards initialize the InsiteWebSocketManager:

insite_ws_manager = WebSocketManager(INSITE_ACCESS_NODE_URL,9011)

the access node url.

To record data to Insite regular monitors have to be wrapped via the InsiteMonitorWrapper:

mon_raw = monitors.Raw()
mon_spat = monitors.SpatialAverage()
insite_spatial = MonitorWrapper(mon_spat,insite_ws_manager)
insite_raw = MonitorWrapper(mon_raw,insite_ws_manager)

Monitors can be configured as usual before calling the MonitorWrapper. All wrapped monitors that are registered as monitors at the simulation will be will be available via Insite pipeline.

what_to_watch = [insite_raw, insite_spatial]
sim = simulator.Simulator(model = oscilator, connectivity = white_matter,
                      coupling = white_matter_coupling, 
                      integrator = heunint, monitors = what_to_watch)

Before starting the simulation connect() and the send_start_sim() function must be called. send_sim_info(sim) must be called before configure is called on the simulation. After the simulation send_end_sim() must be called. Finally, the connection can be close via the close() call.

The following code shows the complete boilerplate code for wrapping a TVB simulation:

insite_ws_manager = WebSocketManager(address,9011)

insite_ws_manager.connect()

mon_raw = monitors.Raw()
mon_spat = monitors.SpatialAverage()
insite_spatial = MonitorWrapper(mon_spat,insite_ws_manager)
insite_raw = MonitorWrapper(mon_raw,insite_ws_manager)

length = 500
what_to_watch = [insite_spatial]

[simulation settings...]


insite_ws_manager.send_start_sim()

sim = simulator.Simulator(model = oscilator, connectivity = white_matter,
                          coupling = white_matter_coupling, 
                          integrator = heunint, monitors = what_to_watch)

insite_ws_manager.send_sim_info(sim)
sim.configure()

for data in sim(simulation_length=length):
    pass

insite_ws_manager.send_end_sim()
insite_ws_manager.close()

The following settings can be configured on the access node:

Values can be provided by settings the corresponding environment variable or via TOML or YAML in a config.{toml,yaml} file via the same directory as the binary.
Toml example:

["nest"]
numberOfNodes = 2
baseUrl = "insite-nest-example"

["arbor"]
numberOfNodes = 1
baseUrl = "insite-arbor-example"

["accessNode"]
port = 52056
websocketPort = 9011

Yaml example:

nest:
  numberOfNodes: 2
  baseUrl: "insite-nest-example"
arbor:
  numberOfNodes: 1
  baseUrl: "insite-arbor-example"
accessNode:
  port: 52056
  websocketPort: 9011

Release 2.1 of Insite has support for the following simulators:

• NEST
• (new) Arbor
• (new) TVB and incorporates the following new components:
• C++ Arbor simulator module
• Python TVB simulator module
• TVB integration tests
• Arbor integration tests
• Docker support:
  • Arbor container with Insite example
  • TVB container with Insite example
  • docker-compose file incorporating all three simulators and Access Node enhanced components:
• C++ NEST simulator module
• C++ Access Node
• Docker support:
  • Access Node container
  • NEST container with Insite example
  • Access Node container as well as:
• Miscellaneous bug fixes
• Updated Documentation
• Integration into Ebrains CI/CD

Release 2.0 of Insite has support for the following simulators:

• NEST and incorporates the following enhancements:
• Complete rewrite of the Access Node into C++
  • General performance improvements
  • Parallalization of requests to simulation nodes
    

NOTE: 2.0 release scraped in benefit of merge with 2.1

Release 1.1 of Insite has support for the following simulators:

• NEST and incorporates the following enhancements:
• C++ NEST simulator module updated for NEST 3.2
• Major performance improvements for Python Access Node
• Improved API:
  • Adds fields to indicate that requests contain the last data point
  • Adds fields to indicate that simulation is running or has finished
• Compatibility to NEST Server
• Improved integration tests
• Miscellaneous bug fixes

Release 1.0 of Insite has support for the following simulators:

• NEST and incorporates the following components:
• C++ NEST simulator module
• Python Access Node
• Docker containers:
  • Access Node
  • NEST Simulator with Insite module installed