TinySoar Host Environment

Like Soar8.2, the TinySoar host enviornment is a Tcl extension that provides a command-line interface to the TinySoar runtime. The Tcl extension also includes commands useful for developing and debugging agents for the runtime.

The handful of commands that the TinySoar Tcl extension adds to the Tcl environment are listed below.

Commands

dump-rete
Dump the RETE network. (For deep debugging only.)
ela[borate]
Run the TinySoar runtime for a single elaboration cycle.
export <file>
Export the RETE network as a C code to the specified file.
init-soar
Reset the runtime to its initial state, removing all preferences and working memory elements.
pref[erences] <id> ^<attr>
pref[erences] -a <id> ^<attr> [+|-]<val> <type> [<ref>]
pref[erences] -r <pref>
Display, add, or remove preferences from working memory. The preferences command has three forms. The first form displays the preferences for the specified slot: <id> must be an identifier, <attr>must by a symbolic constant. The second form is used to add a preference to the specified slot: <id> must be an identifier, <attr> must be a symbolic constant, and <val> may be an identifier, a symbolic constant, or a numeric constant. Numeric constants must be prefixed by a + or a - to distinguish them from identifiers. <type> is the preference type; specifically:
+ acceptable
- reject
@ reconsider
= indifferent, unary or binary
< worst if unary, worse if binary
> best if unary, better if binary
Binary preferences (indifferent, worse, or better) also require the referent <ref> to be specified. The referent may be an identifier, a symbolic constant, or a numeric constant. The result of preferences -a is a unique number identifying the preference. This value can be used with the third form of the command, preferences -r, to remove the preference from working memory. Note that preferences -r is not idempotent: using it more than once on the same preference (or using it with a value not returned from preferences -a) will cause undefined behavior and possibly crash the runtime.
pri[nt] <id>
Print the working memory elements associated with the specified identifer <id>.
sp <production>
Add a production to the RETE network.

Example

Below is a sample session that illustrates how some of the commands are used. To follow along, start tclsh in the directory where you've built tinysoar.so, and load the drive.soar sample:

$ TCLLIBPATH=`pwd` tclsh
% source ../tinysoar/tests/drive.soar
Firing:
Retracting:
compiled: propose*drive
compiled: implement*drive
compiled: drive*reconsider
%

Run two elaboration cycles.

% ela
Firing:
  propose*drive
Retracting:
% ela
[1]: [5]
Firing:
  implement*drive
  drive*reconsider
Retracting:
% 

Note the `[1]: [5]' that is printed after the second elaboration. This indicates that operator [5] has been selected for state [1].

Let's print the working memory elements currently associated with state [1]. (Note that the top-level state is always identifier [1].)

% print 1
([1] ^superstate nil ^io [2] ^operator [5] ^operator [5] +)
% 

In other words, the top state has the I/O link [2], and operator [5] both with “normal” (^operator [5]) and “acceptable” (^operator [5] +) working memory elements present.

Let's look at the operator a bit more closely:

% print 5
([5] ^name drive)
% 

Operator [5]'s name is drive.

Let's look at what preferences are currently in working memory for identifier [1]'s ^operator slot:

% pref 1 ^operator
134698720: [5] @
134691928: [5] +
% 

There is a reconsider preference (`@') and an acceptable preference (`+') for the ^operator slot in the top state. Both preferences are for identifier [5].

Now let's tinker with preferences a bit:

% print 2
([2] ^input-link [3] ^output-link [4])
% pref -a 3 ^sensor-1 +100 +
134699296
% 

We just added an acceptable preference to the input link, setting the ^sensor-1 attribute to a numeric constant of +100. Let's double-check to be sure:

% pref 3 ^sensor-1
134699296: 100 +
% 

Note that there are no square-braces around the 100: that indicates that the value `100' is a numeric constant, not an identifier.

Has a working memory element been created, too?

% print 3
([3])
% 

No! The preference is present, but no working memory element has been created yet. Working memory elements get created during elaboration as a result of preference addition. So, after elaborating once, we should see our acceptable preference converted into a working memory element:

% ela
[1]: [5]
Firing:
  implement*drive
  drive*reconsider
Retracting:
  implement*drive
  drive*reconsider
% print 3
([3] ^sensor-1 100)
% 

Now let's remove that preference, and verify that it's gone:

% pref -r 134699296
% pref 3 ^sensor-1
% 

The preference is gone; does the working memory element remain?

% print 3
([3] ^sensor-1 100)
% 

Yes. Again, working memory elements are created and destroyed during elaboration:

% ela
[1]: [5]
Firing:
  implement*drive
  drive*reconsider
Retracting:
  implement*drive
  drive*reconsider
% print 3
([3])
% 

At this point, the agent's input-link is in the same state as it was before we began tinkering with preferences.

Home