Documentation for atom-generators and push instructions

While I was going through some of the demo programs in Clojush, I noticed there is no proper documentation (either incomplete or at least not at appropriate places) for atom-generators (e.g., in1) and push instructions (e.g., string_take). It took me a while to understand the programs because of it. Therefore, I am planning to complete the documentation. After discussing the same with Lee, it seems there are a couple of options:

  • Putting it on the Push Redux page.
  • Construct an orientation page on the discourse.

I am not sure which one to choose and where to start. Suggestions?


I’ve been thinking that the best approach might be a combination of these things:

  1. In the Push Redux, where there’s just a placeholder now, add documentation for “standardish” instructions which are available both in Clojush and in Pysh, described in an implementation-independent way (possibly noting the actual instruction names in these two systems).

  2. In Discourse, add an Orientation topic for Specifying Atom Generators, which links to the existing topic on Input Instructions but also covers ephemeral random constants, techniques for pulling in all instructions for specified types, etc.

  3. Tweak the READMEs for Clojush and Pysh on github to point to these things.

Thoughts or other suggestions?


This is awesome! I am really glad this is being done :smiley:

I personally don’t have a clear idea of the border between the Push language and the Push language implementation (clojush, pysh, klapaucius, etc) when it comes to the instructions/atom generators. Does anyone else?

If the documentation you are creating is going to be about Push in general then I agree that the Push Redux makes the most sense. However this is tricky because if you start to write documentation on each individual instruction, or how certain atom generators work, suddenly there are major differences between implementations.

Clojush and Pysh contain the mostly the same instructions, but some have different names. Klapaucius is a whole different world. Also, other types of atom generators are different between implementations, as shown by our recent topic on output values.

That isn’t to say to say there isn’t really helpful documentation to be written that isn’t specific to a single implementation. I just predict it will be harder to write.

In my opinion, some lower hanging fruit that would still be extremely helpful would be to improve the documentation of one implementation. I assume you would want to start with Clojush, but this will probably need to be done in some form for all implementations. If this is more along the lines of what you were thinking, then I have some suggestions:

  1. I would strongly consider capturing this documentation in the Clojush repository somehow. If contributors can’t push their own updates to the documentation along with their code, the documentation will probably be out of date within a month.

  2. The closer the documentation of each instruction can be to the code implementing that instruction, the better. That way documentation can be read within the source code, and it is much easier to stay in sync. Unfortunately, I don’t think you can adequately use docstrings because when the instruction set is being built (in pyshgp and Clojush) there are functions that are used to create the same instruction multiple times but for different stacks (ie. integer_pop, boolean_pop, and string_pop are all generated by this one function). You would have to come up with a way to generate informative docstrings for each instruction created by the function, which seems difficult to me.

I realize that I am probably making this far more complicated than anyone wants :slight_smile: . Perhaps it is adequate to simply have 1 page per implementation on the redux that documents the instruction set supported by that implementation.


I think that this is a case where the perfect can be (and has been) the enemy of the good. That is, focusing too much on how to do it perfectly, especially with respect to the issue of implementation-independent vs. implementation-specific instructions and features, has often kept us from making progress on any kind of documentation.

My main takeaway from this is that it’s probably best just to move forward in whatever way makes the most sense to whoever is taking the initiative and time to do it, but with our multiple goals in mind. With luck and input from everyone, we may end up with something(s) that serve our multiple purposes.

That said, I think that Clojush and Pysh are close enough to one another (and also close enough to some other Push implementations), that it should be possible for one resource to serve as a good first-pass introduction to the common features/instructions of both. Whether that ends up looking like something truly generic, or something that’s mostly documentation for one but with some notes about the other, I don’t know. And I would agree that Klapaucius is different enough that it probably can’t be wrapped into this in any direct way at all.

So maybe @aks should just take this quasi/partial/non-advice for what it’s worth, take an initial stab at moving things forward, and ask for us to look at it and comment from time to time?

1 Like

I think this is a really important point. Because of this, I’d favor documentation with the instruction definitions right in Clojush. But, any of the above options are better than none!


This is in fact worse in Klapaucius, since almost all instructions are constructed on demand from macros. What I did in lieu of literal docstrings was to produce a gazetteer function that poops out a complete document with all the instructions described.

Not my favorite consequence of a design decision that was otherwise very useful.


Similar thing done in pysghgp with this script which scrapes the strange comments put in the instruction files like this. Every time I scroll through those hacky not-docstring-but-still-docstring-comments I get sad… :frowning:


Is there any way you can post a simple, everybody-can-use-it-if-they-know-Clojure explanation of how to set up a standard Clojush problem? On the main project website, or in the repo?

I can imagine that very few users really care about most of the stuff reported in the info-dump. But that’s OK. What they do care about is a simple, legible way of setting up a problem that will work, and doesn’t require copying-and-pasting an awful function. Make it a callable function or a macro if you have to, but please stop duplicating all that blasted code in every problem definition file.

Maybe we want to work with training and test data, but not necessarily. But we do not want to try to understand a multifunction with no docstring. I promise.

Is there anything anywhere, besides just “copy and paste from some random problem”?


See also :slight_smile: