clarion.system
Class MS

java.lang.Object
  extended by clarion.system.AbstractSubsystem
      extended by clarion.system.MS

public final class MS
extends AbstractSubsystem

This class implements the Motivational Subsystem (MS) within CLARION. It extends the AbstractSubsystem class.

Usage:

This implementation of the motivational subsystem is in charge of one thing, and one thing only:
The Drives!

Drives are primarily used in CLARION to guide the meta-cognitive tasks performed by the various modules within the MCS. Each drive has an implicit module that is used to derive an activation level for its "drive strength." The drive strengths are then passed to the MCS as well as possibly other subsystems (as defined by the user) so they can be used to guide anything from ACS level probability setting to goal selection and action decision making.

Drives can either be user defined or they can be specified from the list of primary drives defined by the CLARION theory.

If you wish to use the primary drives, an enumerator ("PrimaryDrives") containing the IDs for those drives can be found in the Personality class located within tools package of the CLARION Library.

When adding drives to the MS, they can be placed in any of 3 "behavioral systems" located within the MS:

*If a drive is both approach and avoidance in nature, it will be contained within both of the behavioral systems.

It should also be noted that each of the behavioral systems have their own gain parameter that is used (primarily by the drive equation) for calculating the drive strengths for the drives located within each system respectively.

Below is a list of the primary drives and the behavioral system to which they are affiliated:

The CLARION Library is perfectly capable of handing drives that are arbitrarily defined (i.e. not a primary drive). However, conceptually, any user defined drives should be thought of as a derived drive which (theoretically, not implementationally) extends from a combination of the primary drives. For example, the hypothetical drive for "success" could derive from a combination of the Affiliation & Belongingness, Recognition & Achievement, Dominance & Power, etc. drives.

Although, conceptually, the goal structure is also located on the top level of the MS, implementationally it is logical to specify it as an intermediate module since it is used by several subsystems. Therefore, in the CLARION Library, the goal structure is contained within the CLARION class.

In addition to having methods for getting, adding and manipulating drives, the MS also has methods for defining the concept of a "personality", based on the combination of the drives. The CLARION Library comes pre-packaged with a few pre-defined personalities, which are located in the Personality class (as the enumerator "PersonalityTypes"). If you want to quickly setup the MS with one of these personalities, you can do so by simply calling the constructor that takes in a "personality type" (from the Personality class) as a parameter and will automatically generate the appropriate drives for you.

There is also a method within the MS to allow you to define your own personality by simply passing in a collection of Value objects (representing drive deficits) where the IDs of those Values are equal to the values from the enumerated type, "PrimaryDrives", located in the Personality class.

Note that it is not required that a CLARION agent even have an MS at all. If the task being performed by the agent does not require an MS, the user can choose simply not to attach the MS to the CLARION agent, and the agent will be able to operate quite successfully without this subsystem being specified (for some tasks).

Version:
6.0.5
Author:
Nick Wilson

Field Summary
private  BehavioralApproachSystem BAS
          The behavioral approach system
private  BehavioralInhibitionSystem BIS
          The behavioral inhibition system
private  DimensionValueCollection CurrentInput
          The current input (including current sensory information, current goal, chunks in working memory, and drive stimulus).
private  NeitherBehavioralSystem NEITHER
          The system for drives that belong to neither behavioral system
private static long serialVersionUID
           
 
Fields inherited from class clarion.system.AbstractSubsystem
InputSpace
 
Constructor Summary
MS(CLARION Agent)
          Minimally initializes the MS.
MS(CLARION Agent, Personality.PersonalityTypes Pers)
          Initializes the MS with the personality specified.
 
Method Summary
 void addDrivesToBAS(java.util.Collection<Drive> drives)
          Adds the specified drives to the behavior approach system.
 void addDrivesToBIS(java.util.Collection<Drive> drives)
          Adds the specified drives to the behavior inhibition system.
 void addDrivesToBothSystems(java.util.Collection<Drive> drives)
          Adds the specified drives to both the BIS and the BAS.
 void addDrivesToNeither(java.util.Collection<Drive> drives)
          Adds the specified drives to the MS without specifying a behavioral system.
 void addDriveToBAS(Drive drive)
          Adds the specified drive to the behavior approach system.
 void addDriveToBIS(Drive drive)
          Adds the specified drive to the behavior inhibition system.
 void addDriveToBothSystems(Drive drive)
          Adds the specified drive to both the BIS and the BAS.
 void addDriveToNeither(Drive drive)
          Adds the specified drive to the MS without specifying a behavioral system.
protected  void attachSelfToAgent(CLARION Agent)
          Attaches the MS to the specified CLARION agent.
 DriveStrengthCollection calculateAllDriveStrengths(DimensionValueCollection DriveInput)
          Gets the drive strengths for ALL drives in the MS.
 DriveStrengthCollection calculateBASDriveStrengths(DimensionValueCollection DriveInput)
          Gets the drive strengths for all drives in the behavioral approach system.
 DriveStrengthCollection calculateBISDriveStrengths(DimensionValueCollection DriveInput)
          Gets the drive strengths for all drives in the behavioral inhibition system.
 DriveStrengthCollection calculateBothDriveStrengths(DimensionValueCollection DriveInput)
          Gets the drive strengths for all drives that belong to both the BAS and BIS.
 DriveStrength calculateDriveStrength(java.lang.Object ID, DimensionValueCollection DriveInput)
          Gets the drive strength for the drive with the specified ID.
 DriveStrengthCollection calculateNeitherDriveStrengths(DimensionValueCollection DriveInput)
          Gets the drive strengths for all drives in the MS that do not belong to a behavioral system.
protected  void endEpisode()
          Performs the appropriate end of episode instructions for the MS.
 java.util.Collection<Drive> getAllDrives()
          Gets the all the drives in the MS.
 java.util.Collection<DriveStrength> getAllDriveStrengths()
          Gets all of the drive strength objects for the drives in the MS.
 BehavioralApproachSystem getBAS()
          Gets the BAS.
 java.util.Collection<Drive> getBASDrives()
          Gets the drives in the behavioral approach system.
 java.util.Collection<DriveStrength> getBASDriveStrengths()
          Gets the drive strengths for the drives in the behavioral approach system.
 BehavioralInhibitionSystem getBIS()
          Gets the BIS.
 java.util.Collection<Drive> getBISDrives()
          Gets the drives in the behavioral inhibition system.
 java.util.Collection<DriveStrength> getBISDriveStrengths()
          Gets the drive strengths for the drives in the behavioral inhibition system.
 java.util.Collection<Drive> getBothDrives()
          Gets the drives that are in both the BAS and BIS.
 java.util.Collection<DriveStrength> getBothDriveStrengths()
          Gets the drive strengths for the drives that are in both the BAS and BIS.
 Drive getDrive(java.lang.Object ID)
          Gets the drive with the specified ID.
 DriveStrength getDriveStrength(java.lang.Object ID)
          Gets the drive strength for the drive with the specified ID.
 java.util.Collection<Drive> getNeitherDrives()
          Gets the drives that have been specified as being in neither behavioral system.
 java.util.Collection<DriveStrength> getNeitherDriveStrengths()
          Gets the drive strengths for the drives that have been specified as being in neither behavioral system.
 NeitherBehavioralSystem getNeitherSystem()
          Gets the system for drives that belong to neither behavioral system.
 int getNumDrives()
          Gets the number of drives in the MS.
 void initUserDefinedPersonality(java.util.Collection<Value> deficits)
          Initializes the MS with a user defined personality.
 
Methods inherited from class clarion.system.AbstractSubsystem
updateInputSpace
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

BAS

private BehavioralApproachSystem BAS
The behavioral approach system


BIS

private BehavioralInhibitionSystem BIS
The behavioral inhibition system


NEITHER

private NeitherBehavioralSystem NEITHER
The system for drives that belong to neither behavioral system


CurrentInput

private DimensionValueCollection CurrentInput
The current input (including current sensory information, current goal, chunks in working memory, and drive stimulus).

Constructor Detail

MS

public MS(CLARION Agent)
Minimally initializes the MS. This constructor builds a "frame" for this instance of the MS from which all desired components can be attached. During initialization this instance of the MS will attach itself to the CLARION agent you specify.

Parameters:
Agent - The agent to which the subsystem is being attached.

MS

public MS(CLARION Agent,
          Personality.PersonalityTypes Pers)
Initializes the MS with the personality specified. During initialization this instance of the MS will attach itself to the CLARION agent you specify.

Note that the drives that are created using this constructor will be setup to use the drive equation as their implicit module. If you wish to use a different implicit module for the drives, you must setup, train, and attach that module to each drive that was created separately.

Parameters:
Agent - The agent to which the subsystem is being attached.
Pers - The personality to set.
Method Detail

initUserDefinedPersonality

public void initUserDefinedPersonality(java.util.Collection<Value> deficits)
Initializes the MS with a user defined personality. This method takes a specified collection of deficits for the drives you wish to use and sets those deficits to the appropriate drives. The values representing the deficits must have one of the following IDs (in the form of a PrimaryDrives enumerated type located in the Personality class) that relates to the names of the primary drives used for creating a personality:
Any deficits in the specified collection containing an ID other those listed above will be ignored.

Note that the drives that are created using this constructor will be setup to use the drive equation as their implicit module. If you wish to use a different implicit module for the drives, you must setup, train, and attach that module to each drive that was created separately.


calculateDriveStrength

public DriveStrength calculateDriveStrength(java.lang.Object ID,
                                            DimensionValueCollection DriveInput)
Gets the drive strength for the drive with the specified ID. If none of the behavioral systems have a drive with the specified ID, this method returns null.

If you are using the drive equation, the specified drive input MUST have a dimension whose ID is equal to the specified ID and that dimension must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the from the DriveEquation class).

Parameters:
ID - The ID of the drive whose drive strength you want to get.
DriveInput - The current input for the MS.
Returns:
The strength of the drive with the specified ID.

calculateBASDriveStrengths

public DriveStrengthCollection calculateBASDriveStrengths(DimensionValueCollection DriveInput)
Gets the drive strengths for all drives in the behavioral approach system.

If you are using the drive equation, the dimensions within the specified drive input MUST have IDs equal to the IDs of drives you want to use and those dimensions must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the DriveEquation class).

If there are no drives that belong to the BAS, this method returns null.

Parameters:
DriveInput - The current input to the MS.
Returns:
The drive strengths for the drives in the BAS. The ID of the drive strengths are the same as the specified drives with which they are associated. Null if no drives belong to the BAS.

calculateBISDriveStrengths

public DriveStrengthCollection calculateBISDriveStrengths(DimensionValueCollection DriveInput)
Gets the drive strengths for all drives in the behavioral inhibition system.

If you are using the equation, the dimensions within the specified drive input MUST have IDs equal to the IDs of drives you want to use and those dimensions must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the DriveEquation class).

If there are no drives that belong to the BIS, this method returns null.

Parameters:
DriveInput - The current input to the MS.
Returns:
The drive strengths for the drives in the BIS. The ID of the drive strengths are the same as the specified drives with which they are associated. Null if no drives belong to the BIS.

calculateBothDriveStrengths

public DriveStrengthCollection calculateBothDriveStrengths(DimensionValueCollection DriveInput)
Gets the drive strengths for all drives that belong to both the BAS and BIS.

If you are using the equation, the dimensions within the specified drive input MUST have IDs equal to the IDs of drives you want to use and those dimensions must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the DriveEquation class).

Parameters:
DriveInput - The current input to the MS.
Returns:
The drive strengths for the drives that belong to both the BAS and BIS. The ID of the drive strengths are the same as the specified drives with which they are associated.

calculateNeitherDriveStrengths

public DriveStrengthCollection calculateNeitherDriveStrengths(DimensionValueCollection DriveInput)
Gets the drive strengths for all drives in the MS that do not belong to a behavioral system.

If you are using the equation, the dimensions within the specified drive input MUST have IDs equal to the IDs of drives you want to use and those dimensions must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the DriveEquation class).

If there are no drives that belong to neither behavioral system, this method returns null.

Parameters:
DriveInput - The current input to the MS.
Returns:
The drive strengths for the drives in neither behavioral system. The ID of the drive strengths are the same as the specified drives with which they are associated. Null if no drives belong to the neither behavioral system.

calculateAllDriveStrengths

public DriveStrengthCollection calculateAllDriveStrengths(DimensionValueCollection DriveInput)
Gets the drive strengths for ALL drives in the MS.

If you are using the equation, the dimensions within the specified drive input MUST have IDs equal to the IDs of drives you want to use and those dimensions must contain a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs located in the DriveEquation class).

If there are no drives in the MS, this method returns null.

Parameters:
DriveInput - The current input to the MS.
Returns:
The drive strengths for the drives in the MS. The ID of the drive strengths are the same as the specified drives with which they are associated. Null if there are no drives in the MS.

getNumDrives

public int getNumDrives()
Gets the number of drives in the MS.

Returns:
The number of drives.

getDrive

public Drive getDrive(java.lang.Object ID)
Gets the drive with the specified ID. If the MS does not contain a drive with the specified ID, this method returns null.

Parameters:
ID - The ID of the drive to get.
Returns:
The drive with the specified ID. Null if the MS does not contain a drive with the specified ID.

getAllDrives

public java.util.Collection<Drive> getAllDrives()
Gets the all the drives in the MS. The drives are returned in a new collection, so modifying the returned collection will not affect the structure of any of the behavioral systems.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If no drives exist in the MS, this method returns null.

Returns:
The drives in the MS. Null if the MS does not have any drives.

getBASDrives

public java.util.Collection<Drive> getBASDrives()
Gets the drives in the behavioral approach system. The drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of the BAS.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If the BAS is not being used, this method returns null.

Returns:
A collection of the drives in the behavioral approach system. Null if the system is not being used.

getBISDrives

public java.util.Collection<Drive> getBISDrives()
Gets the drives in the behavioral inhibition system. The drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of the BIS.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If the BIS is not being used, this method returns null.

Returns:
A collection of the drives in the behavioral inhibition system. Null if the system is not being used.

getBothDrives

public java.util.Collection<Drive> getBothDrives()
Gets the drives that are in both the BAS and BIS. The drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive systems.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If neither the BIS or BAS is being used, this method returns null. If only one of the systems is being used, this method will return just the items from that system.

Returns:
A collection of the drives in the BIS and/or BAS. Null if neither system is being used.

getNeitherDrives

public java.util.Collection<Drive> getNeitherDrives()
Gets the drives that have been specified as being in neither behavioral system. The drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of the neither behavioral system collection.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If no drives have been specified as belonging to neither behavioral system, this method returns null.

Returns:
A collection of the drives in neither behavioral system. Null if the system is not being used.

getDriveStrength

public DriveStrength getDriveStrength(java.lang.Object ID)
Gets the drive strength for the drive with the specified ID. If the MS does not contain a drive with the specified ID, this method returns null.

Parameters:
ID - The ID of the drive whose drive strength you wish to get.
Returns:
The drive strength for the drive with the specified ID. Null if the MS does not contain a drive with the specified ID.

getAllDriveStrengths

public java.util.Collection<DriveStrength> getAllDriveStrengths()
Gets all of the drive strength objects for the drives in the MS. The drive strengths for the drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive systems.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If no drives exist in the MS, this method returns null.

Returns:
The drive strengths for the drives in the MS. Null if the MS does not have any drives.

getBASDriveStrengths

public java.util.Collection<DriveStrength> getBASDriveStrengths()
Gets the drive strengths for the drives in the behavioral approach system. The drive strengths for the drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive system.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If the BAS is not being used, this method returns null.

Returns:
A collection of the drive strengths for the drives in the behavioral approach system. Null if the system is not being used.

getBISDriveStrengths

public java.util.Collection<DriveStrength> getBISDriveStrengths()
Gets the drive strengths for the drives in the behavioral inhibition system. The drive strengths for the drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive system.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If the BIS is not being used, this method returns null.

Returns:
A collection of the drive strengths for the drives in the behavioral inhibition system. Null if the system is not being used.

getBothDriveStrengths

public java.util.Collection<DriveStrength> getBothDriveStrengths()
Gets the drive strengths for the drives that are in both the BAS and BIS. The drive strengths for the drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive systems.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If neither the BIS or BAS is being used, this method returns null. If only one of the systems is being used, this method will return just the items from that system.

Returns:
A collection of the drive strengths for the drives in the BIS and/or BAS. Null if neither system is being used.

getNeitherDriveStrengths

public java.util.Collection<DriveStrength> getNeitherDriveStrengths()
Gets the drive strengths for the drives that have been specified as being in neither behavioral system. The drive strengths for the drives are returned in a new collection, therefore modifying the returned collection will not affect the structure of any of the drive system.

This method should NOT be used for obtaining drive strengths from the drives. If you wish to obtain the drive strengths, use one of the calculate methods.

If no drives have been specified as belonging to the neither behavioral system, this method returns null.

Returns:
A collection of the drive strengths for the drives in neither behavioral system. Null if the system is not being used.

addDriveToBAS

public void addDriveToBAS(Drive drive)
                   throws java.lang.IllegalArgumentException
Adds the specified drive to the behavior approach system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization. If the specified drive is already in the behavioral approach system, an exception is thrown.

Parameters:
drive - The drive to add to the BAS
Throws:
java.lang.IllegalArgumentException - If the specified drive is already in the MS.

addDrivesToBAS

public void addDrivesToBAS(java.util.Collection<Drive> drives)
Adds the specified drives to the behavior approach system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization.

Parameters:
drives - The drives to add to the BAS.

addDriveToBIS

public void addDriveToBIS(Drive drive)
                   throws java.lang.IllegalArgumentException
Adds the specified drive to the behavior inhibition system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization. If the specified drive is already in the MS, an exception is thrown.

Parameters:
drive - The drive to add to the BIS
Throws:
java.lang.IllegalArgumentException - If the specified drive is already in the MS.

addDrivesToBIS

public void addDrivesToBIS(java.util.Collection<Drive> drives)
Adds the specified drives to the behavior inhibition system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization.

Parameters:
drives - The drives to add to the BIS.

addDriveToBothSystems

public void addDriveToBothSystems(Drive drive)
                           throws java.lang.IllegalArgumentException
Adds the specified drive to both the BIS and the BAS. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization. If the specified drive is already in another system, an exception is thrown.

Parameters:
drive - The drive to add to the BIS and BAS.
Throws:
java.lang.IllegalArgumentException - If the specified drive is already in the MS.

addDrivesToBothSystems

public void addDrivesToBothSystems(java.util.Collection<Drive> drives)
Adds the specified drives to both the BIS and the BAS. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization.

Parameters:
drives - The drives to add to the BIS and BAS.

addDriveToNeither

public void addDriveToNeither(Drive drive)
                       throws java.lang.IllegalArgumentException
Adds the specified drive to the MS without specifying a behavioral system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization. If the specified drive is already in the MS an exception is thrown.

Parameters:
drive - The drive to add to the MS.
Throws:
java.lang.IllegalArgumentException - If the specified drive is already in the MS.

addDrivesToNeither

public void addDrivesToNeither(java.util.Collection<Drive> drives)
Adds the specified drives to the MS without specifying a behavioral system. Since drives are posited as being hard-wired for the most part, this method should only be used during initialization.

Parameters:
drives - The drives to add to the MS.

getBAS

public BehavioralApproachSystem getBAS()
Gets the BAS. This method returns the ACTUAL behavioral approach system and therefore should be accessed and used with caution.

This method should ONLY be used for initialization and reporting purposes.

Returns:
The BAS.

getBIS

public BehavioralInhibitionSystem getBIS()
Gets the BIS. This method returns the ACTUAL behavioral inhibition system and therefore should be accessed and used with caution.

This method should ONLY be used for initialization and reporting purposes.

Returns:
The BIS.

getNeitherSystem

public NeitherBehavioralSystem getNeitherSystem()
Gets the system for drives that belong to neither behavioral system. This method returns the ACTUAL system and therefore should be accessed and used with caution.

This method should ONLY be used for initialization and reporting purposes.

Returns:
The "neither" behavioral system.

attachSelfToAgent

protected void attachSelfToAgent(CLARION Agent)
Attaches the MS to the specified CLARION agent.

Specified by:
attachSelfToAgent in class AbstractSubsystem
Parameters:
Agent - The agent to wish this MS will be attached.

endEpisode

protected void endEpisode()
Performs the appropriate end of episode instructions for the MS. This method is called by the CLARION class when its endEpisode method is called.

Specified by:
endEpisode in class AbstractSubsystem