Metadata-Version: 2.4
Name: cubnm
Version: 0.0.7
Summary: A toolbox for brain network modeling on GPUs 
Author-email: Amin Saberi <amnsbr@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2023, cuBNM Developers
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: Unix
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy<2,>=1.20
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: pymoo==0.6
Requires-Dist: tabulate
Requires-Dist: matplotlib
Requires-Dist: seaborn
Provides-Extra: cupy-cuda11x
Requires-Dist: cupy-cuda11x; extra == "cupy-cuda11x"
Requires-Dist: numba; extra == "cupy-cuda11x"
Provides-Extra: cupy-cuda12x
Requires-Dist: cupy-cuda12x; extra == "cupy-cuda12x"
Requires-Dist: numba; extra == "cupy-cuda12x"
Dynamic: license-file

.. image:: https://raw.githubusercontent.com/amnsbr/cubnm/main/docs/_static/logo_text.png
    :align: center
    :width: 350px

.. badges-start

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.12097797.svg
  :target: https://zenodo.org/doi/10.5281/zenodo.12097797

.. image:: https://img.shields.io/pypi/v/cubnm
  :target: https://pypi.org/project/cubnm/

.. image:: https://img.shields.io/readthedocs/cubnm
  :target: https://cubnm.readthedocs.io

.. image:: https://img.shields.io/badge/docker-amnsbr/cubnm-blue.svg?logo=docker
  :target: https://hub.docker.com/r/amnsbr/cubnm

.. image:: https://app.codacy.com/project/badge/Grade/e1af99e878bc4dbf9525d8eb610e0026
  :target: https://app.codacy.com/gh/amnsbr/cubnm/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade

.. image:: https://img.shields.io/github/license/amnsbr/cubnm
  :target: ./LICENSE

.. badges-end

cuBNM toolbox is designed for efficient brain network modeling on GPUs.

.. overview-start

Overview
--------
cuBNM toolbox uses GPUs to efficiently run simulations of brain network models 
consisting of nodes (neural mass models) which are connected through a connectome, 
and fit them to empirical neuroimaging data through integrated optimization algorithms.

GPU parallelization enables massive scaling of the simulations into higher number of
simulations and nodes. Below you can see how computing time varies
as a funciton of number of simulations and nodes on GPUs versus CPUs. For example,
running 2^17 simulations (duration: 60s, nodes: 100) would take 15 days on a single
CPU core, but only 19 minutes on an A100 GPU:

.. image:: https://raw.githubusercontent.com/amnsbr/cubnm/main/docs/_static/scaling.png
    :alt: Scaling plots

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.

Currently three models (`rWW`, `rWWEx` and `Kuramoto`) are implemented, but the
modular design of the code makes it possible to add new models, and a guide
is included on how to contribute new models. 

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.

At its core the toolbox runs highly parallelized simulations using C++/CUDA, while the 
user interface is written in Python and allows for user control over simulation 
configurations:

.. image:: https://raw.githubusercontent.com/amnsbr/cubnm/main/docs/_static/flowchart_extended.png
    :alt: Flowchart of the cuBNM program

.. overview-end

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