/*
* Encog(tm) Core v3.4 - Java Version
* http://www.heatonresearch.com/encog/
* https://github.com/encog/encog-java-core
* Copyright 2008-2016 Heaton Research, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* For more information on Heaton Research copyrights, licenses
* and trademarks visit:
* http://www.heatonresearch.com/copyright
*/
package org.encog.ml.ea.train;
import java.util.List;
import org.encog.ml.CalculateScore;
import org.encog.ml.ea.codec.GeneticCODEC;
import org.encog.ml.ea.genome.Genome;
import org.encog.ml.ea.opp.EvolutionaryOperator;
import org.encog.ml.ea.opp.OperationList;
import org.encog.ml.ea.opp.selection.SelectionOperator;
import org.encog.ml.ea.population.Population;
import org.encog.ml.ea.rules.RuleHolder;
import org.encog.ml.ea.score.AdjustScore;
import org.encog.ml.ea.sort.GenomeComparator;
import org.encog.ml.ea.species.Speciation;
/**
* This interface defines the basic functionality of an Evolutionary Algorithm.
* An evolutionary algorithm is one that applies operations to a population of
* potential "solutions".
*/
public interface EvolutionaryAlgorithm {
/**
* Add an operation.
*
* @param probability
* The probability of using this operator.
* @param opp
* The operator to add.
*/
void addOperation(double probability, EvolutionaryOperator opp);
/**
* Add a score adjuster. Score adjusters are used to adjust the adjusted
* score of a genome. This allows bonuses and penalties to be applied for
* desirable or undesirable traits.
*
* @param scoreAdjust
* The score adjustor to add.
*/
void addScoreAdjuster(AdjustScore scoreAdjust);
/**
* Calculate the score for a genome.
*
* @param g
* The genome to calculate the score for.
*/
void calculateScore(Genome g);
/**
* Called when training is finished. This allows the EA to properly shut
* down.
*/
void finishTraining();
/**
* Get the comparator that is used to choose the "true best" genome. This
* uses the real score, and not the adjusted score.
*
* @return The best comparator.
*/
GenomeComparator getBestComparator();
/**
* @return The current best genome. This genome is safe to use while the EA
* is running. Genomes are not modified. They simply produce
* "offspring".
*/
Genome getBestGenome();
/**
* @return The CODEC that is used to transform between genome and phenome.
*/
GeneticCODEC getCODEC();
/**
* @return The current score. This value should either be minimized or
* maximized, depending on the score function.
*/
double getError();
/**
* @return The current iteration number. Also sometimes referred to as
* generation or epoch.
*/
int getIteration();
/**
* @return The maximum size an individual genome can be. This is an
* arbitrary number defined by the genome. Lower numbers are less
* complex.
*/
int getMaxIndividualSize();
/**
* @return The maximum number to try certain genetic operations. This
* prevents endless loops.
*/
int getMaxTries();
/**
* @return The operators.
*/
OperationList getOperators();
/**
* @return The population.
*/
Population getPopulation();
/**
* @return The score adjusters. This allows bonuses and penalties to be
* applied for desirable or undesirable traits.
*/
List<AdjustScore> getScoreAdjusters();
/**
* @return The score function.
*/
CalculateScore getScoreFunction();
/**
* @return The selection operator. Used to choose genomes.
*/
public SelectionOperator getSelection();
/**
* Get the comparator that is used to choose the "best" genome for
* selection, as opposed to the "true best". This uses the adjusted score,
* and not the score.
*
* @return The selection comparator.
*/
GenomeComparator getSelectionComparator();
/**
* @return True if exceptions that occur during genetic operations should be
* ignored.
*/
boolean getShouldIgnoreExceptions();
/**
* @return The speciation method.
*/
Speciation getSpeciation();
/**
* @return True if any genome validators should be applied.
*/
boolean isValidationMode();
/**
* Perform a training iteration. Also called generations or epochs.
*/
void iteration();
/**
* Set the comparator that is used to choose the "true best" genome. This
* uses the real score, and not the adjusted score.
*
* @param bestComparator
* The best comparator.
*/
void setBestComparator(GenomeComparator bestComparator);
/**
* Set the population.
*
* @param thePopulation
* The population.
*/
void setPopulation(Population thePopulation);
/**
* Set the selection operator.
*
* @param selection
* The selection operator.
*/
public void setSelection(SelectionOperator selection);
/**
* Set the comparator that is used to choose the "best" genome for
* selection, as opposed to the "true best". This uses the adjusted score,
* and not the score.
*
* @param selectionComparator
* The selection comparator.
*/
void setSelectionComparator(GenomeComparator selectionComparator);
/**
* Determines if genetic operator exceptions should be ignored.
*
* @param b
* True if exceptions should be ignored.
*/
void setShouldIgnoreExceptions(boolean b);
/**
* Set the speciation method.
*
* @param m
* The speciation method.
*/
void setSpeciation(Speciation m);
/**
* Determine if the genomes should be validated. This takes more time but
* can help isolate a problem.
*
* @param validationMode
* True, if validation mode is enabled.
*/
void setValidationMode(boolean validationMode);
}