Aim of the project is to investigate how people and artificial agents use tools to intervene on the world to make planning easier.
The block tower reconstrution task is based on the one described in McCarthy, Kirsh, & Fan (2020) and adapted from the corresponding block_construction repo.
A subset of this work has been published as: Binder, F., Kirsh, D., and Fan, J. (2021). Visual scoping operations for physical assembly. Proceedings of the 43rd Annual Meeting of the Cognitive Science Society. See the work corresponding to the cogsci 2021 publication in the cogsci2021 branch
There are two main classes: worlds and agents. See the classes and derived classes for details. For minimal example run something like:
from scoping_simulations.model.BFS_Lookahead_Agent import BFS_Lookahead_Agent
import scoping_simulations.utils.blockworld as bw
import scoping_simulations.utils.blockworld_library as bl
a = BFS_Lookahead_Agent() #create agent
w = bw.Blockworld(silhouette=bl.stonehenge_6_4,
block_library=bl.bl_stonehenge_6_4) #create environment
a.set_world(w) #connect the two
while w.status() == 'Ongoing': #can we still act?
a.act(1,verbose=True) #plan and take one action in the environment
print('Finished with world in state:",w.status())
The following action level planners are available in models:
- A*
- A* lookahead
- Beam search lookahead
- Breadth First Search
- Breadth First Search lookahead
- Monte Carlo Tree Search
- Q learning
Use experiment_runner.py to run suites of experiments and save them to a data frame in the current directory.
The output of experiment_runner.py can be analysed in Analysis.ipynb using a variety of measures.
Resource_Rational_Subgoal_Planning_Agent.py implements hierarchical planning using resource-rational task decomposition. This is implemented by calculating all subgoals (when include_subsequences up to) lookahead into the future (on the block tower reconstruction task with the provided target structures, there are at most 8 subgoals possible), then selecting the sequence of subgoals that maximizes
The hierarchical planner can work with all action level planners mentioned above. Pass an instantiated action level planner to lower_agent.
In order to speed up the process, the hierarchical planners are implemented as simulations over a precomputed dataframe with solutions and costs to all potential subgoals.
Use subgoal_generator_runner.py to generate a dataframe of all subgoals. This dataframe can then by used to simulate various subgoal planning strategies using Simulated_Lookahead_Subgoal_Planning_Agent.py
Analysis of the data generated by subgoal_generator_runner.py files is performed with various notebooks in the analysis directory. For analysis and publication-quality figures used in the cogsci 2021 paper, see cogsci2021.ipynb.
To install the scoping_simulations package, run pip install -e . in the root directory of the repository. This will install the package in editable mode, so that changes to the source code will be reflected in the installed package.
Try using $ conda env create -f environment.yml to install all the required packages in a new environment named scoping.
- Python > 3.7 (3.12 recommended)
- node.js (needed for the JS based physics engine)
If Box2D will not install in a virtual environment, try the following:
conda install swig # needed to build Box2D in the pip install
pip install box2d-py # a repackaged version of pybox2d
Note that installiing Box2D is optional.
To run the experiments, run python experiment_runner.py in the root directory of the repository. This will run the experiments and save the results in a data frame either ~/scoping_simulations/results.
If you want to specify a custom folder, set the environment variable SCOPING_SIMULATIONS_DIR to the desired path.`
If you're getting an error like ModuleNotFoundError: No module named 'scoping_simulations', try running pip install -e . in the root directory of the repository.
If you're getting an error like OSError: [Errno 24] Too many open files, the OS doesn't have enough file handles for spawning the physics server. Run ulimit -n 8192 (or some other number) to increase the number of file handles.
The project uses black, isort and ruff for formatting and code sorting.
Please run sh lint.sh before committing.