This guide was produced by Soar Technology, Inc.

Introduction

Any feedback or contributions appreciated. Please email bob.marinier@soartech.com

Perhaps the most common question I get asked by new Soar programmers is some variant of, "What is the right way to do X?" Most often there is no established consensus as there are different approaches each with different pros and cons.

This guide attempts to capture the most frequent questions and non-exhaustively list various possible approaches, along with some analysis of pros and cons when applicable. This analysis will be concerned with things like performance and flexibility, not cognitive plausibility.

There have been previous efforts at documenting Soar development patterns and there is some overlap between this guide and these previous efforts.  This guide focuses on a brain-dump and not with trying to unify previous attempts into a single guide. Other guides are definitely worth checking out. Here's a brief comparison:

Soar Design Dogma

• Very brief
• Focused on broad guidance (e.g., only do one action per operator)
• Most similar (and complementary) to the General guidance section of this guide. Definitely worth reading.

SoarTech's Behavior Engineering guide

• It is not currently publicly available, and would probably take considerable resources to get it to a level of quality and usefulness that SoarTech was comfortable releasing
• It appears to be written as a general (not Soar-specific) behavior pattern library
• It seems to be concerned with a different kind of pattern; e.g., "how to move with respect to a target". (There are some general patterns in there, too, but there's almost no overlap with what I'm presenting here.)
• There is very little Soar code or examples.
• It follows a format that is very terse: I don't think most people could write code from the information given.
• May be useful as advanced follow up materials for those looking for more information after going through this guide.

In short, the existing materials are related to what I'm trying to do here, but are not specifically focused on general Soar patterns, which is what I'm trying to present here.

Other random notes:

• This guide tries not to take a stance on two approaches to creating Soar models (New Goal System (NGS) and the Michigan approach). Rather, it tries to support both, noting the pros and cons of different approaches to problems that may be impacted by goal style. Of course, there is a section on how to approach concurrent goals.
• This guide mentions available tools when applicable (e.g., Tcl, Soar IDE, datamap, etc.).
• This guide is not specific to JSoar or CSoar – it should work on either, although if something comes up that is specific to one or the other, it will be noted.
• I have tried to provide lots of examples throughout. The examples in the guide should all load in Soar, but many of them will not actually execute as they are snippets of some hypothetical larger agent. As I have time, I will work my way through and add executable, downloadable examples where it makes sense. These executable examples will contain more code than the inline examples as necessary to make them run, but will be as close as possible to make the correspondence between them obvious. For simplicity, executable examples will be contained in a single file. Examples that require NGS will not include NGS, but rather will assume it is available to be sourced at some location.

Topics

• Background
  
  • Learning Soar
  • Tcl and Soar
  • NGS and Michigan style goals
  • Editors
  • Debuggers
  • Other resources
• General guidance
  
  • Goals vs. tasks: try to keep them separate
  • File names and directory structures
  • Test goal name in apply rules
  • Treat operators and goals like function calls
  • Avoid side effects in goals
  • Soar "tricks"
  • Common utility code
• Debugging guidance
  • I get questions all the time like, "How can I determine X in Soar?" And the answer is very often, "There's a command for that...didn't you memorize the manual?" Seriously though, here are some tips to help you debug your agents.
• constants
  • How do I do constants?
  • What about enums?
• generic processes
  
  • How do I create a generic operator or goal that I can use anywhere in the goal hierarchy?
• default values: Often useful for generic processes
  
  • How do I fill in default values when some other value is optional and thus might not be there?
• callbacks: Often useful for generic processes
  
  • How do I insert custom steps in a generic process? E.g., A shared goal for doing an smem query that does something user-defined with the result.
• binning data
  
  • How do I define numeric ranges for bins? What if I want to bin non-numeric data?
• foreach
  
  • How do I do an operation on every element of a set if I don't know how many there are? (e.g., map)
    • What if the operations are not independent (e.g., counting)?
  • Pros/cons: reactivity, parallel vs. sequential, multiple waves vs. single wave, interaction with other goals (e.g., worst pref w/NGS may never happen or cause large delays)
• aspects
  
  • How do I do any number of operations at some point in an algorithm if I don't know how many operations I want to do (e.g., it's context-dependent)?
• disappearing input (e.g., messages that only stay on the input-link for a limited time)
  • Copy data (e.g., deep-copy), give agent control over input, prioritize processing of input
• concurrent goals
  
  • How do I create an agent that can interleave work on multiple goals?
• controlling access to shared resources (e.g., smem/epmem or data structures that can't change during processing)
  • If I have multiple concurrent goals, how do I ensure that only one epmem/smem query happens at a time? (multiple queries are an error, and need to ensure can get results in time)