Unit 1 Tutorial

[updated 08/09/15]

Abstract

This document is an augmentation to the unit one tutorial found in the standard ACT-R distribution. To use this tutorial extension, read through the original tutorial and refer back to this document for jACT-R specific comments and features.

Getting Started

Presumably, you have already followed the instructions and configured your Eclipse environment to run jACT-R. Now download the prroject archive for the tutorial: org.jactr.tutorial.unit1.zip (for experts: the contents of the archive are also available on Github.) Import instructions to import the jACT-R project contained in the zip file into Eclipse.

Count Model

The ACT-R tutorial unit 1 starts you off with the basics of chunk, chunk-type, and production creation using the count model. The count.jactr model (found in org.jactr.tutorial.unit1/models/) contains the full model description using the jACT-R (XML-based) syntax, with the Lisp in comments.

Running Models

jACT-R conforms to a compiled-language development model. You write your models, they are compiled, and are then executed in a separate runtime. As you edit the model you may see warnings (yellow underline markers) or errors (red underline markers). Mouse hovering or the Problems View will provide greater detail as to the error. All errors, but not warnings, must be resolved before attempting to the run the model.

errors.jpg

Once the model is free of compilation errors, you can create a run configuration for that model. Run configurations allow you to specify how the model should be executed, any startup/shutdown logic, and what devices and instruments should be connected to the model. If you open the Run Configurations dialog, you should see a jACT-R Run configuration for count already. Just select it and click on run.

run-config.jpg

Inspecting Model Output

The IDE includes a table based model log viewer where each row represents a block of time and each column corresponds to a module, buffer, or other logging source. Log messages are kept in a scrolling buffer that can be increased in size through the preferences. The amount and type of information that is logged is configured in the run configuration. The basics include routing the pure textual log messages as well as maintaining a visual representation of buffer states and contents.

logging.jpg

jACT-R Note: You may notice that in the ACT-R tutorial trace productions are selected at one time and then fired in the next, yet in jACT-R they appear to be selected and fired in the same time step. This is just a difference in logging. In both systems productions when fired post events that will be executed at some time in the future (typically 50ms later). jACT-R notifies that the production has fired immediately after the events are posted, ACT-R notifies once the events start to fire. Same behavior, same timing, just different logging.

IDE Note: The ACT-R trace in the tutorial runs 50ms longer than it does in the jACT-R run. This is a silly bug where the runtime can exit before it has finished sending the last block of logging information to the IDE. Nothing to worry about.

IDE Note: If you look under the org.jactr.tutorial.unit1/runs/ directory you will see a date stamped, then time stamped folder. Within that folder will (at least) be environment.xml. This folder is where the model is actually running. All tools, instruments, devices, whatever, will output to this location. This makes keeping track of the various outcomes really simple. The environment.xml file is used to configure the jACT-R runtime and is quite useful in debugging.

Pattern Matching Exercise

There is no mechanism (yet) to directly manipulate the instantiation of productions in jACT-R. Since the runtime is intentionally hidden from the modeler, something like this is not worth the effort (unless people start clamoring for it). However, if you want to see what is going on, take a look at the trace in for Procedural. jACT-R errs on the verbose side when it comes to logging and you can see quite clearly why any production does not match at any time. Combined with the buffer hovers (to show buffer state and content), you can usually figure out all you need to know.

Addition Model

As with the count model, the addition model is provided and commented with the matching lisp code. Running it is just as simple, merely run the addition run configuration.

Semantic Model

For the semantic model, the lisp tutorial asks readers to change which goal is the focus with the (goal-focus) command. Similar effect can be achieved by modifying the chunk attribute of the buffer tag at the end of the semantic.jactr model file.

Unlike the lisp version of the model, all chunks are defined in the jACT-R model. Missing chunks are not warnings in jACT-R but outright errors. Delete the chunk color and see what happens. Having trouble finding the chunk in all that code? You can use standard Find command, or poke around in the Outline viewer (look under chunk).

outline.jpg

Building a Model

The first step in building a new model is to invoke the new model wizard. Right click on the models folder and select New - jACT-R Model.

new-model-1.jpg

This will open the wizard, allowing you to select from a set of preexisting modules. You will only need Declarative, Procedural, Retrieval, and Goal. Clicking Finish will generate the initial code necessary to get started.

new-model.jpg

Chunk-types & chunks

To create the two chunk-types needed, scroll down to the declarative-memory section, type chu and hit Control-Space. This will pop up a sorted list of code template proposals. Typing XML is a pain, so I've automated most of it for you (templates exist for the Lisp editor too). Enter the name of chunk-type (addition-fact) and the first slot name (addend1). The slot value can be left as null (null and nil are treated the same). Hit return to close the template.

chunktype.jpg

But we still have two more slots to define! Type sl and hit Control-Space again. Look, slot templates.

chunktype-2.jpg

You can use this technique for almost every element in jACT-R. Go ahead, finish the chunk-types and chunks. Then we'll hit the productions.

Productions

Productions can use the exact same template system, but these templates are often a little more complex. First, make sure you are in the procedural section of the model, then type p and Control-Space. The default production template will prompt you for the production name, the initial buffer to test, it's type, a slotName to test, an initial and final slot value. This pattern is really useful because it helps ensure that you write productions that don't loop forever (because they don't change the state).

production.jpg

Now, let's assume we are really lazy typers, or forgot the name of the chunk-type we are testing. Type the first couple of letters, add and hit Control-Space again. You will see a list of possible chunk-types, select and it will fill in the rest. Since the XML format is strongly typed, context completion is generally really good at guessing whether you want buffer, chunk-types, chunks, slots or variables. The Lisp editor isn't quite that good (yet).

guess.jpg

Finally, you are also able to use code templates for queries, proxies and scripts (jACT-R equivalents of !eval!), as well as add, remove, and output actions.

IDE Note : Templates can be modified and customized through the preferences.

Initial Goal

To set the initial goal, merely modify the goal buffer section towards the end of the model.

goal.jpg

Running Your Model

The easiest way to create a new run configuration is to just copy an old one. From the Run Configuration dialog, select the count configuration and click the duplicate buttoncopy_edit.gif . Then uncheck the count model, check your new model and click Add Alias. You'll probably want to change the name of the run configuration, apply and run.

run-copy.jpg

jACT-R Note : The alias mechanism allows you to run multiple instances of the same model in the runtime without any further hassle.

If that isn't enough to keep you occupied until I write the unit 2 tutorial project, you can take a look at these other topics: