Package: phyre
PHYREis 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.How to use the PHYREPhyre 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 thedemo.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., enablereasoning about physics in natural language. Seethis docfor details.As an interface to a fast physical engine: Phyre usesBox2dengine under the hood. In the benchmark we hide all details of the simulation. Seethis docfor details on low level interface.Getting startedInstallationThe 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. usingConda.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 phyreTo check that the installation was successful, runpython -m phyre.serverand openhttp://localhost:30303. That should start a local demo server.For instructions on building PHYRE from source and installing in a Docker container, seeINSTALLATION.NotebooksWe provide jupyter notebooks that showhow to use PHYRE API(open in Colab) to run simulations and evaluate a random agent andhow to use simulation cache(open in Colab) to train agents faster.Training an agentWe provide a set of baseline agents that are described in the paper.
In order to run them, you need to install additional python dependencies withpip install -r requirements.agents.txt.All the agents are located inagents/folder. The entry point istrain.pythat 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=memoizeFilerun_experiment.pycontains groups of experiments, e.g, sweeping over number of update for DQN-O or training agents on all seeds and eval setups. Andtrain_all_baseline.shstarts experiments to train all baseline algorithms in the paper.LicensePHYRE is released under the Apache license. SeeLICENSEfor additional details.CitationIf 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 projectsVirtual Toolsis a similar project aiming to research the structure necessary to capture human-like reasoning in these sorts of physics puzzles.ESPRITis a framework based on PHYRE that connects physical reasoning and natural language explanations.