clarion.system
Class Drive

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

public class Drive
extends java.lang.Object

This class implements a drive within CLARION.

Usage:

This class represents a drives, which exist at the bottom-level of the MS within the behavioral approach and/or behavioral inhibition systems (or a special "neither" behavioral system).

The drive class uses an implicit module in order to obtain a drive strength. The implicit module can be user defined, however if it is not, then the drive will use the DriveEquation as its default.

If you are using the drive equation, the drive input MUST contain a dimension with an ID equal to the ID of this drive that contains a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs) and a value with the ID: SYSTEM_GAIN (of enumerated type RequiredEquationInputs).

All other dimensions and values in the drive input will be ignored if you are using the equation.

Note that if the drive belongs to both the BIS and BAS, the SYSTEM_GAIN should be set to the average of the gains of the two drives.

The formula for the drive equation is as follows:
DriveStrength = (DRIVE_GAIN * SYSTEM_GAIN * UNIVERAL_GAIN) * Deficit * Stimulus + Baseline

If a neural network is used as the implicit module for the drive, it should be pre-trained before it is used as drives are not (generally) runtime trainable (although the you can certainly use a runtime trainable implicit module if you provide your own method for training it during runtime).

Note that if a user defined implicit module is used, it MUST have an output chunk on the output layer that has an ID that is equal to the ID of the drive for which it is being used and that output chunk MUST be of type DriveStrength. If no such output chunk exists, the drive will fail to initialize.

If the implicit module contains more than one output chunk in the output layer, all other output chunks besides the drive strength chunk for this drive will be ignored.

However, it should also be noted, that a user COULD setup a single implicit module that has ALL of the drives linked to a drive strength on the output layer of that single implicit module and then use that implicit module to obtain drive strengths for ALL of the drives in the MS. Using a single implicit module COULD reduce the amount of time it takes to pre-train the drives in the MS.

If you are using a user defined implicit module and if that module is not using any of the parameters specified in the drive equation they will just be ignored.

This class contains both global (static) and local constants. The default is to use the local constants. If you want to change any of the global constants, you need to do so before any instances of this class are initialized.

Version:
6.0.4
Author:
Nick Wilson

Field Summary
 double BASELINE
          The baseline for this particular drive
private  Value Deficit
          The drive deficit represented as a value object.
private  double DEFICIT_CHANGE_RATE
          The rate of change for the deficit.
private  AbstractImplicitModule DriveMod
          The implicit module that is used to get drive strengths.
protected  DriveStrength DS
          The drive strength associated with this drive.
 double GAIN
          The gain for the particular drive
static double GLOBAL_BASELINE
          The baseline for this particular drive
static double GLOBAL_DEFICIT_CHANGE_RATE
          The rate of change for the deficit.
static double GLOBAL_GAIN
          The gain for the particular drive
static double GLOBAL_UNIVERSAL_GAIN
          The universal gain for all drives
private  int hash
          The hash for this object.
private  java.lang.Object ID
          Identifies the drive.
private  Value InitialDeficit
          The initial (pre-decay) drive deficit.
 double UNIVERSAL_GAIN
          The universal gain for all drives
 
Constructor Summary
Drive(java.lang.Object id, double deficit)
          Initializes the drive to use the drive equation for reporting drive strengths.
Drive(java.lang.Object id, double deficit, AbstractImplicitModule im)
          Initializes the drive to use the specified implicit module for reporting drive strengths.
 
Method Summary
 DriveStrength calculateDriveStrength(DimensionValueCollection DriveInput)
          Calculates the drive strength given the specified drive input.
 Drive clone()
          Clones the drive.
 boolean equals(java.lang.Object drive)
          Checks to see if the specified object is a drive and has the same ID as the specified drive.
 double getDeficit()
          Gets the deficit level.
 DriveStrength getDriveStrength()
          Gets the drive strength object associated with this drive.
 java.lang.Object getID()
          Gets the ID of this drive.
 AbstractImplicitModule getImplicitModule()
          Gets the implicit module for this drive.
 double getInitialDeficit()
          Gets the level of the initial deficit.
 int hashCode()
           
 void setDeficit(double deficit)
          Sets the deficit.
 void setDeficitChangeRate(double changeRate)
          Sets the deficit change rate.
 void setImplicitModule(AbstractImplicitModule im)
          Sets the implicit module for this drive.
 java.lang.String toString()
           
protected  void updateDeficit()
          Updates the deficit using the rate of change.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ID

private java.lang.Object ID
Identifies the drive. A name (in the form of a string) is simply one option for identifying a drive.


hash

private int hash
The hash for this object. When this item is cloned, so is this hash.


DriveMod

private AbstractImplicitModule DriveMod
The implicit module that is used to get drive strengths.


DS

protected DriveStrength DS
The drive strength associated with this drive.


GLOBAL_UNIVERSAL_GAIN

public static double GLOBAL_UNIVERSAL_GAIN
The universal gain for all drives


GLOBAL_DEFICIT_CHANGE_RATE

public static double GLOBAL_DEFICIT_CHANGE_RATE
The rate of change for the deficit.


UNIVERSAL_GAIN

public double UNIVERSAL_GAIN
The universal gain for all drives


DEFICIT_CHANGE_RATE

private double DEFICIT_CHANGE_RATE
The rate of change for the deficit.


Deficit

private Value Deficit
The drive deficit represented as a value object.


InitialDeficit

private Value InitialDeficit
The initial (pre-decay) drive deficit. This is used to calculate the baseline when a deficit portion is being used.


GLOBAL_GAIN

public static double GLOBAL_GAIN
The gain for the particular drive


GLOBAL_BASELINE

public static double GLOBAL_BASELINE
The baseline for this particular drive


GAIN

public double GAIN
The gain for the particular drive


BASELINE

public double BASELINE
The baseline for this particular drive

Constructor Detail

Drive

public Drive(java.lang.Object id,
             double deficit)
Initializes the drive to use the drive equation for reporting drive strengths. This is the default option if an implicit module is not specified. This constructor also initializes the deficit to the specified deficit and sets the ID to the specified ID. Once the drive has been initialized, the initial deficit cannot be changed.

Parameters:
id - The ID to set for this drive.
deficit - The initial drive deficit.

Drive

public Drive(java.lang.Object id,
             double deficit,
             AbstractImplicitModule im)
      throws InvalidFormatException
Initializes the drive to use the specified implicit module for reporting drive strengths. Also initializes the deficit to the specified deficit and sets the ID to the specified ID. Once the drive has been initialized, the initial deficit cannot be changed.

Note that the specified implicit module MUST have an output chunk on the output layer that has an ID that is equal to the ID of this drive instance and that output chunk MUST be of type DriveStrength. If no such output chunk exists, the drive will fail to initialize.

If the implicit module contains more than one output chunk in the output layer, all other output chunks besides the drive strength chunk for this drive will be ignored.

However, it should be noted, that a user COULD setup a single implicit module that has ALL of the drives linked to a drive strength on the output layer of that single implicit module and then use that implicit module to obtain drive strengths for ALL of the drives in the MS. Using a single implicit module COULD reduce the amount of time it takes to pre-train the drives in the MS.

Parameters:
id - The ID to set for this drive.
deficit - The initial drive deficit.
im - The implicit module to use for this drive.
Throws:
InvalidFormatException - If the specified implicit module does not contain an output chunk with an ID equal to the ID of this drive or the output chunk has the correct ID but is not of type DriveStrength.
Method Detail

calculateDriveStrength

public DriveStrength calculateDriveStrength(DimensionValueCollection DriveInput)
                                     throws InvalidFormatException
Calculates the drive strength given the specified drive input. In this method, the drive specific parameters are added to the drive input before setting it as the input for drive's implicit module.

If you are using a user defined implicit module and if that module is not using any of the parameters specified in the drive equation they will just be ignored.

If you are using the drive equation, the drive input MUST contain a dimension with an ID equal to the ID of this drive that contains a value with the ID: STIMULUS (of enumerated type RequiredEquationInputs) and a value with the ID: SYSTEM_GAIN (of enumerated type RequiredEquationInputs).

All other dimensions and values in the drive input will be ignored if you are using the equation.

If the drive input does not contain the aforementioned dimension and value and you are using the equation, this method will throw an exception.

Note that if your drive belongs to both the BIS and BAS, the SYSTEM_GAIN should be set to the average of the gains of the two drives.

Parameters:
DriveInput - The input for the drive.
Returns:
The strength of the drive.
Throws:
InvalidFormatException - If the drive is using the equation and the drive input does not contain a dimension with an ID equal to the ID of this drive and a value within that dimension that has the ID: STIMULUS (of enumerated type RequiredEquationInputs) and a value with the ID: SYSTEM_GAIN (of enumerated type RequiredEquationInputs).

getID

public java.lang.Object getID()
Gets the ID of this drive.

Returns:
The ID of this drive.

getImplicitModule

public AbstractImplicitModule getImplicitModule()
Gets the implicit module for this drive. This method is primarily meant for internal purposes. It should NOT be used outside of the CLARION Library for purposes other than reporting the internal state.

Returns:
The implicit module for this drive.

setImplicitModule

public void setImplicitModule(AbstractImplicitModule im)
                       throws InvalidFormatException
Sets the implicit module for this drive. This method should only be used during initialization.

Parameters:
im - The implicit module to set for this drive.
Throws:
InvalidFormatException - If the specified implicit module does not contain an output chunk with an ID equal to the ID of this drive or the output chunk has the correct ID but is not of type DriveStrength.

getDriveStrength

public DriveStrength getDriveStrength()
Gets the drive strength object associated with this drive. This method is mainly used during initialization and does NOT calculate the drive strength for this drive. If you want to calculate the drive strength, call the calculateDriveStrength method.

Returns:
The drive strength object

getDeficit

public double getDeficit()
Gets the deficit level.

Returns:
The deficit.

getInitialDeficit

public double getInitialDeficit()
Gets the level of the initial deficit. Once the drive has been initialized, the initial deficit cannot be changed.

Returns:
The initial deficit.

setDeficit

public void setDeficit(double deficit)
Sets the deficit. The initial deficit is left unchanged.

Parameters:
deficit - The deficit value to set.

setDeficitChangeRate

public void setDeficitChangeRate(double changeRate)
Sets the deficit change rate.

Parameters:
changeRate - The rate of change to set.

updateDeficit

protected void updateDeficit()
Updates the deficit using the rate of change.


equals

public boolean equals(java.lang.Object drive)
Checks to see if the specified object is a drive and has the same ID as the specified drive.

Overrides:
equals in class java.lang.Object
Parameters:
drive - The object to compare to this drive.
Returns:
True if the two drives are have the same ID, otherwise false.

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

clone

public Drive clone()
Clones the drive. This method should NOT be used outside of the CLARION library as it does NOT clone the implicit module and each instance of a drive should have its own implicit module (at least between different instances of a CLARION agent).

Overrides:
clone in class java.lang.Object
Returns:
A copy of this drive.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object