			       SimTime
			     User's Guide
		   by Greg Nelson (ghn@cs.cmu.edu)
			   Tue Jun  1 1993
			       
The SimTime package for Soar-6 is intended to provide some of the
capabilities of Mark Wiesmeyer's EDT (Event and Decision Timing)
package that was available in Soar-5.  SimTime may be used in a
limited way without any knowledge of C language programming, but to
capture its full power it is necessary to be able to write Soar-6 I/O
code in C.  Without the addition of at least a little C code, SimTime
is exclusively an *input* tool, though it has some features which are
targeted at people who would use it for output as well.


DESCRIPTION
The SimTime system simulates the passage of real time (hence the name)
as a function of the cognitive behavior of your Soar model.  In order
for SimTime to monitor the time, you must tell it the initial time for
your simulation in either of two ways, and how it should increment the
time (there are also several ways to do this).  Then, you must tell it
how your system wishes to use or respond to the passage of time.

The simplest way to set the initial time is to use the command
'simtime set <num>', where <num> is an integer value in whatever units
you wish to use (milliseconds is traditional).  It is also possible to
place an initial time at the beginning of the "event-list", which will
be described later.  In the former case, you must explicitly reset the
time when you wish to give it a new value; in the latter, it will be
automatically set when you perform an init-soar.

The description of how SimTime should increment the time is given to
SimTime as a "timing-list".  In this file, which is read in with a
separate command, each operator may be given an independent duration.
Or, the special term "OPERATOR" may be used to specify a time for all
operators, regardless of their name.  Alternately, the special terms
"ELABORATION" and "DECISION", if included, give a base time to be
added for each elaboration cycle and decision cycle, respectively.
These methods may be employed in any combination; their effects will
be additive.  Negative operator durations are legal, but of
questionable value, unless the elaboration/decision mechanism is being
used as well.  (And, more technically, events are not guaranteed to
execute in predictable ways if the time value ever decreases.)

Finally, there are a few different ways in which the system may use
the time value.  By issuing the command 'simtime wme on', a working
memory element containing the current time value will be deposited
into the top state of your Soar model.  While this breaks the
world/brain barrier, it may be a convenient way of using the time
value to perform interesting processing within your model, through
elaboration productions for instance.

A less controversial mechanism allows external events happen at
specified times, which may also place information into working memory.
There are again two options here, a less powerful but standard
mechanism and a more powerful mechanism that requires you to write
your own C code.  You can define event names which may then appear in
the event-list that is read in from a file.  Once these events are
defined and tied to C functions that implement them, you can readily
change the series of events that happen during any given Soar run.
However, if you don't wish to write C code, the special events ADD-WME
and REMOVE-WME are defined to let you get something small running
quickly. (You may use these names for your own events, in which case
these defaults will be overshadowed.)  The syntax for these events is: 
  ADD-WME <wme-id> <id> <attribute> <value>
  REMOVE-WME <wme-id>

The <wme-id> is an arbitrary string (no spaces or tabs) which allows
you to identify a WME you create so that you may remove it later.  The
<id> is either the constant "top-state" or a variable in the standard
SP format, i.e. <var1>.  The <attribute> name must be a symbolic or
integer constant.  The <value> may be a variable or a symbolic or
integer constant.  Any variables found for id's or values will be
given a new identifier; if two instances of the same variable appear,
they will be given the same identifier.  A brief run-time error
message will be printed if you try to remove a WME that you never
added or that you already removed, or if the syntax of either command
is incorrect.

There is another mechanism which allows you to use the SimTime system
to help you monitor resource constraints within a CPM-style cognitive
model.  Calling the command CPM_schedule_resource from an output
function will add a working memory element to the top state with the
attribute ^resource-in-use and a value specified as its first argument
(a string), for a duration specified as the second argument.  This WME
will automatically disappear after the specified duration.

You can also have SimTime log all of the above events to a file, which
you can then use to review when various external and internal events
occurred in relation to one another.

COMMAND SET
You will also need to know the possible commands available in this
interface.  They are:

  simtime
    Just give status report.
    
  simtime on
  simtime off
    Turn the system on (off) so that events will occur (not occur).
    
  simtime print always
  simtime print changes
  simtime print off  
    Turn printing on or off.  "always" prints once per decision cycle;
    "changes" prints every time the value changes.

  simtime wme on
  simtime wme off
    Turn direct time-stamping of wme on or off.  If this is on, the
    ^real-time attribute of the top state will be updated to reflect
    the simulated real time as it changes.
    
  simtime set <num>
    Set the current time to the specified value.
    
  simtime events "filename"
    Load the list of events from the specified filename.
    
  simtime timing "filename"
    Load the list of time accounting methods from the specified filename.

  simtime cpm "filename"
    Save a record of all of the internal and external events that
    SimTime notices to the specified filename.  (The file is opened
    with the first init-soar after the command is given.)  With no
    argument, close this log file immediately.

You could also put these commands into a file along with the SP's you
load, such as
  (simtime events "sample.eventlist")
  (simtime timing "sample.timinglist")
  (simtime on)
  

INSTALLATION
Installing SimTime requires you to link an additional file into your
compiled version of Soar-6, and to modify the "hooks" file hooks.c
that comes with the standard Soar release.  If either of these tasks
sounds absolutely foreign to you, it is probably advisable to talk to
your local Soar administrator about editing and recompiling the code.

First of all, the source code in simtime.c must be compiled and linked
with the other Soar object files.  If you are adding any functions of
your own, you may need to put these into a separate file (something
like example.c) and compile and link this as well.

Second, the hooks file needs to be changed to include the
initialization of the code.  The file hooks.c with this release gives
directions for the edits that need to be made, rather than providing a
complete new hooks.c, because it is possible that you or someone else
has made other changes to hooks.c which would be lost if it were
completely replaced.

The source code and directions reside in the directory:
   /afs/cs/project/soar/member/ghn/simtime

The example file example.c is just an example of some rudimentary
functions (originally used by NTD-Soar) which you may copy and modify
to fit the needs of your own application.  It doesn't give a
particularly broad sample of what one might be able to do, and you'll
have to wade through NASA jargon like "OIS".  I'm happy to consider
examples from other people that they think are clearer or more
general. You could use functions like "add_input_wme()" in this code
to cause the functions to put things into Soar's working memory; you
could place things into global variables that are inspected on the
next input cycle, etc.

Here is a description of the files:
  hooks.c	contains a list of the changes that need to be made to
		the Soar source code file "hooks.c" in order to
		properly initialize and use the SimTime package.

  simtime.c	contains the actual code for the SimTime package; this
		should simply be linked in with the rest of the Soar
		source code, although additions could be made to this
		file as well.

  simtime.h	contains public definitions of the functions in
		SimTime; this should be included (#include "simtime.h")
		near the beginning of any source code file you write
		which accesses the SimTime system.  Be sure to include
		soar.h before simtime.h wherever you use this.

  example.c	contains a small example of the use of the SimTime
		package for NTD-Soar, showing how the functions you
		need to write should look

  sample.eventlist
		contains a sample event listing.  The first line
		indicates the starting time of the simulation (reset
		whenever you perform an init-soar).  Every line
		following this is an "event" -- the first column
		indicates a time (in arbitrary units, I use ms).  The
		second column indicates an "event type", and must
		match to the name of an event type in your code (see
		example.c).  The remainder of each line is passed to
		the C function which implements the event as an
		argument.
		The special entries "ADD-WME" and "REMOVE-WME" (see
		below) are defined for you by the SimTime package, but
		you may override these by specifying your own
		functions.
		
  sample.timinglist
		contains a sample time accounting listing.  Each
		line is the name of an operator (all lower case)
		followed by a duration (in the same arbitrary units
		you used before).  Each operator must be listed
		independently, including those in subgoals; any
		operator not listed will appear to take no time.
		The names given must match to the ^name attribute of
		the operator, and should be all lower-case.
		The special entries "OPERATOR", "ELABORATION", and
		"DECISION", if included, give a base time to be added
		for each operator, elaboration cycle, and decision
		cycle, respectively. 

