API for package ACT-UP

The ACT-UP library. Defines a number of functions and macros implementing the ACT-R theory (Anderson 1993, Anderson et al. 1998, Anderson 2007, etc.). (C) 2010, David Reitter, Carnegie Mellon University.

*act-up-version*   variable

Version of a loaded ACT-UP. ACT-UP has been correctly initialized if this is defined and non-nil.
Initial value: "27bc8ed"

*all*   variable

Constant for *debug*: Show all messages (maximum detail).
Initial value: 1000

*alpha*   variable

Utility learning rate. See also the function assign-reward. See also: ACT-R parameter :alpha
Initial value: 0.2

*ans*   variable

Transient noise parameter for declarative memory. See also: ACT-R parameter :ans
Initial value: 0.2

*associative-learning*   variable

The trigger for associative learning, a in ROM Equation 4.5.
   Can be any non-negative value.
Initial value: NIL

*au-rfr*   variable

base reward proportion for each procedure e.g., the each procedure before the reward trigger gets 10% of the reward. Set to nil (default) to use the ACT-R discounting by time in seconds. See also the parameter *au-rpps* and the function assign-reward.
Initial value: NIL

*au-rpps*   variable

Reward proportion per second elapsed. e.g., after 10 seconds we want to assign 50% of the remaining reward: 0.5/10 = 0.05 time is in between procedures. Set to nil (default) to use the ACT-R discounting by time in seconds. See also the parameter *au-rfr* and the function assign-reward.
Initial value: NIL

*blc*   variable

Base-level constant parameter for declarative memory. See also: ACT-R parameter :blc
Initial value: 0.0

*bll*   variable

Base-level learning decay parameter for declarative memory. See also: ACT-R parameter :bll
Initial value: 0.5

*critical*   variable

Constant for *debug*: Show only critical messages.
Initial value: 0

*current-actup-meta-process*   variable

The current ACT-UP meta-process. The meta process keeps track of simulation time. May be read and manipulated by setting it to a different instance of type meta-process.
Initial value: #S(META-PROCESS :ACTUP-TIME 0.0D0 :NAME NIL)

*dat*   variable

Default time that it takes to execut an ACT-UP procedure in seconds. See also: ACT-R parameter :dat [which pertains to ACT-R productions]
Initial value: 0.05D0

*debug*   variable

Level of debug output currently in effect. The following constants may be used: *critical* *warning* *informational* *all* The parameter *debug-to-log* is helpful in logging debug messages to a file.
Initial value: 10

*debug-to-log*   variable

Enable off-screen logging of debug output. If t, ACT-UP logs all debug messages not to standard output, but to a buffer that can be read with debug-log and cleared with debug-clear. If a stream, ACT-UP logs to the stream.
Initial value: NIL

*declarative-finst-span*   variable

Declarative Finst time span The maximum time period during whichg a finst marks a chunk as recently retrieved. Chunks retrieved longer ago are not considered 'recently retrieved'. Time in seconds, defaults to 3.0. See ACT-R parameter :declarative-finst-span
Initial value: 3.0

*declarative-num-finsts*   variable

Number of Declarative Finsts The maximum number of chunks considered recently retrieved. Defaults to 4. See ACT-R parameter :declarative-num-finsts
Initial value: 4

*detailed*   variable

Constant for *debug*: Show detailed log output .
Initial value: 300

*egs*   variable

Transient noise parameter for ACT-UP procedures. This is the expected gain s parameter. It specifies the s parameter for the noise added to the utility values. It defaults to 0 which means there is no noise in utilities. See also: ACT-R parameter :egs
Initial value: NIL

*informational*   variable

Constant for *debug*: Show informational and more important messages.
Initial value: 100

*iu*   variable

Initial procedure utility. The initial utility value for a user-defined procedure (defproc). This is the U(0) value for a production if utility learning is enabled and the default utility if learning (*ul*) is not enabled. The default value is 0. See also the function assign-reward. See also: ACT-R parameter :iu
Initial value: 0.0

*le*   variable

Latency Exponent parameter for declarative retrieval time calculation. See ACT-R parameter :le
Initial value: 1.0

*lf*   variable

Latency Factor parameter for declarative retrieval time calculation. See ACT-R parameter :lf
Initial value: 1.0

*maximum-associative-strength*   variable

Maximum associative strength parameter for Declarative Memory. *mas* is defined as alias for maximum-associative-strength. See also *associative-learning*, reset-sji-fct. See also: ACT-R parameter :mas.
Initial value: 1.0

*md*   variable

ACT-UP Partial Match Maximum Difference Similarity penalty assigned when chunks are different and no explicit similarity is set. Value in activation (log) space.
Initial value: -1

*mp*   variable

ACT-UP Partial Match Scaling parameter Mismatch (set-similarities-fct) is linearly scaled using this coefficient.
Initial value: 1.0

*ms*   variable

ACT-UP Partial Match Maximum Similarity Similarity penalty assigned when chunks are equal. Value in activation (log) space.
Initial value: 0

*nu*   variable

Utility assigned to compiled procedures. This is the starting utility for a newly learned procedure (those created by the production compilation mechanism). This is the U(0) value for such a procedure if utility learning is enabled and the default utility if learning is not enabled. The default value is 0. See also the function assign-reward and the variable *procedure-compilation*. See also: ACT-R parameter :nu
Initial value: 0.0

*ol*   variable

Optimized Learning parameter for base-level learning in Declarative Memory. OL is always on in ACT-UP. See also: ACT-R parameter :ol
Initial value: 3

*pas*   variable

Permanent noise parameter for declarative memory. See also: ACT-R parameter :pas
Initial value: NIL

*procedure-compilation*   variable

If non-nil, procedure compilation is enabled. Procedure compilation causes ACT-UP procedures defined with defproc to be compiled (or: cached). After execution of a source procedure, name, execution arguments and the result are stored as compiled procedure. The compiled procedure is added to each of the source procedure's groups. When the group is executed, compiled procedures compete for execution with the other procedures in the group. (The procedure with the highest utility is chosen.) The initial utility of a compiled procedure equals the initial utility of the source procedure. When a source procedure is compiled multiple times, the utility of the compiled procedure is updated by assigning the source procedure utility as reward to the compiled procedure (according to the ACT-R difference learning equation). See also assign-reward for reward assignment to regular procedures. *epl* is defined as alias for *procedure-compilation*.
Initial value: NIL

*rt*   variable

Retrieval Threshold parameter for declarative memory. Chunks with activation lower than *rt* are not retrieved. See also: ACT-R parameter :rt
Initial value: 0.0

*ul*   variable

Utility learning flag. If this is set to t, then the utility learning equation used above will be used to learn the utilities as the model runs. If it is set to nil then the explicitly set utility values for the procedures are used (though the noise will still be added if *egs* is non-zero). The default value is nil. See also the function assign-reward. Only if assign-reward is called will this parameter have any effect. See also: ACT-R parameter :ul
Initial value: T

*ut*   variable

Utility threshold. This is the utility threshold. If it is set to a number then that is the minimum utility value that a procedure must have to compete in conflict resolution. Procedures with a lower utility value than that will not be selected. The default value is nil which means that there is no threshold value and all procedures will be considered. See also: ACT-R parameter :ut
Initial value: NIL

*warning*   variable

Constant for *debug*: Show warnings and more important messages.
Initial value: 10

actup-chunk   structure

Type defining an ACT-UP chunk. Derive your own chunks using this as a base structure by using define-chunk.

(actup-time &optional meta-process)   function

Returns the current runtime. An optional parameter META-PROCESS specifies the meta-process to use. It defaults to the current meta-process.

(add-chunk-to-dm chunk first-presentation-time recent-presentation-times number-of-presentations)   function

Add CHUNK to declarative memory of current model. FIRST-PRESENTATION-TIME indicates the time of first presentation of the chunk (see also actup-time). RECENT-PRESENTATION-TIMES is a list of the *ol* or less most recent presentation times. NUMBER-OF-PRESENTATIONS indicates the total number of presentation, including the first one.

(add-sji-fct list)   function

Set Sji link weights between chunks. LIST is a list with elements of form (CJ NI S), where CJ und NI are chunks or chunk names, and S is the new link weight, regulating spreading activation when CJ is in context as a cue and NI is retrieved. S may also be a list of form (FCN TIME), with FCN indicating frequency of CJ and NI occurring together, and TIME indicating the point in time of their last joint occurrence (TIME is unused currently, but must be given.)

(assign-reward reward)   function

Assign reward to recently invoked procedures. Distributes reward value REWARD across the recently invoked procedures. See parameters *au-rpps*, *au-rfr*, *alpha*, and *iu*. See defproc for documentation on how to use utility when selecting between procedures. Reward must be greater than 0. The reward is only distributed to procedures invoked since the last call to assign-reward (or flush-procedure-queue, or reset-model). See also assign-reward* for a function that does not reset this set of procedures.

(assign-reward* reward)   function

Like assign-reward, but does not flush the procedure queue. Only reward portions >0 are assigned to procedures, i.e., if *au-rfr* or *au-rpps* are nil (ACT-R 6 reward propagation), rewards are only assigned to procedures up to reward seconds back in time. See also flush-procedure-queue.

(best-chunk confusion-set &key cues soft-spec timeout inhibit-cues)   function

Retrieves the best chunk in confusion set. CONFUSION-SET is a list of chunks, out of which the chunk is returned. CUES is a list of cues that spread activation. CUES may contain chunk objects or names of chunks. SOFT-SPEC: request specification for partial matching (see also retrieve-chunk). INHIBIT-CUES: do not use (yet). Simulates timing behavior with pass-time. Marks the chunk as recently retrieved (declarative finst). Note that this function extends beyond the power of ACT-R's declarative module. See also the higher-level function retrieve-chunk.

(blend chunks &key cues chunk-type retrieval-spec)   function

Return a blended variant of chunks. Activation is calculated using spreading activation from CUES. CUES may contain chunk objects or names of chunks. The returned chunk is of type CHUNK-TYPE; all CHUNKS must be of type CHUNK-TYPE or of a supertype thereof. If CHUNK-TYPE is not given, all CHUNKS must be of the same class and the returned type will be this class. RETRIEVAL-SPEC should contain the retrieval filter used to obtain CHUNKS; attribute-value pairs in it will be included in the returned chunk as-is and not be blended from the CHUNKS. See also the higher-level function blend-retrieve-chunk.

(blend-retrieve-chunk spec &key cues soft-spec recently-retrieved)   function

Retrieve a blended chunk from declarative memory. The blended chunk is a new chunk represeting the chunks retrievable from declarative memory under specification SPEC. The contents of the blended chunk consist of a weighted average of the retrievable chunks, whereas each chunk is weighted according to its activation. CUES is, if given, a list of chunks that spread activation to facilitate the retrieval of target chunks. CUES may contain chunk objects or names of chunks. SOFT-SPEC is, if given, a retrieval specification whose constraints are soft; partial matching is used for this portion of the retrieval specification. SPEC and SOFT-SPEC are lists of the form (:slot1 value1 :slot2 value2 ...), or (slot1 value1 slot2 value2).

(chunk-name chunk)   function

The unique name of CHUNK. The returned value is a symbol assigned as unique name of CHUNK in the current model.

(current-model)   function

Evaluates to the currently active ACT-UP model.

(debug-clear)   function

Clear the ACT-UP debug log buffer.

(debug-detail &body body)   function

Evaluates BODY while outputting ACT-UP debug information.

(debug-detail* &body body)   function

Evaluates BODY while logging ACT-UP debug information. The log output can be retrieved with debug-log.

(debug-grep keyword &body body)   function

Evaluates BODY while outputting ACT-UP debug information.

(debug-log)   function

Returns logged ACT-R output. If *debug-to-log* is set to t, the ACT-UP debug log may be retrieved using this function.

(define-chunk-type type &rest members)   function

Define a chunk type of name TYPE. MEMBERS should contain all possible elements of the chunk type. TYPE may be a symbol or a list of form (name2 :include parent-type), whereas PARENT-TYPE refers to another defined chunk type whose elements will be inherited. MEMBERS may be a list of symbols, or also a list of member specifiers as used with the lisp defstruct macro, which see.
  
Chunks make be created by invoking the make-TYPE function, whereas TYPE stands for the name of the chunk type as defined with this macro. An attribute called :name should be included to specify the unique name of the chunk (the name may not be used for any other chunk in the model). Chunk contents must not be changed after a chunk has been created. An additional function of name make-TYPE* is also provided, which creates a new chunk just like make-TYPE does, but only if such a chunk does not yet exist in declarative memory (of the current model). All slot values of the chunks are used in the comparison (unspecified ones at their default values), except the :name attribute. If a matching chunk is found in DM, it is returned.

(define-slots &rest slot-names)   function

Define slots to be used in chunks of this process. Only slot names defined using this macro may be used in chunks. Overrides any slot set defined earlier.

(defproc name args &rest body)   function

Define an ACT-UP procedure. The syntax follows the Lisp defun macro, except that some keyword-argument parameters may follow ARGS at the beginning of BODY. This macro will define a Lisp function of name NAME with arguments ARGS. The Lisp function will execute the Lisp forms in BODY and return the value of the last form. The known parameters are:
 :GROUP the-group
A :group parameter defines one or or a list of procedure groups that the procedure will belong to. All procedures defined as part of a group must have the same argument footprint. If GROUP is given, a function of name GROUP will also be defined that invokes one of the procedures assigned to GROUP. For example:
 (defproc subtract-digit-by-addition (minuend subtrahend)
   :group subtract
   "Perform subtraction of a single digit via addition."
   (let ((chunk (retrieve-chunk #96;(:chunk-type addition-fact
                                  :result ,minuend
                                  :add1 ,subtrahend))))
       (if chunk (addition-fact-add2 chunk))))
 (defproc subtract-digit-by-decrement (minuend subtrahend)
   :group subtract
   "Perform subtraction of a single digit via subtraction knowledge."
   ...)
These procedures can be invoked via a function call such as
 (subtract 5 2)
ACT-UP will choose the procedure that has the highest utility. See assign-reward for manipulation of utilities (reinforcement learning), and *procedure-compilation* for in-theory compilation of procedures (routinization, internalization).
 :INITIAL-UTILITY u
The :initial-utility parameter sets the utility that this procedure receives when it is created or the model is reset. If not given, the initial utility will be the value of *iu* at time of first invocation. Procedure utilities, wether initial or acquired through rewards are always specific to the model. Procedures and groupings of procedures are not specific to the model.

(defrule args)   function

Alias for defproc. This is provided for compatibility with some early published examples of ACT-UP code. Please use defproc instead.

(explain-activation chunk-or-name &optional cues retr-spec)   function

Returns a string with an explanation of the evaluation of CHUNK. CUES contains retrieval cues spreading activation. RETR-SPEC describes the retrieval specification for partial matching retrievals.

(filter-chunks chunk-set spec &key recently-retrieved)   function

Filter chunks according to SPEC. SPEC is a list of the form (:slot1 value1 :slot2 value2 ...), or (slot1 value1 slot2 value2). CHUNK-SET is the list of chunks to be filtered (1), or an associative array (2) of the form ((X . chunk1) (Y . chunk2) ...). returns a list of chunks in case (1) and a list of conses in case (2).

(flush-procedure-queue)   function

Empties the queue of procedures in the current model. This resets the list of procedures to which rewards can be distributed (see assign-reward and assign-reward*).

(learn-chunk chunk &key co-presentations)   function

Learn chunk CHUNK. This will note a presentation of a chunk in the model's DM. If the chunk does not already exist in DM, it is added. To create or obtain the chunk from a attribute-value specification, use make-chunk and make-chunk* (or their corresponding constructor functions for a specific chunk type - see define-chunk-type), then apply learn-chunk on the result. Returns the added chunk.

(make-chunk &rest args)   function

Create an ACT-UP chunk. Arguments should consist of named chunk feature values: ARGS is a list of the form (:name1 val1 :name2 val2 ...), whereas names correspond to slot names as defined with define-slots. An attribute called :name should be included to specify the unique name of the chunk (the name may not be used for any other chunk in the model). If chunk types are defined with define-chunk-type, then use the make-TYPE syntax instead.

(make-chunk* &rest args)   function

Like make-chunk, but returns matching chunk from declarative memory if one exists. Arguments should consist of named chunk feature values: ARGS is a list of the form (:name1 val1 :name2 val2 ...), whereas names correspond to slot names as defined with define-slots. An attribute called :name should be included to specify the name of the chunk. Comparing the proposed chunks (in ARGS) to the existing chunks in Declarative Memory, the names of the chunks are ignored. The purpose of this function lies in the ability to boost a chunk existing in DM, when its contents are already known. For example:
 (reset-model)
 (learn-chunk (make-chunk* :one 1 :two 2))
 (learn-chunk (make-chunk* :one 1 :two 2))
will create a chunk (first call), and then boost it, while
 (learn-chunk (make-chunk :one 1 :two 2))
will always create new chunk and add it to declarative memory. If chunk types are defined with define-chunk-type, then use the make-TYPE* syntax instead.

(make-meta-process &key actup-time name)   function

Create a new ACT-UP meta-process. NAME, if given, specifies a name. The meta process keeps track of simulation time. See also meta-process and *current-actup-meta-process*.

(make-model &key name parms pm dm modules time)   function

Create a new ACT-UP model. NAME, if given, specifies a name.

meta-process   structure

An ACT-UP meta process. A meta process keeps track of time for one or more models.

(meta-process-name x)   function

Return the name of an ACT-UP meta-process. See also meta-process and *current-actup-meta-process*.

(model-chunks &optional model)   function

Evaluates to the list of chunks in the given model MODEL.

(model-name x)   function

Return the name of an ACT-UP model.

(pass-time seconds &optional meta-process)   function

Simulates the passing of time. An optional parameter META-PROCESS specifies the meta-process to use. It defaults to the current meta-process.

(pc obj &key stream internals)   function

Print a human-readable representation of chunk OBJ. STREAM, if given, indicates the stream to which output is sent. INTERNALS, if given and t, causes pc to print architectural internals (see also pc* for a shortcut).

(pc* obj &key stream)   function

Print a human-readable representation of chunk OBJ, including architectural internals. STREAM, if given, indicates the stream to which output is sent.

(reset-actup)   function

Resets architectural ACT-UP parameters, meta-process and current model.

(reset-model)   function

Resets the current ACT-UP model. All declarative memory and all subsymbolic knowledge is deleted. Global parameters (dynamic, global Lisp variables) are retained, as are functions and model-independent procedures.

(reset-mp)   function

Resets the current Meta process. Resets the time in the meta process.

(reset-sji-fct chunk)   function

Removes all references to CHUNK from all other chunks in the current model.

(retrieve-chunk spec &key cues soft-spec timeout recently-retrieved)   function

Retrieve a chunk from declarative memory. The retrieved chunk is the most highly active chunk among those in declarative memory that are retrievable and that conform to specification SPEC. CUES is, if given, a list of chunks that spread activation to facilitate the retrieval of a target chunk. CUES may contain chunk objects or names of chunks. SOFT-SPEC is, if given, a retrieval specification whose constraints are soft; partial matching is used for this portion of the retrieval specification. SPEC and SOFT-SPEC are lists of the form (:slot1 value1 :slot2 value2 ...), or (slot1 value1 slot2 value2). TIMEOUT, if given, specifies the maximum time allowed before the retrieval fails. RECENTLY-RETRIEVED, if given, may be either t, in which case the retrieved chunk must have a declarative finst (i.e., has been recently retrieved), or nil, in which is must not have a finst. See also *declarative-num-finsts* and *declarative-finst-span*.

(set-base-level-fct chunk value &optional creation-time)   function

Set base levels of CHUNK. If CREATION-TIME is specified, it contains the time at which the chunk was created in declarative memory, and VALUE contains the number of presentations (an integer value). If TIME is not specified, VALUE is the chunk's absolute activation value (log space). For plausibility reasons, models should specify presentations and time when possible.

(set-base-levels-fct list)   function

Set base levels of several chunks. ACT-R compatibility function. LIST contains elements of form (CHUNK PRES TIME) or (CHUNK ACT), whereas CHUNK is a chunk object or the name of a chunk, PRES is a number of past presentations (integer), and TIME the life time of the chunk, and ACT the chunk's absolute activation. For plausibility reasons, models should not use the ACT form when possible.

(set-current-model new-model)   function

Switches the currently active ACT-UP model. See also current-model and with-current-model.

(set-dm-total-presentations npres)   function

Set the count of total presentations of all chunks in DM. This value is relevant for associative learning (Sji/Rji).

(set-similarities-fct list)   function

Set similarities between chunks. LIST is a list with elements of form (A B S), where A und B are chunks or chunk names, and S is the new similarity of A and B. For example:
 (set-similarities-fct '((dave david -0.05) 
                         (steve hank -0.1)  
                         (mary john -0.9)))

(set-similarity chunk-1 chunk-2 similarity)   function

Set similarity between chunks. CHUNK-1 and CHUNK-2 are chunks or chunk names. SIMILARITY is the new similarity of CHUNK-1 and CHUNK-2. See also set-similarities-fct for an ACT-R compatibility function.

(set-sji chunk-j chunk-i s)   function

Set Sji link weight between two chunks. CHUNK-J und CHUNK-I are chunks or chunk names, and S is the new link weight, regulating spreading activation when CHUNK-J is in context as a cue and CHUNK-I is retrieved. S may also be a list of form (FCN TIME), with FCN indicating frequency of CHUNK-J and CHUNK-I occurring together, and TIME indicating the point in time of their last joint occurrence (TIME is unused currently, but must be given.)

(show-chunks &optional constraints)   function

Prints all chunks in model MODEL subject to CONSTRAINTS. See the function filter-chunks for a description of possible constraints.

(show-parameters &optional show-all)   function

Print architectural ACT-UP parameters different from their defaults. If SHOW-ALL is non-nil, print even unchanged parameters.

(show-utilities)   function

Prints a list of all utilities in the current model.

(stop-actup-time &body body)   function

Returns execution time of BODY in current ACT-UP model. Evaluates BODY. See also actup-time.

(wait-for-model &optional model)   function

Waits until meta-process and MODEL are synchronized. When a model is run with a new meta-process, it can happen that the meta-process time is behind the model's time (since the model was operated with a different meta-process before). This will generate warnings or errors. This function waits (see pass-time) until the model is ready, that is, it sets the meta process time to the model time if the model time is more advanced, plus the current value of *dat*. MODEL defaults to the current model.

(with-current-model model &body body)   function

Execute forms in BODY with the ACT-UP model MODEL being current. See also current-model and set-current-model.

Documentation generated by lispdoc running on Clozure Common Lisp