When issuing commands, the command name can be shortened so long as there is no ambiguity (e.g., pref instead of preferences). Arbitrary aliases may also be assigned using the alias command. Some of the more common shortcuts are listed with each command's synopsis under "Default Aliases".
Manually add an element to working memory.
add-wme id [^]attribute value [+]
| aw | add-wme |
| id | Must be an existing identifier. |
| ^ | Leading ^ on attribute is optional. |
| attribute | Attribute can be any Soar symbol. Use * to have Soar create a new identifier. |
| value | Value can be any soar symbol. Use * to have Soar create a new identifier. |
| + | If the optional preference is specified, its value must be + (acceptable). |
Manually add an element to working memory. add-wme is often used by an input function to update Soar's information about the state of the external world.
add-wme adds a new wme with the given id, attribute, value and optional preference. The given id must be an existing identifier. The attribute and value fields can be any Soar symbol. If * is given in the attribute or value field, Soar creates a new identifier (symbol) for that field. If the preference is given, it can only have the value + to indicate that an acceptable preference should be created for this wme.
Note that because the id must already exist in working memory, the WME that you are adding will be attached (directly or indirectly) to the top-level state. As with other WME's, any WME added via a call to add-wme will automatically be removed from working memory once it is no longer attached to the top-level state.
This example adds the attribute/value pair ^message-status received to the identifier (symbol) S1:
add-wme S1 ^message-status received
This example adds an attribute/value pair with an acceptable preference to the identifier (symbol) Z2. The attribute is message and the value is a unique identifier generated by Soar. Note that since the ^ is optional, it has been left off in this case.
add-wme Z2 message * +
Be careful how you use this command. It may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme nor will such wmes ever be removed thru Soar's garbage collection. Manually removing context/impasse wmes may have unexpected side effects.
Define a new alias, or command, using existing commands and arguments.
alias [name [cmd [args]]]
| a | alias |
This command defines new aliases by creating Soar procedures with the given name. The new procedure can then take an arbitrary number of arguments which are post-pended to the given definition and then that entire string is executed as a command. The definition must be a single command, multiple commands are not allowed. The alias procedure checks to see if the name already exists, and does not destroy existing procedures or aliases by the same name. Existing aliases can be removed by using the unalias command. With no arguments, alias returns the list of defined aliases. With only the name given, alias returns the current definition.
The alias wmes is defined as:
alias wmes print -i
If the user executes a command such as:
wmes {(* ^superstate nil)}... it is as if the user had typed this command:
print -i {(* ^superstate nil)}To check what a specific alias is defined as, you would type
alias wmes
Allocate additional 32 kilobyte blocks of memory for a specified memory pool without running Soar.
allocate [pool blocks]
Soar allocates blocks of memory for its memory pools as it is needed during a run (or during other actions like loading productions). Unfortunately, this behavior translates to an increased run time for the first run of a memory-intensive agent. To mitigate this, blocks can be allocated before a run by using this command.
Issuing the command with no parameters lists current pool usage, exactly like stats command's memory flag.
Issuing the command with part of a pool's name and a positive integer will allocate that many additional blocks for the specified pool. Only the first few letters of the pool's name are necessary. If more than one pool starts with the given letters, which pool will be chosen is unspecified.
Memory pool block size in this context is approximately 32 kilobytes, the exact size determined during agent initialization.
Store the input wmes in a file for reloading later.
capture-input --open filename [--flush] capture-input [--query] capture-input --close
| filename | Open filename and begin recording input. |
| -o, --open | Writes captured input to file overwriting any existing data. |
| -f, --flush | Writes input to file as soon as it is encountered instead of storing it in RAM and writing when capturing is turned off. |
| -q, --query | Returns open if input capturing is active or closed if capturing is not active. |
| -c, --close | Stop capturing input and close the file, writing captured input unless the flush option is given. |
Save agent commands issued from the input cycle function in a file for reloading later.
This command may be used to start and stop the recording of input function commands as created by an external simulation. Commands are recorded decision cycle by decision cycle. Use the command [CommandLineInterface#replay-input replay-input] to replay the sequence.
Note that this command seeds the random number generator and writes the seed to the capture file.
Change directory.
cd [directory]
| chdir | cd |
| directory | The directory to change to, can be relative or full path. |
Change the current working directory. If run with no arguments, returns to the directory that the command line interface was started in, often referred to as the home directory.
To move to the relative directory named ../home/soar/agents:
cd ../home/soar/agents
dirs home ls pushd popd source pwd
Specify format of the name to use for new chunks.
chunk-name-format [-sl] -p [prefix] chunk-name-format [-sl] -c [count]
| -s, --short | Use the short format for naming chunks |
| -l, --long | Use the long format for naming chunks (default) |
| -p, --prefix [p] | If given, use p as the prefix for naming chunks. Otherwise, return the current prefix. (defaults to chunk) |
| -c, --count [c] | If given, set the chunk counter for naming chunks to c. Otherwise, return the current value of the chunk counter. |
The short format for naming newly-created chunks is:
<prefix><chunknum>
The long (default) format for naming chunks is:
<prefix>-<chunknum>*<dc>*<impassetype>*<dcChunknum>
where:
Record all user-interface input and output to a file.
clog -[Ae] filename clog -a string clog [-cdoq]
| filename | Open filename and begin logging. |
| -c, --close, -o, --off, -d, --disable | Stop logging, close the file. |
| -a, --add string | Add the given string to the open log file. |
| -q, --query | Returns open if logging is active or closed if logging is not active. |
| -A, --append, -e, --existing | Opens existing log file named filename and logging is added at the end of the file. |
The clog command allows users to save all user-interface input and output to a file. When Soar is logging to a file, everything typed by the user and everything printed by Soar is written to the file (in addition to the screen).
Invoke clog with no arguments (or with -q) to query the current logging status. Pass a filename to start logging to that file (relative to the command line interface's home directory (see the home command)). Use the close option to stop logging.
To initiate logging and place the record in foo.log:
clog foo.log
To append log data to an existing foo.log file:
clog -A foo.log
To terminate logging and close the open log file:
clog -c
Does not log everything when structured output is selected.
Dump the printed output and results of a command to a file.
command-to-file [-a] filename command [args]
| -a, --append | Append if file exists. |
| filename | The file to log the results of the command to |
| command | The command to log |
| args | Arguments for command |
This command logs a single command. It is almost equivalent to opening a log using clog, running the command, then closing the log, the only difference is that input isn't recorded.
Running this command while a log is open is an error. There is currently not support for multiple logs in the command line interface, and this would be an instance of multiple logs.
This command echos output both to the screen and to a file, just like clog.
Set the level of detail used to print WMEs.
default-wme-depth [depth]
| set-default-depth | default-wme-depth |
| depth | A non-negative integer. |
The default-wme-depth command reflects the default depth used when working memory elements are printed (using the print). The default value is 1. When the command is issued with no arguments, default-wme-depth returns the current value of the default depth. When followed by an integer value, default-wme-depth sets the default depth to the specified value. This default depth can be overridden on any particular call to the print command by explicitly using the --depth flag, e.g. print --depth 10 args.
By default, the print command prints objects in working memory, not just the individual working memory element. To limit the output to individual working memory elements, the --internal flag must also be specified in the print command. Thus when the print depth is 0, by default Soar prints the entire object, which is the same behavior as when the print depth is 1. But if --internal is also specified, then a depth of 0 prints just the individual WME, while a depth of 1 prints all WMEs which share that same identifier. This is true when printing timetags, identifiers or WME patterns.
When the depth is greater than 1, the identifier links from the specified WME's will be followed, so that additional substructure is printed. For example, a depth of 2 means that the object specified by the identifier, wme-pattern, or timetag will be printed, along with all other objects whose identifiers appear as values of the first object. This may result in multiple copies of the same object being printed out. If --internal is also specified, then individuals WMEs and their timetags will be printed instead of the full objects.
List the directory stack.
dirs
This command lists the directory stack. Agents can move through a directory structure by pushing and popping directory names. The dirs command returns the stack.
The command pushd places a new "agent current directory" on top of the directory stack and changes to it. The command popd removes the directory at the top of the directory stack and changes to the previous directory which now appears at the top of the stack.
cd home ls pushd popd source pwd
Print a string to the current output device.
echo [--nonewline] [string]
| string | The string to print. |
| -n, --nonewline | Supress printing of the newline character |
This command echos the args to the current output stream. This is normally stdout but can be set to a variety of channels. If an arg is --nonewline then no newline is printed at the end of the printed strings. Otherwise a newline is printed after printing all the given args. Echo is the easiest way to add user comments or identification strings in a log file.
This example will add these comments to the screen and any open log file.
echo This is the first run with disks = 12
Set whether or not commands are echoed to other connected debuggers.
echo-commands [-yn]
| -n, --no | Do not echo commands. |
| -y, --yes | Do echo commands. |
Setting this on will echo typed commands to other connected debuggers. Otherwise, the output is displayed without the initiating command, and this can be confusing.
Move focus in an editor to this production.
edit-production production_name
| production_name | The name of the production to edit. |
If an editor (currently limited to Visual Soar) is open and connected to Soar, this command causes the editor to open the file containing this production and move the cursor to the start of the production. If there is no editor connected to Soar, the command does nothing. In order to connect Visual Soar to Soar, launch Visual Soar and choose Connect from the Soar Runtime menu. Then open the Visual Soar project that you're working on. At that point, you're set up and edit-production will start to work.
edit-production my*production*name
Delete Soar productions from production memory.
excise production_name excise options
| ex | excise |
| -a, --all | Remove all productions from memory and perform an init-soar command |
| -c, --chunks | Remove all chunks (learned productions) and justifications from memory |
| -d, --default | Remove all default productions (:default) from memory |
| -r, --rl | Excise Soar-RL rules |
| -t, --task | Remove chunks, justifications, and user productions from memory |
| -T, --templates | Excise Soar-RL templates |
| -u, --user | Remove all user productions (but not chunks or default rules) from memory |
| production_name | Remove the specific production with this name. |
This command removes productions from Soar's memory. The command must be called with either a specific production name or with a flag that indicates a particular group of productions to be removed. Using the flag -a or --all also causes an init-soar.
This command removes the production my*first*production and all chunks:
excise my*first*production --chunks
This removes all productions and does an [CommandLineInterface#init-soar init-soar]:
excise --all
Print information about chunk and justification backtraces.
explain-backtraces [options] [prod_name]
| eb | explain-backtraces |
| prod_name | List all conditions and grounds for the chunk or justification. |
| -c, --condition | Explain why condition number n is in the chunk or justification. |
| -f, --full | Print the full backtrace for the named production |
This command provides some interpretation of backtraces generated during chunking.
The two most useful variants are:
explain-backtraces prodname explain-backtraces -c n prodname
The first variant prints a numbered list of all the conditions for the named chunk or justification, and the ground which resulted in inclusion in the chunk/justification. A ground is a working memory element (WME) which was tested in the supergoal. Just knowing which WME was tested may be enough to explain why the chunk/justification exists. If not, the second variant, where n is the condition of interest, can be used to obtain a list of the productions which fired to obtain this condition in the chunk/justification (and the crucial WMEs tested along the way).
save-backtraces mode must be on when a chunk or justification is created or no explanation will be available. Calling explain-backtraces with no argument prints a list of all chunks and justifications for which backtracing information is available.
Use with no arguments to list all productions that can be "explained."
Examining the chunk chunk-65*d13*tie*2 generated in a water-jug task:
soar> explain-backtraces chunk-65*d13*tie*2
(sp chunk-65*d13*tie*2
(state <s2> ^name water-jug ^jug <n4> ^jug <n3>)
(state <s1> ^name water-jug ^desired <d1> ^operator <o1> + ^jug <n1>
^jug <n2>)
(<s2> ^desired <d1>)
(<o1> ^name pour ^into <n1> ^jug <n2>)
(<n1> ^volume 3 ^contents 0)
(<s1> ^problem-space <p1>)
(<p1> ^name water-jug)
(<n4> ^volume 3 ^contents 3)
(<n3> ^volume 5 ^contents 0)
(<n2> ^volume 5 ^contents 3)
-->
(<s3> ^operator <o1> -))
1 : (state <s2> ^name water-jug) Ground : (S3 ^name water-jug)
2 : (state <s1> ^name water-jug) Ground : (S5 ^name water-jug)
3 : (<s1> ^desired <d1>) Ground : (S5 ^desired D1)
4 : (<s2> ^desired <d1>) Ground : (S3 ^desired D1)
5 : (<s1> ^operator <o1> +) Ground : (S5 ^operator O18 +)
6 : (<o1> ^name pour) Ground : (O18 ^name pour)
7 : (<o1> ^into <n1>) Ground : (O18 ^into N3)
8 : (<n1> ^volume 3) Ground : (N3 ^volume 3)
9 : (<n1> ^contents 0) Ground : (N3 ^contents 0)
10 : (<s1> ^jug <n1>) Ground : (S5 ^jug N3)
11 : (<s1> ^problem-space <p1>) Ground : (S5 ^problem-space P3)
12 : (<p1> ^name water-jug) Ground : (P3 ^name water-jug)
13 : (<s2> ^jug <n4>) Ground : (S3 ^jug N1)
14 : (<n4> ^volume 3) Ground : (N1 ^volume 3)
15 : (<n4> ^contents 3) Ground : (N1 ^contents 3)
16 : (<s2> ^jug <n3>) Ground : (S3 ^jug N2)
17 : (<n3> ^volume 5) Ground : (N2 ^volume 5)
18 : (<n3> ^contents 0) Ground : (N2 ^contents 0)
19 : (<s1> ^jug <n2>) Ground : (S5 ^jug N4)
20 : (<n2> ^volume 5) Ground : (N4 ^volume 5)
21 : (<n2> ^contents 3) Ground : (N4 ^contents 3)
22 : (<o1> ^jug <n2>) Ground : (O18 ^jug N4)Further examining condition 21:
soar> explain-backtraces -c 21 chunk-65*d13*tie*2
Explanation of why condition (N4 ^contents 3) was included in chunk-65*d13*tie*2
Production chunk-64*d13*opnochange*1 matched
(N4 ^contents 3) which caused
production selection*select*failure-evaluation-becomes-reject-preference to match
(E3 ^symbolic-value failure) which caused
A result to be generated.Print the number of times each production has fired.
firing-counts [n] firing-counts production_name
| fc | firing-counts |
If given, an option can take one of two forms -- an integer or a production name:
| n | List the top n productions. If n is 0, only the productions which haven't fired are listed |
| production_name | Print how many times the production has fired |
The firing-counts command prints the number of times each production has fired; production names are given from most requently fired to least frequently fired. With no arguments, it lists all productions. If an integer argument, n, is given, only the top n productions are listed. If n is zero (0), only the productions that haven't fired at all are listed. If a production name is given as an argument, the firing count for that production is printed.
Note that firing counts are reset by a call to [CommandLineInterface#init-soar init-soar].
This example prints the 10 productions which have fired the most times along with their firing counts:
firing-counts 10
This example prints the firing counts of production my*first*production:
firing-counts my*first*production
Firing-counts are reset to zero after an [CommandLineInterface#init-soar init-soar].
NB: This command is slow, because the sorting takes time O(n*log n)
Print the WMEs in the goal dependency set for each goal.
gds-print
| gds_print | gds-print |
The Goal Dependency Set (GDS) is described in an appendix of the Soar manual. This command is a debugging command for examining the GDS for each goal in the stack. First it steps through all the working memory elements in the rete, looking for any that are included in any goal dependency set, and prints each one. Then it also lists each goal in the stack and prints the wmes in the goal dependency set for that particular goal. This command is useful when trying to determine why subgoals are disappearing unexpectedly: often something has changed in the goal dependency set, causing a subgoal to be regenerated prior to producing a result.
gds-print is horribly inefficient and should not generally be used except when something is going wrong and you need to examine the Goal Dependency Set.
Generate productions according to a specified pattern.
gp { production_body }The gp command defines a pattern used to generate and source a set of Soar productions. production_body is a single argument that looks almost identical to a standard Soar rule that would be used with the [CommandLineInterface#sp sp] command. Indeed, any syntax that is allowed in sp is also allowed in gp.
Patterns in gp are specified with sets of whitespace-seprated values in square brackets. Every combination of values across all square-bracketed value lists will be generated. Values with whitespaces can be used if wrapped in pipes. Characters can also be escaped with a backslash (so string literals with embedded pipes and spaces outside of string literals are both possible).
gp is primarily intended as an alternative to :template rules for reinforcement learning. :template rules generate new rules as patterns occur at run time. Unfortunately, this incurs a high run time cost. If all possible values are known in advance, then the rules can be generated using gp at source time, thus allowing code to run faster. gp is not appropriate when all possible values are not known or if the total number of possible rules is very large (and the system is likely to encounter only a small subset at run time). It is also possible to combine gp and :template (e.g., if some of the values are known and not others). This should reduce the run time cost of :template.
There is nothing that actually restricts gp to being used for RL, although for non-RL rules, a disjunction list (using << and >>) is better where it can be used. More esoteric uses may include multiple bracketed value lists inside a disjunction list, or even variables in bracketed value lists.
Each rule generated by gp has *integer appended to its name (where integer is some incrementing number).
Template version of rule:
sp {water-jug*fill
:template
(state <s1> ^name water-jug ^operator <op> +
^jug <j1> <j2>)
(<op> ^name fill ^fill-jug.volume <fvol>)
(<j1> ^volume 3 ^contents <c1>)
(<j2> ^volume 5 ^contents <c2>)
-->
(<s1> ^operator <op> = 0)
}gp version of rule (generates 144 rules):
gp {water-jug*fill
(state <s1> ^name water-jug ^operator <op> +
^jug <j1> <j2>)
(<op> ^name fill ^fill-jug.volume [3 5])
(<j1> ^volume 3 ^contents [0 1 2 3])
(<j2> ^volume 5 ^contents [0 1 2 3 4 5])
-->
(<s1> ^operator <op> = 0)
}Esoteric example (generates 24 rules):
gp {strange-example
(state <s1> ^<< [att1 att2] [att3 att4] >> [ val |another val| |strange val\|| ])
-->
(<s1> ^foo [bar <bar>])
}testgp.soar contains many more examples.
Set the upper-limit to the number of productions generated by the gp command.
gp-max [value]
| value | Maximum number of productions to produce |
gp-max is used to limit the number of productions produced by a gp production. It is easy to write a gp production that has a combinatorial explosion and hangs for a long time while those productions are added to memory. The gp-max command bounds this. Use without an argument to query the current value.
gp-max 1000
gp productions that produce more than 1000 productions will stop producing them when 1000 are made and return an error.
Provide formatted usage information about Soar commands.
help [command_name]
| ? | help |
| h | help |
| man | help |
This command prints formatted help for the given command name. Issue alone to see what topics have help available.
Controls indifferent preference arbitration.
indifferent-selection indifferent-selection [-s] indifferent-selection [-bgfxl] indifferent-selection [-et] [value] indifferent-selection [-p] parameter [reduction_policy] indifferent-selection [-r] parameter reduction_policy [reduction_rate] indifferent-selection [-a] [setting]
| inds | indifferent-selection |
| -s, --stats | Summary of settings |
| policy | Set exploration policy |
| parameter [value] | Get/Set exploration policy parameters (if value not given, returns the current value) |
| parameter [reduction_policy] | Get/Set exploration policy parameter reduction policy (if policy not given, returns the current) |
| parameter reduction_policy [reduction_rate] | Get/Set exploration policy parameter reduction rate for a policy (if rate not give, returns the current) |
| -a, --auto-reduce [on,off] | Get/Set auto-reduction setting (if setting not provided, returns the current) |
The indifferent-selection command allows the user to set options relating to selection between operator proposals that are mutually indifferent in preference memory.
The primary option is the exploration policy (each is covered below). When Soar starts, softmax is the default policy. The first time Soar-RL is enabled, the architecture automatically changes the policy to epsilon-greedy and issues a message to the trace.
Some policies have parameters to temper behavior. The indifferent-selection command provides basic facilities to automatically reduce these parameters exponentially and linearly each decision cycle by a fixed rate. In addition to setting these policies/rates, the auto-reduce option enables the automatic reduction system (disabled by default), for which the Soar decision cycle incurs a small performance cost.
| -b, --boltzmann | Tempered softmax (uses temperature) |
| -g, --epsilon-greedy | Tempered greedy (uses epsilon) |
| -x, --softmax | Random, biased by numeric indifferent values (if a non-positive value is encountered, resorts to a uniform random selection) |
| -f, --first | Deterministic, first indifferent preference is selected |
| -l, --last | Deterministic, last indifferent preference is selected |
| Parameter Name | Acceptable Values | Default Value |
| -e, --epsilon | [0, 1] | 0.1 |
| -t, --temperature | (0, inf) | 25 |
| Policy Name | Valid Rates | Default Rate |
| exponential default | [0, 1] | 1 |
| linear | [0, inf] | 0 |
Empties working memory and resets run-time statistics.
init-soar
| init | init-soar |
| is | init-soar |
The init-soar command initializes Soar. It removes all elements from working memory, wiping out the goal stack, and resets all runtime statistics. The firing counts for all productions are reset to zero. The init-soar command allows a Soar program that has been halted to be reset and start its execution from the beginning.
init-soar does not remove any productions from production memory; to do this, use the excise command. Note however, that all justifications will be removed because they will no longer be supported.
Print information about the Soar symbol table.
internal-symbols
The internal-symbols command prints information about the Soar symbol table. Such information is typically only useful for users attempting to debug Soar by locating memory leaks or examining I/O structure.
soar> internal-symbols --- Symbolic Constants: --- operator accept evaluate-object problem-space sqrt interrupt mod goal io (...additional symbols deleted for brevity...) --- Integer Constants: --- --- Floating-Point Constants: --- --- Identifiers: --- --- Variables: --- <o> <sso> <to> <ss> <ts> <so> <sss>
Set the parameters for chunking, Soar's learning mechanism.
learn [-l] learn [-d|E|o] learn [-eabnN]
| l | learn |
| -e, --enable, --on | Turn chunking on. Can be modified by -a or -b. |
| -d, --disable, --off | Turn all chunking off. (default) |
| -E, --except | Learning is on, except as specified by RHS dont-learn actions. |
| -o, --only | Chunking is on only as specified by RHS force-learn actions. |
| -l, --list | Prints listings of dont-learn and force-learn states. |
| -a, --all-levels | Build chunks whenever a subgoal returns a result. Learning must be enabled. |
| -b, --bottom-up | Build chunks only for subgoals that have not yet had any subgoals with chunks built. Learning must be enabled. |
| -n, --enable-through-local-negations | Build chunks when local negation encountered in backtrace. (default) |
| -N, --disable-through-local-negations | Do not build chunks when local negation encountered in backtrace. |
The learn command controls the parameters for chunking (Soar's learning mechanism). With no arguments, this command prints out the current learning environment status. If arguments are provided, they will alter the learning environment as described in the options and arguments table. The watch command can be used to provide various levels of detail when productions are learned. Learning is disabled by default.
With the --on flag, chunking is on all the time. With the --except flag, chunking is on, but Soar will not create chunks for states that have had RHS dont-learn actions executed in them. With the --only flag, chunking is off, but Soar will create chunks for only those states that have had RHS force-learn actions executed in them. With the --off flag, chunking is off all the time.
The --only flag and its companion force-learn RHS action allow Soar developers to turn learning on in a particular problem space, so that they can focus on debugging the learning problems in that particular problem space without having to address the problems elsewhere in their programs at the same time. Similarly, the --except flag and its companion dont-learn RHS action allow developers to temporarily turn learning off for debugging purposes. These facilities are provided as debugging tools, and do not correspond to any theory of learning in Soar.
The --all-levels and --bottom-up flags are orthogonal to the --on, --except, --only, and --off flags, and so, may be used in combination with them. With bottom-up learning, chunks are learned only in states in which no subgoal has yet generated a chunk. In this mode, chunks are learned only for the "bottom" of the subgoal hierarchy and not the intermediate levels. With experience, the subgoals at the bottom will be replaced by the chunks, allowing higher level subgoals to be chunked.
Similarly, --enable-through-local-negations and --disable-though-local-negations are orthogonal to the rest of the learn options. These options control whether or not chunks can be created that are derived from rules that check for negated WMEs on the substate (local negations). Chunking through local negations can result in overgeneral chunks, but disabling this ability will reduce the number of chunks formed. The default is to enable chunking through local negations.
If chunking through local negations is disabled, to see when chunks are discarded (and why), set watch --learning print (see watch command).
Learning can be turned on or off at any point during a run.
To enable learning only at the lowest subgoal level:
learn -e b
To see all the force-learn and dont-learn states registered by RHS actions
learn -l
watch [CommandLineInterface#explain-backtraces explain-backtraces] save-backtraces
Load a shared library into the local client (for the purpose of, e.g., providing custom event handling).
load-library [library_name] [arguments]
| library_name | The root name of the library (without the .dll or .so extension; this is added for you depending on your platform). |
| arguments | Whatever arguments the library's initialization function is expecting, if any. |
Sometimes, a user will want to extend an existing environment. For example, the person may want to provide custom RHS functions, or register for print events for the purpose of logging trace information. If modifying the existing environment is cumbersome or impossible, then the user has two options: create a remote client that provides the functionality, or use load-library. Load-library creates extensions in the local client, making it orders of magnitude faster than a remote client.
To create a loadable library, the library must contain the following function:
#ifdef __cplusplus
extern "C" {
#endif
EXPORT char* sml_InitLibrary(Kernel* pKernel, int argc, char** argv) {
// Your code here
}
#ifdef __cplusplus
} // extern "C"
#endifThis function is called when load-library loads your library. It is responsible for any initialization that you want to take place (e.g. registering custom RHS functions, registering for events, etc).
The argc and argv arguments are intended to mirror the arguments that a standard SML client would get. Thus, the first argument is the name of the library, and the rest are whatever other arguments are provided. This is to make it easy to use the same codebase to create a loadable library or a standard remote SML client (e.g. when run as a standard client, just pass the arguments main gets into smlInitLibrary).
The return value of smlInitLibrary is for any error messages you want to return to the load-library call. If no error occurs, return a zero-length string.
An example library is provided in the Tools/TestExternalLibraryLib project. This example can also be compiled as a standard remote SML client. The Tools/TestExternalLibraryExe project tests loading the TestExternalLibraryLib library.
To load TestExternalLibraryLib:
load-library TestExternalLibraryLib
To load a library that takes arguments (say, a logger):
load-library my-logger -filename mylog.log
List the contents of the current working directory.
ls
| dir | ls |
List the contents of the working directory.
cd dirs home pushd popd source pwd
Prints information about partial matches and the match set.
matches [options] production_name matches [options] -[a|r]
| production_name | Print partial match information for the named production. |
| -n, --names, -c, --count | For the match set, print only the names of the productions that are about to fire or retract (the default). If printing partial matches for a production, just list the partial match counts. |
| -t, --timetags | Also print the timetags of the wmes at the first failing condition |
| -w, --wmes | Also print the full wmes, not just the timetags, at the first failing condition. |
| -a, --assertions | List only productions about to fire. |
| -r, --retractions | List only productions about to retract. |
The matches command prints a list of productions that have instantiations in the match set, i.e., those productions that will retract or fire in the next Propose or Apply phase. It also will print partial match information for a single, named production.
When printing the match set (i.e., no production name is specified), the default action prints only the names of the productions which are about to fire or retract. If there are multiple instantiations of a production, the total number of instantiations of that production is printed after the production name, unless --timetags or --wmes are specified, in which case each instantiation is printed on a separate line.
When printing the match set, the --assertions and --retractions arguments may be specified to restrict the output to print only the assertions or retractions.
In addition to printing the current match set, the matches command can be used to print information about partial matches for a named production. In this case, the conditions of the production are listed, each preceded by the number of currently active matches for that condition. If a condition is negated, it is preceded by a minus sign -. The pointer >>>> before a condition indicates that this is the first condition that failed to match.
When printing partial matches, the default action is to print only the counts of the number of WME's that match, and is a handy tool for determining which condition failed to match for a production that you thought should have fired. At levels --timetags and --wmes the matches command displays the WME's immediately after the first condition that failed to match--temporarily interrupting the printing of the production conditions themselves.
When printing partial match information, some of the matches displayed by this command may have already fired, depending on when in the execution cycle this command is called. To check for the matches that are about to fire, use the matches command without a named production.
In Soar 8, the execution cycle (decision cycle) is input, propose, decide, apply output; it no longer stops for user input after the decision phase when running by decision cycles (run -d 1). If a user wishes to print the match set immediately after the decision phase and before the apply phase, then the user must run Soar by phases (run -p 1).
This example prints the productions which are about to fire and the wmes that match the productions on their left-hand sides:
matches --assertions --wmes
This example prints the wme timetags for a single production.
matches -t my*first*production
Limit the number of chunks created during a decision cycle.
max-chunks [n]
| n | Maximum number of chunks allowed during a decision cycle. |
The max-chunks command is used to limit the maximum number of chunks that may be created during a decision cycle. The initial value of this variable is 50; allowable settings are any integer greater than 0.
The chunking process will end after max-chunks chunks have been created, even if there are more results that have not been backtraced through to create chunks, and Soar will proceed to the next phase. A warning message is printed to notify the user that the limit has been reached.
This limit is included in Soar to prevent getting stuck in an infinite loop during the chunking process. This could conceivably happen because newly-built chunks may match immediately and are fired immediately when this happens; this can in turn lead to additional chunks being formed, etc. If you see this warning, something is seriously wrong; Soar is unable to guarantee consistency of its internal structures. You should not continue execution of the Soar program in this situation; stop and determine whether your program needs to build more chunks or whether you've discovered a bug (in your program or in Soar itself).
Limit the maximum number of elaboration cycles in a given phase. Print a warning message if the limit is reached during a run.
max-elaborations [n]
| n | Maximum allowed elaboration cycles, must be a positive integer. |
This command sets and prints the maximum number of elaboration cycles allowed. If n is given, it must be a positive integer and is used to reset the number of allowed elaboration cycles. The default value is 100. max-elaborations with no arguments prints the current value.
max-elaborations controls the maximum number of elaborations allowed in a single decision cycle. The elaboration phase will end after max-elaboration cycles have completed, even if there are more productions eligible to fire or retract; and Soar will proceed to the next phase after a warning message is printed to notify the user. This limits the total number of cycles of parallel production firing but does not limit the total number of productions that can fire during elaboration.
This limit is included in Soar to prevent getting stuck in infinite loops (such as a production that repeatedly fires in one elaboration cycle and retracts in the next); if you see the warning message, it may be a signal that you have a bug your code. However some Soar programs are designed to require a large number of elaboration cycles, so rather than a bug, you may need to increase the value of max-elaborations.
max-elaborations is checked during both the Propose Phase and the Apply Phase. If Soar runs more than the max-elaborations limit in either of these phases, Soar proceeds to the next phase (either Decision or Output) even if quiescence has not been reached.
The command issued with no arguments, returns the max elaborations allowed:
max-elaborations
to set the maximum number of elaborations in one phase to 50:
max-elaborations 50
Get the number of bytes that when exceeded by an agent, will trigger the memory usage exceeded event.
max-memory-usage [n]
| n | Size of limit in bytes. |
The max-memory-usage command is used to trigger the memory usage exceeded event. The initial value of this is 100MB (100,000,000); allowable settings are any integer greater than 0. The code supporting this event is not enabled by default because the test can be computationally expensive and is needed only for specific embedded applications. Users may enable the test and event generation by uncommenting code in mem.cpp.
Using the command with no arguments displays the current limit.
Limit the maximum number of decision cycles that are executed without producing output when run is invoked with run-til-output args.
max-nil-output-cycles [n]
| n | Maximum number of consecutive output cycles allowed without producing output. Must be a positive integer. |
This command sets and prints the maximum number of nil output cycles (output cycles that put nothing on the output link) allowed when running using run-til-output (run --output). If n is not given, this command prints the current number of nil-output-cycles allowed. If n is given, it must be a positive integer and is used to reset the maximum number of allowed nil output cycles.
max-nil-output-cycles controls the maximum number of output cycles that generate no output allowed when a run --out command is issued. After this limit has been reached, Soar stops. The default initial setting of n is 15.
The command issued with no arguments, returns the max empty output cycles allowed:
max-nil-output-cycles
to set the maximum number of empty output cycles in one phase to 25:
max-nil-output-cycles 25
Print memory usage for partial matches.
memories [options] [number] memories production_name
| -c, --chunks | Print memory usage of chunks. |
| -d, --default | Print memory usage of default productions. |
| -j, --justifications | Print memory usage of justifications. |
| -u, --user | Print memory usage of user-defined productions. |
| production_name | Print memory usage for a specific production. |
| number | Number of productions to print, sorted by those that use the most memory. |
| -T, --template | Print memory usage of Soar-RL templates. |
The memories command prints out the internal memory usage for full and partial matches of production instantiations, with the productions using the most memory printed first. With no arguments, the memories command prints memory usage for all productions. If a production_name is specified, memory usage will be printed only for that production. If a positive integer number is given, only number productions will be printed: the number productions that use the most memory. Output may be restricted to print memory usage for particular types of productions using the command options.
Memory usage is recorded according to the tokens that are allocated in the rete network for the given production(s). This number is a function of the number of elements in working memory that match each production. Therefore, this command will not provide useful information at the beginning of a Soar run (when working memory is empty) and should be called in the middle (or at the end) of a Soar run.
The memories command is used to find the productions that are using the most memory and, therefore, may be taking the longest time to match (this is only a heuristic). By identifying these productions, you may be able to rewrite your program so that it will run more quickly. Note that memory usage is just a heuristic measure of the match time: A production might not use much memory relative to others but may still be time-consuming to match, and excising a production that uses a large number of tokens may not speed up your program, because the Rete matcher shares common structure among different productions.
As a rule of thumb, numbers less than 100 mean that the production is using a small amount of memory, numbers above 1000 mean that the production is using a large amount of memory, and numbers above 10,000 mean that the production is using a very large amount of memory.
Declare a symbol to be multi-attributed.
multi-attributes [symbol [n]]
| symbol | Any Soar attribute. |
| n | Integer greater than 1, estimate of degree of simultaneous values for attribute. |
This command declares the given symbol to be an attribute which can take on multiple values. The optional n is an integer (greater than 1) indicating an upper limit on the number of expected values that will appear for an attribute. If n is not specified, the value 10 is used for each declared multi-attribute. More informed values will tend to result in greater efficiency.
This command is used only to provide hints to the production condition reorderer so it can produce better condition orderings. Better orderings enable the rete network to run faster. This command has no effect on the actual contents of working memory and most users needn't use this at all.
Note that multi-attributes declarations must be made before productions are loaded into soar or this command will have no effect.
Declare the symbol "thing" to be an attribute likely to take more than 1 but no more than 4 values:
multi-attributes thing 4
Select method for combining numeric preferences.
numeric-indifferent-mode [-as]
| -a, --avg, --average | Use average mode (default). |
| -s, --sum | Use sum mode. |
The numeric-indifferent-mode command is used to select the method for combining numeric preferences. This command is only meaningful in indifferent-selection random mode.
The default procedure is --avg (average) which assigns a final value to an operator according to the rule:
The intended range of numeric-preference values for --avg mode is 0-100.
The other combination option --sum assigns a final value according to the rule:
Any real-numbered preference may be used in --sum mode.
Once a value has been computed for each operator, the next operator is selected probabilistically, with each candidate operator's chance weighted by its computed value.
Choose experimental variations of o-support.
o-support-mode [n]
| 3 | Mode 3 is the same as mode 2 except that operator elaborations (adding attributes to operators) now get i-support even though you have to test the operator to elaborate an operator. In cases where the rule mixes support types, support defaults to o-support (and a warning is printed). |
| 4 | Mode 4 is the default. It is the same as mode 3 except where a rule mixes support types, support defaults to i-support (and a warning is still printed). |
The o-support-mode command is used to control the way that o-support is determined for preferences. Only o-support modes 3 & 4 are valid (other modes require Soar 7, which is no longer supported). O-support mode 4 should be considered an improved version of mode 3. The default o-support mode is mode 4.
In o-support modes 3 & 4, support is given production by production; that is, all preferences generated by the RHS of a single instantiated production will have the same support. The difference between the two modes is in how they handle productions with both operator and non-operator augmentations on the RHS. For more information on o-support calculations, see the relevant appendix in the Soar manual.
Running o-support-mode with no arguments prints out the current o-support-mode.
Pop the current working directory off the stack and change to the next directory on the stack. Can be relative pathname or fully specified path.
popd
This command pops a directory off of the directory stack and changes to it. See the [CommandLineInterface#dirs dirs] command for an explanation of the directory stack.
cd dirs home ls pushd source pwd
Returns the port the kernel instance is listening on.
port
Predict the next selected operator
predict
The predict command determines, based upon current operator proposals, which operator will be chosen during the next decision phase. If predict determines an operator tie will be encountered, "tie" is returned. If predict determines no operator will be selected (state no-change), "none" is returned. If predict determines a conflict will arise during the decision phase, "conflict" is returned. If predict determines a constraint failure will occur, "constraint" is returned. Otherwise, predict will return the id of the operator to be chosen. If operator selection will require probabilistic selection, and no alterations to the probabilities are made between the call to predict and decision phase, predict will manipulate the random number generator to enforce its prediction.
Examine details about the preferences that support the specified identifier and attribute.
preferences [options] [identifier [attribute]]
| pref | preferences |
| -0, -n, --none | Print just the preferences themselves |
| -1, -N, --names | Print the preferences and the names of the productions that generated them |
| -2, -t, --timetags | Print the information for the --names option above plus the timetags of the wmes matched by the LHS of the indicated productions |
| -3, -w, --wmes | Print the information for the --timetags option above plus the entire WME matched on the LHS. |
| -o, --object | Print the support for all the WMEs that comprise the object (the specified identifier). |
| identifier | Must be an existing Soar object identifier. |
| attribute | Must be an existing attribute of the specified identifier. |
The preferences command prints all the preferences for the given object identifier and attribute. If identifier and attribute are not specified, they default to the current state and the current operator. The Soar syntax attribute carat (^) is optional when specifying the attribute. The optional arguments indicates the level of detail to print about each preference.
This command is useful for examining which candidate operators have been proposed and what relationships, if any, exist among them. If a preference has O-support, the string, :O will also be printed.
When only the identifier is specified on the commandline, if the identifier is a state, Soar uses the default attribute ^operator. If the identifier is not a state, Soar prints the support information for all WMEs whose value is the identifier.
When an identifier and the --object flag are specified, Soar prints the preferences / WME support for all WMEs comprising the specified identifier.
For the time being, [CommandLineInterface#numeric-indifferent-mode numeric-indifferent] preferences are listed under the heading `binary indifferents:`.
By default, using the --wmes option with a WME on the top state will only print the timetags. To change this, the kernel can be recompiled with DO_TOP_LEVEL_REF_CTS, but this has other consequences (see comments in kernel.h).
This example prints the preferences on (S1 ^operator) and the production names which created the preferences:
soar> preferences S1 operator --names Preferences for S1 ^operator: acceptables: O2 (fill) + From waterjug*propose*fill O3 (fill) + From waterjug*propose*fill unary indifferents: O2 (fill) = From waterjug*propose*fill O3 (fill) = From waterjug*propose*fill
If the current state is S1, then the above syntax is equivalent to:
preferences -n
This example shows the support for the WMEs with the ^jug attribute:
soar> preferences s1 jug Preferences for S1 ^jug: acceptables: (S1 ^jug I4) :O (S1 ^jug J1) :O
This example shows the support for the WMEs with value J1, and the productions that generated them:
soar> pref J1 -1
Support for (31: O3 ^jug J1)
(O3 ^jug J1)
From water-jug*propose*fill
Support for (11: S1 ^jug J1)
(S1 ^jug J1) :O
From water-jug*apply*initialize-water-jug-look-aheadThis example shows the support for all WMEs that make up the object S1:
soar> pref -o s1 Support for S1 ^problem-space: (S1 ^problem-space P1) Support for S1 ^name: (S1 ^name water-jug) :O Support for S1 ^jug: (S1 ^jug I4) :O (S1 ^jug J1) :O Support for S1 ^desired: (S1 ^desired D1) :O Support for S1 ^superstate-set: (S1 ^superstate-set nil) Preferences for S1 ^operator: acceptables: O2 (fill) + O3 (fill) + Arch-created wmes for S1 : (2: S1 ^superstate nil) (1: S1 ^type state) Input (IO) wmes for S1 : (3: S1 ^io I1)
Print items in working memory or production memory.
print [options] [production_name] print [options] identifier|timetag|pattern
| p | |
| pc | print --chunks |
| wmes | print --internal |
| -a, --all | print the names of all productions currently loaded |
| -c, --chunks | print the names of all chunks currently loaded |
| -D, --defaults | print the names of all default productions currently loaded |
| -f, --full | When printing productions, print the whole production. This is the default when printing a named production. |
| -F, --filename | also prints the name of the file that contains the production. |
| -i, --internal | items should be printed in their internal form. For productions, this means leaving conditions in their reordered (rete net) form. |
| -j, --justifications | print the names of all justifications currently loaded. |
| -n, --name | When printing productions, print only the name and not the whole production. This is the default when printing any category of productions, as opposed to a named production. |
| -r, --rl | Print Soar-RL rules |
| -T, --template | Print Soar-RL templates |
| -u, --user | print the names of all user productions currently loaded |
| production_name | print the production named production-name |
Note that only one of the options c,D,j,r,t or U can be used at a time for correct behavior.
| -d, --depth n | This option overrides the default printing depth (see the default-wme-depth command for more detail). |
| -e, --exact | Print only the wmes that match the pattern |
| -i, --internal | items should be printed in their internal form. For working memory, this means printing the individual elements with their timetags, rather than the objects. |
| -t, --tree | wmes should be printed in in a tree form (one wme per line). |
| -v, --varprint | Print identifiers enclosed in angle brackets. |
| identifier | print the object identifier. identifier must be a valid Soar symbol such as S1 |
| pattern | print the object whose working memory elements matching the given pattern. See Description for more information on printing objects matching a specific pattern. |
| timetag | print the object in working memory with the given timetag |
| -s, --stack | Specifies that the Soar goal stack should be printed. By default this includes both states and operators. |
| -o, --operators | When printing the stack, print only operators. |
| -S, --states | When printing the stack, print only states. |
The print command is used to print items from production memory or working memory. It can take several kinds of arguments. When printing items from working memory, the Soar objects are printed unless the --internal flag is used, in which case the wmes themselves are printed.
(identifier ^attribute value [+])
The pattern is surrounded by parentheses. The identifier, attribute, and value must be valid Soar symbols or the wildcard symbol * which matches all occurrences. The optional + symbol restricts pattern matches to acceptable preferences. If wildcards are included, an object will be printed for each pattern match, even if this results in the same object being printed multiple times.
Print the objects in working memory (and their timetags) which have wmes with identifier s1 and value v2 (note: this will print the entire s1 object for each match found):
print --internal (s1 ^* v2)
Print the Soar stack which includes states and operators:
print --stack
Print the named production in its RETE form:
print -if named*production
Print the names of all user productions currently loaded:
print -u
Default print vs tree print:
print s1 --depth 2 (S1 ^io I1 ^reward-link R1 ^superstate nil ^type state) (I1 ^input-link I2 ^output-link I3) print s1 --depth 2 --tree (S1 ^io I1) (I1 ^input-link I2) (I1 ^output-link I3) (S1 ^reward-link R1) (S1 ^superstate nil) (S1 ^type state)
default-wme-depth predefined-aliases
Find productions by condition or action patterns.
production-find [-lrs[n|c]] pattern
| -c, --chunks | Look only for chunks that match the pattern. |
| -l, --lhs | Match pattern only against the conditions (left-hand side) of productions (default). |
| -n, --nochunks | Disregard chunks when looking for the pattern. |
| -r, --rhs | Match pattern against the actions (right-hand side) of productions. |
| -s, --show-bindings | Show the bindings associated with a wildcard pattern. |
| pattern | Any pattern that can appear in productions. |
The production-find command is used to find productions in production memory that include conditions or actions that match a given pattern. The pattern given specifies one or more condition elements on the left hand side of productions (or negated conditions), or one or more actions on the right-hand side of productions. Any pattern that can appear in productions can be used in this command. In addition, the asterisk symbol, *, can be used as a wildcard for an attribute or value. It is important to note that the whole pattern, including the parenthesis, must be enclosed in curly braces for it to be parsed properly.
The variable names used in a call to production-find do not have to match the variable names used in the productions being retrieved.
The production-find command can also be restricted to apply to only certain types of productions, or to look only at the conditions or only at the actions of productions by using the flags.
Find productions that test that some object gumby has an attribute alive with value t. In addition, limit the rules to only those that test an operator named foo:
production-find (<state> ^gumby <gv> ^operator.name foo)(<gv> ^alive t)
Note that in the above command, <state> does not have to match the exact variable name used in the production.
Find productions that propose the operator foo:
production-find --rhs (<x> ^operator <op> +)(<op> ^name foo)
Find chunks that test the attribute ^pokey:
production-find --chunks (<x> ^pokey *)
Examples using the water-jugs demo:
source demos/water-jug/water-jug.soar production-find (<s> ^name *)(<j> ^volume *) production-find (<s> ^name *)(<j> ^volume 3) production-find --rhs (<j> ^* <volume>)
Push a directory onto the directory stack, changing to it.
pushd directory
Maintain a stack of working directories and push the directory on to the stack. Can be relative path name or fully specified.
cd dirs home ls popd source pwd
Trace firings and retractions of specific productions.
pwatch [-d|e] [production name]
| pw | pwatch |
| -d, --disable, --off | Turn production watching off for the specified production. If no production is specified, turn production watching off for all productions. |
| -e, --enable, --on | Turn production watching on for the specified production. The use of this flag is optional, so this is pwatch's default behavior. If no production is specified, all productions currently being watched are listed. |
| production name | The name of the production to watch. |
The pwatch command enables and disables the tracing of the firings and retractions of individual productions. This is a companion command to watch, which cannot specify individual productions by name.
With no arguments, pwatch lists the productions currently being traced. With one production-name argument, pwatch enables tracing the production; --enable can be explicitly stated, but it is the default action.
If --disable is specified followed by a production-name, tracing is turned off for the production. When no production-name is specified, --enable lists all productions currently being traced, and --disable disables tracing of all productions.
Note that pwatch now only takes one production per command. Use multiple times to watch multiple functions.
Print the current working directory.
pwd
| topd | pwd |
Prints the current working directory of Soar.
Close log file, terminate Soar, and return user to the operating system.
quit
| exit | quit |
This command stops the run, quits the log and closes Soar.
Generate a random number.
rand # returns a real number in [0,1] (calls SoarRand()) rand n # returns a real number in [0,n] (calls SoarRand(max)) rand --integer # returns an integer in [0,2^32-1] (calls SoarRandInt) rand --integer n # returns an integer in [0,n], n<2^32 (calls SoarRandInt(max))
| -i, --integer | Return an integer, optional argument is upper-bound (inclusive) |
Generates a random non-negative number, returning the result in a string.
rand --integer 10 # returns 0..10, for example: "4"
Manually remove an element from working memory.
remove-wme timetag
| rw | remove-wme |
| timetag | A positive integer matching the timetag of an existing working memory element. |
The remove-wme command removes the working memory element with the given timetag. This command is provided primarily for use in Soar input functions; although there is no programming enforcement, remove-wme should only be called from registered input functions to delete working memory elements on Soar's input link.
Beware of weird side effects, including system crashes.
remove-wme should never be called from the RHS: if you try to match a wme on the LHS of a production, and then remove the matched wme on the RHS, Soar will crash.
If used other than by input and output functions interfaced with Soar, this command may have weird side effects (possibly even including system crashes). Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.
Load input wmes for each decision cycle from a file.
replay-input --open filename replay-input [--query] replay-input --close
| filename | Open filename and load input and random seed. |
| -o, --open | Reads captured input from file in to memory and seeds the random number generator. |
| -q, --query | Returns open if input replay is active or closed if not active. |
| -c, --close | Stop replaying input. |
Replays input stored using the capture-input command. The replay file also includes a random number generator seed and seeds the generator with that.
Save the current Rete net, or restore a previous one.
rete-net -s|l filename
| rn | rete-net |
| -s, --save | Save the Rete net in the named file. Cannot be saved when there are justifications present. Use excise -j |
| -l, -r, --load, --restore | Load the named file into the Rete network. working memory and production memory must both be empty. Use excise |
| filename | The name of the file to save or load. |
The rete-net command saves the current Rete net to a file or restores a Rete net previously saved. The Rete net is Soar's internal representation of production and working memory; the conditions of productions are reordered and common substructures are shared across different productions. This command provides a fast method of saving and loading productions since a special format is used and no parsing is necessary. Rete-net files are portable across platforms that support Soar.
Normally users wish to save only production memory. Note that justifications cannot be present when saving the Rete net. Issuing an init-soar before saving a Rete net will remove all justifications and working memory elements.
If the filename contains a suffix of .Z, then the file is compressed automatically when it is saved and uncompressed when it is loaded. Compressed files may not be portable to another platform if that platform does not support the same uncompress utility.
Get/Set Soar-RL parameters and statistics.
rl [options parameter|statstic]
| -g, --get | Retrieve a Soar-RL parameter value |
| -s, --set | Set a Soar-RL parameter value |
| -S, --stats | Access Soar-RL statistics |
This command is used to get/set all parameters in Soar-RL. Additionally used to access statistics. See tables below for available parameters, full information is in the Soar-RL manual.
Without any options: summary table of parameter settings.
| Parameter Name | Acceptable Values | Default |
| learning | on, off | off |
| temporal-extension | on, off | on |
| discount-rate | [0, 1] | 0.9 |
| learning-rate | [0, 1] | 0.3 |
| learning-policy | sarsa, q-learning | sarsa |
| hrl-discount | on, off | on |
| eligibility-trace-decay-rate | [0, 1] | 0 |
| eligibility-trace-tolerance | (0, inf) | 0.001 |
This command gets the value of the learning-rate parameter:
rl --get learning-rate
This command sets the value of the learning-rate parameter to 0.5:
rl --set learning-rate 0.5
Begin Soar's execution cycle.
run [-f|count] run -[d|e|o|p][s][un][g] [f|count] run -[d|e|o|p][un] count [-i e|p|d|o]
| d | run -d 1 |
| e | run -e 1 |
| step | run 1 |
| -d, --decision | Run Soar for count decision cycles. |
| -e, --elaboration | Run Soar for count elaboration cycles. |
| -o, --output | Run Soar until the nth time output is generated by the agent. Limited by the value of max-nil-output-cycles. |
| -p, --phase | Run Soar by phases. A phase is either an input phase, proposal phase, decision phase, apply phase, or output phase. |
| -s, --self | If other agents exist within the kernel, do not run them at this time. |
| -u, --update | Sets a flag in the update event callback requesting that an environment updates. This is the default if --self is not specified. |
| -n, --noupdate | Sets a flag in the update event callback requesting that an environment does not update. This is the default if --self is specified. |
| -f, forever | Run until halted by problem-solving completion or until stopped by an interrupt. |
| count | A single integer which specifies the number of cycles to run Soar. |
| -i, --interleave | Support round robin execution across agents at a finer grain than the run-size parameter. e = elaboration, p = phase, d = decision, o = output |
| -g, --goal | Run agent until a goal retracts |
These may be reimplemented in the future.
| --operator | Run Soar until the nth time an operator is selected. |
| --state | Run Soar until the nth time a state is selected. |
The run command starts the Soar execution cycle or continues any execution that was temporarily stopped. The default behavior of run, with no arguments, is to cause Soar to execute until it is halted or interrupted by an action of a production, or until an external interrupt is issued by the user. The run command can also specify that Soar should run only for a specific number of Soar cycles or phases (which may also be prematurely stopped by a production action or the stop-soar command). This is helpful for debugging sessions, where users may want to pay careful attention to the specific productions that are firing and retracting.
The run command takes optional arguments: an integer, count, which specifies how many units to run; and a units flag indicating what steps or increments to use. If count is specified, but no units are specified, then Soar is run by decision cycles. If units are specified, but count is unpecified, then count defaults to '1'. The argument forever (can be shortened to f) is a keyword used instead of an integer count and indicates Soar should be run indefinitely, until halted by problem-solving completion, or stopped by an interrupt.
If there are multiple Soar agents that exist in the same Soar process, then issuing a run command in any agent will cause all agents to run with the same set of parameters, unless the flag --self is specified, in which case only that agent will execute.
If an environment is registered for the kernel's update event, then when the event it triggered, the environment will get information about how the run was executed. If a run was executed with the --update option, then then event sends a flag requesting that the environment actually update itself. If a run was executed with the --noupdate option, then the event sends a flag requesting that the environment not update itself. The --update option is the default when run is specified without the --self option is not specified. If the --self option is specified, then the --noupdate option is on by default. It is up to the environment to check for these flags and honor them.
Some use cases include:
| run --self | runs one agent but not the environment |
| run --self --update | runs one agent and the environment |
| run | runs all agents and the environment |
| run --noupdate | runs all agents but not the environment |
When there are multiple agents running within the same process, it may be useful to keep agents more closely aligned in their execution cycle than the run increment (--elaboration, --phases, --decisions, --output) specifies. For instance, it may be necessary to keep agents in "lock step" at the phase level, eventhough the run command issued is for 5 decisions. Some use cases include:
| 1run -d 5 -inteleave p` | || run the agent one phase and then move to the next agent, looping over agents until they have run for 5 decision cycles|
| run -o 3 -interleave d | run the agent one decision cycle and then move to the next agent. When an agent generates output for the 3rd time, it no longer runs even if other agents continue. |
The interleave parameter must always be equal to or smaller than the specified run parameter. This option is not currently compatible with the forever option.
If Soar has been stopped due to a halt action, an init-soar command must be issued before Soar can be restarted with the run command.
Save trace information to explain chunks and justifications.
save-backtraces [-ed]
| -e, --enable, --on | Turn explain sysparam on. |
| -d, --disable, --off | Turn explain sysparam off. |
The save-backtraces variable is a toggle that controls whether or not backtracing information (from chunks and justifications) is saved.
When save-backtraces is set to off, backtracing information is not saved and explanations of the chunks and justifications that are formed can not be retrieved. When save-backtraces is set to on, backtracing information can be retrieved by using the [CommandLineInterface#explain-backtraces explain-backtraces] command. Saving backtracing information may slow down the execution of your Soar program, but it can be a very useful tool in understanding how chunks are formed.
Force the next selected operator
select id
If no "id" is supplied, currently "select"ed operator (if applicable) is displayed
| id | case-insensitive operator id of the operator to be selected in the next decision phase |
The select command will force the selection of an operator, whose id is supplied as an argument, during the next decision phase. If the argument is not a proposed operator in the next decision phase, an error is raised and operator selection proceeds as if the select command had not been called. Otherwise, the supplied operator will be selected as the next operator, regardless of preferences. If select is called with no id argument, the command returns the operator id currently forced for selection (by a previous call to select), if one exists.
Assuming operator "O2" is a valid operator, this would select it as the next operator to be selected:
select O2
After this command, issuing just "select" will get "O2" as a return:
select
Set the top level directory containing demos/help/etc.
set-library-location [directory]
| directory | The new desired library location. |
Invoke with no arguments to query what the current library location is. The library location should contain at least the help/ subdirectory and the command-names file for help to work.
Controls the phase where agents stop when running by decision.
set-stop-phase -[ABadiop]
Options -A and -B are optional and mutually exclusive. If not specified, the default is -B.
Only one of -a, -d, -i, -o, -p must be selected.
With no options, reports the current stop phase.
| -A, --after | Stop after specified phase. |
| -B, --before | Stop before specified phase (the default). |
| -a, --apply | Select the apply phase. |
| -d, --decision | Select the decision phase. |
| -i, --input | Select the input phase. |
| -o, --output | Select the output phase. |
| -p, --proposal | Select the proposal phase. |
When running by decision cycle it can be helpful to have agents stop at a particular point in its execution cycle. This command allows the user to control which phase Soar stops in. The precise definition is that "running for n decisions and stopping before phase ph means to run until the decision cycle counter has increased by n and then stop when the next phase is ph". The phase sequence (as of this writing) is: input, proposal, decision, apply, output. Stopping after one phase is exactly equivalent to stopping before the next phase.
On initialization Soar defaults to stopping before the input phase (or after the output phase, however you like to think of it).
Setting the stop phase applies to all agents.
set-stop-phase -Bi // stop before input phase set-stop-phase -Ad // stop after decision phase (before apply phase) set-stop-phase -d // stop before decision phase set-stop-phase --after --output // stop after output phase set-stop-phase // reports the current stop phase
Prints information about the current release.
soarnews
| sn | soarnews |
Load and evaluate the contents of a file.
source [options] filename
| filename | The file of Soar productions and commands to load. |
| -a, --all | Enable a summary for each file sourced |
| -d, --disable | Disable all summaries |
| -v, --verbose | Print excised production names |
Load and evaluate the contents of a file. The filename can be a relative path or a fully qualified path. source will generate an implicit push to the new directory, execute the command, and then pop back to the current working directory from which the command was issued.
After the source completes, the number of productions sourced and excised is printed:
agent> source demos/mac/mac.soar ****************** Total: 18 productions sourced. Source finished. agent> source demos/mac/mac.soar #*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#* Total: 18 productions sourced. 18 productions excised. Source finished.
This can be disabled by using the -d flag:
agent> source demos/mac/mac.soar -d ****************** Source finished. agent> source demos/mac/mac.soar -d #*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#* Source finished.
A list of excised productions is available using the -v flag:
agent> source demos/mac/mac.soar -v
#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*#*
Total: 18 productions sourced. 18 productions excised.
Excised productions:
mac*detect*state*success
mac*evaluate*state*failure*more*cannibals
monitor*move-boat
monitor*state*left
...A separate summary for each file sourced can be enabled using the -a flag:
agent> source demos/mac/mac.soar -a _firstload.soar: 0 productions sourced. all_source.soar: 0 productions sourced. ** goal-test.soar: 2 productions sourced. *** monitor.soar: 3 productions sourced. **** search-control.soar: 4 productions sourced. top-state.soar: 0 productions sourced. elaborations_source.soar: 0 productions sourced. _readme.soar: 0 productions sourced. ** initialize-mac.soar: 2 productions sourced. ******* move-boat.soar: 7 productions sourced. mac_source.soar: 0 productions sourced. mac.soar: 0 productions sourced. Total: 18 productions sourced. Source finished.
Combining the -a and -v flags add excised production names to the output for each file.
cd dirs home ls pushd popd pwd
Define a Soar production.
sp {production_body}| production_body | A Soar production. |
The sp command creates a new production and loads it into production memory. production_body is a single argument parsed by the Soar kernel, so it should be enclosed in curly braces to avoid being parsed by other scripting languages that might be in the same process. The overall syntax of a rule is as follows:
name
["documentation-string"]
[FLAG*]
LHS
-->
RHSThe first element of a rule is its name. Conventions for names are given in the Soar Users Manual. If given, the documentation-string must be enclosed in double quotes. Optional flags define the type of rule and the form of support its right-hand side assertions will receive. The specific flags are listed in a separate section below. The LHS defines the left-hand side of the production and specifies the conditions under which the rule can be fired. Its syntax is given in detail in a subsequent section. The --> symbol serves to separate the LHS and RHS portions. The RHS defines the right-hand side of the production and specifies the assertions to be made and the actions to be performed when the rule fires. The syntax of the allowable right-hand side actions are given in a later section. The Soar Users Manual gives an elaborate discussion of the design and coding of productions. Please see that reference for tutorial information about productions.
If the name of the new production is the same as an existing one, the old production will be overwritten (excised).
Rules matching the following requirement are flagged upon being created/sourced: a rule is a Soar-RL rule if and only if its right hand side (RHS) consists of a single numeric preference and it is not a template rule (see FLAGs below). This format exists to ease technical requirements of identifying/updating Soar-RL rules, as well as to make it easy for the agent programmer to add/maintain RL capabilities within an agent. See the Soar-RL Manual for further details.
The optional FLAGs are given below. Note that these switches are preceeded by a colon instead of a dash -- this is a Soar parser convention.
:o-support specifies that all the RHS actions are to be given
o-support when the production fires
:no-support specifies that all the RHS actions are only to be given
i-support when the production fires
:default specifies that this production is a default production
(this matters for excise -task and watch task)
:chunk specifies that this production is a chunk
(this matters for learn trace)
:interrupt specifies that Soar should stop running when this
production matches but before it fires
(this is a useful debugging tool)
:template specifies that this production should be used to generate
new reinforcement learning rules by filling in those
variables that match constants in working memoryMultiple flags may be used, but not both of o-support and no-support.
Although you could force your productions to provide O-support or I-support by using these commands --- regardless of the structure of the conditions and actions of the production --- this is not proper coding style. The o-support and no-support flags are included to help with debugging, but should not be used in a standard Soar program.
sp {blocks*create-problem-space
"This creates the top-level space"
(state <s1> ^superstate nil)
-->
(<s1> ^name solve-blocks-world ^problem-space <p1>)
(<p1> ^name blocks-world)
}Seed the random number generator.
srand [seed]
| seed | Random number generator seed. |
Seeds the random number generator with the passed seed. Calling srand without providing a seed will seed the generator based on the contents of /dev/urandom (if available) or else based on time() and clock() values.
srand 0
Print information on Soar's runtime statistics.
stats [options]
| st | stats |
| -m, --memory | report usage for Soar's memory pools |
| -r, --rete | report statistics about the rete structure |
| -s, --system | report the system (agent) statistics (default) |
SMem branch only:
| -M, --max | report the per-cycle maximum statistics (decision cycle time, WM changes, production fires) |
| -R, --reset | zero out the per-cycle maximum statistics reported by --max command |
| -t, --track | begin tracking the per-cycle maximum statistics reported by --max for each cycle (instead of only the max value) |
| -c, --cycle | print out collected per-cycle maximum statistics saved by --track in human-readable form |
| -C, --cycle-csv | print out collected per-cycle maximum statistics saved by --track in comma-separated form |
| -S, --sort N | sort the tracked cycle stats by column number N, see table below |
For use with --sort option. Negative values sorts descending.
| 0 | Use default sort |
| 1, -1 | Sort by decision cycle (use negative for descending) |
| 2, -2 | Sort by DC time (use negative for descending) |
| 3, -3 | Sort by WM changes (use negative for descending) |
| 4, -4 | Sort by production firings (use negative for descending) |
This command prints Soar internal statistics. The argument indicates the component of interest, --system is used by default.
With the --system flag, the stats command lists a summary of run statistics, including the following:
The stats argument --memory provides information about memory usage and Soar's memory pools, which are used to allocate space for the various data structures used in Soar.
The stats argument --rete provides information about node usage in the Rete net, the large data structure used for efficient matching in Soar.
The --max argument reports per-cycle maximum statistics for decision cycle time, working memory changes, and production fires. For example, if Soar runs for three cycles and there were 23 working memory changes in the first cycle, 42 in the second, and 15 in the third, the --max argument would report the highest of these values (42) and what decision cycle that it occurred in (2nd). Statistics about the time spent executing the decision cycle and number of productions fired are also collected and reported by --max in this manner. --reset zeros out these statistics so that new maximums can be recorded for future runs. The numbers are also zeroed out with a call to init-soar.
The --track argument starts tracking the same stats as the --max argument but records all data for each cycle instead of the maximum values. This data can be printed using the --cycle or --cycle-csv arguments. When printing the data with --cycle, it may be sorted using the --sort argument and a column integer. Use negative numbers for descending sort.
The current implementation of Soar uses a number of timers to provide time-based statistics for use in the stats command calculations. These timers are:
Total CPU time is calculated from the time a decision cycle (or number of decision cycles) is initiated until stopped. Kernel time is the time spent in core Soar functions. In this case, kernel time is defined as the all functions other than the execution of callbacks and the input and output functions. The total kernel timer is only stopped for these functions. The phase timers (for the kernel and callbacks) track the execution time for individual phases of the decision cycle (i.e., input phase, preference phase, working memory phase, output phase, and decision phase). Because there is overhead associated with turning these timers on and off, the actual kernel time will always be greater than the derived kernel time (i.e., the sum of all the phase kernel timers). Similarly, the total CPU time will always be greater than the derived total (the sum of the other timers) because the overhead of turning these timers on and off is included in the total CPU time. In general, the times reported by the single timers should always be greater than than the corresponding derived time. Additionally, as execution time increases, the difference between these two values will also increase. For those concerned about the performance cost of the timers, all the run time timing calculations can be compiled out of the code by defining NO_TIMING_STUFF (in soarkernel.h) before compilation.
Track per-cycle stats then print them out using default sort:
stats --track run stop stats --cycle
Print out per-cycle stats sorting by decision cycle time
stats --cycle --sort 2
Print out per-cycle stats sorting by firing counts, descending
stats --cycle --sort -4
Save per-cycle stats to file stats.csv
ctf stats.csv stats --cycle-csv
timers init-soar command-to-file
Pause Soar.
stop-soar [-s] [reason string]
| interrupt | stop-soar |
| ss | stop-soar |
| stop | stop-soar |
| -s, --self | Stop only the soar agent where the command is issued. All other agents continue running as previously specified. |
| reason_string | An optional string which will be printed when Soar is stopped, to indicate why it was stopped. If left blank, no message will be printed when Soar is stopped. |
The stop-soar command stops any running Soar agents. It sets a flag in the Soar kernel so that Soar will stop running at a "safe" point and return control to the user. This command is usually not issued at the command line prompt - a more common use of this command would be, for instance, as a side-effect of pressing a button on a Graphical User Interface (GUI).
If the graphical interface doesn't periodically do an "update" of flush the pending I/O, then it may not be possible to interrupt a Soar agent from the command line.
Use a default system clock timer to record the wall time required while executing a command.
time command [arguments]
| command | The command to execute. |
| arguments | Optional command arguments. |
Toggle on or off the internal timers used to profile Soar.
timers [options]
| -d, --disable, --off | Disable all timers. |
| -e, --enable, --on | Enable timers as compiled. |
This command is used to control the timers that collect internal profiling information while Soar is running. With no arguments, this command prints out the current timer status. Timers are ENABLED by default. The default compilation flags for soar enable the basic timers and disable the detailed timers. The timers command can only enable or disable timers that have already been enabled with compiler directives. See the [CommandLineInterface#stats stats] command for more info on the Soar timing system.
Undefine an existing alias
unalias name
| un | [CommandLineInterface#unalias unalias] |
This command undefines a previously created alias. This command takes exactly one argument: the name of the alias to remove. Use the alias command by itself to list all defined aliases.
unalias varprint
Control detailed information printed as Soar runs.
verbose [-ed]
| -d, --disable, --off | Turn verbosity off. (default) |
| -e, --enable, --on | Turn verbosity on. |
The verbose command enables tracing of a number of low-level Soar execution details during a run. The details printed by verbose are usually only valuable to developers debugging Soar implementation details. Invoke with no arguments to query the current setting.
Returns the version number of the Soar kernel.
version
This command gives version information about the current Soar kernel. It returns the version number and build date which can then be stored by the agent or the application.
Generate a wait state rather than a state-no-change impasse.
wait -[e|d]
| -e, --enable, --on | Turns a state-no-change into a wait state. |
| -d, --disable, --off | Default. A state-no-change generates an impasse. |
In some systems, espcially those that model expert (fully chunked) knowledge, a state-no-change may represent a wait state rather than an impasse. The waitsnc command allows the user to switch to a mode where a state-no-change that would normally generate an impasse (and subgoaling), instead generates a wait state. At a wait state, the decision cycle will repeat (and the decision cycle count is incremented) but no state-no-change impasse (and therefore no substate) will be generated.
When issued with no arguments, waitsnc returns its current setting.
Enable or disable the printing of warning messages from the Soar kernel.
warnings [options]
| -e, --enable, --on | Default. Print all warning messages from the kernel. |
| -d, --disable, --off | Disable all, except most critical, warning messages. |
Enables and disables the printing of warning messages. If an argument is specified, then the warnings are set to that state. If no argument is given, then the current warnings status is printed. At startup, warnings are initially enabled. If warnings are disabled using this command, then some warnings may still be printed, since some are considered too important to ignore.
The warnings that are printed apply to the syntax of the productions, to notify the user when they are not in the correct syntax. When a lefthand side error is discovered (such as conditions that are not linked to a common state or impasse object), the production is generally loaded into production memory anyway, although this production may never match or may seriously slow down the matching process. In this case, a warning would be printed only if warnings were --on. Righthand side errors, such as preferences that are not linked to the state, usually result in the production not being loaded, and a warning regardless of the warnings setting.
Control the run-time tracing of Soar.
watch [options] watch level
| w | watch |
When appropriate, a specific option may be turned off using the remove argument. This argument has a numeric alias; you can use 0 for remove. A mix of formats is acceptable, even in the same command line.
| Option Flag | Argument to Option | Description |
| -l, --level | 0 to 5 (see Watch Levels below) | This flag is optional but recommended. Set a specific watch level using an integer 0 to 5, this is an inclusive operation |
| -N, --none | No argument | Turns off all printing about Soar's internals, equivalent to --level 0 |
| -d, --decisions | remove (optional) | Controls whether state and operator decisions are printed as they are made |
| -p, --phases | remove (optional) | Controls whether decisions cycle phase names are printed as Soar executes |
| -P, --productions | remove (optional) | Controls whether the names of productions are printed as they fire and retract, equivalent to -Dujc |
| -w, --wmes | remove (optional) | Controls the printing of working memory elements that are added and deleted as productions are fired and retracted. (Including wme changes to GDS) |
| -r, --preferences | remove (optional) | Controls whether the preferences generated by the traced productions are printed when those productions fire or retract |
Use of the --level (-l) flag is optional but recommended.
| 0 | watch nothing; equivalent to -N |
| 1 | watch decisions; equivalent to -d |
| 2 | watch phases and decisions; equivalent to -dp |
| 3 | watch productions, phases, and decisions; equivalent to -dpP |
| 4 | watch wmes, productions, phases, and decisions; equivalent to -dpPw |
| 5 | watch preferences, wmes, productions, phases, and decisions; equivalent to -dpPwr |
It is important to note that watch level 0 turns off ALL watch options, including backtracing, indifferent selection and learning. However, the other watch levels do not change these settings. That is, if any of these settings is changed from its default, it will retain its new setting until it is either explicitly changed again or the watch level is set to 0.
By default, the names of the productions are printed as each production fires and retracts (at watch levels 3 and higher). However, it may be more helpful to watch only a specific type of production. The tracing of firings and retractions of productions can be limited to only certain types by the use of the following flags:
| Option Flag | Argument to Option | Description |
| -D, --default | remove (optional) | Control only default-productions as they fire and retract |
| -u, --user | remove (optional) | Control only user-productions as they fire and retract |
| -c, --chunks | remove (optional) | Control only chunks as they fire and retract |
| -j, --justifications | remove (optional) | Control only justifications as they fire and retract |
| -T, --template | remote (optional) | Soar-RL template firing trace |
Note: The pwatch command is used to watch individual productions specified by name rather than watch a type of productions, such as --user.
Additionally, when watching productions, users may set the level of detail to be displayed for WMEs that are added or retracted as productions fire and retract. Note that detailed information about WMEs will be printed only for productions that are being watched.
| Option Flag | Description |
| -n, --nowmes | When watching productions, do not print any information about matching wmes |
| -t, --timetags | When watching productions, print only the timetags for matching wmes |
| -f, --fullwmes | When watching productions, print the full matching wmes |
| Option Flag | Argument to Option | Description |
| -L, --learning | noprint, print, or fullprint (see table below) | Controls the printing of chunks/justifications as they are created |
As Soar is running, it may create justifications and chunks which are added to production memory. The watch command allows users to monitor when chunks and justifications are created by specifying one of the following arguments to the --learning command:
| Argument | Alias | Effect |
| noprint | 0 | Print nothing about new chunks or justifications (default) |
| 1 | Print the names of new chunks and justifications when created | |
| fullprint | 2 | Print entire chunks and justifications when created |
| Option Flag | Argument to Option | Description |
| -b, --backtracing | remove (optional) | Controls the printing of backtracing information when a chunk or justification is created |
| -i, --indifferent-selection | remove (optional) | Controls the printing of the scores for tied operators in random indifferent selection mode |
| -R, --rl | remove (optional) | Soar-RL debugging trace |
The watch command controls the amount of information that is printed out as Soar runs. The basic functionality of this command is to trace various levels of information about Soar's internal workings. The higher the level, the more information is printed as Soar runs. At the lowest setting, 0 (--none), nothing is printed. The levels are cumulative, so that each successive level prints the information from the previous level as well as some additional information. The default setting for the level is 1, (--decisions).
The numerical arguments inclusively turn on all levels up to the number specified. To use numerical arguments to turn off a level, specify a number which is less than the level to be turned off. For instance, to turn off watching of productions, specify --level 2 (or 1 or 0). Numerical arguments are provided for shorthand convenience. For more detailed control over the watch settings, the named arguments should be used.
With no arguments, this command prints information about the current watch status, i.e., the values of each parameter.
For the named arguments, including the named argument turns on only that setting. To turn off a specific setting, follow the named argument with remove or 0.
The named argument --productions is shorthand for the four arguments --default, --user, --justifications, and --chunks.
The most common uses of watch are by using the numeric arguments which indicate watch levels. To turn off all printing of Soar internals, do any one of the following (not all possibilities listed):
watch --level 0 watch -l 0 watch -N
Although the --level flag is optional, its use is recommended:
watch --level 5 # OK watch 5 # OK, avoid
Be careful of where the level is on the command line, for example, if you want level 2 and preferences:
watch -r -l 2 # Incorrect: -r flag ignored, level 2 parsed after it and overrides the setting watch -r 2 # Syntax error: 0 or remove expected as optional argument to -r watch -r -l 2 # Incorrect: -r flag ignored, level 2 parsed after it and overrides the setting watch 2 -r # OK, avoid watch -l 2 -r # OK
To turn on printing of decisions, phases and productions, do any one of the following (not all possibilities listed):
watch --level 3 watch -l 3 watch --decisions --phases --productions watch -d -p -P
Individual options can be changed as well. To turn on printing of decisions and wmes, but not phases and productions, do any one of the following (not all possibilities listed):
watch --level 1 --wmes watch -l 1 -w watch --decisions --wmes watch -d --wmes watch -w --decisions watch -w -d
To turn on printing of decisions, productions and wmes, and turns phases off, do any one of the following (not all possibilities listed):
watch --level 4 --phases remove watch -l 4 -p remove watch -l 4 -p 0 watch -d -P -w -p remove
To watch the firing and retraction of decisions and only user productions, do any one of the following (not all possibilities listed):
watch -l 1 -u watch -d -u
To watch decisions, phases and all productions except user productions and justifications, and to see full wmes, do any one of the following (not all possibilities listed):
watch --decisions --phases --productions --user remove --justifications remove --fullwmes watch -d -p -P -f -u remove -j 0 watch -f -l 3 -u 0 -j 0
Print information about wmes matching a certain pattern as they are added and removed.
watch-wmes -[a|r] -t type pattern watch-wmes -[l|R] [-t type]
| -a, --add-filter | Add a filter to print wmes that meet the type and pattern criteria. |
| -r, --remove-filter | Delete filters for printing wmes that match the type and pattern criteria. |
| -l, --list-filter | List the filters of this type currently in use. Does not use the pattern argument. |
| -R, --reset-filter | Delete all filters of this type. Does not use pattern arg. |
| -t, --type | Follow with a type of wme filter, see below. |
The pattern is an id-attribute-value triplet:
id attribute value
Note that * can be used in place of the id, attribute or value as a wildcard that maches any string. Note that braces are not used anymore.
When using the -t flag, it must be followed by one of the following:
| adds | Print info when a wme is added. |
| removes | Print info when a wme is retracted. |
| both | Print info when a wme is added or retracted. |
When issuing a -R or -l, the -t flag is optional. Its absence is equivalent to -t both.
This commands allows users to improve state tracing by issuing filter-options that are applied when watching wmes. Users can selectively define which object-attribute-value triplets are monitored and whether they are monitored for addition, removal or both, as they go in and out of working memory.
Note: The functionality of watch-wmes resided in the watch command prior to Soar 8.6.
Users can watch an attribute of a particular object (as long as that object already exists):
soar> watch-wmes --add-filter -t both D1 speed *
or print WMEs that retract in a specific state (provided the state already exists):
soar> watch-wmes --add-filter -t removes S3 * *
or watch any relationship between objects:
soar> watch-wmes --add-filter -t both * ontop *