diff --git a/README.md b/README.md index 8fdca23..59a7fc1 100644 --- a/README.md +++ b/README.md @@ -10,23 +10,29 @@ If you are working in a Clojure IDE with an integrated REPL, the first thing you may want to do is to open `src/propeller/session.cljc` and evaluate the namespace declaration and the commented-out expressions therein. These demonstrate core components of Propeller including -complete genetic programming runs. +complete genetic programming runs. When conducting complete genetic +programming runs this way (using `gp/gp`), depending on your IDE you +may need to explicitly open and load the problem file before evaluating +the calls to `require` and `gp/gp`. To run Propeller from the command line, on a genetic programming problem that is defined within this project, you will probably want to use either the Clojure [CLI tools](https://clojure.org/guides/deps_and_cli) or -[leiningen](https://leiningen.org). +[leiningen](https://leiningen.org). In the examples below, the leiningen +and CLI commands are identical except that the former begin with +`lein run -m`, while the latter begin with `clj -M -m`. -The instructions below are written for leiningen. If you are using -the CLI tools instead, then replace `lein run -m` in each command -with `clj -M -m`. - -If you are using leiningen, then you can start a run with the command +To start a run use `clj -M -m ` or `lein run -m `, replacing `` with the actual namespace that you will find at the top of the problem file. For example, you can run the simple-regression genetic programming problem with: +``` +clj -M -m propeller.problems.simple-regression +``` +or + ``` lein run -m propeller.problems.simple-regression ``` @@ -35,6 +41,11 @@ Additional command-line arguments may be provided to override the default key/value pairs specified in the problem file, for example: +``` +clj -M -m propeller.problems.simple-regression :population-size 100 +``` + +or ``` lein run -m propeller.problems.simple-regression :population-size 100 @@ -44,6 +55,13 @@ 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 `outfile` in this example): + +``` +clj -M -m propeller.problems.simple-regression | tee outfile +``` + +or + ``` lein run -m propeller.problems.simple-regression | tee outfile ``` @@ -55,10 +73,24 @@ quotes, like in this example that provides a non-default value for the `:variation` argument, which is a clojure map containing curly brackets that may confuse your shell: +``` +clj -M -m propeller.problems.simple-regression :variation "{:umad 1.0}" +``` + +or + ``` lein run -m propeller.problems.simple-regression :variation "{:umad 1.0}" ``` +For many genetic operator hyperparameters, collections may be provided in place of single values. When this is done, a random element of the collection will be chosen (with each being equally likely) each time the operator is used. When specied at the command line, these collections will also have to be quoted, for example with `:umad-rate "[0.01 0.05 0.1]"` to mean that UMAD rates of 0.01, 0.05, and 0.1 can be used. + +By default, Propeller will conduct many processes concurrently on multiple +cores using threads. If you want to disable this behavior (for example, during +debugging) then provide the argument `:single-thread-mode` with the value `true`. +Threads are not available in Javascript, so no processes are run concurrnetly +when Propeller is run in Clojurescript. + ## CLJS Usage diff --git a/deps.edn b/deps.edn index f0bb8e3..7a271fb 100644 --- a/deps.edn +++ b/deps.edn @@ -3,7 +3,7 @@ {org.clojure/clojure #:mvn{:version "1.10.0"}, org.clojure/clojurescript #:mvn{:version "1.9.946"}, org.clojure/test.check #:mvn{:version "1.1.0"}, - net.clojars.schneau/psb2 #:mvn{:version "1.1.0"}}, + net.clojars.schneau/psb2 #:mvn{:version "1.1.1"}}, :mvn/repos {} :codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}} :exec-fn codox.main/generate-docs diff --git a/docs/A_Guide_To_Propeller.html b/docs/A_Guide_To_Propeller.html index fd23bc8..b79e2b8 100644 --- a/docs/A_Guide_To_Propeller.html +++ b/docs/A_Guide_To_Propeller.html @@ -1,6 +1,6 @@ -A Guide to Propeller

Project

Topics

Namespaces

A Guide to Propeller

+A Guide to Propeller

Project

Topics

Namespaces

A Guide to Propeller

Propeller is an implementation of the Push programming language and the PushGP genetic programming system in Clojure.

For more information on Push and PushGP see http://pushlanguage.org.

Overview

@@ -31,7 +31,7 @@

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.

Installation

If you have installed leiningen, 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 lein run -m <namespace>, replacing <namespace> with the actual namespace that you will find at the top of the problem file.

-

If you have installed Clojure, you can run Propeller on a genetic programming problem with the command clj --main <namespace>, replacing <namespace> with the actual namespace that you will find at the top of the problem file. The examples below use leiningen, but you can replace lein run -m with clj --main to run the same problem.

+

If you have installed Clojure, you can run Propeller on a genetic programming problem with the command clj -M -m <namespace>, replacing <namespace> with the actual namespace that you will find at the top of the problem file. The examples below use leiningen, but you can replace lein run -m with clj -M -m to run the same problem.

A specific example is provided later below.

How do I run Propeller on a problem?

To run Propeller on a problem, you want to call the -main function in the problem file using leiningen. The -main function will create a map of arguments from the input and run the main genetic programming loop.

diff --git a/docs/Adding_Genetic_Operators.html b/docs/Adding_Genetic_Operators.html index 5d572c1..723490c 100644 --- a/docs/Adding_Genetic_Operators.html +++ b/docs/Adding_Genetic_Operators.html @@ -1,6 +1,6 @@ -Adding Genetic Operators

Project

Topics

Namespaces

Adding Genetic Operators

+Adding Genetic Operators

Project

Topics

Namespaces

Adding Genetic Operators

In addition to the already-included genetic operators, you can add your own!

Variation Genetic Operators

    diff --git a/docs/Adding_Problem.html b/docs/Adding_Problem.html index ac75452..47b490d 100644 --- a/docs/Adding_Problem.html +++ b/docs/Adding_Problem.html @@ -1,6 +1,6 @@ -Adding a Problem

    Project

    Topics

    Namespaces

    Adding a Problem

    +Adding a Problem

    Project

    Topics

    Namespaces

    Adding a Problem

    In general, a problem file has 3 components: train-and-test-data, instructions, error-function, and -main.

    1. To add a new problem, you need training and test data. For Problem Synthesis Benchmark Problems (PSB2), you can fetch datasets using psb2.core/fetch-examples.
      2. @@ -110,8 +110,7 @@ :umad-rate 0.1 :variation {:umad 1.0 :crossover 0.0} :elitism false} - (apply hash-map (map #(if (string? %) (read-string %) %) args)))) - (#?(:clj shutdown-agents))) + (apply hash-map (map #(if (string? %) (read-string %) %) args)))))
    \ No newline at end of file diff --git a/docs/Adding_Selection_Method.html b/docs/Adding_Selection_Method.html index d380eed..2af2135 100644 --- a/docs/Adding_Selection_Method.html +++ b/docs/Adding_Selection_Method.html @@ -1,6 +1,6 @@ -Adding a Selection Method

    Project

    Topics

    Namespaces

    Adding a Selection Method

    +Adding a Selection Method

    Project

    Topics

    Namespaces

    Adding a Selection Method

    1. Define a selection method function in propeller.selection that selects an individual from the population
    2. Add the selection method in propeller.selection/select-parent under the case call:
      3. diff --git a/docs/Additional_Instructions.html b/docs/Additional_Instructions.html index c2fe3b9..3de1ab7 100644 --- a/docs/Additional_Instructions.html +++ b/docs/Additional_Instructions.html @@ -1,9 +1,10 @@ -Additional Instructions

      Project

      Topics

      Namespaces

      Table of contents

      +Additional Instructions

      Project

      Topics

      Namespaces

      Table of contents