JGAP

org.jgap
Interface Gene

All Superinterfaces:
java.lang.Comparable, IUniqueKey, java.io.Serializable
All Known Subinterfaces:
ICompositeGene, Supergene
All Known Implementing Classes:
AbstractSupergene, BaseGene, BooleanGene, CompositeGene, DoubleGene, FixedBinaryGene, IntegerGene, MapGene, MutipleIntegerGene, NickelsPenniesSupergene, NumberGene, SetGene, StringGene

public interface Gene
extends java.lang.Comparable, java.io.Serializable, IUniqueKey

Genes represent the discrete components of a potential solution (the Chromosome). This interface exists so that custom gene implementations can be easily plugged-in, which can add a great deal of flexibility and convenience for many applications. Note that it's very important that implementations of this interface also implement the equals() method. Without a proper implementation of equals(), some genetic operations will fail to work properly.

When implementing a new Gene type, extend it from BaseGene!

Since:
1.0

Field Summary
static java.lang.String CVS_REVISION
          String containing the CVS revision.
static java.lang.String PERSISTENT_FIELD_DELIMITER
          Represents the delimiter that is used to separate fields in the persistent representation.
 
Method Summary
 void applyMutation(int index, double a_percentage)
          Applies a mutation of a given intensity (percentage) onto the atomic element at given index (NumberGenes only have one atomic element)
 void cleanup()
          Executed by the genetic engine when this Gene instance is no longer needed and should perform any necessary resource cleanup.
 java.lang.Object getAllele()
          Retrieves the value represented by this Gene.
 java.lang.Object getApplicationData()
          Retrieves the application-specific data that is attached to this Gene.
 Configuration getConfiguration()
           
 double getEnergy()
           
 java.lang.String getPersistentRepresentation()
          Retrieves a string representation of the value of this Gene instance that includes any information required to reconstruct it at a later time, such as its value and internal state.
 boolean isCompareApplicationData()
           
 Gene newGene()
          Provides an implementation-independent means for creating new Gene instances.
 void setAllele(java.lang.Object a_newValue)
          Sets the value of this Gene to the new given value.
 void setApplicationData(java.lang.Object a_newData)
          This sets the application-specific data that is attached to this Gene.
 void setCompareApplicationData(boolean a_doCompare)
          Should we also consider the application data when comparing?
 void setConstraintChecker(IGeneConstraintChecker a_constraintChecker)
          Sets the constraint checker to be used for this gene whenever method setAllele(Object) is called.
 void setEnergy(double a_energy)
          Sets the energy of the gene
 void setToRandomValue(RandomGenerator a_numberGenerator)
          Sets the value of this Gene to a random legal value for the implementation.
 void setValueFromPersistentRepresentation(java.lang.String a_representation)
          Sets the value and internal state of this Gene from the string representation returned by a previous invocation of the getPersistentRepresentation() method.
 int size()
           
 java.lang.String toString()
           
 
Methods inherited from interface java.lang.Comparable
compareTo
 
Methods inherited from interface org.jgap.IUniqueKey
getUniqueID, getUniqueIDTemplate, setUniqueIDTemplate
 

Field Detail

CVS_REVISION

static final java.lang.String CVS_REVISION
String containing the CVS revision. Read out via reflection!

See Also:
Constant Field Values

PERSISTENT_FIELD_DELIMITER

static final java.lang.String PERSISTENT_FIELD_DELIMITER
Represents the delimiter that is used to separate fields in the persistent representation.

See Also:
Constant Field Values
Method Detail

newGene

Gene newGene()
Provides an implementation-independent means for creating new Gene instances. The new instance that is created and returned should be setup with any implementation-dependent configuration that this Gene instance is setup with (aside from the actual value, of course). For example, if this Gene were setup with bounds on its value, then the Gene instance returned from this method should also be setup with those same bounds. This is important, as the JGAP core will invoke this method on each Gene in the sample Chromosome in order to create each new Gene in the same respective gene position for a new Chromosome.

It should be noted that nothing is guaranteed about the actual value of the returned Gene and it should therefore be considered to be undefined.

Returns:
a new Gene instance of the same type and with the same setup as this concrete Gene
Since:
1.0

setAllele

void setAllele(java.lang.Object a_newValue)
Sets the value of this Gene to the new given value. The actual type of the value is implementation-dependent.

Parameters:
a_newValue - the new value of this Gene instance
Since:
1.0

getAllele

java.lang.Object getAllele()
Retrieves the value represented by this Gene. The actual type of the value is implementation-dependent.

Returns:
the value of this Gene.
Since:
1.0

getPersistentRepresentation

java.lang.String getPersistentRepresentation()
                                             throws java.lang.UnsupportedOperationException
Retrieves a string representation of the value of this Gene instance that includes any information required to reconstruct it at a later time, such as its value and internal state. This string will be used to represent this Gene instance in XML persistence. This is an optional method but, if not implemented, XML persistence and possibly other features will not be available. An UnsupportedOperationException should be thrown if no implementation is provided.

Returns:
string representation of this Gene's current state
Throws:
java.lang.UnsupportedOperationException - to indicate that no implementation is provided for this method
Since:
1.0

setValueFromPersistentRepresentation

void setValueFromPersistentRepresentation(java.lang.String a_representation)
                                          throws java.lang.UnsupportedOperationException,
                                                 UnsupportedRepresentationException
Sets the value and internal state of this Gene from the string representation returned by a previous invocation of the getPersistentRepresentation() method. This is an optional method but, if not implemented, XML persistence and possibly other features will not be available. An UnsupportedOperationException should be thrown if no implementation is provided.

Parameters:
a_representation - the string representation retrieved from a prior call to the getPersistentRepresentation() method
Throws:
java.lang.UnsupportedOperationException - to indicate that no implementation is provided for this method
UnsupportedRepresentationException - if this Gene implementation does not support the given string representation
Since:
1.0

setToRandomValue

void setToRandomValue(RandomGenerator a_numberGenerator)
Sets the value of this Gene to a random legal value for the implementation. This method exists for the benefit of mutation and other operations that simply desire to randomize the value of a gene.

Parameters:
a_numberGenerator - The random number generator that should be used to create any random values. It's important to use this generator to maintain the user's flexibility to configure the genetic engine to use the random number generator of their choice
Since:
1.0

cleanup

void cleanup()
Executed by the genetic engine when this Gene instance is no longer needed and should perform any necessary resource cleanup.


toString

java.lang.String toString()
Overrides:
toString in class java.lang.Object
Returns:
a string representation of the gene
Since:
1.1 (in the interface)

size

int size()
Returns:
the size of the gene, i.e the number of atomic elements. Always 1 for numbers
Since:
1.1

applyMutation

void applyMutation(int index,
                   double a_percentage)
Applies a mutation of a given intensity (percentage) onto the atomic element at given index (NumberGenes only have one atomic element)

Parameters:
index - index of atomic element, between 0 and size()-1
a_percentage - percentage of mutation (greater than -1 and smaller than 1).
Since:
1.1

setApplicationData

void setApplicationData(java.lang.Object a_newData)
This sets the application-specific data that is attached to this Gene. Attaching application-specific data may be useful for some applications when it comes time to distinguish a Gene from another. JGAP ignores this data functionally.

Parameters:
a_newData - the new application-specific data to attach to this Gene
Since:
2.4

getApplicationData

java.lang.Object getApplicationData()
Retrieves the application-specific data that is attached to this Gene. Attaching application-specific data may be useful for some applications when it comes time to distinguish a Gene from another. JGAP ignores this data functionally.

Returns:
the application-specific data previously attached to this Gene, or null if there is no data attached
Since:
2.4

setCompareApplicationData

void setCompareApplicationData(boolean a_doCompare)
Should we also consider the application data when comparing? Default is "false" as "true" means a Gene is losing its identity when application data is set differently!

Parameters:
a_doCompare - true: consider application data in method compareTo
Since:
2.4

isCompareApplicationData

boolean isCompareApplicationData()

getEnergy

double getEnergy()
Returns:
energy of the gene
Since:
2.3

setEnergy

void setEnergy(double a_energy)
Sets the energy of the gene

Parameters:
a_energy - the energy to set
Since:
2.3

setConstraintChecker

void setConstraintChecker(IGeneConstraintChecker a_constraintChecker)
Sets the constraint checker to be used for this gene whenever method setAllele(Object) is called.

Parameters:
a_constraintChecker - the constraint checker to be set
Since:
2.6 (moved from CompositeGene, where it was since 2.0)

getConfiguration

Configuration getConfiguration()
Returns:
the configuration used
Since:
3.0

JGAP