Wolfram Elementary 1-D CA (Textbook)

Math essence

For each cell i: idx = (row[i-1] * K^2 + row[i] * K + row[i+1]) mod K^3; next[i] = table[idx]. The 3^K-entry lookup table is encoded by treating the rule number as a base-K integer (K=2 -> 8-bit rule 0..255). Periodic boundary via np.roll. Each new generation is drawn onto the next canvas row with a 5-pixel cross stamp and an optional colour map (binary, viridis, magma, rainbow).

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/shiffman_pearson_textbook/wolframCA1DTextbook/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


def _rule_bits(rule: int, k: int) -> np.ndarray:
    """Decode a 3^K-ary lookup rule to a K-state array of length k**3.

    For K=2 this is the classic Wolfram 8-bit rule (0..255). For K>2 each
    3-cell neighbourhood `(left, self, right)` with state in [0, K-1] maps
    to a K-ary index `((left*K + self)*K + right)` whose value becomes the
    rule's output. The rule number itself is written in base-K over k**3
    digits.
    """
    out = np.zeros(k ** 3, dtype=np.uint8)
    v = int(rule)
    for i in range(k ** 3):
        out[i] = v % k
        v //= k
        if v == 0:
            break
    return out


class WolframCA1DTextbook:
    """Wolfram elementary cellular automaton — textbook rendering.

    A 1-D row of ``dim`` cells each holding a value in ``[0, K-1]`` is
    updated by a 3-neighborhood rule (left, self, right -> next). For K=2
    this is the classic Wolfram rule 0..255 used everywhere in the
    textbook (rule 30, 90, 110, 184 being the visual favourites).
    For K>2 it becomes a cyclic cellular automaton: ``next = (cell + 1) mod K``
    if the *right* neighbour has state ``(cell + 1) mod K`` and otherwise the
    cell stays. This extension is also from Shiffman's Nature of Code Ch. 7.

    Each step() appends one row to a square ``dim x dim`` history canvas, so
    generations stack downward and the diagonal-of-time pattern emerges.
    The default is K=2 with rule 30 (Wolfram's poster-child chaotic rule),
    started from a single live cell in the middle of an empty row.
    """

    family: ClassVar[str] = "shiffman_pearson_textbook"
    sketch: ClassVar[str] = "wolframCA1DTextbook"

    def __init__(
        self,
        dim: int = 360,
        rule: int = 30,
        k: int = 2,
        seed_mode: str = "single",
        rule_table: np.ndarray | None = None,
        generations: int | None = None,
        palette_mode: str = "binary",
        bg_color: tuple[int, int, int] = (245, 240, 230),
        ink_color: tuple[int, int, int] = (20, 25, 40),
        seed: int | None = None,
    ) -> None:
        self.dim = dim