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.
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
QUICKSTARTinstructions below. -
On installing new dependencies (via
piporconda), please make sure to update theenvironment-<ID>.yamlfiles via the following command (note that you need to separately create theenvironment-cpu.yamlfile 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.
Clones odyssey to the working directory, then walks through dependency setup, mostly leveraging the
environment-<arch>.yaml files.
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).
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!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!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.).
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, supportscondaserialization, 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!
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.
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!)
...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!)
...Support for running odyssey inside of a Docker or Singularity container is TBD. If this support is
urgently required, please file an issue.