Introducing tomsup: Theory of mind simulations using Python

Peter Thestrup Waade, Kenneth Enevoldsen, Arnault‐Quentin Vermillet, Arndis Simonsen, Riccardo FusaroliBehavior 2022 · DOI

Abstract

Theory of Mind (ToM)—the capacity to attribute mental states such as beliefs and intentions to others—is a fundamental component of social interaction. Despite its importance, many ToM theories remain verbally specified and lack the computational rigor required for precise experimental testing. This paper introduces tomsup, an open-source Python package that implements the variational recursive Bayesian $k$-ToM model. By providing a high-performance environment for simulating social agents, tomsup allows researchers to model complex mentalizing processes, benchmark human behavior, and integrate computational models into real-time experimental designs.

Introduction

The study of social cognition has long been hampered by the "under-specification" of Theory of Mind. While researchers agree that humans infer the mental states of others, the underlying mechanisms are often described in vague terms. This lack of precision contributes to inconsistent results in experimental psychology and ongoing debates regarding the development of ToM in children or its impairment in clinical populations, such as those with autism spectrum disorder.

Computational modeling offers a solution by formalizing these processes. However, many existing models are implemented in specialized software environments, such as the MATLAB-based VBA toolbox, which can be inaccessible to researchers primarily using Python. tomsup bridges this gap, offering a robust, accessible, and high-performance ecosystem for ToM simulation.

The $k$-ToM Framework

The core of the tomsup package is the $k$-ToM model, a recursive Bayesian framework that defines levels of social sophistication:

  • 0-ToM Agents: These agents are "mindblind." They do not attribute mental states to others but instead track the probability of an opponent's actions as if they were observing a biased coin.
  • 1-ToM Agents: These agents represent their opponent as a 0-ToM agent, adjusting their own strategy based on the inferred bias of the other player.
  • $k$-ToM Agents: These agents recursively represent their opponent as having a sophistication level of $k-1$.

To ensure these recursive inferences are computationally feasible for real-time applications, tomsup utilizes Variational Bayesian inference. This approach transforms complex integration problems into faster optimization problems, enabling agents to update their beliefs about an opponent's volatility, bias, and sophistication level on a trial-by-trial basis.

In addition to the $k$-ToM model, the package includes standard game-theoretic baselines for comparison, including heuristic models like Tit-For-Tat and Win-Stay Lose-Shift, as well as model-free reinforcement learning agents (Q-Learning).

Implementation and Performance

A primary goal of tomsup is to provide a significant performance boost over previous implementations. By porting the $k$-ToM model to Python and optimizing the underlying mathematics, the authors achieved speedups of 10x to 100x compared to the original MATLAB VBA implementation. For instance, a 1-ToM agent simulation that took ~0.80 seconds in VBA now takes approximately 0.04 seconds in tomsup. With 4-core parallelization, even complex 5-ToM simulations are reduced from nearly 40 seconds to just 7 seconds.

This efficiency makes tomsup viable for high-throughput simulations and real-time online experiments. The package is designed to integrate seamlessly with experimental software like PsychoPy, allowing these agents to serve as dynamic, adaptive stimuli that respond to human participants in real-time.

Key Insights from Simulations and Human Data

The authors evaluated the package through simulated tournaments and a human validation study involving 47 undergraduate students. Several key insights emerged:

  1. The Limit of Recursion: Simulations suggest that recursion beyond level 3 ($k=3$) rarely yields additional strategic benefits. At higher levels, representations become so uncertain that they are indistinguishable from lower levels, a finding that mirrors the known cognitive limits of human social reasoning.
  2. Parameter Recovery: $k$-ToM agents are highly effective at "reading" their opponents. Simulations demonstrated that a 3-ToM agent could accurately recover the hidden bias and volatility parameters of its opponent within 10 to 30 rounds of play.
  3. Framing Effects: In human studies, participants performed better when they believed they were playing against a "slot machine" (non-social framing) rather than a "human" (social framing). However, this performance gap closed as the opponent's strategy increased in complexity.

Limitations and Future Directions

While tomsup provides a powerful tool for social cognition research, it currently focuses on "dominantly reactive" agents. These agents choose the optimal move for the current trial but do not yet engage in long-term strategic planning, such as intentional deception. Future versions may incorporate Monte Carlo Tree Search (MCTS) or active inference to address this.

Additionally, the current implementation is optimized for binary choices (2x2 payoff matrices). Expanding the framework to support multi-choice games, continuous action spaces, and interactions within complex social networks remains a priority for future development.

Conclusion

tomsup provides a necessary bridge between theoretical social psychology and rigorous computational modeling. By offering a fast, open-source Python implementation of the $k$-ToM model, it empowers researchers to move beyond verbal theories and develop more precise, testable models of human social interaction.

Summary updated

BibTeX
@inproceedings{waade2022introducing,
  author = {Peter Thestrup Waade and Kenneth Enevoldsen and Arnault‐Quentin Vermillet and Arndis Simonsen and Riccardo Fusaroli},
  title = {{Introducing tomsup: Theory of mind simulations using Python}},
  booktitle = {Behavior},
  year = {2022},
  doi = {10.3758/s13428-022-01827-2},
}
Figure