ref: e30d11ecd169c2e963fada4cac28123b4f4f9a7e
dir: /spectre.c/
/*
* Code to generate patches of the aperiodic 'spectre' tiling
* discovered in 2023.
*
* Resources about the tiling from its discoverers:
* https://cs.uwaterloo.ca/~csk/spectre/
* https://arxiv.org/abs/2305.17743
*
* Writeup of the generation algorithm:
* https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/aperiodic-spectre/
*/
#include <assert.h>
#include <string.h>
#include "puzzles.h"
#include "tree234.h"
#include "spectre-internal.h"
#include "spectre-tables-manual.h"
#include "spectre-tables-auto.h"
static const char *const letters =
#define STRINGIFY(x) #x
HEX_LETTERS(STRINGIFY)
#undef STRINGIFY
;
bool spectre_valid_hex_letter(char letter)
{
return strchr(letters, letter) != NULL;
}
static Hex hex_from_letter(char letter)
{
char buf[2];
buf[0] = letter;
buf[1] = '\0';
return strcspn(letters, buf);
}
static Hex hex_to_letter(unsigned char letter)
{
return letters[letter];
}
struct HexData {
const struct MapEntry *hexmap, *hexin, *specmap, *specin;
const struct MapEdge *hexedges, *specedges;
const Hex *subhexes;
const struct Possibility *poss;
size_t nposs;
};
static const struct HexData hexdata[] = {
#define HEXDATA_ENTRY(x) { hexmap_##x, hexin_##x, specmap_##x, \
specin_##x, hexedges_##x, specedges_##x, subhexes_##x, \
poss_##x, lenof(poss_##x) },
HEX_LETTERS(HEXDATA_ENTRY)
#undef HEXDATA_ENTRY
};
static const struct Possibility *choose_poss(
random_state *rs, const struct Possibility *poss, size_t nposs)
{
/*
* If we needed to do this _efficiently_, we'd rewrite all those
* tables above as cumulative frequency tables and use binary
* search. But this happens about log n times in a grid of area n,
* so it hardly matters, and it's easier to keep the tables
* legible.
*/
unsigned long limit = 0, value;
size_t i;
for (i = 0; i < nposs; i++)
limit += poss[i].prob;
value = random_upto(rs, limit);
for (i = 0; i+1 < nposs; i++) {
if (value < poss[i].prob)
return &poss[i];
value -= poss[i].prob;
}
assert(i == nposs - 1);
assert(value < poss[i].prob);
return &poss[i];
}
SpectreCoords *spectre_coords_new(void)
{
SpectreCoords *sc = snew(SpectreCoords);
sc->nc = sc->csize = 0;
sc->c = NULL;
return sc;
}
void spectre_coords_free(SpectreCoords *sc)
{
if (sc) {
sfree(sc->c);
sfree(sc);
}
}
void spectre_coords_make_space(SpectreCoords *sc, size_t size)
{
if (sc->csize < size) {
sc->csize = sc->csize * 5 / 4 + 16;
if (sc->csize < size)
sc->csize = size;
sc->c = sresize(sc->c, sc->csize, HexCoord);
}
}
SpectreCoords *spectre_coords_copy(SpectreCoords *sc_in)
{
SpectreCoords *sc_out = spectre_coords_new();
spectre_coords_make_space(sc_out, sc_in->nc);
memcpy(sc_out->c, sc_in->c, sc_in->nc * sizeof(*sc_out->c));
sc_out->nc = sc_in->nc;
sc_out->index = sc_in->index;
sc_out->hex_colour = sc_in->hex_colour;
sc_out->prev_hex_colour = sc_in->prev_hex_colour;
sc_out->incoming_hex_edge = sc_in->incoming_hex_edge;
return sc_out;
}
void spectre_place(Spectre *spec, Point u, Point v, int index_of_u)
{
size_t i;
Point disp;
/* Vector from u to v */
disp = point_sub(v, u);
for (i = 0; i < 14; i++) {
spec->vertices[(i + index_of_u) % 14] = u;
u = point_add(u, disp);
disp = point_mul(disp, point_rot(
spectre_angles[(i + 1 + index_of_u) % 14]));
}
}
Spectre *spectre_initial(SpectreContext *ctx)
{
Spectre *spec = snew(Spectre);
spectre_place(spec, ctx->start_vertices[0], ctx->start_vertices[1], 0);
spec->sc = spectre_coords_copy(ctx->prototype);
return spec;
}
Spectre *spectre_adjacent(SpectreContext *ctx, const Spectre *src_spec,
unsigned src_edge, unsigned *dst_edge_out)
{
unsigned dst_edge;
Spectre *dst_spec = snew(Spectre);
dst_spec->sc = spectre_coords_copy(src_spec->sc);
spectrectx_step(ctx, dst_spec->sc, src_edge, &dst_edge);
spectre_place(dst_spec, src_spec->vertices[(src_edge+1) % 14],
src_spec->vertices[src_edge], dst_edge);
if (dst_edge_out)
*dst_edge_out = dst_edge;
return dst_spec;
}
static int spectre_cmp(void *av, void *bv)
{
Spectre *a = (Spectre *)av, *b = (Spectre *)bv;
size_t i, j;
/* We should only ever need to compare the first two vertices of
* any Spectre, because those force the rest */
for (i = 0; i < 2; i++) {
for (j = 0; j < 4; j++) {
int ac = a->vertices[i].coeffs[j], bc = b->vertices[i].coeffs[j];
if (ac < bc)
return -1;
if (ac > bc)
return +1;
}
}
return 0;
}
void spectre_free(Spectre *spec)
{
spectre_coords_free(spec->sc);
sfree(spec);
}
static void spectrectx_start_vertices(SpectreContext *ctx, int orientation)
{
Point minus_sqrt3 = point_add(point_rot(5), point_rot(-5));
Point basicedge = point_mul(point_add(point_rot(0), point_rot(-3)),
point_rot(orientation));
Point diagonal = point_add(basicedge, point_mul(basicedge, point_rot(-3)));
ctx->start_vertices[0] = point_mul(diagonal, minus_sqrt3);
ctx->start_vertices[1] = point_add(ctx->start_vertices[0], basicedge);
ctx->orientation = orientation;
}
void spectrectx_init_random(SpectreContext *ctx, random_state *rs)
{
const struct Possibility *poss;
ctx->rs = rs;
ctx->must_free_rs = false;
ctx->prototype = spectre_coords_new();
spectre_coords_make_space(ctx->prototype, 1);
poss = choose_poss(rs, poss_spectre, lenof(poss_spectre));
ctx->prototype->index = poss->lo;
ctx->prototype->c[0].type = poss->hi;
ctx->prototype->c[0].index = -1;
ctx->prototype->nc = 1;
/*
* Choose a random orientation for the starting Spectre.
*
* The obvious thing is to choose the orientation out of all 12
* possibilities. But we do it a more complicated way.
*
* The Spectres in a tiling can be partitioned into two
* equivalence classes under the relation 'orientation differs by
* a multiple of 1/6 turn'. One class is much more common than the
* other class: the 'odd'-orientation Spectres occur rarely (very
* like the rare reflected hats in the hats tiling).
*
* I think it's nicer to arrange that there's a consistent
* orientation for the _common_ class of Spectres, so that there
* will always be plenty of them in the 'canonical' orientation
* with the head upwards. So if the starting Spectre is in the
* even class, we pick an even orientation for it, and if it's in
* the odd class, we pick an odd orientation.
*
* An odd-class Spectre is easy to identify from SpectreCoords.
* They're precisely the ones expanded from a G hex with index 1,
* which means they're the ones that have index 1 _at all_.
*/
spectrectx_start_vertices(ctx, random_upto(rs, 6) * 2 +
ctx->prototype->index);
/* Initialiise the colouring fields deterministically but unhelpfully.
* spectre-test will set these up properly if it wants to */
ctx->prototype->hex_colour = 0;
ctx->prototype->prev_hex_colour = 0;
ctx->prototype->incoming_hex_edge = 0;
}
void spectrectx_init_from_params(
SpectreContext *ctx, const struct SpectrePatchParams *ps)
{
size_t i;
ctx->rs = NULL;
ctx->must_free_rs = false;
ctx->prototype = spectre_coords_new();
spectre_coords_make_space(ctx->prototype, ps->ncoords);
ctx->prototype->index = ps->coords[0];
for (i = 1; i < ps->ncoords; i++)
ctx->prototype->c[i-1].index = ps->coords[i];
ctx->prototype->c[ps->ncoords-1].index = -1;
ctx->prototype->nc = ps->ncoords;
ctx->prototype->c[ps->ncoords-1].type = hex_from_letter(ps->final_hex);
for (i = ps->ncoords - 1; i-- > 0 ;) {
const struct HexData *h = &hexdata[ctx->prototype->c[i+1].type];
ctx->prototype->c[i].type = h->subhexes[ctx->prototype->c[i].index];
}
spectrectx_start_vertices(ctx, ps->orientation);
ctx->prototype->hex_colour = 0;
ctx->prototype->prev_hex_colour = 0;
ctx->prototype->incoming_hex_edge = 0;
}
void spectrectx_cleanup(SpectreContext *ctx)
{
if (ctx->must_free_rs)
random_free(ctx->rs);
spectre_coords_free(ctx->prototype);
}
SpectreCoords *spectrectx_initial_coords(SpectreContext *ctx)
{
return spectre_coords_copy(ctx->prototype);
}
/*
* Extend sc until it has at least n coordinates in, by copying from
* ctx->prototype if needed, and extending ctx->prototype if needed in
* order to do that.
*/
void spectrectx_extend_coords(SpectreContext *ctx, SpectreCoords *sc, size_t n)
{
if (ctx->prototype->nc < n) {
spectre_coords_make_space(ctx->prototype, n);
while (ctx->prototype->nc < n) {
const struct HexData *h = &hexdata[
ctx->prototype->c[ctx->prototype->nc-1].type];
const struct Possibility *poss;
if (!ctx->rs) {
/*
* If there's no random_state available, it must be
* because we were given an explicit coordinate string
* and ran off the end of it.
*
* The obvious thing to do here would be to make up an
* answer non-randomly. But in fact there's a danger
* that this leads to endless recursion within a
* single coordinate step, if the hex edge we were
* trying to traverse turns into another copy of
* itself at the higher level. That happened in early
* testing before I put the random_state in at all.
*
* To avoid that risk, in this situation - which
* _shouldn't_ come up at all in sensibly play - we
* make up a random_state, and free it when the
* context goes away.
*/
ctx->rs = random_new("dummy", 5);
ctx->must_free_rs = true;
}
poss = choose_poss(ctx->rs, h->poss, h->nposs);
ctx->prototype->c[ctx->prototype->nc-1].index = poss->lo;
ctx->prototype->c[ctx->prototype->nc].type = poss->hi;
ctx->prototype->c[ctx->prototype->nc].index = -1;
ctx->prototype->nc++;
}
}
spectre_coords_make_space(sc, n);
while (sc->nc < n) {
assert(sc->c[sc->nc - 1].index == -1);
assert(sc->c[sc->nc - 1].type == ctx->prototype->c[sc->nc - 1].type);
sc->c[sc->nc - 1].index = ctx->prototype->c[sc->nc - 1].index;
sc->c[sc->nc].index = -1;
sc->c[sc->nc].type = ctx->prototype->c[sc->nc].type;
sc->nc++;
}
}
void spectrectx_step_hex(SpectreContext *ctx, SpectreCoords *sc,
size_t depth, unsigned edge, unsigned *outedge)
{
const struct HexData *h;
const struct MapEntry *m;
spectrectx_extend_coords(ctx, sc, depth+2);
assert(0 <= sc->c[depth].index);
assert(sc->c[depth].index < num_subhexes(sc->c[depth].type));
assert(0 <= edge);
assert(edge < 6);
h = &hexdata[sc->c[depth+1].type];
m = &h->hexmap[6 * sc->c[depth].index + edge];
if (!m->internal) {
unsigned recedge;
const struct MapEdge *me;
spectrectx_step_hex(ctx, sc, depth+1, m->hi, &recedge);
assert(recedge < 6);
h = &hexdata[sc->c[depth+1].type];
me = &h->hexedges[recedge];
assert(m->lo < me->len);
m = &h->hexin[me->startindex + me->len - 1 - m->lo];
assert(m->internal);
}
sc->c[depth].index = m->hi;
sc->c[depth].type = h->subhexes[sc->c[depth].index];
*outedge = m->lo;
if (depth == 0) {
/*
* Update the colouring fields to track the colour of the new
* hexagon.
*/
unsigned char new_hex_colour;
if (!((edge ^ sc->incoming_hex_edge) & 1)) {
/* We're going out via the same parity of edge we came in
* on, so the new hex colour is the same as the previous
* one. */
new_hex_colour = sc->prev_hex_colour;
} else {
/* We're going out via the opposite parity of edge, so the
* new colour is the one of {0,1,2} that is neither this
* _nor_ the previous colour. */
new_hex_colour = 0+1+2 - sc->hex_colour - sc->prev_hex_colour;
}
sc->prev_hex_colour = sc->hex_colour;
sc->hex_colour = new_hex_colour;
sc->incoming_hex_edge = m->lo;
}
}
void spectrectx_step(SpectreContext *ctx, SpectreCoords *sc,
unsigned edge, unsigned *outedge)
{
const struct HexData *h;
const struct MapEntry *m;
assert(0 <= sc->index);
assert(sc->index < num_spectres(sc->c[0].type));
assert(0 <= edge);
assert(edge < 14);
h = &hexdata[sc->c[0].type];
m = &h->specmap[14 * sc->index + edge];
while (!m->internal) {
unsigned recedge;
const struct MapEdge *me;
spectrectx_step_hex(ctx, sc, 0, m->hi, &recedge);
assert(recedge < 6);
h = &hexdata[sc->c[0].type];
me = &h->specedges[recedge];
assert(m->lo < me->len);
m = &h->specin[me->startindex + me->len - 1 - m->lo];
}
sc->index = m->hi;
*outedge = m->lo;
}
void spectrectx_generate(SpectreContext *ctx,
bool (*callback)(void *cbctx, const Spectre *spec),
void *cbctx)
{
tree234 *placed = newtree234(spectre_cmp);
Spectre *qhead = NULL, *qtail = NULL;
{
Spectre *spec = spectre_initial(ctx);
add234(placed, spec);
spec->next = NULL;
if (callback(cbctx, spec))
qhead = qtail = spec;
}
while (qhead) {
unsigned edge;
Spectre *spec = qhead;
for (edge = 0; edge < 14; edge++) {
Spectre *new_spec;
new_spec = spectre_adjacent(ctx, spec, edge, NULL);
if (find234(placed, new_spec, NULL)) {
spectre_free(new_spec);
continue;
}
if (!callback(cbctx, new_spec)) {
spectre_free(new_spec);
continue;
}
add234(placed, new_spec);
qtail->next = new_spec;
qtail = new_spec;
new_spec->next = NULL;
}
qhead = qhead->next;
}
{
Spectre *spec;
while ((spec = delpos234(placed, 0)) != NULL)
spectre_free(spec);
freetree234(placed);
}
}
const char *spectre_tiling_params_invalid(
const struct SpectrePatchParams *params)
{
size_t i;
Hex h;
if (params->ncoords == 0)
return "expected at least one numeric coordinate";
if (!spectre_valid_hex_letter(params->final_hex))
return "invalid final hexagon type";
h = hex_from_letter(params->final_hex);
for (i = params->ncoords; i-- > 0 ;) {
unsigned limit = (i == 0) ? num_spectres(h) : num_subhexes(h);
if (params->coords[i] >= limit)
return "coordinate out of range";
if (i > 0)
h = hexdata[h].subhexes[params->coords[i]];
}
return NULL;
}
struct SpectreCallbackContext {
int xoff, yoff;
Coord xmin, xmax, ymin, ymax;
spectre_tile_callback_fn external_cb;
void *external_cbctx;
};
static bool spectre_internal_callback(void *vctx, const Spectre *spec)
{
struct SpectreCallbackContext *ctx = (struct SpectreCallbackContext *)vctx;
size_t i;
int output_coords[4*14];
for (i = 0; i < 14; i++) {
Point p = spec->vertices[i];
Coord x = point_x(p), y = point_y(p);
if (coord_cmp(x, ctx->xmin) < 0 || coord_cmp(x, ctx->xmax) > 0 ||
coord_cmp(y, ctx->ymin) < 0 || coord_cmp(y, ctx->ymax) > 0)
return false;
output_coords[4*i + 0] = ctx->xoff + x.c1;
output_coords[4*i + 1] = x.cr3;
output_coords[4*i + 2] = ctx->yoff - y.c1;
output_coords[4*i + 3] = -y.cr3;
}
if (ctx->external_cb)
ctx->external_cb(ctx->external_cbctx, output_coords);
return true;
}
static void spectre_set_bounds(struct SpectreCallbackContext *cbctx,
int w, int h)
{
cbctx->xoff = w/2;
cbctx->yoff = h/2;
cbctx->xmin.c1 = -cbctx->xoff;
cbctx->xmax.c1 = -cbctx->xoff + w;
cbctx->ymin.c1 = cbctx->yoff - h;
cbctx->ymax.c1 = cbctx->yoff;
cbctx->xmin.cr3 = 0;
cbctx->xmax.cr3 = 0;
cbctx->ymin.cr3 = 0;
cbctx->ymax.cr3 = 0;
}
void spectre_tiling_randomise(struct SpectrePatchParams *ps, int w, int h,
random_state *rs)
{
SpectreContext ctx[1];
struct SpectreCallbackContext cbctx[1];
size_t i;
spectre_set_bounds(cbctx, w, h);
cbctx->external_cb = NULL;
cbctx->external_cbctx = NULL;
spectrectx_init_random(ctx, rs);
spectrectx_generate(ctx, spectre_internal_callback, cbctx);
ps->orientation = ctx->orientation;
ps->ncoords = ctx->prototype->nc;
ps->coords = snewn(ps->ncoords, unsigned char);
ps->coords[0] = ctx->prototype->index;
for (i = 1; i < ps->ncoords; i++)
ps->coords[i] = ctx->prototype->c[i-1].index;
ps->final_hex = hex_to_letter(ctx->prototype->c[ps->ncoords-1].type);
spectrectx_cleanup(ctx);
}
void spectre_tiling_generate(
const struct SpectrePatchParams *params, int w, int h,
spectre_tile_callback_fn external_cb, void *external_cbctx)
{
SpectreContext ctx[1];
struct SpectreCallbackContext cbctx[1];
spectre_set_bounds(cbctx, w, h);
cbctx->external_cb = external_cb;
cbctx->external_cbctx = external_cbctx;
spectrectx_init_from_params(ctx, params);
spectrectx_generate(ctx, spectre_internal_callback, cbctx);
spectrectx_cleanup(ctx);
}