README.md

Evolution Gym

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. Task suite evaluations are described in our NeurIPS 2021 paper.

Note

EvoGym has been recently updated! TLDR: requirements have been modernized (gym/gymnasium, numpy, etc.), and the library is now pip-installable.

Installation

EvoGym supports python 3.7 to 3.10 on most operating systems:

pip install evogym --upgrade

On Linux install the following packages (or equivalent):

sudo apt-get install xorg-dev libglu1-mesa-dev

From Source

If your platform is not supported, you may alternatively build from source:

Requirements

• Python 3
• Linux, macOS, or Windows with Visual Studios 2017 build tools.
• CMake

Clone the repo and submodules:

git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git

On Linux only:

sudo apt-get install xorg-dev libglu1-mesa-dev

Finally, to install evogym, run the following in the environment of your choice:

pip install -e .

Test Installation

If you have the repo cloned, cd to the examples folder and run the following script:

python gym_test.py

Alternatively, you can run the following snippet:

import gymnasium as gym
import evogym.envs
from evogym import sample_robot


if __name__ == '__main__':

    body, connections = sample_robot((5,5))
    env = gym.make('Walker-v0', body=body, render_mode='human')
    env.reset()

    while True:
        action = env.action_space.sample()
        ob, reward, terminated, truncated, info = env.step(action)

        if terminated or truncated:
            env.reset()

    env.close()

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.

Known Issues

Linux and Conda

Error message: libGL error: MESA-LOADER: failed to open iris: /usr/lib/dri/iris_dri.so

Fix: conda install -c conda-forge libstdcxx-ng

Usage

In addition to the resources below, you can find API documentation on our website.

Tutorials

You can find tutorials for getting started with the codebase on our website. Completed code from all tutorials is also available in the tutorials folder, along with a README. Tutorials are included for:

• Using the evogym API
• Making a custom evogym environment
• Supported rendering options

Examples

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

Make sure you clone the repo with submodules:

git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git

Install the necessary python requirements:

pip install -r requirements.txt

Design Tool

The Design Tool provides a gui for creating Evolution Gym environments. Please see this repo.

Headless Mode

EvoGym runs in headless mode by default, and avoids initializing rendering libraries until necessary. If using a server without rendering capabilities, ensure that:

# Envs are created with render_mode=None (None by default)
env = gym.make('Walker-v0', body=body, render_mode=None)

# If using the low-level api, do not call EvoViewer.render()
world = EvoWorld.from_json(os.path.join('world_data', 'simple_environment.json'))
sim = EvoSim(world)
viewer = EvoViewer(sim)
viewer.render('img') # <-- Rendering libraries are initialized; do not call this

Dev

Install the repo with submodules:

git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git

Install the necessary python requirements. You will additionally need to install the dev requirements:

pip install -r requirements.txt
pip install -r requirements-dev.txt

Run Tests

From within the tests directory run the full test suite:

cd tests
pytest -s -v -n auto

Or the lite test suite:

cd tests
pytest -s -v -n auto -m lite

Citation

If you find our repository helpful to your research, please cite our paper:

@article{bhatia2021evolution,
  title={Evolution gym: A large-scale benchmark for evolving soft robots},
  author={Bhatia, Jagdeep and Jackson, Holly and Tian, Yunsheng and Xu, Jie and Matusik, Wojciech},
  journal={Advances in Neural Information Processing Systems},
  volume={34},
  year={2021}
}