run¶
Begin Soar's execution cycle.
Synopsis¶
Options¶
| Option | Description |
|---|---|
-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. |
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 |
Deprecated Run Options¶
These may be reimplemented in the future.
| Option | Description |
|---|---|
--operator |
Run Soar until the nth time an operator is selected. |
--state |
Run Soar until the nth time a state is selected. |
Description¶
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'. If both are unspecified, Soar will run until either a
halt is executed, an interrupt is received, or max stack depth is reached.
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:
| Option | Description |
|---|---|
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 |
Setting an interleave size¶
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,
even though the run command issued is for 5 decisions. Some use cases include:
| Option | Description |
|---|---|
run -d 5 -i 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 -i 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.
Note¶
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.