Updated WolframAutomata's rule related CLI flags to match README.

[screensavers] / hacks / WolframAutomata / README.md

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. As one
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.


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.


Command-Line Flags
==================

Whenever related options exist, such as the following two rule-selection
options, the related options are listed in order of precedence.

Where flags instruct the program to make random selections, these selections
are re-randomized every time the simulation is reset, such as after a
simulation completes or after resizing the window.


CLI: Simulation Seed
--------------------

If none of the following options are specified, the starting seed will contain
randomly interspersed active/inactive cells at a 30/70, 50/50, or 70/30 ratio,
itself also randomly selected.

  - **`-seed-left`**: Seeds a single active cell on the left side of the
    display. All other cells are inactive.

  - **`-seed-center`**: As above, but in the center.

  - **`-seed-right`**: As above, but on the right side.

  - **`-seed-density N`**: Generates random seed with `N` percent active cells.


CLI: Rule Selection
-------------------

If neither of the following two options are passed, rules are randomly selected
from `curated_ruleset_list[]` in `WolframAutomata.c`.

  - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
    from a curated list. Note that many rules are visually uninteresting.

  - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
    from 0-255 inclusive are valid.


CLI: Simulation Speed
---------------------

If neither of the following two options are passed, the simulation runs as
though `-delay 25000` was passed.

  - **`-random-delay`**: A random delay is selected, but not truly random. For
    more details, read `WolframAutomata.c` starting around the comment, "When
    randomly setting the delay, the problem is to avoid ..."

  - **`-delay N`**: Request `N` microsecond delay between each frame/generation
    of the simulation. Note that this is only a request; XScreensaver reserves
    the right to ignore requested values, and of course we execute at the mercy
    of the kernel's scheduling. In practice, non-absurd values are reasonably
    well respected.


CLI: Simulation Length
----------------------

If neither of the following two options are passed, the simulation runs as
thought `-length 5000` was passed.

  - **`-random-length`**: A random length smaller than 10,000 generations but
    large enough to fill the screen is selected.

  - **`-length N`**: Request `N` generations be simulated on each run.

Note that an upper limit of 10,000 generations is enforced in order to avoid
`BadAlloc` errors from some X servers.  For more details, read
`WolframAutomata.c` starting around the comment, "The maximum number of
generations is cell_size dependent. This is a soft limit and may be increased
if ..."


CLI: Cell Dimensions
--------------------

Individual cells may be displayed as any square number of pixels (e.g. 1x1,
2x2, etc). Increasing the cell size may help with flickering on high DPI
monitors displaying chaotic rulesets.

If neither of the following two options are passed, the simulation behaves as
though `-cell-size 2` was passed.

  - **`-random-cell-size`**: Randomly selects 1, 2, 4, 8, 16, or 32 as the cell
    size on each reset of the simulation.

  - **`-cell-size N`**: Display each individual cell as an `N`x`N` square of
    pixels on the screen.


CLI: Color
----------

At the moment, the program does not allow the user to specify raw RGB values
from the command line.  Instead, color pairs are selected from `color_list[]`
in `WolframAutomata.c` by specifying an index (starting from `0`) into this
array. However, any RGB color the user desires may be added by creating new
entries in that array (or editing existing entries) and recompiling.

If the following CLI option is not passed, a random color selection is made
from `color_list[]` at the start of each new simulation run.

  - **`-color-index N`**: Select color pair `N` from `color_list[]` in
    `WolframAutomata.c`.

Note that the names provided as comments in `color_list[]` are X11 color names.


CLI: Admiration
---------------

When the simulation reaches its end as determined by flags like `-length N` it
will pause for a period of time, allowing the viewer to examine it without
interference from scrolling. By default, this 'admiration window' is five
seconds long.

  - **`-admiration-delay N`**: At the end of a simulation, pause for `N`
    seconds before resetting for the next simulation.


XScreensaver Integration
========================

In addition to running as a standalone program, WolframAutomata can be
integrated into the XScreensaver framework.

To accomplish this integration, begin by installing and configuring
XScreensaver via whatever method is appropriate for your operating system. The
following instructions assume the filesystem paths used by FreeBSD packages and
ports; your paths may differ. After XScreensaver installation, ensure all
pertinent config files are created by running `xscreensaver-demo` and
configuring XScreensaver for your system.

After XScreensaver is configured and working on your system, ensure that
WolframAutomata runs in standalone mode on your system. If you can `make clean run`
in the `screensavers/hacks/WolframAutomata/` folder and see the hack's visual
output, you're ready to move on.

At this point, copy the hack into your XScreensaver hack directory. For
example, with prerequisite steps spelled out:

    git clone git://git.subgeniuskitty.com/screensavers
    cd screensavers/hacks/WolframAutomata
    make clean all
    cp WolframAutomata /usr/local/bin/xscreensaver-hacks/

Now create the file `WolframAutomata.xml` wherever your system stores
XScreensaver config files and populate it with the contents shown below. For
example, on FreeBSD:

    vi /usr/local/share/xscreensaver/config/WolframAutomata.xml

    TODO: Finish writing this file after the command line options are finalized.

The next step integrates WolframAutomata into an individual user's XScreensaver
config via the file `~/.xscreensaver`. If preferred, it could instead be done
in the global XScreensaver config.

In the `~/.xscreensaver` file, create a WolframAutomata entry under the
`programs:` label in the same list as all the other hacks. Position in the
list is irrelevant, but ensure you don't paste WolframAutomata's entry into the
middle of pre-existing, multi-line entries. For context, the example below
includes a multi-line entry, a GL entry and a plain entry. All that is needed
is to insert the WolframAutomata line somewhere in the `programs:` list, as
demonstrated.

    vi ~/.xscreensaver

    <snip>
    programs:                                                                     \
                                    xplanet -vroot -wait 1 -timewarp 400          \
                                      -label -origin moon                       \n\
      GL:                           fireflies -root                             \n\
                                    WolframAutomata -root                       \n\
                                    blitspin -root                              \n\
    <snip>

That's all. Now you can run `xscreensaver-demo` and select WolframAutomata just
like any other hack.


Screen Tearing
==============

Certain combinations of rules and display settings lead to full screen vertical
scrolling of alternating light and dark pixels, or other difficult to display
patterns. If your display doesn't include some type of vertical refresh
synchronization, such output will look terrible.

If stuck in this situation, changing the output of WolframAutomata to scroll
horizontally may help, or simply increasing the cell size.