# tutorial/Templates/README

    00001 Quick NOTE: This version of README is obsolete (May 25, 2004)
    00002 In particular, a simpler version of the algorithm can be generated
    00003 using the script
    00004                    createSimple
    00005
    00006 with the same syntax. It is also more powerful, allowing for instance
    00007 to create you own statistics on the population, saving it in a file
    00008 and/or plotting on on-line during the run (see eoStat.tmpl).
    00009 More details some day, when I have some time ...
    00010
    00011 ============= Old README (most is still accurate, though) ==========
    00012
    00013 This directory contains sample files that should make it easy to
    00014 create an EO algorithm to evolve any type of structure
    00015 (EO comes with two examples, bitstrings and vector of real variables,
    00016 so you'll need this as soon as you want to evolve something else).
    00017
    00018 At the moment, only algorithms involving a scalar fitness (double)
    00019 are implemented (see test dir for Pareto optimization of multiple-
    00020 objective fitness - or be patient :-)
    00021
    00022 This file will help you to build the same algorithm than the ones
    00023 in the Lesson4 of the tutorial, but with YOUR genotype instead of
    00024 bitstrings or vector<double>. More details in Lesson5 of the tutorial.
    00025
    00026 It is assumed in the following that you have read the first part of
    00027 the tutorial (Lessons 1 to 4).
    00028
    00029 Creating the algorithm for your genotype
    00030 ----------------------------------------
    00031 In what follows, we will suppose that you want to evolve some data
    00032 structure, and that you have enough programming skills to be able to
    00033 write C code for its random initilialization, its crossover, its
    00034 mutation and the computation of its fitness.
    00035
    00036 The helper script * create.sh * will create for you the files you need
    00037 from the samples in tutorial/Templates dir, and all you'll have to do
    00038 is to include the actual code where indicated in those files (between
    00039 keywords START and END).
    00040
    00041 First, let's choose a name: let's call the new EO class eoAppli.
    00042 All newly created classes will be named eoAppliXXX (in the file
    00043 eoAppliXXX)
    00044
    00045 1- cd to the tutorial dir
    00046
    00047 2- create the directory for your application (let's assume you call it
    00048 APPLICATION): type in
    00049
    00050             mkdir APPLICATION
    00051
    00052 3- go to the Templates dir
    00053
    00054             cd Templates
    00055
    00056 and run the helper script create.sh with the following arguments
    00057
    00058             ./create.sh Appli ../APPLICATION
    00059
    00060 4- cd to the APPLICATION dir (cd ../APPLICATION).
    00061 You should see there the following files:
    00062    AppliEA.cpp            the main file, includes all other, to be compiled
    00063    Makefile               with default target eoAppliEA
    00064    eoAppli.h              class eoAppli<FitT>, FitT = template fitness
    00065    eoAppliEvalFunc.h      class for the computation of fotness
    00066    eoAppliInit.h          class for genotype initlialization
    00067    eoAppliMutation.h      class for mutation
    00068    eoAppliQuadCrossover.h class for (quadratic) crossover
    00069    make_genotype_Appli.h  helper function that create the initializer
    00070    make_op_Appli.h        helper function that creates the variatin operators
    00071
    00072 Note: You can go directly to step 6 and 7: you'll get a lot of
    00073 warnings, but will be able to run an EA that does nothing!
    00074
    00075 5- Edit those files to suit your needs. The minimal addition you'll need
    00076 to make are
    00077    in eoAppli.h              define your genotype
    00078    in eoAppliInit.h          define the initialization of one genotype
    00079    in eoAppliMutation.h      define the mutation of one genotype
    00080    in eoAppliQuadCrossover.h define the crossover of 2 genotypes
    00081
    00082 HINT: look for keywords START and END and modify code in between.
    00083
    00084 6- Compile eoAppliEA.cpp. If your APPLICATION dir is in the tutorial
    00085 dir, you don't need to modify Makefile. Just type in
    00086
    00087                % make
    00088
    00089 7- Run the resulting program:
    00090
    00091                % eoAppliEA
    00092
    00093 The default output is one line per generation with the generation
    00094 number, the number of evaluations performed, the best and average
    00095 fitnesses in the population.
    00096 The algorithm stops by default after 100 generations.
    00097
    00098 8- Customize the parameters: copy eoAppliEA.status into
    00099 e.g. eoAppliEA.param, edit eoAppliEA.param (uncomment the lines you
    00100 want to become active), and run
    00101
    00102                % eoAppliEA @eoAppliEA.param
    00103
    00104 (see the Lesson 5 of the tutorial for more details now).
    00105
    00106 HINTS
    00107 -----
    00108
    00109 1- If some new classes you create require some user parameter, you can
    00110 either read them in the file where they are created (e.g.
    00111 make_op_Appli.h for variation operators), or pass the eoParser to the
    00112 constructor of the class, and read the parameter from the parser.
    00113
    00114 2- If you stick to privacy for the data in your EO class, you will
    00115 probably need to write accessors to those data, as well as some public
    00116 methods to modify them, as soon as some other methods need them too.
    00117
    00118 3- The sample make_op_Appli.h supposes that you ony have one crossover
    00119 and one mutation operator. However, the code for multiple operators is
    00120 there: you can have for instance 2 crossover operators, and choose
    00121 among them according to relative weights (proportional choice) - same
    00122 for mutation. Look at the operator section in eoAppliEA.cpp In
    00123 particular, the user parameters cross1Rate and mut1Rate are totally
    00124 useless for a single operator.
    00125
    00126 To add another operator, you have to create another class by mimicking
    00127 what has been done for the first operator.
    00128 For instance, let's suppose you want to create another mutation.
    00129
    00130 * duplicate the code for eoAppliMutation class
    00131 * in the second version, change the class name (eoAppliMutation) into
    00132 another name (let's say eoAppliBetterMutation) - you must change the
    00133 name in the class declaration, in the constructor and in the
    00134 className() method.
    00135 * in the new eoAppliBetterMutation class, change the code for the
    00136 operator() - and eventually the code for the constructor.
    00137 * in the make_op_Appli.h file, in the mutation section, uncomment the
    00138 lines
    00139       mut = new eoAppliSecondMutation<Indi>(varType  _anyVariable);
    00140       _state.storeFunctor(mut);
    00141       double mut2Rate = _parser.createParam(1.0, "mut2Rate", "Relative rate for mutation 2", '2', "Variation Operators").value();
    00142        propMutation.add(*mut, mut2Rate);
    00143
    00144 and change the name of the class from eoAppliSecondMutation to your
    00145 name eoAppliBetterMutation (you can also change the keyword from
    00146 mut2Rate to something more meaningful like BetterMutationRate).
    00147 You're done!
    00148
    00149 In case of problem: Marc.Schoenauer@inria.fr