Skip to content

Latest commit

 

History

History
148 lines (105 loc) · 6.33 KB

README.md

File metadata and controls

148 lines (105 loc) · 6.33 KB
Raw

Odyssey

Odyssey: A journey through robotic infrastructure; the ILIAD lab's stack for robotic demonstration collection, policy training, perception, and natural language.

Repository containing package source for Odyssey, the ILIAD lab's stack for real-world robotics, including perception and natural language handling. Built with Polymetis, PyTorch, using Anaconda for python dependencies and sane quality defaults (black, isort, flake8, precommit).

Note: This will eventually be rewritten as a PyPI-enabled package, with a setup.py to handle dependency management. The source here is mostly for nightly development.

Contributing

Before committing to the repository, make sure to set up your dev environment and pre-commit (pre-commit install)! Here are the basic contribution guidelines:

  • Install and activate the Conda Environment using the QUICKSTART instructions below.

  • On installing new dependencies (via pip or conda), please make sure to update the environment-<ID>.yaml files via the following command (note that you need to separately create the environment-cpu.yaml file by exporting from your local development environment!):

    make serialize-env --arch=<cpu | gpu>

More detailed instructions for intricate set up (e.g., simulators, experiment tooling, etc.) can be found in CONTRIBUTING.md.

Quickstart

Clones odyssey to the working directory, then walks through dependency setup, mostly leveraging the environment-<arch>.yaml files.

Shared Environment (for Clusters w/ Centralized Conda)

Project-specific conda environments have already been setup for both the Stanford-NLP and ILIAD clusters, under the name odyssey. The only necessary steps to take are cloning the repo, activating the appropriate environment, and running pre-commit install to start developing (if you develop on the remote).

Local Development - Linux w/ GPU & CUDA 11.3

Note: Assumes that conda (Miniconda, MiniForge, or Anaconda are all fine) is installed and on your path.

Ensure that you're using the appropriate environment-<gpu | cpu>.yaml file --> if PyTorch doesn't build properly for your setup, checking the CUDA Toolkit is usually a good place to start. We have environment-<gpu>.yaml files for CUDA 11.3 (and any additional CUDA Toolkit support can be added -- file an issue if necessary).

git clone https://github.com/Stanford-ILIAD/odyssey
cd odyssey
conda env create -f environments/environment-gpu.yaml  # Choose CUDA Kernel based on Hardware - by default use 11.3!
conda activate odyssey
pre-commit install  # Important!

Local Development - CPU (Mac OS & Linux)

Note: Assumes that conda (Miniconda, MiniForge or Anaconda are all fine) is installed and on your path. Use the -cpu environment file.

git clone https://github.com/Stanford-ILIAD/odyssey
cd odyssey
conda env create -f environments/environment-cpu.yaml
conda activate odyssey
pre-commit install  # Important!

Usage

This repository comes with sane defaults for black, isort, and flake8 for formatting and linting. It additionally defines a bare-bones Makefile (to be extended for your specific build/run needs) for formatting/checking, and dumping updated versions of the dependencies (after installing new modules).

Other repository-specific usage notes should go here (e.g., training models, running a saved model, running a visualization, etc.).

Repository Structure

High-level overview of repository file-tree (expand on this as you build out your project). This is meant to be brief, more detailed implementation/architectural notes should go in ARCHITECTURE.md.

  • environments - Serialized Conda Environments for both CPU and GPU (CUDA 11.3). Other architectures/CUDA toolkit environments can be added here as necessary.
  • odyssey/ - Package Source - has all functionality for robot interfaces, demo collection, perception, etc.
    • robot/ - Core robot interface implementation.
    • demonstration/ - Useful utilities for demonstration collection.
  • tests/ - Tests - please unit test (& integration test) your code when possible.
  • Makefile - Top-level Makefile (by default, supports conda serialization, and linting).
  • .flake8 - Flake8 Configuration File (Sane Defaults).
  • .pre-commit-config.yaml - Pre-Commit Configuration File (Sane Defaults).
  • pyproject.toml - Black and isort Configuration File (Sane Defaults).
  • ARCHITECTURE.md - [WIP] Write up of repository architecture/design choices, how to extend and re-work for different applications.
  • CONTRIBUTING.md - [WIP] Detailed instructions for contributing to the repository, in furtherance of the default instructions above.
  • README.md - You are here!
  • LICENSE - By default, research code is made available under the GPLv3 License. Change as you see fit, but think deeply about why!

Start-Up (from Scratch)

Use these commands if you're starting a repository from scratch (this shouldn't be necessary typically since original repository gets set up once, but I like to keep this in the README in case things break in the future).

Generally, if you're just trying to run/use this code, look at the Quickstart section above.

GPU & Cluster Environments (CUDA 11.3)

conda create --name odyssey python=3.8
conda activate odyssey
conda install pytorch torchvision torchaudio cudatoolkit=11.3 -c pytorch
conda install ipython jupyter

pip install black flake8 gym isort matplotlib pre-commit wandb

# Install other dependencies via pip below -- conda dependencies should be added above (always conda before pip!)
...

CPU Environments (Usually for Local Development -- Geared for Mac OS & Linux)

Similar to the above, but installs the CPU-only versions of Torch and similar dependencies.

conda create --name odyssey python=3.8
conda activate odyssey
conda install pytorch torchvision torchaudio -c pytorch
conda install ipython jupyter

pip install black flake8 gym isort matplotlib pre-commit

# Install other dependencies via pip below -- conda dependencies should be added above (always conda before pip!)
...

Containerized Setup

Support for running odyssey inside of a Docker or Singularity container is TBD. If this support is urgently required, please file an issue.