Installation¶

pulse2percept is in active development. To get the latest stable version, we recommend installing our latest release. If you wish to contribute to the project or require the bleeding-edge version, you will want to install from source instead.

Note

Having trouble with the installation? Please refer to our Troubleshooting Guide.

Prerequisites¶

Python (>=3.5): Before getting started, you will need to have to install Python on your computer. Check if Python is installed on your system by typing python --version in a terminal or command prompt.

Important

pulse2percept 0.5 was the last release to support Python 2.7 and 3.4. pulse2percept 0.6+ will require Python 3.5 or newer.
Cython (>= 0.28): pulse2percept relies on C extension modules for code acceleration. These require a C compiler, which on Unix platforms is already installed (gcc). However, on Windows you will have to install a compiler yourself:
1. Install Build Tools for Visual Studio 2019 from the Microsoft website. Note that the build tools for Visual Studio 2015 or 2017 should work as well (Python >= 3.5 requires C++ 14.X to be exact). Also note that you don’t need to install Visual Studio itself.
2. Install Cython:
```
pip3 install Cython
```
  If you get an error saying unable to find vcvarsall.bat, then there is a problem with your Build Tools installation, in which case you should follow this guide.
Warning

Some guides on the web tell you to install MinGW instead of Visual Studio. However, this is not recommended for 64-bit platforms. When in doubt, follow this guide.

Installing a release¶

After taking care of the prerequisites, the latest pulse2percept release can be installed using pip:

pip3 install pulse2percept

Then from any Python console or script, try:

import pulse2percept as p2p

Note

Find out what’s new in the Release Notes.

Installing from source¶

Prerequisites¶

Git: On Unix, you can install git from the command line. On Windows, make sure to download Git for Windows.
make (optional): pulse2percept provides a Makefile to simplify the build process. make is part of build-essentials on Ubuntu, XCode on Mac OS X, and can be downloaded from ezwinports on Windows.

Dependencies¶

pulse2percept requires:

Python (>= 3.5)
Cython (>= 0.28)
NumPy (>= 1.9)
SciPy (>= 1.0)
JobLib (>= 0.11)

Optional packages:

scikit-image for image functionality in the io module.
scikit-video for video functionality in the io module. You will also need an FFMPEG codec (see next bullet point).
ffmpeg codec if you’re on Windows and want to use functions in the io module.
Dask for parallel processing (a joblib alternative). Use conda to install.
Numba for just-in-time compilation. Use conda to install.
Pytest to run the test suite.

Obtaining the latest code from GitHub¶

Go to pulse2percept on GitHub and click on “Fork” in the top-right corner (you will need a GitHub account for this). This will allow you to work on your own copy of the code (https://github.com/<username>/pulse2percept) and contribute changes later on.
Clone the repository to get a local copy on your computer:
```
git clone https://github.com/<username>/pulse2percept.git
cd pulse2percept
```
Make sure to replace <username> above with your actual GitHub user name.

Note

A “fork” is basically a “remote copy” of a GitHub repository; i.e., creating “https://github.com/<username>/pulse2percept.git” from “https://github.com/pulse2percept/pulse2percept.git”.

A “clone” is basically a “local copy” of your GitHub repository; i.e., creating a local “pulse2percept” directory (including all the git machinery and history) from “https://github.com/<username>/pulse2percept.git”.
Install all dependencies listed in requirements.txt:
```
pip3 install -r requirements.txt
```
This includes Cython. If you are on Windows, you will also need a suitable C compiler (see Prerequisites above).

If you plan on contributing to pulse2percept, you should also install all developer dependencies listed in requirements-dev.txt:
```
pip3 install -r requirements-dev.txt
```

Building pulse2percept¶

Assuming you are still in the root directory of the git clone, type:

pip3 install -e .

Then from any Python console or script, try:

import pulse2percept as p2p

Building with make¶

pulse2percept provides a Makefile to simplify the build process. If you followed the above guide to install make, the following commands are available:

make: Installs pulse2percept
make uninstall: Uninstalls pulse2percept
make tests: Installs pulse2percept and runs the test suite
make doc: Installs pulse2percept and generates the documentation
make clean: Cleans out all build files
make help: Prints a help message with this menu of options

Upgrading pulse2percept¶

If you have previously installed pulse2percept, but wish to upgrade to the latest version, you have two options.

To upgrade to the latest stable release, use the -U option with pip:

pip3 install -U pulse2percept

To upgrade to the bleedingest-edge version, navigate to the directory where you cloned the git repository. If you have never upgraded your code before, add a new remote repository named “upstream” (you need to do this only once):

git remote add upstream https://github.com/pulse2percept/pulse2percept.git

Then you sync your fork by grabbing the latest code from the pulse2percept master branch:

git pull upstream master

Uninstalling pulse2percept¶

You can uninstall pulse2percept using pip:

pip3 uninstall pulse2percept

In addition, if you installed from source, you may want to manually delete the directory where you cloned the git repository that contains all the source code.

Troubleshooting¶

I’m getting an error in fast_retina.pyx when installing with pip on Windows¶

Early builds of pulse2percept 0.4 mistakingly omitted the Windows binary for the Cython-dependent fast_retina module (see issue #88). The solution is to either pip install a later version, or to build from source.

Note

Still having trouble? Please open an issue on GitHub and describe your problem there. Make sure to mention your platform and whether you are installing using pip or from source.