thevirtualbrain/fast_tvb repository overview

⁠The fast & parallel Virtual Brain

⁠A fast implementation of The Virtual Brain brain network simulator written in C using a host of optimizations that make brain simulation reeeallllyy fast.

⁠Features

• parallelized (multithreading)
• containerized (can be conveniently run e.g. through Docker, Shifter or Singularity, without the need to install dependencies or set up environment)
• uses the Deco-Wang (aka "ReducedWongWang") neural mass model to simulate local brain region activity as described in Deco et al., 2014, Journal of Neuroscience or Schirner et al., 2018, eLife

⁠Support

[email protected]⁠ [email protected]⁠

⁠Run your brain model

After you pulled the container with docker pull thevirtualbrain/fast_tvb

The image can be run in a container with

docker run --mount=type=bind,source=/path/to/output,target=/output --mount=type=bind,source=/path/to/input,target=/input thevirtualbrain/fast_tvb /start_simulation.sh <parameter_file> <sub_id> <num_threads>

<parameter_file> specifies the filename of the file that contains parameters, which must be located in the input folder.

<sub_id> specifies the identifier of the subject, please see below for further naming/data conventions of input files.

⁠HOWTO: Preparing your brain model

Brain model data consists of a structural connectome (weights and distance files) and a parameter set (parameter file). Unlike the Python TVB version where brain model input data (i.e. the structural connectome) is stored as a Zip or hdf5 file, for this implementation a brain model simply consists of two ASCII text files and, additionally, one ASCII text files that contains the simulation parameters.

All three files must be stored in a folder with the name input. Additionally, we need a folder where outputs are stored called output.

Naming conventions of weights and distance matrix files

Connectome files must have the suffixes "_SC_weights.txt" or "_SC_distances.txt"

connection weights file: <sub_id>_SC_weights.txt

connection distances file: <sub_id>_SC_distances.txt

The subject identifier <sub_id> can be any arbitrary short (alphanumeric) string, e.g. "sub002", and must be provided as a parameter to the batch file (which allows to have multiple different brain models stored in the same folder).

Example:

sub002_SC_weights.txt

and

sub002_SC_distances.txt

Formatting conventions of weights and distance matrix files

ASCII text files that contain the connection weight and distance matrices as floating point numbers separated by white-spaces (columns) and line breaks/newline characters (rows). The unit of distances is mm while connection weights are dimensionless and depend on the global coupling scaling factor parameter that is set in the parameter file.

Example (weights file):

0 0.012 0.0 0.119 0.0 1.1234 ...
0.012 0 0 0.0 1.34 ...
...
...

Naming conventions of parameter file

Arbitrary short string with the suffix ".txt". Must be provided as a parameter to the batch file (which allows to have multiple different parameter sets stored in the same folder). The file must have the suffix ".txt" (actually, the TVB container is able to work with arbitrary parameter file names, but HBP Collab Storage prevents upload of files without suffix).

Example:

param_set_042.txt

Formatting conventions of parameter file

ASCII text file that contains the parameters as floating point or integer numbers separated by white spaces.

The sorting of the parameter file is:

nodes, G, J_NMDA, w_plus, Ji, sigma, time_steps, BOLD_TR, global_trans_v, rand_num_seed

Important: Correct formatting of floating point vs. integer numbers is mandatory. Integer parameters (like "number of nodes") must not be formatted as floating point numbers (don't format the integer "2" with a radix point like this "2.0")! For correct number format please refer to the table below.

Example:

379 1.000 0.150 1.400 1.000 0.0100 10000 720 12.5000 1403

Parameter description

For a detailed description of parameters see Deco et al. (2014) JNeuro or Schirner et al. (2018) eLife