132 lines
27 KiB
HTML
132 lines
27 KiB
HTML
<!DOCTYPE html PUBLIC ""
|
||
"">
|
||
<html><head><meta charset="UTF-8" /><title>A Guide to Propeller</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Propeller</span> <span class="project-version">0.3.2</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 current"><a href="A_Guide_To_Propeller.html"><div class="inner"><span>A Guide to Propeller</span></div></a></li><li class="depth-1 "><a href="Adding_Genetic_Operators.html"><div class="inner"><span>Adding Genetic Operators</span></div></a></li><li class="depth-1 "><a href="Adding_Problem.html"><div class="inner"><span>Adding a Problem</span></div></a></li><li class="depth-1 "><a href="Adding_Selection_Method.html"><div class="inner"><span>Adding a Selection Method</span></div></a></li><li class="depth-1 "><a href="Additional_Instructions.html"><div class="inner"><span>Additional Instructions</span></div></a></li><li class="depth-1 "><a href="Generating_Documentation.html"><div class="inner"><span>Generating Documentation for Propeller</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>propeller</span></div></div></li><li class="depth-2 branch"><a href="propeller.genome.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>genome</span></div></a></li><li class="depth-2 branch"><a href="propeller.gp.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>gp</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>problems</span></div></div></li><li class="depth-3"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>PSB1</span></div></div></li><li class="depth-4 branch"><a href="propeller.problems.PSB1.count-odds.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>count-odds</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB1.grade.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>grade</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB1.scrabble-score.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>scrabble-score</span></div></a></li><li class="depth-4"><a href="propeller.problems.PSB1.small-or-large.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>small-or-large</span></div></a></li><li class="depth-3"><div class="no-link"><div class="inner"><span class="tree" style="top: -145px;"><span class="top" style="height: 154px;"></span><span class="bottom"></span></span><span>PSB2</span></div></div></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.basement.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>basement</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.bouncing-balls.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>bouncing-balls</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.bowling.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>bowling</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.camel-case.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>camel-case</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.dice-game.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>dice-game</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.fizz-buzz.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>fizz-buzz</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.fuel-cost.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>fuel-cost</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.gcd.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>gcd</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.luhn.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>luhn</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.middle-character.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>middle-character</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.paired-digits.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>paired-digits</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.shopping-list.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>shopping-list</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.snow-day.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>snow-day</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.solve-boolean.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>solve-boolean</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.spin-words.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>spin-words</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.square-digits.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>square-digits</span></div></a></li><li class="depth-4 branch"><a href="propeller.problems.PSB2.substitution-cipher.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>substitution-cipher</span></div></a></li><li class="depth-4"><a href="propeller.problems.PSB2.twitter.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>twitter</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.complex-regression.html"><div class="inner"><span class="tree" style="top: -579px;"><span class="top" style="height: 588px;"></span><span class="bottom"></span></span><span>complex-regression</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.float-regression.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>float-regression</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.integer-regression.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>integer-regression</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.simple-classification.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>simple-classification</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.simple-regression.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>simple-regression</span></div></a></li><li class="depth-3"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>software</span></div></div></li><li class="depth-4 branch"><a href="propeller.problems.software.number-io.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>number-io</span></div></a></li><li class="depth-4"><a href="propeller.problems.software.smallest.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>smallest</span></div></a></li><li class="depth-3 branch"><a href="propeller.problems.string-classification.html"><div class="inner"><span class="tree" style="top: -83px;"><span class="top" style="height: 92px;"></span><span class="bottom"></span></span><span>string-classification</span></div></a></li><li class="depth-3"><a href="propeller.problems.valiant.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>valiant</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree" style="top: -1075px;"><span class="top" style="height: 1084px;"></span><span class="bottom"></span></span><span>push</span></div></div></li><li class="depth-3"><a href="propeller.push.instructions.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>instructions</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.bool.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>bool</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.character.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>character</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.code.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>code</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.input-output.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>input-output</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.numeric.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>numeric</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.polymorphic.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>polymorphic</span></div></a></li><li class="depth-4 branch"><a href="propeller.push.instructions.string.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>string</span></div></a></li><li class="depth-4"><a href="propeller.push.instructions.vector.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>vector</span></div></a></li><li class="depth-3 branch"><a href="propeller.push.interpreter.html"><div class="inner"><span class="tree" style="top: -269px;"><span class="top" style="height: 278px;"></span><span class="bottom"></span></span><span>interpreter</span></div></a></li><li class="depth-3 branch"><a href="propeller.push.limits.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>limits</span></div></a></li><li class="depth-3"><a href="propeller.push.state.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>state</span></div></a></li><li class="depth-2 branch"><a href="propeller.selection.html"><div class="inner"><span class="tree" style="top: -393px;"><span class="top" style="height: 402px;"></span><span class="bottom"></span></span><span>selection</span></div></a></li><li class="depth-2 branch"><a href="propeller.simplification.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>simplification</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>tools</span></div></div></li><li class="depth-3 branch"><a href="propeller.tools.calculus.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>calculus</span></div></a></li><li class="depth-3 branch"><a href="propeller.tools.character.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>character</span></div></a></li><li class="depth-3 branch"><a href="propeller.tools.distributions.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>distributions</span></div></a></li><li class="depth-3 branch"><a href="propeller.tools.math.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>math</span></div></a></li><li class="depth-3"><a href="propeller.tools.metrics.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>metrics</span></div></a></li><li class="depth-2 branch"><a href="propeller.utils.html"><div class="inner"><span class="tree" style="top: -176px;"><span class="top" style="height: 185px;"></span><span class="bottom"></span></span><span>utils</span></div></a></li><li class="depth-2"><a href="propeller.variation.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>variation</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#a-guide-to-propeller" id="a-guide-to-propeller"></a>A Guide to Propeller</h1>
|
||
<p><strong>Propeller</strong> is an implementation of the Push programming language and the PushGP genetic programming system in Clojure.</p>
|
||
<p>For more information on Push and PushGP see <a href="http://pushlanguage.org">http://pushlanguage.org</a>.</p>
|
||
<h2><a href="#overview" id="overview"></a>Overview</h2>
|
||
<p><strong>Propeller</strong> is a Push-based genetic programming system in Clojure.</p>
|
||
<!-- TOC -->
|
||
<ul>
|
||
<li><a href="#a-guide-to-propeller">A Guide to Propeller</a></li>
|
||
<li><a href="#overview">Overview</a>
|
||
<ul>
|
||
<li><a href="#what-can-you-do-with-propeller">What can you do with Propeller?</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#installation">Installation</a></li>
|
||
<li><a href="#how-do-i-run-propeller-on-a-problem">How do I run Propeller on a problem?</a>
|
||
<ul>
|
||
<li><a href="#an-example">An Example</a></li>
|
||
<li><a href="#can-you-use-a-repl">Can you use a REPL?</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorials">Tutorials</a></li>
|
||
<li><a href="#contributing">Contributing</a></li>
|
||
<li><a href="#license">License</a></li>
|
||
<li><a href="#citation">Citation</a></li>
|
||
<li><a href="#contact">Contact</a></li>
|
||
</ul>
|
||
<!-- TOC -->
|
||
<h3><a href="#what-can-you-do-with-propeller" id="what-can-you-do-with-propeller"></a>What can you do with Propeller?</h3>
|
||
<p>You can evolve a Push program to solve a problem. You can also use the Push interpreter to evaluate Push programs in other projects, for example in agent-based evolutionary simulations in which agents are controlled by evolving Push programs.</p>
|
||
<h2><a href="#installation" id="installation"></a>Installation</h2>
|
||
<p>If you have installed <a href="https://leiningen.org">leiningen</a>, which is a tool for running Clojure programs, then you can run Propeller on a genetic programming problem that is defined within this project from the command line with the command <code>lein run -m <namespace></code>, replacing <code><namespace></code> with the actual namespace that you will find at the top of the problem file.</p>
|
||
<p>If you have installed <a href="https://clojure.org/guides/install_clojure#java">Clojure</a>, you can run Propeller on a genetic programming problem with the command <code>clj -M -m <namespace></code>, replacing <code><namespace></code> with the actual namespace that you will find at the top of the problem file. The examples below use leiningen, but you can replace <code>lein run -m</code> with <code>clj -M -m</code> to run the same problem.</p>
|
||
<p>A specific example is provided later below.</p>
|
||
<h2><a href="#how-do-i-run-propeller-on-a-problem" id="how-do-i-run-propeller-on-a-problem"></a>How do I run Propeller on a problem?</h2>
|
||
<p>To run Propeller on a problem, you want to call the <code>-main</code> function in the problem file using leiningen. The <code>-main</code> function will create a map of arguments from the input and run the main genetic programming loop.</p>
|
||
<p>Below is the general format to run a problem through the command-line:</p>
|
||
<pre><code>lein run -m [namespace of the problem file you want to test]
|
||
</code></pre>
|
||
<p>Additional command-line arguments may be provided to override the default key/value pairs specified in the problem file,</p>
|
||
<pre><code>lein run -m [namespace of the problem file you want to test] [key and value] [key and value]...
|
||
</code></pre>
|
||
<p>The possible keys come from the table below:</p>
|
||
<table>
|
||
<thead>
|
||
<tr><th> Key </th><th> Description </th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td> <code>:instructions</code> </td><td> List of possible Push instructions used to create a plushy </td></tr>
|
||
<tr><td> <code>:error-function</code> </td><td> The error function used to evaluate individuals, specified in the given problem’s namespace </td></tr>
|
||
<tr><td> <code>:training-data</code> </td><td> Map of inputs and desired outputs used to evaluate individuals of the form: {:input1 first-input :input2 second-input … :output1 first-output …} </td></tr>
|
||
<tr><td> <code>:testing-data</code> </td><td> Map of inputs and desired outputs not in the training-data to test generalizability of a program that fits the <code>training-data</code>. The map is of the form: {:input1 first-input :input2 second-input … :output1 first-output …} </td></tr>
|
||
<tr><td> <code>:max-generations</code> </td><td> Maximum number of generations </td></tr>
|
||
<tr><td> <code>:population-size</code> </td><td> Size of population in a generation </td></tr>
|
||
<tr><td> <code>:max-initial-plushy-size</code> </td><td> Maximum number of Push instructions in the initial plushy </td></tr>
|
||
<tr><td> <code>:step-limit</code> </td><td> The maximum number of steps that a Push program will be executed by <code>interpret-program</code> </td></tr>
|
||
<tr><td> <code>:parent-selection</code> </td><td> Function from <code>propeller.selection</code> that determines method of parent selection method. Propeller includes <code>:tournament-selection</code>, <code>:lexicase-selection</code>, and <code>:epsilon-lexicase-selection</code>. </td></tr>
|
||
<tr><td> <code>:tournament-size</code> </td><td> If using a tournament selection method, the number of individuals in each tournaments used to determine parents </td></tr>
|
||
<tr><td> <code>:umad-rate</code> </td><td> Rate (decimal between 0 and 1) of uniform mutation by addition and deletion (UMAD) genetic operator </td></tr>
|
||
<tr><td> <code>:variation</code> </td><td> Map with genetic operators as keys and probabilities as values. For example, {:umad 0.3 :crossover 0.7}. This would mean that when the system needs to generate a child, it will use UMAD 30% of the time and crossover 70% of the time. The probabilities should sum to 1. </td></tr>
|
||
<tr><td> <code>:elitism</code> </td><td> When true, will cause the individual with the lowest error in the population to survive, without variation, into the next generation. </td></tr>
|
||
</tbody>
|
||
</table>
|
||
<p>When you run a problem, you will get a report each generation with the following information:</p>
|
||
<pre><code> :generation
|
||
:best-plushy
|
||
:best-program
|
||
:best-total-error
|
||
:best-errors
|
||
:best-behaviors
|
||
:genotypic-diversity
|
||
:behavioral-diversity
|
||
:average-genome-length
|
||
:average-total-error
|
||
|
||
</code></pre>
|
||
<h3><a href="#an-example" id="an-example"></a>An Example</h3>
|
||
<p>For example, you can run the simple-regression genetic programming problem with:</p>
|
||
<pre><code>lein run -m propeller.problems.simple-regression
|
||
</code></pre>
|
||
<p>This will run simple-regression with the default set of arguments in the <code>simple-regression</code> problem file.</p>
|
||
<pre><code>{:instructions instructions
|
||
:error-function error-function
|
||
:training-data (:train train-and-test-data)
|
||
:testing-data (:test train-and-test-data)
|
||
:max-generations 500
|
||
:population-size 500
|
||
:max-initial-plushy-size 100
|
||
:step-limit 200
|
||
:parent-selection :lexicase
|
||
:tournament-size 5
|
||
:umad-rate 0.1
|
||
:variation {:umad 0.5 :crossover 0.5}
|
||
:elitism false}
|
||
</code></pre>
|
||
<p>You can override the default key/value pairs with additional arguments. For example:</p>
|
||
<pre><code>lein run -m propeller.problems.simple-regression :population-size 100
|
||
</code></pre>
|
||
<p>On Unix operating systems, including MacOS, you can use something like the following to send output both to the terminal and to a text file (called <code>outfile</code> in this example):</p>
|
||
<pre><code>lein run -m propeller.problems.simple-regression | tee outfile
|
||
</code></pre>
|
||
<p>If you want to provide command line arguments that include characters that may be interpreted by your command line shell before they get to Clojure, then enclose those in double quotes, like in this example that provides a non-default value for the <code>:variation</code> argument, which is a clojure map containing curly brackets that may confuse your shell:</p>
|
||
<pre><code>lein run -m propeller.problems.simple-regression :variation "{:umad 1.0}"
|
||
</code></pre>
|
||
<h3><a href="#can-you-use-a-repl" id="can-you-use-a-repl"></a>Can you use a REPL?</h3>
|
||
<p>Yes!</p>
|
||
<p>To run a genetic programming problem from a REPL, start your REPL for the project (e.g. with <code>lein repl</code> at the command line when in the project directory, or through your IDE) and then do something like the following (which in this case runs the simple-regression problem with <code>:population-size</code> 100):</p>
|
||
<pre><code>(require 'propeller.problems.simple-regression)
|
||
(in-ns 'propeller.problems.simple-regression)
|
||
(-main :population-size 100 :variation {:umad 1.0})
|
||
</code></pre>
|
||
<p>If you want to run the problem with the default parameters, then you should call <code>-main</code> without arguments, as `(-main).</p>
|
||
<h2><a href="#tutorials" id="tutorials"></a>Tutorials</h2>
|
||
<ul>
|
||
<li><a href="Adding_Genetic_Operators.html">Adding genetic operators</a></li>
|
||
<li><a href="Adding_Selection_Method.html">Adding selection methods</a></li>
|
||
<li><a href="Adding_Problem.html">Adding a new problem</a></li>
|
||
<li><a href="Generating_Documentation.html">Generating Documentation</a></li>
|
||
</ul>
|
||
<h2><a href="#contributing" id="contributing"></a>Contributing</h2>
|
||
<p>You can report a bug on the <a href="https://github.com/lspector/propeller/issues">GitHub issues page</a>.</p>
|
||
<p>The best way to contribute to Propeller is to fork the <a href="https://github.com/lspector/propeller">main GitHub repository</a> and submit a pull request.</p>
|
||
<p>Propeller provides a way to automatically <a href="Generating_Documentation.html">generate documentation</a> for any contributions you might make.</p>
|
||
<h2><a href="#license" id="license"></a>License</h2>
|
||
<p><strong>Eclipse Public License 2.0</strong></p>
|
||
<p>This commercially-friendly copyleft license provides the ability to commercially license binaries; a modern royalty-free patent license grant; and the ability for linked works to use other licenses, including commercial ones.</p>
|
||
<h2><a href="#citation" id="citation"></a>Citation</h2>
|
||
<p>We are in the process of creating a DOI, but in the meantime, we ask that you cite the <a href="https://github.com/lspector/propeller">link to the repository</a> if you use Propeller.</p>
|
||
<h2><a href="#contact" id="contact"></a>Contact</h2>
|
||
<p>To discuss Propeller, Push, and PushGP, you can join the <a href="https://discourse.pushlanguage.org/">Push-Language Discourse</a>.</p>
|
||
</div></div></div></body></html> |