From 74edf5615df795383c222e83aa53894114dfd193 Mon Sep 17 00:00:00 2001
From: Aaron Taylor <ataylor@subgeniuskitty.com>
Date: Sun, 6 Jun 2021 19:38:36 -0700
Subject: [PATCH] Added basic README to WolframAutomata.

---
 hacks/WolframAutomata/README.md | 77 +++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 hacks/WolframAutomata/README.md

diff --git a/hacks/WolframAutomata/README.md b/hacks/WolframAutomata/README.md
new file mode 100644
index 0000000..fd091a7
--- /dev/null
+++ b/hacks/WolframAutomata/README.md
@@ -0,0 +1,77 @@
+Overview
+========
+
+This WolframAutomata hack displays the time evolution of [elementary cellular
+automata](https://en.wikipedia.org/wiki/Elementary_cellular_automaton).
+
+These automata consist of a line of cells, each of which may be either on or
+off. To ensure every cell has neighbors, the two endpoints of the line connect
+together, thereby forming a circular universe for the cells to inhabit.  This
+line is drawn horizontally on the screen.
+
+Over time, this line of cells evolves according to rules, with some cells
+switching on or off. Each new iteration is drawn below its predecessor, leading
+the screen to scroll vertically over time.
+
+The rules which govern the time evolution of this system depend only on the
+current state of a given cell and the state of its two immediate neighbors.
+These rules are formalized as
+[Wolfram codes](https://en.wikipedia.org/wiki/Wolfram_code),
+where the code number is directly convertible into a rule set.
+
+For example, the following screenshot demonstrates
+[Rule 110](https://en.wikipedia.org/wiki/Rule_110), itself Turing complete as
+discussed at length in a
+[fascinating paper](https://arxiv.org/pdf/0906.3248.pdf).
+
+![Rule 110 Animated Screenshot](/screensavers/.git/blob_plain/HEAD:/hacks/WolframAutomata/screenshot_rule_110.gif)
+
+Commandline flags are provided enabling the user to tweak attributes such as
+length and speed of simulation, cell size, rule number, colors, starting seed,
+and other attributes. For example, the screenshot below depicts Rule 73 with
+different colors than the Rule 110 screenshot. Like the Rule 110 screenshot, it
+uses `-cell-size 2` and seeds the simulation with only a single active cell.
+
+![Rule 73 Animated Screenshot](/screensavers/.git/blob_plain/HEAD:/hacks/WolframAutomata/screenshot_rule_73.gif)
+
+In situations where true randomness would lead to visually unappealing
+displays, this program provides random selection from curated lists. For
+example, to avoid randomly selecting visually indistinguishable colors like
+`dark red` and `brown` to depict on/off cells, the program includes a
+pre-selected list of color pairs that complement each other and chooses
+randomly from this list when the `-random-color` flag is passed.  Similarly, to
+avoid the visually uninteresting rules like rule 0, a rule which simply turns
+every cell off and keeps it off, the program includes a list of rulesets and
+starting seeds which are visually appealing, selecting randomly from this list
+when the `-random-rule` flag is passed.
+
+
+Status
+======
+
+Complete. Tested on FreeBSD.
+
+Nearly works on Linux. The only problem resides in `WolframAutomata_free()`,
+where the call to `XFreeGC()` results in a linker error. Commenting that line
+allows WolframAutomata to build and execute on Linux, but creates a memory leak
+in the X server, resulting in its eventual termination.
+
+
+Instructions
+============
+
+The included `Makefile` includes targets for `make all` to build the hack,
+`make clean` to delete any build detritus, and `make run` to execute the hack.
+
+If you are running on FreeBSD, simply run one of those three commands. Anywhere
+else, edit the `Makefile` to suit your environment per the comments included in
+that file. Note that the `Makefile` assumes a copy of the screenhack library
+source code is located at `../screenhack/` relative to this directory.
+
+For assistance setting `$(DEFINES)` on non-FreeBSD platforms, consider
+downloading the XScreensaver source tarball, running `./configure` in the
+unpacked directory, and examining the resulting `config.h` file.
+
+Although WolframAutomata can integrate with XScreensaver, the presence of
+XScreensaver is not strictly required.  WolframAutomata will both build and
+execute using only the included screenhack library.
-- 
2.20.1