install.md

Installation

• Installation
  • Install requirements
    • [Optional] Step 1. Install conda
    • Step 2. Install Git LFS
      • Comment: working with data files
    • Steps 3. Install requirements to dedicated python environment
      • Option 1: use conda and pip
      • Option 2: use pip only
    • Step 3. Install htm.core
    • [Optional] Step 4. Install PyRep
    • [Optional] Step 5. Install AnimalAI 3
    • Step 6. Install hima package
    • [Optional] Step 7. Install Pinball
    • Project structure

Install requirements

[Optional] Step 1. Install conda

Using conda as an environment and package manager is optional. Using pip as a package manager and pipenv/virtualenv/etc. as Python environment managers is a valid option too.

However, we recommend to prioritize using conda over pip, because it allows managing not only python packages, as pip does, and also resolves package dependencies smarter, ensuring that the environment has no version conflicts (see understanding pip and conda for details). Having said that, we recommend trying to install as much packages as you can with conda first, and use pip only as the last resort (sadly, not every requirement is available in conda channels).

If you are new to conda, we recommend getting conda with Miniconda instead of Anaconda, because it's just a minimal console version of the conda tool (see the difference).

If you feel confident, you may also consider Miniforge as an alternative to Miniconda — the difference is only that it sets the default conda package channel to conda-forge, which is community-driven, so it gets updates faster in general and contains more packages. Another alternative - now to conda itself - is to use Mamba. Mamba mimics conda API, even uses it and fully backward compatible with it, so you can use both together; Mamba has enhanced dependency-resolving performance and async package installation, and also extends conda functionality. Last two options combined, Mamba + Miniforge = Mambaforge, are distributed by Miniforge community.

Step 2. Install Git LFS

To setup Git LFS you need to install git-lfs first:

# Linux:
apt install git-lfs

# Mac:
brew install git-lfs

Then "link" git and git-lfs together by:

# system-wise
git lfs install --system

# or only for the repository you're in
git lfs install

After this you just work as usual.

Check out .gitattributes for the project's git-lfs rules. To print all tracked files use git lfs ls-files.

Comment: working with data files

Storing binary or any other "data" files in a repository can quickly bloat its size. They rarely change, and if so, mostly as a whole file (i.e they are added or deleted, not edited). But git still treats them as text files and tries to track their content, putting it to the index.

If only was a way to track some signature of these files, store their content somewhere else and pull them only on demand! Fortunately, that's exactly what Git[hub] LFS do :) It stands for Large File Storage. Here's the quote from Git LFS site:

Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server like GitHub.com or GitHub Enterprise.

Steps 3. Install requirements to dedicated python environment

File requirements.txt contains all required dependencies. Also, as commented in requirements.txt, you will need to install four additional dependencies:

1. Our fork of the htm.core package.
2. [optional] CoppeliaSim + PyRep
3. [optional] AnimalAI
4. [optional] Pinball

In this section we provide you with two options: a) install requirements using both conda and pip or b) install everything with pip. In both cases everything is installed into the dedicated conda environment. The name of the environment is up to you, while we use hima for this guide.

Option 1: use conda and pip

Create new conda environment with all requirements that can be installed with conda; then install what's left with pip:

conda create --name hima python=3.9 numpy matplotlib jupyterlab ruamel.yaml tqdm wandb mock imageio seaborn pygraphviz colormap prettytable pytest
conda activate hima
pip install hexy

Option 2: use pip only

Create new conda environment and install everything with pip:

conda create --name hima python=3.9
conda activate hima
pip install -r requirements.txt

Step 3. Install htm.core

In our research we use a slightly modified version of the htm.core package, thus you have to install our fork instead of the origin. The following script installs it from the sources:

cd <where to fork>
git clone https://github.com/ZhekaHauska/htm.core.git
cd htm.core
pip install .

[Optional] Step 4. Install PyRep

If you are planning to run experiments with arm manipulators, you should also install PyRep.

[Optional] Step 5. Install AnimalAI 3

If you are planning to run experiments in AnimalAI environment, you should also install it.

Step 6. Install hima package

Install our hima package:

cd <hima_project_root>
pip install -e .

The last command installs hima with the "development mode" flag. It allows you importing modules from the hima package outside of the package root folder, e.g. in Jupyter Notebooks or in another projects. Development mode flag -e prevents the package sources to be copied to the package index. Instead, the symlink is created, which means that the edits are "visible" immediately and don't require you to reinstall/update the package manually after any changes in its sources.

[Optional] Step 7. Install Pinball

If you are planning to run experiments in Pinball environment, you should also install it.

Project structure

• hima/ - the package sources
  • experiments/scirpts/run_agent.py - runner, i.e. entry point to run testing scenarios.