clarion.system
Class CLARION

java.lang.Object
  extended by clarion.system.CLARION

public class CLARION
extends java.lang.Object

This is the main class of the CLARION Library. All agents within a task environment must have their own instance of this class.

Usage:

The CLARION class acts as the "brain" for a CLARION agent. The "brain" of this agent interacts with the task environment using the "perceive" and "act" functions. If setup correctly, only these two methods should need to be called during runtime (after the CLARION agent has been initialized).

The constructor of this class builds a "frame" from which all desired subsystems can be attached. After a CLARION instance has been fully setup, only those subsystems that have been attached will be used when performing action-decision making.

Subsystems and intermediate modules (i.e. the working memory and goal structure) for CLARION must be attached in the following order:

  1. MS
  2. MCS
  3. GoalStructure
  4. ACS
  5. NACS
  6. WorkingMemory

Every instance of CLARION MUST at least have an ACS attached to it in order to operate correctly. This is the MINIMUM requirement for setting up a CLARION agent.

Also, keep in mind that each instance of CLARION needs to have its own instances of the subsystems it uses. CLARION should NOT share instances of subsystems (or any other components within those subsystems for that matter). Doing so would be like saying that two agents share the same brain or parts of the same brain. Also, any component that is given to an instance of CLARION MUST NOT be tied to another instance of CLARION.

While CLARION will automatically create its own internal representation for some components, it is HIGHLY recommended that you create UNIQUE instances for EVERYTHING that is provided and/or attached to a CLARION agent (with the notable exception of the sensory information).

Many of the components located within CLARION (including the subsystems) have options and parameters (in the form of constants) that can be adjusted from their defaults as is deemed necessary by the task being performed. All parameters come in two varieties:

*If you want to set the parameters globally you MUST do so before ANY instances of that component have been initialized.

The parameters can be found within their appropriate components. If you are having trouble locating a parameter, it is advised that you consult the documentation for assistance.

Requirements for using the CLARION Library:

Version:
6.0.5
Author:
Nick Wilson

Field Summary
private  ACS acs
          The Action Centered Subsystem.
private  long Birthdate
          The time-stamp taken from the internal-clock at the moment the CLARION agent in instantiated.
private  AbstractAction ChosenAction
          The chosen action when the "act" method was last called
private  Goal CurrentGoal
          The current goal
private  DimensionValueCollection CurrentInput
          The current input (including perceived sensory information, current goal, and chunks in working memory) for this instance of CLARION.
private  GoalStructure gs
          The Goal Structure.
protected  DimensionValueCollection InputSpace
          A dimension-value collection that contains all of the dimension-value pairs of which this instance of CLARION is currently aware.
private  long InternalClock
          The number of time-steps (incremented whenever an action is performed) that the agent has been alive.
private  MCS mcs
          The Meta Cognitive Subsystem.
private  MS ms
          The Motivational Subsystem.
private  NACS nacs
          The Non Action Centered Subsystem.
private  WorkingMemory wm
          The Working Memory.
 
Constructor Summary
CLARION(DimensionValueCollection SensoryInformationSpace)
          Minimally initializes a CLARION agent.
 
Method Summary
 AbstractAction act()
          Determines the action to perform given what was perceived.
protected  void attachACS(ACS Acs)
          Attaches the action centered subsystem to this instance of CLARION.
protected  void attachGoalStructure(GoalStructure GS)
          Attaches the goal structure to this instance of CLARION.
protected  void attachMCS(MCS Mcs)
          Attaches the meta-cognitive subsystem to this instance of CLARION.
protected  void attachMS(MS Ms)
          Attaches the motivational subsystem to this instance of CLARION.
protected  void attachNACS(NACS Nacs)
          Attaches the non-action centered subsystem to this instance of CLARION.
protected  void attachWorkingMemory(WorkingMemory WM)
          Attaches the working memory to this instance of CLARION.
 void endEpisode()
          Marks the end of an "episode".
private  DimensionValueCollection generateCurrentInput(DimensionValueCollection CurrentSensoryInformation)
          Generates the current input to use inside of CLARION given the current sensory information, the current goal, and the items in working memory.
 ACS getACS()
          Gets the ACS.
 long getAge()
          Gets the age (the number of time steps since this instance of CLARION was initialized) of the agent.
 long getBirthdate()
          Gets the birthdate (the time stamp when this instance of CLARION was initialized) of the agent.
 Goal getCurrentGoal()
          Gets the current goal.
 GoalStructure getGoalStructure()
          Gets the goal structure.
protected  DimensionValueCollection getInputSpace()
          Gets the internal representation of the input space from this instance of CLARION.
 java.util.Collection<Dimension> getInternalInputSpace()
          Gets the internal representation of the input space from this instance of CLARION.
 AbstractAction getLastAction()
          Gets the last action chosen by this instance of CLARION.
 MCS getMCS()
          Gets the MCS.
 MS getMS()
          Gets the MS.
 NACS getNACS()
          Gets the NACS.
 WorkingMemory getWorkingMemory()
          Gets the working memory.
 void perceive(DimensionValueCollection NewSensoryInformation)
          Perceives the new sensory information and performs learning.
 void perceive(DimensionValueCollection NewSensoryInformation, double feedback)
          Perceives the new sensory information as well as any feedback that is to be received for performing the last action.
 void resetGoal()
          Resets the current goal.
 void resetLastAction()
          Resets the last chosen action.
protected  void updateInputSpace(java.util.Collection<Dimension> c)
          Updates the input space based on the specified collection of dimension-value pairs.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

acs

private ACS acs
The Action Centered Subsystem.


nacs

private NACS nacs
The Non Action Centered Subsystem.


ms

private MS ms
The Motivational Subsystem.


mcs

private MCS mcs
The Meta Cognitive Subsystem.


gs

private GoalStructure gs
The Goal Structure. Conceptually, this system exists on the top level of the MS. However, implementationally it is logical to specify it as an intermediate module since it is used by several subsystems.


wm

private WorkingMemory wm
The Working Memory. Conceptually, this system exists between the ACS and the NACS. However, implementationally it is logical to specify it as an intermediate module since it is used by several subsystems.


InputSpace

protected DimensionValueCollection InputSpace
A dimension-value collection that contains all of the dimension-value pairs of which this instance of CLARION is currently aware.


CurrentInput

private DimensionValueCollection CurrentInput
The current input (including perceived sensory information, current goal, and chunks in working memory) for this instance of CLARION.


ChosenAction

private AbstractAction ChosenAction
The chosen action when the "act" method was last called


CurrentGoal

private Goal CurrentGoal
The current goal


Birthdate

private long Birthdate
The time-stamp taken from the internal-clock at the moment the CLARION agent in instantiated.


InternalClock

private long InternalClock
The number of time-steps (incremented whenever an action is performed) that the agent has been alive.

Constructor Detail

CLARION

public CLARION(DimensionValueCollection SensoryInformationSpace)
Minimally initializes a CLARION agent. This constructor builds a "frame" for this instance of CLARION from which all desired subsystems can be attached. After the CLARION instance has been fully setup, only those subsystems that have been attached to this CLARION instance will be used when performing action-decision making.

Parameters:
SensoryInformationSpace - A collection that contains all of the possible dimension-values that can be specified as sensory information to be perceived by a CLARION agent.
Method Detail

perceive

public void perceive(DimensionValueCollection NewSensoryInformation)
              throws MissingACSException
Perceives the new sensory information and performs learning.

If you are using the drive equation (or its equivalent) for calculating drive strengths within the MS, the sensory information should also include a dimension with the ID "STIMULUS" that contains the stimulus values for each of the drives. The stimulus for the drives is simply a translation from the sensory information (or context) into a single value to be used by the drive equation (etc.) for calculating the drive strength.

Parameters:
NewSensoryInformation - The new sensory information to be perceived.
Throws:
MissingACSException - If no instance of the ACS has been initialized.

perceive

public void perceive(DimensionValueCollection NewSensoryInformation,
                     double feedback)
              throws MissingACSException
Perceives the new sensory information as well as any feedback that is to be received for performing the last action. In addition, this method performs learning based on the feedback.

If you are using the drive equation (or its equivalent) for calculating drive strengths within the MS, the sensory information should also include a dimension with the ID "STIMULUS" that contains the stimulus values for each of the drives. The stimulus for the drives is simply a translation from the sensory information (or context) into a single value to be used by the drive equation (etc.) for calculating the drive strength.

Parameters:
NewSensoryInformation - The new sensory information to be perceived.
feedback - The feedback received for performing the last action.
Throws:
MissingACSException - If no instance of the ACS has been initialized.

act

public AbstractAction act()
                   throws MissingACSException,
                          MissingSensoryInformationException
Determines the action to perform given what was perceived. If this instance of CLARION does not contain an ACS or no sensory information has been perceived (by calling the perceive method) this method will throw an exception.

Returns:
The chosen action.
Throws:
MissingACSException - If no instance of the ACS has been initialized.
MissingSensoryInformationException - If no sensory information has been perceived.

generateCurrentInput

private DimensionValueCollection generateCurrentInput(DimensionValueCollection CurrentSensoryInformation)
Generates the current input to use inside of CLARION given the current sensory information, the current goal, and the items in working memory.

Parameters:
CurrentSensoryInformation - The current sensory information being perceived.
Returns:
The current input for use within CLARION.

attachGoalStructure

protected void attachGoalStructure(GoalStructure GS)
Attaches the goal structure to this instance of CLARION. This method is called by the GoalStructure class when it is first initialized. When the GoalStructure class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the goal structure "growing out of" the CLARION agent.

Parameters:
GS - The goal structure to be attached.

attachWorkingMemory

protected void attachWorkingMemory(WorkingMemory WM)
Attaches the working memory to this instance of CLARION. This method is called by the WorkingMemory class when it is first initialized. When the WorkingMemory class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the working memory "growing out of" the CLARION agent.

Parameters:
WM - The working memory to be attached.

attachACS

protected void attachACS(ACS Acs)
Attaches the action centered subsystem to this instance of CLARION. This method is called by the ACS class when it is first initialized. When the ACS class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the ACS "growing out of" the CLARION agent.

Parameters:
Acs - The action centered subsystem to be attached.

attachMS

protected void attachMS(MS Ms)
Attaches the motivational subsystem to this instance of CLARION. This method is called by the MS class when it is first initialized. When the MS class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the MS "growing out of" the CLARION agent.

Parameters:
Ms - The motivational subsystem to be attached.

attachMCS

protected void attachMCS(MCS Mcs)
Attaches the meta-cognitive subsystem to this instance of CLARION. This method is called by the MCS class when it is first initialized. When the MCS class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the MCS "growing out of" the CLARION agent.

Parameters:
Mcs - The meta-cognitive subsystem to be attached.

attachNACS

protected void attachNACS(NACS Nacs)
Attaches the non-action centered subsystem to this instance of CLARION. This method is called by the NACS class when it is first initialized. When the NACS class is initialized it will automatically attach itself to this instance of CLARION. Conceptually, this can be conceived of as the NACS "growing out of" the CLARION agent.

Parameters:
Nacs - The non-action centered subsystem to be attached.

getACS

public ACS getACS()
Gets the ACS.

Returns:
the ACS.

getMS

public MS getMS()
Gets the MS.

Returns:
the MS.

getMCS

public MCS getMCS()
Gets the MCS.

Returns:
the MCS.

getNACS

public NACS getNACS()
Gets the NACS.

Returns:
the NACS.

getGoalStructure

public GoalStructure getGoalStructure()
Gets the goal structure.

Returns:
the goal structure.

getWorkingMemory

public WorkingMemory getWorkingMemory()
Gets the working memory.

Returns:
the working memory.

getInputSpace

protected DimensionValueCollection getInputSpace()
Gets the internal representation of the input space from this instance of CLARION. This method is used by the subsystems (and intermediate modules) as part of attaching themselves to an instance of CLARION.

Returns:
The internal input space.

getInternalInputSpace

public java.util.Collection<Dimension> getInternalInputSpace()
Gets the internal representation of the input space from this instance of CLARION. The collection returned is unmodifiable and is meant for reporting the internal state only.

Returns:
An unmodifiable collection containing this instance of CLARION's internal representation of the input space.

getLastAction

public AbstractAction getLastAction()
Gets the last action chosen by this instance of CLARION.

Returns:
The last action chosen.

getCurrentGoal

public Goal getCurrentGoal()
Gets the current goal. If goals are not being used by this instance of CLARION then this method will return null.

Returns:
The current goal.

resetLastAction

public void resetLastAction()
Resets the last chosen action.


resetGoal

public void resetGoal()
Resets the current goal.


getAge

public long getAge()
Gets the age (the number of time steps since this instance of CLARION was initialized) of the agent.

Returns:
The age of the agent.

getBirthdate

public long getBirthdate()
Gets the birthdate (the time stamp when this instance of CLARION was initialized) of the agent.

Returns:
The birthdate of the agent.

endEpisode

public void endEpisode()
Marks the end of an "episode". The CLARION agent will perform a series of internal instructions related to ending an episode when this method is called. Calling this method does not increment the age of the agent and is therefore considered to be a process that occurs pseudo-automatically without needing the agent to expend time to perform.


updateInputSpace

protected void updateInputSpace(java.util.Collection<Dimension> c)
Updates the input space based on the specified collection of dimension-value pairs. If any dimensions or values exist within the specified collection that are not currently in the input space, those dimensions and/or values are added to the input space.

Parameters:
c - The collection of dimension-value pairs with which to update the input space.