clarion.tools
Class TrainableImplicitModulePreTrainer

java.lang.Object
  extended by clarion.tools.TrainableImplicitModulePreTrainer

public class TrainableImplicitModulePreTrainer
extends java.lang.Object

This class implements a pre-trainer that can be used on trainable implicit modules in CLARION.

Usage:

The pre-trainer is a tool for training implicit modules that are trainable (i.e. they extend from AbstractTrainableImplicitModule). Any class which extends the AbstractTriainableImplicitModule class can be trained by this pre-trainer.

This class is called a PRE-trainer because it is intended to be used "offline" BEFORE the start of a task (i.e. during initialization).

If the implicit module you wish to train is a "runtime trainable" implicit module (i.e. it extends from AbstractRuntimeTrainableImplicitModule), it will be trained in an "online" fashion. That is, at each time step, the "runtime trainable" implicit module you are training will stochastically choose an output, receive feedback, and learn based on the feedback.

Below are the things that need to be provided in order to use this pre-trainer:

  1. A target AbstractTrainableImplicitModule
    • The module you intend to train.
  2. An AbstractImplicitModule to act as a trainer.
    • Can be ANY implicit module.
      Examples:
      • An equation (such as the drive equation, goal equation, etc.).
      • A table lookup (for learning the values in a table).
        • Ideal for training with a training set.
      • Another, already trained, trainable implicit module.
        • Target module is trained to imitate the trainer module.
    • Note: The inputs and outputs of the trainer should be in the same format as the target.
  3. A data set, specified as a collection of dimension-value collections.
    • Examples of possible data sets:
      • Training sets
        • A collection of dimension-value collections where each dimension-value collection is a different configuration of the inputs of the target and training modules. In other words, each dimension-value collection is a different "state."
      • Ranges
        • A collection of dimension-value collections where the Values inside the Dimensions are of type "Range" and have the same ID as the Values of the inputs of the target module.
        • If a "Range" is specified for a Value within a Dimension for one of these dimension-value collections, the associated Value in the input layer of the target module will be trained to handle all of the activations between the lower-bound and the upper-bound at a precision determined by the increment parameter specified by that range.
      • A combination of ranges and training sets
        • Where some dimension-value collections are training sets and others are ranges.
        • Where each dimension-value collection has a combination of Values and Ranges. (i.e. each "state" has some Values that are Ranges and others that are simply Values).
    • Note: The data set just specifies the inputs to use during training. It is the "trainer" module's job to provide the desired output for the target.
    • Also, if you wish to use only one data set (i.e. a single dimension-value collection) for training, then simply create a collection of dimension-value collections that contains only 1 dimension-value collection.
      • This is most often the case when you want to train ALL of the input nodes using ranges.

There are three possible termination conditions for training (as determined by the TERMINATION_CONDITION constant):

  1. Can train for a fixed number of trials (a trial is 1 time through the data set).
    • As determined by the NUM_TRAINING_REPEATS constant (5000 by default)
    • This is the default option.
  2. Can train until the sum of squared errors reaches a certain threshold.
    • As determined by the SUM_SQ_ERRORS_THRESHOLD constant (.001 by default)
  3. A combination of a fixed number of trials AND sum of squared errors.
    • This option will train until the sum of squared errors reaches the threshold OR the fixed number of trials is reached (whichever comes first)

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.5
Author:
Nick Wilson

Nested Class Summary
private  class TrainableImplicitModulePreTrainer.SumSquaredErrorTracker
          This class implements a sum of squared error tracker.
static class TrainableImplicitModulePreTrainer.TerminationConditions
          The termination condition options
 
Field Summary
static int GLOBAL_NUM_TRAINING_REPEATS
          The number of times to run through the training set before ending training.
static boolean GLOBAL_PRINT_PROGRESS_TO_SYSTEM_OUT
          Option for printing out the progress of training (false by default)
static double GLOBAL_SUM_SQ_ERRORS_THRESHOLD
          The threshold the sum of squared errors must meet before training can end.
static TrainableImplicitModulePreTrainer.TerminationConditions GLOBAL_TERMINATION_CONDITION
          The method of determining the termination condition(s) when training BPNets.
 int NUM_TRAINING_REPEATS
          The number of times to run through the training set before ending training.
 boolean PRINT_PROGRESS_TO_SYSTEM_OUT
          Option for printing out the progress of training (false by default)
 StochasticSelector SELECTOR
          The stochastic selector to use if the target module to be trained is runtime trainable.
 double SUM_SQ_ERRORS_THRESHOLD
          The threshold the sum of squared errors must meet before training can end.
 TrainableImplicitModulePreTrainer.TerminationConditions TERMINATION_CONDITION
          The method of determining the termination condition(s) when training BPNets.
 
Constructor Summary
TrainableImplicitModulePreTrainer()
           
 
Method Summary
private  void dataRecursor(AbstractTrainableImplicitModule target, AbstractImplicitModule trainer, java.util.ListIterator<Dimension> dim, java.util.ListIterator<? extends Value> val, TrainableImplicitModulePreTrainer.SumSquaredErrorTracker sqe)
          Recursive method that iterates over the dimensions of a dimension-value collection (from the data set and trains the specified target implicit module based on the outputs from the specified trainer implicit module.
private  void innerLoop(AbstractTrainableImplicitModule target, AbstractImplicitModule trainer, java.util.ListIterator<Dimension> dim, java.util.ListIterator<? extends Value> val, Dimension d, Value v, TrainableImplicitModulePreTrainer.SumSquaredErrorTracker sqe)
          The inner loop of the dataRecursor method.
 void trainModule(AbstractTrainableImplicitModule target, AbstractImplicitModule trainer, java.util.Collection<? extends DimensionValueCollection> data)
          Trains the specified target implicit module using the specified training implicit module over the specified data set.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GLOBAL_NUM_TRAINING_REPEATS

public static int GLOBAL_NUM_TRAINING_REPEATS
The number of times to run through the training set before ending training.


GLOBAL_SUM_SQ_ERRORS_THRESHOLD

public static double GLOBAL_SUM_SQ_ERRORS_THRESHOLD
The threshold the sum of squared errors must meet before training can end.


GLOBAL_TERMINATION_CONDITION

public static TrainableImplicitModulePreTrainer.TerminationConditions GLOBAL_TERMINATION_CONDITION
The method of determining the termination condition(s) when training BPNets.


NUM_TRAINING_REPEATS

public int NUM_TRAINING_REPEATS
The number of times to run through the training set before ending training.


SUM_SQ_ERRORS_THRESHOLD

public double SUM_SQ_ERRORS_THRESHOLD
The threshold the sum of squared errors must meet before training can end.


TERMINATION_CONDITION

public TrainableImplicitModulePreTrainer.TerminationConditions TERMINATION_CONDITION
The method of determining the termination condition(s) when training BPNets.


GLOBAL_PRINT_PROGRESS_TO_SYSTEM_OUT

public static boolean GLOBAL_PRINT_PROGRESS_TO_SYSTEM_OUT
Option for printing out the progress of training (false by default)


PRINT_PROGRESS_TO_SYSTEM_OUT

public boolean PRINT_PROGRESS_TO_SYSTEM_OUT
Option for printing out the progress of training (false by default)


SELECTOR

public StochasticSelector SELECTOR
The stochastic selector to use if the target module to be trained is runtime trainable.

Constructor Detail

TrainableImplicitModulePreTrainer

public TrainableImplicitModulePreTrainer()
Method Detail

trainModule

public void trainModule(AbstractTrainableImplicitModule target,
                        AbstractImplicitModule trainer,
                        java.util.Collection<? extends DimensionValueCollection> data)
Trains the specified target implicit module using the specified training implicit module over the specified data set.

Parameters:
target - The target implicit module to train.
trainer - The implicit module to use as the trainer.
  • Can be ANY implicit module.
    Examples:
    • An equation (such as the drive equation, goal equation, etc.).
    • A table lookup (for learning the values in a table).
      • Ideal for training with a training set.
    • Another, already trained, trainable implicit module.
      • Target module is trained to imitate the trainer module.
  • Note: The inputs and outputs of the trainer should be in the same format as the target.
data - The data set over which to train the target module.
  • Examples of possible data sets:
    • Training sets
      • A collection of dimension-value collections where each dimension-value collection is a different configuration of the inputs of the target and training modules. In other words, each dimension-value collection is a different "state."
    • Ranges
      • A collection of dimension-value collections where the Values inside the Dimensions are of type "Range" and have the same ID as the Values of the inputs of the target module.
      • If a "Range" is specified for a Value within a Dimension for one of these dimension-value collections, the associated Value in the input layer of the target module will be trained to handle all of the activations between the lower-bound and the upper-bound at a precision determined by the increment parameter specified by that range.
    • A combination of ranges and training sets
      • Where some dimension-value collections are training sets and others are ranges.
      • Where each dimension-value collection has a combination of Values and Ranges. (i.e. each "state" has some Values that are Ranges and others that are simply Values).
  • Note: The data set just specifies the inputs to use during training. It is the "trainer" module's job to provide the desired output for the target.
  • Also, if you wish to use only one data set (i.e. a single dimension-value collection) for training, then simply create a collection of dimension-value collections that contains only 1 dimension-value collection.
    • This is most often the case when you want to train ALL of the input nodes using ranges.

dataRecursor

private void dataRecursor(AbstractTrainableImplicitModule target,
                          AbstractImplicitModule trainer,
                          java.util.ListIterator<Dimension> dim,
                          java.util.ListIterator<? extends Value> val,
                          TrainableImplicitModulePreTrainer.SumSquaredErrorTracker sqe)
Recursive method that iterates over the dimensions of a dimension-value collection (from the data set and trains the specified target implicit module based on the outputs from the specified trainer implicit module.

Parameters:
target - The target implicit module to be trained.
trainer - The implicit module to be used as the trainer.
dim - A list iterator for the dimensions.
val - A list iterator for the values within the dimension currently being addressed.
sqe - The sum of squared error tracker being used to track the sum of squared error.

innerLoop

private void innerLoop(AbstractTrainableImplicitModule target,
                       AbstractImplicitModule trainer,
                       java.util.ListIterator<Dimension> dim,
                       java.util.ListIterator<? extends Value> val,
                       Dimension d,
                       Value v,
                       TrainableImplicitModulePreTrainer.SumSquaredErrorTracker sqe)
The inner loop of the dataRecursor method.

Parameters:
target - The target implicit module to be trained.
trainer - The implicit module to be used as the trainer.
dim - A list iterator for the dimensions.
val - A list iterator for the values within the dimension currently being addressed.
d - The dimension currently being addressed.
v - The value currently being addressed.
sqe - The sum of squared error tracker being used to track the sum of squared error.