Skip to content

Latest commit

 

History

History
278 lines (194 loc) · 11.3 KB

Instructions.md

File metadata and controls

278 lines (194 loc) · 11.3 KB
Raw

GOSEEK Instructions

These instructions will get your local machine setup to train, test, and submit solutions for the GOSEEK challenge.

Contents:

Prerequisites

The competition requires that you use linux.

Using Anaconda or miniconda is highly recommended. Python 3.7 is required.

Participating in the competition requires Docker, as well. The Perception Pipeline is defined in a Docker container. Participant policies are also submitted as Docker containers. Install Docker and then install nvidia-docker on your host machine. Note that if you are behind a proxy, please follow these instructions on configuring the docker client to use your organization's proxy settings.

Installation

  1. If using conda, create a new conda environment:
conda create -n goseek python=3.7 ipython jupyter numpy scipy
conda activate goseek
  1. Install tesse-gym.
git clone https://github.com/MIT-TESSE/tesse-gym.git
cd tesse-gym
python setup.py develop
cd ..

Note that we recommend installing in development mode in case you wish to make any local modifications. See below for further discussion.

  1. Clone this repository and install requirements.
git clone https://github.com/MIT-TESSE/goseek-challenge.git
cd goseek-challenge
  1. Next, you need to obtain GOSEEK simulator. Execute the following:
mkdir -p simulator
wget https://github.com/MIT-TESSE/goseek-challenge/releases/download/0.1.0/goseek-v0.1.4.zip -P simulator
unzip simulator/goseek-v0.1.4.zip -d simulator
chmod +x simulator/goseek-v0.1.4.x86_64

This creates a new simulator folder, download and unzips the simulator to that folder, and makes the simulator executable. Note that if you choose to place the simulator in an alternative location, you will need to specify the location in a configuration file that overrides the default value such as in config/check-ground-truth.yaml.

  1. Test your installation by running a random agent. The agent receives observations and takes random actions:
python eval.py --agent-config baselines/config/random-agent.yaml --episode-config config/check-ground-truth.yaml
  1. Next, build a docker image called goseek-base, which is needed to submit online solutions.
cd docker/goseek-base/
docker build -t goseek-base .
cd ../../

Optionally, run the following to verify the docker image. It should print the usage instructions for eval.py.

docker run --rm -it goseek-base /bin/bash -c "python eval.py --help"

  1. In order to run the Perception Pipeline, you will need another docker image with Kimera. Directions for building this image (named goseek-kimera) are as follows. Please note that building this image is not required to submit a solution for the competition; it is only used for any local testing and/or training with the Perception Pipeline. We strongly encourage participants to review further details on the perception pipeline, as well.

    a. First, obtain TensorRT. Note that you'll need to create an Nvidia account and manually download it because TensorRT is proprietary. Select TensorRT-6.0.1.5.Ubuntu-18.04.x86_64-gnu.cuda-10.0.cudnn7.6.tar.gz from the Nvidia TensorRT download page and place the binary in goseek-challenge/docker/goseek-kimera/.

    b. Build the docker image. Note that this takes quite a while. (Go watch a movie? 🤷‍♂️)

    docker build --rm -t goseek-kimera .

    c. And, optionally again, run the following to verify the docker image. It should return the list of directory contents in tesse_gym_bridge.

    docker run --rm -it goseek-kimera /bin/bash -c "source /catkin_ws/devel/setup.bash && rosls tesse_gym_bridge"

Usage

Training

We implement the OpenAI Gym interface in tesse-gym which can be used for reinforcement learning.

Our specific implementation for this challenge can be found in the goseek module. Participants are welcome to locally modify relevant details for developing a solution (e.g. modifying the reward function).

We provide a complete example demonstrating how to train a PPO agent using tesse-gym.

Local Evaluation

  1. Implement the following interface in baselines/agents.py.
class Agent:
    """ Interface for submitting an agent for evaluation. """

    def act(self, observation: np.ndarray) -> int:
        """ Act upon an environment observation.

        The observation is given as a vector of shape (384003,).
        The first 384000 values contain RGB, depth, and segmentation images,
        the last three contain pose in (x, y, heading).

        `tesse_gym` provides a function to decode this:

        >>> from tesse_gym.tasks.goseek import decode_observations 
        >>> rgb, segmentation, depth, pose = decode_observations(observation)
        
        Providing image and pose data:
        
        >>> rgb.shape
        (1, 240, 320, 3)
        >>> segmentation.shape
        (1, 240, 320, 3)
        >>> depth.shape
        (1, 240, 320, 3)
        >>> pose.shape
        (1, 3)

        Args:
            observation (np.ndarray): Shape (1, 384003) array of observations as described above.

        Returns:
            int: Agent's action in the range [0,3].
        """
        raise NotImplementedError

    def reset(self) -> None:
        """ Called when the environment resets. """
        raise NotImplementedError
  1. Define configuration files

All configurations required by the agent must be specified by a YAML file. This file must contain the field name, specifying the agent class name. All other fields will be passed as keyword arguments to the agent's class constructor upon initialization. An example is below:

# example-configuration.yaml
name: AgentName
custom_field_1: VALUE_1
...
custom_field_n: VALUE_N

Prepare Docker Submission

Competition submission are submitted as docker image, which you are responsible for preparing.

We will run eval.py on a participant docker image, which has the following usage.

usage: eval.py [-h] [--episode-config EPISODE_CONFIG]
               [--agent-config AGENT_CONFIG]

optional arguments:
  -h, --help            show this help message and exit
  --episode-config EPISODE_CONFIG
  --agent-config AGENT_CONFIG

Note the following.

  • We will run eval.py with an EPISODE_CONFIG value that points to a file we mount on the docker image with episode configuration information. Example configuration files, which are used for local testing, can be found in config.
  • You are responsible for updating baselines/agents.py to include your agent definition. Your code changes and any dependencies or additional files must be incorporated into the docker image.
  • We will also run eval.py with AGENT_CONFIG defined as agent.yaml. You are responsible for defining this file in the docker image. Note that if your policy does not require any configuration, then an empty file is acceptable.

Create docker image

This repository has a Dockerfile that specifies a RandomAgent. It copies baselines/agents.py, which defines the RandomAgent. It also copies a configuration file for the RandomAgent to agent.yaml.

Update this file as appropriate for your agent.

When complete, build your docker image.

docker build -t submission .

Test docker image

You can test your docker image locally using test_locally.py. It has the following usage.

usage: test_locally.py [-h] -s SIMULATOR -i IMAGE (-g | -p)

optional arguments:
  -h, --help            show this help message and exit
  -s SIMULATOR, --simulator SIMULATOR
                        Path to the simulator binary
  -i IMAGE, --image IMAGE
                        Name of the docker image to use for local evaluation
  -g, --groundtruth     Use groundtruth observations
  -p, --perception      Use realistic perception for observations

For example, you can run the following to test against Ground Truth data source:

python test_locally.py -s simulator/goseek-v0.1.4.x86_64 -i submission -g

Submitting docker image

As mentioned in competition overview, we are using the EvalAI platform to host our submission server. To upload a solution, please follow the instructions below:

  1. Install EvalAI-CLI: pip install evalai.

  2. Create on account on EvalAI's website and sign up for the GOSEEK-Challenge.

  3. Follow the instructions on the submission tab to push your docker image. Note that we've provided four phases -- some to support development. Only the leader of the Competition Phase with Perception Pipeline will be declared the competition winner.

Examples

See any of the following for additional information and examples.

Disclaimer

DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.

This material is based upon work supported by the Under Secretary of Defense for Research and Engineering under Air Force Contract No. FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Under Secretary of Defense for Research and Engineering.

(c) 2020 Massachusetts Institute of Technology.

MIT Proprietary, Subject to FAR52.227-11 Patent Rights - Ownership by the contractor (May 2014)

The software/firmware is provided to you on an As-Is basis

Delivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work.