fr.vergne.optimization.population.PopulationManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of optimization-core Show documentation
Algorithms implementation.
The newest version!
package fr.vergne.optimization.population;

import java.util.Collection;
import java.util.Iterator;

import fr.vergne.optimization.generator.Generator;

/**
 * A {@link PopulationManager} aims at managing the storage of
 * {@link Individual}s. In particular, when a new {@link Individual} is
 * generated by a {@link Generator}, this {@link Individual} is expected to be
 * inserted into the current population. However, specific policies could be
 * used, such as keeping only a restricted amount of {@link Individual}s, or
 * refusing {@link Individual}s which does not meet some criteria, etc. This
 * interface stays at a high abstraction level and let such decisions to
 * specific implementations.

 * 

 * As this {@link PopulationManager} aimed to be used for an optimization
 * purpose, the method {@link #getBest()} is requested to be implemented,
 * because the {@link PopulationManager} is the one which is expected to deal
 * with {@link Individual} evaluations.
 * 
 * @author Matthieu Vergne 
 * 
 * @param 
 */
public interface PopulationManager {

	/**
	 * 
	 * @param individual
	 *            a new {@link Individual} to introduce into the population
	 */
	public void push(Individual individual);

	/**
	 * 
	 * @return the current population of {@link Individual}s
	 */
	public Collection getPopulation();

	/**
	 * This method aims at providing some best {@link Individual}s of the
	 * population. More concretely, this method return an iterator among the
	 * population which should respect these constraints:
	 * 
	 * only {@link Individual}s in the current population can be returned
	 * when an {@link Individual} is returned, it should be at at least as
	 * good as the {@link Individual}s in the population which have not been
	 * returned
	 * if the population is not empty, at least one {@link Individual}
	 * should be returned
	 * 
	 * These constraints allow to ensure that this method can be used to get the
	 * best {@link Individual}. It is recommended to return all the
	 * {@link Individual}s in the population, but it is not mandatory,
	 * especially because nothing ensure that all the population can be totally
	 * sorted. In such a case, a possible implementation of the {@link Iterator}
	 * is to return all the {@link Individual}s which has the same (best)
	 * evaluation.
	 * 
	 * @return a sequence of {@link Individual}s in the current population,
	 *         starting from the best one.
	 */
	public Iterator getBest();

}