#include "soarkernel.h"
#include "soar_core_api.h"
#include "soar_ecore_api.h"
#include "soarapi_datatypes.h"
#include "debugutil.h"
Go to the source code of this file.
Interaction With Soar | |
This section deals with four main areas of interaction
| |
int | soar_ReInitSoar (int argc, char *argv[], soarResult *res) |
soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent. More... | |
int | soar_CreateAgent (int argc, char *argv[], soarResult *res) |
soar_CreateAgent -- This command creates a new agent. More... | |
int | soar_Run (int argc, char *argv[], soarResult *res) |
soar_Run -- This is the command procedure for the "run" command which runs the Soar agent. More... | |
int | soar_DestroyAgent (int argc, char *argv[], soarResult *res) |
soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent. More... | |
int | soar_Quit (int argc, char *argv[], soarResult *res) |
soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited. More... | |
Modifying Agent Memory | |
This section deals with two areas of the agent:
| |
int | soar_ReteNet (int argc, char *argv[], soarResult *res) |
soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network. More... | |
int | soar_AddWme (int argc, char *argv[], soarResult *res) |
soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory. More... | |
int | soar_RemoveWme (int argc, char *argv[], soarResult *res) |
soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory. More... | |
int | soar_Excise (int argc, char *argv[], soarResult *res) |
soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory. More... | |
Modifying the Agents Parameters | |
int | soar_CaptureInput (int argc, char *argv[], soarResult *res) |
soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase. More... | |
int | soar_ReplayInput (int argc, char *argv[], soarResult *res) |
soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input. More... | |
int | soar_ChunkNameFormat (int argc, char *argv[], soarResult *res) |
soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks. More... | |
int | soar_Learn (int argc, char *argv[], soarResult *res) |
soar_Learn -- This is the command procedure for the "learn" command. More... | |
int | soar_MaxElaborations (int argc, char *argv[], soarResult *res) |
soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed. More... | |
int | soar_MaxChunks (int argc, char *argv[], soarResult *res) |
soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed. More... | |
int | soar_Operand2 (int argc, char *argv[], soarResult *res) |
soar_Operand2 -- This is the command procedure for the "soar8" command. More... | |
int | soar_WaitSNC (int argc, char *argv[], soarResult *res) |
soar_WaitSNC -- This is the command procedure for the "waitsnc" command. More... | |
int | soar_InputPeriod (int argc, char *argv[], soarResult *res) |
soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period. More... | |
int | soar_MultiAttributes (int argc, char *argv[], soarResult *res) |
soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values. More... | |
int | soar_OSupportMode (int argc, char *argv[], soarResult *res) |
soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent). More... | |
int | soar_ExplainBacktraces (int argc, char *argv[], soarResult *res) |
soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command. More... | |
int | soar_FiringCounts (int argc, char *argv[], soarResult *res) |
soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired. More... | |
int | soar_FormatWatch (int argc, char *argv[], soarResult *res) |
soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack. More... | |
int | soar_IndifferentSelection (int argc, char *argv[], soarResult *res) |
soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration. More... | |
int | soar_InternalSymbols (int argc, char *argv[], soarResult *res) |
soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table. More... | |
int | soar_Matches (int argc, char *argv[], soarResult *res) |
soar_Matches -- This is the command procedure for the "matches" command. More... | |
int | soar_Memories (int argc, char *argv[], soarResult *res) |
soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use. More... | |
int | soar_ProductionFind (int argc, char *argv[], soarResult *res) |
soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic. More... | |
int | soar_Preferences (int argc, char *argv[], soarResult *res) |
soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot. More... | |
int | soar_Print (int argc, char *argv[], soarResult *res) |
soar_Print -- This is the command procedure for the "print" command, which prints various Soar items. More... | |
int | soar_PWatch (int argc, char *argv[], soarResult *res) |
soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing. More... | |
int | soar_Pool (int argc, char *argv[], soarResult *res) |
soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools. More... | |
int | soar_Sp (int argc, char *argv[], soarResult *res) |
soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production. More... | |
int | soar_Stats (int argc, char *argv[], soarResult *res) |
soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information. More... | |
int | soar_Stop (int argc, char *argv[], soarResult *res) |
soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents. More... | |
int | soar_Verbose (int argc, char *argv[], soarResult *res) |
soar_Verbose -- This is the command procedure for the "verbose" command. More... | |
int | soar_Warnings (int argc, char *argv[], soarResult *res) |
soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages. More... | |
int | soar_Log (int argc, char *argv[], soarResult *res) |
soar_Log -- This is the command procedure for the "log" command which records session information to a log file. More... | |
int | soar_AttributePreferencesMode (int argc, char *argv[], soarResult *res) |
soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled. More... | |
int | soar_Watch (int argc, char *argv[], soarResult *res) |
soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing. More... | |
int | soar_DefaultWmeDepth (int argc, char *argv[], soarResult *res) |
soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth. More... | |
int | soar_BuildInfo (int argc, char *argv[], soarResult *res) |
soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar. More... | |
int | soar_ExcludedBuildInfo (int argc, char *argv[], soarResult *res) |
soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar. More... |
Copyright (c) 1995-1999 Carnegie Mellon University, University of Michigan, University of Southern California/Information Sciences Institute. All rights reserved.
The Soar consortium proclaims this software is in the public domain, and is made available AS IS. Carnegie Mellon University, The University of Michigan, and The University of Southern California/Information Sciences Institute make no warranties about the software or its performance, implied or otherwise. All rights reserved.
|
soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory.
This command surgically modifies Soar's working memory. Add-wme adds a new wme with the given id, attribute, value, and optional acceptable preference. The given id must be an existing identifier. If '*' is given in place of the attribute or value, Soar creates a new identifier (gensym) for that field. WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.
|
|
soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled.
This command affects the handling of preferences (other than acceptable and reject preferences) for non-context slots. It takes a single numeric argument:
|
|
soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar.
This function indicates compile time setting which affect the current instantiation of Soar. For example, the Note that the options which are printed using this function are filtered. They are expected to be the most pertanant of all the compile time options.
|
|
soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase.
This command may be used to start and stop the recording of input wmes as created by an external simulation. wmes are recorded decision cycle by decision cycle. Use the command replay-input to replay the sequence.
|
|
soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks.
|
|
soar_CreateAgent -- This command creates a new agent. If there were no agents previously, the current agent is defined as the newly created agent. Otherwise, the current agent remains the same.
|
|
soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth.
With no arguments, this command prints the current default print depth used by the "print" command. With an integer argument, it sets the current default print depth. This default print depth can be overridden on any particular invocation of the "print" command by using the -depth flag, e.g., print -depth 10 args.... The default print depth is initially 1.
|
|
soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent.
|
|
soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory.
"excise -chunks" removes all chunks and justifications from the agent. "excise -task" removes all non-default productions from the agent and performs an init-soar command. excise -all removes all productions from the agent. The switches may be abbreviated to 2 characters (e.g, -c for chunks).
|
|
soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar.
This function indicates compile time setting which affect the current instantiation of Soar.
Note that the options which are printed using this function are filtered. The options presented using this command are those which are expected to be of lesser importance. However, using this command in conjunction with
|
|
soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command.
Explain provides some interpretation of backtraces generated during chunking. Explain mode must be ON when the chunk/ justification is CREATED or no explanation will be available. Explain mode is toggled using the save_backtraces variable. When explain mode is on, more memory is used, and building chunks/justifications will be slower. The two most useful commands are 'explain-backtraces <name>' and *'explain-backtraces <name> <cond-num>'. The first command lists all of the conditions for the named chunk/justification, and the 'ground' which resulted in inclusion in the chunk/justification. A 'ground' is a 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 conditions can be listed with an integer value. This value can be used in 'explain <name> <cond-num>' 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). Why use an integer value to specify the condition? To save a big parsing job.
|
|
soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired.
This command prints how many times certain productions have fired. With no arguments, it lists all the productions sorted according to how many times they have fired. If an integer argument (call it k) is given, only the top k productions are listed. If k=0, only the productions which haven't fired at all are listed. Note that firing counts are not reset by an (init-soar); the counts indicate the number of firings since the productions were loaded or built. NB: this is slow, because the sorting takes time O(n*log n) With one or more production names as arguments, this command prints how many times each of those productions fired.
|
|
soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack.
Object trace formats control how Soar prints an object-- e.g., a certain operator, problem-space, etc. (This is like trace-attributes in Soar 5.) Stack trace formats control how Soar prints its context stack selections in 'watch 0' and 'pgs' printouts. You specify a trace format by indicating two things:
With an -add argument, these commands add new trace formats (replacing any existing ones with identical applicability conditions). With a -remove argument, they remove trace formats with the given applicability conditions. With no arguments, they print out all current trace formats. The following escape sequences can be used within trace format strings. The S indicates the sequence is ONLY usable in stack traces:
|
|
soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration.
With no arguments, this command prints the current setting of indifferent-selection. With an argument, it sets indifferent-selection to the given value. This controls how Soar's decision procedure chooses between multiple indifferent items:
|
|
soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period.
With no arguments, this command stores the current period used to control the input rate to the Soar agent in the SoarResult. With an integer argument, it sets the current input period. If the argument is 0, Soar behaves as it did in versions before 6.2.4, accepting input every elaboration cycle. An input period of "n" means that input is accepted only every "n" decision cycles. The input period is initially set to 0. Negative integer values are disallowed.
|
|
soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table.
|
|
soar_Learn -- This is the command procedure for the "learn" command. With no arguments, this command prints out the current learning status. Any of the following arguments may be given:
|
|
soar_Log -- This is the command procedure for the "log" command which records session information to a log file.
This command may be used to open and close log files. With the -add argument, specific strings can also be added to the log file.
|
|
soar_Matches -- This is the command procedure for the "matches" command. This command prints partial match information for a selected production. It also prints information about the current match set. The match set is a list of productions that are about to fire or retract in the next preference phase. With no arguments, this command prints out the production names for both Assertions and Retractions. The first optional argument specifies listing of either Assertions or Retractions. The last optional argument specifies the level of detail wanted: -counts (the default for single productions) prints out just the partial match counts; -names (the default for match sets) prints out just the production names; -timetags also prints the timetags of wmes matched; and -wmes prints the wmes rather than just their timetags.
|
|
soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed.
With no arguments, this command returns the current value of the system variable "max-chunks" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of chunks allowed in a single decision cycle. After this many chunks have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-chunks is initially 50.) The maximum number of chunks can also be limited by setting the soar variable max_chunks.
|
|
soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed.
With no arguments, this command returns the current value of the system variable "max-elaborations" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of elaboration cycles allowed in a single decision cycle. After this many elabloration cycles have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-elaborations is initially 100.)
|
|
soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use.
Information is displayed about the memory usage in tokens, of partial matches of productions. If a production-name is given, memory use for that production is printed. If no production name is given, memories will list 'count' productions of the specified type (or all types, if no type is specified). If 'count' is omitted, memory use of all productions is printed.
|
|
soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values.
If given, the value must be a positive integer > 1. The default is 10. If no args are given on the cmdline, the list of symbols that are multi-attributed is printed.
|
|
soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent).
It takes a single numeric argument:
|
|
soar_Operand2 -- This is the command procedure for the "soar8" command. With no arguments, this command prints out the current operand state. Otherwise it turns on or off soar8 mode.
|
|
soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing.
This command enables tracing of the firings and retractions of individual productions. (This mechanism is orthogonal to the watch -firings mechanism. See the "watch" command for more information. PWatch, with no arguments, lists the productions currently being traced. With one or more production name arguments, it enables tracing of those productions. Using the -on or -off option explicitly turns tracing on or off for the given productions. Tracing persists until disabled, or until the production is excised.
|
|
soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools.
pool-arguements: for -instantiation, one of: -none (no wme information) -full (full wme information) for -production, one of: -name (print production name only) -full (print entire production)
|
|
soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot.
This command prints all the preferences for the slot given by the 'id' and 'attribute' arguments. The optional 'detail' argument must be one of the following (-none is the default):
|
|
soar_Print -- This is the command procedure for the "print" command, which prints various Soar items.
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 objects are printed unless the -internal flag is used, in in which case the wmes themselves are printed.
-depth 0 is meaningful only for integer and pattern arguments. It causes only the matching wmes to be printed, instead of all wmes whose id is an id in one of the matching wmes. -name | -full apply to printing productions. For the specified production type, only the production name will be printed, unless the -full flag is specified. For named productions, the default is to print the entire production unless -name is specified. (-name for an individual prod seems silly, but it's included for completeness...) The -depth n, -internal, -name, and -full flags apply only to the args that appear after them on the command line.
The changes here to PrintCmd are meant to be more illustrative of how to provide a production's file name to the user than they are meant to be final changes to PrintCmd, which is undergoing concurrent work at this time. print -filename <production-name>+ |
|
soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic.
pf is a production finding facility. It allows you to find productions that either test a particular LHS pattern or produce particular RHS preferences. The syntax of the lhs-conditions or rhs-actions is exactly their syntax within SP's. In addition, the symbol '*' may be used as a wildcard for an attribute or value. Note that variable names do not have to match the specific names used in productions. Specifying -chunks means only chunks are searched (and -nochunks means no chunks are searched). Note that leading blanks in the clause will cause pf to fail.
Find productions that test that some object gumby has attribute ^alive t, and test an operator named foo: production-find {(<s> ^gumby <gv> ^operator.name foo)(<gv> ^alive t)} Find productions that propose foo: production-find -rhs {(<x> ^operator<op> +)(<op> ^name foo)} Find productions that test the attribute ^pokey: production-find {(<x> ^pokey *)} Find productions that test the operator foo production-find {(<s> ^operator.name foo)}
|
|
soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited.
|
|
soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent.
This command removes all wmes from working memory, wiping out the goal stack, and resets all statistics (except the counts tracking how many times each individual production has fired which is used by the "firing-counts" command).
|
|
soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory.
WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.
|
|
soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input.
Input originally obtained using the "capture-input" command is replayed with this command
|
|
soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network.
The rete-net is a binary file containing the contents of production memory. Because productions are decomposed into their constituent conditions before being added to the network, the productions themselves are difficult to recognize. Although this file format is not encrypted in any real sense, it does obfuscate productions to a degree similar to compilation of source code. Moreoever, if productions are saved as a rete-net, they can be loaded by a version of Soar which does not contain a productions parser (and supporting elements) this allows a significantly smaller footprint for the executable when memory is at a premium.
|
|
soar_Run -- This is the command procedure for the "run" command which runs the Soar agent.
This is the command for running Soar agents. It takes two optional arguments, one specifying how many things to run, and one specifying what type of things to run (by default all agents are run). The following types are available:
|
|
soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production.
This command adds a new production to the system. (If another production with the same name already exists, it is excised.) The optional flags are as follows:
|
|
soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information.
|
|
soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents.
|
|
soar_Verbose -- This is the command procedure for the "verbose" command. With no arguments, this command prints out the current verbose state. Any of the following arguments may be given:
|
|
soar_WaitSNC -- This is the command procedure for the "waitsnc" command. With no arguments, this command stores the current wait/snc state in the SoarResult. If this mode is on, soar waits (in its current state) for new things to happen. If it is off, then soar generates impasses when the state does not change.
|
|
soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages.
warnings -on enables the printing of warning messages. This is the default. warnings -off turns off most warning messages. warnings prints an indication of whether warning messages are enabled or not.
|
|
soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing.
This command controls what information gets printed in the run-time trace. With no arguments, it just prints out the current watch status. The numeric arguments are different from the semantics in Soar 5 and 6; for details, see help watch. Setting either the -on or -off switch selectively turns on or off only that setting. Setting the -inclusive switch (which can be abbreviated as -inc) or setting no flag at all has the effect of setting all levels up to and including the level specified. For example, watch productions -on selectively turns on the tracing of production firings/retractions; watch productions -off selectively turns it off again. watch productions [-inc] turns on the tracing of productions and also turns on tracing of all levels below productions: decisions and phases, too. Individual watch parameters may be used to modify the inclusive settings as well, selectively turning on or off and levels outside or inside the inclusive range. The following keyword arguments may be given to the 'watch' command:
|