diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b395378f..deb79e21 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -34,12 +34,12 @@ jobs: - name: Install deb dependencies run: sudo apt-get install -y xorg-dev libglu1-mesa-dev libglew-dev xvfb - name: Install python dependencies - run: pip install -r requirements.txt + run: pip install -r requirements-dev.txt - name: Cache python wheel packages uses: actions/cache@v3 with: path: ~/.cache/pip - key: wheel-cache-${{ hashFiles('requirements.txt') }} + key: wheel-cache-${{ hashFiles('requirements-dev.txt') }} - name: Install evolution gym run: pip install -e . - name: Run test diff --git a/README.md b/README.md index 1acc5eb6..d904e745 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,14 @@ > - Pip-installable, with wheels for common builds > - Tests -A large-scale benchmark for co-optimizing the design and control of soft robots. As seen in [Evolution Gym: A Large-Scale Benchmark for Evolving Soft Robots](https://evolutiongym.github.io/) (**NeurIPS 2021**). +Evolution Gym is a large-scale benchmark for co-optimizing the design and control of soft robots. It provides a lightweight soft-body simulator wrapped with a gym-like interface for developing learning algorithms. Evogym also includes a suite of 32 locomotion and manipulation tasks, detailed on our [website](https://evolutiongym.github.io/all-tasks). Task suite evaluations are described in our [NeurIPS 2021 paper](https://arxiv.org/pdf/2201.09863). [//]: # (teaser) ![teaser](images/teaser.gif) # Installation -You can install evogym from PyPi or from source. - -## From PyPi - -To use evogym in your projects, simply run: +To use evogym, simply run: ```shell pip install --upgrade evogym @@ -36,10 +32,8 @@ If your platform is not supported, you may try building from source: ### Requirements * Python 3.7+ -* Linux, macOS, or Windows with [Visual Studios 2017](https://visualstudio.microsoft.com/vs/older-downloads/) -* [OpenGL](https://www.opengl.org//) +* Linux, macOS, or Windows with [Visual Studios 2017](https://visualstudio.microsoft.com/vs/older-downloads/) build tools. * [CMake](https://cmake.org/download/) -* [PyTorch](http://pytorch.org/) Clone the repo and submodules: @@ -53,7 +47,7 @@ On **Linux only**: sudo apt-get install xorg-dev libglu1-mesa-dev ``` -To build the C++ simulation, build all the submodules, and install `evogym` run the following command in the environment of your choice: +Finally, to install `evogym`, run the following command in the environment of your choice: ```shell pip install -e . @@ -82,7 +76,7 @@ if __name__ == '__main__': env.reset() while True: - action = env.action_space.sample()-1 + action = env.action_space.sample() ob, reward, terminated, truncated, info = env.step(action) if terminated or truncated: @@ -93,24 +87,37 @@ if __name__ == '__main__': This script creates a random `5x5` robot in the `Walking-v0` environment. The robot is taking random actions. A window should open with a visualization of the environment -- kill the process from the terminal to close it. - -# Usage +## Tutorials + +You can find tutorials for getting started with the codebase on our [website](https://evolutiongym.github.io/tutorials). Completed code from all tutorials is also available in the `tutorials` folder, along with a `README`. Tutorials are included for: +- Using the [evogym API](https://evolutiongym.github.io/tutorials/basic-api.html) +- Making a [custom evogym environment](https://evolutiongym.github.io/tutorials/new-env.html) +- Supported [rendering options](https://github.com/EvolutionGym/evogym/blob/main/tutorials/rendering_options.py) ## Examples -To see example usage as well as to run co-design and control optimization experiments in EvoGym, please see the `examples` folder and its `README`. +To run co-design and control optimization experiments in EvoGym, please see the `examples` folder and its `README`. Included are scripts for: +- Running PPO +- Running a Genetic Algorithm +- Running Bayesian Optimization +- Running CPPN-NEAT +- Visualizing results +- Saving results as gifs -## Tutorials +Make sure you clone the repo with submodules: -You can find tutorials for getting started with the codebase on our [website](https://evolutiongym.github.io/tutorials). Completed code from all tutorials is also available in the `tutorials` folder. +```shell +git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git +``` + +Install the necessary python requirements: +```shell +pip install -r requirements.txt +``` ## Docs @@ -118,7 +125,39 @@ You can find documentation on our [website](https://evolutiongym.github.io/docum ## Design Tool -For instructions on how to use the Evolution Gym Design Tool, please see [this repo](https://github.com/EvolutionGym/evogym-design-tool). +The Design Tool provides a gui for creating Evolution Gym environments. Please see [this repo](https://github.com/EvolutionGym/evogym-design-tool). + +[//]: # (teaser) +![teaser](images/design-tool.gif) + +# Dev + +Install the repo with submodules: + +```shell +git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git +``` + +Install the necessary python requirements. You will additionally need to install the dev requirements: +```shell +pip install -r requirements.txt +pip install -r requirements-dev.txt +``` + +## Run Tests + +Run the full test suite: + +```shell +pytest -s -v -n auto +``` + +Or the lite test suite: + + +```shell +pytest -s -v -n auto -m lite +``` # Citation diff --git a/images/design-tool.gif b/images/design-tool.gif new file mode 100644 index 00000000..e086cac0 Binary files /dev/null and b/images/design-tool.gif differ diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 00000000..8883f14a --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,2 @@ +pytest +pytest-xdist \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index fff6cdaf..0d11f04c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,26 +1,5 @@ -# glfw==2.5.0 -# GPy==1.10.0 -# gym==0.22.0 -# h5py==3.6.0 -# imageio==2.14.1 -# matplotlib==3.5.1 -# neat-python @ git+https://github.com/yunshengtian/neat-python@2762ab630838520ca6c03a866e8a158f592b0370 -# numpy==1.21.5 -# opencv-python==4.5.5.62 -# Pillow==9.0.0 -# pybind11==2.9.0 -# pygifsicle==1.0.5 -# PyOpenGL==3.1.5 -# PyOpenGL-accelerate==3.1.5 -# torch==1.10.2 -# ttkbootstrap==1.5.1 -# typing==3.7.4.3 - neat-python @ git+https://github.com/yunshengtian/neat-python@2762ab630838520ca6c03a866e8a158f592b0370 GPyOpt @ git+https://github.com/yunshengtian/GPyOpt@5fc1188ffdefea9a3bc7964a9414d4922603e904 stable-baselines3 imageio -pygifsicle - -pytest -pytest-xdist \ No newline at end of file +pygifsicle \ No newline at end of file