Giter VIP home page Giter VIP logo

phyre's Introduction

GitHub license CircleCI

PHYRE is a benchmark for physical reasoning.

It provides a set of physics puzzles in a simulated 2D world. Each puzzle has a goal state (e.g., make the green ball touch the blue wall) and an initial state in which the goal is not satisfied (see the figure below). A puzzle can be solved by placing one or more new bodies in the environment such that when the physical simulation is run the goal is satisfied. An agent playing this game must solve previously unseen puzzles in as few attempts as possible.

phyre

How to use the PHYRE

Phyre framework could be used for several tasks related to physical reasoning.

  • As a benchmark: Phyre allows to evaluate different reasoning agents on a predefined set of tasks and complexity tiers. You can explore the tasks and try to solve them using the demo.
  • As a task building platform: Phyre contains a framework to create new levels with goals and objects from a way richer set that one used in the standard tiers. This could be used to study specific types of generalization for reasoning agents, performance or forward modelling, or something else, e.g., enable reasoning about physics in natural language. See this doc for details.
  • As an interface to a fast physical engine: Phyre uses Box2d engine under the hood. In the benchmark we hide all details of the simulation. See this doc for details on low level interface.

Getting started

Installation

The simplest way to install PHYRE is via pip. As PHYRE requires Python version 3.6, we recommend installing PHYRE inside a virtual environment, e.g. using Conda.

We provide PHYRE as a pip package for both Linux and Mac OS.

conda create -n phyre python=3.6 && conda activate phyre
pip install phyre

To check that the installation was successful, run python -m phyre.server and open http://localhost:30303. That should start a local demo server.

For instructions on building PHYRE from source and installing in a Docker container, see INSTALLATION.

Notebooks

We provide jupyter notebooks that show how to use PHYRE API (open in Colab) to run simulations and evaluate a random agent and how to use simulation cache (open in Colab) to train agents faster.

Training an agent

We provide a set of baseline agents that are described in the paper. In order to run them, you need to install additional python dependencies with pip install -r requirements.agents.txt.

All the agents are located in agents/ folder. The entry point is train.py that will train an agent on specified eval setup with a specified fold. E.g., the following command will train a memoization agent:

python agents/train.py \
    --output-dir=results/ball_cross_template/0 \
    --eval-setup-name=ball_cross_template \
    --fold-id=0 \
    --mem-rerank-size 100 \
    --agent-type=memoize

File run_experiment.py contains groups of experiments, e.g, sweeping over number of update for DQN-O or training agents on all seeds and eval setups. And train_all_baseline.sh starts experiments to train all baseline algorithms in the paper.

License

PHYRE is released under the Apache license. See LICENSE for additional details.

Citation

If you use PHYRE in your experiments, please cite it:

@article{bakhtin2019phyre,
    title={PHYRE: A New Benchmark for Physical Reasoning},
    author={Anton Bakhtin and Laurens van der Maaten and Justin Johnson and Laura Gustafson and Ross Girshick},
    year={2019},
    journal={arXiv:1908.05656}
}

Related projects

Datasets

Virtual Tools is a similar project aiming to research the structure necessary to capture human-like reasoning in these sorts of physics puzzles.

ESPRIT is a framework based on PHYRE that connects physical reasoning and natural language explanations.

Models

Forward Prediction for Physical Reasoning uses forward-prediction models improve the performance of physical-reasoning agents, particularly on complex tasks that involve many objects.

Solving Physics Puzzles by Reasoning about Paths is a model for goal-driven tasks that requires intuitive physical reasoning and intervention in the scene to achieve a desired end goal.

phyre's People

Contributors

akhti avatar dependabot[bot] avatar eltayebahmed avatar lauragustafson avatar ndrwmlnk avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.