# Installation

> We recommend [mamba](https://github.com/mamba-org/mamba) as a faster drop-in replacement for conda. After installing `mamba` (`conda install mamba -n base -c conda-forge`), simply substitute `mamba` for `conda` in all of the following instructions.

## Simple

### From Anaconda

1. Activate a conda environment with `python=3.8`:
    ```bash
    conda activate polymetis
    ```
    - If you don't have one yet, create one with the proper Python version:
       ```bash
       conda create -n polymetis python=3.8
       ```

1. Install polymetis using conda. This should pull the latest successful build from `main` branch.
    ```bash
    conda install -c pytorch -c fair-robotics -c aihabitat -c conda-forge polymetis
    ```
    > Note: We build the conda package with the [libfranka v0.9.0](https://github.com/frankaemika/libfranka/tree/0.9.0), which requires [Franka Control Interface (FCI) version >=4.2.1](https://frankaemika.github.io/docs/libfranka_changelog.html#id1). If you have a different version of FCI, consider building from source with the compatible version of libfranka (see below).

## For advanced users & developers

### From source

1. Clone repo:
    ```bash
    git clone git@github.com:facebookresearch/fairo
    cd fairo/polymetis
    ```

1. Create environment
    ```bash
    conda env create -f ./polymetis/environment.yml
    conda activate polymetis-local
    ```

1. Install Python package in editable mode:
    ```bash
    pip install -e ./polymetis
    ```

1. Build from source:
    - Optionally, build [libfranka](https://frankaemika.github.io/docs/libfranka.html) for use on Franka Panda hardware:
        ```bash
        # Build libfranka
        ./scripts/build_libfranka.sh

        # OPTIONAL: Build custom version of libfranka instead
        ./scripts/build_libfranka.sh <version_tag_or_commit_hash>
        ```
    - Optionally, [install the CUDA-enabled version of PyTorch](https://pytorch.org/get-started/locally/) (by default, only the CPU version is enabled).
    - Build Polymetis from source:
        ```bash
        mkdir -p ./polymetis/build
        cd ./polymetis/build

        cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_FRANKA=[OFF/ON] -DBUILD_TESTS=[OFF/ON] -DBUILD_DOCS=[OFF/ON]
        make -j
        ```

5. Start developing! Remember to rebuild if modifying C++ source code. When updating, you may need to do a `conda env update --file ./polymetis/environment.yml --prune` to update dependencies.

### From a local conda package

We rebuild a new conda package during CI on every pushed commit, and store it as an artifact in CircleCI. If you're trying to debug a particular commit, you may want to install the generated Conda package locally.

1. For the commit you're interested in, select the "Details" of the `conda-pkg-create-and-test` test:

    ![CircleCI artifact](img/circleci-check.png)

1. Click the "Artifacts" tab, and download the `polymetis*.tar.bz2` file generated by CircleCI:

    ![CircleCI artifact](img/circleci-artifact.png)

1. In a fresh conda environment, install the package:

    - Create a fresh conda environment:
        ```bash
        conda create -n polymetis-test python=3.8
        conda activate polymetis-test
        ```
    - Update the local channel:
        ```bash
        cd polymetis/polymetis
        PKG_PATH=/path/to/downloaded/polymetis*.tar.bz2 ./conda/build_conda_package.sh
        ```
    
    - Install polymetis from the local channel:
        ```bash
        conda install -c file://$(eval pwd)/conda/channel \
            -c pytorch \
            -c fair-robotics \
            -c aihabitat \
            -c conda-forge \
            polymetis
        ```