We are in early beta, and may not have tested Walnut in your browser/OS combination yet, so it may not look perfect. Thanks for your patience! ×
We are in early beta, and the documentation may be incomplete and/or have missing links. Thanks for your patience! ×

What is Walnut

Walnut is a software system which allows the design and simulation of virtual “worlds” where several actors (from now on “agents”) interact with each other. It is designed as a teaching tool in the area of Artificial Intelligence (AI), so its users are assumed to have at least elementary notions of programming.

In typical usage a “world designer” (for example a teacher) defines a “world” (called “task environment” in AIMA) using a domain specific programming language. A world can be seen as a formal description for the rules of a game: tic-tac-toe, chess and poker are worlds with their rules, but other more abstract systems with no recreational purposes (stock broking, driving a taxi) are also worlds because they have rules, actors interacting within the world within those rules, and some notion of doing well or bad (i.e “winning” or “losing”). Walnut can use this world description to completely simulate the environment by software.

Once the world designer has specified a world, there are normally many problems that can be described within the rules of that world. The world of chess has problems ranging from “starting on the initial position, play the black pieces and win”, but also “starting with this set of pieces in these particular positions play white and checkmate black in 2 moves.”. The world of taxi driving may have problems like “pick as many passengers as possible in a day” or “earn the most money possible while avoiding dangerous areas in the city”. A “problem designer” generates a “problem description” based on a world description, describing what is the initial state, which agents are present, and what is the goal of the problem. This description is stored in a specially formatted data file.

Given a problem, one or several “agent programmers” (for example students) can write computer programs that control the behavior of agents. Those programs can be written in general purpose programming languages (right now, JavaScript is the one with better support).

With a world definition, a problem description, and agent programs Walnut allows a user to run “simulations”, essentially executions where the agents controlled by the programs interact during time with the world, and through the world with other agents. The Walnut simulator keeps track of how everything changes through time, and stores a historical log of the simulation called “trace”. The “trace” can also contain arbitrary data that agents wish to record, which allows to include internal information about the agent that is not part of the world definition (for example, a poker playing agent could store in the trace information about its belief about other players' bets and if it “thinks” they are bluffing or not).

Once a trace is generated (or even partially generated, which can happen when a simulation takes a long time to run), a user can see graphical representations of the trace. This graphical representation is controlled by users, because they might desire to observe different aspects of the game. On a poker game, one user might be interested about seeing the complete game (including the secret cards from every player), other might be interested in seeing the games from the viewpoint of an agent (seeing his one cards, but not the secret cards for other players), and other might not care for the cards but wants to see a plot showing how much money each player has over time. Walnut defines a visualization notation which allows specifying different was to graphically represent data.

Getting Started

Walnut is used through a web interface. To use walnut you should go to <http://thewalnut.io> using a web browser. You can browse at existing content without an account, but you need to sign up to be able to create and save new worlds, programs, problems and or visualizations.

The Walnut team tried to make it friendly and easy to use. However, as any system that allows describing complex elements with textual notation, it forces the user to go through a initial period of learning before being fully productive. The recommended way to learn it is:

  1. Learn how to use the simulator and the visualization interface, by playing with already defined world+problem+agents. You can follow the user-guide.rst, but it should be quite intuitive if you are used to learn how to use applications by clicking.
  2. If you want to design worlds read in detail the environment-design.rst document. Try following it, and then play by modifying the example worlds and problems. Once you have some familiarity you can use the reference.rst to look up specific functionality and build worlds from scratch. It's probably easier to start defining new problems based on example worlds if you want to do both.
  3. If you want to design agents for a specific world you'll need to skim at the environment-design.rst to see how it defines what kind of information is exchanged between your agent program and the world (i.e. the agent sensors and actuators). The agent-design.rst should be read in detail so you can learn the API that your agent should use to talk to the Walnut simulator. You can use the reference.rst document to look up any specific details used in the world specification or problem definition.