-
Notifications
You must be signed in to change notification settings - Fork 78
cmd_soar
Commands and settings related to running Soar
====== Soar General Commands and Settings =====
soar ? Print this help listing
soar init Re-initializes current state of Soar
soar stop Stop Soar execution
----------------- Settings --------------------
max-elaborations 100 Maximum elaboration in a phase
max-goal-depth 23 Maximum goal stack depth
max-nil-output-cycles 15 Used with run --out
max-dc-time 0 Maximum time per decision
max-memory-usage 100000000 Maximum memory usage
max-gp 20000 Maximum rules gp can generate
stop-phase apply Phase before which Soar will stop
wait-snc off Wait after state-no-change
---------------------------------------------
To change a setting: soar <setting> [<value>]
For a detailed explanation of these settings: help soar
Using the soar command without any arguments will display a summary of Soar's
current state of execution and which capabilities of Soar are enabled:
=======================================================
Soar 9.6.0 Summary
=======================================================
Enabled: Core, EBC, SMem, EpMem
Disabled: SVS, RL, WMA, SSA
-------------------------------------------------------
Number of rules: 52
Decisions 20
Inferences 61
-------------------------------------------------------
State stack S1, S21 ... S29, S33
Current number of states 5
Next phase apply
For a full list of sub-commands and settings: soar ?
soar init
The init-soar command re-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.
soar stop [--self]
The stop 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. The --self option will stop only the soar agent where the command
is issued. All other agents continue running as previously specified.
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).
Note that if a graphical interface doesn't periodically do an "update"/flush the pending I/O, then it may not be possible to interrupt a Soar agent from the command line.
Invoke a sub-command with no arguments to query the current setting. Partial commands are accepted.
| Option | Valid Values | Default |
|---|---|---|
max-dc-time |
>= 0 | 0 |
max-elaborations |
> 0 | 100 |
max-goal-depth |
> 0 | 23 |
max-gp |
> 0 | 20000 |
max-memory-usage |
> 0 | 100000000 |
max-nil-output-cycles |
> 0 | 15 |
o-support-mode |
3 or 4 | 4 |
stop-phase |
apply | |
wait-snc |
>= 1 | 1 |
'max-dc-time' sets a maximum amount of time a deicsion cycle is permitted. After output phase, the elapsed decision cycle time is checked to see if it is greater than the old maximum, and the maximum dc time stat is updated (see stats). At this time, this threshold is also checked. If met or exceeded, Soar stops at the end of the current output phase with an interrupted state.
'max-elaborations' 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 'max-goal-depth' command is used to limit the maximum depth of sub-states. The initial value of this variable is 100; allowable settings are any integer greater than 0. This limit is also included in Soar to prevent getting stuck in an infinite recursive loop, which may come about due to deliberate actions or via an agent bug, such as dropping inadvertently to state-no-change impasses.
'max-gp' 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.
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.
'max-nil-output-cycles' 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 '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.
'stop-phase' allows the user to control which phase Soar stops in.
When running by decision cycle it can be helpful to have agents stop at a
particular point in its execution cycle. 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.
'wait-snc' controls an architectural wait state. On some systems, especially those that model expert 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.
init-soarinitisinterruptssstop
soar init
soar stop -s
soar stop-phase output // stop before output phase
soar max-goal-depth 100
soar max-elaborations
init soar init
is soar init
init-soar soar init
interrupt soar stop
ss soar stop
stop soar stop
stop-soar soar stop
gp-max soar max-gp
max-dc-time soar max-dc-time
max-elaborations soar max-elaborations
max-goal-depth soar max-goal-depth
max-memory-usage soar max-memory-usage
max-nil-output-cycles soar max-nil-output-cycles
set-stop-phase soar stop-phase
waitsnc soar wait-snc