Interface ProgressionNode<N>

Type Parameters:
N - the type of object used to represent a node in the search space
All Superinterfaces:
State
public interface ProgressionNode<N> extends State
A progression node represents a node in a search space and its context in a progression search, such as the temporal and epistemic depth at which the node exists in that search. The same node in a search space might be reached at different times and in different ways during different search methods. Likewise, the same search might find the same node in a search space multiple times but at different temporal or epistemic depths. A progresison node is a reference both to the search space node and to how and when it was reached in a particular search.
Author:
Stephen G. Ware

  • Method Details

    • getProblem

      default CompiledProblem getProblem()
      Returns the problem the search that generated this node is solving.
      Returns:
      the problem being solved by the search that generated this node

    • getSearch

      ProgressionSearch getSearch()
      Returns the search that generated this node.
      Returns:
      the search that generated this node

    • getSpace

      default ProgressionSpace<N> getSpace()
      Returns the search space the search that generated this node is using. The search space node associated with this progression node will be a node in that space.
      Returns:
      the search space used by the search that generated this node

    • getCharacter

      Character getCharacter()
      Returns the character whose utility the search that produced this node was trying to improve when this node was generated.
      Returns:
      the character whose utility the search was trying to improve when this node was generated

    • getTrunk

      N getTrunk()
      Returns this node's trunk, which is a search space node that represents the original action that was being explained when the search generated this node. When a progression search adds an action to a plan, it must explain that action for each of its consenting characters by creating branches for each one. A branch is the state that character believes will be the case after taking the action; the state after the original action from which the branches extend is the trunk for all of those branches. The primary search to improve the author's utility has no trunk, and this method will return null for those nodes.
      Returns:
      the trunk node that the search was explaining when this node was created, or null if this node is part of the search to improve the author's utility

    • getRoot

      N getRoot()
      Returns the root from which this node is a temporal descendant, which is a search space node that represents where the search that generated this node started. When a progression search adds an action to a plan, it must explain the action for each of its consenting characters by creating branches for each one. A branch starts in the state that character believes will be the case after taking the action; this starting state is called the root. The root node is one which, if explained, would mean the original trunk node is also explained for one of its consenting characters.
      Returns:
      the root node where the search began to explain an action for a character and which caused this node to be generated

    • getAction

      default CompiledAction getAction()
      Returns the action associated with this node's search space node.
      Returns:
      the action associated with this node's search space node

    • getNode

      N getNode()
      Returns the node from the search space that this progression node is referring to. A progression node is a reference to a node in the search's space (accessed with this method), but annotated with the context in which it was generated by the search.
      Returns:
      the search space node associated with this progression node

    • isExplained

      default boolean isExplained()
      Returns whether or not the search space node that this progression node refers to is explained for all the characters for which it needs to be explained. Usually, a node needs to be explained for all of the consenting characters of the action that led to the state the node represents. However, there is one special case: a root node. A root node is created to explain one action (the trunk) for one character. This means that a root node only needs to be explained for the character it was created to explained, even if the action has more than one consenting character. If this progression node is a root, this method will return true if it is explained for its character, no matter how many consenting characters the action may have.
      Returns:
      true if the node is explained for all its consenting characters or if the node is a root node and is explained for the character that root node was created to explain; false otherwise

    • isExplained

      default boolean isExplained(Character character)
      Returns whether or not the search space node that this progression node refers to is explained for the given character. In some implementations, this method will return false if the character is not a consenting character to the node's action, even if that character would want the action to happen.
      Parameters:
      character - the character for whom the node may be explained
      Returns:
      true if the node is explained for that character

    • getUtility

      default Value getUtility(Character character)
      Returns the utility of a given character (or the author, if the character is null) in the state represented by this progression node's search space node.
      Parameters:
      character - the character whose utility is desired, or null if the author's utility is desired
      Returns:
      the utility of that character in that state this node represents

    • getTemporalDepth

      int getTemporalDepth()
      Returns the number of actions that have been taken since the initial state, regardless of this node's epistemic depth. For author nodes (epistemic depth 0), this value is the same as plan length. For character nodes (epistemic depth > 0), this value includes any actions that occurred before the root node (even if the character did not observe them), the action leading to the root node, and all actions that have occurred since the root node.
      Returns:
      the number of actions taken since the initial state

    • getExplanationDepth

      int getExplanationDepth()
      Returns the number of actions that have been taken since the explanation this node is part of began. For author nodes (epistemic depth 0), this value is the same as plan length. For nodes with epistemic depth 1 (nodes created to explain author nodes), this value is also the same as plan length, regardless of where in the author's plan the action being explained occurs, because explanation length does not depend on the length of the author's plan. For nodes with epistemic depth > 1, this value includes any actions taken at lower epistemic depths.

      For example, say the author's plan is actions A then B. After the second action (B), explanation depth is the same as plan length, which is 2. Now suppose a branch is created with B as the trunk. This branch has an epistemic depth of 1. That node will have an explanation depth and plan length of 1 because action B is the first action in the branch (action B and the state after taking it form the root node of the new search). From that root, say two more actions C and D are taken. The state after D has an explanation depth of 3 (the root B + the two actions that have been taken since the root). Now suppose a branch is created with D as the trunk and an epistemic depth of 2. From there, two more actions E and F are taken. The state after F has a plan length of 3 (the root D + the two actions that have been taken since the root) but an explanation depth of 5, because it also counts actions B, C, and D from epistemic depth 1.

      Explanation depth is defined this way so that a search can have a character temporal limit which is different from its author temporal limit without creating an infinitely deep space.

      A search will only expand an author node (epistemic depth 0) if its explanation depth is less than the search's author temporal limit. A search will only expand a character node (epistemic depth > 0) if its explanation depth is less than the search's character temporal limit.

      Returns:
      the number of actions taken since the explanation began

    • getPlanLength

      int getPlanLength()
      Returns the number of actions that have been taken in the plan leading to this node. The only node with a plan length of 0 is the author root node of the search. The children of the author root node have a plan length of 1, their children a plan length of 2, and so on. For character nodes (epistemic depth > 0), this number will always be at least 1, because it will include the first action leading to the search's root node. In other words, for character nodes, the plan length is always 1 + the number of actions that have been taken since the root node.
      Returns:
      the number of actions taken in the plan to reach this node

    • getEpistemicDepth

      int getEpistemicDepth()
      Returns the depth of nested theory of mind (what one character believes another character believes, and so on) at which this node was created. All nodes have the same epistemic depth as their root, which is always 1 higher than their trunk. A node will only be visited if its epistemic depth is less than or equal to the search's epistemic limit.
      Returns:
      the depth of theory of mind at which this node was created