/*
  Copyright 2006 by Sean Luke
  Licensed under the Academic Free License version 3.0
  See the file "LICENSE" for more information
*/


package ec;
import ec.util.*;
import java.io.*;

/* 
 * Population.java
 * 
 * Created: Tue Aug 10 20:50:54 1999
 * By: Sean Luke
 */

/**
 * A Population is the repository for all the Individuals being bred or
 * evaluated in the evolutionary run at a given time.
 * A Population is basically an array of Subpopulations, each of which
 * are arrays of Individuals coupled with a single Species per Subpoulation.
 *
 * 
The first Population is created using the initializePopulation method
 * of the Initializer object, which typically calls the Population's
 * populate() method in turn.  On generational systems, subsequent populations
 * are created on a generation-by-generation basis by the Breeder object,
 * replacing the previous Population.
 *
 * 
In a multithreaded area of a run, Populations should be considered
 * immutable.  That is, once they are created, they should not be modified,
 * nor anything they contain.  This protocol helps ensure read-safety under
 * multithreading race conditions.
 *

 
Parameters

 

 
base.subpops

 int >= 1
 
(the number of subpopulations)

 
base.subpop.n

 classname, inherits or = ec.Subpopulation
 
(the class for subpopulation #n)

 
base.default-subpop

 int >= 0
 
(the default subpopulation index.  The parameter base of this subpopulation will be used as the default base for all subpopulations which do not define one themselves./tr>
 

 
Parameter bases

 

 
base.subpop.n
 
Subpopulation #n.
 
 *
 * @author Sean Luke
 * @version 1.0 
 */

public class Population implements Group
    {
    private static final long serialVersionUID = 1;

    public Subpopulation[] subpops;
    public static final String P_SIZE = "subpops";
    public static final String P_SUBPOP = "subpop";
    public static final String P_DEFAULT_SUBPOP = "default-subpop";
    public static final String P_FILE = "file";
    public static final String NUM_SUBPOPS_PREAMBLE = "Number of Subpopulations: ";
    public static final String SUBPOP_INDEX_PREAMBLE = "Subpopulation Number: ";


    /* A new population should be loaded from this resource name if it is non-null;
       otherwise they should be created at random.  */
    public boolean loadInds;
    public Parameter file;

    /** Returns an instance of Population just like it had been before it was
        populated with individuals. You may need to override this if you override
        Population. IMPORTANT NOTE: if the size of the array in
        Population has been changed, then the clone will take on the new array
        size.  This helps some evolution strategies.
        @see Group#emptyClone()
    */

    public Group emptyClone()
        {
        try
            {
            Population p = (Population)clone();
            p.subpops = new Subpopulation[subpops.length];
            for(int x=0;x0.\n",base.push(P_SIZE));
        subpops = new Subpopulation[size];

        // Set up the subpopulations
        for (int x=0;x= 0)
                    {
                    state.output.warning("Using subpopulation " + defaultSubpop + " as the default for subpopulation " + x);
                    p = base.push(P_SUBPOP).push(""+defaultSubpop);
                    }
                // else an error will occur on the next line anyway.
                }
            subpops[x] = (Subpopulation)(state.parameters.getInstanceForParameterEq(p,null,Subpopulation.class));  // Subpopulation.class is fine
            subpops[x].setup(state,p);
            
            // test for loadinds
            if (loadInds && subpops[x].loadInds)  // uh oh
                state.output.fatal("Both a subpopulation and its parent population have been told to load from files.  This can't happen.  It's got to be one or the other.",
                    base.push(P_FILE), null);
            }
        }

    /** Populates the population with new random individuals. */ 
    public void populate(EvolutionState state, int thread)
        {
        // should we load individuals from a file? -- duplicates are permitted
        if (loadInds)
            {
            InputStream stream = state.parameters.getResource(file,null);
            if (stream == null)
                state.output.fatal("Could not load population from file", file);
            
            try { readPopulation(state, new LineNumberReader(new InputStreamReader(stream))); }
            catch (IOException e) { state.output.fatal("An IOException occurred when trying to read from the file " + state.parameters.getString(file, null) + ".  The IOException was: \n" + e,
                    file, null); }
            }
        else
            {
            // let's populate!
            for(int x=0;x