Skip to content

Commit

Permalink
Update installation.rst (AdaptiveMotorControlLab#80)
Browse files Browse the repository at this point in the history 
* Update installation.rst

- simplify options, move paper repo to secondary menu

* Update installation.rst

- typo fixes

* Update docs/source/installation.rst
  • Loading branch information
@MMathisLab
MMathisLab authored Oct 2, 2023
1 parent eaa8940 commit 7400fb9
Showing 1 changed file with 47 additions and 41 deletions.
88 changes: 47 additions & 41 deletions docs/source/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Installation Guide
System Requirements
-------------------

CEBRA is written in Python (3.8+) and PyTorch. CEBRA is most effective when used with a GPU, but CPU-only support is provided. We provide instructions to run CEBRA on your system directly using Anaconda or Docker. The instructions below were tested on different compute setups with Ubuntu 18.04 or 20.04, using Nvidia GTX 2080, A4000, and V100 cards. Other setups are possible (including Windows), as long as CUDA 10.2+ support is guaranteed.
CEBRA is written in Python (3.8+) and PyTorch. CEBRA is most effective when used with a GPU, but CPU-only support is provided. We provide instructions to run CEBRA on your system directly. The instructions below were tested on different compute setups with Ubuntu 18.04 or 20.04, using Nvidia GTX 2080, A4000, and V100 cards. Other setups are possible (including Windows), as long as CUDA 10.2+ support is guaranteed.

- Software dependencies and operating systems:
- Linux or MacOS
Expand All @@ -20,25 +20,15 @@ Installation Guide
We outline installation instructions for different systems.
CEBRA will be installed via ``pip install cebra``.

Its dependencies can be installed using ``pip`` or ``conda`` and
CEBRA's dependencies can be installed using ``pip`` or ``conda`` and
we outline different options below.

Most users can only install the **minimal install**. 🚀 For more advanced users, CEBRA has different extra install options that you can select based on your usecase:

* ``[integrations]``: This will install (experimental) support for our streamlit and jupyter integrations.
* ``[docs]``: This will install additional dependencies for building the package documentation.
* ``[dev]``: This will install additional dependencies for development, unit and integration testing,
code formatting, etc. Install this extension if you want to work on a pull request.
* ``[demos]``: This will install additional dependencies for running our demo notebooks.
* ``[datasets]``: This extension will install additional dependencies to use the pre-installed datasets
in ``cebra.datasets``. Note that installing this extension *will not* download the data, which is available on `FigShare <https://figshare.com/s/60adb075234c2cc51fa3>`_.

.. tabs::

.. tab:: Google Colab

CEBRA can also be installed and run on Google colaboratory.
Please see the ``open in colab`` button at the top of each demo notebook for examples.
CEBRA can also be installed and run on Google Colaboratory.
Please see the ``open in colab`` button at the top of each `demo notebook <https://cebra.ai/docs/demos.html>`_ for examples.

If you are starting with a new notebook, simply run

Expand All @@ -58,33 +48,6 @@ Most users can only install the **minimal install**. 🚀 For more advanced user
$ conda env create -f conda/cebra.yml
.. tab:: Supplied conda (paper reproduction)

We provide a ``conda`` environment with the full requirements needed to reproduce the first CEBRA paper (although we
recommend using Docker). Namely, you can run CEBRA, piVAE, tSNE and UMAP within this conda env. It is *NOT* needed if you only want to use CEBRA.

* For all platforms except MacOS with M1/2 chipsets, create the full environment using ``cebra_paper.yml``, by running the following from the CEBRA repo root directory:

.. code:: bash
$ conda env create -f conda/cebra_paper.yml
* If you are a MacOS M1 or M2 user and want to reproduce the paper, use the ``cebra_paper_m1.yml`` instead. You'll need to install tensorflow. For that, use `miniconda3 <https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html>`_ and follow the setup instructions for tensorflow listed in the `Apple developer docs <https://developer.apple.com/metal/tensorflow-plugin/>`_. In the Terminal, run the following commands:

.. code:: bash
wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-MacOSX-arm64.sh -O ~/miniconda.sh
bash ~/miniconda.sh -b -p $HOME/miniconda
source ~/miniconda/bin/activate
conda init zsh
Then, you can build the full environment from the root directory:

.. code:: bash
$ conda env create -f conda/cebra_paper_m1.yml
.. tab:: conda

Conda users should currently use ``pip`` for installation. The missing dependencies will be installed in the install process. A fresh conda environment can be created using
Expand Down Expand Up @@ -127,6 +90,16 @@ Most users can only install the **minimal install**. 🚀 For more advanced user
$ pip install cebra
* 🚀 For more advanced users, CEBRA has different extra install options that you can select based on your usecase:

* ``[integrations]``: This will install (experimental) support for our streamlit and jupyter integrations.
* ``[docs]``: This will install additional dependencies for building the package documentation.
* ``[dev]``: This will install additional dependencies for development, unit and integration testing,
code formatting, etc. Install this extension if you want to work on a pull request.
* ``[demos]``: This will install additional dependencies for running our demo notebooks.
* ``[datasets]``: This extension will install additional dependencies to use the pre-installed datasets
in ``cebra.datasets``.

* Inference and development tools only

.. code:: bash
Expand Down Expand Up @@ -197,6 +170,39 @@ Installation Troubleshooting

If yopu have issues installing CEBRA, we recommend carefully checking the `traceback`_ which can help you look on `stackoverflow`_ or the popular-in-life-sciences, `Image Forum`_ for similar issues. If you cannot find a solution, please do post an issue on GitHub!

Advanced Installation for Schneider, Lee, Mathis 2023 paper experiments
-----------------------------------------------------------------------

If you want to install the additional dependencies required to run comparisons with other algorithms, please see the following:

.. tabs::
.. tab:: Supplied conda (paper reproduction)

We provide a ``conda`` environment with the full requirements needed to reproduce the first CEBRA paper (although we
recommend using Docker). Namely, you can run CEBRA, piVAE, tSNE and UMAP within this conda env. It is *NOT* needed if you only want to use CEBRA.

* For all platforms except MacOS with M1/2 chipsets, create the full environment using ``cebra_paper.yml``, by running the following from the CEBRA repo root directory:

.. code:: bash
$ conda env create -f conda/cebra_paper.yml
* If you are a MacOS M1 or M2 user and want to reproduce the paper, use the ``cebra_paper_m1.yml`` instead. You'll need to install tensorflow. For that, use `miniconda3 <https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html>`_ and follow the setup instructions for tensorflow listed in the `Apple developer docs <https://developer.apple.com/metal/tensorflow-plugin/>`_. In the Terminal, run the following commands:

.. code:: bash
wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-MacOSX-arm64.sh -O ~/miniconda.sh
bash ~/miniconda.sh -b -p $HOME/miniconda
source ~/miniconda/bin/activate
conda init zsh
Then, you can build the full environment from the root directory:

.. code:: bash
$ conda env create -f conda/cebra_paper_m1.yml
.. _PyTorch Docs: https://pytorch.org/
.. _virtual environment: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
.. _traceback: https://realpython.com/python-traceback/
Expand Down

0 comments on commit 7400fb9

Please sign in to comment.