Merge pull request #36 from EvolutionGym/v2

v2 of EvoGym:
- Separation of requirements between core EvoGym library and examples
- Modernize requirements (python, gym, numpy)
- Pip-installable, with wheels for common builds
- Tests

.github/workflows/test.yml

@@ -1,6 +1,6 @@
-name: Testing
+name: Test
 
-on: [push, pull_request]
+on: [push]
 
 permissions:
   contents: read
@@ -10,16 +10,17 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
+  build_and_test:
     strategy:
+      fail-fast: false
       matrix:
         os:
-          - "ubuntu-22.04"
           - "ubuntu-latest"
         python:
           - "3.7"
           - "3.8"
           - "3.9"
+          - "3.10"
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v3
@@ -34,13 +35,14 @@ 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
-        run: xvfb-run python -m unittest tests/test_render.py
+        run: xvfb-run python -m pytest -s -v -n auto -m lite
+        working-directory: tests

.github/workflows/wheels.yml

@@ -0,0 +1,58 @@
+name: Build
+
+on: [push]
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Window 64 bit
+          - os: windows-latest
+            platform_id: win_amd64
+
+          # Linux 64 bit
+          - os: ubuntu-latest
+            platform_id: manylinux_x86_64
+            manylinux_image: manylinux_2_28
+
+            # manylinux2014 dosen't work due to an issue in GLEW:
+            # https://github.com/glfw/glfw/issues/2139
+            # manylinux_image: manylinux2014
+
+          # MacOS x86_64
+          - os: macos-12
+            platform_id: macosx_x86_64
+
+          # MacOS arm64
+          - os: macos-14
+            platform_id: macosx_arm64
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      # Used to host cibuildwheel
+      - uses: actions/setup-python@v5
+        with:
+            python-version: "3.8"
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel==2.19.0
+
+      # Build wheels
+      - name: Build wheels
+        run: python -m cibuildwheel --output-dir wheelhouse
+        # to supply options, put them in 'env', like:
+        # env:
+        #   CIBW_SOME_OPTION: value
+
+      # Upload wheels
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl

.gitignore

@@ -22,3 +22,4 @@ build_scripts
 .DS_Store
 exported/
 req_ns.txt
+backup/

MANIFEST.in

@@ -0,0 +1 @@
+graft evogym/simulator

README.md

@@ -1,91 +1,196 @@
 # Evolution Gym
 
-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**).
+![example workflow](https://github.com/EvolutionGym/evogym/actions/workflows/wheels.yml/badge.svg)
+![example workflow](https://github.com/EvolutionGym/evogym/actions/workflows/test.yml/badge.svg)
 
-[//]: # (<img src="images/teaser.gif" alt="teaser" width="800"/>)
-![teaser](images/teaser.gif)
+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).
+
+> [!NOTE]
+> EvoGym has been recently updated! TLDR: requirements have been modernized (gym/gymnasium, numpy, etc.), and the library is now pip-installable.
+
+[//]: # (<img src="https://github.com/EvolutionGym/evogym/blob/main/images/teaser.gif" alt="teaser" width="800"/>)
+![teaser](https://github.com/EvolutionGym/evogym/blob/main/images/teaser.gif)
 
 # Installation
 
-Clone the repo and submodules:
+EvoGym supports python `3.7` to `3.10` on most operating systems:
 
 ```shell
-git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git
+pip install evogym --upgrade
+```
+
+> [!CAUTION]
+> This doesn't work yet -- coming soon! For now, you can install from test pypi:
+> ```shell
+> pip install "numpy<2.0.0" gymnasium
+> pip install -i https://test.pypi.org/simple/ evogym
+> ```
+
+On **Linux** install the following packages (or equivalent):
+
+```shell
+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.7/3.8
-* Linux, macOS, or Windows with [Visual Studios 2017](https://visualstudio.microsoft.com/vs/older-downloads/)
-* [OpenGL](https://www.opengl.org//)
+* Python 3
+* 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/)
 
-<!--- (See [installation instructions](#opengl-installation-on-unix-based-systems) on Unix based systems) --->
+Clone the repo and submodules:
+
+```shell
+git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git
+```
 
 On **Linux only**:
 
 ```shell
 sudo apt-get install xorg-dev libglu1-mesa-dev
 ```
 
-Either install Python dependencies with conda:
+Finally, to install `evogym`, run the following in the environment of your choice:
 
 ```shell
-conda env create -f environment.yml
-conda activate evogym
+pip install -e .
 ```
 
-or with pip:
+## Test Installation
+
+If you have the repo cloned, `cd` to the `examples` folder and run the following script:
 
 ```shell
-pip install -r requirements.txt
+python gym_test.py
 ```
 
-### Build and Install Package
+Alternatively, you can run the following snippet:
 
-To build the C++ simulation, build all the submodules, and install `evogym` run the following command:
+```python
+import gymnasium as gym
+import evogym.envs
+from evogym import sample_robot
 
-```shell
-python setup.py install
-``` 
 
-### Test Installation
+if __name__ == '__main__':
 
-cd to the `examples` folder and run the following script:
+    body, connections = sample_robot((5,5))
+    env = gym.make('Walker-v0', body=body, render_mode='human')
+    env.reset()
 
-```shell
-python gym_test.py
+    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.
 
-<!--### OpenGL installation on Unix-based systems
+## Known Issues
 
-To install OpenGL via [homebrew](https://brew.sh/), run the following commands:
+### Linux and Conda
 
-```shell
-brew install glfw
-```
---->
+Error message: `libGL error: MESA-LOADER: failed to open iris: /usr/lib/dri/iris_dri.so`
 
-# Usage
+Fix: `conda install -c conda-forge libstdcxx-ng`
 
-## Examples
+</details>
+
+# Usage
 
-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`.
+In addition to the resources below, you can find API documentation on our [website](https://evolutiongym.github.io/documentation).
 
 ## 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.
+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 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
 
-## Docs
+Make sure you clone the repo with submodules:
 
-You can find documentation on our [website](https://evolutiongym.github.io/documentation).
+```shell
+git clone --recurse-submodules https://github.com/EvolutionGym/evogym.git
+```
+
+Install the necessary python requirements:
+```shell
+pip install -r requirements.txt
+```
 
 ## 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).
+
+[//]: # (<img src="images/teaser.gif" alt="teaser" width="800"/>)
+![teaser](images/design-tool.gif)
+
+## Headless Mode
+
+EvoGym runs in headless mode by default, without initializing libraries used for rendering.
+These libraries are initialized on user requests. If using a server without rendering capabilities, ensure that:
+
+```python
+# Envs are created with render_mode=None (None by default)
+env = gym.make('Walker-v0', body=body, render_mode=None)
+```
+
+```python
+# 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:
+
+```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
+
+From within the `tests` directory run the full test suite:
+
+```shell
+cd tests
+pytest -s -v -n auto
+```
+
+Or the lite test suite:
+
+
+```shell
+cd tests
+pytest -s -v -n auto -m lite
+```
 
 # Citation
 

evogym/envs/__init__.py

@@ -10,7 +10,7 @@
 from evogym.envs.traverse import *
 from evogym.envs.walk import *
 
-from gym.envs.registration import register
+from gymnasium.envs.registration import register
 
 ## SIMPLE ##
 register(