updated software and push instructions

project.clj

@@ -13,5 +13,5 @@
   :jvm-opts ^:replace []
   :plugins [[lein-codox "0.10.8"]]
   :codox {:output-path "docs"
-          :metadata {:doc/format :markdown}
+          :metadata {:doc "FIXME: write docs" :doc/format :markdown}
           :doc-paths ["src/docs_src"]})

src/propeller/problems/software/fizz_buzz.cljc

@@ -1,4 +1,4 @@
-(ns propeller.problems.software.fizz-buzz
+(ns ^:no-doc propeller.problems.software.fizz-buzz
   (:require [psb2.core :as psb2]))
 
 ;; @todo This namespace is never used an it isn't a complete problem. Furthermore fizz-buzz exists in the PSB2 folder.

src/propeller/problems/software/number_io.cljc

@@ -1,4 +1,10 @@
 (ns propeller.problems.software.number-io
+  "Number IO from iJava (http://ijava.cs.umass.edu/)
+
+     This problem file defines the following problem:
+There are two inputs, a float and an int. The program must read them in, find
+their sum as a float, and print the result as a float.
+     "
   (:require [propeller.genome :as genome]
             [propeller.push.interpreter :as interpreter]
             [propeller.push.state :as state]
@@ -34,12 +40,13 @@
 ;; =============================================================================
 
 ;; Random float between -100.0 and 100.0
-(defn random-float [] (- (* (rand) 200) 100.0))
+(defn random-float "Random float between -100.0 and 100.0" [] (- (* (rand) 200) 100.0))
 
 ; Random integer between -100 and 100
-(defn random-int [] (- (rand-int 201) 100))
+(defn random-int "Random integer between -100 and 100" [] (- (rand-int 201) 100))
 
 (def instructions
+  "Stack-specific instructions, input instructions, close, and constants"
   (utils/not-lazy
     (concat
       ;; stack-specific instructions
@@ -50,6 +57,7 @@
       (list random-float random-int))))
 
 (def train-and-test-data
+  "Inputs are random integers and random floats and outputs are the sum as a float."
   (let [inputs (vec (repeatedly 1025 #(vector (random-int) (random-float))))
         outputs (mapv #(apply + %) inputs)
         train-set {:inputs  (take 25 inputs)
@@ -60,6 +68,10 @@
      :test  test-set}))
 
 (defn error-function
+  "Finds the behaviors and errors of an individual: Error is the absolute difference between
+  program output and the correct output.
+  The behavior is here defined as the final top item on
+  the PRINT stack."
   [argmap data individual]
   (let [program (genome/plushy->push (:plushy individual) argmap)
         inputs (:inputs data)

src/propeller/problems/software/smallest.cljc

@@ -1,4 +1,13 @@
 (ns propeller.problems.software.smallest
+  "SMALLEST PROBLEM from C. Le Goues et al.,
+  \"The ManyBugs and IntroClass Benchmarks\n
+   for Automated Repair of C Programs,\" in IEEE Transactions on Software\n
+    Engineering, vol. 41, no. 12, pp. 1236-1256, Dec. 1 2015.\n
+     doi: 10.1109/TSE.2015.2454513
+
+This problem file defines the following problem:
+takes as input four ints, computes the smallest, and prints to the screen the smallest input.
+```"
   (:require [propeller.genome :as genome]
             [propeller.push.interpreter :as interpreter]
             [propeller.push.state :as state]
@@ -12,20 +21,10 @@
 ;;
 ;; SMALLEST PROBLEM
 ;;
-;; This problem file defines the following problem:
-;; There are two inputs, a float and an int. The program must read them in, find
-;; their sum as a float, and print the result as a float.
-;;
 ;; Problem Source: C. Le Goues et al., "The ManyBugs and IntroClass Benchmarks
 ;; for Automated Repair of C Programs," in IEEE Transactions on Software
 ;; Engineering, vol. 41, no. 12, pp. 1236-1256, Dec. 1 2015.
 ;; doi: 10.1109/TSE.2015.2454513
-;;
-;; NOTE: input stack: in1 (int),
-;;                    in2 (int),
-;;                    in3 (int),
-;;                    in4 (int),
-;;       output stack: printed output
 ;; =============================================================================
 
 ;; =============================================================================
@@ -38,9 +37,10 @@
 ;; =============================================================================
 
 ; Random integer between -100 and 100
-(defn random-int [] (- (rand-int 201) 100))
+(defn random-int "Random integer between -100 and 100" [] (- (rand-int 201) 100))
 
 (def instructions
+  "Stack-specific instructions, input instructions, close, and constants"
   (utils/not-lazy
     (concat
       ;; stack-specific instructions
@@ -51,6 +51,7 @@
       (list random-int))))
 
 (def train-and-test-data
+  "Inputs are 4-tuples of random integers and the outputs are the minimum value of each tuple."
   (let [inputs (vec (repeatedly 1100 #(vector (random-int) (random-int)
                                               (random-int) (random-int))))
         outputs (mapv #(apply min %) inputs)
@@ -62,6 +63,10 @@
      :test  test-set}))
 
 (defn error-function
+  "Finds the behaviors and errors of an individual: Error is 0 if the value and
+  the program's selected behavior match, or 1 if they differ.
+  The behavior is here defined as the final top item on
+  the PRINT stack."
   [argmap data individual]
   (let [program (genome/plushy->push (:plushy individual) argmap)
         inputs (:inputs data)

src/propeller/problems/string_classification.cljc

@@ -13,7 +13,7 @@ Given a string, return true if it contains A, C, G, and T. Else return false."
 
 ;; Set of original propel instructions
 (def instructions
-  "stack-specific instructions, input instructions, close, and constants"
+  "Set of original propel instructions"
   (list :in1
         :integer_add
         :integer_subtract

src/propeller/problems/valiant.cljc

@@ -14,6 +14,8 @@
 (def num-test 200)
 
 (def train-and-test-data
+  "Inputs are `num-train` random boolean values and outputs are the
+  even parity of a subset of input variables."
   (let [input-indices (take num-inputs (shuffle (range num-vars)))
         rand-vars (fn [] (vec (repeatedly num-vars #(< (rand) 0.5))))
         even-parity? (fn [vars]
@@ -25,7 +27,13 @@
     {:train (map (fn [x] {:input1 x :output1 (vector (even-parity? x))}) train-inputs)
      :test (map (fn [x] {:input1 x :output1 (vector (even-parity? x))}) test-inputs)}))
 
+;even-parity? takes in a list of variables and returns true if the number of true values in the input variables,
+;as determined by the input-indices is even, and false otherwise.
+
 (def instructions
+  "A list of instructions which includes keyword strings
+  with the format \"in + i\" where i is a number from 0 to num-vars-1
+  concatenated with boolean and exec_if instructions and close."
   (vec (concat (for [i (range num-vars)] (keyword (str "in" i)))
                (take num-inputs
                      (cycle [:boolean_xor
@@ -37,6 +45,10 @@
                              ])))))
 
 (defn error-function
+  "Finds the behaviors and errors of an individual:
+  Error is 0 if the value and the program’s selected behavior
+  match, or 1 if they differ.
+  The behavior is here defined as the final top item on the BOOLEAN stack."
   [argmap data individual]
   (let [program (genome/plushy->push (:plushy individual) argmap)
         inputs (map (fn [x] (:input1 x)) data)

src/propeller/push/instructions/bool.cljc

@@ -1,4 +1,5 @@
 (ns propeller.push.instructions.bool
+  "BOOLEAN Instructions, created with `propeller.push.instructions/def-instruction`"
   (:require [propeller.push.instructions :refer [def-instruction
                                                  make-instruction]]))
 

src/propeller/push/instructions/character.cljc

@@ -1,5 +1,5 @@
 (ns propeller.push.instructions.character
-  "Push instructions for CHARs."
+  "CHAR Instructions, created with `propeller.push.instructions/def-instruction`"
   (:require [propeller.push.state :as state]
             [propeller.tools.character :as char]
             [propeller.push.instructions :refer [def-instruction

src/propeller/push/instructions/code.cljc

@@ -1,5 +1,5 @@
 (ns propeller.push.instructions.code
-  "Push instructions for code."
+  "CODE Instructions, created with `propeller.push.instructions/def-instruction`"
   (:require [propeller.utils :as utils]
             [propeller.push.state :as state]
             [propeller.push.instructions :refer [def-instruction

src/propeller/push/instructions/input_output.cljc

@@ -1,5 +1,5 @@
 (ns propeller.push.instructions.input-output
-  "Push instructions for input and output."
+  "INPUT and OUTPUT Instructions"
   (:require [propeller.push.state :as state]
             [propeller.push.instructions :refer [def-instruction
                                                  generate-instructions]]))
@@ -12,6 +12,9 @@
 ;; elements thus labeled from the :input map and pushing them onto the :exec
 ;; stack.
 (defn handle-input-instruction
+  "Allows Push to handle input instructions of the form :inN, e.g. :in2, taking
+  elements thus labeled from the :input map and pushing them onto the :exec
+  stack."
   [state instruction]
   (if (contains? (:input state) instruction)
     (let [input (instruction (:input state))]
@@ -33,6 +36,7 @@
       (state/push-to-stack popped-state :print (str current-output \newline)))))
 
 (def _print
+  "Instruction to print output."
   ^{:stacks [:print]
     :name "_print"}
   (fn [stack state]

src/propeller/push/instructions/numeric.cljc

@@ -1,4 +1,5 @@
 (ns propeller.push.instructions.numeric
+  "FLOAT and INTEGER Instructions (polymorphic)"
   (:require [propeller.tools.math :as math]
             [propeller.push.instructions :refer [def-instruction
                                                  generate-instructions
@@ -11,6 +12,8 @@
 ;; Pushes TRUE onto the BOOLEAN stack if the first item is greater than the second
 ;; item, and FALSE otherwise
 (def _gt
+  "Pushes TRUE onto the BOOLEAN stack if the first item is greater
+  than the second item, and FALSE otherwise"
   ^{:stacks #{:boolean}
     :name "_gt"}
   (fn [stack state]
@@ -19,6 +22,8 @@
 ;; Pushes TRUE onto the BOOLEAN stack if the second item is greater than or
 ;; equal to the top item, and FALSE otherwise
 (def _gte
+  "Pushes TRUE onto the BOOLEAN stack if the second item is greater than or
+  equal to the top item, and FALSE otherwise"
   ^{:stacks #{:boolean}
     :name "_gte"}
   (fn [stack state]
@@ -27,6 +32,8 @@
 ;; Pushes TRUE onto the BOOLEAN stack if the second item is less than the top
 ;; item, and FALSE otherwise
 (def _lt
+  "Pushes TRUE onto the BOOLEAN stack if the second item is less than the top
+  item, and FALSE otherwise"
   ^{:stacks #{:boolean}
     :name "_lt"}
   (fn [stack state]
@@ -35,6 +42,8 @@
 ;; Pushes TRUE onto the BOOLEAN stack if the second item is less than or equal
 ;; to the top item, and FALSE otherwise
 (def _lte
+  "Pushes TRUE onto the BOOLEAN stack if the second item is less than or equal
+  to the top item, and FALSE otherwise"
   ^{:stacks #{:boolean}
     :name "_lte"}
   (fn [stack state]
@@ -42,6 +51,7 @@
 
 ;; Pushes the sum of the top two items onto the same stack
 (def _add
+  "Pushes the sum of the top two items onto the same stack"
   ^{:stacks #{}
     :name "_add"}
   (fn [stack state]
@@ -51,6 +61,8 @@
 ;; Pushes the difference of the top two items (i.e. the second item minus the
 ;; top item) onto the same stack
 (def _subtract
+  "Pushes the difference of the top two items (i.e. the second item minus the
+  top item) onto the same stack"
   ^{:stacks #{}
     :name "_subtract"}
   (fn [stack state]
@@ -59,6 +71,7 @@
 
 ;; Pushes the product of the top two items onto the same stack
 (def _mult
+  "Pushes the product of the top two items onto the same stack"
   ^{:stacks #{}
     :name "_mult"}
   (fn [stack state]
@@ -68,6 +81,8 @@
 ;; Pushes the quotient of the top two items (i.e. the first item divided by the
 ;; second item) onto the same stack. If the second item is zero, pushes 1
 (def _quot
+  "Pushes the quotient of the top two items (i.e. the first item divided by the
+  second item) onto the same stack. If the second item is zero, pushes 1"
   ^{:stacks #{}
     :name "_quot"}
   (fn [stack state]
@@ -78,6 +93,10 @@
 ;; quotient, where the quotient has first been truncated towards negative
 ;; infinity.
 (def _mod
+  "Pushes the top item modulo the second item onto the same stack. If the second
+  item is zero, pushes 1. The modulus is computed as the remainder of the
+   quotient, where the quotient has first been truncated towards negative
+   infinity."
   ^{:stacks #{}
     :name "_mod"}
   (fn [stack state]
@@ -85,6 +104,7 @@
 
 ;; Pushes the maximum of the top two items
 (def _max
+  "Pushes the maximum of the top two items"
   ^{:stacks #{}
     :name "_max"}
   (fn [stack state]
@@ -92,6 +112,7 @@
 
 ;; Pushes the minimum of the top two items
 (def _min
+  "Pushes the minimum of the top two items"
   ^{:stacks #{}
     :name "_min"}
   (fn [stack state]
@@ -99,6 +120,7 @@
 
 ;; Pushes 1 / 1.0 if the top BOOLEAN is TRUE, or 0 / 0.0 if FALSE
 (def _from_boolean
+  "Pushes 1 / 1.0 if the top BOOLEAN is TRUE, or 0 / 0.0 if FALSE"
   ^{:stacks #{:boolean}
     :name "_from_boolean"}
   (fn [stack state]
@@ -109,6 +131,7 @@
 
 ;; Pushes the ASCII value of the top CHAR
 (def _from_char
+  "Pushes the ASCII value of the top CHAR"
   ^{:stacks #{:char}
     :name "_from_char"}
   (fn [stack state]
@@ -117,6 +140,8 @@
 ;; Pushes the value of the top STRING, if it can be parsed as a number.
 ;; Otherwise, acts as a NOOP
 (def _from_string
+  "Pushes the value of the top STRING, if it can be parsed as a number.
+Otherwise, acts as a NOOP"
   ^{:stacks #{:string}
     :name "_from_string"}
   (fn [stack state]
@@ -133,6 +158,7 @@
 
 ;; Pushes the increment (i.e. +1) of the top item of the stack
 (def _inc
+  "Pushes the increment (i.e. +1) of the top item of the stack"
   ^{:stacks #{}
     :name "_inc"}
   (fn [stack state]

src/propeller/push/instructions/polymorphic.cljc

@@ -1,4 +1,5 @@
 (ns propeller.push.instructions.polymorphic
+  "Polymorphic Instructions (for all stacks, with the exception of non-data ones like input and output)"
   (:require [propeller.utils :as utils]
             [propeller.push.state :as state]
             [propeller.push.limits :as limit]

src/propeller/push/instructions/string.cljc

@@ -1,4 +1,5 @@
 (ns propeller.push.instructions.string
+  "STRING Instructions"
   (:require [clojure.string :as string]
             [propeller.push.state :as state]
             [propeller.push.instructions :refer [def-instruction

src/propeller/push/instructions/vector.cljc

@@ -1,5 +1,5 @@
 (ns propeller.push.instructions.vector
-  "Vector instructions for all vector element subtypes: BOOLEAN, FLOAT, INTEGER, and STRING."
+  "VECTOR instructions for all vector element subtypes: BOOLEAN, FLOAT, INTEGER, and STRING."
   (:require [clojure.string]
             [propeller.utils :as utils]
             [propeller.push.state :as state]

src/propeller/tools/math.cljc

@@ -1,9 +1,9 @@
 (ns propeller.tools.math)
 
-(defonce PI #?(:clj  Math/PI
+(defonce ^:no-doc PI #?(:clj  Math/PI
                :cljs js/Math.PI))
 
-(defonce E #?(:clj  Math/E
+(defonce ^:no-doc E #?(:clj  Math/E
               :cljs js/Math.PI))
 
 (defn mean