amnsbr/cubnm repository overview

cuBNM toolbox simulates neuronal activity of network nodes (neural mass models) which are connected through the structural connectome using GPUs/CPUs. Currently three models (rWW, rWWEx and Kuramoto) are implemented, but the modular design of the code makes it possible to include additional models in future. The simulated activity of model neurons is fed into the Balloon-Windkessel model to calculate simulated BOLD signal. Functional connectivity (FC) and functional connectivity dynamics (FCD) from the simulated BOLD signal are calculated efficiently on GPUs/CPUs and compared to FC and FCD matrices derived from empirical BOLD signals to assess similarity (goodness-of-fit) of the simulated to empirical BOLD signal.

The toolbox supports parameter optimization algorithms including grid search and evolutionary optimizers (via pymoo), such as the covariance matrix adaptation-evolution strategy (CMA-ES). Parallelization within the grid or the iterations of evolutionary optimization is done at the level of simulations (across the GPU ‘blocks’), and nodes (across each block’s ‘threads’). The models can incorporate global or regional free parameters that are fit to empirical data using the provided optimization algorithms. Regional parameters can be homogeneous or vary across nodes based on a parameterized combination of fixed maps or independent free parameters for each node or group of nodes.

GPU usage is the primary focus of the toolbox but it also supports running the simulations on single or multiple cores of CPU. CPUs will be used if no GPUs are detected or if requested by the user.

Please find the documentations on installation, usage examples and API at https://cubnm.readthedocs.io⁠.

Docker images are available for the development and stable versions (except v0.0.1).

• Stable (amnsbr/cubnm:v*): These are more lightweight and smaller in size. The output simulations given the same input data and random seed should be reproducible across platforms.
• Development (amnsbr/cubnm:dev): This includes latest changes of the code but is not updated after each commit. The output of identical simulations with the same random seed may be different across platforms, and therefore, tests of expected simulations may fail.

Pull the container via docker pull amnsbr/cubnm:<version> or singularity build /path/to/cubnm-<version>.sif docker://amnsbr/cubnm:<version>.

The containers can be used in two modes:

• Interactively: docker run -it --entrypoint /bin/bash amnsbr/cubnm:<version> or singularity shell /path/to/cubnm-<version>.sif. cubnm is installed and can be imported in python3.10 (stable versions) or /opt/miniconda/bin/python (development version).
• Using command line interface: docker run amnsbr/cubnm:* or singularity run /path/to/cubnm-<version>.sif. Command line interface is not available in v0.0.2.

Remember to bind your input and output directories to the container via -v in Docker and -B in Singularity.

To use GPUs add the flag --gpus all to Docker (before container name) and --nv to Singularity (before path to image). For more details on prerequisites for using GPUs inside the containers see Docker⁠ and Singularity⁠ documentations.