=head1 NAME

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

=cut

=head1 SYNOPSIS


   <?xml version="1.0"?>
   <!-- Parameters for an evolutionary algorithm; also generation 0 of the same algorithm -->

   <ea xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation='ea-alpha.xsd'
    version='0.2'>

    <initial>
     <section name='indi'> 
      <param name='type' value='VectorIndi' /> 
      <param name='length' value='2' />
	  <param name='rangestart' value='0' />
      <param name='rangeend' value='1' />
     </section>

     <section name='pop'> 
      <param name='size'  value='20' />
      <op name='EasyAlgorithm'  type='unary'>
        <param name='selrate' value='0.4' />
        <param name='maxgen' value='100' />
        <code type='eval' language='perl'>
    	  <src>	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>
     </section>
    
    </initial>

    <runtime>
    </runtime> 

  </ea>

  # This XML doc will be read by a program like this one, which will
  # run the EA (parse-opeal-1.pl)

  #!/usr/bin/perl

  use warnings;
  use strict;
  #New parser for the new version of the schema

  use XML::Simple;

  #EA-related modules
  use IndiBase;
  use OpBase;

  #-------------------------- Program starts here --------------------------------

  my $file = shift || die "Usage: $0 <filename to parse>\n";

  #Open file and parse it
  open(IN, "<$file" );
  my $xml=join("", <IN>);
  close IN;
  my $ref = XMLin($xml);

  #Create population
  my @pop;
  for ( my $i = 0; $i < $ref->{initial}{section}{pop}{param}{value}; $i ++ ) {
    my $indi = IndiBase->fromParam( $ref->{initial}{section}{indi}{param} );
    push( @pop, $indi );
    print $indi->asString, "\n";
  }

  #Create an algorithm
  my $easyEA = OpBase->fromXML( $ref->{initial}{section}{pop}{op} );

  for ( my $i = 0; $i < $ref->{initial}{section}{pop}{op}{param}{maxgen}{value}; $i++ ) {
    print "<", "="x 20, "Generation $i", "="x 20, ">\n";
    $easyEA->apply( \@pop );
    for ( @pop ) {
	print $_->asString, "\n";
    }
  }


=cut

=head1 DESCRIPTION

OPEAL supports XML as a language for description of the evolutionary algorithm. 
The language is described in the F<ea-alpha.xsd> file, which is an
XSchema 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>.

This dialect will be used to describe the algorithm, and also the
results of the algorithm, 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<runtime> tags.

The  B<initial> tag contains several sections. In principle, the
number of sections is not bounded, but it's usual to have only two,
one related to the individuals, and another related to the
population. 

The first section describes the parameters used to create
an individual by the evolutionary algorithm, included its type. In
this case, individuals of the class L<VectorIndi|VectorIndi> will be created to
form the population, described in the second section. All parameters
have a B<name> and a B<value>, and you can have as many as you
need. The only compulsory one is the B<type> parameter, which
indicates the class in which the population members will be instantiated.

The second section describes population-related stuff; basically
population parameters and the algorithms that are going to be applied
to the population; the tag B<op> describes the operator applied to the
population; how these operators will be applied is left to the program
that parses this file. In this case, an algorithm of the class L<EasyAlgorithm|EasyAlgorithm>
will be applied.

This operator includes in itself all the parameters and operators that
it needs, in such a way that it recursively creates the objects that
are described in the XML fragment: the
L<GaussianMutation|GaussianMutation> operator, and the
L<VectorCrossover|VectorCrossover> crossover operator.

It also includes the fragments of code that are problem specific, such
as, in this case, the code that evaluates the I<chromosome> to give it
a fitness; this code, within the B<code> tag will be wrapped into a
bit of more code, and converted to a pointer-so-subroutine. Any other
specific code should be declared this way; it will be available within
the operator via the C<self->{_type}> pointer.


=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: 2006/03/15 08:51:23 $ 
  $Header: /cvsroot/opeal/opeal/Algorithm/xml/XML.pod,v 1.1 2006/03/15 08:51:23 jmerelo Exp $ 
  $Author: jmerelo $ 
  $Revision: 1.1 $

=cut