clarion.system
Class AbstractRule

java.lang.Object
  extended by clarion.system.AbstractExplicitModule
      extended by clarion.system.AbstractRule
All Implemented Interfaces:
InterfaceHandlesFeedback, InterfaceHandlesFeedbackWithTime, InterfaceTracksMatchStatistics, InterfaceTracksTime
Direct Known Subclasses:
AbstractFixedRule, RefineableRule

public abstract class AbstractRule
extends AbstractExplicitModule
implements InterfaceTracksMatchStatistics, InterfaceHandlesFeedbackWithTime, InterfaceTracksTime

This class implements an abstract rule within CLARION. It extends the AbstractExplicitModule class and implements the InterfaceTracksMatchStatistics, InterfaceHandlesFeedbackWithTime, and InterfaceTracksTime interfaces. This class is abstract and therefore cannot be instantiated on its own.

Usage:

The abstract rule is the base class for rules within the ACS. All rule types within the rule collection in the ACS extend from this class.

Known Subclasses:

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

Nested Class Summary
static class AbstractRule.SelectionTypes
          The various types of measures that can be selected over when performing action decision making.
static class AbstractRule.UtilityOptions
          The options for calculating the utility of a rule.
 
Field Summary
 double BENEFIT_CONSTANT
          The constant to use for benefit when using the constant option for utility.
 double C7
          Benefit equation constant c7.
 double C8
          Benefit equation constant c8.
protected  java.util.HashMap<java.lang.Integer,AbstractRule> Children
          The child rules (if any) of this rule.
 double COST_CONSTANT
          The constant to use for benefit when using the constant option for utility.
protected  DimensionValueCollection CurrentInput
          The current input.
static double DEAFUALT_PARTIAL_MATCH_ON
          The default partial match threshold if partial match is turned on.
static double DEFAULT_PARTIAL_MATCH_OFF
          The default partial match threshold if partial match is turned off.
 double DENSITY
          The density (the minimum frequency needed to be kept)
private  double Feedback
          The immediate feedback (if given).
static double GLOBAL_BENEFIT_CONSTANT
          The constant to use for benefit when using the constant option for utility.
static double GLOBAL_C7
          Benefit equation constant c7.
static double GLOBAL_C8
          Benefit equation constant c8.
static double GLOBAL_COST_CONSTANT
          The constant to use for cost when using the constant option for utility.
static double GLOBAL_DENSITY
          The density (the minimum frequency needed to be kept)
static double GLOBAL_PARTIAL_MATCH_THRESHOLD
          The threshold the support must pass for the condition to be matched.
static double GLOBAL_POSITIVE_MATCH_THRESHOLD
          The threshold that must be passed to meet the positive match criterion.
static AbstractRule.SelectionTypes GLOBAL_SELECTION_TYPE
          The selection type to use for the selection measure of the rule.
static double GLOBAL_SUPPORT_EPSILON
          How close a condition's support must be to the current input in order for it to be considered as matching the current input.
static AbstractRule.UtilityOptions GLOBAL_UTILITY_OPTION
          Specifies the method to use for calculating utility.
static double GLOBAL_V
          The cost scaling factor.
protected  long LastMatch
          The time-stamp associated with the last time the rule matched the input.
protected  double NM
          The negative match counter.
 double PARTIAL_MATCH_THRESHOLD
          The threshold the support must pass for the condition to be matched.
protected  double PM
          The positive match counter.
 double POSITIVE_MATCH_THRESHOLD
          The threshold that must be passed to meet the positive match criterion.
protected  AbstractAction rAction
          The action chunk of the rule.
protected  GeneralizedConditionChunk rCondition
          The condition chunk of the rule.
 AbstractRule.SelectionTypes SELECTION_TYPE
          The selection type to use for the selection measure of the rule.
 double SUPPORT_EPSILON
          How close a condition's support must be to the current input in order for it to be considered as matching the current input.
 AbstractRule.UtilityOptions UTILITY_OPTION
          Specifies the method to use for calculating utility.
 double V
          The cost scaling factor.
 
Fields inherited from class clarion.system.AbstractExplicitModule
ACTUATION_TIME, C, D, DECISION_TIME, GLOBAL_ACTUATION_TIME, GLOBAL_C, GLOBAL_D, GLOBAL_DECISION_TIME, GLOBAL_INITIAL_BLA, GLOBAL_PERCEPTION_TIME, GLOBAL_WEIGHT, INITIAL_BLA, PERCEPTION_TIME, WEIGHT
 
Constructor Summary
AbstractRule(GeneralizedConditionChunk cond, AbstractAction act)
          Initializes a rule with the condition and action chunks specified.
 
Method Summary
 boolean checkMatchCriterion()
          Checks if the condition is matched given the new input.
 boolean checkMatchCriterion(long TimeStamp)
          Checks if the condition is matched given the new input.
abstract  AbstractRule clone()
          Copies the rule.
 boolean covers(AbstractRule r)
          Checks to see if the condition of the specified rule is covered by this rule and that the two rules have the same action.
 boolean covers(GeneralizedConditionChunk cond, AbstractAction act)
          Checks to see if the specified condition is covered by this rule and that the specified action is the same as this rule's action.
 boolean equals(GeneralizedConditionChunk cond, AbstractAction act)
          Checks to see if the specified condition and action are equal to the condition and action of this rule.
 boolean equals(java.lang.Object R)
          Checks to see if the specified object is a rule and checks to see if the condition and action of that rule are equal to this rule.
 AbstractAction getAction()
          Gets the action of the rule.
 java.util.Collection<AbstractRule> getChildren()
          Gets a collection of the children of this rule.
 GeneralizedConditionChunk getCondition()
          Gets the condition of the rule.
 double getFeedback()
          Gets the immediate feedback that was last provided to the rule.
 double getNM()
          Gets the negative match statistic.
 int getNumChildren()
          Gets the number of child rules in top level of the child rule tree.
 double getPM()
          Gets the positive match statistic.
 double getSupport(DimensionValueCollection CurrentInput)
          Gets the support based on the current input.
 double getUtility()
          Gets the utility.
 double getUtility(double AverageRT)
          Gets the utility using the equation option and the specified average response time.
 void incrementNM()
          Increments the negative match statistic.
 void incrementPM()
          Increments the positive match statistic.
 void initChildren()
          Initializes the child rules collection.
 void resetChildren()
          Resets the child collection.
 void resetMatchStatistics()
          Resets the match statistics.
 void setCurrentInput(DimensionValueCollection input)
          Sets the current input to the specified input.
 void setFeedback(double feedback)
          Sets the immediate feedback for the rule.
 void setNM(double nm)
          Sets the negative match statistic.
 void setPM(double pm)
          Sets the positive match statistic.
 java.lang.String toString()
           
static void turnPartialMatchON()
          Sets the partial match threshold to the default value when partial match is turned on.
 void updateMatchStatistics(AbstractMatchCalculator MatchCalculator)
          Updates the positive or negative match statistics based on the feedback.
 
Methods inherited from class clarion.system.AbstractExplicitModule
addTimeStamp, getBLA, getResponseTime
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface clarion.system.InterfaceTracksTime
addTimeStamp, getBLA
 

Field Detail

rCondition

protected GeneralizedConditionChunk rCondition
The condition chunk of the rule.


rAction

protected AbstractAction rAction
The action chunk of the rule.


Children

protected java.util.HashMap<java.lang.Integer,AbstractRule> Children
The child rules (if any) of this rule.


CurrentInput

protected DimensionValueCollection CurrentInput
The current input.


DEFAULT_PARTIAL_MATCH_OFF

public static double DEFAULT_PARTIAL_MATCH_OFF
The default partial match threshold if partial match is turned off.


DEAFUALT_PARTIAL_MATCH_ON

public static double DEAFUALT_PARTIAL_MATCH_ON
The default partial match threshold if partial match is turned on.


GLOBAL_PARTIAL_MATCH_THRESHOLD

public static double GLOBAL_PARTIAL_MATCH_THRESHOLD
The threshold the support must pass for the condition to be matched.


PARTIAL_MATCH_THRESHOLD

public double PARTIAL_MATCH_THRESHOLD
The threshold the support must pass for the condition to be matched.


GLOBAL_SUPPORT_EPSILON

public static double GLOBAL_SUPPORT_EPSILON
How close a condition's support must be to the current input in order for it to be considered as matching the current input. Needed due to the nature of double precision arithmetic.


SUPPORT_EPSILON

public double SUPPORT_EPSILON
How close a condition's support must be to the current input in order for it to be considered as matching the current input. Needed due to the nature of double precision arithmetic.


GLOBAL_DENSITY

public static double GLOBAL_DENSITY
The density (the minimum frequency needed to be kept)


DENSITY

public double DENSITY
The density (the minimum frequency needed to be kept)


GLOBAL_UTILITY_OPTION

public static AbstractRule.UtilityOptions GLOBAL_UTILITY_OPTION
Specifies the method to use for calculating utility. The default is to use constants


UTILITY_OPTION

public AbstractRule.UtilityOptions UTILITY_OPTION
Specifies the method to use for calculating utility. The default is to use constants


GLOBAL_BENEFIT_CONSTANT

public static double GLOBAL_BENEFIT_CONSTANT
The constant to use for benefit when using the constant option for utility.


BENEFIT_CONSTANT

public double BENEFIT_CONSTANT
The constant to use for benefit when using the constant option for utility.


GLOBAL_COST_CONSTANT

public static double GLOBAL_COST_CONSTANT
The constant to use for cost when using the constant option for utility.


COST_CONSTANT

public double COST_CONSTANT
The constant to use for benefit when using the constant option for utility.


GLOBAL_V

public static double GLOBAL_V
The cost scaling factor. Used to calculate utility


V

public double V
The cost scaling factor. Used to calculate utility


GLOBAL_C7

public static double GLOBAL_C7
Benefit equation constant c7.


GLOBAL_C8

public static double GLOBAL_C8
Benefit equation constant c8.


C7

public double C7
Benefit equation constant c7.


C8

public double C8
Benefit equation constant c8.


PM

protected double PM
The positive match counter.


NM

protected double NM
The negative match counter.


GLOBAL_POSITIVE_MATCH_THRESHOLD

public static double GLOBAL_POSITIVE_MATCH_THRESHOLD
The threshold that must be passed to meet the positive match criterion.


POSITIVE_MATCH_THRESHOLD

public double POSITIVE_MATCH_THRESHOLD
The threshold that must be passed to meet the positive match criterion.


Feedback

private double Feedback
The immediate feedback (if given).


GLOBAL_SELECTION_TYPE

public static AbstractRule.SelectionTypes GLOBAL_SELECTION_TYPE
The selection type to use for the selection measure of the rule.


SELECTION_TYPE

public AbstractRule.SelectionTypes SELECTION_TYPE
The selection type to use for the selection measure of the rule.


LastMatch

protected long LastMatch
The time-stamp associated with the last time the rule matched the input.

Constructor Detail

AbstractRule

public AbstractRule(GeneralizedConditionChunk cond,
                    AbstractAction act)
             throws java.lang.IllegalArgumentException
Initializes a rule with the condition and action chunks specified.

Parameters:
cond - The condition for the new rule.
act - The action for the new rule.
Throws:
java.lang.IllegalArgumentException - If the condition or action are null.
Method Detail

getUtility

public double getUtility()
Gets the utility. If you are using the equation option for calculating the utility, this method assumes that the cost is equal to the response time.

Specified by:
getUtility in class AbstractExplicitModule
Returns:
The utility.

getUtility

public double getUtility(double AverageRT)
Gets the utility using the equation option and the specified average response time.

Parameters:
AverageRT - The average response time used for calculating the cost.
Returns:
The utility.

getSupport

public double getSupport(DimensionValueCollection CurrentInput)
Gets the support based on the current input.

Specified by:
getSupport in class AbstractExplicitModule
Parameters:
CurrentInput - The current input represented as a dimension-value collection.
Returns:
The support for this rule.

getCondition

public GeneralizedConditionChunk getCondition()
Gets the condition of the rule.

Returns:
The condition.

getAction

public AbstractAction getAction()
Gets the action of the rule.

Returns:
The action.

setCurrentInput

public void setCurrentInput(DimensionValueCollection input)
Sets the current input to the specified input. This method should be called before the getSupport method is called.

Parameters:
input - The input to set as the current input.

checkMatchCriterion

public boolean checkMatchCriterion(long TimeStamp)
Checks if the condition is matched given the new input.

Specified by:
checkMatchCriterion in interface InterfaceHandlesFeedbackWithTime
Parameters:
TimeStamp - The current time stamp.
Returns:
True if the condition is matched, otherwise false.

checkMatchCriterion

public boolean checkMatchCriterion()
Checks if the condition is matched given the new input.

Specified by:
checkMatchCriterion in interface InterfaceHandlesFeedback
Returns:
True if the condition is matched, otherwise false.

covers

public boolean covers(AbstractRule r)
Checks to see if the condition of the specified rule is covered by this rule and that the two rules have the same action.

Parameters:
r - The rule to check against this rule.
Returns:
True if this rule covers the specified rule, otherwise false.

covers

public boolean covers(GeneralizedConditionChunk cond,
                      AbstractAction act)
Checks to see if the specified condition is covered by this rule and that the specified action is the same as this rule's action.

Parameters:
cond - The condition to check against the condition of this rule.
act - The action to check.
Returns:
True if the condition of this rule covers the specified condition, otherwise false.

equals

public boolean equals(java.lang.Object R)
Checks to see if the specified object is a rule and checks to see if the condition and action of that rule are equal to this rule.

Specified by:
equals in class AbstractExplicitModule
Parameters:
R - The object to compare to this rule
Returns:
True if the object is equal to this rule, otherwise false.

equals

public boolean equals(GeneralizedConditionChunk cond,
                      AbstractAction act)
Checks to see if the specified condition and action are equal to the condition and action of this rule.

Parameters:
cond - The condition to check.
act - The action to check.
Returns:
True if the condition and action are equal to the specified condition and action, otherwise false.

getPM

public double getPM()
Gets the positive match statistic.

Specified by:
getPM in interface InterfaceTracksMatchStatistics
Returns:
The positive match statistic.

getNM

public double getNM()
Gets the negative match statistic.

Specified by:
getNM in interface InterfaceTracksMatchStatistics
Returns:
The negative match statistic.

setPM

public void setPM(double pm)
Sets the positive match statistic. This method can be used to update the positive match statistic if the user wishes to provide their own match criterion function.

Specified by:
setPM in interface InterfaceTracksMatchStatistics
Parameters:
pm - The value to set as the positive match statistic.

setNM

public void setNM(double nm)
Sets the negative match statistic. This method can be used to update the negative match statistic if the user wishes to provide their own match criterion function.

Specified by:
setNM in interface InterfaceTracksMatchStatistics
Parameters:
nm - The value to set as the negative match statistic.

getFeedback

public double getFeedback()
Gets the immediate feedback that was last provided to the rule. This method is only used if feedback is being provided.

Specified by:
getFeedback in interface InterfaceHandlesFeedback
Returns:
The feedback.

setFeedback

public void setFeedback(double feedback)
Sets the immediate feedback for the rule. This method should be called before the updateMatchStatistics method is called. This method is only used if feedback is being provided.

Specified by:
setFeedback in interface InterfaceHandlesFeedback
Parameters:
feedback - The value of the feedback.

updateMatchStatistics

public void updateMatchStatistics(AbstractMatchCalculator MatchCalculator)
Updates the positive or negative match statistics based on the feedback.

This update is usually performed after the feedback has been set.

Specified by:
updateMatchStatistics in interface InterfaceTracksMatchStatistics
Parameters:
MatchCalculator - The match calculator to use to determine positivity.

resetMatchStatistics

public void resetMatchStatistics()
Resets the match statistics.

Specified by:
resetMatchStatistics in interface InterfaceTracksMatchStatistics

incrementPM

public void incrementPM()
Increments the positive match statistic. This method can be used to update the positive match statistic if the user wishes to provide their own match criterion function.

Specified by:
incrementPM in interface InterfaceTracksMatchStatistics

incrementNM

public void incrementNM()
Increments the negative match statistic. This method can be used to update the negative match statistic if the user wishes to provide their own match criterion function.

Specified by:
incrementNM in interface InterfaceTracksMatchStatistics

turnPartialMatchON

public static void turnPartialMatchON()
Sets the partial match threshold to the default value when partial match is turned on. By default partial match is turned off. This method must be called before any instances of a rule are initialized.


getNumChildren

public int getNumChildren()
Gets the number of child rules in top level of the child rule tree.

Returns:
The number of child rules.

getChildren

public java.util.Collection<AbstractRule> getChildren()
Gets a collection of the children of this rule.

Returns:
A collection the children of this rule.

initChildren

public void initChildren()
Initializes the child rules collection.


resetChildren

public void resetChildren()
Resets the child collection.


clone

public abstract AbstractRule clone()
Copies the rule.

Overrides:
clone in class java.lang.Object
Returns:
A copy of the rule.

toString

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