README.md 8.6 KB
Newer Older
Benjamin's avatar
Benjamin committed
1
# Animal-AI 2.0.0
Benjamin Beyret's avatar
Benjamin Beyret committed
2

Matthew Crosby's avatar
Matthew Crosby committed
3
4
5
6
<p align="center">
  <img height="300" src="documentation/PrefabsPictures/steampunkFOURcrop.png">
</p>

Benjamin Beyret's avatar
try mp4    
Benjamin Beyret committed
7
<p align="center">
Benjamin Beyret's avatar
Benjamin Beyret committed
8
  <img width="24%" src="examples/notebook_data/animal-cyl-fail.gif">
Benjamin Beyret's avatar
try mp4    
Benjamin Beyret committed
9
10
</p>

Benjamin Beyret's avatar
Benjamin Beyret committed
11
12
![](examples/notebook_data/animal-cyl-fail.gif)

Benjamin's avatar
Benjamin committed
13
14
<div>
    <div>
Benjamin Beyret's avatar
Benjamin Beyret committed
15
16
17
18
19
20
21
22
23
24
25
26
27
      <video width="24%" playsinline="" autoplay="" muted="" loop="">
          <source src="examples/notebook_data/animal-cyl-pass.mp4" type="video/mp4">
      </video>
      <video width="24%" " playsinline="" autoplay="" muted="" loop="">
          <source src="examples/notebook_data/agent-cyl-pass.mp4" type="video/mp4">
      </video>
      <video width="24%" playsinline="" autoplay="" muted="" loop="">
          <source src="examples/notebook_data/animal-cyl-fail.mp4" type="video/mp4">
      </video>
      <video width="24%" playsinline="" autoplay="" muted="" loop="">
          <source src="examples/notebook_data/agent-cyl-fail.mp4" type="video/mp4">
      </video>
  </div>
Benjamin's avatar
Benjamin committed
28
29
</div>

Benjamin Beyret's avatar
Benjamin Beyret committed
30
31
## Overview

Benjamin's avatar
Benjamin committed
32
33
34
The [Animal-AI](http://animalaiolympics.com/AAI) is a project which introduces the study of animal cognition to the world of AI. 
The aim is to provide an environment for testing agents on tasks taken from or inspired by the animal cognition literature.
Decades of research in this field allow us to train and test for cognitive skills in Artificial Intelligence agents.
35

Benjamin's avatar
Benjamin committed
36
37
This repo contains the [training environment](animalai), a [training library](animalai_train) as well as [900 tasks](competition_configurations) for testing and/or training agents.
The experiments are divided into categories meant to reflect various cognitive skills, the details can be found on the [website](http://animalaiolympics.com/AAI/testbed).
38

Benjamin's avatar
Benjamin committed
39
40
41
42
We ran a competition using this environment and the associated tests, more details about the results can be found [here](http://animalaiolympics.com/AAI/2019)

The environment is built using [Unity ml-agents](https://github.com/Unity-Technologies/ml-agents/tree/master/docs) and contains an agent enclosed in a fixed sized arena. Objects can spawn in this arena, including positive 
and negative rewards (green, yellow and red spheres) that the agent must obtain (or avoid). All of the hidden tests that will appear in the competition are made using the objects in the training environment. 
Benjamin Beyret's avatar
Benjamin Beyret committed
43

Benjamin's avatar
Benjamin committed
44
To get started install the requirements below, and then follow the jupyter notebook tutorials in the [examples folder](examples). 
45
More in depth documentation can be found on the [Documentation Page](documentation/README.md).
Benjamin Beyret's avatar
Benjamin Beyret committed
46

mdcrosby's avatar
mdcrosby committed
47
48
## Development Blog

49
You can read the launch posts - with information about prizes and the categories in the competition here:
50

51
52
[Animal-AI: AWS Prizes and Evaluation: Aug 12th](https://www.mdcrosby.com/blog/animalaiprizes1.html) - with updated submission and test information.

Matthew Crosby's avatar
Matthew Crosby committed
53
[Animal-AI Evaluation: July 8th](https://mdcrosby.com/blog/animalaieval.html) - with collated information about the evaluation.
54
55

[Animal-AI Launch: July 1st](https://mdcrosby.com/blog/animalailaunch.html) - with information about the prizes and  introduction to all 10 categories.
56

57
58
You can read the development blog [here](https://mdcrosby.com/blog). It covers further details about the competition as 
well as part of the development process.
mdcrosby's avatar
mdcrosby committed
59
60
61
62
63

1. [Why Animal-AI?](https://mdcrosby.com/blog/animalai1.html)

2. [The Syllabus (Part 1)](https://mdcrosby.com/blog/animalai2.html)

64
65
3. [The Syllabus (Part 2): Lights Out](https://mdcrosby.com/blog/animalai3.html)

Benjamin Beyret's avatar
Benjamin Beyret committed
66
67
## Requirements

Benjamin's avatar
Benjamin committed
68
The Animal-AI package works on Linux, Mac and Windows, as well as most Cloud providers, and requires python 3.
Benjamin Beyret's avatar
Benjamin Beyret committed
69

Benjamin's avatar
Benjamin committed
70
We offer two packages:
71
72

- The main package is an API for interfacing with the Unity environment. It contains both a 
73
74
75
[gym environment](https://github.com/openai/gym) as well as an extension of Unity's 
[ml-agents environments](https://github.com/Unity-Technologies/ml-agents/tree/master/ml-agents-envs). You can install it
 via pip:
76
    ```
Benjamin's avatar
Benjamin committed
77
    pip install animalai
78
    ```
Benjamin's avatar
Benjamin committed
79
    Or you can install it from the source by running `pip install -e animalai` from the repo folder
80

Benjamin's avatar
Benjamin committed
81
    <!--In case you wish to create a conda environment you can do so by running the below command from the `animalai` folder:
Guikarist's avatar
Guikarist committed
82
    ```
83
    conda env create -f conda_isntall.yaml
84
    ```-->ni    
Guikarist's avatar
Guikarist committed
85

86
- We also provide a package that can be used as a starting point for training, and which is required to run most of the 
Benjamin's avatar
Benjamin committed
87
example scripts found in the `examples/` folder. It contains an extension of 
88
[ml-agents' training environment](https://github.com/Unity-Technologies/ml-agents/tree/master/ml-agents) that relies on 
Benjamin's avatar
Benjamin committed
89
[OpenAI's PPO](https://openai.com/blog/openai-baselines-ppo/) and [BAIR's SAC](https://bair.berkeley.edu/blog/2018/12/14/sac/). You can also install this package using pip:
90
    ```
Benjamin's avatar
Benjamin committed
91
    pip install animalai-train
92
    ```
Benjamin's avatar
Benjamin committed
93
    Or you can install it from source by running `pip install -e animalai_train` from the repo folder
Benjamin Beyret's avatar
Benjamin Beyret committed
94

Benjamin's avatar
Benjamin committed
95
Finally **download the environment** for your system:
Benjamin Beyret's avatar
Benjamin Beyret committed
96
97
98

| OS | Environment link |
| --- | --- |
Benjamin's avatar
Benjamin committed
99
100
101
| Linux |  [download v2.0.0](https://www.doc.ic.ac.uk/~bb1010/animalAI/env_linux_v2.0.0.zip) |
| MacOS |  [download v2.0.0](https://www.doc.ic.ac.uk/~bb1010/animalAI/env_mac_v2.0.0.zip) |
| Windows | [download v2.0.0](https://www.doc.ic.ac.uk/~bb1010/animalAI/env_windows_v2.0.0.zip)  |
Benjamin Beyret's avatar
Benjamin Beyret committed
102

103
104
105
You can now unzip the content of the archive to the `env` folder and you're ready to go! Make sure the executable 
`AnimalAI.*` is in `env/`. On linux you may have to make the file executable by running `chmod +x env/AnimalAI.x86_64`. 
Head over to [Quick Start Guide](documentation/quickstart.md) for a quick overview of how the environment works.
Benjamin Beyret's avatar
Benjamin Beyret committed
106

Benjamin's avatar
Benjamin committed
107
The Unity source files for the environment can be found on our [ml-agents fork](https://github.com/beyretb/ml-agents). 
Benjamin Beyret's avatar
Benjamin Beyret committed
108

Benjamin Beyret's avatar
Benjamin Beyret committed
109
110
111
112
113
114
115
116
117
118
119
120
121
122
## Manual Control

If you launch the environment directly from the executable or through the VisualizeArena script it will launch in player 
mode. Here you can control the agent with the following:

| Keyboard Key  | Action    |
| --- | --- |
| W   | move agent forwards |
| S   | move agent backwards|
| A   | turn agent left     |
| D   | turn agent right    |
| C   | switch camera       |
| R   | reset environment   |

mdcrosby's avatar
mdcrosby committed
123
## Citing
124
If you use the Animal-AI environment in your work you can cite the environment paper:
mdcrosby's avatar
mdcrosby committed
125

126
127
128
129
130
131
132
133
134
135
Beyret, B., Hernández-Orallo, J., Cheke, L., Halina, M., Shanahan, M., Crosby, M. [The Animal-AI Environment: Training and Testing Animal-Like Artificial Cognition](https://arxiv.org/abs/1909.07483), arXiv preprint

```
@inproceedings{Beyret2019TheAE,
  title={The Animal-AI Environment: Training and Testing Animal-Like Artificial Cognition},
  author={Benjamin Beyret and Jos'e Hern'andez-Orallo and Lucy Cheke and Marta Halina and Murray Shanahan and Matthew Crosby},
  year={2019}
}
```

136
Paper with all the details of the test battery will be released after the competition has finished.
137

Benjamin Beyret's avatar
Benjamin Beyret committed
138
139
140
141
## Unity ML-Agents

The Animal-AI Olympics was built using [Unity's ML-Agents Toolkit.](https://github.com/Unity-Technologies/ml-agents)

Benjamin's avatar
Benjamin committed
142
143
The Python library located in [animalai](animalai) extends [ml-agents v0.15.0](https://github.com/Unity-Technologies/ml-agents/tree/0.15.0). Mainly, we add the 
possibility to change the configuration of arenas between episodes. 
Benjamin Beyret's avatar
Benjamin Beyret committed
144

145
146
Juliani, A., Berges, V., Vckay, E., Gao, Y., Henry, H., Mattar, M., Lange, D. (2018). [Unity: A General Platform for 
Intelligent Agents.](https://arxiv.org/abs/1809.02627) *arXiv preprint arXiv:1809.02627*
Benjamin Beyret's avatar
Benjamin Beyret committed
147

148
149
## EvalAI

Benjamin's avatar
Benjamin committed
150
151
The competition was kindly hosted on [EvalAI](https://github.com/Cloud-CV/EvalAI), an open source web application for AI competitions. Special thanks to [Rishabh Jain](https://rishabhjain.xyz/) for his help in setting this up.
We will aim to reopen submissions with new hidden files in order to keep some form of competition going.
152
153
154

Deshraj Yadav, Rishabh Jain, Harsh Agrawal, Prithvijit Chattopadhyay, Taranjeet Singh, Akash Jain, Shiv Baran Singh, Stefan Lee and Dhruv Batra (2019) [EvalAI: Towards Better Evaluation Systems for AI Agents](https://arxiv.org/abs/1902.03570)

mdcrosby's avatar
mdcrosby committed
155

Benjamin Beyret's avatar
Benjamin Beyret committed
156
## Version History
Benjamin Beyret's avatar
Benjamin Beyret committed
157

Benjamin's avatar
Benjamin committed
158
159
160
161
-v2.0.0:
    - fix small bugs
    - adds tutorial notebooks

Benjamin's avatar
Benjamin committed
162
163
164
165
166
167
168
169
170
171
172
- v2.0.0b0 (beta)
    - Bump ml-agents from 0.7 to 0.15 which:
        - allows multiple parallel environments for training
        - adds Soft actor critic (SAC) trainer
        - has a new kind of actions/observations loop (on demand decisions)
        - removes brains and some protobufs
        - adds side-channels to replace some protobufs
        - refactoring of the codebase
    - GoodGoalMulti are now yellow with the same texture (light emitting) as GoodGoal and BadGoal
    - The whole project including the Unity source is now available on [our ml-agents fork](https://github.com/beyretb/ml-agents)

Benjamin's avatar
Benjamin committed
173
For earlier versions see [here](documentation/versions.md)