Welcome To Herbal

A High-Level Modeling Language for Intelligent Agents and Cognitive Models

(last updated 10-16-11)

Herbal: Frequently Asked Questions List

Frank E. Ritter: frank.ritter@psu.edu
Jong W. Kim: jongkim@psu.edu
Mark A. Cohen: mcohen@lhup.edu
Steven R. Haynes: shaynes@ist.psu.edu

Last updated: 11 november 2008
Created: April 2, 2007


Table of Contents

Section 0: Introduction

Section 1: General Questions

(G1) Where can I get a copy of the Herbal FAQ?

(G2) What is Herbal?

(G3) Where can I get more information about Herbal?

(G4) What does "Herbal" stand for?

(G5) What do I need to run Herbal?

(G6) Where can I obtain a copy of Herbal?

(G7) Who uses Herbal for what?

(G8) How can I learn Herbal?

(G9) Is Herbal the right tool for me?

(G10) Is there any support documentation available for Herbal?

(G11) How can I find out what bugs are outstanding in Herbal?

(G12) How does Herbal currently stand as a Psychology theory?

(G13) Can Herbal be embedded?

(G14) Resources for teaching Herbal

(G15) How do I share Herbal models?

Section 2: Technological/Terminology Questions

(T1) What is Herbal based on? (what technologies and programming languages and tools does it use?)

Section 3: Programming Questions

(P1) How can I make my life easier when programming in Herbal?

(P2) Are there any guidelines on how to name objects?

(P3) What are design patterns?

(P4) What are the design patterns in Herbal?

(P5) What's the general method for debugging a Herbal program?

(P6) How can I find out which productions are responsible for a WME?

(P7) How do I write fast code?

(P8) How does one create a 'wait' operator in Herbal

(P9) How does one mess with the WMEs on the IO link?

(P10) How can I find out about a programming problem not addressed here?

(P11) Why doesn't Herbal/Soar hook up to dTank?

(P12) How can I find an object that has attributes and values?

(P13) How to represent waypoints and partial results in hierarchical goal stacks?

Section 4: Downloadable Models

(DM1) Sally: A hungry/thirsty model

(DM2) Vacuum Cleaner model

(DM3) dTank: A competitive environment for distributed agents

Section 5: Advanced Programming Tips

(APT1) Are there any reserved words in Herbal?

(APT2) How can I access Tcl, Unix, and Java variables?

(APT3) How can I access Herbal objects?

(APT4) How can I trace state changes?

(APT5) How do I use SML (Soar Markup Language)?

(APT6) How can I get in trouble?

Section 6: Miscellaneous Resources

(M1) Comparisons between Soar and Herbal

(M2) Herbal memorabilia

(M3) What is TAQL?


Section 0: Introduction


This is the introduction to a list of frequently asked questions (FAQ) about Herbal with answers. The FAQ is provided as a guide for finding out more about Herbal. It is intended for use by all levels of people interested in Herbal, from novices to experts. With this in mind, the questions are essentially divided into six parts as follows:

  • Section 1 (General Questions): This section deals with general details about Herbal.
  • Section 2 (Technological Issues): This section examines technological issues in Herbal.
  • Section 3 (Programming Questions): This section looks at some issues related to programming using Herbal.
  • Section 4 (Downloadable Models): The valuable information on several major models are presented in this section.
  • Section 5 (Advanced Programming Tips): Advanced programming tips that are useful are provided to help developers.
  • Section 6 (Miscellaneous Resources): Other resources associated with an understanding of Herbal are presented in this section.

Questions in the first section have their numbers prefixed by the letter G (for General); those in the second section are prefixed by the letter T (for Technological); those in the third section are prefixed by the letter P (for Programming); those in the fourth section are prefixed by the letter DM (for Downloadable Models); those in the fifth section are prefixed by the letter APT (for Advanced Programming Tips); and, finally, those in the sixth section are prefixed by the letter M (Miscellaneous Resources). It also attempts to serve as a repository of the canonical "best" answers to these questions. So, if you know of a better answer or can suggest improvements, please feel free to make suggestions.

This FAQ is updated and posted on a variable schedule. We solicit answers where we can see common and important questions. Full instructions for getting the current version of the FAQ are given in question (G0). In order to make it easier to spot what has changed since last time around, new and significantly changed items have often been tagged with the "new" icon on each major reference.

Suggestions for new questions, answers, re-phrasing, deletions etc., are all welcomed. Please include the word "Herbal FAQ" in the subject of your e-mail correspondence.

This FAQ is not just our work, but includes answers from members of the cognitive modeling community, past and present. The development of Herbal and of this FAQ are supported by the Office of Naval Research (ONR).

Frank E. Ritter (frank.ritter@psu.edu)
Jong W. Kim (jongkim@psu.edu)
Mark A. Cohen (mcohen@lhup.edu)
Steven R. Haynes (shaynes@ist.psu.edu)

Back to Table of Contents


Section 1: General Questions


(G1) Where can I get a copy of the Herbal FAQ?

If you are reading a plain text version of this FAQ, there is also an html version available, via either of the following URL:


acs.ist.psu.edu/Herbal/herbal-faq/

that you can access using any Web browser.

If you find that material here is out of date or does not include your favorite paper or author, please let us know.

Back to Table of Contents


(G2) What is Herbal?

Herbal is a high-level language for behavior representation. It is an integrated development tool that supports modeling of human behavior and intelligent agents. Herbal is funded by the Office of Naval Research and was developed by the Applied Cognitive Science Laboratory at Penn State.

Herbal operates as an Eclipse plug-in. To support both novice and expert users, Herbal allows modelers to create models by either using a graphical editor or by directly editing an XML-based high-level language.

The Herbal environment currently supports creating models for the Soar Cognitive Architecture and the Jess Expert System Shell. If you are a modeler using Soar or Jess, it may be worthwhile for you to try out Herbal.

A theory laden language that attempts to support the high level constructs of behavior representation and hide the low level representations. In hiding the low level, it is also able to apply the low level behavior representations more routinely, accurately, and regularly. It uses 'lightweight operators'.

Back to Table of Contents


(G3) Where can I get more information about Herbal?

Tutorial

You can download the most recent tutorial from here: acs.ist.psu.edu/herbal/tutorials.html

Journal Articles, Conference Proceedings, Technical Reports

Recent and forthcoming publications related to Herbal include (chronologically ordered):

Ritter, F. E., Kase, S. E., Bhandarkar, D., Lewis, B., & Cohen, M. A. (2007). dTank updated: Exploring moderated behavior in a light-weight synthetic environment. In Proceedings of the 16th Conference on Behavior Representation in Modeling and Simulation, 51-60. Norfolk, VA.

Ritter, F. E., Haynes, S. R., Cohen, M. A., Howes, A., John, B. E., Best, B., Lebiere, C., Jones, R. M., Lewis, R. L., St. Amant, R., McBride, S. P., Urbas, L., Leuchter, S., & Vera, A. (2006). High-level behavior representation languages revisited. In Proceedings of the Seventh International Conference on Cognitive Modeling, 404-407. Trieste, Italy: Edizioni Goliardiche.

Ritter, F. E., Morgan, G. P., Stevenson, W. E., & Cohen, M. A. (2005). A tutorial on Herbal: A high-level language and development environment based on Protege for developing cognitive models in Soar. In Proceedings of the 14th Conference on Behavior Representation in Modeling and Simulation, Universal City, CA.

Morgan, G. P., Haynes, S. R., Ritter, F. E. & Cohen, M. A. (2005). Increasing efficiency of the development of user models. In Proceedings of the 2005 IEEE Systems and Information Engineering Design Symposium.

Cohen, M. A., Ritter, F. E., & Haynes, S. R. (2005). Herbal: A high-level language and development environment for developing cognitive models in Soar. In Proceedings of the 14th Behavior Representation in Modeling and Simulation, 133-140. University City, CA.

Cohen, M. A., Ritter, F. E., & Haynes, S. R. (2004). An Introduction to Herbal. In Proceedings of the XXIV Soar Workshop, 75-77. University of Michigan: The Soar Group.

Web Site

There is a official web site available that provides information about Herbal: acs.ist.psu.edu/Herbal

Back to Table of Contents


(G4) What does "Herbal" stand for?

Originally, Herbal indicated "HRBL" (High-level Representation of Behavior Language). Now, Herbal is not considered as an acronym but a name for a high-level behavior representation language.

Back to Table of Contents


(G5) What do I need to run Herbal?

Herbal was developed in the Eclipse Integrated Development Environment that is written in Java. Eclipse supports plug-in based toolkit construction. Thus, you need to install Eclipse to your machine, and then download and install Herbal. Here are procedures to run Herbal on your own machine.

  1. Download and install Eclipse.
  2. Download Herbal to your local drive. The extension of the downloaded file name should be ".jar". If not, please, correct it.
  3. Copy and paste the downloaded ".jar" file of Herbal to the folder named "plugins" under the Eclipse folder (e.g., ~/Eclipse/plugins).
  4. Restart Eclipse. If you see "Herbal" on the Eclipse menu bar, the installation was successful.
  5. Go to the "Herbal" menu item and select "show GUI editor". You will see the welcome page of Herbal. You are now ready to use Herbal.
  6. Herbal produces Soar and Jess models, so you will need one of these to run the resulting models written in Herbal.


(G6) Where can I obtain a copy of Herbal?

You can simply go to the ACS Lab's Herbal website. Click here: acs.ist.psu.edu/herbal.

Back to Table of Contents


(G7) Who uses Herbal for what?

Herbal is and can be used by:

  • Cognitive scientists: To model human behavior and understand cognitive processes
  • Human factors engineers and psychologists: To model human performance and human interaction with a system
  • AI or other engineering researchers: To model intelligent agents and implement intelligent systems (e.g., opponent simulation for the military or operator modeling of unmanned aerial vehicles).

Pennsylvania State University

The Herbal work at Penn State involves using Soar models as a way to test theories of learning, creating a high level language for modeling, and improving human-computer interaction. For more information, please contact Frank Ritter (frank.ritter@psu.edu).

Lock Haven University

Mark Cohen develops and teaches Herbal in his classes at Lock Haven University. For more information, please contact Mark Cohen (mcohen@lhup.edu).

Pace University

Paul Benjamin uses Herbal to work with Soar models to interact with large systems.

Back to Table of Contents


(G8) How can I learn Herbal?

In order to help people learn, there is a tutorial available. Please visit the Herbal site: acs.ist.psu.edu/herbal. You need to read the tutorial and try out the example models such as HungryThirsty model, Vacuum Cleaner model, and dTank model.

Using Herbal requires some Soar and Jess knowledge, so concurrent study of these languages will be necessary.

Back to Table of Contents


(G9) Is Herbal the right tool for me?

Herbal is an exploration in how to create a high level behavior representation language. It is an exploration and not a well tested language at this point. While another site (or two) have found it useful, it will not be useful for everyone, or even a broad range of users yet. If you have models that you want to run in Jess or in Soar where you want a higher level language, it may be useful enough to try now. If you want to play with a model compiler, it will be very interesting. If you want to make the language even higher level, you will find it useful. If you want to compare Soar and Jess, you will find Herbal useful. If you want to teach modeling, the associated simulations (e.g., Vacuum cleaner and dTank) may make Herbal very useful as an educational tool.

Herbal is not likely to be as easy to use as systems that use programming by demonstration (e.g., ACT-Simple). It is not likely to be as fast to use as Jack or pure agent architectures.

If you want explainable code and code that can explain itself, that is what Herbal is designed for.

If you want bullet proof code, or like to write your rules by hand (e.g., an old assembler programmer), you won't like it. In the first case, come back in the year.

Back to Table of Contents


(G10) Is there any support documentation available for Herbal?

As mentioned in the section G3, there are a tutorial, this FAQ. Other documents available for Herbal users include this FAQ, the papers referenced, and the existing models.

Back to Table of Contents


(G11) How can I find out what bugs are outstanding in Herbal?

Features

Currently, Herbal does not yet support a complete set of high level language constructs (e.g., loops).

Bugs

There are currently no outstanding bugs in Herbal. If you have a feature you would like to see in Herbal, or find a bug, please notify Mark Cohen.

Back to Table of Contents


(G12) How does Herbal currently stand as a psychology theory?

Herbal has not been well evaluated as a psychology theory. In that it compiles into Soar code, it should inherit some of the support for a psychology theory that Soar will bring. In that it compiles into Jess code, it appears to be either an expert system type of psychology theory or not to be a psychology theory at all. This is an unusual position to be in.

Herbal does provide strong control about how the constructs in behavior are represented at a fine level. That is, the compiler ensures that every operator is implemented the same way. So, it promises that if there are systematic differences and deviations, it can modify how these constructs are implemented to match performance.

Back to Table of Contents


(G13) Can Herbal be embedded?

Mark Cohen wrote (June 5, 2007):

The answer to that question is yes. The code produced by Herbal is plain old Soar and plain old Jess, and can be embedded in any environment that uses Soar or Jess (e.g., the dTank, Vacuum Cleaner, and Baseball environments).

Back to Table of Contents


(G14) Resources for teaching Herbal

Herbal has been and is being taught as a component of programming classes at Penn State University and Lock Haven University. Herbal has also been used to teach Soar at a conference and in the classroom.

More resources can be found at Ritter's class website. Also, please contact Frank Ritter, Mark Cohen, or Steve Haynes.

Back to Table of Contents


(G15) How do I share Herbal models?

Answer from Mark Cohen, 27 Mar 2007

Each Herbal model consists of a group of XML files that are stored in the "Model" subfolder in the Project's folder. Models can be shared by copying these XML files into the "Model" folder of a different model.

Once the files are copied, their contents will be immediately available in the other model. You just need to be sure to copy all of the XML files because there are dependencies between them that have to be maintained.

Thus to share, either pass these files, or pass a tar of these files and then untar-[FER].

Back to Table of Contents


Section 2: Technological Issues


(T1) What is Herbal based on? (what technologies and programming languages and tools does it use?)

Herbal is a high level language that is defined by its manual and by the source code compiler. The GUI is a plugin to Eclipse. The language is represented in XML (usually but not exclusively in the Eclipse editor plugin). The compiler is written in XSLT, and compiles the agent models into Soar productions or Jess systems (mostly but not exclusively rules). Each of these have some Java extensions to help the models hook up to simulations; these Java extensions are typically put in the Herbal model's preamble or postamble.

Back to Table of Contents


Section 3: Programming Questions


(P1) How can I make my life easier when programming in Herbal?

There are a number of ways to make your life easier when programming in Herbal. First of all, you need to learn how to use Eclipse. Please visit the Eclipse documentation site, you can get more information about it. In addition, it is helpful for you to learn Soar and Jess.

Also, understanding the PSCM (Problem Space Computational Model) helps you to do modeling with Herbal, because Herbal is based on the concepts of the PSCM. The PSCM is an idea that revolves around the commitment in Soar using problem spaces as the model for all symbolic goal-oriented computation. The PSCM is based on the primitive acts that are performed using problem spaces to achieve a goal. These primitive actions are based on the fundamental object types within Soar (i.e., goals, problem spaces, states, and operators).

Back to Table of Contents


(P2) Is there any guidance on how to name objects?

Objects can generally be named what ever you wish. Terse names and words reserved in Soar (e.g., operator, state) and words reserved in Jess (e.g., Markus, COhenus) can be used because the compiler either maps them onto the correct construct or wraps them with delimiters, but you should avoid this as it will make the resulting system more difficult to understand. (Who wants to have a model that has an operator named State modify the operator State before passing up results to Impasse-state operator being applied to the Restart-Soar state?)

Domain objects are thus often best named as in the domain, for example, ball, table, menu. The operators and states do not need 'operator' or 'state' in their name. Including 'Operator-' may be useful in early work, but eventually you will find that it is clear enough or clearer to leave the label out. Herbal appears to allow slightly longer names conveniently than when coding by hand. Attributes and values are best represented by the objects.

Back to Table of Contents


(P3) What are design patterns?

Design patterns are common solutions to common problems in design. In software, they are common algorithms to common manipulation of problems. Herbal attempts to support them more directly than other cognitive architectures. To this end, some are included in the Herbal language (e.g., objects in the problem space computational model as first class objects), and others are noted. Here are some example design patterns that we have seen so far.

Long Term Memory

Problem: How to keep information in long term declarative memory

Design pattern:

  1. Keep information on the state. This approximates the knowledge level (Newell), but can fill up the state. This works only as a simple approximation.
  2. Keep as a learned rule that retrieves the information. This is called data-chunking in Soar.

How to compare two numbers

Problem: Trying to decide which of two numbers are greater

Design pattern:

  1. Keep a set of comparisons (e.g., 1 < 2, 1< 3, 1< 4 ..... 2< 3, 2 < 4 ....), retrieve or use these facts when needed.
  2. Count them. If the number is a set, then remove one, and when there is a set with 0, if the other set is 0, they are equal, otherwise, the set with elements is more.
  3. This can also be done with decrementing a number. (both b and c could lead to learning)

Learning and knowing a categorization

Problem: Learning how to classify objects

Design pattern: SCA algorithm (for more information see the section of G13 in the Soar FAQ)

Interlocking with the world

Problem: Knowing when an action has been completed in the world and it's worth checking for changes

Design pattern: Give the action a unique timestamp and wait for the action on the Input link to marked as done, or for the timestamp to come back.

Avoiding small changes in an input number leading to changes in working memory

Problem: Changes in an input number, particularly as a rational number, may lead to rules firing and refiring as it changes, but only by a small and not important amount.

Design pattern: Map the number by range into a symbol. This reduces the changes to important ones.

Back to Table of Contents


(P4) What are the design patterns in Herbal?

We attempt here to enumerate the design patterns in Herbal. Generally, this list attempts to go from low level to high level.

Random choice-attribute

How to randomly set an attribute's from a range or from a set.

Use the random value from the Herbal menu when changing an attribute.

Random choice-operator

How to randomly choose an operator from a set.

Propose multiple indifferent (=) operators. The resulting Soar and Jess model will choose one randomly between them based on Soar's operator indifferent setting.

Random choice-goal

How to randomly choose a goal.

The Problem Space Computational Model does not support choosing goals, so this will cause problems trying to do. Generally, where you are thinking goals, think operators, adjust your mental model appropriately, and carry on.

Delete working memory

How to remove a value from working memory.

You cannot remove certain values from working memory in Soar, such as the skeleton of the goal stack and the Input link of the IO structures -- doing so has often caused Soar to crash. But, removing typical and allowable structures is done by an edit action clause in Herbal for both Soar and Jess models, and the value is either removed or replaced.

Multiple value for an attribute

How to set an attribute to have multiple values. For example, a list of colors of an object or a list of sides.

Soar (and thus now to some extent the PSCM) has found that having multiple attributes for a value can make systems slow down, and can cause theoretical problems as well. Herbal and Soar still allows this with a multiple value preference for simple attribute values (&).

There are at least two better ways to do this in the PSCM, Soar, and Herbal. The first is to name each of the objects that would be on the list. For example, if you wanted sides of a car, instead, use top, bottom, left, right, etc. The second way is to have a linked list. For example, to have ^sides f1 (f1 ^name top ^next f2) (f2 ^name bottom ^next f3) and so on.

Trace of model

How to trace the running of a model, in particular to trace everything and to trace objects and changes of interest.

This can be done by inserting trace material into the preamble. Two Soar commands of interest include the ability to set the watch level with a watch command, and the other is to insert a rule (perhaps written by hand) to print out states and objects that match the rule. Finally, this can also be done by hooking up to the Soar debugger, which has different strengths and weaknesses.

Wait operator

Note: This is covered in the section of P8 in more detail because it is very common.

Counter

How to count actions.

Create a variable and store it on a state or an operator. Create a clause that will add 1 to that value, and add this clause to every operator that should be counted or counting.

Counter - counting WMEs

How to count objects on a state or object.

[needs to be taken from the Soar FAQ].

Sequence operators

Many tasks will have a sequence of operators that need to be performed. They may, for example, have to do IO and can't be combined into a single operator. Thus, they need to be sequenced.

They can be given different preferences in Herbal, and in the future Herbal needs to support these more directly.

Iterate

How to do a task a fixed number of times.

This would combine the counter design pattern and the sequence operator design pattern.

Walk a map

How to explore a map.

We have seen two ways to do this. One way moves to the upper left corner (or, any corner really), and then walks to an edge, turns, and repeats this until it hits the opposite corner. The other way is to spiral, which would be to keep a counter and move in progressively (N+1) sides until all the sides of the spiral were hitting sides.

Back to Table of Contents


(P5) What's the general method for debugging a Herbal program?

Sections 5 and 7 of the Herbal Tutorial describe in detail how to debug a model using Herbal.

Back to Table of Contents


(P6) How can I find out which Herbal constructs are responsible for the resulting code?

When you open up the Herbal source code you will see the operator structure, with comments separating each set of operator constructs. The preamble and postamble are separated from the main code and noted as such. The constructs within each operator will use the design rational information and the names used for the operators and attributes, so it should be relatively straightforward to see how the constructs lead to the resulting code.

Back to Table of Contents


(P7) How do I write fast code?

Please, refer to the Soar FAQ.

Back to Table of Contents


(P8) How does one create a 'wait' operator in Herbal?

Wait operators can be be created in Herbal by creating an operator with "worst" preference. This will cause the operator to be proposed and applied only when no other operators are viable; thus causing the model to "wait" until some other operator, with a higher preference, is proposed. Because this is done in Herbal, it will work in either Soar or Jess.

Back to Table of Contents


(P9) How does one mess with WMEs on the Soar IO link?

Please, refer to the Soar FAQ

Back to Table of Contents


(P10) How can I find out about a programming problem not addressed here?

There are several places to turn to, listed here in order that you should consider them.

  1. The Herbal tutorial and other documentations listed in G2 may provide general help, and you should consult them if possible before trying the mailing lists.
  2. You can consult with Frank Ritter or Mark Cohen.

Back to Table of Contents


(P11) Why doesn't Herbal/Soar hook up to dTank?

Soar (version 8.6.1 or later) supports bridging an external environment (e.g., a Vacuum Cleaner or a dTank environment) written in Java to a Soar model (e.g., a Vacuum Cleaner Soar model or a dTank Soar model built in Herbal). This is called Soar/Java runtime bridge. If you look inside the Soar folder, you can find library files. If you copy the library files into a specific folder (e.g., VacuumCleaner or dTank), you can run the Soar models interacting with an external environment.

Here are the library files that you need.

For Windows machines
  • soar-library\ElementXML.dll
  • soar-library\Java_sml_ClientInterface.dll
  • soar-library\SoarKernelSML.dll
  • soar-library\sml.jar
For Macintosh machines
  • lib/libElementXML.0.0.0.dylib
  • lib/libElementXML.0.dylib
  • lib/libElementXML.dylib
  • lib/libJava_sml_ClientInterface.0.0.0.jnilib
  • lib/libJava_sml_ClientInterface.0.jnilib
  • lib/libJava_sml_ClientInterface.jnilib
  • lib/libSoarKernelSML.0.0.0.dylib
  • lib/libSoarKernelSML.0.dylib
  • lib/libSoarKernelSML.dylib
  • soar-library/sml.jar

Back to Table of Contents


(P12) How can I find an object that has attributes and values?

[Question from Ernst Bovenkamp, July 2000]:

I would like to know how I can find an object <object> that has attributes and values which are exactly equal to some other object <object1> and there can be only one <object> with these characteristics.

However, there is more than one <object>. Moreover, every object may have some, but not all, values equal to <object1>. Further I don't know how many attributes an object has, nor what its values should be. On top these objects are created in parallel which makes it difficult to attach a unique identification number to it because all objects are attached the same number in that case.

[Answer from Randy Jones]:

Since Soar does not have any explicit quantifiers, you usually have to use negation or double-negation "tricks" to get their effects. Note that, the double-negation would not work if you had it "standing alone". But, in the production I gave you, <object> gets bound to one object at a time by the condition: (<s> ^object <object>)

I tried testing with the following set of rules. See if they work for you (these are in Soar 8, so you have to add some parallel preferences if you are using Soar 7).

sp {elaborate*state*identical-to-key
   (state <s> ^key-object <object1>
                    ^object <object>)
   ## It is not the case that <object> has an attribute-value pair that
   ## <object1> does not have.
  -{ (<object> ^<att> <val>)
    -(<object1> ^<att> <val>) }
   ## It is not the case the <object1> has an attribute-value pair that
   ## <object> does not have.
  -{ (<object1> ^<att> <val>)
    -(<object> ^<att> <val>) }
-->
    (<s> ^identical-to-key <object>)
 }

sp {elaborate*state*key-object
   (state <s> ^superstate nil)
-->
   (<s> ^key-object <ob>)
   (<ob> ^a 1)
   (<ob> ^b 2)
   (<ob> ^c 3)
 }

sp {elaborate*state*object1
   (state <s> ^superstate nil)
-->
   (<s> ^object <ob>)
 }

sp {elaborate*state*object2
   (state <s> ^superstate nil)
-->
   (<s> ^object <ob>)
   (<ob> ^a 1)
 }

sp {elaborate*state*object3
   (state <s> ^superstate nil)
-->
   (<s> ^object <ob>)
   (<ob> ^a 1)
   (<ob> ^b 2)
   (<ob> ^c 3)
 }

sp {elaborate*state*object4
   (state <s> ^superstate nil)
-->
   (<s> ^object <ob>)
   (<ob> ^a 1)
   (<ob> ^b 2)
   (<ob> ^c 3)
   (<ob> ^d 4)
 }

sp {elaborate*state*object5
   (state <s> ^superstate nil)
-->
   (<s> ^object <ob>)
   (<ob> ^a 1)
   (<ob> ^b 2)
   (<ob> ^c 3)
 }

Back to Table of Contents


(P13) How to represent waypoints and partial results in hierarchical goal stacks?

Question from Randy Jones:

Suppose that you have a problem-space structure something along the following lines:

top-ps
   execute-mission
      racetrack
 

Inside the racetrack problem space, we want to set an O-supported flag (based on our current position) marking that the racetrack waypoint was achieved. In Soar 8, we can't put that flag on the racetrack state, because as soon as our position changes the whole racetrack state will get retracted (right?). So instead I put flag up on the top-ps state.

Now the problem is that I have to clean up after myself. I need to clean up that flag when the racetrack operator is gone. Is there an "approved" way to do this? Or has someone done this and developed a clean way?

One possibility I can think of is that I propose a clean-up-racetrack operator (in the execute-mission problem-space) that is worse than the racetrack operator (and conditional on the existence of the O-supported stuff I want to delete). This makes the clean-up-racetrack operator wait until racetrack is done to do its cleaning up. Is that the best way?

Answer from Scott Wallace (March 19, 2002):

Here is what I do to deal with this situation. I've been using it for a while now, and it seems to work.

First, I use this rule to create an augmentation on the top state that will hold the subgoal data.

sp {all*elaborate*sub-goal*data-head
   (state <s> ^superstate nil)
   -->
   (<s> ^sub-goal-data <gd>)}
 

Then, I use this rule to create a unique augmentation on each subgoal.

sp {all*elaborate*goal*gensym
   (state <s> ^top-state <ts>)
   -->
   (<s> ^unique-id <u>)
   (<u> ^symbol (make-constant-symbol))}
 

This rule copies and creates sub-structures on the top-state's sub-goal-data for each state in the current stack.

sp {all*elaborate*sub-goal*data
   (state <s> ^name <name> ^unique-id.symbol <sym>
                    ^top-state <ts>)
   (<ts> ^sub-goal-data <gd>)
   -->
   (<gd> ^<name> <n>)
   (<n> ^id <sym>)
   }
 

Finally, this rule removes stale sub-goal information:

sp {any*apply*remove*old*sub-goal*data
   (state <s> ^operator.name <name>
                    ^top-state <ts>)
   (<ts> ^sub-goal-data <gd>)
   (<gd> ^<ss> <ssa>)
   (<ssa> ^id <sym>)
  -{(state <somestate> ^unique-id <>)
    (<u> ^symbol <sym>)}
   -->
   (<gd> ^<ss> <ssa> -)}
 

This seems to work for me, basically I use it for a similar thing: I have an agent, and one of its low level operators is "wander". It wanders about trying to achieve its super goal. But for any given super goal. I want to make sure that I don't wander to the same place twice. So I store this information in the sub-goal-data. Then, when I've wandered to the right place, I pop up in the goal stack, this temporary data is blown away, and then I might select a new goal which again requires me to wander about, but this time I will have a clean slate.

Back to Table of Contents


Section 4: Downloadable Models


(DM1) Sally: A hungry/thirsty model

The hungry/thirsty model, named Sally, is based on the hungry/thirsty model in the Psychological Soar Tutorial. The model has a simple life. If Sally is hungry, she will eat. But it causes Sally to be thirsty, so Sally will drink. Drinking causes Sally to be hungry again. This cycle continues until Sally's life is ended by way of stopping her execution. You can easily create this model by following procedural steps specified in the Herbal tutorial.

Back to Table of Contents


(DM2) Vacuum Cleaner model

A vacuum cleaner agent environment was created by Mark Cohen and is available at the Herbal website. You can also easily create the model by following the Herbal tutorial. This environment is based on the vacuum cleaner world in one of the popular AI textbooks by Russell and Norvig entitled Artificial intelligence: A modern approach.

Back to Table of Contents


(DM3) dTank: A competitive environment for distributed agents

dTank is originally inspired by Tank-Soar that was developed by Mazin As-Sanie at the University of Michigan. dTank was developed to efficiently utilize the flexibility of Java graphics and networking. For example, dTank provides an agent architecture-neutral interface to the game server, so that humans and agents can interact within the same environment over the networking. It includes a basic-tank model, and Herbal includes a dTank model. You can get more information on dTank, at acs.ist.psu.edu/projects/dTank.

Currently, dTank version 4.0 is available at http://acs.ist.psu.edu/dTank/dtank3mar07/index.html.

Back to Table of Contents


Section 5: Advanced Programming Tips


(APT1) Are there any reserved words in Herbal?

If you are using the GUI editor, the programmer does not have to worry about reserved words in Herbal. However, if you are coding by hand using the Herbal XML language, all of the reserved words are documented in the XSL files that are included in the schema folder of each Herbal project.

Back to Table of Contents


(APT2) How can I access Tcl, Unix, Java variables?

soar_library and default_wme_depth, for example, are defined as global variables, and all Soar files can be obtained through relative path names from the file path. On the Mac this is a bit trickier, but doable as well. Check out the TSI source code for examples.

Unix environmental variables are also available through the "env" matrix of variables (e.g., $env(MANPATH). Advanced users can also set variables in their shells by hand or with init files.

You should keep in mind that the Tcl scoping of variables is non-intuitive (to us, at least, at times), and it is a common problem in setting up paths and installation flags.

This sort of problem is becoming a trend as its easy to overlook. All Soar global Tcl variables, such as $default, need to be defined with a Tcl "global" command when used in a script. When procedures call procedures that call scripts which call scripts ..., your variable scope will change!

If variables are not visible as you expect them to be, often the problem is that they are global but not declared in your function or file. Insert a 'global var_name' and often the variable will appear again.

Expanded from email between Tom Head (Tom_Head@anato.soar.cs.cmu.edu), Karen J. Coulter (kcoulter@eecs.umich.edu), and Aladin Akyurek (akyurek@bart.nl) on soar-bugs, Tue, 25 Mar 1997, and later email as well.

Back to Table of Contents


(APT3) How can I access Herbal objects?

Within the Herbal GUI, you can access other herbal objects through the menus. One of the useful results of using the GUI is that you can insert all appropriate elements and you can only insert appropriate elements. If you want to access the internals of the Herbal model as a Herbal internal code, open up the project files and look at the XML code that define the internal model. For information about how to program using Herbal's XML language please see the XML Programming Tutorial.

Back to Table of Contents


(APT4) How can I trace state changes?

State changes can be traced using either the Soar, Jess, or Herbal debugger. Please refer to sections 5 and 7 of the Herbal Tutorial for more details.

Back to Table of Contents


(APT5) How do I use SML (Soar Markup Language)?

Question from Michela De Vincentis (Nov. 21, 2005):

I need more information about the methods used in sml package (e.g., class kernel,or class agent, etc.). I'd like to know if there is a manual that explain how all the objects and the methods inside the classes work (Java).

Bob Marinier wrote (Nov. 21, 2005):

Unfortunately, there is no separate manual at this time. However, all of the available functions are thoroughly documented in the header files in SoarIO/ClientSML/include. While these are C++ headers, the Java methods are virtually identical (with the obvious substitutions, i.e. String instead of char *, etc). Some Java-specific issues are discussed in the SML FAQ.

Note: After installing Soar 8.6.1, you can find the "SML Quick Start Guide" under "Documentation" folder. Also, you can get brief information about "SML Quick Start Guide" in APT17.

Back to Table of Contents


(APT6) How can I get in trouble?

In eclipse, you can get in trouble if you include a space in the path for your workspace. Ritter thinks it is related to eclipse and not Herbal.

Back to Table of Contents


Section 6: Miscellaneous Resources


(M1) Comparisons between Soar and Herbal

Herbal is a high level language that uses directly the objects and constructs of the problem space computational model. These objects are not first class objects in Soar and Jess, and in these languages many of these constructs are implicitly implemented but not explicitly implemented. Herbal allows these constructs to be manipulated more directly and on a higher level.

Back to Table of Contents


(M2) Herbal memorabilia

[will be updated]

Back to Table of Contents


(M3) What is TAQL?

TAQL (Task AcQuisition Language) was a higher level programming language written for to work with Soar 5. The best citations for it that I [FER] know of are as follows:

Yost, G. R., & Newell, A. (1989). A problem space approach to expert system specification. Proceedings of the Eleventh International Joint Conference on Artificial Intelligence. 621-627.

Yost, G. R. (1993). Acquiring knowledge in Soar. IEEE Expert, 8(3), 26-34.

The TAQL compiler was written in Lisp. You would load TAQL into a running Lisp. You put in a file templates that were designed to do common problem space operations, such as create and implement an operator or a problem space. When these templates were loaded (or compiled) they would produce Soar 5 productions. These template-produced productions could be augmented with additional hand-written productions. It had a manual and a short tutorial. Gregg Yost using TAQL was probably the fastest that Soar code has ever been written.

There was also a mode in GNU Emacs to help write TAQL code, it would balance braces of various sorts and insert templates for you to fill out. This mode is written up in Ritter's PhD thesis. It showed that TAQL had a more complex syntax (by its grammar) than the C programming language had.

My belief about why TAQL is no longer with us is this: It was an initial pass at a necessary level in Soar. A successor is badly needed because TAQL was a good idea -- it was a higher level language so that users did not have to write Soar productions to generate behavior on the problem space level. It had several flaws, however.

The syntax was large. This could be because there is not a simple syntax that will do the job, or it could be because it was a first draft. This complex syntax made it slightly hard to use.

TAQL ran with learning off. Learning could be turned on, but things broke. I don't have access and I don't think a full analysis of how things broke was ever done.

TAQL was written in Lisp. When Soar moved to C and Tcl/Tk, TAQL had to be translated. Greg Yost graduated around this time, and it was not carried forward. It was a large project and was most naturally written in Lisp. It would be harder, but not at all impossible to write in Tcl.

Herbal uses some of the ideas in TAQL, the most notable idea of higher level constructs. The use of macros at Soar Tech can also be seen as a part of this approach.

Back to Table of Contents


End of Herbal FAQ