for best results make sure you have the Palatino font installed

Section 2 Models 12

Section 3 Global Parameters and Traces 14

Section 4 Declarative Memory 20

Section 5 Goal Stack 25

Section 6 Procedural Memory 26

Section 7 Partial Matching 34

Section 8 Analogy 36

Section 9 Hooks 40

Section 10 Bibliography 41

ACT-R 4.0 (hereafter referred to as ACT-R, unless otherwise specified) was written in Macintosh Common LISP. However, it strictly adheres to the standard put forth in the second edition of "Common Lisp: The Language" by Guy Steele Jr. and should run without any modifications in any complete Common Lisp implementation. If a compiler is not available in your implementation, you should set the variable *compile-eval-calls* to NIL when it is defined at the top of the code file. This manual is a reference for the ACT-R implementation. It is not meant to be a treatise, a tutorial or a textbook on ACT-R. A good understanding of the first chapters of Anderson & Lebiere’s upcoming The Atomic Components of Thought (ACT in short) is required before experimenting with ACT-R.

The ACT-R folder should contain:

• ACT-R 4.0: the source code, which can be loaded directly or first compiled.

• Load ACT-R 4.0 (optional): a compiled version of the code for fast loading.

• Manual: this manual, written in Microsoft Word 5.1.

• Changes: outlines the few changes from the previous version, ACT-R 3.0.

• Examples: a directory containing a number of ACT-R models.

The following commands are available to define an ACT-R model and control the ACT-R production system. The command Help without any argument (i.e. (Help)) will print the list of commands, and if given one or more command(s) as argument will display a short description of the command(s) (e.g. (Help Help) will print something like "HELP: Outputs a short description of one or more ACT-R command(s), or the full list of commands if none is supplied.").

More complex tasks can be accomplished by combining several commands together by sending the output from a command to another command and so on. A distinction must first be drawn between a command and its underlying function, which has the same name as the command with the "-fct" suffix appended. A command typically does not evaluate its arguments and, when any number of arguments may be supplied, they are given one after the other without being included in a list. The functions underlying commands, on the other hand, do evaluate their arguments and usually require multiple arguments to be specified as a list. In practice, that means that when results from a command or function are passed to another, then the function form must be used for the latter rather than the command form. E.g., to delete chunks three, five and seven, the command form would be:

whereas the function form would require quoting the arguments and including them in a list:

As an example of command combination, to delete all chunks of type addition-fact, you could write:

The internal SDM command will print and return the list of chunks of type addition-fact, which is then passed to the Delete-Chunk-fct function to be removed from memory. If you do not want the SDM command to print the list of chunks which it returns, you can use the no-output command to turn off printing during execution of its argument, while still returning the same value:

Some functions take their arguments in a slightly more complex form than a list. To find out the functional form equivalent to a command, use the Lisp function macroexpand:

will return (Mod-Chunk-fct ‘dime ‘(on left next nickel)), indicating that Mod-Chunk-fct takes two arguments, first the chunk to be modified, then the list of slot-value pairs.

Note that many of those, including SDM, DM and pp, return actual chunks and productions, not their names as it may appear from the printing. The same is true for production variables which are also bound to actual chunks. To obtain the name of chunks and productions, use the get-name command. For example, to obtain the list of the names of chunks of type peg:

A number of command names have been changed in ACT-R 4.0 from earlier versions to systematize the use of the hyphen "-" as a word separator in commands and to remove references to the phrase "working memory" and its derivatives ("wm", "wme") with the more accurate "declarative memory" and related concepts ("dm", "chunk" and "goal"). The outdated commands can still be used, but usage of their replacements is recommended. The outdated commands are listed below with their replacements. That information can also be obtained by using the Help function with those commands.

Although a fully interactive mode is possible, in general ACT-R models should be developed in a file or files instead of the listener to make saving and resetting easier. A call to (Clear-All) should always be at the top of the main model file, to clear previous models and define from where to reset the current model:

It should be followed by a call to the sgp command (see Section 3) if any global parameters and traces need to be set.

If preliminary model files need to be included (e.g. the example file integers as the standard representation of integers and arithmetic facts), they should be loaded immediately after the clearing and setting of global parameters, using either the Lisp load command or the ACT-R load-model command (see the Equation example):

When the model has been run and needs to be reset to its starting point, use the (reset) command:

Reset works by saving, when it encounters the initial (Clear-All), the contents of the model file after the Clear-All command and any other files it loads after it. Resetting then consists in reevaluating the saved contents without re-reading the file itself. This implies that if the model file has been modified since it was loaded, then it must be reloaded rather than reset, using the reload command:

For reset, reload and load-model to work properly, the main model file should be loaded using load-model, rather than other commands such as Eval Buffer which may be available in the Lisp environment. In some Lisp implementations such as Macintosh Common Lisp and Allegro Common Lisp, using the Lisp command load will also work. Also, if the model includes some Lisp definitions, those should be either included before the Clear-All command or in a separate file to be loaded beforehand, either from the model file or independently.

The general model format should therefore be:

<load or define Lisp functions (if necessary)>

(Clear-All) ;; this command should only appear in the main model file

<set global parameters>

<load related models (if necessary)>

<define chunk types>

<define chunks>

<define chunk parameters (if necessary)>

<define productions>

<define production parameters (if necessary)>

<general commands, commented trace of model run, and other miscellaneous>

The core of the model should define declarative memory (using commands such as Chunk-Type, Add-DM and others described in Section 4), select the initial goal stack focus (using the Goal-Focus command described in Section 5) then procedural memory (using commands such as p and parameters described in Section 6). Keeping to that order helps avoid having items such as chunks being used before they are defined. The main command to run the model is the run command:

The Pstep command lets the user step through a run and perhaps guide ACT-R by selecting the instantiation to fire:

The sgp command (for Set Global Parameters) is used to query and set the value of global parameters and toggle traces, both interactively and in model files. Since the internal variable names of some global parameters have been changed from ACT-R 2.0, it is strongly recommended to update the setf Lisp commands used to set them in previous models to the corresponding sgp command. The syntax of sgp is:

When sgp is called without arguments (i.e. (sgp)), the list of global parameters is printed. Each line includes the full name of the parameter, a two- or three-letter keyword for use when setting its value with sgp, and its current value. The parameters are listed in groups separated by dotted lines, each containing a number of related parameters. Each group and its parameters is detailed below. A value of NIL means that the function corresponding to the parameter is disabled. A value of T means that it is enabled. Other types of values are specified when acceptable. Note that values are set as specified and are NOT evaluated.

For further details on partial matching, see Section 7 in this manual and the papers cited in the bibliography.

These traces are enumerated here roughly in the order they would appear during each production cycle. They can be enabled by being set to T, which sends the trace output to the standard output (Lisp listener), or to any file name, pathname or stream if output is to be directed to another destination. Each trace message starts on a new line and is indented by a number of spaces proportional to the current depth of the goal stack.

To print and return the value of some but not all parameters, sgp can be called with just the list of those parameters. For example, to print the value of G, GThreshold and Conflict Resolution Trace:

which will also return the list of their (default here) values:

To set global parameters and traces, simply call the sgp command with as arguments the series of one- to three-letters keywords preceded by the keyword specifier : (no space), followed by the desired value. For example, to set the Goal value G to 10.0 and to turn Activation Trace on:

In general, sgp will check that the values supplied fall within the required type and range for the parameter, and reject those that don't while printing a warning message. Note again that turning Verbose off is a quick way to shut off all the traces for maximum running efficiency.

Each chunk is of a particular type, which must be defined before an element of that type can be created. Types are defined using the Chunk-Type command:

The ACT-R type hierarchy only allows single inheritance, i.e. only one (previously defined) type can be defined as the parent of a new type, which inherits all the slots of the parent. Chunks of the new type will match any production template specifying the type of the parent or further ancestors.

Chunks can be added using the Add-DM command:

Chunktype must have been previously defined as including each slot. Note that not all slots of the chunk need to be initialized (in which case they will contain the standard value NIL), and that they can appear in any order. If a symbol which hasn't yet been defined as a chunk appears as a slot value in a chunk (or production) definition, it will be defined by default as a chunk of the built-in type chunk, which has no slots. Chunks can be redefined of being of a different type, in which case the new type and slot/values definition will replace the old, although the rest of the chunk history will remain unchanged and a warning message will be printed.

A chunk can be modified using the Mod-Chunk command:

Chunks can be deleted using the Delete-Chunk command:

A warning message will be printed if a deleted chunk is still used as a value in another chunk or production, and the resulting effect is undefined (in other words: don't do it).

The contents of declarative memory, or just some selected chunks, can be displayed using the DM command:

Declarative memory can also be searched for chunks fitting a particular pattern using the SDM command:

For example, to display all chunks of type addition-fact with a value of slot sum of five:

Individual slot values can be obtained using the Chunk-Slot-Value command:

To each chunk is associated a quantity called activation, described in ACT equation 2.5, which is the sum of its base level and the activation spread from the current activation sources. The base level of chunks (see ACT equation 3.1) can be queried using the Get-Base-Level command and set using the Set-Base-Levels and Set-All-Base-Levels command:

For example, with Base Level Learning on, to specify that chunk 3+4=7 was created at time -1000.0 and has been accessed 10 times since:

The rest of a chunk's activation is computed by summing the product of each activation source level times the Interactive Activation (IA) value from the source to the chunk. The activation sources are the set of chunks in the slots of the focus, at a level of Goal Activation divided by the number of sources. They can be displayed using the Activation-Sources command:

IA values can be queried and set using the IA and Add-IA command respectively:

IA values which are not explicitly specified are initialized using ACT equation 3.2: the value of the IA value Sji between chunkj and chunki is log(m/n) if chunkj appears as a slot value of chunki and 0.0 otherwise. m is the number of chunks in declarative memory and n is the fan of chunkj, i.e. the number of chunks in which chunkj appears as a slot value.

This command uses a syntax similar to sgp, where any number of parameter keywords can be specified in any order, perhaps followed by an assigned value. Again, values are NOT evaluated. The list of chunk parameters follows, with their keywords and default values, and a description:

For example, in the Tower of Hanoi model, to print all active parameters for all chunks:

To print the activation, base level and source spread for chunks penny, nickel, dime and quarter:

To set the base level of those chunks to their monetary values, then print the same information as above:

ACT-R provides for a simple goal-stacking mechanism. At any point in time, (at most) one chunk is the focus, aka the (top) goal. This element is the root from which all productions must match. A chunk can be designated as the focus, replacing the current one if one had previously been selected, using the Goal-Focus command:

The slot values of the focus element can also be modified using the Mod-Focus command:

The focus can also be manipulated by productions, which can push the focus on the goal stack, replacing it with a new one, pop the top goal off the goal stack to replace the current focus, or simply switch the focus without manipulating the stack (see Section 6). The contents of the goal stack can be inspected and cleared using the Goal-Stack and Clear-Goal-Stack commands respectively:

An ACT-R production consists of two halves: a matching part aka the left-hand side (lhs) and an action side aka the right-hand side (rhs). A production is declared using the p command:

(p production-name
{ =chunk>

isa chunk-type

{ {-} slot {value | =variable }}*

| !eval! expression

| !bind! =variable expression }*
==>
{ =chunk>

{ isa chunk-type }

{ slot {value | =variable }}*

| !push! =variable

| !pop!

| !focus-on! =variable

| !output! ("output-string" {expression }*)

| !eval! expression

| !bind! =variable expression

| !delete! =variable

| !stop!

| !restart! }*
)

The opening "(p", delimiting "==>" and final ")" are all required. production-name is the name of the production, and lhs and rhs are the two sides of the production separated by the delimiter. Each side is composed of a number of chunk patterns used to match (for the lhs), create or modify (for the rhs) chunks in declarative memory, and some special commands appearing between exclamation marks "!".

Variables can be bound to any element in declarative memory except the special element NIL used to initialize slots. They are represented by an equal sign "=" followed by the variable name. A left-hand side chunk pattern is composed of the variable bound to the chunk followed by the chunk selector ">", a type identification consisting of isa followed by the chunk type, then any number of conditions on its slot values. A condition consists of the slot name, followed by a value or variable. If a value is specified, then the content of the slot must equal the value for the condition to succeed. If a variable is specified and that variable has not appeared earlier in the lhs, then the condition succeeds and the variable is bound, i.e. its value later in the production is set to the value of the slot. If that value then appears later in a condition then its previously set value is sued to test the condition. If the negation marker "-" appears before the slot name, then the test is negated, i.e. it succeeds if it would otherwise fail and vice versa.

A chunk will match a chunk pattern it is of the required chunk type (or one of its descendants - see the chunk type hierarchy in Section 4) and if all the slot conditions are satisfied. The first chunk pattern must match to the focus. If a variable which has been previously bound is matched at the head of a chunk pattern, it is matched against the pattern in what is called a direct retrieval. If it hasn’t yet been bound, all chunks in declarative memory are matched against the pattern independently in what is called an indirect retrieval. A set of bindings for all the variables appearing on the lhs of a production is called an instantiation of that production.

A number of special commands can appear on the lhs of a production:

The syntax of the right-hand side is similar to the left-hand side’s, but the semantics is different. When a chunk pattern appears in the right-hand side, if the corresponding variable has been bound in the left-hand side the chunk will be modified, otherwise it will be created. The chunk type only needs to be specified is it hasn’t previously been. Slot/value pairs now indicate how to modify or initialize the chunk slots. All variables appearing as slot values must have been previously bound, except for return variables. If a previously unbound variable appears as a slot value of a chunk which will be pushed on the stack (see below), it will be bound to the value of that slot when the chunk is popped off the stack. It will then be copied to the chunk slots in which it appears later in the right-hand side (see examples factorial and fibonacci for a simple and complex usage of return variables, respectively).

A number of special commands can also appear on the rhs of a production:

Conflict resolution is the process by which the system chooses among several competing instantiations. The value PG-C of a production instantiation is determined by a number of quantities associated with a production (see ACT equations 2.2, 2.3, 3.5 and 3.6) and which can be displayed and set using the production-parameter and parameters commands, respectively, or the more general spp command:

These commands use a syntax similar to sgp, where any number of parameter keywords can be specified in any order, perhaps followed by an assigned value. The list of production parameters follows, with their keywords and default values, and a description:

A number of parameters (value, chance, effort, success and failure) can take as value an arbitrary Lisp expression, possibly including variables from the production. Those expressions are evaluated for every instantiation. All other parameters are set as specified and are NOT evaluated.

For example, in the Tower of Hanoi model, to print all active parameters for all productions:

To print only the strength and pg-c for productions move-disk and clear-disk:

To set the strength of move-disk to 1.0 and its a to 1.0 and the r of clear-disk to 0.5 and its b to 2.0, then print all active parameters for both productions:

To define move-disk as a success production and clear-disk as a failure (after switching parameters learning on):

The contents of procedural memory or some selected productions can be displayed and returned using the pp command:

Note that disabled productions are not printed by the (pp) command, but will be if given explicitly as arguments. Productions can be disabled and reactivated using the PDisable and PEnable commands respectively:

Breakpoints can be set and removed for productions by using the PBreak and PUnbreak productions respectively:

To determine which production instantiations match the current state of memory, and why a particular production does not, use the PMatches and whynot productions respectively:

Partial matching enables ACT-R to display errors of omission and commission, as described in the papers cited in the bibliography. It consists in modifying the pattern matching algorithm for production lhs from an exact backtracking search to a sequential, activation-penalty matching. It can be activated and traced by the global parameter partial matching and trace partial matching trace, respectively:

Partial matching does not apply to the matching of the focus (first pattern in each production lhs) or to the type-checking of chunks. For all chunks after the focus, a mismatch between an actual slot value and the desired pattern results not in outright failure, but in the subtraction from the activation of the chunk of an amount equal to the mismatch penalty constant times the degree of mismatch between desired and actual value. If, after matching, the modified activation of the chunk remains above a retrieval threshold, then the match is successful, otherwise it fails. For indirect matches, only the chunk with the highest resulting activation matches (thus no multiple instantiations of a production), and no backtracking occurs to consider other less active elements if matching fails later in the production. Note that retrieval threshold defaults to NIL and therefore MUST be set when partial matching is activated (it can also be set to work with standard matching).

The mismatch penalty and retrieval threshold global parameters are:

The degree of match, aka the similarity (which is equal to 1.0 - the degree of mismatch), between two values defaults to 1.0 if the two values are identical chunks, and 0.0 if they are different chunks and not chunks at all. Similarities between chunks can be queried and set using the similarity and Set-Similarities commands respectively (note that similarities are symmetrical, i.e. the similarity between chunkj and chunki is equal to the similarity between chunki and chunkj, and Set-Similarities sets both at the same time):

Analogy examples are stored in chunks of the predefined type dependency. Dependencies are considered by the analogy mechanism in decreasing order of activation. If a dependency is found compatible with the current goal, then a new analogized production is created based on the dependency, or an existing production is selected if it is identical to the analogized production modulo variable names. The resulting production is then applied to the focus. If instantiations result, they are added to the conflict set. Otherwise, the analogy process goes on to the next dependency. Note: no search is performed for bridging chunks; only the mapping constraints explicitly specified in the dependency are used in composing an analogized production.

The predefined chunk type dependency contains the following slots, which as usual default to NIL and can be left unspecified if not needed:

The name of the new production is automatically generated based on the goal type. Chunk headers (appearing followed by the selector >) and chunks which appear more than once in the production are variabilized. Other chunks and non-chunk values are left as constant. The special dependency slots generals, specifics and dont-cares can be used to override this variabilization rule. Negation tests can be generated using the differents dependency slot.

(p goaltype-productionn

goal

{constraints}*

{subgoals}*

{modified}

{!pop! | !focus-on! subgoal}

{!push! subgoal}*

{actions}*)

The left-hand side of the analogized production consists of the goal description followed by the list of constraints. The right-hand side consists of the list of subgoals and the modified goal if specified (only the modified part of which is actually repeated, but the whole goal counts for variabilization purposes), followed by a !pop! command if success or failure was specified, the respective !push! statements in reverse order (the first may be aggregated with the optional !pop! into a !focus-on!) and finally the actions:

The latency of the analogy process is defined, similarly to an instantiation's, as the sum of the latencies of the dependencies examined, modified by the strength of the analogy process. That strength is held in the global parameter analogy strength which defaults to 0.0 and is not affected by strength learning:

The analogy process and the instantiation of the resulting production occur sequentially. Therefore, the latency of the resulting instantiation(s) is defined as its usual matching latency, plus the latency of the analogy process. If analogy returns before the conflict resolution terminates, a new analogized production will be added or an identical existing one is used and reinforced (if strength learning is enabled). Otherwise, the analogized production will be disabled, but still accessible to the pp and whynot commands. The dependencies used during analogy are strengthened if base level learning and/or associative learning are enabled.

Since the search for an analogy is now carried out at every epoch, it may be desirable to disable the analogy mechanism when it is not needed. If no dependencies are provided or if the strength of the analogy mechanism is set low enough, then analogy will not succeed. However, for efficiency, the global parameter enable analogy has been provided for that purpose:

The progress of the analogy mechanism can be traced using analogy trace, which is set by default:

The initial parameters (see Section 6) of the analogized productions can be set using the Set-Analogized-Parameters command:

Finally, if analogy should apply on some dependencies but somehow does not, a more detailed trace of the compatibility test on the dependencies can be obtained with the whynot-analogy command:

A number of hooks are provided to better monitor and/or alter ACT-R’s runtime behavior. Users need to be at least moderately proficient in Lisp to use this advanced feature. The hooks are global variables which, if set to a proper function definition, can be used to transfer control of the production system to the user’s code at a number of places in each run cycle. The list of hooks with their arguments and values (when applicable) is:

Ultimately I hope to document the set of internal functions used to manipulate those data structures but until then you should just poke around the code and figure it out. Hopefully, it should be simple enough, but if you have any problem feel free to contact me at cl+@cmu.edu.

The main ACT-R reference is:

Anderson, J. R., & Lebiere, C. (1998). The Atomic Components of Thought. Hillsdale, NJ: Erlbaum.

The previous ACT-R reference was:

Anderson, J. R. (1993). Rules of the Mind. Hillsdale, NJ: Erlbaum.

Partial matching in ACT-R was first introduced in:

Lebiere, C., Anderson, J. R., & Reder, L. M. (1994). Error modeling in the ACT-R production system. In Proceedings of the 16th Annual Conference of the Cognitive Science Society, pp. 555-559. Erlbaum.

Further use of partial matching and the introduction of the constraint on total source activation can be found in:

Anderson, J. R., Reder, L. M., & Lebiere, C. (1996). Working memory: Activation limitations on retrieval. Cognitive Psychology. To appear in the April 1996 issue.