Added CLI options for requesting a specific rule, random rules, or random curated...

[screensavers] / hacks / WolframAutomata / WolframAutomata.c

/* (c) 2021 Aaron Taylor <ataylor at subgeniuskitty dot com>   */
/* See LICENSE.txt file for copyright and license details.     */


/* TODO: Write description explaining that this simulates all 1D NN CAs, and explain briefly what all those terms imply. */
/* TODO: Explain things like the topology of the space. */
/* TODO: Explain how the numbering for a CA expands to the actual rules. */
/* TODO: Briefly explain the four different classes of behavior and their implications. */
/* TODO: Include a link to Wikipedia. */
/* TODO: I suppose a lot of this stuff goes in the README instead. */
/* TODO: Explain the data structures in detail. */
/* TODO: Explain all the options, like the various starting conditions. */


/* TODO: Check manpage for all functions I use and ensure my includes are correct. I don't want to depend on picking up includes via screenhack.h. */
/* TODO: Verify everything in this file is C89. Get rid of things like '//' comments, pack all my declarations upfront, no stdint, etc. */

#include "screenhack.h"

// Command line options
//        directory to output XBM files of each run (and call an external command to convert to PNGs?)
//              -save-dir STRING
//        number of generations to simulate
//              -num-generations N
//        delay time (speed of simulation)
//              -delay-usec N
//        foreground and background color
//              ??? (strings of some sort, but I need to look up what X resources to interact with)
//        display info overlay with CA number and start conditions?
//              -overlay
//        which ruleset number to use? Or random? Or random from small set of hand-selected interesting examples?
//              In order of precedence:
//                  -random (select a random rule on each run)
//                  -rule N (always simulate Rule N on each run)
//                  (if neither of the above two are specified, then a random CURATED rule is selected on each run)
//        which starting population to use? Or random? Or one bit in middle? Or one bit on edge?  (For random: Can I allow specifying a density like 25%, 50%, 75%?)
//              Options (with precedence): -population STRING   (string is a comma separated list of cell IDs to populate, starting from 0)
//                                         -population-curated
//                                         -population-random
//        size of pixel square (e.g. 1x1, 2x2, 3x3, etc)
//              -pixel-size N

struct state {
    /* Various X resources */
    Display * dpy;
    Window    win;
    GC        gc;

    // TODO: Explain that this holds the whole evolution of the CA and the actual displayed visualization is simply a snapshot into this pixmap.
    Pixmap    evolution_history;

    // TODO: Explain all of these.
    unsigned long fg, bg;
    int xlim, ylim, ypos; // explain roughly how and where we use these. Note: I'm not thrilled xlim/ylim since they are actually the width of the display, not the limit of the index (off by one). Change those names.
    Bool display_info;

    Bool * current_generation;

    // TODO: Describe these.
    uint8_t rule_number;  // Note: This is not a CLI option. You're thinking of rule_requested.
    uint8_t rule_requested; // Note: Repurposing Rule 0 as a null value.
    Bool rule_random;

    /* Misc Commandline Options */
    int pixel_size; /* Size of CA cell in pixels (e.g. pixel_size=3 means 3x3 pixels per cell). */
    int delay_microsec; /* Requested delay to screenhack framework before next call to WolframAutomata_draw(). */
    int num_generations; /* Number of generations of the CA to simulate before restarting. */

    /* Expository Variables - Not strictly necessary, but makes some code easier to read. */
    size_t number_of_cells;
};

// TODO: Check the full set of 256 CAs for visually interesting examples.
static const uint8_t curated_rule_list[] = {
    22,
    30,
    45,
    57,
    73,
    86
};

static void *
WolframAutomata_init(Display * dpy, Window win)
{
    struct state * state = calloc(1, sizeof(*state)); // TODO: Check calloc() call
    XGCValues gcv;
    XWindowAttributes xgwa;

    state->dpy = dpy;
    state->win = win;

    XGetWindowAttributes(state->dpy, state->win, &xgwa);
    state->xlim = xgwa.width;
    state->ylim = xgwa.height;
    state->ypos = 0; // TODO: Explain why.

    state->fg = gcv.foreground = get_pixel_resource(state->dpy, xgwa.colormap, "foreground", "Foreground");
    state->bg = gcv.background = get_pixel_resource(state->dpy, xgwa.colormap, "background", "Background");
    state->gc = XCreateGC(state->dpy, state->win, GCForeground, &gcv);

    state->delay_microsec = get_integer_resource(state->dpy, "delay-usec", "Integer");
    if (state->delay_microsec < 0) state->delay_microsec = 0;

    state->pixel_size = get_integer_resource(state->dpy, "pixel-size", "Integer");
    if (state->pixel_size < 1) state->pixel_size = 1;
    if (state->pixel_size > state->xlim) state->pixel_size = state->xlim;

    state->number_of_cells = state->xlim / state->pixel_size;

    /* The minimum number of generations is 2 since we must allocate enough   */
    /* space to hold the seed generation and at least one pass through        */
    /* WolframAutomata_draw(), which is where we check whether or not we've   */
    /* reached the end of the pixmap.                                         */
    state->num_generations = get_integer_resource(state->dpy, "num-generations", "Integer");
    if (state->num_generations < 0) state->num_generations = 2;

    /* Time to figure out which rule to use for this simulation.              */
    /* We ignore any weirdness resulting from the following cast since every  */
    /* bit pattern is also a valid rule; if the user provides weird input,    */
    /* then we'll return weird (but well-defined!) output.                    */
    state->rule_requested = (uint8_t) get_integer_resource(state->dpy, "rule-requested", "Integer");
    state->rule_random = get_boolean_resource(state->dpy, "rule-random", "Boolean");
    /* Through the following set of branches, we enforce CLI flag precedence. */
    if (state->rule_random) {
        /* If this flag is set, the user wants truly random rules rather than */
        /* random rules from a curated list.                                  */
        state->rule_number = (uint8_t) random();
    } else if (state->rule_requested != 0) {
        /* Rule 0 is terribly uninteresting, so we are reusing it as a 'null' */
        /* value and hoping nobody notices. Finding a non-zero value means    */
        /* the user requested a specific rule. Use it.                        */
        state->rule_number = state->rule_requested;
    } else {
        /* No command-line options were specified, so select rules randomly   */
        /* from a curated list.                                               */
        size_t number_of_array_elements = sizeof(curated_rule_list)/sizeof(curated_rule_list[0]);
        state->rule_number = curated_rule_list[random() % number_of_array_elements];
    }

    // TODO: These should be command-line options, but I need to learn how the get_integer_resource() and similar functions work first.
    state->display_info = True;

    state->current_generation = calloc(1, (sizeof(*(state->current_generation))*state->number_of_cells)); // TODO: Check calloc() call TODO: Can't recall precedence; can I eliminate any parenthesis?
    // TODO: Make the starting state a user-configurable option. At least give the user some options like 'random', 'one-middle', 'one edge', etc.
    //       Ideally accept something like a list of integers representing starting pixels to be "on".
    state->current_generation[0] = True;

    state->evolution_history = XCreatePixmap(state->dpy, state->win, state->xlim, state->num_generations*state->pixel_size, xgwa.depth);
    // Pixmap contents are undefined after creation. Explicitly set a black
    // background by drawing a black rectangle over the entire pixmap.
    XSetForeground(state->dpy, state->gc, state->bg);
    XFillRectangle(state->dpy, state->evolution_history, state->gc, 0, 0, state->xlim, state->num_generations*state->pixel_size);
    XSetForeground(state->dpy, state->gc, state->fg);
    // TODO: Need to draw starting generation on pixmap and increment state->ypos.

    return state;
}

// TODO: function decorations?
// TODO: Explain why this santizes the index for accessing current_generation (i.e. it creates a circular topology).
size_t
sindex(struct state * state, int index)
{
    while (index < 0) {
        index += state->number_of_cells;
    }
    while (index >= state->number_of_cells) {
        index -= state->number_of_cells;
    }
    return (size_t) index;
}

// TODO: function decorations?
// TODO: At least give a one-sentence explanation of the algorithm since this function is the core of the simulation.
Bool
calculate_cell(struct state * state, int cell_id)
{
    uint8_t cell_pattern = 0;
    int i;
    for (i = -1; i < 2; i++) {
        cell_pattern = cell_pattern << 1;
        if (state->current_generation[sindex(state, cell_id+i)] == True) {
            cell_pattern |= 1;
        }
    }
    if ((state->rule_number >> cell_pattern) & 1) {
        return True;
    } else {
        return False;
    }
}

// TODO: function decorations?
void
render_current_generation(struct state * state)
{
    size_t xpos;
    for (xpos = 0; xpos < state->number_of_cells; xpos++) {
        if (state->current_generation[xpos] == True) {
            XFillRectangle(state->dpy, state->evolution_history, state->gc, xpos*state->pixel_size, state->ypos, state->pixel_size, state->pixel_size);
        }
    }
}

static unsigned long
WolframAutomata_draw(Display * dpy, Window win, void * closure)
{
// TODO: Mark these basic sections of the function
//draw()
//    calculate (and store) new generation
//    draw new generation as line of pixels on pixmap
//    calculate current 'viewport' into pixmap
//    display on screen
//  check for termination condition

    struct state * state = closure;
    int xpos;
    int window_y_offset;

    Bool new_generation[state->xlim];
    for (xpos = 0; xpos < state->number_of_cells; xpos++) {
        new_generation[xpos] = calculate_cell(state, xpos);
    }
    for (xpos = 0; xpos < state->number_of_cells; xpos++) {
        state->current_generation[xpos] = new_generation[xpos];
    }
    render_current_generation(state);

    // Was this the final generation of this particular simulation? If so, give
    // the user a moment to bask in the glory of our output and then start a
    // new simulation.
    if (state->ypos/state->pixel_size < state->num_generations-1) {
        state->ypos += state->pixel_size;
    } else {
        // TODO: Wait for a second or two, clear the screen and do a new iteration with suitably changed settings.
        // Note: Since we can't actually loop or sleep here, we need to add a flag to the state struct to indicate that we're in an 'admiration timewindow' (and indicate when it should end)
        printf("infinite hamster wheel\n");
        while (1) continue;
    }

    // Calculate the vertical offset of the current 'window' into the history
    // of the CA. After the CA's evolution extends past what we can display, have
    // the window track the current generation and most recent history.
    if (state->ypos < state->ylim) {
        window_y_offset = 0;
    } else {
        window_y_offset = state->ypos - (state->ylim - 1);
    }

    // Render everything to the display.
    XCopyArea(state->dpy, state->evolution_history, state->win, state->gc, 0, window_y_offset, state->xlim, state->ylim, 0, 0);
    // TODO: Print info on screen if display_info is true. Will need fonts/etc. Do I want to create a separate pixmap for this during the init() function and then just copy the pixmap each time we draw the screen in draw()?

    return state->delay_microsec;
}

// TODO: Fix formatting
static const char * WolframAutomata_defaults[] = {
    ".background:    black",
    ".foreground:    white",
    "*delay-usec:    25000",
    // TODO: Difference between dot and asterisk? Presumably the asterisk matches all resouces of attribute "pixelsize"? Apply answer to all new options.
    "*pixel-size:    2",
    "*num-generations:    5000",
    "*rule-requested:    0",
    "*rule-random:    False",
    0
};

// TODO: Fix formatting
static XrmOptionDescRec WolframAutomata_options[] = {
    { "-delay-usec",        ".delay-usec",    XrmoptionSepArg, 0 },
    { "-pixel-size",    ".pixel-size",    XrmoptionSepArg, 0 },
    { "-num-generations",    ".num-generations",    XrmoptionSepArg, 0 },
    { "-rule",    ".rule-requested",    XrmoptionSepArg, 0 },
    { "-rule-random",    ".rule-random",    XrmoptionNoArg, "True" },
    { 0, 0, 0, 0 }
};

static Bool
WolframAutomata_event(Display * dpy, Window win, void * closure, XEvent * event)
{
    return False;
}

static void
WolframAutomata_free(Display * dpy, Window win, void * closure)
{
    struct state * state = closure;
    XFreeGC(state->dpy, state->gc);
    XFreePixmap(state->dpy, state->evolution_history);
    free(state->current_generation);
    free(state);
}

static void
WolframAutomata_reshape(Display * dpy, Window win, void * closure, unsigned int w, unsigned int h)
{
    WolframAutomata_free(dpy, win, closure);
    closure = WolframAutomata_init(dpy, win);
}

XSCREENSAVER_MODULE ("1D Nearest-Neighbor Cellular Automata", WolframAutomata)