Installation¶
Because pulse2percept is in active development, there are at least two versions to choose from:
stable
: Our stable release can be installed via pip (see docs, code).latest
: Our bleeding-edge version must be installed from source, and may contain experimental features (see docs, code).
Note
Having trouble with the installation? Please refer to our Troubleshooting Guide.
Installing Python¶
Before getting started, you will need to install Python on your computer.
You can check if Python is already installed by typing python --version
in
a terminal or command prompt.
If you don’t have Python, you have several options:
- If you’re unsure where to start, check out the Python Wiki.
- Python Anaconda (good but slow in 2020): comes with the conda package manager and a range of scientific software pre-installed (NumPy, SciPy, Matplotlib, etc.).
- Python Miniconda (fast but minimal): comes with the conda package manager but nothing else.
Important
pulse2percept 0.6 was the last release to support Python <= 3.5. pulse2percept 0.7+ requires Python 3.6+.
On some platforms (e.g., macOS), you might also have to install pip yourself.
You can check if pip is installed on your system by typing pip --version
in a terminal or command prompt.
If you don’t have pip, do the following:
Download get-pip.py to your computer.
Open a terminal or command prompt and navigate to the directory containing
get-pip.py
.Run the following command:
python get-pip.py
Installing the stable pulse2percept release¶
After installing Python above, the stable pulse2percept release can be installed with pip:
pip3 install pulse2percept
You can also install a specific version:
pip3 install pulse2percept==0.6.0
Then from any Python console or script, try:
import pulse2percept as p2p
Important
Make sure you are reading the right version of the documentation: https://pulse2percept.readthedocs.io/en/stable (<– “stable”, not “latest”).
Note
Find out what’s new in the Release Notes.
Installing version 0.7.1 from source¶
Prerequisites¶
Python (>= 3.6): Make sure to install Python first.
XCode: On macOS, make sure to install Apple XCode.
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: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.6 requires C++ 14.X to be exact). Also note that you don’t need to install Visual Studio itself.
-
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.
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.OpenMP (optional): OpenMP is used to parallelize code written in Cython or C. OpenMP is part of the GCC compiler on Unix, and part of the MinGW compiler on Windows. Follow these instructions to get it to work on macOS.
Dependencies¶
pulse2percept requires:
- Python (>= 3.6)
- Cython (>= 0.28)
- NumPy (>= 1.9)
- SciPy (>= 1.0.1)
- ScikitImage (>=0.14)
- Matplotlib (>= 3.0.2)
- ImageIO FFMPEG (>=0.4)
- JobLib (>= 0.11)
Optional packages:
- Pandas for loading datasets in the
datasets
module. - Scikit Learn for machine learning functionality in the
model_selection
module. - Dask for parallel processing (a joblib alternative). Use conda to install.
- Pytest to run the test suite.
- OpenMP for parallel processing support.
All required packages are listed in requirements.txt
in the root directory
of the git repository, and can be installed with the following command:
git clone https://github.com/pulse2percept/pulse2percept.git
cd pulse2percept
pip3 install -r requirements.txt
All packages required for development (including all optional packages) are
listed in requirements-dev.txt
and can be installed via:
pip3 install -r requirements-dev.txt
Where to go from here
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
(note the .
):
pip3 install -e .
Then from any Python console or script, try:
import pulse2percept as p2p
Important
Make sure you are reading the right version of the documentation: https://pulse2percept.readthedocs.io/en/latest (<– “latest”, not “stable”).
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 pulse2perceptmake uninstall
: Uninstalls pulse2perceptmake tests
: Installs pulse2percept and runs the test suitemake doc
: Installs pulse2percept and generates the documentationmake clean
: Cleans out all build filesmake help
: Prints a help message with this menu of options
Upgrading pulse2percept¶
If you have previously installed pulse2percept, but wish to upgrade to the newest release, you have two options.
To upgrade to the newest 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
This works for both stable and latest releases.
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¶
Python ImportError: No module named pulse2percept¶
This is usually an issue related to $PATH
, the environment variable that
keeps track of all locations where pip should be looking for pulse2percept.
Chances are that pip installed pulse2percept somewhere outside of $PATH
.
You can check the installation location:
pip3 show pulse2percept
Then add the specificed location to $PATH
; see PATH on Windows,
PATH on macOS, PATH on Linux.
Error: numpy.ufunc size changed, may indicate binary incompatibility¶
This issue may arise when one of the p2p dependencies was compiled using an older NumPy version. Upgrading to the latest NumPy version should fix the issue:
pip3 install -U numpy
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.