| 1 |
Installing the BMTK |
| 2 |
=================== |
| 3 |
|
| 4 |
**Users are encouraged to register** `here <https://secure2.convio.net/allins/site/SPageServer/?pagename=modeling_tools>`_ |
| 5 |
**to receive updates and other communications, but registration is not required to use the package.** |
| 6 |
|
| 7 |
The BMTK was developed for use for Python 2.7+ and Python 3.6+. Previous releases can be downloaded from |
| 8 |
`here <https://github.com/AllenInstitute/bmtk/releases>`__. The latest code including the newest features and bug fixes |
| 9 |
can be found on the `develop branch of our GitHub repo <https://github.com/AllenInstitute/bmtk>`_. |
| 10 |
|
| 11 |
The base installation, which will let you build networks, parse and analyze simulation reports, requires the following |
| 12 |
dependencies: |
| 13 |
|
| 14 |
* `numpy <http://www.numpy.org/>`_ |
| 15 |
* `h5py <http://www.h5py.org/>`_ |
| 16 |
* `pandas <http://pandas.pydata.org/>`_ |
| 17 |
* `matplotlib <https://matplotlib.org/>`_ |
| 18 |
* `jsonschema <https://pypi.python.org/pypi/jsonschema>`_ |
| 19 |
* `pytest <https://docs.pytest.org/en/latest/>`_ [optional for running unit tests] |
| 20 |
|
| 21 |
All components of the BMTK will work on a single machine, but some parts can take advantage of parallelism against |
| 22 |
HPC clusters, and requires the following to be installed: |
| 23 |
|
| 24 |
* `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ |
| 25 |
|
| 26 |
|
| 27 |
For running network simulations BMTK uses existing software which varies depending on the type of simulation you want |
| 28 |
to run. Individual instructions are done for the various requirements of the different simulation engines. |
| 29 |
|
| 30 |
|
| 31 |
Installing the latest from the source |
| 32 |
------------------------------------- |
| 33 |
:: |
| 34 |
|
| 35 |
$ git clone https://github.com/AllenInstitute/bmtk.git |
| 36 |
$ cd bmtk |
| 37 |
$ python setup.py install |
| 38 |
|
| 39 |
|
| 40 |
Installing with pip |
| 41 |
------------------- |
| 42 |
:: |
| 43 |
|
| 44 |
$ pip install bmtk |
| 45 |
|
| 46 |
|
| 47 |
Installing with conda |
| 48 |
--------------------- |
| 49 |
:: |
| 50 |
|
| 51 |
$ conda install -c kaeldai bmtk |
| 52 |
|
| 53 |
|
| 54 |
Using the Docker Image |
| 55 |
---------------------- |
| 56 |
The BMTK docker container lets you build and simulate networks without requiring installing all the BMTK prerequisites on |
| 57 |
your computer. All you need is the `docker client <https://docs.docker.com/install/>`__ installed on your machine. |
| 58 |
|
| 59 |
:: |
| 60 |
|
| 61 |
$ docker pull alleninstitute/bmtk |
| 62 |
|
| 63 |
There are two main ways of using the bmtk-docker image, either as a command-line application or as a Jupyter Notebook |
| 64 |
server |
| 65 |
|
| 66 |
Through the command line |
| 67 |
++++++++++++++++++++++++ |
| 68 |
|
| 69 |
Go to the directory where your BMTK network-builder and/or network-simulation scripts and supporting files are located |
| 70 |
(*local/path*) and run the following in a command-line terminal |
| 71 |
|
| 72 |
:: |
| 73 |
|
| 74 |
$ docker run alleninstitute/bmtk -v local/path:/home/shared/workspace python <my_script>.py <opts> |
| 75 |
|
| 76 |
Due to the way docker works, all files to build/run the network must be within *local/path*, including network files, |
| 77 |
simulator components, output directories, etc. If your config.json files references anything outside the working |
| 78 |
directory branch things will not work as expected. |
| 79 |
|
| 80 |
**NEURON mechanisms:** |
| 81 |
If you are running BioNet and have special mechanisms/mod files that need to be compiled, you can do so by running |
| 82 |
|
| 83 |
:: |
| 84 |
|
| 85 |
$ cd /path/to/mechanims |
| 86 |
$ docker run -v $(pwd):/home/shared/workspace/mechanisms alleninstitute/bmtk nrnivmodl modfiles/ |
| 87 |
|
| 88 |
|
| 89 |
Through Jupyter Notebooks |
| 90 |
+++++++++++++++++++++++++ |
| 91 |
The bmtk-docker image can be run as a jupyter notebook server. Not only will it contain examples and notebook tutorials |
| 92 |
for you to run, but you can use it to create new bmtk notebooks. In a command-line run |
| 93 |
|
| 94 |
:: |
| 95 |
|
| 96 |
$ docker run -v $(pwd):/home/shared/workspace -p 8888:8888 alleninstitute/bmtk jupyter |
| 97 |
|
| 98 |
|
| 99 |
Then open a browser to 127.0.0.1:8888/. Any new files/notebooks should be saved to *workspace* directory, otherwise they |
| 100 |
will be lost once the container is closed. |
| 101 |
|
| 102 |
|
| 103 |
Through Neuroscience Gateway (NSG) |
| 104 |
++++++++++++++++++++++++++++++++++ |
| 105 |
The bmtk can be run through the Neuroscience Gateway for anyone who has an account. |
| 106 |
|
| 107 |
For running multi-core BioNet (NEURON-based) simulations on the NSG please refer to `Readme file <https://github.com/AllenInstitute/bmtk/tree/develop/examples/bio_nsg_template>`_. |
| 108 |
|
| 109 |
|
| 110 |
Running Simulations |
| 111 |
------------------- |
| 112 |
|
| 113 |
Biophysically detailed simulations |
| 114 |
++++++++++++++++++++++++++++++++++ |
| 115 |
|
| 116 |
Running simulations of biophysically detailed, multi-compartmental neuronal models are done with `BioNet <bionet>`_ which |
| 117 |
uses the NEURON simulator, version 7.4 and above. Precompiled version of NEURON can be downloaded and installed from |
| 118 |
`here <https://www.neuron.yale.edu/neuron/download/precompiled-installers>`__. Make sure to install the Python bindings. |
| 119 |
|
| 120 |
The precompiled installed version of NEURON may have issues if you are using an Anaconda or Python virtual environment. |
| 121 |
Similarly, it will not compile with MPI support so you can't parallelize the simulation. You can find instructions |
| 122 |
for compiling NEURON for `Linux <https://www.neuron.yale.edu/neuron/download/compile_linux>`_, |
| 123 |
`Mac <https://www.neuron.yale.edu/neuron/download/compilestd_osx>`_, and |
| 124 |
`Windows <https://www.neuron.yale.edu/neuron/download/compile_mswin>`_. |
| 125 |
|
| 126 |
* **NOTE** - BioNet does not use the NEURON GUI (iv package) and we recommend you compile with the --without-iv option |
| 127 |
|
| 128 |
|
| 129 |
Point-Neuron simulations |
| 130 |
++++++++++++++++++++++++ |
| 131 |
|
| 132 |
The PointNet simulation engine is responsible for running point-neuron networks using the `NEST simulator <http://www.nest-simulator.org/>`_, |
| 133 |
version 2.11 and above. Instructions for installing NEST can be found `here <http://www.nest-simulator.org/installation/>`__. |
| 134 |
|
| 135 |
|
| 136 |
Filter Models |
| 137 |
+++++++++++++ |
| 138 |
|
| 139 |
FilterNet is the simulation engine responsible for simulating firing rate responses to stimuli onto the visual fields. It |
| 140 |
uses a piece of simulation software called LGNModel developed at the Allen Institute for Brain Science. Luckily, LGNModel |
| 141 |
is already built into the BMTK and no extra installation instructions are required. |
| 142 |
|
| 143 |
|
| 144 |
Population-Level Models |
| 145 |
+++++++++++++++++++++++ |
| 146 |
|
| 147 |
PopNet will simulate population-level firing rate dynamics using `DiPDE <https://github.com/AllenInstitute/dipde>`_. Instructions |
| 148 |
for installing DiPDE can be found `here <http://alleninstitute.github.io/dipde/user.html#quick-start-install-using-pip>`_. |
| 149 |
However, we recommend installing DiPDE using anaconda:: |
| 150 |
|
| 151 |
$ conda install -c nicholasc dipde |
| 152 |
|