Small changes after proof-reading of WolframAutomata README.

[screensavers] / hacks / WolframAutomata / README.md

diff --git a/hacks/WolframAutomata/README.md b/hacks/WolframAutomata/README.md
index 88ecbe7..91fe6e8 100644 (file)
--- a/hacks/WolframAutomata/README.md
+++ b/hacks/WolframAutomata/README.md
@@ -10,8 +10,9 @@ 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
 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.
+switching on or off. Each new application of the rule to the universe is drawn
+on the screen as a new line directly below the previous generation's line,
+leading the screen to scroll vertically.

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


@@ -26,24 +27,21 @@ discussed at length in a
 
 ![Rule 110 Animated Screenshot](/screensavers/.git/blob_plain/HEAD:/hacks/WolframAutomata/screenshot_rule_110.gif)
 
 
 ![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.
+Commandline flags are provided which enable 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
 
 ![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
+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
 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.
+randomly from this list.

 
 
 Status
 
 
 Status


@@ -68,9 +66,9 @@ 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.
 
 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.
+For assistance setting `$(DEFINES)` in the `Makefile` 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
 
 Although WolframAutomata can integrate with XScreensaver, the presence of
 XScreensaver is not strictly required.  WolframAutomata will both build and


@@ -88,12 +86,30 @@ are re-randomized every time the simulation is reset, such as after a
 simulation completes or after resizing the window.
 
 
 simulation completes or after resizing the window.
 
 

+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 Seed
 --------------------
 
 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.
+The following seed related CLI flags apply only when using the
+`-true-random-rule` or `-rule N` flags. Without these flags, the program draws
+rules from `curated_ruleset_list[]` which also includes curated seeds, all of
+which override any seed related CLI flags.
+
+If the curated rule list is not in use and 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-left`**: Seeds a single active cell on the left side of the
     display. All other cells are inactive.


@@ -105,22 +121,22 @@ itself also randomly selected.
   - **`-seed-density N`**: Generates random seed with `N` percent active cells.
 
 
   - **`-seed-density N`**: Generates random seed with `N` percent active cells.
 
 

-CLI: Rule Selection
--------------------
+CLI: Simulation Length
+----------------------

 
 

-If neither of the following two options are passed, rules are randomly selected
-from `curated_ruleset_list[]` in `WolframAutomata.c`.
+If neither of the following two options are passed, the simulation runs as
+though `-length 5000` was passed.

 
 

-  - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
-    from a curated list. Note that many rules are visually uninteresting.
+  - **`-random-length`**: A random length smaller than 10,000 generations but
+    large enough to fill the screen is selected.

 
 

-  - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
-    from 1-255 inclusive are valid.
+  - **`-length N`**: Request `N` generations be simulated on each run.

 
 

-Note that, although Rule 0 is a valid set of rules, it is reused as a null
-value by the program and thus is ignored if passed as `-rule 0`. If you want to
-see Rule 0, choose any starting conditions you desire, then turn off your
-monitor and enjoy the resulting simulation.
+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: Simulation Speed
 
 
 CLI: Simulation Speed


@@ -140,24 +156,6 @@ though `-delay 25000` was passed.
     well respected.
 
 
     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
 --------------------
 
 CLI: Cell Dimensions
 --------------------
 


@@ -165,11 +163,11 @@ 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.
 
 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 selects
-whatever cell size it feels appropriate for the current simulation speed.
+If neither of the following two options are passed, the simulation behaves as
+though `-cell-size 2` was passed.

 
 

-  - **`-random-cell-size`**: Selects cell size of 2^N pixels for an `N`
-    randomly chosen in the inclusive range `0`-`5`.
+  - **`-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.
 
   - **`-cell-size N`**: Display each individual cell as an `N`x`N` square of
     pixels on the screen.


@@ -196,10 +194,128 @@ Note that the names provided as comments in `color_list[]` are X11 color names.
 CLI: Admiration
 ---------------
 
 CLI: Admiration
 ---------------
 

-When the simulation reaches its end as determined by flags like `-length N`, it
+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.
 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/wolframautomata
+
+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
+
+    <?xml version="1.0" encoding="ISO-8859-1"?>
+    
+    <screensaver name="wolframautomata" _label="WolframAutomata">
+    
+      <command arg="-root"/>
+    
+      <string  id="rule_number"   _label="Rule number: "      arg="-rule %" />
+      <boolean id="rnd_rule"      _label="Random rule"        arg-set="-random-rule" />
+    
+      <string  id="seed_density"  _label="Seed density (%):"  arg="-seed-density %" />
+      <boolean id="seed_left"     _label="Seed left"          arg-set="-seed-left" />
+      <boolean id="seed_center"   _label="Seed center"        arg-set="-seed-center" />
+      <boolean id="seed_right"    _label="Seed right"         arg-set="-seed-right" />
+    
+      <string  id="length"        _label="Length (gen):"      arg="-length %" />
+      <boolean id="rnd_length"    _label="Random length"      arg-set="-random-length" />
+    
+      <string  id="delay"         _label="Delay (usec):"      arg="-delay %" />
+      <boolean id="rnd_delay"     _label="Random delay"       arg-set="-random-delay" />
+    
+      <string  id="cell_size"     _label="Cell size (px):"    arg="-cell-size %" />
+      <boolean id="rnd_cellsize"  _label="Random cell size"   arg-set="-random-cell-size" />
+    
+      <string  id="color_index"   _label="Color index (int):" arg="-color-index %" />
+    
+      <string  id="admiration"    _label="Admiration (sec):"  arg="-admiration-delay %" />
+    
+      <_description>
+    Displays the time evolution of elementary cellular automata.
+    
+    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, where the code number is directly
+    convertible into a rule set.
+      </_description>
+    </screensaver>
+
+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.
+