Computing symbolic evaluations
..............................

Soar provides a set of eight predefined symbolic evaluations.  The evaluation
object can be augmented with attribute ^symbolic-value and one of the
following values: *require-success, success, partial-success, indifferent,
partial-failure, failure,* and *prohibit-failure*.

The semantics of these values are given below, relative to their use in an
evaluation subgoal.  As with numeric evaluations, objects with the same
evaluation are made indifferent.

   * Require-success The state is the only next state in which success can be
     achieved, and this is the only path that can lead to this state. This is
     translated into a require preference for the operator.
     
   * Success The state achieves the goal.  There may be other states that
     achieve the goal and other paths to this state.  This is translated into
     a best preference for the operator.
     
   * Partial-success The state is on the path to the goal.  The state may, or
     may not be on the shortest or best path to the goal.  This is translated
     into a best preference for the operator.  If one operator has a success
     augmentation, and a second operator has a partial-success augmentation,
     a preference is created that the first operator is better than the
     second.
     
     
   * Indifferent There is knowledge that it does not matter whether this
     state is reached.  This is translated into an indifferent preference for
     the operator.
     
     
   * Partial-failure The state is not on the path to success.  This is
     translated into a worst preference for the operator.
     
     
   * Failure The state is a failure state.  This is translated into a worst
     preference for the operator.  If one operator is augmented with
     partial-failure, and a second operator is augmented with failure, a
     preference is created that the first operator is better than the second.
     
   * Prohibit-failure If the state is encountered, success can never be
     achieved.  This is translated into an prohibit preference for the
     operator.

The default knowledge also provides a simpler method to use in the evaluation
subgoal.  One of the predefined symbolic values can augment a lookahead state
*as the attribute*, taking the desired object its value.  The following
template shows how to use a success evaluation as a goal test in an
evaluation subgoal:

(sp your-production-name
   (goal <g> ^state <s> ^desired <d>)
   conditions that detect subgoal success by comparing <s> to <d>.
    -->
   (<s> ^success <d>))

These augmentations are converted to the corresponding ^symbolic-value
augmentations by the default productions for the evaluation object.

The desired object is copied from the tie-context automatically by the
default productions.  The value of the ^desired augmentation is necessary
because a given state may occur in multiple goals.  The desired object must
be included in the augmentation so that the symbolic evaluation is correctly
tied to the appropriate desired state.