===================================  
Soar 8.5.2 Release Notes, June 2004  
=================================== 
We are pleased to announce that Soar Suite 8.5.2 is ready for the
Windows and Linux platforms! We expect this to be the last 8.5.x release.
Soar Suite 8.6.0, expected fall 2004, will be the next release and will
include gSKI/TgD.

*** Components included in this release: Soar Kernel 8.5.2, VisualSoar 4.5.3,
Eaters 3.0.8, TankSoar 3.0.8, DMGen 1.0.0, SoarDoc 0.9.3, SGIO 1.1.2,
Documentation (including Soar manual and tutorial).

*** Almost every component has been updated for this release, some
significantly. Please check out the release notes (available with the
installer
and on the web page).

*** All necessary Tcl/Tk files are included with the Windows version.
Linux
users will have to install Tcl/Tk, see installation notes for details.

*** Mac OSX is currently not available but will be soon.

*** Visit the Soar home page for news, documentation, and updates:
--> http://sitemaker.umich.edu/soar/
*** Report all Soar suite bugs using the Soar Bugzilla bug tracking
system.
Please do not use the trackers on SourceForge.net.
--> http://winter.eecs.umich.edu/soar-bugzilla/
*** Thank you to all who helped make this release possible!

     Summary of changes between SoarSuite 8.5.1 and SoarSuite 8.5.2
                         July, 2004

A summary of changes in SoarSuite 8.5.2 is listed immediately below. For
more
details, including changes not mentioned in the summary and a list of
known
issues see the Details section after the summary.

======================
New Windows Installer:
======================
The Windows installer is now built with a different technology which
is much easier for us and results in a much smaller package.

=========================
Several kernel bug fixes:
=========================
Almost all known bugs fixed, including all known crash bugs. See the
details section below for more information.

==================
New TankSoar Bots:
==================
TankSoar now comes with two new bots.  Mapping-bot demonstrates how a
tank might build up an internal map of the level.  Obscure-bot is a
challenge bot
for people to test their own bots against.  The code is provided in an
obfuscated
binary.  See obscure-bot.txt in the TankSoar agents directory for
details.

==========================
SoarDoc and DMGen updated:
==========================
These changes were actually in the the 8.5.1 release, but we failed
to note them.
SoarDoc:
 - Fixed special character handling when UseExistingComments is used.
 - Added ShowProdSourceInline which shows production source code
inline in the production documentation
 - Ability disable datamap node coloring
 - Fixed case-sensitivity issues for production names and list sorting.
DMGen:
 - Fixed handling of mixed-case production names.

======================
Documentation Updated:
======================
The tutorials have had some typo fixes and screenshot updates, and
also
explain substates better.

==================
Tcl Soar Debugger:
==================
The TSDebugger has several bug fixes which may have affected some
users.

===================
VisualSoar Updated:
===================
VisualSoar has several small bug fixes.

======================
Critical SGIO bug fix:
======================
Our fix for bug 254 in the last release actually caused serious
problems. This has been fixed for real now.

====================================================================
                        Details
====================================================================
Below is a fairly complete list of enhancements, changes, bug fixes, and
known
issues, with bug numbers for reference. For more information and up to
date list
of what's been fixed please visit the Soar bugzilla server at:

https://winter.eecs.umich.edu/soar-bugzilla/.

New bug submissions and enhancement requests are welcome!

Soar-8.5.2
==========
Bug Fixes
---------
353  stats command keeps recording between runs
389  missing error handling for set_watch_prod_group_setting

Enhancements
---------
358  change soar8 command error message

Known Issues
---------
312  agent structure isn't cleaned up properly
356  All matches get same support as last processed match

TSDebugger 4.0.1
================
Bug Fixes
---------
365  rules that contain a capital letter break productions tab
376  stop button doesn't work with Eaters, TankSoar 396  error when closing group from task bar
398  extra 0 gets printed when soar connected to environments

Known Issues
---------
336  negated conditions don't print properly in the console window
397  grouping bar in production tab not always right

SGIO 1.1.2
==========
Bug Fixes
---------
254  Some special characters in StringWME's do not transfer to Soar

Eaters 3.0.8
============
Bug Fixes
---------
391  garbage printed to debugger output when Stop After Decision Phase
is on

TankSoar 3.0.8
==============
Bug Fixes
---------
map loading menu now defaults to maps directory
188  Selecting Map->Random Map causes error message when agent present
on
 current map
392  garbage printed to debugger output when Stop After Decision Phase
is on
393  command 'run 1' generates 'invalid command step' error

Enhancements
---------
new challenge bot (obscure-bot) and mapping bot provided

Known Issues
---------
 
399  can't use reset tank command in tank control panel tanks menu

Documentation
=============
Bug Fixes
---------
349  tutorial images need to be updated
375  typo in tutorial part 1: move-north 
386  typos in tutorial part 1 (search control) 

Enhancements
---------
Added information to tutorial about substates.

Known Issues
---------
380  typo in section 5.6.3
381  o-support-mode command missing newest support modes

VisualSoar 4.5.3
================
Bug Fixes
---------

361  adding a dir that doesn't exist to agent path on file->new project
fails with no warning
362  initial rules in a project are not justified correctly
363  if project loaded then create new project, title bar does not
change
364  file with same name as datamap have same window names
366  Initialize-<task> Operator not in datamap
368  dragging node onto itself makes node disappear
372  fails to detect extra whitespace after :

Known Issues
---------
Too many to list. See bugzilla for details.

8.5.1
Summary of changes between SoarSuite 8.5.0 and SoarSuite 8.5.1
                         June, 2004
A summary of changes in SoarSuite 8.5.1 is listed immediately below. For
more
details, including changes not mentioned in the summary and a list of
known
issues see the Details section after the summary.

==================
Several bug fixes:
==================
Almost all known bugs fixed, including all known crash bugs. See the
details
section below for more information.

======================
Documentation Updated:
======================
The manual has been updated to include appendices on the BNF grammar
for Soar's syntax, the calculation of O Support, the resolution of
preferences
and the Goal Dependency Set, as well as many other small changes. The
manual
is also now searchable, and the table of contents has links to the
associated
sections. Finally, the tutorial has been reorganized.

==================================
New Tcl Soar Debugger (TSI 4.0.0):
==================================
The Tcl debugger, TSI, has undergone a major revision, improving its
intuitiveness and presentation of information dramatically. For more
details,
see the TSI 4 Tour documentation.

=======================
Updated Version of Tcl:
=======================
The system has been tested with the latest version of Tcl, 8.4.6, and
the Windows distribution ships with this version included.

========================
Learning Off by Default:
========================
In previous versions of Soar, learning was turned on by default. This
could be a source of confusion and frustration since most users do not
intend to
have learning on. Thus, starting with Soar 8.5.1, learning is turned
off.

====================================
O Support Mode 4 is now the Default:
====================================
O Support Mode 4 was introduced in Soar 8.5.0, and starting with Soar
8.5.1 it is now the default mode. Those requiring other modes (i.e. for
compatibility) can switch to them using the o-support-mode command.
 O Support Mode 3 (the default mode in Soar 8.3 - 8.5.0) is meant to
give I-Support to elaborations of the operator.  At certain times,
these elaborations were not detected as such, and received O-Support.
Soar 8.5's O Support Mode 4 can overcome these problems by detecting
more operator elaborations.  However, it also makes the following change
from O-Support Mode 3:
 mixed productions (i.e. operator applications + operator elaborations)
now receive i-support instead of o-support.  Running with 'warnings -on'
will print messages when any such productions fire.  You should try
to be careful not to build any such mixed productions when using
o-support mode 4
 While O Support Mode 3 remains the default for this release, this is
for backwards compatibility only.  It is recommended that O Support Mode
4 is
used from now on; in a future release, O Support Mode 4 will be the
default.

======================
New Interrupt Command:
======================
Soar 8.5.1 now allows matchtime interrupts to be turned on and off at
runtime. Matchtime interrupts were introduced in Soar 8.5.0 (see
immediately
below for details). The syntax for the interrupt command is:

 interrupt [-on|-off] [production name]
If the -on or -off switch is used without a production name, then the
list of all productions with interrupts turned on or off is given. If
the
production name is used without the -on or -off switch, then the
interrupt
status of the production is given.

Soar 8.5.0 introducted support for interrupting execution at
production
match-time in addition to interrupts when a production matches.  This
new
capability makes it possible to examine Soar's state before the
production
fires, and even makes it possible to excise the production that matches
before
its effects are realized.  To use the matchtime interrupt feature,
productions
must add the ':interrupt' directive as in the following example
production:

sp { interrupt*on*application
          :interrupt
    (state <s> ^operator.name stop)
 -->
        (write (crlf) |I've already Halted|)}

Note that supporting this feature adds a small amount of computational
overhead
to the match phase.  If you desire a maximally streamlined version of
Soar,
recompile /without/ the MATCHTIME_INTERRUPT flag in soarBuildOptions.h

===================
VisualSoar Updated:
===================
VisualSoar has undergone several usability improvements for this
development
iteration.  Key among these are:
 - highlighting code for the user that has been identified
as the cause of a syntax error, datamap error or text search.
 - improvements to window focus, size and positioning.  In the past,
VisualSoar has been a little too "bullheaded" about enforcing the
default display type of tile mode.  Users who maximize windows or
cascade them will find VS easier to manage.
 - some additional search capabilities.  In particular, it's easy to
find code corresponding to entries in the datamap and also easy to
find the datamap that goes with particular code.  You can also
limit your text searches to specific operator subtrees.
 - Finally, VisualSoar has been made compatible with MacOS.

====================================================================
                        Details
====================================================================
Below is a fairly complete list of enhancements, changes, bug fixes, and
known
issues, with bug numbers for reference. For more information and up to
date list
of what's been fixed please visit the Soar bugzilla server at:

https://winter.eecs.umich.edu/soar-bugzilla/.

New bug submissions and enhancement requests are welcome!

Soar-8.5.1
==========
Enhancements
---------
186  New interrupt command

Changes
-------338  turn off learning by default
339  default o-support-mode changed from 3 to 4
351  some demos need to be updated

Bug Fixes
---------
139  Soar crashes when it spends some time in a state no-change substate
204  Soar crashes when multiple agents are running and one of them halts
or
 reaches an interrupt
213  GDS crashes when backtracing through result WMEs
214  fixed behavior of "monitor -delete" command
274  operator treated as keyword even when not attached to a state
154  Print message explaining that can't save RETE when justifications
are
 present.
311  extra newline in Soar output
278  o-support mode 3 & 4 do not correctly identify mixed
 elaboration-application productions
194  warnings when running demos in O Support Mode 4
357  o-support determination fails to recognize operator elaboration
355  New GDS bug

Known Issues
---------
312  agent structure isn't cleaned up properly
353  stats command keeps recording between runs
356  All matches get same support as last processed match

TSI 4.0.0
=========
Enhancements
---------
Too many to list -- really rewritten to a large extent.

Bug Fixes
---------
215  Learn settings printed in log when stepping
206, 211, 212  The output of some commands wasn't redirectable, causing
problems
 in the TSI
192  wish.exe process doesn't go away sometimes

Known Issues
---------
327  bottom of phase graphic is cut off in non-minimal views
336  negated conditions don't print properly in the console window

SGIO 1.1.1
==========
Bug Fixes
---------
254  Spaces and $'s in StringWME's do not transfer to Soar

Eaters 3.0.7
============
Bug Fixes
---------
197  Eaters sets TSI version number

TankSoar 3.0.7
==============
Enhancements
---------
352 updates to default agent

Bug Fixes
---------
196  TankSoar sets TSI version number

Known Issues
---------
 
188  Selecting Map->Random Map causes error message when agent present
on
 current map 
151  Can't use run <n> command in TankSoar 

Documentation
=============
Enhancements
---------
343  Make manual searchable
344  Make table of contents into links
350  reorganize tutorials
341  Preference resolution appendix needs updating
345  section 1.3: "contacting the Soar group" is outdated
348  need GDS description
340  BNF grammar appendix needs to be updated
342  o-support appendix needs to be updated

Known Issues
---------
349  tutorial images need to be updated

VisualSoar 4.5.2
================
Enhancements
---------
3    Expand datamap as it is being generated.
37   Document all shortcut and key bindings.
48   Search / replace should highlight the line found
53   VS doesn't display new windows in size/position that is intuitive
91   Parse error should highlight offending line.
92   Remove parse error pop up dialog and place all errors in feedback
pane
93   Allow separate syntax and datamap checks.

100  Change template default from "01" to Op1" to reduce confusion
159  The save operation should always save the entire project
171  agent name in title bar
222  Better tab-formatting for multiple values on separate lines
225  Allow searching within a specific operator subtree
255  IO Error message fails to specify filename that caused the error
263  Syntax error should not popup dialog when checking productions
265  Find productions that use a particular datamap WME
333  Should be able to generate datamap for just one file

Bug Fixes
---------
90   Undo should move the cursor (and display) to what is being undone
106  Better tab-formatting after a comment and after a condition
122  If you close an editor window another window does not become active
128  The neon green color used in data map verification is very annoying
131  Opening a new project should close old
133  Close project menu options don't invoke same dialog as close button
153  VisualSoar broken on Mac OS X
177  Fix spelling and capitalization errors in VS menu
199  The KnownIssues.txt file should be removed from the CVS archive
200  VS contains deprecated function calls
205  Runtime menu should be deactivated when the library is absent
220  New file windows should receive focus
228  Syntax coloring is incorrect for ".{"
250  Syntax coloring is incorrect for { ... } { ... }
262  Operator with a non-enumeration named "name" causes crash

Known Issues
---------
Too many to list. See bugzilla for details.

8.5.0
Soar 8.5.0 is now available for Windows platforms and Linux! Mac OSX support is forthcoming. Download the installer (Win32) or tarball (Linux) and get installation instructions here: http://sitemaker.umich.edu/soar/soar_software_downloads
Release notes for Soar Suite 8.5
For the Win32 platform, all Soar components are hosted on
SourceForge?.Net in one installer. A Linux tarball is also available at the same URL. http://sourceforge.net/projects/soar/
The Soar web site has been redesigned and moved to a new location.
Links to the old site should redirect to the new site. http://sitemaker.umich.edu/soar/
VisualSoar? has been updated for this release with many bug fixes and
is available for the Win32 platform (VisualSoar? support for Linux and Mac OSX is forthcoming).
The Soar manual has been updated and is included in the installer.
Per a renewed commitment to bug fixing in Soar, the Soar project now
uses Bugzilla for bug tracking and feature requests. All bug tracking and feature requests should be posted using the new Soar Bugzilla and not with SourceForge?.Net's trackers. http://winter.eecs.umich.edu/soar-bugzilla
New SoarDoc? and DataMap? Generator tools from Soar Technology are
included with this Soar 8.5.0 release http://www.eecs.umich.edu/~soar/sitemaker/projects/soardoc/soardoc.html
Major changes for Soar 8.5.0:
All known crashes fixed.
Numeric indifference preferences added.
8.3.5 and 8.4.5 have been merged, only one version of Soar is
needed now.
All Soar components have been combined into one installer.
Updated for latest version of Tcl/Tk (8.4.4).
Various bug fixes, see CHANGES for details
This release was made possible by: Mazin Assanie, Karen Coulter,
John Laird, Bob Mariner, Shelley Nason, Andrew Nuxoll, David Ray, Jonathan Voigt, Robert Wray and Soar Technology.
Summary of changes between Soar 8.4.5 and Soar 8.5. Scott Wallace August, 2003
The change from Soar8.4.5 to Soar8.5 introduces some new features, and bug fixes. Below is a brief summary of the salient changes (all modifications have been verified with the soar-8.5-test-suite which is released independently from this source code).
Operator No Changes
In Soar 8.4.5, Operator No Changes were identified agressively by the architecture. This meant that they could be created before the end of the decision cycle. In some situations, this led to odd behavior, notably within some of the tutorial lessions. As a result, this behavior has now become a compile-time option and is no longer included in the deafult-builds. If you desire Soar with aggressive no changes, simply add the AGRESSIVE_ONC flag to soarBuildOptions.h and recompile.
MatchTime? Interrupt
Soar 8.5 now supports interrupting execution at production match-time in addition to interrupts when a production matches. This new capability makes it possible to examine Soar's state before the production fires, and even makes it possible to excise the production that matches before its effects are realized. To use the matchtime interrupt feature, productions must add the :interrupt directive as in the following example production:
sp { interrupt*on*application
:interrupt
 (state <s> ^operator.name stop)
-->
 (write (crlf) |I've already Halted|)
}
Note that supporting this feature adds a small amount of computational overhead to the match phase. If you desire a maximally streamlined version of Soar, recompile /without/ the MATCHTIME_INTERRUPT flag in soarBuildOptions.h
Reject Preferences
Earlier versions of Soar processed all reject preferences after acceptable preferences. One of the unintuitive side effects of this is that when a user wants to change the value of a wme, they typically need to test that its current value is not equal to the new value. As a first attempt to alleviate this artifact, by default Soar 8.5 changes the order in which preferences are evaluated by examining O-Supported Reject preferences first thus (^cheese-type cheddar - chedder +) will result in the wme (... ^cheese-type cheddar) remaining in working-memory. Note that this may have some unanticipated consequences, and can be turned off be undefining the O_REJECTS_FIRST flag in soarBuildOptions.h and recompiling.
Cmdline Interface Parser
Now appropriately parses strings containing the '#' character.
Run Till Output
In Soar 8.3 - 8.4.5, if an output command was issued in the first decision-cycle, it would not be appropriately detected. As a result, if Soar was instructed to run until output, and output occured on the 1st decision cycle, Soar would continue running for 15 decision cycles before returning control to the user. This bug was most often noticed using simple agents in TankSoar?, and is now fixed in Soar 8.5.
O Support Mode 4
O Support Mode 3 (the default mode in Soar 8.3 - 8.5.0) is meant to give I-Support to elaborations of the operator. At certain times, these elaborations were not detected as such, and received O-Support. Soar 8.5's O Support Mode 4 can overcome these problems by detecting more operator elaborations. However, it also makes the following change from O-Support Mode 3:
mixed productions (i.e. operator applications + operator elaborations) now receive i-support instead of o-support. Running with 'warnings -on' will print messages when any such productions fire. You should try to be careful not to build any such mixed productions when using o-support mode 4
While O Support Mode 3 remains the default for this release, this is for backwards compatibility only. It is recommended that O Support Mode 4 is used from now on; in a future release, O Support Mode 4 will be the default.
Numeric Indifference Preferences
Soar 8.5 has better capabilities to support behavioral diversity than previous versions of Soar. The difference stems from Soar 8.5 numeric indifferent preferences that allow operators to be assigned weights along with the '=' preference. In the event of a tie, the indifference selection mechanism is invoked. In previous versions of Soar, the probability of selecting any of the tied operators was distributed evenly among the candidates (assuming the indifferent-selection mode was 'random'). Soar 8.5's numeric indifferent preferences allow the programmer to skew this distribution such that certain operators are chosen more or less frequently. Preferences are specified simply by adding an integer or float value following an operator's '=' preference. As in the example below:
sp { example
 (state <s> superstate nil -initialized true)
-->
 (<s> ^operator <o> + = 30)
 (&lt;o&gt; ^name initialize-a)
}
Two algorithms are available via a run-time switch:
numeric-indifferent-mode -avg
Here, we calculate the 'average' preference value associated with a particular operator. Thus, if preference A for operator X has value 30 while preference B for operator X has value 60, the average will be 45. Once this value has been calculated for all competeing operators, we sum their average preferences and select a random number between 0 and this sum. Each operator is associated with a range on this scal equal to its average numeric preference. Thus, the randomly selected number can simply be mapped back to an operator that then becomes for 'selected' operator for the current decison. In average mode, indifferent preferences without a numeric value are given the default value of 50 for selection purposes. For programmers, we expect that this mode of numeric-indifferent selection will be most intuitive. Note however, that this scheme doesn't make a lot of sense for preferences are less than zero. If an operator's average value is ever below zero, Soar will print a warning indicating this situation. As an initial recommendation, we suggest using values between 0.0 and 100.0 for your operators.
numeric-indifferent-mode -sum
Here, the preferences for each operator are first summed. Thus, if preference A for operator X has value 30 while preference B for operator X has value 70.5 the sum will be 100.5. This sum is calculated for all competing operators. Next, we calculate: e ^ (preference_sum / agent_temperature) where agent_temperature is a compile time constant currently set at 25.0 We'll call this value the operator's final numeric preference. Finally, we sum all the competing operator's final numeric preferences and select a random number between 0 and this sum. Each operator is associated with a range on this scale equal to the size of its final numeric preference. Thus, the randomly selected number can simply be mapped back to an operator that then becomes the 'selected' operator for the current decision. In the sum mode, indifferent preferences without a numeric value are given the default value 0.0 for the selection purposes. Note it does make sense to use this methodology even if the numeric preferences are negative, however, because the numeric preference are used in exponientation, their values should be somewhat limited so floating-point overflow does not become a problem. We expect this sum mode to be more useful for future reinforcement-learning methods, and have included it here mainly for experimental purposes.
Timer Warnings
Timer warnings are not displayed unless the following are true:
Soar was compiled with the WARN_IF_TIMERS_REPORT_ZERO flag
at runtime, the 'warnings' sysparam is set to TRUE (as with the
'warnings -on' command
Other changes for Soar 8.5 made after the above document was written:
Removal of many depricated Tcl/Tk functions, upgrading them to
Tcl/Tk 8.4.4.
Various stability enhancements, including:
Kernel now uses snprintf() instead of sprintf() whenever possible.
Kernel now uses strncpy() instead of strcpy() whenever possible.
Kernel now uses strncat() instead of strcat() whenever possible.
'verbose' command bug fix, it was not working as documented when
multiple agents were active.
'init-soar' kernel crash fixed in both Eaters and TankSoar?.
MSVC and GCC warning levels moved to maximum, all warnings silenced.
Logging bug fixed, did not work properly with multiple active
agents.
'indifferent-selection -ask' command fixed.
Decision cycle bug fix.
All demos are in VisualSoar? format now.
Fixed a kernel crash related to justifications.