|
Command Reference | |
|
|
chil home > projects > ACT-R/PM > documentation > | ||
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 | Vision Module | Motor Module | Audition Module | Speech Module
These are commands you can issue to the interpreter or include directly in Lisp code.
(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. Note that this is not generally necessary because pm-reset includes this functionality.
(pm-add-screen-object object)
Takes a Lisp object and adds the visual representation of the object to the visicon. A build-features-for method must be defined for that object.
(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. Note that this is not generally necessary because pm-reset includes this functionality.
(pm-angle-to-pixels angle)
Sometimes, your code may need to convert a length from degrees of visual angle to pixels. This function will do that.
(pm-attend-location x y)
If you assume the person being modeled is attending some specific location before your model starts, you need to initialize the Vision Module to be attending some location. That's what this is for. So, to have RPM attend the location (74 121), call (pm-attend-location 74 121).
(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-delete-screen-object object)
Takes a Lisp object and removes the visual representation of that object from the visicon. Note that this assumes the relevant build-features-for method sets the screen-obj slot of the icon features it generates to this object.
(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-device device)
RPM communicates with some (usually simulated) device, but you have to tell it which object that device is. The device parameter should be a Lisp object that has the relevant methods defined for an RPM device--see the Device Interface guide for more details. (This used to be called pm-install-window, which will still work.)
(pm-pixels-to-angle pixels)
Sometimes, your code may need to convert a length from pixels to degrees of visual angle. This function will do that.
(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). This should not be used from inside a production and should only be used at the beginning of the model file.
(pm-print-icon)
Prints a listing of all of the features (one feature per line) of the current visual icon (visicon). 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-display {: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 pm-install-device 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. (This command used to be called pm-proc-screen, which will still work.)
(pm-register-articulartion-time string time)
Articulation time is computed by ACT-R based on a fairly dumb formula. If you want to set the time of articulation for a particular string, use this. Time is in seconds.
(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-cursor-position x y)
Sets the location of the cursor to the specified location, which should be an x and y pair. So, to have RPM set the cursor location to (50 37), call (pm-set-cursor-position 50 37).
(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 (or [q]uit) [C]ommand menu printing toggle [D]equeue current events only [I]con: Print the visicon [M]odule state [P]rint a module's input queue [R]un: dequeue current events and advance clock [S]earch declarative memory [W]hnot (also [Y])
Abort quits the stepper.
Command menu printing toggle will suppress printing of this menu if it is being printed, and enable it if printing is suppressed.
Dequeue will only process the events scheduled to run at the current time, but does not advance the clock.
Icon runs the (pm-print-icon) command and prints the current visicon.
Module state prints out the state of one of the PM modules, identified by keyword (one of :MOTOR, :VISION, :AUDIO, or :SPEECH).
Print a module's input queue does exactly what it says. Again, it will request a module by keyword.
Run will dequeue the currently scheduled events and run RPM for one "step." That is, it runs the events which are to execute at the current time, then advances the clock to the next event. (Note that the space bar will execute this command.
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.
visual-location
The visual location buffer only takes one type of request, which is for a new visual location chunk to be placed in the buffer. Requests take this form:
+visual-location> ISA visual-location attended t | nil | new screen-x numeric-spec screen-y numeric-spec distance numeric-spec value symbol kind symbol color symbol size numeric-spec nearest chunk of type VISUAL-LOCATION | current
attended has three allowable values, T, nil, and new. T means the object occupying the location has been seen, nil means is has not, and new means not only has the object not been seen, but that it's a recent onset. Note that nil will match to new objects.
number-spec specifies either a number, a range of numbers, or a criterion on numbers. So, this can simply be a number, (e.g. 3), or one of the following:
(GREATER-THAN value) will match only if the value of the slot is greater than the supplied value.(LESS-THAN value) will match only if the value of the slot is greater than the supplied value.(WITHIN min max) will match only if the value of the slot is in the range min to max, inclusive.LOWEST will find the feature that matches all the other criteria, but with the lowest value for this slot.HIGHEST will find the feature that matches all the other criteria, but with the highest value for this slot.
For screen-x and screen-y, there are three other allowable values, greater-than-current and less-than-current, and current. In this context, current refers to the visual location currently being attended. Thus, less-than-current will match items that have a value less than the current one.
nearest will return the location of the feature matching the other constraints which is closest to the supplied location, which should be a chunk of type visual-location. This will also accept the value current, which will provide the location matching all the other constraints nearest to the currently attended location. Note that this is "nearest" in the retinal distance sense (on the XY) and ignores depth/distance.
visual-object
Requesting a new visual object is fairly straighforward, and takes this form:
+visual> ISA visual-object screen-pos symbol scale word | phrase
screen-pos must be a chunk of type visual-location. This is where visual attention should be directed.
The scale parameter is optional and designed for use with reading text. The "resolution" of the attentional spotlight and currently supports the values word and phrase. word will cause RPM to read the text at the attended location as a whole word, even if optimizing is off. (If optimizing is on, then words will be delivered anyway.) The phrase scale value will read a bunch of text sharing a common vertical location with the attended location, and will produce a chunk representing a phrase of words.
start-tracking
This will initiate tracking of moving visual objects. Requests take this form:
+visual> ISA start-tracking object symbol
object must be a chunk of type visual-object, and should be the object that is currently being attended.
While tracking, the object's screen-pos slot will be kept up-to-date, even if the object moves. The visual location buffer will also be updated, and the visual execution state will be set to busy.
Tracking stops when a +visual> or -visual> command is issued.
punch
Executes a simple punch movement of the specified hand/finger. Usage:
+manual> ISA punch hand right | left finger index | middle | ring | pinkie | thumb
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. Usage is:
+manual> ISA click-mouse
peck
Executes a peck movement with the supplied hand/finger. Distance (that's r) is specified in "key units": the distance between adjacent keys on the keyboard is one "key unit." Direction (that's theta) is in polar coordinates, with 0 set to move right along the x-axis. Usage is:
+manual> ISA peck hand right | left finger index | middle | ring | pinkie | thumb r number theta number
peck
Same as a peck, but the finger is returned to its original location.
+manual> ISA peck hand right | left finger index | middle | ring | pinkie | thumb r number theta number
press-key
Presses a key on the keyboard. The usage is:
+manual> ISA press-key key symbol or string
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
enter.
ply
PLY moves a finger or hand a given distance and direction. Usage is very much like the PECK style above.
+manual> ISA ply hand right | left finger index | middle | ring | pinkie | thumb r number theta number
Usage of PLY directly should be rare; most uses will be more specialized movements based on PLY, such as those below.
move-cursor
This moves the cursor. It is assumed that the right hand moves the mouse. This will print a warning message if the hand is not already at the mouse. Movement is actually done with a ply movement, taking time based on Fitts' Law.
+manual> ISA move-cursor object symbol loc location device mouse | joystick-1 | joystick-2
Either the object or the location must be supplied, but not both. object much be a chunk of type visual-object (or a subtype). location must be a chunk of type visual-location.
device is optional and defaults to mouse. This specifies the pointing device. joystick-1 denotes first-order joystick and joystick-2 denotes second-order joystick).
hand-to-mouse
Moves the right hand from wherever it is to the mouse.
+manual> ISA hand-to-mouse
hand-to-home
Moves the right hand from wherever it is to its "home row" location on the keyboard.
+manual> ISA hand-to-home
point-hand-at-key
Sometimes, the hand needs to be repositioned on the keyboard, which is what this call does. This function positions the hand such that the index finger will be above the supplied key (the other fingers shift as well).
+manual> ISA point-hand-at-key hand right | left to-key symbol or string
hand should be either right or left
to-key should be the name of a key as per PRESS-KEY.
prepare parameters
If you want the Motor Module to prepare but not immediately execute a particular movement, send this with the movement specification as the parameters. So, for instance, if you know the next motor action is going to be a punch of the right index finger, but you're not sure when, you can prepare the movement in advance with !send-command! :motor prepare punch :hand right :finger index.
execute
If there is a movement that has been prepared in advance, execute it.
aural-location
This is the parallel of +visual-location in vision. This will generate a chunk of type sound-event which can then be passed to +aural. The form is as follows:
+aural-location> ISA audio-event attended t | nil type symbol onset number-spec pitch symbol
aural
This is the parallel of +visual> in vision. The event passed should be a chunk of type sound-event. This will ultimately generate a sound chunk. Calls take this form:
+aural> ISA sound event symbol
speak
Speaks the specified string.
+vocal> ISA speak string string
subvocalize
The same as speak, except that this doesn't generate speech output.
+vocal> ISA subvocalize string string
 |
|
 |
People Facilities Research Projects Miscellany Search | Home |
Last modified 2004.03.12