ai4r 1.0

data/site/src/documentation/README.txt

@@ -0,0 +1,7 @@
+This is the base documentation directory.
+
+skinconf.xml     # This file customizes Forrest for your project. In it, you
+                 # tell forrest the project name, logo, copyright info, etc
+
+sitemap.xmap     # Optional. This sitemap is consulted before all core sitemaps.
+                 # See http://forrest.apache.org/docs/project-sitemap.html

data/site/src/documentation/classes/CatalogManager.properties

@@ -0,0 +1,62 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#=======================================================================
+# CatalogManager.properties for Catalog Entity Resolver.
+#
+# This is the default properties file for your project.
+# This facilitates local configuration of application-specific catalogs.
+# If you have defined any local catalogs, then they will be loaded
+# before Forrest's core catalogs.
+#
+# See the Apache Forrest documentation:
+# http://forrest.apache.org/docs/your-project.html
+# http://forrest.apache.org/docs/validation.html
+
+# verbosity:
+# The level of messages for status/debug (messages go to standard output).
+# The setting here is for your own local catalogs.
+# The verbosity of Forrest's core catalogs is controlled via
+#  main/webapp/WEB-INF/cocoon.xconf
+#
+# The following messages are provided ...
+#  0 = none
+#  1 = ? (... not sure yet)
+#  2 = 1+, Loading catalog, Resolved public, Resolved system
+#  3 = 2+, Catalog does not exist, resolvePublic, resolveSystem
+#  10 = 3+, List all catalog entries when loading a catalog
+#    (Cocoon also logs the "Resolved public" messages.)
+verbosity=1
+
+# catalogs ... list of additional catalogs to load
+#  (Note that Apache Forrest will automatically load its own default catalog
+#  from main/webapp/resources/schema/catalog.xcat)
+# Use either full pathnames or relative pathnames.
+# pathname separator is always semi-colon (;) regardless of operating system
+# directory separator is always slash (/) regardless of operating system
+# The project catalog is expected to be at ../resources/schema/catalog.xcat
+#catalogs=../resources/schema/catalog.xcat
+# FIXME: Workaround FOR-548 "project DTD catalogs are not included
+# when running as a servlet WAR". 
+# Same catalog, different path
+catalogs=../resources/schema/catalog.xcat;../../project/src/documentation/resources/schema/catalog.xcat
+
+# relative-catalogs
+# If false, relative catalog URIs are made absolute with respect to the
+# base URI of the CatalogManager.properties file. This setting only 
+# applies to catalog URIs obtained from the catalogs property in the
+# CatalogManager.properties file
+# Example: relative-catalogs=[yes|no]
+relative-catalogs=no

data/site/src/documentation/content/locationmap.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<locationmap xmlns="http://apache.org/forrest/locationmap/1.0">
+  <components>
+    <matchers default="lm">
+      <matcher name="lm" src="org.apache.forrest.locationmap.WildcardLocationMapHintMatcher"/>
+    </matchers>
+<!--
+      * Can contain any sitemap selector with the following syntax. * 
+    <selectors default="exists">
+      <selector name="exists" logger="sitemap.selector.exists"  
+          src="org.apache.forrest.sourceexists.SourceExistsSelector" />
+    </selectors>
+    -->
+  </components>
+<!--
+    * Can contain a mount statement as a sibling to components and locator *
+    <mount src="somelocation.xml"/>
+  -->
+  <locator>
+<!--
+      * Can contain a mount within a selector where a selector is valid. 
+    <select>
+      <mount src="somelocation.xml"/>
+    </select>
+    -->
+    <match pattern="project.rewrite.**">
+      <location src="http://cocoon.apache.org/{1}.html"/>
+    </match>
+    <match pattern="project.remote.**.xml">
+      <location src="http://svn.apache.org/repos/asf/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/{1}.xml"/>
+    </match>
+<!-- 
+      * Can use a selector inside a match.  *
+    <match pattern="somepattern/**">
+      <select>
+        <location src="first-location-attempted"/>
+        <location src="second-location-attempted"/>
+        <location src="third-location-attepted"/>
+      </select>
+    </match>
+    -->
+<!--
+     To locate all your source documents in a slide repository you can do:
+
+    <match pattern="tabs.xml">
+      <location src="http://127.0.0.1:8080/slide/files/tabs.xml"/>
+    </match>
+    <match pattern="site.xml">
+      <location src="http://127.0.0.1:8080/slide/files/site.xml"/>
+    </match>
+    <match pattern="**.xml">
+      <location src="http://127.0.0.1:8080/slide/files/{1}.xml"/>
+    </match>
+    -->
+  </locator>
+</locationmap>

data/site/src/documentation/content/xdocs/downloads.html

@@ -0,0 +1,9 @@
+<html>
+<head>
+  <title>Artificial intelligence for ruby :: ai4r :: download page at RubyForge</title>
+</head>
+	<body>
+		<h1><a name="intro" />Artificial intelligence for ruby - ai4r - download page at RubyForge</h1>
+		<iframe width="100%" height="800px" frameborder="0" src="http://rubyforge.org/frs/?group_id=4942" />
+	</body>
+</html>

data/site/src/documentation/content/xdocs/geneticAlgorithms.xml

@@ -0,0 +1,280 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Genetics Algorithms in Ruby :: ai4r</title>
+  </header>
+  <body>
+    <section id="Introduction">
+      <title>Introduction to Genetics Algorithms in Ruby</title>
+      <p>The GeneticAlgorithm module implements the GeneticSearch and Chromosome classes. The GeneticSearch is a generic class, and can be used to solved any kind of problems. The GeneticSearch class performs a stochastic search 
+	of the solution of a given problem. It uses the following pseudocode:        
+      </p>
+	<ol>
+		<li>Choose initial population</li>
+		<li>Evaluate the fitness of each individual in the population</li>
+		<li>Repeat as many times as generations we allow
+			<ol>
+				<li>Select randomly best-ranking individuals to reproduce</li>
+				<li>Breed new generation through crossover and mutation (genetic operations) and give birth to offspring</li>
+				<li>Evaluate the individual fitnesses of the offspring</li>
+				<li>Replace worst ranked part of population with offspring</li>
+			</ol>
+		</li>
+	</ol>
+	<p>The Chromosome is "problem specific". Ai4r built-in Chromosomeclass was designed to model the <a href="http://en.wikipedia.org/wiki/Traveling_salesman_problem" title="Link to Wikipedia">Travelling salesman problem</a>. You have to provide a matrix with the cost of traveling from one point to another (array of arrays of float values). If you want to solve other type of problem, you will have to modify the Chromosome class, by overwriting its fitness, reproduce, and mutate functions, to model you specific problem.</p>
+    </section>
+
+<section id="how-to-run">
+      <title>How to use it</title>
+<source>
+<![CDATA[
+#Cost of traveling from one point to another. E.g. Travelling from Node 0 to Node 2 costs 5.
+data_set = [	[ 0, 10, 5],
+		[ 6,  0, 4],
+		[25,  4, 0]
+	]		
+
+GeneticAlgorithm::Chromosome.set_cost_matrix(data_set)
+
+search = GeneticAlgorithm::GeneticSearch.new(10, 20)
+result = search.run
+puts "Result cost: #{result.fitness}"
+puts "Result nodes: #{result.data.inspect}"
+]]>
+</source>
+    </section>
+
+    <section id="Example">
+      <title>The European Rock Tour Problem (Also known as the Travelling salesman problem)</title>
+      <p>An ageing rock band was planning its (hopefully) last european tour. They were planning to visite 15 european cities: Barcelona, Berlin, Brussels, Dublin, Hamburg, Kiev, London, Madrid, Milan, Moscow, Munich, Paris, Rome, Vienna, and  Warsaw.</p>
+	<p><img src="images/europe2.png" alt="European Tour" /></p>
+      <p>They start planning the trip, when they realize that they could save a lot of money, if they ordered the cities to minimize the traveling cost. So they decided to try all possible combinations. The sat in front of the computer, visited they favorite traveling site, and started typing. 53 hours and several liters of coffee later, they realized it was a little bit more complicated than what they expected. They called their drummer (who was on vacations) and explained the problem to him. Fortunately, their drummer had a Master in Computer Science degree.</p>
+	<p><em><strong>Drummer</strong> – Boys, if you continue, you will have to try 1,307,674,368,000 combinations. You are in front of a NP Problem.</em>
+</p>
+<p><em><strong>Band member #1</strong> – Oh man! So it is going to take us all day!</em>
+</p>
+<p><em><strong>Band member #2</strong> – And maybe more, 'cause this internet connection sucks...</em>
+</p>
+<p><em><strong>Drummer</strong> – err... yes, it would take a while. But don't worry, I am sure we can get to a good solution using stochastic search algorithms applied to this problem..</em>
+</p>
+<p><em><strong>Band</strong> – (Silence)</em>
+</p>
+<p><em><strong>Drummer</strong> – .. that is, we are going to move from solution to solution in the space of candidate solutions, using techniques similar to what nature use for evolution, these are known as genetic algorithms.</em>
+</p>
+<p><em><strong>Band</strong> – (Silence)</em>
+</p>
+<p><em><strong>Drummer</strong> - ... What I mean is, we will pick some of them randomly, leave the ugly ones behind, and mate with the good looking ones...</em>
+</p>
+<p><em><strong>Band</strong> – YEAH! THAT'S THE MAN! LET'S DO IT!</em>
+</p>
+<p>I forgot to tell another restriction of this problem: This band is really bad (What did you expect? Their drummer is a computer geek!) so once they visited a city, they cannot go back there. 
+</p>
+    </section>
+
+
+<section id="Results">
+      <title>Results of using Genetic Algorithms to the The European Rock Tour Problem (or Travelling salesman problem)</title>
+	<p>The cost of 3 randomly selected tours:</p>
+	<ul>
+		<li>$17486.01 : Madrid Vienna Moscow Berlin Brussels Munich Milan Barcelona London Hamburg Warsaw Dublin Kiev Paris Rome</li>
+		<li>$20198.92 : London Rome Brussels Kiev Hamburg Warsaw Barcelona Paris Munich Dublin Vienna Moscow Madrid Milan Berlin</li>
+		<li>$17799.34 : Madrid Milan Kiev Vienna Warsaw London Barcelona Hamburg Paris Munich Dublin Berlin Moscow Rome Brussels</li>
+	</ul>
+	<p>3 tours obtained with an initial population of 800, and after 100 generations:</p>
+	<ul>
+		<li>$7611.99 : Moscow Kiev Warsaw Hamburg Berlin Munich Vienna Milan Rome Barcelona Madrid Paris Brussels London Dublin</li>
+		<li>$7596.74 : Moscow Kiev Warsaw Berlin Hamburg Munich Vienna Milan Rome Barcelona Madrid Paris Brussels London Dublin (See Image)</li>
+		<li>$7641.61 : Madrid Barcelona Rome Milan Paris Dublin London Brussels Hamburg Berlin Vienna Munich Warsaw Kiev Moscow</li>
+	</ul>
+	<p><img src="images/europe3.png" alt="Best tour result using Genetic Algorithms in ruby" /></p>
+	<p>The GeneticSearch class is an generic class to try to solve any kind of problem using genetic algorithms. If you
+want to model another type of problem, you will have to modify the Chromosome class, defining its fitness, mutate, and reproduce functions.</p>
+    </section>
+
+<section id="chromosome-impl">
+      <title>Implementation of Chromosome class for the Travelling salesman problem</title>
+	<p>Although the GeneticSearch class is an generic class to try to solve any kind of problem using genetic algorithms, the Chromosome class is problem specific.</p>
+	<section id="chromosome-impl-data">
+      		<title>Data representation</title>
+		<p>Each chromosome must represent a posible solution for the problem. This class conatins an array
+		with the list of visited nodes (cities of the tour). The size of the tour is obtained automatically from the traveling costs matrix. You have to assign the costs matrix BEFORE you run the genetic search. The following costs matrix could be used to solve the problem with only 3 cities:</p>
+<source>
+<![CDATA[
+data_set = [	[ 0, 10, 5],
+		[ 6,  0, 4],
+		[25,  4, 0]
+	]
+GeneticAlgorithm::Chromosome.set_cost_matrix(data_set)
+]]>
+</source>
+    	</section>
+	<section id="chromosome-impl-fitness">
+      		<title>Fitness function</title>
+		<p>The fitness function quantifies the optimality of a solution (that is, a chromosome) in a genetic algorithm so that that particular chromosome may be ranked against all the other chromosomes.
+Optimal chromosomes, or at least chromosomes which are more optimal, are allowed to breed and mix their datasets by any of several techniques, producing a new generation that will (hopefully) be even better.</p>
+		<p>The fitness function will return the complete tour cost represented by the chromosome, multiplied by -1.
+For example:</p>
+
+<source>
+<![CDATA[
+data_set = [	[ 0, 10, 5],
+		[ 6,  0, 4],
+		[25,  4, 0]
+	]
+GeneticAlgorithm::Chromosome.set_cost_matrix(data_set)
+chromosome = GeneticAlgorithm::Chromosome.new([0, 2, 1])
+chromosome.fitness
+	# => -9
+]]>
+</source>
+<p>That is: From 0 to 2 costs 5. From 2 to 1 costs 4. Total cost is 9.</p>
+    	</section>
+	<section id="chromosome-impl-reproduce">
+      		<title>Reproduce function</title>
+		<p>Reproduction is used to vary the programming of a chromosome or chromosomes from one generation to the next. There are several ways to combine two chromosomes: One-point crossover, Two-point crossover, "Cut and splice", edge recombination, and more. The method is usually dependant of the problem domain. In this case, we have implemented edge recombination, wich is the most used reproduction algorithm for the Travelling salesman problem. The edge recombination operator (ERO) is an operator that creates a path that is similar to a set of existing paths (parents) by looking at the edges rather than the vertices.</p>
+<p><img src="images/ero.gif" alt="Edge recombination" /></p>
+<p>The previous image was taken from the wikipedia, so hail to the author: Koala man (not me).</p>
+    	</section>
+	<section id="chromosome-impl-mutation">
+      		<title>Mutation function</title>
+		<p>Mutation funtion will be called fro every member of the population, on each generations. But you do not want to mutate your chromosomes every time, specialy if the are very fit. This is how it is currently implemented: With a probabilty of changing inversely proportional to its fitness, we swap 2 consecutive random nodes.</p>
+<source>
+<![CDATA[
+    def self.mutate(chromosome)
+      if chromosome.normalized_fitness && rand < ((1 - chromosome.normalized_fitness) * 0.3)
+        data = chromosome.data
+        index = rand(data.length-1)
+        data[index], data[index+1] = data[index+1], data[index]
+        chromosome.data = data
+        @fitness = nil
+      end
+    end
+]]>
+</source>
+    	</section>
+	<section id="chromosome-impl-seed">
+      		<title>Seed function</title>
+		<p>Initializes an individual solution (chromosome) for the initial population. The built in seed function generates a chromosome randomly, but you can use some problem domain knowledge, to generate better initial solutions (although this not always deliver better results, it improves convergency times).</p>
+<source>
+<![CDATA[
+    def self.seed
+      data_size = @@costs[0].length
+      available = []
+      0.upto(data_size-1) { |n| available << n }
+      seed = []
+      while available.length > 0 do 
+        index = rand(available.length)
+        seed << available.delete_at(index)
+      end
+      return Chromosome.new(seed)
+    end
+]]>
+</source>
+    	</section>
+    </section>
+
+<section id="search-impl">
+      <title>Implementation of GeneticSearch</title>
+	<p>The GeneticSearch class is an generic class to try to solve any kind of problem using genetic algorithms. If you
+want to model another type of problem, you will have to modify the Chromosome class, defining its fitness, mutate, and reproduce functions.</p>
+
+<section id="search-impl-init">
+
+      <title>Initialize the search</title>
+	<p>You have to provide two parameters during instantiation: The initial population size, and the how many generations produce. Large numbers will usually converge to better results, while small numbers will have better performance.</p>
+<source>
+<![CDATA[
+search = GeneticAlgorithm::GeneticSearch.new(10, 20)
+result = search.run
+]]>
+</source>
+    </section>
+<section id="search-impl-run">
+      <title>Run method</title>
+	<p>Once you initialize an instance of GeneticSearch class, you can perform the search executing the run method. 
+This method will:</p>
+	<ol>
+		<li>Choose initial population</li>
+		<li>Evaluate the fitness of each individual in the population</li>
+		<li>Repeat as many times as generations we allow
+			<ol>
+				<li>Select randomly the best-ranking individuals to reproduce</li>
+				<li>Breed new generation through crossover and mutation (genetic operations) and give birth to offspring</li>
+				<li>Evaluate the individual fitnesses of the offspring</li>
+				<li>Replace worst ranked part of population with offspring</li>
+			</ol>
+		</li>
+	</ol>
+    </section>
+
+	<section id="search-impl-selection">
+      		<title>Selection</title>
+	<p>Selection is the stage of a genetic algorithm in which individual genomes are chosen from a population for later breeding. There are several generic selection algorithms, such as tournament selection and roulette wheel selection. We implemented the latest.</p>
+<ol>
+<li>The fitness function is evaluated for each individual, providing fitness values</li>
+<li>The population is sorted by descending fitness values.</li>
+<li>The fitness values ar then normalized. (Highest fitness gets 1, lowest fitness gets 0). The normalized value is stored in the "normalized_fitness" attribute of the chromosomes.</li>
+<li> A random number R is chosen. R is between 0 and the accumulated normalized value (all the normalized fitness values added togheter).</li>
+<li>The selected individual is the first one whose accumulated normalized value (its is normalized value plus the normalized values of the chromosomes prior it) greater than R.</li>
+<li>We repeat steps 4 and 5, 2/3 times the population size.</li>
+</ol>
+<p><img src="images/fitness.png" alt="Edge recombination" /></p>
+<p>The previous image was taken from the wikipedia, so hail to the author: Simon Hatthon.</p>
+</section>
+
+
+<section id="search-impl-reproduction">
+      		<title>Reproduction</title>
+	<p>The reproduction function combines each pair of selected chromosomes using the method Chromosome.reproduce.</p>
+<p>The reproduction will also call the Chromosome.mutate method with each member of the population. You should implement Chromosome.mutate to only change (mutate) randomly. E.g. You could effectivly change the chromosome only if: </p>
+<source>
+<![CDATA[
+rand < ((1 - chromosome.normalized_fitness) * 0.4)
+]]>
+</source>
+</section>
+
+
+    </section>
+
+
+<section id="example-run">
+      <title>How to run the example</title>
+	<p>You can run the example with "ruby genetic_algorithm_example.rb". The genetic_algorithm_example.rb file
+contains:</p>
+<source>
+<![CDATA[
+require File.dirname(__FILE__) + '/../../lib/genetic_algorithm/genetic_algorithm'
+require 'csv'
+
+# Load data from data_set.csv
+data_set = []
+CSV::Reader.parse(File.open("#{File.dirname(__FILE__)}/travel_cost.csv", 'r')) do |row|
+  data_set << row
+end
+data_labels = data_set.shift
+data_set.collect! do |column|
+  column.collect { |element| element.to_f}
+end
+
+GeneticAlgorithm::Chromosome.set_cost_matrix(data_set)
+
+puts "Beginning genetic search, please wait... "
+search = GeneticAlgorithm::GeneticSearch.new(800, 100)
+result = search.run
+puts "Result cost: #{result.fitness}"
+puts "Result tour: "
+result.data.each { |c| print " #{data_labels[c]}"}
+]]>
+</source>
+
+    </section>
+
+<section id="more-genetic-run">
+      <title>More about Genetic Algorithms and the Travelling salesman problem</title>
+	<p><a href="http://en.wikipedia.org/wiki/Traveling_salesman_problem" title="Link to Wikipedia">Travelling salesman problem at Wikipedia</a></p>
+	<p><a href="http://en.wikipedia.org/wiki/Genetic_algorithm" title="Link to Wikipedia">Genetic Algorithms at Wikipedia</a></p>
+    </section>
+  </body>
+</document>

data/site/src/documentation/content/xdocs/index.xml

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Artificial Intelligence for Ruby :: ai4r</title>
+  </header>
+  <body>
+    <section id="Introduction">
+      <title>Introduction</title>
+      <p>
+        This project aims to produce ruby 
+	implementations of algorithms covering several Artificial 
+	intelligence fields, including:
+      </p>
+	<ul>
+		<li><a href="geneticAlgorithms.html">Genetic algorithms</a></li>
+		<li><a href="machineLearning.html">Machine Learning (ID3, Decision Trees)</a></li>
+		<li><a href="neuralNetworks.html">Neural networks (Backpropagation networks)</a></li>
+	</ul>
+    </section>
+
+    <section id="howtoinstall">
+      <title>How to install</title>
+      <p>1. Install the gem:</p>
+      <source>gem install http://rubyforge.org/frs/download.php/32923/ai4r-1.0.gem</source>
+      <p>Include require statements in your code:</p>
+      <source>
+require "rubygems"
+require "decision_tree/id3"
+require "neural_network/backpropagation"
+require "genetic_algorithm/genetic_algorithm"
+      </source>
+
+    </section>
+
+    <section id="ContactMe">
+      <title>Contact me</title>
+      <p>
+        If you have some constructive comments about this project, please do send those to me: 
+        Sergio Fierens, email address:	<img src="images/my_email.png" alt="(sergio (dot) fierens (at) gmail (dot) com)" 
+	title="Sergio Fierens contact email" />
+      </p>
+    </section>
+
+    <section id="warranty">
+      <title>Disclaimer Note</title>
+      <p>
+        This software is 
+	provided "as is" and without any 
+	express or implied warranties, including, without limitation, 
+	the implied warranties of merchantibility and fitness for a 
+	particular purpose.
+      </p>
+    </section>
+  </body>
+</document>