- summary watch command documentation
Control the run-time tracing of Soar.
|| `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 || || `-g, --gds` || `remove` (optional) || Controls printing of warnings about wme changes to GDS || || `-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. || || `-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, gds, and decisions; equivalent to `-dpg` || || `3` || watch productions, phases, and decisions; equivalent to `-dpgP` || || `4` || watch wmes, productions, phases, and decisions; equivalent to `-dpgPw` || || `5` || watch preferences, wmes, productions, phases, and decisions; equivalent to `-dpgPwr` ||
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 [cmd_pwatch] command is used to watch
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) || || `print` || `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* || || `-a, --wma` || `remove` (optional) || Print log of working memory activation events || || `-b, --backtracing` || `remove` (optional) || Print backtracing information when a chunk or justification is created || || `-e, --epmem` || `remove` (optional) || Print episodic retrieval traces and IDs of newly encoded episodes || || `-i, --indifferent-selection` || `remove` (optional) || Print scores for tied operators in random indifferent selection mode || || `-R, --rl` || `remove` (optional) || Print RL debugging output || || `-s, --smem` || `remove` (optional) || Print log of semantic memory storage events ||
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):
Although the `--level` flag is optional, its use is recommended:
Be careful of where the level is on the command line, for example, if you want level 2 and preferences:
To turn on printing of decisions, phases and productions, do any one of the following (not all possibilities listed):
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):
To turn on printing of decisions, productions and wmes, and turns phases off, do any one of the following (not all possibilities listed):
To watch the firing and retraction of decisions and _only_ user productions, do any one of the following (not all possibilities listed):
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):
[cmd_epmem] [cmd_pwatch] [cmd_print] [cmd_run] [cmd_watch_wmes]