DOCSEARCHbyAlgolia
Submit Docs

Evolution Gym

repository·main·Indexed 42 days ago

https://github.com/evolutiongym/evogym

A large-scale benchmark for developing and evaluating soft robot co-design algorithms. It provides a lightweight soft-body simulator with a Gymnasium-compatible interface for co-optimizing robot design and control using algorithms like PPO, Genetic Algorithms, Bayesian Optimization, and CPPN-NEAT. Version 2.0.0 supports Python 3.7 to 3.10.

Tokens
6K
Snippets
27
Records
28
Agent score
54%

What's inside EvoGym

  1. Run EvoGym in headless mode

    main

    EvoGym runs in headless mode by default. To ensure you do not trigger rendering library initialization on a server without a display, follow these patterns:

    Using the Gymnasium API: Set render_mode=None (which is the default).

    env = gym.make('Walker-v0', body=body, render_mode=None)

    Using the low-level API: Avoid calling EvoViewer.render().

    # Do NOT call viewer.render('img') if you want to stay headless
world = EvoWorld.from_json(os.path.join('world_data', 'simple_environment.json'))
sim = EvoSim(world)
viewer = EvoViewer(sim)

  3. Run Co-Design experiments

    main

    Co-design experiments evolve robot structures and control policies simultaneously. EvoGym provides three algorithms for this: Genetic Algorithm (run_ga.py), Bayesian Optimization (run_bo.py), and CPPN-NEAT (run_cppn_neat.py).

    Common Parameters

    All co-design scripts share these core parameters:

    • --exp-name: The name of the experiment. Files are saved to saved_data/<exp-name>.
    • --env-name: The environment to run co-design on (e.g., Walker-v0).
    • --pop-size: The population size for evolving robots.
    • --structure-shape: A (m, n) matrix representing the voxel dimensions of each robot.
    • --max-evaluations: The maximum number of unique robots to evaluate.
    • --num-cores: The number of robots to train in parallel. Note that the total number of processes created will be num-cores * n-envs.

    Execution

    Run the scripts from the examples directory. Note that default parameters are intended for testing and may not produce performant robots.

    python run_ga.py --eval-interval 10000 --total-timesteps 100000
python run_bo.py --eval-interval 10000 --total-timesteps 100000
python run_cppn_neat.py --eval-interval 10000 --total-timesteps 100000

    Use --help with any of the scripts to see specific available options.

    python run_ga.py --eval-interval 10000 --total-timesteps 100000

  4. Build EvoGym from source

    main

    If your platform is not supported by the pip wheels, you can build from source.

    Requirements

    Steps

    1. Clone the repository including submodules:
    git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git
    1. (Linux only) Install system dependencies:
    sudo apt-get install xorg-dev libglu1-mesa-dev
    1. Install the package in editable mode:
    pip install -e .
    git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git
# ... install dependencies ...
pip install -e .

  5. Use the EvoGym Simulator API

    main

    The EvoGym Simulator API allows you to programmatically create, step, and render simulators containing arbitrary objects and robots. While the simulator can handle many objects, performance may decrease as complexity increases. For a basic implementation pattern, refer to basic_api.py.

    # Refer to basic_api.py for implementation details on:
# - Creating a simulator
# - Stepping the simulation
# - Rendering the simulation

  6. Create a custom EvoGym environment

    main

    To create a custom environment, you should follow the pattern established in envs/simple_env.py. Custom environments must be registered in envs/__init__.py to be accessible. Once registered, you can visualize your custom environment using the provided visualization scripts.

    # Example workflow for custom environments:
# 1. Define environment in envs/simple_env.py
# 2. Register in envs/__init__.py
# 3. Visualize using:
# python .\visualize_simple_env.py

  7. Install EvoGym via pip

    main

    EvoGym supports Python 3.7 to 3.10. You can install the latest version directly using pip.

    On Linux, you must install the following system dependencies first:

    sudo apt-get install xorg-dev libglu1-mesa-dev
    pip install evogym --upgrade

  8. Generate GIFs from experiments

    main

    The make_gifs.py script generates GIFs from co-design experiments. This script does not take command line arguments; instead, you must edit the script directly to configure the following parameters:

    • GIF_RESOLUTION: Resolution of the produced GIFs.
    • name: The subdirectory name under saved_data/all_media/ where files are saved.
    • experiment_names: An array of experiment names to process.
    • env_names: An array of corresponding environment names.
    • load_dir: The directory where experiment data is stored.
    • generations: An array of generation numbers to include (defaults to all).
    • ranks: An array specifying which robots to use (ranked 1 to n based on reward). Defaults to all robots.
    • organize_by_experiment: Boolean flag to organize GIFs into separate folders per experiment.
    • organize_by_generation: Boolean flag to organize GIFs into separate folders per generation.
    my_job = Job(
    name = 'ga_walking_experiment_gifs',
    experiment_names= ['ga_walking_experiment'],
    env_names = ['Walker-v0'],
    load_dir = exp_root,
    ranks = [i for i in range(5)],
    organize_by_generation=True,
)

  9. Manage simulation layouts with EvoWorld

    main

    The EvoWorld class is used to specify and manage the layout of an Evolution Gym environment. It acts as a container for WorldObject instances and manages a grid that represents the simulation space. You can create worlds from JSON files (generated by the EvoGym Design Tool) or build them programmatically by adding objects via arrays or existing WorldObject instances. The world grid automatically expands if objects are added outside its current boundaries.

    from evogym.world import EvoWorld

# Create a world from a JSON specification
world = EvoWorld.from_json('my_env.json')

# Or build manually
world = EvoWorld()
# (Add objects using add_object or add_from_array)

  10. Define and manipulate WorldObject

    main

    A WorldObject represents a single entity within the simulation, containing its voxel structure, connections, and position.

    Creation Methods:

    • WorldObject.from_json(file_path): Loads a single object from a JSON file.
    • WorldObject.from_array(name, structure, connections=None): Creates an object from a NumPy array. If connections is None, all adjacent voxels are assumed connected.

    Key Attributes & Methods:

    • get_structure(): Returns the (n, m) voxel structure matrix (flipped vertically).
    • get_connections(): Returns a (2, k) array of pairwise voxel connections.
    • get_pos(): Returns the (x, y) position.
    • set_pos(x, y) / translate(dx, dy): Updates the object's position.
    import numpy as np
from evogym.world import WorldObject

# Create an object from an array
structure = np.array([[1, 2], [2, 1]])
obj = WorldObject.from_array(name='block', structure=structure)

print(f"Object position: {obj.get_pos()}")
print(f"Connections: {obj.get_connections()}")

  11. Fix libGL error on Linux and Conda

    main

    If you encounter the error libGL error: MESA-LOADER: failed to open iris: /usr/lib/dri/iris_dri.so while using Conda on Linux, run the following command to fix it:

    conda install -c conda-forge libstdcxx-ng

  12. Run PPO control optimization

    main

    You can train a robot's policy using Proximal Policy Optimization (PPO) by running the run_ppo.py script. The default setup in the example trains a policy for the Walker-v0 environment.

    Important Notes:

    • All scripts must be run from within the examples directory.
    • Ensure you have installed requirements via pip install -r requirements.txt and cloned the repository with submodules.
    • For serious training runs, it is recommended to set --total-timesteps to a value greater than 1e6.
    • Results are saved to saved_data/test_ppo by default.

    Use python run_ppo.py --help to see all customization options.

    python run_ppo.py --n-envs 4 --n-eval-envs 4 --n-evals 4 --eval-interval 10000 --total-timesteps 100000