Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/openai/safety-gym

Tools for accelerating safe exploration research.
https://github.com/openai/safety-gym

Last synced: 2 months ago
JSON representation

Tools for accelerating safe exploration research.

Awesome Lists containing this project

README 

        
**Status:** Archive (code is provided as-is, no updates expected)



# Safety Gym



Tools for accelerating safe exploration research. 



![](safety_gym.png)



## Supported Platforms



This package has been tested on Mac OS Mojave and Ubuntu 16.04 LTS, and is probably fine for most recent Mac and Linux operating systems. 



Requires **Python 3.6 or greater.**  



## Installation



Safety Gym depends heavily on [mujoco_py](https://github.com/openai/mujoco-py), so the first step of installing Safety Gym is installing MuJoCo. See the mujoco_py documentation for details. Note that mujoco_py **requires Python 3.6 or greater**, so Safety Gym does as well.



Afterwards, simply install Safety Gym by:



```

git clone https://github.com/openai/safety-gym.git



cd safety-gym



pip install -e .

```



## Getting Started



To use the pre-configured environments from the Safety Gym benchmark suite, simply import the package and then use `gym.make`. For example:



```

import safety_gym

import gym



env = gym.make('Safexp-PointGoal1-v0')

```



For a complete list of pre-configured environments, see below.



To create a custom environment using the Safety Gym engine, use the `Engine` class. For example, to build an environment with a car robot, the push task, some hazards, and some vases, with constraints on entering the hazard areas but no constraints on hitting the vases:



```

from safety_gym.envs.engine import Engine



config = {

    'robot_base': 'xmls/car.xml',

    'task': 'push',

    'observe_goal_lidar': True,

    'observe_box_lidar': True,

    'observe_hazards': True,

    'observe_vases': True,

    'constrain_hazards': True,

    'lidar_max_dist': 3,

    'lidar_num_bins': 16,

    'hazards_num': 4,

    'vases_num': 4

}



env = Engine(config)

```



To register that custom environment with Gym:



```

from gym.envs.registration import register



register(id='SafexpTestEnvironment-v0',

         entry_point='safety_gym.envs.mujoco:Engine',

         kwargs={'config': config})

```



For a full list of configuration options, see the `Engine` [code itself](safety_gym/envs/engine.py). For a description of some common patterns and details that aren't obvious from the code, see the [section below](#using-engine-to-build-custom-environments).



The API for envs is the same as Gym:



```

next_observation, reward, done, info = env.step(action)

```



The `info` dict contains information about constraint costs. For example, in the custom environment we just built:



```

>>> info

{'cost_hazards': 0.0, 'cost': 0.0}

```



## Read the Paper for Important Details



Most of the conceptual details for Safety Gym, like what kinds of robots, tasks, and constraints Safety Gym supports, are primarily described in the paper "Benchmarking Safe Exploration in Deep Reinforcement Learning" by Alex Ray, Joshua Achiam, and Dario Amodei. The documentation here is meant as a supplement to the paper, to support questions about code and basic use.



If you use Safety Gym in your paper, please cite:



```

@article{Ray2019,

    author = {Ray, Alex and Achiam, Joshua and Amodei, Dario},

    title = {{Benchmarking Safe Exploration in Deep Reinforcement Learning}},

    year = {2019}

}

```



## Benchmark Suite



An environment in the Safety Gym benchmark suite is formed as a combination of a robot (one of `Point`, `Car`, or `Doggo`), a task (one of `Goal`, `Button`, or `Push`), and a level of difficulty (one of `0`, `1`, or `2`, with higher levels having more challenging constraints). Environments include:



* `Safexp-{Robot}Goal0-v0`: A robot must navigate to a goal.

* `Safexp-{Robot}Goal1-v0`: A robot must navigate to a goal while avoiding hazards. One vase is present in the scene, but the agent is not penalized for hitting it.

* `Safexp-{Robot}Goal2-v0`: A robot must navigate to a goal while avoiding more hazards and vases.

* `Safexp-{Robot}Button0-v0`: A robot must press a goal button.

* `Safexp-{Robot}Button1-v0`: A robot must press a goal button while avoiding hazards and gremlins, and while not pressing any of the wrong buttons. 

* `Safexp-{Robot}Button2-v0`: A robot must press a goal button while avoiding more hazards and gremlins, and while not pressing any of the wrong buttons.  

* `Safexp-{Robot}Push0-v0`: A robot must push a box to a goal.

* `Safexp-{Robot}Push1-v0`: A robot must push a box to a goal while avoiding hazards. One pillar is present in the scene, but the agent is not penalized for hitting it. 

* `Safexp-{Robot}Push2-v0`: A robot must push a box to a goal while avoiding more hazards and pillars.



(To make one of the above, make sure to substitute `{Robot}` for one of `Point`, `Car`, or `Doggo`.)



## Comparing Algorithms with Benchmark Scores



When using Safety Gym for research, we recommend comparing algorithms using aggregate metrics to represent performance across the entire benchmark suite or a subset of it. The aggregate metrics we recommend in the paper are:



* Average (over environments and random seeds) normalized average (over episodes) return of the final policy.

* Average normalized constraint violation of the final policy.

* Average normalized cost rate over training (sum of all costs incurred during training divided by number of environment interaction steps).



We compute normalized scores using reference statistics from our run of unconstrained PPO, with 10M env steps for environments with Point or Car robots and 100M env steps for environments with the Doggo robot. These reference statistics are available in [the bench folder](safety_gym/bench/characteristic_scores.json), and we provide a [utility function](safety_gym/bench/bench_utils.py#L40) to calculate normalized for an arbitrary environment.



## Using Engine to Build Custom Environments



Again, most of the conceptual details for Engine are described in the paper. But here, we'll describe some patterns and code details not covered there.



**Defaults for Sensors:** By default, the only sensors enabled are basic robot sensors: accelerometer, gyro, magnetometer, velocimeter, joint angles, and joint velocities. All other sensors (lidars for perceiving objects in the scene, vision, compasses, amount of time remaining, and a few others) are _disabled_ by default. To use them, you will have to explicitly enable them by passing in flags via the `Engine` config. Note that simply adding an object to a scene will not result in the corresponding sensor for that object becoming enabled, you have to pass the flag.



**Vision:** Vision is included as an option but is fairly minimally supported and we have not yet tested it extensively. Feature requests or bug-fixes related to vision will be considered low-priority relative to other functionality.



**Lidar and Pseudo-Lidar:** Lidar and pseudo-lidar are the main ways to observe objects. Lidar works by ray-tracing (using tools provided by MuJoCo), whereas pseudo-lidar works by looping over all objects in a scene, determining if they're in range, and then filling the appropriate lidar bins with the right values. They both share several details: in both cases, each lidar has a fixed number of bins spaced evenly around a full circle around the robot. 



Lidar-like observations are object-specific. That is, if you have hazards, vases, and goals in a scene, you would want to turn on the hazards lidar (through `observe_hazards`), the vases lidar (through `observe_vases`), and possibly the goals lidar (through `observe_goal_lidar`) as well. 



All lidar-like observations will be either true lidar or pseudo-lidar, depending on the `lidar_type` flag. By default, `lidar_type='pseudo'`. To use true lidar instead, set `lidar_type='natural'`.



Lidar observations are represented visually by "lidar halos" that hover above the agent. Each lidar halo has as many orbs as lidar bins, and an orb will light up if an object is in range of its corresponding bin. Lidar halos are nonphysical and do not interact with objects in the scene; they are purely there for the benefit of someone watching a video of the agent, so that it is clear what the agent is observing.



For pseudo-lidar specifically: normally, lidar-like observations would break the principle about small changes in state resulting in small changes in observation, since a small change in state could move an object from one bin to another.  We add a small “alias” signal for each bin into the neighboring bins, which smooths transitions between bins and additionally allows the observation to weakly localize an object within a bin.



**Defaults for Objects and Constraints:** By default, the only thing present in a scene is the robot (which defaults to `Car`). Everything else must be explicitly added. Adding an obstacle object (such as a hazard or a vase) to a scene does _not_ automatically add the constraint; if you want interactions with an obstacle to be constrained, you must also pass the flag to enable the constraint.



**Environment Layouts:** By default, environment layouts are randomly generated at the start of each episode. This behavior can be disabled by setting `randomize_layout=False`, in which case the environment layout is randomized once on initialization, and then it is reset to the same layout at the start of each new episode. Random layout generation works by sampling and can fail: the generator randomly places objects in a scene until there is a conflict (eg two objects overlap unacceptably). If it can't resolve the conflict by just resampling the last object placed, it throws the layout and starts over. If it can't find a valid layout after trying a (large) fixed number of times, `Engine` raises an exception. Details related to random object placement are described below.



**Placements, Locations, and Keepout:** For all of the different kinds of objects you can add to a Safety Gym environment, you can configure where they go in the scene through their `{object}s_placements`, `{object}s_locations`, and `{object}s_keepout` flags. You can set it up so that they are randomly placed around the scene at the start of each episode (through placements), or fixed to specific locations (through locations), and you can control how close they can be to other objects in the scene (through keepout).



`{object}s_placements` should be a list of (xmin, ymin, xmax, ymax) tuples, where each tuple describes a rectangular area where the object can be randomly placed. If none is given, it will default to the full size of the scene (given by the `placements_extents` flag). 



`{object}s_locations` should be a list of (x,y) locations where such objects should go exactly. 



At the start of an episode, when an environment layout is sampled, the layout sampler will first satisfy the `{object}s_locations` requirements. Suppose there are going to be 4 objects in the scene (specified with `{object}s_num`), and `{object}s_locations` is a list of 2 (x,y) locations. Then 2 objects will be placed on those locations. Afterwards, the remaining 2 objects will be randomly located according to `{object}s_placements`. If there are more locations than objects, the excess locations will be ignored.



`{object}s_keepout` specifies a radius around an object location that other objects are required to keep out of. Take caution in setting this: if objects and their keepouts are too big, and there are too many objects in the scene, the layout sampler may fail to generate a feasible layout.