/*
 * File:        Chromosome.java
 * Author:      Justin Basilico
 * Course:      PO CS 152: Neural Networks
 * Assignment:  Final Project
 * Updated:     2001.12.18
 * Created:     2001.12.06
 *
 * Description:
 * This file contains the Chromosome interface, which defines the common
 * functionality among chromosomes used in genetic programming.
 *
 * Copyright:    Justin Basilico (2001).
 */

import java.util.Random;

/**
 * Chromosome interface
 *
 * This interface defines the common functionality among chromosomes used in
 * genetic programming. Classes that implement this interface need to
 * implement methods for crossover and mutation along with a method for making
 * a deep-copy of the Chromosome.
 *
 * In genetic programming, a Chromosome refers to the genetic code that is
 * being evolved encoded in some manner that is susceptible to crossover and
 * mutation.
 *
 * @author  Justin Basilico
 * @version 2001.12.18
 * @see     Genome
 * @see     FitnessFunction
 */
public interface Chromosome
    extends Cloneable
{
    /**
     * crossover
     *
     * This method takes another Chromosome object, a crossover rate per
     * element in the Chromosome, and a Random object. It applies a crossover
     * to the Chromosome it is called on and the given Chromosome using the
     * given rate and random number generator. The result of the crossover is
     * stored in the two Chromosomes that were being crossed over.
     *
     * The idea of crossover is that you take two Chromosomes and interchange
     * elements between them in some manner in order to get two new
     * Chromosomes in order to improve the population.
     *
     * Any classes that implement this method need to make sure that the
     * Chromosome that is being crossed over with is compatible for crossover.
     *
     * @param  otherChrom The Chromosome to do the crossover with. It needs to
     *         be a Chromosome that is compatible for crossover with this one.
     * @param  crossoverRate The double crossover rate per element in the
     *         Chromosome.
     * @param  random The Random object to do the random number generation
     *         with.
     * @see    java.util.Random
     */
    public void crossover(
        Chromosome          otherChrom,         // Chromosome to crossover.
        double              crossoverRate,      // Crossover rate per element.
        Random              random);            // Random number generator.

    /**
     * mutate
     *
     * This method takes a mutation rate per element in the Chromosome and a
     * Random object. It applies mutation to the Chromosome it is called on by
     * somehow changing the genes in the Chromosome randomly by using the
     * given values. No value is returned because the Chromosome itself is to
     * be mutated.
     *
     * The idea of mutation is to randomly select elements in the Chromosome
     * to change in order to increase the variety of the population.
     *
     * @param  mutationRate The double mutation rate per element of the
     *         Chromosome.
     * @param  random The Random object to do the random number generation
     *         with.
     * @see    java.util.Random
     */
    public void mutate(
        double              mutationRate,       // Mutation rate per element.
        Random              random);            // Random number generator.

    /**
     * clone
     *
     * This method returns a deep-copy of the Chromosome it is called on.
     *
     * @return A new Chromosome is a deep-copy of this Chromosome.
     * @see    java.lang.Cloneable
     */
    public Object clone();
}