Installing Rockpool and contributing

Base requirements

Rockpool requires `Python 3.10`_, numpy and scipy to install. These requirements will be installed by pip when installing Rockpool. We recommend using anaconda, miniconda or another environment manager to keep your Python dependencies clean.

Installation using pip

The simplest way to install Rockpool is by using pip to download and install the latest version from PyPI.

pip install rockpool

Installation using conda

You can also install Rockpool using conda, from the conda-forge channel.

conda install -c conda-forge rockpool

Rockpool version

To check your Rockpool version, access the __version__ attribute of the module:

import rockpool
rockpool.__version__

Dependencies

Rockpool has several dependencies for various aspects of the library. However, these dependencies are compartmentalised as much as possible. For example, Jax is required to use the Jax-backed modules (e.g. RateJax); PyTorch is required to use the Torch-backed modules, and so on. But if these dependencies are not available, the remainder of Rockpool is still usable.

Rockpool provides several convenience installation options to assist with dependency management. These will install the required dependencies for e.g. running the tests, building the docs, installing specific backends, etc.

$ pip install "rockpool[numba, jax, torch, brian, sinabs, exodus, xylo, dynapse, tests, docs]"

To automatically install all of the extra dependencies required by Rockpool, use the command

$ pip install "rockpool[all]"

Some dependencies, such as pandoc, must be installed manually.

To check which computational back-ends are available to Rockpool, use the list_backends() function:

import rockpool
rockpool.list_backends()

Contributing

If you would like to contribute to Rockpool, then you should begin by forking the public repository at https://github.com/synsense/rockpool to your own account. Then clone your fork to your development machine

$ git clone https://github.com/your-fork-location/rockpool.git rockpool

Install the package in development mode using pip

$ cd rockpool
$ pip install -e . --user

or

$ pip install -e ".[all]" --user

The main branch is development. You should commit your modifications to a new feature branch.

$ git checkout -b feature/my-feature develop
...
$ git commit -m 'This is a verbose commit message.'

Then push your new branch to your repository

$ git push -u origin feature/my-feature

Use the Black code formatter on your submission during your final commit. This is required for us to merge your changes. If your modifications aren’t already covered by a unit test, please include a unit test with your merge request. Unit tests go in the tests directory.

Then when you’re ready, make a merge request on github.com, from the feature branch in your fork to https://github.com/synsense/rockpool.

Building the documentation

The Rockpool documentation is based on sphinx, and all dependencies required for a local HTML version are installed with pip install "rockpool[all]". You can install just the minimal dependencies to build the documentaion with pip install "rockpool[docs]", but note that you can only build documentation for the backends which are correctly installed and available for use by Rockpool.

To build a live, locally-hosted HTML version of the docs, use the command

$ cd docs
$ make clean html

Once built, the documentation will be placed in rockpool\docs\_build\html. Open index.html in a web browser to start using the documentation.

To build a PDF version of the docs, you need to install imagemagick on your system, as well as a working version of latex and pdflatex. You will need to install these dependencies manually.

Once all dependencies are installed, you can build the PDF docs with

$ cd docs
$ make clean latexpdf

Running tests

As part of the merge review process, we’ll check that all the unit tests pass. You can check this yourself (and probably should before making your merge request), by running the unit tests locally.

To run all the unit tests for Rockpool, use pytest:

$ git clone https://github.org/synsense/rockpool.git
$ cd rockpool
$ pip install ".[tests]"
$ pytest tests