001/*
002 * BioJava development code This code may be freely distributed and modified
003 * under the terms of the GNU Lesser General Public Licence. This should be
004 * distributed with the code. If you do not have a copy, see:
005 * http://www.gnu.org/copyleft/lesser.html Copyright for this code is held
006 * jointly by the individual authors. These should be listed in @author doc
007 * comments. For more information on the BioJava project and its aims, or to
008 * join the biojava-l mailing list, visit the home page at:
009 * http://www.biojava.org/
010 */
011
012package org.biojavax.ga;
013
014import org.biojava.bio.symbol.IllegalAlphabetException;
015import org.biojava.bio.symbol.IllegalSymbolException;
016import org.biojava.utils.ChangeType;
017import org.biojava.utils.ChangeVetoException;
018import org.biojava.utils.Changeable;
019import org.biojavax.ga.functions.CrossOverFunction;
020import org.biojavax.ga.functions.FitnessFunction;
021import org.biojavax.ga.functions.MutationFunction;
022import org.biojavax.ga.functions.SelectionFunction;
023
024/**
025 * The class that runs the cycles of reproduction, evolution and selection,
026 * potentially on multiple <code>Population</code>s
027 * </p>
028 *
029 * @author Mark Schreiber
030 * @author Susanne Merz
031 * @author Andreas Dr&auml;ger
032 * @version 1.1
033 * @since 1.5
034 */
035
036public interface GeneticAlgorithm extends Changeable {
037
038        public static ChangeType        FITNESS_FUNCTION        = new ChangeType(
039                                                       "Fitness function changed",
040                                                       GeneticAlgorithm.class,
041                                                       "FITNESS_FUNCTION");
042
043        /**
044         * The fitness function that will be used to compute the fitness of each
045         * organism.
046         *
047         * @param func
048         *          the <code>FitnessFunction</code> to be used
049         * @throws ChangeVetoException
050         *           if the change is vetoed.
051         */
052        public void setFitnessFunction(FitnessFunction func)
053            throws ChangeVetoException;
054
055        /**
056         * Returns the fitness function, i.e. the class that computes the fitness of
057         * each organism in a population.
058         *
059         * @return the fitness function
060         */
061        public FitnessFunction getFitnessFunction();
062
063        /**
064         * Sets the <code>Population</code> of <code>Organisms</code> to the
065         * Algorithm.
066         *
067         * @param pop
068         *          the population to add.
069         * @throws ChangeVetoException
070         *           if new populations are not allowed.
071         */
072        public void setPopulation(Population pop) throws ChangeVetoException;
073
074        /**
075         * The registered <code>Population</code>
076         *
077         * @return the <code>Population</code> being operated on.
078         */
079        public Population getPopulation();
080
081        /**
082         * Changes the <code>SelectionFunction</code> used to select candidates for
083         * the next generation
084         *
085         * @param function
086         *          a <code>SelectionFunction</code>
087         * @throws ChangeVetoException
088         *           if the <code>SelectionFunction</code> is not allowed to be
089         *           changed
090         */
091        public void setSelectionFunction(SelectionFunction function)
092            throws ChangeVetoException;
093
094        /**
095         * @return the current <code>SelectionFunction</code>
096         */
097        public SelectionFunction getSelectionFunction();
098
099        /**
100         * Changes the <code>CrossOverFunction</code> used to CrossOver Chromosomes
101         *
102         * @param function
103         *          a <code>CrossOverFunction</code>
104         * @throws ChangeVetoException
105         *           if the <code>CrossOverFunction</code> is not allowed to be
106         *           changed
107         */
108        public void setCrossOverFunction(CrossOverFunction function)
109            throws ChangeVetoException;
110
111        /**
112         * @return the current CrossOverFunction
113         */
114        public CrossOverFunction getCrossOverFunction();
115
116        /**
117         * Sets the current <code>MutationFunction</code>
118         *
119         * @param function
120         *          a <code>MutationFunction</code>
121         * @throws ChangeVetoException
122         *           if the <code>MutationFunction</code> change is Vetoed by a
123         *           listener.
124         */
125        public void setMutationFunction(MutationFunction function)
126            throws ChangeVetoException;
127
128        /**
129         * @return the current <code>MutationFunction</code>
130         */
131        public MutationFunction getMutationFunction();
132
133        /**
134         * @return the Current generation number
135         */
136        public int getGeneration();
137
138        /**
139         * Iterates the Algorithm until the stopping criteria are met. For saftey
140         * implementations should synchronize on this method.
141         *
142         * @param stoppingCriteria
143         *          determines when to stop.
144         * @throws ChangeVetoException
145         *           if the Population being modified is locked
146         * @throws IllegalAlphabetException
147         *           if the MutationFunction chosen attempts to modify a Symbol from
148         *           one of the Chromosomes to a Symbol outside of its Alphabet.
149         * @throws IllegalSymbolException
150         *           if the MutationFunction chosen is using the wrong Alphabet.
151         */
152        public void run(GAStoppingCriteria stoppingCriteria)
153            throws ChangeVetoException, IllegalAlphabetException,
154            IllegalSymbolException;
155
156        public static ChangeType        POPULATION              = new ChangeType(
157                                                          "Population changed",
158                                                          GeneticAlgorithm.class,
159                                                          "POPULATION");
160
161        public static ChangeType        FUNCTION                  = new ChangeType(
162                                                          "Function changed",
163                                                          GeneticAlgorithm.class,
164                                                          "FUNCTION");
165
166        public static ChangeType        CROSS_OVER_FUNCTION     = new ChangeType(
167                                                          "Cross over function changed",
168                                                          GeneticAlgorithm.class,
169                                                          "CROSS_OVER_FUNCTION",
170                                                          FUNCTION);
171
172        public static ChangeType        MUTATION_FUNCTION         = new ChangeType(
173                                                          "Mutation function changed",
174                                                          GeneticAlgorithm.class,
175                                                          "MUTATION_FUNCTION",
176                                                          FUNCTION);
177
178        public static ChangeType        SELECTION_FUNCTION      = new ChangeType(
179                                                          "Selection function changed",
180                                                          GeneticAlgorithm.class,
181                                                          "SELECTION_FUNCTION",
182                                                          FUNCTION);
183}