ACT-R Memory Output Library

Library Explanation

Jen's ACTR Project
Jen's ACTR Home

The Output Library

The ACT-R Memory Output Library contains functions which record the contents of working memory while an ACT-R model is running. To understand what these functions do, it is important to understand the difference between these functions and the macros that are typically used in ACT-R models. It is also necessary to understand how the memory of the basic ACT-R model is set up. I discuss the difference between the macros and functions like the ones I have written in my essay. For an explanation of the ACT-R Memory Structure see Explaining ACT-R Memory, below.

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.)

Once the output files have been created, there are a number of ways in which this information can be used to make more clear the workings of the ACTR model being studied. In addition to simply viewing the files themselves (see Output Explanations, below), several built in unix functions can be easily used to trace the changes in memory that occur while a model is running (see Using The Output, below). Finally, these files can themselves be used as input for other programs that automatically display desired aspects of the model (see the ACTR Output Perl Apps page for suggestions and a sample program)

Explaining ACT-R Memory

  Before describing the ACT-R model's computer memory structures, it is important to distinguish between the computer memory that ACT-R uses when it is running and the human memory involved in the human memory system that ACT-R is trying to model. As it happens, The ACT-R model is trying to model human memory. However, the computer program itself uses a computer memory store when it runs, the usage of which is not necessarily related to how the computer program is modeling human 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:

These structures are associated with the production structure. Each production structure has a list of pointers to instances of these structures. Unfortunately this is all that I currently know. I have not yet been able to decipher the ACT-R lisp code with which they are associated.

Top

Functions Explained

 

General Description

Each of the functions below prints a certain part of the ACT-R model's working memory to a specified file. For example, the output-goal-stack-verbose function outputs the contents of the goal-stack to a file.

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
output-global-variables-verbose
output-goal-stack-verbose
output-procedural-memory-verbose
output-all-memory-verbose

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>

Top

How to Use the Library

  The functions in the Memory Output Library are lisp functions. As a result they can either be used by putting them directly into specific task models, along with the supplied ACT-R macros or they can be placed directly into the code of the basic ACT-R 4.0 model.

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.

Used in the basic ACT-R model code:
These functions can be inserted into the code of the basic ACT-R model as well. Most usefully, they can be placed at the beginning of the run-fct right after the beginning of the run cycle loop (Shown here.) This will result in a print out of memory contents at the beginning of every model cycle.

Top

Output Explanations

  The output from each function is placed into the file specified by the filename argument. The particular format of the file contents depend on the structures being printed into that file.

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.

Top

Using The Output

  Due to the sheer volume of output, looking directly at the files created by these functions can be confusing. Two unix functions, available at the unix command line prompt, make this task easier.

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.

The diff function compares two files and prints out only the lines from each that are different. In the case of the Memory Output Library files, it may be used, in conjunction with split, to compare memory states at different points in the run of the model or to compare memory states of different models at analogous points in their run.

Top

Jen ACT-R Home Link Index

This page is maintained by Jennifer Schellinck. Last updated 2000.06.23