====================================
Soar 9.4 Release Notes, October 2014
====================================

This release of Soar includes the the much anticipated Soar Spatial Visual
System (SVS), various important bug fixes, new commands for semantic memory, a
new command to set interrupts on productions at run-time, a new chunk naming
scheme, and an automated mechanism to convert old semantic and episodic memory
databases to the newest format and a lot of code clean-up/refactoring. SVS and
all learning mechanisms are off by default.

Soar can be downloaded by following the download link on the Soar home
page at:

http://soar.eecs.umich.edu/articles/...ads/soar-suite

Soar releases include source code, demo programs, and a number of
applications that serve as examples of how to interface Soar to an
external environment. There is support for integrating Soar with C++,
Java, Tcl and Python applications. Many tools that aid in development
of Soar programs are also available. The download section of the web site
allows you to browse and download all of the
different distributions, tools and agents.

Help and Contact information

You can find many helpful resources on the Soar home page at:

https://soar.eecs.umich.edu

To contact the Soar group, you may join and post to one of our mailing
lists:

For general Soar-related discussion and announcements:

soar-group@lists.sourceforge.net

For more technical developer discussion:

soar-sml-list@lists.sourceforge.net

Also, please do not hesitate to file bugs on our issue tracker:

https://github.com/SoarGroup/Soar/issues

To avoid redundant entries, please search for duplicate issues first.

=================
Important Changes
=================

(1) Soar now includes the Spatial Visual System.
- This component allows agents to reason about the spatial relationship
between objects.
- This component was based on a developmental version but has been
significantly updated.
- Fully integrated into the latest version of Soar
- Now works on all platforms
- Can be enabled and disabled like other sub-modules
- Old obsolete filters removed
- All the latest filters from current research added
- Lots of code clean up and refactoring
- Lots of bug fixes
- Quicker to build and rebuild
- SVS is off by default.

(2) Soar will now silently load a 'settings.soar' in every agent created. This
allows you to set personal global settings and aliases for your Soar environment
that will persist across runs.
This is an especially useful new feature for TclSoarLib users, as it
provides a way to activate tcl interpreting from initial launch. This
allows users to immediately source files on launch that contain tcl code.

(3) New semantic memory utility commands:
'smem --remove'
Remove concepts from semantic memory manually.
'smem --query'
Manually search for a concept that matches a cue.
'smem --history'
Show the activation history of a concept in semantic memory.

(4) By default, chunk names use a new naming scheme. They are now based on the
rule that created the result rather than type of impasse.
For example, in Soar 9.3.2 a chunk may be named
'chunk*impasse*state*no*change*3'
while in Soar 9.3.3, it would be called something like
'chunk*my-create-result*d3-2'
- That name indicates (a) that the rule 'my-create-result' is the matched
rule which resulted in the chunk, (b) that it was created at decision
cycle 3 and (c) was the second chunk created at that decision cycle.
- Note that if a chunk is created based on another chunk, the prefix of the
chunk-name will be something like chunk-2*my-create-result*d12-1,
instead of chunk-chunk*my-create-result*d12-1.
- The chunk naming scheme can be changed back to the old mechanism via the
command
'chunk-name-format --long'
- The other two naming conventions are '--numbered' and '--rule' (default)

(5) New 'pbreak 'command has been added to set interrupts on a production at
run-time.
'pbreak' [--set|--clear] <rule-name>: sets or clears an interrupt on a rule
'pbreak' [--print]: prints all rules that have interrupts set

(6) For both episodic and semantic memory, the 'append-database' parameter has
been shorted to 'append'.

(7) If a user switches file mode or path parameters when a database is already
open, Soar will warn users that they must do a smem --init or epmem --init
command to finalize settings.

(8) Soar will now automatically convert semantic and episodic memory databases
from the old schema to the new (9.3.2 and below used the old schema).

(9) When printing a single LTI, Soar will no longer print a verbose header.

(10) Some user interface feedback will no longer have an SMem or EPmem prefix.
This will be no longer necessary when output manager handles in 9.5.

(11) Soar will now always tell the user when erasing the contents of an episodic
or semantic memory store, regardless of whether in file or memory mode.

(12) Epmem will now warn that it cannot append to an in-memory database.

=========
Bug Fixes
=========

(1) Fixed bugs where some epmem and smem commands crashed Soar if performed
before the first use of database. Those commands will now try to attach to the
database first.

(2) Fixed bug where memory corruption and crashing could occur when semantic
memory tried to access a preference that no longer existed. (Issue 176)

(3) Fixed bug where smem statistics of node and edges were becoming corrupted
after init-soar or smem --init

(4) Fixed bug where using multiple printing functions that used the agent's
temporary string buffer would produce incorrect, duplicate output. Printing
functions that used that buffer now use output manager version that rotates
between several string buffers.

(5) Fixed potential resource leak that could occur when a file was not closed
after a memory allocation or file read failed.

(6) When printing from semantic memory, Soar will now add pipe symbols around
string constants that may appear to be identifiers. (Issue 182)

(7) When printing from semantic memory, Soar will now add pipe symbols around
attributes that have spaces in them. (Issue 185)

(8) Fixed potential bug with fake architectural instantiations that had a few
uninitialized variables.

(9) Fixed bug that could cause crash Soar if production creates an operator
with a string value rather than an identifier.

(10) Soar will now properly wrap lines at 80 characters again.

===========================
Technical Changes and Fixes
===========================

(1) Soar code is now hosted on github
- Code that generates the Soar manual now pulls from github repository.
- Projects are now all separate repos

Note: Github has trouble displaying history for files that are moved or
renamed. For example, if you look at the SVS history on github's
web interface, you'll see only one commit. The commit history on
the actual SVS folder does exist in the repository but is not
viewable on github. This is a known github limitation that they
are apparently working on. Other git interfaces, like the one in
Eclipse, are also be affected. Using the command line or a more
robust interface like SourceTree will allow you to see the full
history of commits for those files and directories.

(2) Standardized formatting for all C++ files.
- Formatting style now used in Soar code documented in the Contributions.md
file
- Fixed all non-unix line feeds

(3) Symbol refactoring
- Symbol struct changed from a large struct containing a union of
sub-structs into a more object-oriented model. There are now five
different structs for each symbol types that inherit from a base
symbol struct. This is a major refactoring and eliminates need for
the common macro that was previously used to access symbol data common
to all symbol type.
- Many symbol-related functions now member functions of symbol struct

(4) Removed crusty code
- Removed all USE_MACROS, all USE_TCL, all USE_X_DISPLAY and some _cplusplus
deprecated code blocks.
- Removed obsolete references to Soar 6.
- Removed comments that were obsolete or add little value

(5) Standardized conventions
- Removed Bool typecast and standardized to built-in bool.
- Removed use of TRUE/FALSE and standardized to built-in true/false.
- Consolidated all agent variable/parameter names to use thisAgent

(6) Reorganized code
- Moved random functions from utilities to better places.
- Added test.cpp, stats.cpp, rhs.cpp
- Eliminated gdatastructs.h, utilities.h, soarkernel.h
- Renamed io.soar to io_soar to match its header file
- Consolidated a lot of scattered #defines to kernel.h, so developers can
see in one place what can be changed. May make compile time longer
when changing one of these settings, but most people aren't likely to
do that often. Making them more visible seems like a worthwhile
trade-off.
- Consolidated many enums into enums.h
- Improved includes and more forward declarations to eliminate includes

(7) Main scons script now has --tcl parameter to specify a custom path to Tcl
when compiling TclSoarLib or the Tcl SWIG interface.

(8) Main scons script now has --scu flag to be explicit about using single
compilation units (default).

(9) Various include issues that prevented non-scu builds on some platforms have
been fixed.

(10) Bug fixed that was breaking LSB builds in non-scu compilations.

(11) CSharp SWIG interface should build again.

(12) Main scons script will report and handle issues with the MSVC compiler
better.

(13) New episodic memory and SVS unit tests have been added.

(14) Soar will now properly build on Macs with non-Apple JDK.