[updated 08/09/15]

To import a zipped tutorial like org.jactr.tutorial.unit1.zip in Eclipse, choose Import ... from the File menu of Eclipse. In the Import dialog, keep the pre-selected entry Existing Projects into Workspace and click Next >. Click on Select archive file and Browse ... to the select the downloaded zip archive. Click Finish to import the project into the workspace.

If you came here from a novice tutorial, you may now proceed with the tutorial. You may also continue to get more info on exporting and importing jACT-R projects.

Screencasts

The following screencasts cover how to export and import both zipped and installed jACT-R projects. It also introduces you to run configurations and the creation of custom modules.

Importing/Exporting v1 (19:33 min)
Importing/Exporting v2 (04:50 min)

Note: The tutorials referenced in these (old) videos are not installed by default. You can grab them and similar examples directly from GitHub.

Note: The exporter trims out empty folders. You will need to add the empty java folder at the root of the project. If not, you will receive a error for the project, but it's not critical

Eclipse uses run configurations to manage and store the necessary options and parameters needed in order to execute programs, this includes running of jACT-R models. This screencast covers the basics of getting a particular model run configured as well as importing of models.

• Run configurations

The following screencast illustrates how one can run batch model executions. This is useful for data collection as well as parameter space searches. As with the run configurations, listeners can be attached in order to influence and record the model behavior.

• Iterative runs

Note: The below references deprecated tools. A new system for farming remote model runs is in the works. 

The remote execution tools permit the execution of iterative runs over the network. It can be run both locally and remotely, with auto-start options. The screencast below illustrates how to use this new feature. But first, it has to be installed:

• Update site : http://jactr.org/update/remote/
• Screencast

Copying a chunk is frequently needed by buffers that copy on insertion. This is delegated to the IDeclarativeModule. Note: You cannot copy chunks from one model into another. That's a theoretical brain transplant.

 IModel model = ...
 IDeclarativeModule decM = model.getDeclarativeModule();
 IChunk toCopy = ...
 IChunk copied = decM.copyChunk(toCopy).get();

  IModel model = ...
  IDeclarativeModule decM = model.getDeclarativeModule();
  IChunkType chunkType = ...
  String chunkName = ...
  Future result = decM.createChunk(chunkType, chunkName);
  IChunk newChunk = result.get();

The IDeclarativeModule explicitly supports asynchronous action. That is why all the methods return futures and not the relevant type directly. If you don't care about asynchrony, just call the future's get() method. Otherwise, separate the request from the harvesting to give other threads a chance..

 IModel model = ...
 IChunk chunkToEncode = ...
 IDeclarativeModule decM = model.getDeclarativeModule();
 Future result = decM.addChunk(chunkToEncode);
 
 IChunk encoded = result.get();
 
/*
 Merging might mean that the returned chunk is not the exact same reference,
 however, both IChunk objects will point to the same content
*/

 boolean alwaysTrue = encoded.equalsSymbolic(chunkToEncode);

 boolean trueIfNotMerged = encoded == chunkToEncode;

Chunks once encoded cannot be modified, only copied (IDeclarativeModule.copyChunk()). However, if it hasn't been encoded, there are two considerations. If you have just created the chunk and no other buffers or modules might have access to it, you can merely manipulate it directly:

 IChunk chunk = ...
 ISymbolicChunk sc = chunk.getSymbolicChunk();
 
 for(ISlot slot : sc.getSlots())
  ((IMutableSlot) slot).setValue(...);

//the same applies for parameters

However, once the chunk is accessible in the system (added to a buffer, referenced by another chunk, etc), you need to be concerned about other threads accessing it. If the chunk is in a buffer, the easiest way to do this is with ChunkUtilities and its associated IChunkModifier interface. The utility class handles the locking and execution time for you.

  IModel model = ...;
  IActivationBuffer goalBuffer = model.getActivationBuffer(IActivationBuffer.GOAL);
  ChunkUtilities.manipulateChunkLater(goalBuffer, new IChunkModifier(){
    public void modify(IChunk chunk, IActivationBuffer buffer)
    {
       ISymbolicChunk sc = chunk.getSymbolicChunk();
       for(ISlot slot : sc.getSlots())
        ((IMutableSlot) slot).setValue(...);
    }
});

Otherwise, you should use the chunk's write lock to ensure no contention.

 IChunk chunk = ...
 Lock lock = chunk.getWriteLock();
 try
 {
   lock.lock();
    ISymbolicChunk sc = chunk.getSymbolicChunk();
       for(ISlot slot : sc.getSlots())
        ((IMutableSlot) slot).setValue(...);
 }
 finally
 {
  lock.unlock();
 }

The declarative module interface defines the methods necessary to asynchronously create and encode chunktypes and chunks. It also includes methods for disposing of temporary chunks (or cleaning up chunks during model disposal), and both partial and exact search methods.

An abstract implementation is provided that handles all of the basics (including event firing) requiring implementations of the actual create, add, copy, dispose and search methods.

There are specific extension interfaces for theory revisions four and five.

The default implementation conforms to theory revision six.

Declarative learning is generally accomplished by an IDeclarativeLearningModule. Since the learning theories evolve faster than the rest of the architecture, there are significant differences between the various implementations and their expectations.

The imaginal system is used to store intermediate problem state representations. Typically used in conjunction with the goal module which retains the goal state.

The imaginal system is time dependent (unlike the goal module), so all imaginal buffer operations take some (configurable) amount of time.

The DefaultGoalModule6 provides a simple immediate buffer and little else.

The procedural module is the second primary module that all models must have (the other being declarative). It is responsible for managing all productions in the model.

Procedural learning has undergone much evolution since the early days of ACT-R.

IRandomModule provides a centralized location for the generation of random numbers. Any module that relies upon randomness should check for the existence of a random module (e.g. (IRandomModule) model.getModule(IRandomModule.class)) and use the returned instance. If no random module is installed, random behavior should not be enabled. This allows one to easily enable/disable random behavior. By centralizing the random generation, you can more easily guarantee repeatable behavior for a given random seed.

There is a single default implementation.

The basic retrieval module template. All retrieval module implementations must support the parameter RetrievalThreshold, which defines the minimum chunk activation value that a chunk must have to be accessible.
This module class also provides access to the model-wide retrieval time equation. And an asynchronous retrieval method. Note: the retrieval method need not actually be asynchronous, but support is provided at this level since retrofitting is such a pain.
There is currently a single default implementation of this module.

These extensions are used to tweak the performance of model runs.

This instrument intercepts the log messages and sends them to a named file. After the file reaches a maximum size, it is backed up. The number of backups can be configured. By default, this instrument attaches to all the models in the runtime. When configured programmatically, you can specify which log streams go to which file. In the IDE, all the streams go to a single file.

Parameters

• MaxFileSize: in megabytes before the file is backed up and a new file created.
• NumberOfBackups: the number of backups to retain.
• all: what filename to send all the streams to.

Instrument that records the runtime's models at the start and stop of execution. The format of the saved models can be configured to use any of the installed syntaxes (e.g., jactr, lisp). The location of the files can also be specified.

Parameters

• SaveAsExtension : extension of the code generator to use. (default: jactr)
• StartDirectory : local working directory path to save the start state models to. Will be created if missing. (default: start/)
• StopDirectory : local working directory path to save the stop models to. Will be created if missing. (default: stop/)
• TrimModuleContributions : Don't include the injected content from modules and extensions in the generated code. (default: true).

Whether you are tracing or trying to be nice to other programs, sometimes models just run too fast. The runtime throttler allows you to specify a minimum real cycle time for the models. If the model runs too on that cycle, the model thread will be put to sleep for the remainder of the time. The default value of MinimumCycleRealTime is 0.05, i.e. real time.

An alternative logger that routes messages to an xml file. This logger attaches to all the models in the runtime.

Parameters

• FileName : the xml file to save to.

Overwrite action

Canonical ACT-R supports an overwrite buffer operation that performs an end-run around the managing module and also prevents the encoding of previous contents. =goal> =chunk will replace the contents of the goal buffer with =chunk without encoding the current contents.

jACT-R does not directly support this operation. You can set, add, remove, modify or request, and that's it. You cannot circumvent the encoding. The best you can do is use the set operation which will move a chunk from one buffer to another (in 0 time). But the prior contents will still be encoded. The Lisp parser will tranform overwrites into sets automatically and notify you that this has been done.

Explicit state reset

If a retrieval fails, the only way to reset the state is to complete a successful retrieval. There is no mechanism to explicitly reset the state. While some modules do have this (+visual> isa clear), it is not standard. jACT-R solves this by using an explicit remove operation (-retrieval>). If there is nothing in the buffer, it will have its states reset.

Indexed Retrievals

Retrieval module does permit indexed (i.e. immediate) retrievals of chunks you already have references to. However, this must be explicitly enabled with the EnableIndexedRetrievals parameter.

Asynchrony

Retrievals can also be performed asynchronously if the declarative module is asynchronous.

Declarative FINSTS

Declarative FINSTs are controlled by two parameters: FINSTDurationTime (3 seconds) and NumberOfFINSTs (4 chunks). :recently-retrieved (null, false, true) can be used in retrieval requests.

Partial Matching

The canonical ACT-R partial matching allows completely mismatching chunks to be retrieved, assuming they have the highest activation. jACT-R requires at least one feature in the retrieval spec to match. This is a functional, not theoretic, design decision. This matches better with the modeler's expectations and is also more performant (not requiring testing against all of DM).

Coordinate System

Quick, draw a two-dimensional graph. Did you put the x-axis on the bottom, increasing to the right with the y-axis on the left increasing upwards? You sure didn't draw it with y-axis decreasing downwards. Now draw a graph with a nature center point. Yeah, you get the picture.

Canonical Lisp uses a computer screen based coordinate system, +x to the right, +y down. While the slot names are the same (for now), the coordinates in jACT-R are retinotopic visual angles (degrees). 0,0 is at center, +x to the right, +y up.

Recycled Locations

From an informal survey of modelers, I found that almost none of us use the visual-location chunks for anything other than to encode some object. Because of this limited use and the fact that during the lifetime of a model there can be thousands of these chunks created, jACT-R actually recycles visual-locations.

There is at most one visual-location for each possible retinotopic position (as defined by the visual field size and resolution). Its x and y locations are fixed, but the remaining slot values are mutable by the system. The mutable slot values have a relatively limited lifespan. They are valid only after a visual search until the next visual search is started. In this way the explosive growth of visual locations is eliminated, which is particularly important when operating for long periods in a truly embodied environment.

FINSTS

Canonical ACT-R marks FINSTS at the visual-location level. This makes sense assuming that the visual scene is limited. However, if you've got multiple objects at the same location (due to visual resolution issue or overlap), you can easily end up missing objects and can possibly end up in a situation where you can never actually encode some objects.

To prevent this, jACT-R assigns FINSTS at the object level. In simple scenes, the behavior is exactly the same. In more complex scenes (with overlapping objects), this allows the visual system to differentiate between attended and unattended objects at the same location. The semantics are exactly the same for making a visual-location request.

The only incompatibility this introduces is with the visual-location buffer query. Canonical ACT-R supports ?visual-location> attended {t|new|nil}. jACT-R does not support this query at all. I'm looking at implementing it in the future, but it will be based on the attended status of all the objects at that location.

If you require this query, contact me and I'll see about bumping up its priority.

Movement Tolerances

Canonical ACT-R uses movement tolerance to allow the model to encode a visual object after it has moved from the location returned from the visual search. jACT-R uses this tolerance to also deal with object tracking. If the object is moving too fast, it will exceed the tolerance. When this occurs, the track is lost, the visual buffer state is set to error, but the chunk is maintained in the buffer. (I'm still trying to figure out whether it should be removed from the buffer or not)

Object tracking

So if I've attended to an object why do I have to explicitly tell the visual system to follow it? When something you're looking at moves, it's hard not to follow it. In jACT-R all attended objects are automatically tracked. The only benefit of using the object tracking mechanism is that it stuffs the updated visual location of the object into the visual-location buffer.

If the parameter EnableStickyAttention is true, attended objects will remain attended as long as the object is in the visual field. No amount of movement will shake it.

Asynchrony

All perceptual/motor modules are already asynchronous.

There is no manual system, just a global motor system. The motor system is a drop-in replacement with the same basic functionality, plus a few bells and whistles.

Muscle-level parallelism

If EnableMuscleLevelParallelism is true, motor programs can be prepared and executed in parallel so long as they don't overlap in the muscle groups used.

Compound commands

The motor buffer can also contain chunks derived from compound-motor-command. Compound motor commands allow you to execute primitive motor commands in a coordinated manner, even though they are not actual motor commands.

Preparation

Canonical ACT-R provides a separate chunk-type to specify a motor command to be prepared in advance and then executed later. The problem with this mechanism is that it locks you into a limited set of predefined movements (Specifically keyboard and mouse movements), preventing modelers from contributing their own movement types. jACT-R instead uses a meta-slot (:prepare-only) which can be added to any movement request. Using this, any movement command (past or future) can be prepared in advance, and then executed with the execute chunk-type request.

This is a strange problem that I have yet to track down. It appears to be a bug in Eclipse's caching of classpath data. One instant everything is working fine, but suddenly (and forever after), the classpath gets corrupted and the runtime will be unable to find your model even though it is on the classpath. Through some digging, a temporary fix is available.

1. Quit Eclipse
2. go to ${workspace}/.metadata/.plugins/
3. delete org.eclipse.pde.core
4. Restart will take a little longer, but all should be good.

Actually, this will result in the loss of your Target Platform, but that can be fixed here.

If this problem still persists, it suggests that there is a lower level dependency resolution failure of an option dependency. These are not normally reported because they are at a lower level. Check ${userHome}/.jactr/configuration/${projectName}/${runConfiguration}-actual/${timestamp}.log for any errors.

Setting the model's EnablePersistentExecution parameter to true will enforce conflict resolution when there is no goal and no pending events.

Models that are entirely internal (i.e., they are not reactive to the external world), can use the internal event queue to determine when it can possibly fire again. To enable this, set the model's EnableUnusedCycleSkipping parameter to true.

Be warned, though - if the model is connected to another system for its perceptual world, the model will skip cycles, making the detection time wonky.

Ah, now this is a problem that I run into regularly. Here's the deal: it's not a bug and it's not a memory leak. Almost all communication in jACT-R is asynchronous. This allows the model to run instrumented with (relatively) little performance impact. The problem arises when the model is actually running too fast (and producing too much data) for the IDE to keep up with. When this happens, network buffers rapidly start filling up and memory is consumed at an alarming rate. The two process then start butting against the resource limits and performance crawls to a halt - potentially with out of memory errors.

This problem most often occurs when persistent execution is on and cycle skipping is off. Basically, your model is plowing through a lot of worthless cycles and generating a bunch of data that is worthless. The IDE chokes on the volume and kaboom.

Your best bet fix is to enable the SynchronizationManager instrument in the run configuration. This will force message synchronization at a periodic (and configurable) rate.

Ok, so you have built your awesome model, tested it, hardened it, and it looks amazing. Now you decide it is time to embed the model in your game engine, or whatever. How do you trim the bloat of the IDE and get just what you need in the arch?

None of the jACT-R core or modules actually depends upon Eclipse or OSGi, rather it is the launchers that do. To effectively embed, you just need to place the core dependencies on the classpath and build a launcher suitable for your needs.

(note: I am working on some code to make this easier, but it is far from ready. If you want to code as it is, just ask)

The simplest solution is just to use org.jactr.entry.Main as a starting point. It's the same entry point the Eclipse launcher uses, but only after it has dynamically hooked up all the extensions (i.e. parsers, compilers, automatic code injection).

However, if you do require custom parsers, or any of the other dynamically resolved elements, you will have to do so yourself, with calls such as : ModelParserFactory.addParser(String extension, Class extends IModelParser> clazz) or ASTParticipantRegistry.addParticipant(String moduleClassName, IASTParticipant participant)

Additionally, you will likely require finer-grained control of the run cycle. org.jactr.tools.throttle.RuntimeThrottler (sorry, no javadoc yet) provides an example of how to limit the cycle time. It can also be adapted to run for one cycle and wait until signaled to run another.

jACT-R did support command line execution back in the day. It was meant to make it easier to execute in "lighter" environments (i.e., within a game engine, controlling a robot, on a cell phone, whatever). As time progressed, it became clear that a general solution for that was at odds with the primary use case: modelers trying to build and analyze their particular phenomenon.

The primary use case relies heavily upon OSGi and Eclipse's dynamic and modular tools. These, however, make traditional command lines much more difficult (and unwieldy). OSGi and Eclipse dynamically check project dependencies and securely set up the various classloaders and resource paths, as well as extensions (for parser, compilers, modules, extensions, etc.) and the actual runtime environment.

This does not mean that you can't run from the command line. You can, but it is a really bad idea to use that mode for the development of a model. Only after you have built, tested, and hardened your model in the IDE should you even think about embedding or command line execution.

Let's assume your model is the awesomsauce and you want to run it command line now. First, you will need the environment.xml file that the IDE generated in the run directory. This tells the org.jactr.entry.Main entry point how to assemble the environment. You will want to strip out the attachments : org.jactr.tools.async.controller.RemoteInterface and org.jactr.tools.tracer.RuntimeTracer, as they are only for IDE runs.

Next, you need the command line that Eclipse uses. To do this, run your model, switch to the debug view and bring up the properties of the running processes. It will include the actual command line. It looks something like this:

/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home/bin/java -Dorg.apache.commons.logging.log=org.apache.commons.logging.impl.Log4JLogger -Dlog4j.configuration=file:/Users/harrison/Archive/Development/workspaces/modeling-dev/mil.navy.nrl.ncarai.associative.fan/jactr-log.xml -Dfile.encoding=MacRoman -Xbootclasspath/p:/Users/harrison/Archive/Development/Apps/3.7/eclipse-model-dev-32/plugins/org.eclipse.jdt.debug_3.7.100.v20120529-1702/jdi.jar -classpath /Users/harrison/Archive/Development/Apps/3.7/eclipse-model-dev-32/plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar org.eclipse.equinox.launcher.Main -application org.jactr.launching.application -data /Users/harrison/.jactr/workspaces/mil.navy.nrl.ncarai.associative.fan -configuration file:/Users/harrison/.jactr/configuration/mil.navy.nrl.ncarai.associative.fan/Embodied-Fan-actual/ -dev file:/Users/harrison/.jactr/configuration/mil.navy.nrl.ncarai.associative.fan/Embodied-Fan-actual/dev.properties -name jACTR -nosplash -os macosx -arch x86 -e file:/Users/harrison/Archive/Development/workspaces/modeling-dev/mil.navy.nrl.ncarai.associative.fan/runs/8.16.12/9.49.28AM/environment.xml

There's a lot of mess in there. Let's break it down.

• -Dorg.apache.commons.logging.log=org.apache.commons.logging.impl.Log4JLogger merely tells the runtime what logger to use. This is optional and controled view the Logging/Trace tab of the run configuration window.
• -Dlog4j.configuration=file:/Users/harrison/Archive/Development/workspaces/modeling-dev/mil.navy.nrl.ncarai.associative.fan/jactr-log.xml this is the logging config file used, again optional.
• -Dfile.encoding=MacRoman -Xbootclasspath/p:/Users/harrison/Archive/Development/Apps/3.7/eclipse-model-dev-32/plugins/org.eclipse.jdt.debug_3.7.100.v20120529-1702/jdi.jar -classpath /Users/harrison/Archive/Development/Apps/3.7/eclipse-model-dev-32/plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar org.eclipse.equinox.launcher.Main -application org.jactr.launching.application This is the main entry point for the jactr-in-eclipse application. Jar files will be dependent upon the version of eclipse you have installed, and where you have it installed.
• -data /Users/harrison/.jactr/workspaces/mil.navy.nrl.ncarai.associative.fan -configuration file:/Users/harrison/.jactr/configuration/mil.navy.nrl.ncarai.associative.fan/Embodied-Fan-actual/ -dev file:/Users/harrison/.jactr/configuration/mil.navy.nrl.ncarai.associative.fan/Embodied-Fan-actual/dev.properties Anything in the ${home}/.jactr/ directory tree is where eclipse stores cached data to accelerated subsequent launches. The contents of these directories is generated on runtime, unless the data already exists. The dev.properties file tells the environment how to combine your workspace projects (i.e., your model) and installed bundles.
• -name jACTR -nosplash -os macosx -arch x86 These are platform specific flags to tell the runtime what to expect (line endings, path separators, etc).
• -e file:/Users/harrison/Archive/Development/workspaces/modeling-dev/mil.navy.nrl.ncarai.associative.fan/runs/8.16.12/9.49.28AM/environment.xml this tells the jACT-R environment to build the environment and wait for the IDE to signal the start. Using -r, instead, will build the environment and immediately execute it.

That will get you up and running on the command line, but again, I don't recommend it. The IDE provides you a ton of tools that will help you understand your model. Command line ninjas will always be at a disadvantage here.

Project management

• Revert edits
• Use source control (i.e. CVS, SVN)
• Import/Export projects

User Interface

• Change code or annotation (e.g. error, warning, reference, bookmark) colors?
• Use collaborative editing?

The IDE includes many useful tools both for tracing/inspecting model execution and for recording information.

Broadly speaking, there are tool classes of tools: instruments and tracers.