A reference guide for ACT-R/PM commands. Parameters that can take one of a few fixed values have | as a separator, those that can take a range of values are in italics. Parameters offset in curly braces {} are optional.
[Toplevel] [All Modules] [Vision Module] [Motor Module] [Audition Module] [Speech Module]
(new-digit-sound digit {onset})
This will create a new digit sound event. The digit parameter should be a string, like "7" and onset will default to the (simulated) time at which the function was called.
(new-other-sound content duration delay recode {string onset} )
Creates a new sound event with the specified properties, which should be self-explanatory (see the section on the Audition Module for details).
(new-tone-sound frequency duration {onset})
Creates a new tone event with supplied frequency and duration, optionally at a specific onset.
(pm-add-chunks)
RPM requires a number of chunks in declarative memory, including state chunks and chunks such as letters and numbers. This function adds them.
(pm-add-types-and-chunks)
Same as above, but this function also executes a number of chunk-type commands so that the chunks can indeed be added. This will be required to initialize the system or if a (clear-all) has been executed.
(pm-delayed-event delay func {args}*)
Causes the Lisp function specified in func to be applied to the provided args at simulated time equal to the current simulated time plus delay (in seconds). Useful for causing interface events.
(pm-get-time)
If *actr-enabled-p* is T, returns the RPM system clock in milliseconds, otherwise calls the Lisp function get-internal-real-time.
(pm-install-window window)
The environment is an MCL window that is perceived and acted upon by RPM. This command tells RPM which window to use.
(pm-prepare-motor specification)
If you want the model to pre-load features, that is, you're assuming the subjects you're modeling have prepared some movement features in advance, this is the command to use. If, for example, you believe your subjects have prepared a PUNCH movement in advance and have specified the hand but not the finger, you'd call (pm-prepare-motor punch :hand left).
(pm-print-icon)
Prints a listing of all of the features (one feature per line) to the icon. Included to assist debugging.
(pm-print-input-q module)
Prints a list of all the entries in the input queue of the specified module. module should be one of :VISION, :MOTOR, :SPEECH, or :AUDIO. Included to assist debugging.
(pm-print-module-state module)
Prints out the state of the specified module, which takes the same values as pm-print-input-q.
(pm-print-sched)
Prints the Master Process schedule queue. For debugging.
(pm-proc-screen {:clear t | nil })
Like the old Visual Interface's proc-screen, this command builds an iconic representation of the installed window. This must be called after install-window but before any commands are sent to the Vision Module. By default, the system assumes this is screen change and not a whole new screen--if it is a whole new screen, the :clear parameter should be set to T to improve performance.
(pm-reset)
This command resets the Master Process to its initial state. It does not affect ACT-R's declarative memory, though.
(pm-run duration)
Runs the Master Process, including the cognitive layer, for duration seconds. This is the main command used to run RPM. Note that this command is not guaranteed to terminate at the specified time--it will not interrupt ACT in the middle of a production cycle and so will generally run for longer than the specified duration. This function returns two values: the actual amount of time run, and the current value of RPM's clock.
(pm-set-hand-location right | left location)
Sets the location of one of the hands to the specified location, which should be an x and y list. So, to set the right hand at (12 2), call (pm-set-hand-location right 12 2).
(pm-set-params parameter-name value {parameter-name value}*)
Sets parameters used by the Master Process and various Modules. For the parameters and their associated keywords, the Parameter Reference.
(pm-show-params {parameter-name}*)
Will print the value of the specified parameters. If none are specified, it prints the values of all parameters.
(pm-step)
This is the stepper for RPM, hopefully useful in debugging. A call to this function will print the current (simulated) time and the Master Process schedule queue and provide a brief menu of options: [A]bort, [D]equeue events only, [R]un one step, [S]earch declarative memory, or [W]hynot. Abort quits the stepper. Dequeue will only process the events scheduled to run at the current time, but will run no productions. Run will dequeue the currently scheduled events and run RPM for one "step." A "step" in RPM does not have a fixed length, but is fairly simple to understand. If the schedule queue is empty, then it runs ACT for one production cycle. If there is something in the schedule queue, it runs ACT up to that event. Search provides ACT-R's sdm functionality in the stepper. Whynot provides ACT-R's whynot functionality in the stepper. See the ACT-R Users Manual for more information about these functions.
(pm-time)
Returns the current time as kept track of by the Master Process. When using RPM, this function should be used instead of ACT-R's actr-time command.
(pm-timed-event time func {args}*)
Causes the Lisp function specified in func to be applied to the provided args at simulated time (in seconds) time. Useful for causing interface events.
clear
This resets the state of a Module to the default. This is useful for clearing out the cached movement features in the Motor Module or the currently-attended object and location in the Vision Module, for example.
find-location {:attended boolean | :screen-x value | :screen-y value | :value description | :kind type | :color value}
Creates a chunk of type visual-location which can be passed to move-attention for later processing. As in the old Visual Interface, suitability of a location is determined by the keyword parameters. :attended determines if the location of the feature has been attended to by a previous call of move-attention. :screen-x and :screen-y can limit the x or y screen position to a specific integer or the words lowest or highest. :value can limit the type of visual feature, with description having the possible values OVAL (for buttons), RECTANGLE (for editable text items), and HORIZONTAL-LINE, VERTICAL-LINE, and DIAGONAL-LINE for text when optimizing is turned off (see the Principles subsection for more information). Note that this call is not necessary since it can implicitly be called in the LHS of a production.
move-attention :location loc {:scale size}
Moves attention and categorizes features at the location given by loc, which should be a chunk of type visual-location. This will typically result in creation of one or more new chunks, which will be accessible through the objects slot of loc (once the move has been completed) or via time now matching (see the section on the Vision Module). The :scale parameter determines the "resolution" of the attentional spotlight and currently supports the values word and phrase.
start-tracking object
When this command is executed, the Vision Module will begin tracking the screen object corresponding to the visual-object specified by object. That is, the object's screen-pos slot will be kept up-to-date, even if the object moves. Tracking stops when a move-attention or clear command is issued.
click-mouse
Simply clicks the mouse at the current location (actually translated into a punch movement). Note that the hand must already be on the mouse, if not, a warning message is printed.
hand-to-mouse
Moves the right hand from wherever it is to the mouse.
hand-to-home
Moves the right hand from wherever it is to its "home row" location on the keyboard.
move-cursor :loc location {:device device}
Moves the cursor to the supplied location, which must be a chunk of type visual-location. device specifies the pointing device, currently either mouse (the default) or joystick-1 (first-order joystick) or joystick-2 (second-order joystick). Movement is actually done with a ply movement, taking time based on Fitts Law.
peck :hand hand :finger finger :r distance :theta direction
Executes a peck movement with the supplied hand/finger. Distance is specified in "key units": the distance between adjacent keys on the keyboard is one "key unit." Direction is in polar coordinates, with 0 set to move right along the x-axis.
peck-recoil :hand hand :finger finger :r distance :theta direction
Same as a peck, but the finger is returned to its original location.
point-hand-at-key :hand hand :to-key key
Sometimes, the hand needs to be repositioned on the keyboard, which is what this call does. hand should be either right or left, and to-key should be the name of a key (as either a symbol or a string). This function positions the hand such that the index finger will be above the supplied key (the other fingers shift as well). Many keys are named with something other than the letter, for example, comma, period, and slash are all used as key names instead of the corresponding single characters.
press-key key
Presses a key on the keyboard. The key parameter determines what movement will actually be made, which may be a punch or a peck-recoil. In general, key should just be a symbol or one-character string for the relevant key (e.g. "B"). Some special keys are supported as well: space, backquote, tab, comma, period, semicolon, slash, hyphen, quote, return, and enter.
punch :hand hand :finger finger
Executes a simple punch movement of the specified hand/finger.
find-sound {:attended boolean | :type type | :onset value | :pitch pitch}
This is the parallel of find-location in vision. This will generate a chunk of type sound-event which can then be passed to attend-sound. Not really necessary since the same functionality is now provided in an implicit LHS call.
attend-sound :event event
This is the parallel of move-attention in vision. The event passed should be a chunk of type sound-event. This will ultimately generate a sound chunk.
listen-for {:attended boolean | :type type | :onset value | :pitch pitch}
Causes the Audition Module to encode a sound, if one can be found that matches the supplied parameters. :attended should be either T or NIL, depending on whether the sound to be encoded has been previously encoded or not. :type should be either TONE, DIGIT, or SPEECH depending on the type of sound to be encoded. :onset can be a specific time or the symbols lowest or highest.
speak string
Speaks the specified string.