NAME

stats - Print statistical data about Soar

SYNOPSIS

stats [-system [stat] | -memory [stat] |-rete [stat]]

DESCRIPTION

This command prints Soar internal statistics. The module indicates the component of interest. If specified, module must be one of -system, -memory, or -rete. If no specific stat is given for the specified module, then all statistics are listed for that module. If no module is given, then the -system statistics are listed.

The -system module contains the following stats:

-default-production-count
-user-production-count
-chunk-count
-justification-count
-all-productions-count
-dc-count
-ec-count
-ecs/dc
-firings-count
-firings/ec
-wme-change-count
-wme-addition-count
-wme-removal-count
-wme-count
-wme-avg-count
-wme-max-count

If Soar has been compiled with the NO_TIMING_STUFF NOT set, then the following statistics are also available in the -system module:

-total-time
-ms/dc
-ms/ec
-ms/firing
-ms/wme-change

If Soar has been compiled with the DETAILED_TIMING_STATS SET, then the following statistics are also available in the -system module:

-match-time
-ownership-time
-chunking-time

The -memory module contains the following statistics:

-total
-overhead
-strings
-hash-table
-pool pool-statistic
-misc

The -pool statistic is additionally qualified by a pool-statistic option. If this option is not given, then all -memory pool statistics are printed. If given, pool-statistic must have one of the following forms:

-total
Print just the overall totals for the pools
pool-name [aspect]
Print statistics about the specific pool pool-name. The permissable pool-names are:
     chunk condition
     io wme
     output link
     preference
     wme
     slot
     instantiation
     ms change
     right mem
     negative token
     token
     node varnames
     rete node
     rete test
     alpha mem
     saved test
     not
     action
     production
     condition
     complex test
     float constant
     int constant
     sym constant
     identifier
     variable
     dl cons
     cons cell

If no aspect is given, then print all statistics about the given pool. If given, aspect must have one of the following forms:

     -used
     -free
     -item-size
     -total-bytes
The first two aspects are available only if Soar has been compiled with MEMORY_POOL_STATS SET.

The -rete module contains statistics for the following node types:

unhashed memory
memory
unhashed mem-pos
mem-pos
unhashed negative
negative
unhashed positive
positive
dummy top
dummy matches
conj. neg.
conj. neg. partner
production
total
The total statistic gives a total count over all node types.

A -rete statistic is obtained by specifying one of the above nodes followed by a qualifier. The qualifier is one of -actual, -if-no-merging, and -if-no-sharing. The -if-no-sharing option is only available if Soar has been compiled with the SHARING_FACTORS option SET.

EXAMPLES

This prints all statistics in the -system module:
stats -system

This prints the number of io wme's:

stats -memory -pool {io wme} -used
Note that this particular pool name, "io wme", contains an embedded space character. Hence, the name must be surrounded by curly braces or double quotes to override the normal Tcl parsing of words separated by whitespace. This is not necessary for pool names that do not include spaces:
stats -memory -pool wme -used

This prints the actual number of unhashed negative nodes in the Rete memory:

stats -rete {unhashed negative} -actual

A NOTE ON TIMERS

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
total kernel time
phase kernel time (per phase)
phase callbacks time (per phase)
input function time
output function time

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.

FILES

soarkernel.h