ACT-R Memory Output Library

Library Explanation

• Explaining ACT-R Memory
• Functions Explained
• How to Use the Library
• Output Explanations
• Using The Output (with UNIX)
• Output Library Lisp Code

The Output Library

The ACTR Output library contains twelve functions, five of which are for use by modelers, the other seven of which support these five user functions (see Functions Explained , below). The five user functions are intended to be used by modelers who wish to understand or trace particular parts of their model. They are also intended to be used by people evaluating ACT-R models and by people trying to evaluate the basic ACT-R model. Each function generates files containing information about the contents of the model memory at the particular time the function is called (see How to Use the Library, below, for suggestions on where to put the functions in the model code.)

Explaining ACT-R Memory

It is the computer memory which is printed to files by the functions in this library.

Of course, there may be some relationships between how the program uses computer memory, and how it is modeling human memory. Presumably there are relationships between the two, since one is modeling the other. The specific relationships between the memory structure of the ACT-R computer program and human memory, if any, must be defined by the modelers, however. (see my essay for a discussion of the modelers' responsibility in this regard)

ACT-R's memory consists of a collection of 74 global variables, and 7 different structure types. I provide descriptive summaries of each of these in turn, below. For a more detailed discussion of the specific parts involved in these structures and variables, consultthe defstruct listings in the ACT-R 4.0 code.

Memory Structures:

global variables
wme-type
wme
ia
production
goal-frame
action and functional-parameter

global variables:

The values given to the 74 global variables determine exactly how the ACT-R model will be run. Some explanation of their use and roles that they play in the ACT-R model can be found in the code comments (see the Gobal System Variables section of the ACT-R 4.0 lisp code).

wme-type:

This is one of the main structure types in ACT-R. Wme-type structures are created every time the Chunk-Type macro is called in an ACT-R task model. The *declarative-memory* global variable simply contains a list of pointers to all the wme-type structures that have been created. The rest of declarative memory is then attached to these wme-type structures.

wme:

Wme structures are created everytime the Add-Dm macro is called in an ACT-R task model. In addition to its own name, each wme is given a wme-type name, which is the same as the name of a wme-type structure. The relevant wme-type structure maintains a list of pointers to all the wmes associated with it.

Each wme structure maintains a list of pointers to the wme structures associated with its slot values (i.e. wmes that have the same name as the slot values) and a list of pointers to the wme structures with which it is associated by means of their slot values.

ia:

As discussed, wmes contain a list of pointers to other wmes with the same name as their slot values. In addition to this the wme structure has a list of pointers to ia structures, one for each wme it points to based on its slot values. These ia structures contain values which are dependent on these wmes and which are calculated during the run time of the model.

production:

Production structures are the second major structure type in the actr model. Production structures are created when the p macro is used in an actr task model. They hold the information that the basic model code needs in order to simulate production action and the resulting changes to declarative memory.

A list of pointers to production structures is maintained in the *procedural-memory* global variable.

goal-frame:

Goal-frame structures are accessed through a list of pointers maintained in the global variable *goal-stack*. These structures are created and manipulated as the ACT-R program runs.

action and functional-parameter:

Functions Explained

General Description

When a function is called repeatedly with the same file name, the resulting outputs will be appended to a single file. This is useful if, for example, one of these functions is called at the top of the ACT-R run-fct cycle loop (see How to Use the Library). The resulting file will contain a consecutive series of snapshots showing the changing state of ACT-R's memory at the beginning of each cycle. Redundancy Note

In order to keep each memory snapshot separate within the same file, at the beginning of each snapshot a string of five x's and ,optionally, a supplied descriptive message will be printed, so that it will be obvious where one snapshot ends and the next snapshot starts.

Specific Function Descriptions

output-declarative-memory-verbose
Form: (output-declarative-memory-verbose filename message)

When called, this function writes the contents of declarative memory to a file. The name of the file should be specified by the filename argument, in quotes.

The message argument is optional. It specifies a message that will be printed, after the string of five x's, at the beginning of each memory snapshot.

Example: (Output-declarative-memory "my_declarative-memory.txt" "Next cycle")

output-global-variables-verbose

Form: (output-global-variables-verbose filename message)

When called, this function writes the contents of procedural memory to a file. The name of the file should be specified by the filename argument, in quotes.

The message argument is optional. It specifies a message that will be printed, after the string of five x's, at the beginning of each memory snapshot.

Example: (Output-global_variables-verbose "my_global_variables.txt" "Next cycle")

output-goal-stack-verbose

Form: (output-goal-stack-verbose filename message)

When called, this function writes the contents of the goal stack and the contents of the goal focus to a file. The name of the file should be specified by the filename argument, in quotes.

The message argument is optional. It specifies a message that will be printed, after the string of five x's, at the beginning of each memory snapshot.

Example: (Output-goal-stack-verbose "my_goal_stack.txt" "Next cycle")

output-procedural-memory-verbose

Form: (output-procedural-memory-verbose filename message)

When called, this function writes the contents of procedural memory to a file. The name of the file should be specified by the filename argument, in quotes.

The message argument is optional. It specifies a message that will be printed, after the string of five x's, at the beginning of each memory snapshot.

Example: (Output-procedural-memory-verbose "my_procedural_memory.txt" "Next cycle")

output-all-memory-verbose

Form: (output-all-memory-verbose dec_filename globv_filename goals_filename proc_filename message)

When called, this function in turn calls each of the functions described above, using the supplied filenames (dec_filename is the name of the declarative memory file, globv_filename is the name of the global variable file, goals_filename is the name of the goal stack file and proc_filename is the name of the procedural memory file. They are in alphabetical order to make this easier to remember). As usual, the message argument supplies a message that will printed along with the xxxxxx divider at the beginning of each memory snapshot. This function allows all of ACT-R's memory to output at once. < /FONT>

How to Use the Library

Here are some usage tips and suggestions:

Used in an ACT-R model:
These functions can be inserted directly into an ACT_R specific task model For example, inserting the output-global-variables-verbose function, which prints out the current value of the global variables, right before the run command of a model and repeating this for a number of models, would make it possible to compare global variable settings between models.

Output Explanations

Declarative Memory:
This file contains a print out of declarative memory, which encompasses wme-type structures, wme structures and ia structs. For each wme-type pointed to by the *declarative-memory* global variable, all of the values associated with that wme-type are printed. Below this, the values for each wme associated with that wme-type structure, are printed. Below each wme structure, the values of all of the ia structures associated with that wme structure are printed.

Global Variables:
This file contains a list of global variables and their associated values.

Goal Stack:
This file contains a print out of the current goal focus and the goal stack. First it prints the contents of the global variable *wme-focus*, which contains a pointer to the wme structure currently acting as the focus. Then it prints out goal-frame structures that are pointed to by the *goal-stack* globabl variable.

Procedural Memory:
This file contains a print out of procedural memory. It prints out the values for each procedure structure pointed to by the list held in the *procedural-memory* global variable.

Using The Output

split
Usage: split -p xxxxx filename prefix
where xxxxx is the pattern used to split the file, filename is the name of the file to be split and prefix is a prefix given to all of the files created during the split.

The split function will split a file into multiple files. If the -p option is used, it will split the files using a provided pattern as the file delimiter. In the case of the files produced by the Memory Output Library, the xxxxxx printed at the beginning of each memory snapshot can be used to split the file into a number of files containing individual snapshots of, for example, declarative memory. Once this is done, the diff function (see next) can be used to compare the files.

diff
Usage: diff filename1 filename2
where filename1 and filename2 are the names of the files to be compared.