{"id":20304404,"url":"https://github.com/lspector/clojush","last_synced_at":"2025-05-16T11:05:23.403Z","repository":{"id":48653832,"uuid":"616728","full_name":"lspector/Clojush","owner":"lspector","description":"The Push programming language and the PushGP genetic programming system implemented in Clojure.","archived":false,"fork":false,"pushed_at":"2023-05-06T17:03:52.000Z","size":21674,"stargazers_count":332,"open_issues_count":53,"forks_count":93,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-16T11:05:16.884Z","etag":null,"topics":["clojure","genetic-programming","interpreter","programming-language","pushgp","stack-based"],"latest_commit_sha":null,"homepage":"http://hampshire.edu/lspector/push.html","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lspector.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2010-04-18T19:45:50.000Z","updated_at":"2025-02-16T09:45:17.000Z","dependencies_parsed_at":"2024-01-06T12:19:01.123Z","dependency_job_id":"d5e20816-c230-416c-aeaa-d179afe321ee","html_url":"https://github.com/lspector/Clojush","commit_stats":{"total_commits":2251,"total_committers":34,"mean_commits":66.20588235294117,"dds":0.5442025766326077,"last_synced_commit":"8f8c6dcb181e675a3f514e6c9e9fc92cf76ac566"},"previous_names":[],"tags_count":311,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lspector%2FClojush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lspector%2FClojush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lspector%2FClojush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lspector%2FClojush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lspector","download_url":"https://codeload.github.com/lspector/Clojush/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","genetic-programming","interpreter","programming-language","pushgp","stack-based"],"created_at":"2024-11-14T16:45:38.528Z","updated_at":"2025-05-16T11:05:18.397Z","avatar_url":"https://github.com/lspector.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"Clojush [![Travis branch](https://img.shields.io/travis/lspector/Clojush/master.svg?style=flat-square)](https://travis-ci.org/lspector/Clojush) [![Coveralls branch](https://img.shields.io/coveralls/lspector/Clojush/master.svg?style=flat-square)](https://coveralls.io/github/lspector/Clojush) [![API Docs](https://img.shields.io/badge/api%20docs-master-blue.svg?style=flat-square)](http://lspector.github.io/Clojush/) [![Clojars Project](https://img.shields.io/clojars/v/clojush.svg?style=flat-square)](http://clojars.org/clojush)\n=======\n\n\nLee Spector (lspector@hampshire.edu), started 20100227\n[See version history](https://github.com/lspector/Clojush/commits/master).\nOlder version history is in `old-version-history.txt`.\n\nThis is the README file accompanying Clojush, an implementation of the\nPush programming language and the PushGP genetic programming system in the\nClojure programming language. Among other features this implementation\ntakes advantage of Clojure's facilities for multi-core concurrency.\n\nAvailability\n------------\n\nhttps://github.com/lspector/Clojush/\n\nRequirements\n------------\n\nTo use this code you must have a Clojure programming environment; see\nhttp://clojure.org/. The current version of Clojush requires Clojure 1.7.0.\n\nClojure is available for most OS platforms. [A good starting point for\nobtaining and using Clojure](https://clojure.org/guides/getting_started).\n\n\nQuickstart\n----------\n\nUsing [Leiningen](https://github.com/technomancy/leiningen) you can\nrun an example from the OS command line (in the Clojush directory) with\na call like:\n\n    lein run clojush.problems.demos.simple-regression\n\nIf you would like to change a parameter, you may do so at the command line.\nFor example, to change the default population size from 1000 to 50, call:\n\n    lein run clojush.problems.demos.simple-regression :population-size 50\n\nAdditional parameters may also be specified. All valid parameters with their descriptions can be found in [args.clj](https://github.com/lspector/Clojush/blob/master/src/clojush/args.clj).\n\nThe above calls will load everything and run PushGP on a simple symbolic\nregression problem (symbolic regression of y=x^3-2x^2-x). Although the\ndetails will vary from run to run, and it's possible that it will fail,\nthis usually succeeds in a few generations.\n\nAnother option is to evaluate in the leinigen REPL (Read Eval Print Loop):\n\n    sh\u003e lein repl\n    ...\n    clojush.core=\u003e (use 'clojush.problems.demos.simple-regression)\n    ...\n    clojush.core=\u003e (pushgp argmap)\n\nArguments to pushgp are specified in the `argmap` variable in the problem's\nnamespace.\n\nTo run the examples in an IDE (Integrated Development Environment) for\nClojure such as Clooj or Eclipse/Counterclockwise, load one of the\nfiles in src/clojush/problems into the IDE's REPL, type `(pushgp argmap)`\ninto the REPL's input area, and hit the enter key.\n\nYou can also use [Docker](https://docs.docker.com/) to run examples, if you\ndon't want to install Clojure on your machine directly.\n\n```bash\n# first build the image. This needs to be re-done if any of the code changes\ndocker build -t lspector/clojush .\n# then run it on a specific problem\ndocker run --rm lspector/clojush lein run clojush.problems.demos.simple-regression\n```\n\nFor large-scale runs you may want to provide additional arguments to\nJava in order to allow  access to more memory and/or to take maximal\nadvantage of Clojure's concurrency support in the context of Clojush's\nreliance on garbage  collection. For example, you might want to provide\narguments such  as `-Xmx2000m` and `-XX:+UseParallelGC`. Details will depend\non the method that you use to launch your code.\n\nAn additional tutorial is available in `src/clojush/problems/demos/tutorial.clj`.\n\nDescription\n-----------\n\nClojush is a version of the Push programming language for evolutionary\ncomputation, and the PushGP genetic programming system, implemented in\nClojure. More information about Push and PushGP can be found at\nhttp://hampshire.edu/lspector/push.html.\n\nClojush derives mainly from Push3 (for more information see\nhttp://hampshire.edu/lspector/push3-description.html,\nhttp://hampshire.edu/lspector/pubs/push3-gecco2005.pdf) but it is not\nintended to be fully compliant with the Push3 standard and there are a\nfew intentional differences. It was derived most directly from the Scheme\nimplementation of Push/PushGP (called Schush). There are several differences\nbetween Clojush and other versions of Push3 -- for example, almost all of the\ninstruction names are different because the `.` character has special\nsignificance in Clojure -- and these are listed below.\n\nIf you want to understand the motivations for the development of Push, and\nthe variety of things that it can be used for, you should read a selection of\nthe documents listed at http://hampshire.edu/lspector/push.html, probably\nstarting with the 2002 \"Genetic Programming and Evolvable Machines\" article\nthat can be found at http://hampshire.edu/lspector/pubs/push-gpem-final.pdf.\nBear in mind that Push has changed over the years, and that Clojush is\nclosest to Push3 (references above).\n\nPush can be used as the foundation of many evolutionary algorithms,\nnot only PushGP (which is more or less a standard GP system except\nthat it evolves Push programs rather than Lisp-style function trees --\nwhich can make a big difference!). It was developed primarily for\n\"meta-genetic-programming\" or \"autoconstructive evolution\" experiments, in\nwhich programs and genetic operators co-evolve or in which programs produce\ntheir own offspring while also solving problems. But it turns out that\nPush has a variety of uniquely nice features even within a more\ntraditional genetic programming context; for example it makes it unusually\neasy to evolve programs that use multiple data types, it provides novel and\nautomatic forms of program modularization and control structure co-evolution,\nand it allows for a particularly simple form of automatic program\nsimplification. Clojush can serve as the foundation for other evolutionary\nalgorithms, but only the core Push interpreter and a version of PushGP\nare provided here.\n\nStarting with version 2.0.0, the genomes of evolving individuals in Clojush are based on Plush (linear Push) genomes, which are translated into normal Push programs before execution. Plush genomes are composed of instruction maps, each of which contains an instruction and potentially other metadata describing whether that instruction should be silenced, whether closing parentheses should follow it, etc.\n\nUsage\n-----\n\nExample calls to PushGP are provided in other accompanying files.\n\nPush programs are run calling `run-push`, which takes as arguments a Push\nprogram and a Push interpreter state that can be made with `make-push-state`.\nIf you are planning to use PushGP then you will want to use this in the error\nfunction (a.k.a. fitness function) that you pass to the `pushgp` function.\nHere is a simple example of a call to `run-push`, adding 1 and 2 and returning\nthe top of the integer stack in the resulting interpreter state:\n\n    (top-item :integer (run-push '(1 2 integer_add) (make-push-state)))\n\nIf you want to see every step of execution you can pass an optional third\nargument of `true` to `run-push`. This will cause a representation of the\ninterpreter state to be printed at the start of execution and after\neach step. Here is the same example as above but with each step printed:\n\n    (top-item :integer (run-push '(1 2 integer_add) (make-push-state) true))\n\nSee the \"parameters\" section of the code for some parameters that will affect\nexecution, e.g. whether code is pushed onto and/or popped off of the code\nstack prior to/after execution, along with the evaluation limits (which can be\nnecessary for halting otherwise-infinite loops, etc.).\n\n`Run-push` returns the Push state that results from the program execution; this\nis a Clojure map mapping type names to data stacks. In addition, the map\nreturned from `run-push` will map `:termination` to `:normal` if termination was\nnormal, or `:abnormal` otherwise (which generally means that execution was\naborted because the evaluation limit was reached.\n\nRandom code can be generated with `random-code`, which takes a size limit and a\nlist of \"atom generators.\" Size is simply the length of the linear Plush genome.\nEach `atom-generator` should\nbe a constant or the name of a Push instruction (in which case it will be\nused literally), or a Clojure function that will be called with no arguments\nto produce a constant or a Push instruction. This is how \"ephemeral random\nconstants\" can be incorporated into evolutionary systems that use Clojush --\nthat is, it is how you can cause random constants to appear in\nrandomly-generated programs without including all possible constants in the\nlist of elements out of which programs can be constructed. Here is an example\nin which a random program is generated, printed, and run. It prints a message\nindicating whether or not the program terminated normally (which it may not,\nsince it may be a large and/or looping program, and since the default\nevaluation limit is pretty low) and it returns the internal representation of\nthe resulting interpreter state:\n\n```clojure\n(let [s (make-push-state)\n      c (random-push-code\n          100                                  ;; size limit of 100 points\n          (concat @registered-instructions     ;; all registered instrs\n                  (list (fn [] (rand-int 100)) ;; random integers from 0-99\n                        (fn [] (rand)))))]     ;; random floats from 0.0-1.0\n  (printf \"\\n\\nCode: %s\\n\\n\" (apply list c))\n  (run-push c s))\n```\n\nIf you look at the resulting interpreter state you will see an \"auxiliary\"\nstack that is not mentioned in any of the Push publications. This exists\nto allow for auxiliary information to be passed to programs without using\nglobal variables; in particular, it is used for the \"input instructions\"\nin some PushGP examples. One often passes data to a Push program by pushing\nit onto the appropriate stacks before running the program, but in many\ncases it can also be helpful to have an instruction that re-pushes the\ninput whenever it is needed. The auxiliary stack is just a convenient place\nto store the values so that they can be grabbed by input instructions and\npushed onto the appropriate stacks when needed. Perhaps you will find other\nuses for it as well, but no instructions are provided for the auxiliary stack\nin Clojush (aside from the problem-specific input functions in the examples).\n\nThe `pushgp` function is used to run PushGP. It takes all of its parameters\nas keyword arguments, and provides default values for any parameters that are\nnot provided. See the `pushgp` definition in `pushgp/pushgp.clj` for details. The single\nargument that must be provided is `:error-function`, which should be a function that\ntakes a Push program and returns a list of errors. Note that this assumes\nthat you will be doing single-objective evolution with the objective being\nthought of as an error to be minimized. This assumption not intrinsic to Push\nor PushGP; it's just the simplest and most standard thing to do, so\nit's what I've done here. One could easily hack around that. In the most\ngeneric applications you'll want to have your error function run through a\nlist of inputs, set up the interpreter and call run-push for each,\ncalculate an error for each (potentially with penalties for abnormal\ntermination, etc.), and return a list of the errors.\n\nNot all of the default arguments to pushgp will be reasonable for all\nproblems. In particular, the default list of atom-generators -- which is ALL\nregistered instructions, a random integer generator (in the range from 0-99)\nand a random float generator (in the range from 0.0 to 1.0) -- will be\noverkill for many problems and is so large that it may make otherwise simple\nproblems quite difficult because the chances of getting the few needed\ninstructions together into the same program will be quite low. But on the\nother hand one sometimes discovers that interesting solutions can be formed\nusing unexpected instructions (see the Push publications for some examples of\nthis). So the set of atom generators is something you'll probably want to\nplay with. The `registered-for-type` function can make it simpler to include\nor exclude groups of instructions. This is demonstrated in some of the\nexamples.\n\nAs of Clojush 2.0.0, genetic operator arguments are provided as a map to the `:genetic-operator-probabilities` argument. Here, each key may be a single operator or an \"operator pipeline\" vector, which allows the application of multiple operators sequentially, using one operators output as the input to the next operator. An example argument could be:\n\n```clojure\n{:reproduction 0.1\n :alternation 0.2\n :uniform-mutation 0.2\n [:alternation :uniform-mutation] 0.2\n :uniform-close-mutation 0.1\n :uniform-silence-mutation 0.1\n [:make-next-operator-revertable :uniform-silence-mutation] 0.1}\n```\n\nHere, two different pipelines would be used. In the second pipeline, the meta-operator `:make-next-operator-revertable` makes the `:uniform-silence-mutation` operator revertable, which means that the child will be compared to the parent, and the parent kept if it is better than the child.\n\nThe use of simplification is also novel here. Push programs can be automatically\nsimplified -- to some extent -- in a very straightforward way: because\nthere are almost no syntax constraints you can remove anything (one or more\natoms or sub-lists, or a pair of parentheses) and still have a valid\nprogram. So the automatic simplification procedure just iteratively removes\nsomething, checks to see what that does to the error, and keeps the simpler\nprogram if the error is the same (or lower!).\n\nAutomatic simplification is used in this implementation of PushGP in two places:\n\n1. A specified number of simplification iterations is performed on the best\nprogram in each generation. This is produced only for the sake of the report,\nand the result is not added to the population. It is possible that the\nsimplified program that is displayed will actually be better than the best\nprogram in the population. Note also that the other data in the report\nconcerning the \"best\" program refers to the unsimplified program.\n2. Simplification is also performed on solutions at the ends of runs.\n\nNote that the automatic simplification procedure will not always find all\npossible simplifications even if you run it for a large number of iterations,\nbut in practice it does often seem to eliminate a lot of useless code (and to\nmake it easier to perform further simplification by hand).\n\nIf you've read this far then the best way to go further is probably to read\nand run the example problem files in `src/clojush/problems/demos`.\n\nImplementation Notes\n--------------------\n\nA Push interpreter state is represented here as a Clojure map that maps type\nnames (keywords) to stacks (lists, with the top items listed first).\n\nPush instructions are names of Clojure functions that take a Push\ninterpreter state as an argument and return it modified appropriately. The\n`define-registered` macro is used to establish the definitions and\nalso to record the instructions in the global list registered-instructions.\nMost instructions that work the same way for more than one type are\nimplemented using a higher-order function that takes a type and returns a\nfunction that takes an interpreter state and modifies it appropriately.\nFor example: there's a function called `popper` that takes a type and returns\na function -- that function takes a state and pops the right stack in the\nstate. This allows us to define `integer_pop` with a simple form:\n\n    (define-registered integer_pop (popper :integer))\n\nIn many versions of Push `RUNPUSH` takes initialization code or initial stack\ncontents, along with a variety of other parameters. The implementation of\n`run-push` here takes only the code to be run and the state to modify. Other\nparameters are set globally in the parameters section below. At some point\nsome of these may be turned into arguments to `run-push` so that they aren't\nglobal.\n\nMiscellaneous differences between clojush and Push3 as described in the Push3\nspecification:\n\n- Clojush instruction names use `_` instead of `.` since the latter has\n  special meaning when used in Clojure symbols.\n- Equality instructions use `eq` rather than `=` since the latter in not\n  explicitly allowed in Clojure symbols.\n- for similar reasons `+, -, *, /, %, \u003c`, and `\u003e` are replaced with `add, sub,\n  mult, div, mod, lt`, and `gt`.\n- Boolean literals are `true` and `false` (instead of `TRUE` and `FALSE` in\n  the Push3 spec). The original design decision was based on the fact that\n  Common Lisp's native Boolean literals couldn't used without conflating\n  false and the empty list (both `NIL` in Common Lisp).\n- Clojush adds `exec_noop` (same as `code_noop`).\n- Clojush includes an execution time limit (via the parameter\n  `evalpush-time-limit`) that may save you from exponential code growth or other\n  hazards. But don't forget to increase it if you expect legitimate programs\n  to take a long time.\n\nPush3 stuff not (yet) implemented:\n- `NAME` type/stack/instructions\n- Other missing instructions: `*.DEFINE`, `CODE.DEFINITION`, `CODE.INSTRUCTIONS`\n- The configuration code and configuration files described in the Push3\n  spec have not been implemented here. The approach here is quite different,\n  so this may never be implemented\n\n[How to Contribute](./CONTRIBUTING.md)\n--------------------------------------\n\nTo Do (sometime, maybe)\n-----------------------\n\n- Implement remaining instructions in the Push3 specification.\n- Add support for seeding the random number generator.\n- Improve the automatic simplification algorithm and make it work on Plush genomes.\n- Possibly rename the auxiliary stack the \"input\" stack if no other\n  uses are developed for it.\n- Write a `sufficient-args` fn/macro to clean up Push instruction definitions.\n\nAcknowledgements\n----------------\n\nThis material is based upon work supported by the National Science Foundation\nunder Grant No. 1017817. Any opinions, findings, and conclusions or\nrecommendations expressed in this publication are those of the authors and\ndo not necessarily reflect the views of the National Science Foundation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flspector%2Fclojush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flspector%2Fclojush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flspector%2Fclojush/lists"}