README.md

Statespace

Plugin to generate state-space visualizations

Display a JSON statespace from a file, currently generated by Web-Planner, as a D3.js interactive graph. Supports both cartesian and radial layouts, with animations during layout change. Hover nodes and links with mouse to see state and action information, respectively. Click nodes to collapse or expand the graph. Click and drag background to move graph, and use scroll wheel to zoom in and out.

Statespace JSON

A complete JSON for a trivial Hanoi problem looks like the following:

{
  "name":  "initial state",
  "color": "#0000FF",
  "state": "3F",
  "children": [
    {
      "name":  "state 1",
      "color": "#0000FF",
      "state": "61E",
      "children": [],
      "action": "move(d1 d2 peg2)"
    },
    {
      "name":  "goal state",
      "color": "#FF0000",
      "state": "45D",
      "children": [],
      "action": "move(d1 d2 peg3)"
    }
  ],
  "predicates": [
    "clear peg2",
    "clear peg3",
    "clear d1",
    "on d3 peg1",
    "on d2 d3",
    "on d1 d2",
    "on d1 peg3",
    "on d1 peg1",
    "clear peg1",
    "on d1 peg2",
    "clear d2",
    "clear d3",
    "on d1 d3",
    "on d2 peg1",
    "on d2 peg2",
    "on d2 peg3",
    "on d3 peg2",
    "on d3 peg3"
  ]
}

In this example we start from the root node initial state and explore two states, children from the initial state. One of such states is state 1 and it does not meet the requirements to be a goal state, and is obtained by action move(d1 d2 peg2) applied to initial state. The other state does meet the requirements to be goal state applying move(d1 d2 peg3) to initial state. This example contains a very small JSON, remove spaces to obtain smaller files and better response times.

Each node contains a:

• name: string - nodes can have any name, however paths between initial state and "goal state" nodes are highlighted.
• color: color string - optional secondary notation to show the distance between current and goal state.
  • Color gradient from blue (far from goal) to red (goal).
• state: hexadecimal string or string array.
  • each set bit in the hexadecimal number represents a predicate from predicates at the same index that is true in the state. Leading zeros can be omitted.
  • each string in the array represents part of the state: ["at agent home", "happy agent"]. This representation leads to bigger files.
• children: array of nodes - array can be empty.
• action: string - name of action that generated this state, does not exist for the initial state.

All nodes share the same predicates, a list of fluent predicates used to display description of each state. Rigid predicates are not stored as they never change during planning.

Web-Planner uses breadth-first search (optimal) or greedy best-first search (fast) with Hamming distance and will ignore a previously visited state, which explains why some children may appear to be missing from the statespace. Previously found states are not connected to keep the graph as a tree structure, however previous states can reappear in new nodes if desired.

Payload

The client asks the server defined by Custom Planner URL for a statespace JSON, using {domain: domText, problem: probText, heuristic: heurText} as input, where:

• domText is the domain string;
• probText is the problem string;
• heurText is the heuristic search mode, currently limited to '' and 'hamming'.

The expected response is a statespace JSON.

References

For more information see our paper WEB PLANNER: A Tool to Develop Classical Planning Domains and Visualize Heuristic State-Space Search

@inproceedings{magnaguagno2017web,
  title={WEB PLANNER: A tool to develop classical planning domains and visualize heuristic state-space search},
  author={Magnaguagno, Maur{\'i}cio C. and Pereira, Ramon Fraga and M{\'o}re, Martin D. and Meneguzzi, Felipe},
  booktitle={Proceedings of the Workshop on User Interfaces and Scheduling and Planning, UISP},
  pages={32--38},
  year={2017}
}

Statespace is based on two D3.js examples:

• Radial Reingold-Tilford Tree
• Cartesian Reingold-Tilford Tree with interactive functions

ToDo's

• Improve documentation
• Optional name and color properties
• Generate color with user specified gradient (replace color with distance value)
• Generate Dovetail from root to specified node (requires new JS Dovetail implementation and bridge plugin)
• Search states (CTRL+F)