=head1 NAME

    XML - Syntax and semantics of the XML files used in OPEAL

=cut

=head1 SYNOPSIS
 
   my $xml==<<EOC;
  <?xml version="1.0"?>
  <!DOCTYPE ea SYSTEM "EvoSpec.dtd">
  
  <ea version='0.4'>
   <initial>
    <op name='Creator' >
      <param name='number' value='20' />
      <param name='class' value='Vector' />       
      <param name='options'>
        <param name='length' value='2' />
	    <param name='rangestart' value='0' />
        <param name='rangeend' value='1' />
      </param>
    </op>

    <op name='Easy'  type='unary'>
       <param name='selrate' value='0.4' />
       <param name='maxgen' value='100' />
       <code type='eval' language='perl'>
    	  <src><![CDATA[ my $indi = shift;
	                 my ( $x, $y ) = @{$indi->{_array}};
		         my $sqrt = sqrt( $x*$x+$y*$y);
			 return sin( $sqrt )/$sqrt;
          ]]></src>
        </code>
        <op name='GaussianMutation' type='unary' rate='1'>
        	<param name='avg' value='0' />
		<param name='stddev' value='0.1' />
      	</op>
      	<op name='VectorCrossover' type='binary' rate='1'>
        	<param name='numPoints' value='1' />
      	</op>
      </op>
   </initial>

  </ea>
  EOC
  use Algorithm::Evolutionary::Experiment;
  use Algorithm::Evolutionary::Op::Easy;
  my $xp = Algorithm::Evolutionary::Experiment->fromXML( $xml );
  my $popRef = $xp->go();
  
  

=head1 DESCRIPTION


Algorithm::Evolutionary supports XML as a language for description of
the evolutionary algorithm.  
The language is described in the F<EvoSpec.dtd> file, which is an
DTD file, something like a dictionnary that allows to check which
constructions in XML are syntactically correct and which are not. This
XML dialect will be called, for lack of a better name, B<EvoSpec>. I
tried to use XML Schemas instead of DTDs, but couldn't find a good
tool to process them in Perl.

This dialect will be used to describe the algorithm, and also its
results, that is, the population of individuals the
algorithms is going to be applied to. The first part is contained
within the B<initial> tag, while the latter goes between a couple of
B<pop> tags, and right after the  B<initial> element.

=head2 C<initial>

The B<initial> tag contains several sections. In principle, the number
of sections is not bounded, but it is usual to have only two, one
related to the individuals, and another related to the
population. Imagine that section as a set of transformations to be
performed in turn. If you put a B<pop> descriptor at the beginning of
the B<initial> element, and then an operator, the operator will be
applied to the population; if it is an population
L<Algorithm::Evolutionary::Op::Creator|Creator>, and then several
operators, the population will be created and then each operator will
be applied in turn. B<initial> is like a pipeline that applies
operators to a population, which is implied or not, in document order.

So, basically what you will find or include in this section are
L<Algorithm::Evolutionary::Op::Base|operator> and population
elements. 

=head3 C<pop>
A population element might look like this:C< <pop size='20'>
<param name='type' value='BitString' /> <param name='length'
value='64' /> </pop> > . The pop element has an attribute that
indicates its size, and then describes the kind of individuals that
are going to be create. This section includes parameters that describe
the individual type and any other thing needed to create it; the
parameters are C<type>, for the class in which the individuals are
going to be instantiated, and other parameters such as C<length>, that
will be passed to the class constructor. 

=head3 C<op>

After, or instead, the declaration of the initial population, there
will be declarations for one or more operators that will act on the
population. If there is no population, the first operator should be a
C<Creator>, just like this: 

    <op name='Creator' > 
       <param name='number' value='20' /> 
       <param name='class' value='BitString' /> 
       <param name='options'> 
          <param name='length' value='64' /> 
       </param> 
    </op> 

A C<Creator> is a 0-ary population operator: takes a population, which
could have no individuals, and adds individuals as specified by the
XML fragment. In this case, 20 individuals, of class
L<Algorithm::Evolutionary::Individual::BitString|BitString>, with the
C<length> as an option that will be passed to the individual
constructor. 

Once the population has been created, be it via the C<pop> tag or a
C<Creator> operator, some stuff should be done on it. In this case, we
apply the L<Algorithm::Evolutionary::Individual::Easy|Easy> operator:
an easy-to-build genetic algorithm, with default mutation and
crossover operator. A couple of parameters, given using the C<param>
tag, are passed to the operator: the selection rate (C<selrate>) and
the maximun number of generations (C<maxgen>). Each operator has its
own parameters, which are normally (or should be) specified in its
synopsis. Wrong parameters will not hurt, but if required parameters
are not set, Perl will complain (as it should). 

There is another part a bit further on that is required: the fitness
function, which falls within the C<code> tag. The language and the
type of function should be specified. Right now, only the Perl
language is supported, as well as only the C<eval> or fitness
function, but, in principle, any code could be passed this way; it
will go to an entry in the operator under the C<_eval> name. Since
this entry includes free Perl code, it must be enclosed in a CDATA
tag, so it's not interpreted by the XML parser. 

Although this can be in any order, following the code come the
operators that are going to be included in this operator. In this
case, the operators are Mutation and Crossover, and they follow the
same convention as its parent. Type and rate must be specified, as
well as any parameters. These parameters are interpreted in the
context of the operator, so they could be applied, in principle, to
the population or to individuals within it; the only requisite is that
the L<Algorithm::Evolutionary::Op::Base> class is able to interpret
this and create an operator from it.

=head2 Runtime 

Any Algorithm::Evolutionary program should be able to generate valid
XML at any point during execution; normally, whatever is generated
during runtime will go B<after> the C<initial> tag, and will usually
consist of a population section like this one.

  <pop> <indi type='BitString' fitness='16' >  <atom>0</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>1</atom> <atom>0</atom>
  <atom>0</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>1</atom> <atom>1</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>0</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>0</atom>
  <atom>0</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>0</atom> <atom>1</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>0</atom> <atom>1</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>1</atom> <atom>1</atom>
  <atom>1</atom> <atom>1</atom> <atom>1</atom> <atom>1</atom>
  <atom>0</atom> <atom>0</atom> <atom>1</atom> <atom>0</atom>
  <atom>1</atom> <atom>0</atom> <atom>0</atom> </indi> </pop>

This population will be read when reinstating an experiment by the
L<Algorithm::Evolutionary::Experiment> class, and taken as initial
population to apply the rest of operators on it.


=cut

=head2 Copyright
  
  This file is released under the GPL. See the LICENSE file included in this distribution,
  or go to http://www.fsf.org/licenses/gpl.txt

  CVS Info: $Date: 2003/02/27 11:05:45 $ 
  $Header: /cvsroot/opeal/opeal/Algorithm/Evolutionary/XML.pod,v 1.7 2003/02/27 11:05:45 jmerelo Exp $ 
  $Author: jmerelo $ 
  $Revision: 1.7 $

=cut