James Adam Buckland

Three-Dimensional Prints with Blender and OpenStreetMap

Sat, 09 Apr 2022 00:00:00 -0400

Summary

I used blender-osm and Freestyle to render three-dimensional geodata from OpenStreetMap to a pen plotter.

Here is the finished product, a 11in x 17in print on vellum. (Click through for high resolution.)

Here is an overview of the data pipeline I used to generate this print:

┌─────────────┐
│OpenStreetMap│
└┬────────────┘
│
┌▼──────────┐
│blender-osm│
└┬──────────┘
│
┌▼──────┐
│Blender│
└┬──────┘
│
┌▼─────────────────────┐
│Freestyle SVG Exporter│
└┬─────────────────────┘
│
┌▼──────┐
│AxiDraw│
└───────┘

OpenStreetMap

OpenStreetMap is a Wikipedia-style repository of map data. I have used it before to download and print map data with a pen plotter. It contains high-quality, free, volunteered and compiled 2D and 3D geodata about the real world.

blender-osm

blender-osm is a plugin written by prochitecture which imports geodata from OSM into Blender, a free 3D computer graphics software suite.

After installing the plugin and using it to create a new document, blender-osm links the user to an area selection website which makes it simple to select an area of the map to download.

We can copy/paste the lat/long area selection (in this case, a string like -74.02041,40.73327,-73.98792,40.75015) into the blender-osm interface and select which map layers to import (buildings, forests, water, etc.)

Blender

We end up with a detailed 3D model…

…but of course it looks better in perspective.

I knew I wanted to draw a multicolor print, so I grouped the downloaded layers by pen color. All the buildings went in one group, all primary roads in another, etc. Later I print these layers on the plotter one by one, swapping out the pen in between layers.

Using separate object collections means we can toggle on/off items by layer in the Blender UI. Here is a render of the map with only 3D buildings visible:

and another render of the map with only primary and secondary highways visible:

and another render of the map with only pedestrian roads visible.

Of course, we can render this for any combination of the layers.

The result is a 3D model in Blender which can be exported as a raster image or as an animation. But the pen plotter expects vector data, so we have to use a plugin.

Freestyle SVG Exporter

Freestyle is a Blender plugin which plots the edges of visible objects as SVG lines.

This is perfect for pen plotting, since pen plotters expect vector input.

Freestyle is very powerful but a bit hard to use. First I enabled it like so:

Then I played with the settings until it handled crease angles in the way I expected.

I also applied a Bezier filter which gave the finished edges a cartoonish curve.

It’s hard to tell the effects of these settings until Blender actually renders the scene to SVG.

Camera

Finally I played with the camera location and perspective settings until I had a scene composition I liked. The focal length of the virtual camera makes a big difference:

It is also possible to swap out a perspective camera for an orthographic one, which looks isometric like a video game. This is a nice effect but I felt it gave the scene some undesirable flatness.

SVG

The default exported PNG has both the raster image and the overlaid vector lines, which makes it easy to see why Freestyle drew lines in certain places.

The default exported SVG is what we eventually send to the plotter.

Layers

We can pop into the SVG file and separate the layers manually, since AxiDraw requires printing one SVG file at a time and cannot filter by layer. Here is the layer for buildings-only:

roads-only:

and highways-only:

Blender rendered these all in the same pass, so objects in the foreground correctly block objects in the background.

Foreground:

Background:

AxiDraw

That’s pretty much it. We can send each layer to the plotter one at a time, swapping out pen colors, and we know that objects in the foreground will appear to obscure objects in the background. Here is the final product:

OpenStreetMap with a Pen Plotter

Sun, 06 Feb 2022 00:00:00 -0400

I wrote some Rust code to render GeoJSON data to SVG for use with a pen plotter.

┌─────────────┐ ┌───────┐ ┌───┐ ┌───────┐
│OpenStreetMap├─►GeoJSON├─►SVG├─►Printer│
└─────────────┘ └───────┘ └───┘ └───────┘

Along the way I learned about OpenStreetMap, the Overpass API, the Overpass query language (OverpassQL), and a web-based interface for quickly trying out OverpassQL queries. I also wrote some trivial and some nontrivial geometry algorithms for point/segment/polygon collision, intersection, cropping, and crosshatching.

Background

Pen Plotters

I recently bought an AxiDraw V3/A3. AxiDraw is a line of pen plotters sold by Evil Mad Scientist.

The AxiDraw V3/A3 pen plotter is a numerical control machine with a large drawing area (16.93 × 11.69 inches), a surprisingly fast arm (15 in per second), and an unusually high precision (2032 steps per inch).

A pen plotter comes with general-purpose mount which you can tighten around any kind of writing implement.

I suspect you could mount something more exotic (watercolor, laser cutter, knife) if you wanted to. I mostly use pens and markers.

Pen plotters have been around since at least 1959. They generally inspect to be fed low-level instructions such as ‘go here’, ‘pen down’, ‘go there’, ‘pen up’, etc.

A modern pen plotter such as the AxiDraw V3/A3 comes with utilities for interpreting SVGs, reordering instructions for faster printing, estimating print time, controlling print speed to avoid ink blots, etc.

OpenStreetMap

OpenStreetMap began in the mid-2000s as an effort to create a Wikipedia-style repository of map data. It comprises a backend database for storing map data (locations, paths, areas, and associated information), a series of APIs for querying that information, a general-purpose web frontend for viewing map data (think Google Maps or MapQuest), and a large set of tools for inserting, editing, and retrieving data.

Overpass API

The Overpass API is an API for querying OpenStreetMap geodata. The easiest way to understand it is to

visit overpass-turbo.eu,
enter an example query such as (node(51.249,7.148,51.251,7.152);<;);out meta;
press ▶️ Run, and
press 🔎 to center the preview window around the returned data.

The example query above is written in Overpass QL, the Overpass query language. I find it a bit complex, but I understand that it’s very powerful.

Work

Generative Art

When I first started to use the pen plotter, I began by developing a set of low-level libraries in Rust for manipulating points, line segments and open/closed polygons in a vector format. I made some generative art with simple lines and curves:

(Most of this stuff is inspired by Sol LeWitt.)

This was a really good starting point. I began to rewrite some of my low-level libraries for more ergonomic usage (simpler construction of points and rectangles relative to each other, automatic centering, predictable cropping behavior) and began to squash floating-point bugs. I also started to write more complex generative art which required computing bounding boxes, line/line collisions, and other geometry problems.

Absolutely every problem I needed to solve here had a solution on Wikipedia (line-line intersection, line segment intersection). Vector graphics are well-understood and well-trodden territory.

Dealing with Geodata

Eventually I began to try to print OpenStreetMap data instead. I learned that plotting unprocessed lat/long data results in a squashed, stretched map, like so:

This is because points in geographic databases are generally stored as (latitude, longitude) (or, sometimes, (longitude, latitude)) pairs.

Because of issues with map projection and especially ESPG:3857 (the specific spherical mercator projection OpenStreetMap uses), areas further from the equator become more distorted.

I ended up building some utilities to rotate, scale, shift, and project the vector data. I often found that I would pull down map data, render a plot, and later decide that I wanted to zoom in a bit, or pan over a bit.

Layers and tags

Next I realized I wanted to use colored pens / colored markers to draw multicolor prints. It seems natural that streets might be one color, water another, etc.

OpenStreetMap tags all features with tags, which areconvention-driven key/value pairs. These might annotate some line as a highway or as a footway, or they might annotate an area as a park vs. a garden, etc.

I began to pull down geodata and process each element as a polygon, multipolygon, linestring, etc. while preserving the tags associated with that original bit of geodata. This let me apply colors, crosshatching, etc. first, then apply color and separate into layers near the end.

Crosshatching

I wrote a crosshatcher to transform a closed polygon into a set of straight lines which fill its interior with crosshatching at some spacing and angle.

Crosshatching is computational tricky – given some angle and distance, you have to find the set of all lines which could pass through the polygon and truncate each line into one or more line segments. Because the polygon isn’t necessarily convex, a given line might intersect the polygon zero, one, or more than one times. It might intersect the polygon along an edge, or precisely at a vertex. A crosshatch line might run along one of the edges of the polygon.

You can probably see in the print above that this algorithm used to fail whenever a crosshatch line was unfortunate enough to meet its surrounding polygon at a vertex rather than along an edge.

Deduplication

When plotting transit data, I found that the pen plotter spent a lot of time retracing its path. Transit data is very layered – the train going uptown, the same train going uptown express, the same train going downtown, etc. all occupy the same points and lines in space. When the pen plotter retraces its steps, the ink smears and bleeds in an ugly way.

Deduplication is another surprisingly hard problem. I ended up quantizing each point to a fine grid, hashing the data in order to deduplicate it, and then restoring the data to its original position.

Quantization is determined by the size of the underlying grid. If you make the grid too coarse, it mangles curved input data into blocky output data.

Conclusion

This is a pretty fun project. I ended up with a a very fast piece of software which can convert OpenStreetMap GeoJSON data into an SVG suitable for plotting. It’s easy to dial in an address or an area of land, toggle on and off layers, and produce a large, detailed print as a piece of art or a gift.

I plan to add some more interesting features – crosshatching is only one way to fill an area with a line, for example. I also think it would be really fun to plot data which has been stretched or transformed in some obviously mathematical way (projected onto a hyperbolic plane so that things get more dense further from the center, for example).

Simulated Annealing for Image Tracing

Mon, 18 Oct 2021 00:00:00 -0400

Github	https://gist.github.com/ambuc/3374d271444a303612d86d08801291be

I wrote a bit of Python to help “trace” an image (perform a raster-to-vector transformation) using simulated annealing.

If you already know about image tracing, image formats, and simulated annealing, feel free to skip ahead to work. Otherwise, read on.

Background

Image tracing

Raster images

Raster images (such as digital photos) are stored in the computer as grids of pixels. Since a raster image lives in a grid, it necessarily has a fixed size (number of pixels) and resolution (number of pixels per inch). Image resolution relates to how much detail a photograph has. An image with higher resolution can be printed larger before it begins to appear pixellated or blocky.

Here is a (low-resolution) raster image of a smiley face.

Vector images

Vector images are not grids of pixels. They are instructions to a graphics processor for visiting points, drawing lines between them, shading areas, etc. Since points and lines are stored in the vector format as floating-point numbers, vector images have dramatically higher resolution than raster images. They can be printed at arbitrary size without pixellation since they do not consist of pixels.

When a raster is enlarged, it becomes pixellated.

Rasterization

Rasterization refers to the process of converting a vector image to a raster image. This might be useful for rendering a vector to any destination which requires a grid of inputs such as an LCD screen or an inkjet printer. Rasterization is an interesting field full of optimizations (antialiasing or subpixel resolution) but it is essentially straightforward: we want to find a target raster which looks most like its source vector to the human eye.

Image tracing

Image tracing refers to the process of converting a raster image to a vector image. It is also essentially straightforward: we want to find the target vector which looks most like its source raster to the human eye.

But image tracing is inherently more imprecise since it involves extrapolating information from the raster which isn’t there. (i.e. image content from in-between pixels.)

Human-assisted image tracing. Note that some extra detail was extrapolated from the source raster.

Simulated annealing

Simulated annealing is an optimization technique inspired by a physical phenomenon, so let’s discuss the physical phenomenon first.

Annealing

Annealing is a metallurgical process for making metal more ductile (softer) by heating it up and letting it cool slowly.

Atoms in a metal packed regularly, semi-irregularly, and irregularly.

Metals usually consist of small regions of atoms called grains, where all the atoms in a grain are packed regularly. But adjacent grains are often misaligned (see the “polycrystalline” example above), leading to fracture lines called discontinuities.

When a metal is heated above some recrystallization temperature, bonds within the metal begin to break.

Cooling that metal again slowly heals fracture lines between grains, aligns adjacent grains with each other to create bigger grains, and eventually leads to a more regular (and more ductile) metal.

Simulated Annealing

Simulated Annealing is an optimization technique for finding a local maximum within some search space which is too large to search completely. It is named after metallurgical annealing.

Finding the maximum value of an irregular function using simulated annealing.

For a large and complicated search space where finding a maximum is sufficient (i.e. finding a short path between points but not necessarily the shortest possible), simulated annealing is a surprisingly effective technique.

In physical annealing, we raise and then slowly lower the temperature of a metal. In simulated annealing, temperature corresponds to the internal energy of the system, i.e. how often we spontaneously hop between candidate positions.

When simulated temperature is high, our cursor is flightier and hops between positions at random. As temperature lowers, we still seek out more optimal neighboring candidates, but our cursor “settles” and becomes increasingly unlikely to pick a new point at random.

Simulated annealing and other optimization techniques are complicated and interesting. Read much more about the techniques and history behind it here.

I won’t go into the math because this article is about a possible application of the technique rather than the technique itself.

Work

With a bit of simulated annealing, we can partially automate the process of image tracing.

Here are the four kinds of image we’ll deal with:

Source ( don't have ) Candidate ( we generate )
vector ( this data ) vector ( this candidate )
│ │
│ ( rasterized ) │ ( rasterized )
│ ( by someone ) │ ( by us )
│ │
▼ ▼
Source ◀────(compared to)────► Candidate
raster raster

The plan is as follows: We guess a series of candidate vectors and trivially rasterize them to produce a series of candidate rasters. Once we have generated a candidate raster which sufficiently resembles the source raster, we can assume its associated candiate vector also sufficiently resembles the source vector (which we cannot see).

Overview

Our whole algorithm runs in a loop:

 Initial guess
parameters
│
│
Guess new │
use as input ╭──► parameters ───┤ use them
for annealing │ │ to make a new
│ ▼
Fitness Candidate
▲ vector
│ │
compare to │ │ rasterize
target raster ╰─── Candidate ◀──╯ this to produce
to calculate raster a new

Eventually our measure of ‘fitness’ (more on that later) becomes sufficiently low and we decide that our candidate vector is close enough.

Caveats

Here are some of the important caveats:

we need a reasonable initial vector guess. This guess can be generated by a human or by some low-quality heuristic.
we need a very fast way to evaluate fitness. This is the bottleneck, i.e. the majority of the time spent in the loop will be spent doing this. (Running the annealing algorithm, generating vectors, and rasterizing images are all extremely well-optimized already.)

Worked Example

Take as a source vector this crude vector illustration of an ampersand, and as a source raster this even cruder rasterization.

Hopefully you can see that the raster image has lower resolution. If not, zoom in on both images until the one on the right becomes pixellated.

This is our source. Now let’s make a reasonable initial vector guess:

It doesn’t look very close. But it’s a good start.

As our simulated annealing cycle runs, we mutate each point in this initial candidate vector until the candidate raster image starts to look more and more like our source raster.

Until eventually we arrive at a final raster guess and a final vector guess.

Measuring image similarity

How do we measure image similarity?

Measuring image similarity, for humans

For a human, it’s really handy to look at two images with a red/blue overlay. (A red/blue overlay is a blend of two images where one input becomes the red channel of the output, and the other input becomes the blue channel of the output. Pixels which are present in both images are rendered black.)

Here are two overlays: one of the initial guess against the source image, and another of the final guess against the source image.

You can see that the initial guess (in blue) is quite poor. But our final guess is much better. You can see only a few blue or red edges peeking out.

Measuring image similarity, for computers

It might be tempting to define fitness as “number of black pixels in an overlay”. But it turns out that this definition has some serious shortcomings.

Under this scheme, if two shapes don’t overlap at all, it doesn’t matter how far apart they are. The pixel overlap of two squares with an inch between them is zero, but the pixel overlap of two squares with three inches betweeen them is also zero.

Put another way: if we measure fitness in this way, then we’re not rewarding incremental improvement.

Blur

The way around this is to blur both images before comparing them. Now we have a smooth transition between different colors in the image, so pixel overlap increases smoothly as our candidate converges.

There is obviously a sweet spot here. If you blur an image too much, then it becomes a mess and the annealing algorithms have no incentive to position the shapes precisely. If you blur them too little then you don’t get the benefit. This almost certainly needs to be tuned to the specific use case.

Conclusion

This is a powerful technique for a very specific set of circumstances and inputs. But I don’t think this is a useful general-purpose technique for image tracing, since most people who want to trace images want the entire task automated. And the application domain needs a very fast evaluation loop, so this is probably unsuitable for scripting heavyweight professional vector editors. But for certain circumstances, it seems like a fast way to fine-tune the contents of a vector.

Code

Here is some (lightly commented) code I used to perform the simulated annealing discussed in this article, as well as generate the illustrations above.

python


#!/usr/bin/python3
from PIL import Image
from scipy import optimize
from skimage import metrics
import cairo
import cv2
import numpy as np
import random
import scipy
import skimage
import tempfile
# Data class to hold lists of points, transform them, and print them to different kinds of images.
class DrawingData():
def __init__(self, list_of_points):
self._list_of_points = list_of_points
self._degrees_of_freedom = sum(len(p) for p in self._list_of_points)
# The width and height (in pixels) of the image.
self._dimension = 90
def transform(self, l):
# Apply a mutator lambda |l| to each point.
self._list_of_points = [l(p) for p in self._list_of_points]
def degreesOfFreedom(self):
# Return the number of degrees of freedom in the system.
return self._degrees_of_freedom
def applyDeltas(self, list_of_deltas) -> "DrawingData":
# Apply a list of floating-point deltas to each x and y coordinate in
# order. This application order must be consistent so that annealing
# converges.
return DrawingData([
(x + list_of_deltas.pop(), y + list_of_deltas.pop())
for (x, y) in self._list_of_points
])
def mutate(self, n=5) -> "DrawingData":
# Take each point and randomly displace it by up to |n| pixels.
deltas = [random.uniform(-n, n)
for _ in range(2*self.degreesOfFreedom())]
return self.applyDeltas(deltas)
def writeToPng(self, list_of_filepaths):
with cairo.ImageSurface(cairo.Format.RGB24, self._dimension, self._dimension) as surface:
ct = cairo.Context(surface)
ct.rectangle(0, 0, self._dimension, self._dimension)
ct.set_source_rgb(1, 1, 1)
ct.fill()
ct.set_line_width(10)
ct.set_source_rgb(0, 0, 0)
ct.move_to(*self._list_of_points[0])
for x, y in self._list_of_points[1:]:
ct.line_to(x, y)
ct.stroke()
for filepath in list_of_filepaths:
surface.write_to_png(filepath)
def writeToSvg(self, list_of_filepaths):
for filepath in list_of_filepaths:
with cairo.SVGSurface(filepath, 90, 90) as surface:
surface.set_document_unit(cairo.SVGUnit.PX)
ct = cairo.Context(surface)
ct.set_source_rgb(1, 1, 1)
ct.paint()
ct.set_line_width(10)
ct.set_source_rgb(0, 0, 0)
ct.move_to(*self._list_of_points[0])
for x, y in self._list_of_points[1:]:
ct.line_to(x, y)
ct.stroke()
def blur_image(image, s=(33, 33), f=10, n=0.5):
# Take an image, blur it, and return a blend of the original and blurred images.
# I think that this is slightly superior to the completely blurred image,
# since it preserves a sharp cliff at the boundary of the unblurred shapes.
return cv2.addWeighted(image, n, cv2.GaussianBlur(image, s, f), 1-n, 0.0)
def main():
# Pointwise drawing of an ampersand. I sketched this on paper on an 8x8 grid, so...
target_drawing = DrawingData([(6.3, 6.3), (5, 6), (2, 3), (1.5, 2), (2, 1), (3, .5), (4, .75), (4.5, 1.5),
(4, 2.5), (1.75, 5), (2, 6), (2.5, 6.5), (3.5, 6.25), (5.5, 5), (7, 3), ])
# ...we have to scale it up to fit on an 80x80 image.
target_drawing.transform(lambda p: (3 + (p[0]*10), 7 + (p[1]*10)))
target_drawing.writeToPng(['target.png'])
target_drawing.writeToSvg(['target.svg'])
# Keep track of the frame number, so that we can render a gif of only every
# tenth frame. (Otherwise we store too much data in memory, and the GIF
# takes too long to watch.)
global frame_num
frame_num = 0
frame_files = []
# This is the function scipy.optimize.minimize is minimizing, so it has to
# return fitness as a floating-point number.
def eval(ts, initial_guess_drawing, target_file):
global frame_num
frame_num += 1
guess_file = tempfile.SpooledTemporaryFile(suffix="png")
guess_drawing = initial_guess_drawing.applyDeltas(list(ts.tolist()))
guess_drawing.writeToPng([guess_file, "guess.png"])
guess_drawing.writeToSvg(["guess.svg"])
# Open both images, blur them, and return the mean squared error.
mse = skimage.metrics.mean_squared_error(
blur_image(cv2.imdecode(np.frombuffer(
guess_file._file.getbuffer(), np.uint8), -1)),
blur_image(cv2.imdecode(np.frombuffer(
target_file._file.getbuffer(), np.uint8), -1)))
# The image contents of tenth frame gets moved into a big list instead
# of garbage collected.
if frame_num % 10 == 0:
frame_files.append(guess_file)
else:
del guess_file
return mse
# This is a bit nontraditional -- we store target and guess images both on
# disk (for human analysis later) and in spooled temporary files, for very
# fast inmemory access.
with tempfile.SpooledTemporaryFile(suffix="png") as target_file:
target_drawing.writeToPng([target_file])
with tempfile.SpooledTemporaryFile(suffix="png") as init_guess_file:
init_guess_drawing = target_drawing.mutate(n=5)
init_guess_drawing.writeToPng([init_guess_file, 'init_guess.png'])
init_guess_drawing.writeToSvg(['init_guess.svg'])
# It typically takes 3-8 rounds before one converges. If a round
# doesn't converge within 1000 iterations (see `maxiter` below), we
# make another random guess and try some more.
round = 0
while True:
round += 1
# Reset our list of frames.
frames = []
for frame_file in frame_files:
del frame_file
frame_num = 0
# Make another random guess. These guesses are drawn from the
# initial random guess, so they are one step further removed
# from our source image.
random_start_drawing = init_guess_drawing.mutate(n=5)
r = scipy.optimize.minimize(
fun=eval,
# Since the set of parameters we're tuning are x/y
# translations for the points in the image, our intial state
# should be a vector of zeros.
x0=[0]*2*random_start_drawing.degreesOfFreedom(),
# COBYLA was experimentally selected. There might be better methods.
method='COBYLA',
args=(random_start_drawing, target_file),
# Also experimentally selected.
tol=0.000001,
options={
# Also experimentally selected.
'maxiter': 1000,
}
)
# If our image is within 20 pixels MSE (also experimentally
# selected), it is close enough.
if r.fun < 20:
print("Num Trials: ", round)
print("Success: ", r.success)
print("Minimum error: ", r.fun)
print("# Trials", r.nfev)
print("Tuned parameters", r.x)
break
else:
print("Minimum error: ", r.fun)
# Open each of the spooled temp files as a PIL image.
frames = [Image.open(f._file) for f in frame_files]
# Trim the back half of the list. We spent a lot of time fine-tuning this,
# which is important but uninteresting to watch in a GIF.
frames = frames[:int(len(frames)/4)]
# Render the list of images as a GIF.
frames[0].save('out.gif', save_all=True, append_images=frames[1:], loop=0)
# And finally clean up the images manually.
for f in frame_files:
del f
if __name__ == '__main__':
main()

video2anki: OCR for onscreen multilanguage audio captions

Mon, 12 Jul 2021 00:00:00 -0400

Github	https://github.com/ambuc/pleco-to-anki/blob/master/video2anki.py

Background

Pleco is an Android Chinese/English dictionary app. Users can look up and save words to a personal dictionary, and export an XML file containing those words and their definitions.

Anki is a flashcard app (and website) which implements spaced repetition. People use it to learn all sorts of things, but mostly languages.

Last year I wrote a custom pipeline which takes as input Pleco’s exported XML and produces as output a set of flashcards suitable for consumption by Anki. I could now mark a character or phrase in Pleco and expect to review it in Anki some time later that week.

Types of information in Anki

Anki presents information in the form of flash cards: given the front of some card, one is meant to recall the contents on the back. For the Chinese language, the important forms of a word are:

hanzi: written characters in the original script
pinyin: romanized characters which phonetically imitate the original pronunciation
meaning: usually a definition in English
audio: usually a recording of a human or machine speaking the word or phrase

Types of review in Anki

I configured Anki to help me review words and phrases in each of the following directions:

hanzi+meaning → pinyin+audio: (tests my ability to pronounce a word or phrase)
hanzi+pinyin+audio → meaning: (tests my ability to understand a word or phrase)
pinyin+audio+meaning → hanzi: (tests my ability to recall and write a character)
hanzi → pinyin+meaning+audio: (tests my ability to read, pronounce, and understand a character)
audio → meaning+pinyin+hanzi: (tests my ability to hear and understand a character)

Shortcomings

This process improved my reading and writing abilities for short words and phrases. But you can’t learn grammar from context-free words, and you can’t train your ability to hear and understand a full sentence from single words or phrases. What I want is a new kind of card:

audio → meaning+pinyin+hanzi: (tests my ability to hear and understand a sentence)

Resources

Many languages have large amounts of free educational content. Sometimes this free content comes with oncreen subtitles, which many people use while watching to check their understanding. To watch a piece of television and quiz myself as effectively as Anki, I would need to hide and show the subtitles while rewinding to the beginning of each sentence fragment. I found that this got in the way of learning, and made it difficult to review a large volume of material easily.

video2anki

My solution was this:

Import a video containing both Chinese-language audio and onscreen hanzi captions.
Determine the timestamps at which sentence breaks appear.
Extract the hanzi from the on-screen subtitles via OCR.
Extract the audio from the video.
Split the audio and the extracted hanzi by timestamp, creating pairs of audio fragments and written sentence fragments.
Format those pairs and import them into Anki.

I used Python because I knew all of the requisite libraries (video and audio manipulation, fast OCR, video anlysis for cutscene detection) would be available. This script only needs to run once per video, so performance is not a priority.

Consuming video

I used pytube to download the highest-resolution version of a video from YouTube.

python


from pytube import YouTube
yt = YouTube("some_youtube_url")
download_path = yt.streams
.get_highest_resolution()
.download(output_path="some_path")

Detecting scene transitions

I used pyscenedetect to detect scene transitions: points in time when some percentage of pixels change.

python


video_manager = scenedetect.VideoManager(["some_local_file"])
scene_manager = scenedetect.SceneManager()
scene_manager.add_detector(
scenedetect.detectors.ContentDetector(threshold=1))
video_manager.set_downscale_factor()
video_manager.start()
scene_manager.detect_scenes(frame_source=video_manager)
scenelist = scene_manager.get_scene_list()
imagepaths_by_scenenum = scenedetect.scene_manager
.save_images(scenelist, video_manager,
output_dir="some_output_directory", show_progress=True)
with open("some_output_file", "w") as f:
scenedetect.scene_manager.write_scene_list(f, scenelist)

I found that a threshold of 1 was necessary. I also found I needed to crop the video before running scene detection, since I didn’t want to detect when the speaker moved their hands or when the stock photo changed.

A low threshold meant I often accidentally inferred a scene transition mid-sentence. We deduplicate these later on.

One side-effect of cutscene detection is a dictionary which maps scene number to an individual midpoint frame from that scene. We can extract the image of the sentence from that frame.

Cropping the video

As mentioned above, I cropped the video before running scene detection.

I used ffmpeg to perform video manipulation. I also used ffplay to preview manipulation in real time before undergoing the expensive conversion process.

Specific crop geometry is expressed as a command of the form width:height:xoffset:yoffset. video2anki.py accepts a flag to tune the crop command so that I can preview the crop and tune the command when rerunning.

bash


CROP_COMMAND="in_w:in_h/3:0:1.9*in_h/3"
ffplay -i "<video_path>" -vf "crop=$CROP_COMMAND"
ffmpeg -i "<video_path>" -filter:v "crop=$CROP_COMMAND" -c:a copy "<output_path>"

OCR

Reading plaintext out of an image is called OCR (optical character recognition). There are many libraries and toolkits for doing this. I began with pytesseract, but found low-quality results. Small errors with image margin, spacing, and resolution often led to inaccuracies. I eventually found cnocr which had much higher accuracy for recognizing hanzi.

python


cn = cnocr.cn_ocr.CnOcr()
hanzi_obj = cn.ocr(img_fp=FOO)
hanzi_txt = ''.join(flatten([chrs for (chrs, _) in hanzi_obj]))
# Example: `汉字`

I decided not to use OCR to consume the pinyin from the image. Pinyin isn’t a real language, so there is no pre-trained OCR model which knows how to read its diacritics. I ended up pulling in another library (pinyin) to convert my extracted hanzi into pinyin.

python


pinyin_txt = pinyin.get(hanzi_txt, delimiter=" ").strip()
# Example: `hànzì`

Audio extraction

I needed to convert the downloaded video into an audio file. I have found that FLAC works as expected on every platform, so I encoded all audio clips to FLAC. I also found that ffmpeg required two passes in order to convert m4a video into flac audio.

bash


ffmpeg -i IN_PATH -c copy OUT_M4A_PATH
ffmpeg -i OUT_M4A_PATH -c:a flac OUT_FLAC_PATH

Audio clipping

I then needed to trim the audio file into sentence fragments. I used sox to perform audio trimming and compression.

python


fm = sox.Transformer()
tfm.trim(start_sec, end_sec)
tfm.compand()
tfm.build_file("input_file", "output_file")

Conclusion

Then we write the trimmed files to the Anki media collection, write a CSV with the audio path, the hanzi, the pinyin, and the source video, and import that CSV into Anki.

Here is a video recording in which I review a single card in Anki which was produced with this method. The video shows me opening a card and listening to the autoplayed audio. Then I type in what I think was said. Then I press “Show Answer”, and Anki presents a diff between my answer and the canonical one. Then I press the “Link” button and watch that sentence in the original video on YouTube.

Your browser doesn't support embedded videos, but don't worry, you can download it and watch it with your favorite video player!

Lion Wall: Building a character-matching game

Sun, 18 Apr 2021 00:00:00 -0400

App	https://jbuckland.com/games/lionwall

Background

Lion Wall is an online game inspired by Only Connect, a British TV quiz show. In the third round of Only Connect, contestants are faced with a four-by-four grid of cards. These cards can be grouped into four sets of four, where group is connected by some common thread.

An example “Connecting Wall” puzzle. The answer requires dividing the items into “Terms for zero”, “Poker terms”, “Flying ___” and “Things made of rubber”.

Red Herrings

To make the puzzle harder, some of the cards seem to belong to more than one category. In the example above, the category “Poker terms” applies to “Deuce”, “Bullet”, “Crab”, and “Cowboy”.

This category also seems as though it ought to apply to “Ace”, but “Ace” actually belongs to the category “Flying ___”.

On Only Connect, these cards are called red herrings.

Generalizing the Connecting Wall

I first wanted to lift this game out of the domain of English-language trivia.

Let each of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] represent a category in the abstract.
- The values [1, 2, 3, 4] will be special “real” categories. The others will be “red herring” categories.
Let a card consist of an unordered list of categories.
- Each card must contain exactly one of [1, 2, 3, 4].

I constructed a generalized Connecting Wall game:

[ [ (1, 5), (1, 6), (1, 7), (1, 8) ]
, [ (2, 6), (2, 7), (2, 8), (2, 9) ]
, [ (3, 0), (3, 7), (3, 8), (3, 9) ]
, [ (4, 0), (4, 5), (4, 6), (4, 9) ]
]

such that the special “real” categories [1, 2, 3, 4] are mentioned in exactly four cards each, with no overlaps, and the “red herring” categories [0, 5, 6, 7, 8, 9] are mentioned in three or fewer cards each.

If we wanted to map this generalized game back to an English-language trivia game, the real categories [1, 2, 3, 4] might become ["Terms for zero", “Poker terms”, “Flying ___”, “Things made of rubber”], and the red herring categories might become more loosely-defined categories such as:

“Starts with B” (Buttress, Bullet),
“Animal” (Crab, Fox, Fish, Goose-egg?), or
“Contains a repeating letter” (Goose-egg, Buttress, Bullet), etc.

Specifying for CJK characters

Many CJK characters consist of two subcomponents: if we map each of the categories 0-9 to a component, we can usually find characters which contain only those two components.

By hand

Before writing an automated solution, I stepped through the process of assembling a valid puzzle by hand. I picked ten common radicals and mapped them to the numbers 0-9:

0 九
1 疒
2 宀
3 犭
4 口
5 了
6 丁
7 主
8 由
9 示

Then, for each card in the generalized grid above, I tried to find a character which matched:

15 疒了 疗
26 宀丁 宁
30 犭九 犰
40 口九 㕤
16 疒丁 疔
27 宀主 宔
37 犭主 㹥
45 口了 𠮩
17 疒主 疰
28 宀由 宙
38 犭由 㹨
46 口丁 叮
18 疒由 㾄
29 宀示 宗
39 犭示 狋
49 口示 呩

This got me a valid puzzle:

疗 宁 犰 㕤
疔 宔 㹥 𠮩
疰 宙 㹨 叮
㾄 宗 狋 呩

This puzzle is unshuffled as drawn above. You can see that each character in the first row contains 疒; each character in the second row contains 宀; then 犭, then 口.

Automating

Similar to AutoCJK, I used the phenomenal resource IDS.TXT as a backing dataset. I reused the decomposition utilities from AutoCJK which know how to read/parse IDS.TXT. In short, running decomposer.Decomposer() returns a networkx digraph such that 子 and 宀 are ancestors of 字, and vice versa for descendants.

Then I wrote this script to generate valid puzzles.

python


from operator import itemgetter
from typing import *
import collections
import decomposer as decomposer_lib
import random
# Get the thirty most common radicals from the graph, weighted by how often
# they appear as subcomponents. (That's why we iterate thru predecessors(n)
# below.)
def most_common_radicals(graph) -> List[Text]:
common = collections.defaultdict(int)
for n in graph.nodes():
for k in list(graph.predecessors(n)):
common[k] += 1
res = dict(sorted(common.items(), key=itemgetter(1), reverse=True)[:30])
return list(res.keys())
# If a character is in the first Unicode CJK plane, it probably has a
# rendering in most web browsers. (This assumption is flawed.)
def has_rendering(i: int) -> bool:
return 0x4E00 <= i <= 0x9FFF
# Given a character, find the set of characters with which it shares a descendant.
# Example: 宀 and 子 are coparents of 字.
def coparents(graph, node): # returns set[node]
cpts = set()
for succ in graph.successors(node):
if not has_rendering(ord(succ)):
continue
preds = list(graph.predecessors(succ))
if len(preds) != 2:
continue
for pred in graph.predecessors(succ):
if not has_rendering(ord(pred)):
continue
if pred != node:
cpts.add(pred)
return cpts
# Given two nodes, returns a list of successors they share.
def children(graph, na, nb): # returns node
s = set.intersection(set(graph.successors(na)), set(graph.successors(nb)))
return list(filter(lambda c: has_rendering(ord(c)), list(s)))
class BoardBuilder:
def __init__(self, graph):
self._graph = graph
# This is the default game described above.
self._cells = [[[1, 5], [1, 6], [1, 7], [1, 8]],
[[2, 6], [2, 7], [2, 8], [2, 9]],
[[3, 0], [3, 7], [3, 8], [3, 9]],
[[4, 0], [4, 5], [4, 6], [4, 9]], ]
# Store our selected categories below.
self._extant = set()
def Build(self):
# Pick four "real categories".
[a, b, c, d] = random.sample(most_common_radicals(self._graph), 4)
# Assign these categories.
[self.assign(n, l) for n, l in zip([1, 2, 3, 4], [a, b, c, d])]
# Assign the red herring categories.
[self.assign(n, self.find_assignment(n)) for n in [5, 6, 7, 8, 9, 0]]
for r_idx, row in enumerate(self._cells):
for c_idx, [a, b] in enumerate(row):
# Pick a random descendant shared by the two components.
self._cells[r_idx][c_idx] = random.sample(
children(self._graph, a, b), 1)[0]
return self._cells
def assign(self, num, ch):
# Replace all instances of |num| with |ch| in self._cells.
for r_idx, row in enumerate(self._cells):
for c_idx, cell in enumerate(row):
for v_idx, v_val in enumerate(cell):
if v_val == num:
self._cells[r_idx][c_idx][v_idx] = ch
self._extant.add(ch)
# Given a category, what other categories share a card with it?
# Example: In the example above, neighbors(1) => [5,6,7,8].
def neighbors(self, num):
others = []
for r_idx, row in enumerate(self._cells):
for c_idx, cell in enumerate(row):
if num not in cell:
continue
others.append(list(filter(lambda n: n != num, cell))[0])
return others
# For our red herring categories, find a CJK character which can sit in for
# |num|, i.e. is a coparent with each of the neighbors.
def find_assignment(self, num):
others = self.neighbors(num)
coparents_list = [coparents(self._graph, o) for o in others]
candidates = set.intersection(*coparents_list)
candidates -= self._extant
return random.sample(list(candidates), 1)[0]
if __name__ == "__main__":
d = decomposer_lib.Decomposer()
for row in BoardBuilder(d._graph).Build():
print(row)

Running this script generates a valid, unshuffled puzzle such as 窠窒岤空洷溄江沚食仚仝企踉踝跮趾.

Making the game

Then I wrote a webpage which could consume these puzzles and display them in an interactive format. You can visit https://jbuckland.com/games/lionwall.html to play the game or you can view the source of the webpage to see how it works.

Semaphores

I wanted cards to animate (flip over, fade out, wait, reappear at the top of the page), but I didn’t want the UI to be interactive during those times. So I wrote a semaphore to ensure that the UI could not be changed while animations or timeouts were ongoing. My solution was a global counter semaphore and two methods:

a sleep() timeout which incremented the semaphore, ran the callback, then waited until it was done to decrement the semaphore, and
a ensureSemaphoreZero() blocker which waited until semaphore was 0 until running.

javascript


var semaphore = 0
function ensureSemaphoreZero() {
return new Promise(function (resolve, reject) {
(function waitForSemaphoreZero() {
if (semaphore == 0) return resolve();
setTimeout(waitForSemaphoreZero, 10);
})();
});
}
const sleep = (milliseconds) => {
semaphore++
return new Promise(resolve => {
setTimeout(resolve, milliseconds)
}).then(() => {
semaphore--
})
}

This let me chain sleep callbacks for running spaced-out animations:

javascript


sleep(100).then(() => {
// Manipulate the webpage.
sleep(100).then(() => {
// Once that's done, manipulate the webpage again.
})
})

But also react to keystrokes in a blocking way:

javascript


function onClickCallback() {
ensureSemaphoreZero().then(() => {
// React to callback.
});
}

Future work

I generated ~100 games for Lion Wall but I ought to go back and generate more. I could also make this game more like the Only Connect version, with a timer, limited guesses, and extra points for specifying the connecting themes.

Predicting CJK Character Shapes

Mon, 08 Mar 2021 00:00:00 -0400

Github	http://github.com/google/autocjk

AutoCJK is a tool for generating low-resolution predictions of uncommon CJK characters, given full-width images of their components.

Example:

Left-to-right: (a) source left-hand component, (b) source right-hand component, (c) expected composition, (d) predicted composition, and (e) (c) / (d) difference.

NB: If you already know about the Chinese language, feel free to skip the Background section and read onwards, starting from AutoCJK below. Also, if you already know about the Chinese language and notice something below is wrong, please open an issue against this repository and let me know!

Background

Chinese Language

The written Chinese language comprises tens of thousands of logograms (汉字; hànzì), each with a (non-unique) pronunciation and meaning. Hanzi are used in many other East Asian scripts. CJK scripts are usually fixed-width, and character proportions and spacings exist on a regular grid.

It is often useful to think of Hanzi as “decomposing” into radicals (部首; bùshǒu), which can be combined to create all other characters. The most common system of radicals is the set of 214 Kangxi radicals (康熙部首; kāngxī bùshǒu). ¹

Radical composition

Radicals compose in about a dozen regular ways to form new characters. A new character produced by one of these compositions is often phonetically or semantically linked to one of its components, but this is not always the case.

Two radicals can be composed horizontally (女 + 子 = 好) or vertically (几 + 木 = 朵). ²
Three radicals can be composed horizontally (氵+ 方 + 字 = 游) or vertically (日 + 罒 + 又 = 曼). In the horizontal case, it is common for two adjacent radicals to first combine into another character (方 + 字 = 斿; 氵+ 斿 = 游).
One radical can fully surround another (囗 + 玉 = 国).
One radical can surround another from above, (门 + 日 = 间), from the left (匚 + 矢 = 医), or from below (凵 + 乂 = 凶) (but never from the right).
One radical can surround another from the upper-left (广 + 木 + 床), from the upper-right (丁 + 口 = 可), or from the lower-left (辶 + 文 = 这) (but never from the lower-right).
Finally, two radicals can be overlaid. Overlaid compositions are generally ambiguous: for example: 一 + 木 = 未, but also 一 + 木 = 末. Note the widths of the horizontal strokes in each resultant character.

As can be seen from the 未 vs. 末 distinction above, there is sometimes more than one way to compose the same pair of components. Clearly, composition should be seen as a way to understand complex characters, rather than the way to parse and understand these characters.

Finally, composition is often recursive. Examine the sequence: (乛 + 头 = 买, 十 + 买 = 卖, 讠+ 卖 = 读). Composition depth rarely exceeds four or five levels.

How many Chinese characters are there?

A newspaper often contains between 2,000 and 3,000 unique characters. An educated Chinese person knows around 8,000 characters. A standard Chinese dictionary contains around 20,000 characters. A comprehensive Chinese dictionary contains around 80,000 characters.

Chinese and Unicode

Unicode is an international standard for encoding text. Here, ‘encoding’ means associating each character with a unique number. Unicode is divided into disjoint ranges called “blocks”, which usually group characters by script or by language. New blocks are released over time as the Unicode standard evolves.

In 1992, the Unicode consortium released an initial CJK³ block, titled CJK Unified Ideographs. This block contains around 20,000 code points representing common CJK characters. Unicode continues to release “extension” blocks containing less-common characters; these blocks are named CJK Unified Ideographs Extension A, CJK Unified Ideographs Extension B, etc. and act as supplements to the original 20,000 characters. Later blocks tend to contain CJK characters of increasing rarity.

As of 2020, there are around 93,000⁴ CJK unified ideographs in Unicode. Around two-thirds of all the code points in Unicode are reserved for CJK characters.⁵

Kangxi radicals and Unicode

Even though Unicode aims to include most CJK characters, there will always be rare characters such as place names and proper nouns which do not appear in Unicode.

Unicode offers a system called IDS (Ideographic Description Characters) which helps express (but not render) rare CJK characters.

IDS is a set of ideographic description characters. An ideographic description character might represent the act of joining characters horizontally, vertically, etc. These characters can be rendered as dotted-line divisions of a unit square (ex: ⿰, ⿱, ⿲, ⿳, ⿴, …)

A series of glyphs combined by ideographic description characters is known as an ideographic description sequence.

Thus a character like 好 can also be expressed as ⿰女子. This is a useful tool for communicating rare characters, but does not help in actually rendering them.

Why doesn’t the Unicode standard adopt a compositional model for encoding Han ideographs? Wouldn’t that save a large number of code points?

In short, Unicode decided that the burden on font authors and the difficulty of “normalization”, i.e. transforming characters into a normalized form to allow for searching and comparison, was too great. For a more detailed answer, see the original question and answer from the Unicode CJK FAQs.

Ideographic description sequence shaping

Since Unicode prefers individual code points over composition, fonts and the platforms which enable them (Opentype, Truetype, etc.) generally do not implement “ideographic description sequence shaping”, i.e. the process of rendering “⿰女子” as “好” at display time. Instead we rely on Unicode to provide code points for the most common characters, and on font authors to provide renderings for those characters.

Complications of CJK Font Rendering

Since modern text encoding for CJK characters is non-compositional, font authors need to create a rendering for each individual character in question. As noted above, there are (currently) around 93,000 CJK unified ideographs. Due to the number of characters and the difficulty of researching and creating character renderings, most fonts lag behind the latest Unicode releases by several years. ⁶

Why? CJK font design often tries to faithfully replicate the way natural handwriting works: adjacent strokes are joined, complex radicals take up more space than simple ones, and very complex radicals get simplified. These complications occur naturally in handwriting, but are often difficult to represent algorithmically.

Here are some examples of complications:

Complication 1: Variable-proportion radicals

A character made up of components rarely gives the same amount of space to each component. Often these changes in proportion occur in response to the relative complexity and rarity of the components.

Examples:

When the left component of a character is less dense than the right component, the right component will take up around ⅔ of the horizontal space. (讠+ 吾 = 语).
When the left and right components of a character are of equal density, each component will take up around ½ of the horizontal space (身 + 朵 = 躲).
When the left and right components of a character are the same, each component will take up around ½ of the horizontal space (月 + 月 = 朋).
When the top and bottom components of a character are the same shape, they will often “nest”. (Example: 夕 + 夕 = 多) This helps squash the overall character to better fill out a square.

These are just a few of dozens of rough guidelines, each with exceptions. Radicals can be squashed, stretched, scaled, and translated (although never rotated) during composition.

The exact proportions and placement of radicals is not regular. I personally don’t believe there is an algorithm for deriving them. But, as you will see in the next section, we can approximate one.

Complication 2: Variable-form radicals

Often radicals will change form as well as proportion when composed.

When 刀 appears on the right, it can be written as刂 (as in 刖). (Exception: 切.)
When 人 appears on the left, it can be written as 亻(as in 他). (Exception: 从.)
When 手 appears on the left, it can be written as 扌(as in 扡). (Exception: 拜, or 帮.)
When 心 appears on the left, it can be written as 忄(as in 快).
When 水 appears on the left, it can be written as 氵(as in 池).
When 火 appears on the bottom, it can be written as 灬 (as in 黑).
When 犬 appears on the left, it can be written as 犭(as in 猪).

These are just a few examples from a longer list. Like written English’s “i before e except after c”, these rules tend to have as many exceptions as they do examples.

Because some radicals change form when they change form (i.e. 火 => 灬, as seen above), the IDS rules are flexible. You could write ⿱占火 to mean 点, but you could also choose to specify ⿱占灬 = 点.

The Long Tail

There is a long tail of characters in the CJK Unified Ideographic Extension blocks which (a) have a Unicode representation, but (b) don’t yet have a rendering in most fonts. A font which fails to implement CJK Unified Ideographic Extension blocks B through G is missing roughly 65,000 characters. ⁷ This gulf mirrors the difference in characters between a standard Chinese dictionary and a “complete” Chinese dictionary. These characters are disproportionately likely to be proper nouns, place names, and other rare words.

AutoCJK

I wrote and published AutoCJK a tool which can predict what composite CJK characters should look like. These predictions take the form of low-resolution raster images, which, while unsuitable for use in fonts, can be a useful input for a font design tool (more to come on that later).

Generative adversarial networks (GANs)

AutoCJK uses a GAN which is based on Pix2Pix. Pix2Pix is a generative adversarial network (GAN). In a GAN, two neural networks train to fool each other: one network trains to produce accurate, realistic examples like those in the dataset in order to fool the discriminator, which trains to more accurately differentiate between real elements and the generated examples. Once a GAN is trained, the generator can be used to produce novel outputs similar to, but not the same as, those in the input dataset. GANs are often used to create images.

Thinking about faces actually led me to the approach of using a GAN. Faces and CJK characters are similar in a few ways: both are roughly visually balanced, both are easily recognizable, and both have both macro- and micro-scale features which contribute heavily to their apparent realism. When it comes to computationally generating new faces, even a tiny mistake can betray an image’s inauthenticity.

In short, faces and CJK characters both seem to follow subtle rules which don’t cleanly fit into an imperative algorithm but which nonetheless can be generally predicted.

Generating custom training data

I fed the GAN a custom dataset⁸ of images of CJK characters and their decompositions.

Take U+3416 㐖 as an example.

This character can be decomposed as ⿰吉乚; it is a vertical composition of U+5409 吉 and U+4E5A 乚.

When I trained the GAN on a particular font, I rendered all three characters in that font and produced an image with 吉, 乚, and 㐖 side-by-side:

I refitted the Pix2Pix tutorial to accept a 256x256x2 input image and predict a 256x256x1 output image.

The input image was two 256x256 greyscale bitmaps of the full-width input characters. In the example above, picture the superposition of the first two thirds of the image, i.e. the segments containing 吉 and 乚.

By “superposition” I just mean that there were two layers to the image. (These are layers you could use to hold red / blue / green in a color image, for example.)
The output image was one 256x256 greyscale bitmap of the full-width output character. In the example above, picture the right third of the image, containing 㐖.

The vast majority of the Pix2Pix model was unchanged in AutoCJK’s model.

Training and using a model

The v1 model currently published as a part of https://github.com/google/autocjk was trained for around 48 TPU-hours.

This model is definitely not perfect. The rasters it generates have rough edges, and the proportions and kerning between the components are biased towards the styles of the fonts I trained it on (in this case, zh-CN). Over time I will revisit this model and experiment with loss functions, higher and lower resolution predictions, etc.

The model was trained on a large number of Noto CJK fonts, but is by no means limited to predicting outputs given inputs from that particular font. I found cachebusting (testing with inputs not in the training data) very useful while building confidence in this model.

In some cases this meant rendering character pairs not in the training data. In other cases this meant using fonts not in the training data. The thumbnail image is actually trained from glyphs downloaded from GlyphWiki.

For instructions on installing and running AutoCJK, see the README.md and the installation wiki.

Acknowledgements

I would be remiss if I didn’t mention Andrew West (魏安)’s dataset which offers per-character decomposition for all 92,856 CJK unified ideographs defined in Unicode version 13.0. This extraordinary resource powers the character de/composition algorithm which underlies the training image generation utility.

Kangxi radicals were developed as an indexing system in the 1600s, but Chinese indexing systems are at least two millennia old. ↩︎
]: Sometimes (but not always) the left half of a character has some semantic hint at the meaning, and the right half of a character has some phonetic hint at the pronunciation. ↩︎
In Unicode, characters which are used across many East Asian languages are broadly termed CJK, which stands for Chinese-Japanese-Korean. ↩︎
See https://en.wikipedia.org/wiki/CJK_Unified_Ideographs. ↩︎
See https://www.unicode.org/faq/han_cjk.html#16. ↩︎
See https://github.com/googlefonts/noto-cjk/issues/13 and https://github.com/adobe-fonts/source-han-sans/issues/222. ↩︎
The characters in these extension blocks are unevenly distributed across traditional and simplified Chinese scripts as well as Japanese, Korean, Vietnamese, and other East Asian scripts. ↩︎
You can generate training data like it with make_dataset.py and some local fonts of your own. ↩︎

Anki flash cards with audio

Sat, 09 Jan 2021 00:00:00 -0400

Github	http://github.com/ambuc/pleco-to-anki

Here I discuss how I got audio samples working in Anki (for Mac OS X) and AnkiDroid (for Android).

Using `say`

Mac OS comes with a text-to-speech utility, say. Say supports a few voices, many of which are tailored to specific languages. I ran:

bash


$ say -v "?" | grep zh_
Mei-Jia zh_TW # 您好，我叫美佳。我說國語。
Sin-ji zh_HK # 您好，我叫 Sin-ji。我講廣東話。
Ting-Ting zh_CN # 您好，我叫Ting-Ting。我讲中文普通话。

It looks like Ting-Ting is the best match, since I want to render audio with a mainland Chinese accent. So we can render and save an audio sample with:

bash


/usr/bin/say -v Ting-Ting "拼音" -o ~/path/to/output

I wanted to avoid the cost of converting the generated audio file, since there would be as many unique files as there are flash cards. I used .flac since it was the only format which say can natively render on Mac OS X and which Android (and, by extension AnkiDroid, running on Android) can open.

Saving to Anki

Anki looks for media at a path which varies per-platform. Since I’m on Mac OS X, I need to save my samples to ~/Library/Application Support/Anki2/User 1/media.collection/<file>.flac.

In Anki, you can use the special embed syntax [sound:<file>] which renders a system-native audio player. If the field containing that embed is on the front of a card, it will play when the card first appears; otherwise it will play when the reverse of the card is revealed.

Conclusion

I ended up writing this behavior directly into pleco-to-anki, which now generate the audio samples, save them to ~/Library/Application Support/Anki2/media.collection, and generate a .csv with a column containing embed syntax as specified above. You may need to adapt this workflow for your own platform and card/field format.

A Pleco-to-Anki flash card creator

Fri, 27 Nov 2020 00:00:00 -0400

Github	http://github.com/ambuc/pleco-to-anki

Background

When I am learning a new word in Chinese, I usually look it up in Pleco and hit the [+] button to create a flash card. Pleco is extremely useful for generating flash cards, but I prefer to use Anki, which lets me review those flash cards using spaced repetition.

Both Pleco and Anki have Android apps, but there is no native interface between them. Pleco exports a complex XML file with a lot of metadata. Anki expects to import a CSV file which maps to your custom note.

Anki

In Anki terminology, a note is a set of two or more fields:

# type: Note
French: Bonjour
English: Hello
Page: 12

and a card is a view into that note via a card type:

# type: Card Type
Q: French
A: English<br>
Page #Page

# type Card
Q: Bonjour
A: Hello
Page #12

It is normal to have a few card types, which represent a few views into that note which you are trying to memorize.

Anki for Chinese

My Chinese-language notecards have three fields:

# type: Note
characters: 苹果
pinyin: <font color="green">píng</font><font color="blue">guǒ</font>
meaning: noun apple

where the characters field contains CJK unicode, and the pinyin field is HTML. Anki will render these fields correctly on web and mobile.

I have four card types:

Q: characters + meaning
A: pinyin
Q: characters + pinyin
A: meaning
Q: pinyin + meaning
A: characters
Q: characters
A: pinyin + meaning

It doesn’t make sense to have a card where Q: pinyin, since the question is ambiguous – there are many words and characters with the same pronunciation. I think it also doesn’t make sense to have a card where Q: meaning, since there are many ways to say the same idea in each language.

Problem statement

In Pleco, a flash card looks like this:

Pleco can export your set of saved flash cards, but it does so as XML:

xml


<?xml version="1.0" ?>
<plecoflash formatversion="2" creator="Pleco User -1" generator="Pleco 2.0 Flashcard Exporter" platform="Android" created="1605883885">
<categories/>
<cards>
<card language="chinese">
<entry>
<headword charset="sc">感冒</headword>
<headword charset="tc">感冒</headword>
<pron type="hypy" tones="numbers">gan3mao4</pron>
<defn>noun common cold verb 1 catch cold 2 dialect be interested in; like (usu. used in the negative)</defn>
</entry>
<dictref dictid="PACE" entryid="21428224"/>
</card>
</cards>
</plecoflash>

where each <card> entry is a rich object with (1) sc (simplified Chinese) and tc (traditional Chinese) characters, (2) a pinyin string in which the numeral following a syllable denotes its tone, and (3) a dictionary definition.

Anki, on the other hand, prefers to import data as a CSV (comma-separated or semicolon-separated is fine), where each columns maps to a field in the destination note. The above example as CSV might look like:

csv


<span><font color="blue">găn</font></span> <span><font color="purple">mào</font></span>;感冒;noun common cold verb 1 catch cold 2 dialect be interested in.

This might render in Anki like so:

Solution

I wrote pleco-to-anki, a Python script which converts an XML file with a plecoflash object to a CSV file suitable for import.

Requirements

I want to test myself on a character’s tones, but I don’t want to use the style of pinyin in which tones have numbers. I prefer to read the tones as diacritics over vowels, i.e. the pinyin for 苹果 should appear as píngguǒ, not ping2guo3.
I like the convention where syllables are colored based on their tone. Everyone has their own convention, but for me red=flat, green=rising, blue=u-shaped, purple=falling, and grey=neutral. I want these flash cards to have colored pinyin syllables, but not colored Chinese characters.

Gotchas

u and ü are two different vowels in pinyin and the difference must be preserved. For example, 旅游 can be written as “lǚyóu”: note the diaeresis (¨) and háček (ˇ) over the letter ‘u’.
The dictionary definition which Pleco provides often repeats the Chinese characters: it is unsuitable as a question if it contains or hints at the answer.

Conclusion

Hopefully pleco-to-anki can benefit you as well as me. Please leave me a PR or open an issue if you catch a bug or encounter difficulty using this tool.

Latis, a command-line spreadsheet toy

Fri, 03 Jul 2020 00:00:00 -0400

Github	http://github.com/ambuc/latis

Background

I wrote a command-line spreadsheet toy in C++. It renders as a TUI and implements an Excel-like grammar for defining formulae. The full source is here.

Design

In-scope for this project:

Designing an ABNF grammar
Writing a system for lexing, parsing, and evaluating user input.
Writing a TUI for rendering spreadsheets interactively.
Using C++. (Mostly to learn about OSS Bazel, absl, and protobuffers.

Out-of-scope:

A fully-featured spreadsheet app which is easy to use or interoperates with other spreadsheet formats.

Design Overview

A spreadsheet program needs to have individual cells, each of which either has:

a typed value (a string value, a numeric value, or a monetary value, to name a few) or
a formula which is dependent on zero or more cells and which returns a typed value.

User input must be lexed (broken up into a series of meaningful tokens), parsed, (turned from a series of tokens into a data structure via a formal grammar), and evaluated (rendered to a typed value). The degenerate case of this lex-parse-evaluate pipeline is a single typed value.

The program must also maintain a graph of cells and their dependencies on each other. If cell A depends on cell B, and cell B is updated, the rendering of cell A (but not its underlying formula) must also be updated. Furthermore, cells depending on A must be updated, and so on and so forth.

Finally, there should be some decoupling between the spreadsheet data structure and the onscreen contents. This design problem is often solved using the MVC pattern, and was far and away the most complex part of this project, since I foolishly insisted on using C++ and writing myself not only the spreadsheet but the underlying MVC tools and frameworks.

ABNF Grammar

As mentioned above, a spreadsheet which can lex, parse, and evaluate user input must attempt to understand that input according to a grammar. I chose to design a grammar using ABNF, which is a manner of specifying grammar using some rules. ABNF already defines some bottom-level terminal values (numerics, literals, etc.) which make defining a grammar easier. Here is the grammar I ended up with:

Notes on ABNF:

Anything in double quotes is a literal, i.e. - might mean a range of values, but "-" means the literal - character.
Anything on a line after ; is a comment.
%c means a single text character.
%d means a decimal digit.
0-9 means a range of values.
<a>*<b>e means between a and b instances of e. If a is not specified, the default lower bound is 0. If b is not specified, the default upper bound is infinity. So 1*e means one or more instances of e.
<a>e means e exactly a times.
X / Y means either X or Y.
[e] means that e is optional, i.e. shorthand for 0*1e.

DIGIT = %d0-9
DATE_FULLYEAR = 4DIGIT
DATE_MONTH = 2DIGIT ; 01-12
DATE_MDAY = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on month/year
TIME_HOUR = 2DIGIT ; 00-23
TIME_MINUTE = 2DIGIT ; 00-59
TIME_SECOND = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second rules
TIME_SECFRAC = "." 1*DIGIT
TIME_NUMOFFSET = ("+" / "-") TIME_HOUR ":" TIME_MINUTE
TIME_OFFSET = "Z" / time_numoffset
DATE_TIME = DATE_FULLYEAR "-" DATE_MONTH "-" DATE_MDAY "T"
TIME_HOUR ":" TIME_MINUTE ":" TIME_SECOND [TIME_SECFRAC]
TIME_OFFSET
UPPERCASE = %c"A"-"Z"
ALPHANUMERIC = 1*(UPPERCASE / DIGIT)
INT_NUMERIC = 1*DIGIT
DOUBLE_NUMERIC = *DIGIT "." *DIGIT
NUM_VAL = INT_NUMERIC |
DOUBLE_NUMERIC
CURRENCY_ENUM = "USD" / "SEK" / ...
CURRENCY_VAL = NUM_VAL CURRENCY_ENUM
STR_VAL = "\"" *e "\""
ROW_INDICATOR = 1*DIGIT
COL_INDICATOR = 1*UPPERCASE
LOCATION_VAL = COL_INDICATOR ROW_INDICATOR ; A1
RANGE_VAL = COL_INDICATOR ":" COL_INDICATOR ; A:B
/ LOCATION_VAL ":" ROW_INDICATOR ; A1:3
/ LOCATION_VAL ":" LOCATION_VAL ; A1:B3
BOOL_VAL = "True" / "False"
VAL = CURRENCY_VAL / DATE_TIME / NUM_VAL / STR_VAL
/ LOCATION_VAL / RANGE_VAL / BOOL_VAL
FN = 1*(ALPHANUMERIC / "_")
EXPR = VAL ; 4
/ "(" EXPR ")" ; (5)
/ "(" EXPR FN EXPR ")" ; (1+1)
/ FN "(" EXPR *( "," EXPR) ")" ; POW(2,4,6)
/ EXPR "?" EXPR ":" EXPR ; cond ? val1 : val2
GRAMMAR = "=" EXPR

Lexing

When lexing, we convert a string of user input into a linear sequence of meaningful tokens. Things get very verbose at this stage. We define an enum T of possible lex types, and store tokens as:

c++


struct Token {
enum T {
equals, // =
period, // .
...
};
T type
std::string_view value;

where each Token holds a reference to the substring of user input it represents.

For example, lexing might turn a string like:

=POW(4.605, 2)
00000000001111
01234567890123

into a sequence of tokens like:

substring	type	start	length
`=`	`T::equals`	0	1
`POW`	`T::alpha`	1	3
`(`	`T::lparen`	4	1
`4.605`	`T::numeric`	5	5
`,`	`T::comma`	10	1
`2`	`T::numeric`	12	1
`)`	`T::rparen`	13	1

By passing around types and underlying substrings, we can parse the contents of alphanumeric tokens lazily, i.e. only when necessary.

Note on std::string_view

std::string_view represents a read-only view into an existing character buffer. So long as the underlying string doesn’t vanish, the constructed string_view is a small data structure suitable for passing by-value (or mutating in-place) without the overhead of copying an arbitrary-length string.

Parsing

Parsing is the process of taking a series of lexical tokens (as described above) and generating a useful data structure (read: tree) which can be stored, traversed, evaluated, manipulated, and displayed. This process happens hand-in-hand with the grammar defined above, and some tools can read ABNF grammars or other regular grammars and spit out parsers. I chose to hand-roll my own. This was the most challenging and educational aspect of this project by far.

Parser combinators

I used the parser-combinator style; that is, I wrote a set of low-level parsers (one which parses into a character, one which parses into a number, etc.) and then a set of higher-order parsers, which combine two or more parsers and return a new parser.

Before we get into how this works, we need some background on absl::Status, StatusOr<T>, absl::Span, absl::variant, and absl::bind_front.

absl::Status

absl::Status is a C++ error handling class which encapsulates a typed error (kInvalidArgument, kPermissionDenied, etc.) and a human-readable string payload.

`???::StatusOr<T>`

::StatusOr<T> is the sum type of a value of type T and an absl::Status. It doesn’t exist (yet!) in absl, but other OSS libraries hint at its existence. Since my project already imported "google/protobuf", I decided to use "google/protobuf/stubs/statusor.h", which exposes ::google::protobuf::util::StatusOr<T>. One day this may be a part of absl.

`absl::Span`

absl::Span is the same idea as std::string_view, only it applies to other containers beyond strings. Think of it as a read-only view into a container. Notably, it can be passed by-reference or mutated in-place.

`absl::variant`

absl::variant is a union type of one or more typed values. It holds exactly one value of one of its types. So a value of type absl::Variant<int, double> numeric could hold either an integer or a double.

One could use std::get<int>(numeric) to access the underlying integer type, but std::get excepts (std::bad_variant_access) if the underlying variant holds a type other than the one specified. Instead it is idiomatic to use the visitor pattern:

c++


struct Visitor {
void operator()(const int& i) const {
std::cout << "Int: " << i;
}
void operator()(const double& i) const {
std::cout << "Double: " << i;
}
};
absl::variant<int, double> numeric = 123.456;
Visitor visitor;
absl::visit(visitor, numeric); // Prints "double: 123.456";

This is a little complicated, but the benefits outweigh the costs.

`absl::bind_front`

Finally, absl::bind_front and std::bind_front both implement partial function application. Here is an example:

c++


// |minus| is a function with two arguments.
int minus(int a, int b) {
return a - b;
}
// But |fifty_minus| is a function with only one argument;
auto fifty_minus = std::bind_front(minus, 50);
int fifty_minus_three = fifty_minus(3); // outputs 47.

We can use this to stage partially-evaluated methods which already have their first n arguments and are waiting on their last m arguments, and can be thunked later.

Back to Parser Combinators

What is a Parser?

If a lexer spits out a vector of tokens, define a using TSpan = absl::Span<const Token>, where a TSpan is a mutable span of immutable tokens. That is, it is a sliding window which can be slid to any starting node and length, but there is no risk of mutating the underlying tokens.

In Latis, a parser has this type:

c++


template <typename T>
using Prsr = std::function<StatusOr<T>(TSpan *)>;

that is, a parser takes a pointer to a TSpan, may mutate that TSpan in-place, and returns either a value of type T or an absl::Status explaining why it was unable to parse the input.

NB: This parser definition attempts to parse the head of some input, not the entire body. A successful parse will truncate the token span, leaving a shorter span suitable for running through anothe parser.

What is a Parser combinator?

A parser combinator is a higher-order function; it accepts as arguments one or more function(s) and returns another function.

Here are some existing parsers:

c++


StatusOr<int> ConsumeInt(TSpan *tspan);
StatusOr<double> ConsumeDouble(TSpan *tspan);

And here is a parser combinator:

c++


template <typename... O>
static std::function<StatusOr<absl::variant<O...>>(TSpan *)>
AnyVariant(StatusOr<O>(TSpan *)>... ls);

This parser combinator (named AnyVariant) uses variadic templates to accept a series of any number of parsers (i.e. any number of inputs of type StatusOr<O>(TSpan *), and returns a parser whose return type is absl::variant<O...>.

We can use a parser combinator like AnyVariant to write a parser which attempts to parse the input as either an int or a double:

c++


StatusOr<absl::Variant<double, int>> ConsumeNumeric(TSpan *tspan) {
return AnyVariant<double, int>(
absl::bind_front(&ConsumeDouble, this),
absl::bind_front(&ConsumeInt, this))(tspan);
}

NB: Recall that AnyVariant<O...>(...) itself returns a parser. So we need to call it like so: AnyVariant<O...>(...)(...).

Other useful parser combinators:

In addition to AnyVariant, I also wrote:

Any<T>, which takes one or more parsers of type T and returns one parser returning type T, which atempts to match the parsers in priority order.
Maybe<T>, which takes exactly one parser and returns another lenient parser, which reads from TSpan but does not fail if it fails to match. This is useful for implementing optional aspects of the grammar, such as TIME_SECFRAC in the timespec.
WithRestriction<T>, which takes exactly one parser and an filtering function, and returns a parser which only returns a value of type T if it passes that filtering function. This is useful for introducing logic into our parser, such as recognizing a numeric value as representing a number of hours if and only if it is in the range [0-24].
InSequence<std::tuple<O...>>(Prsr<O>...), which takes a sequence of parsers and attempts to match them all, in-sequence, returning a std::tuple<> of their outputs. This is useful for matching all-or-nothing of a subgrammar, such as datetime specifications, which are only valid if they match the entire DATE_FULLYEAR-DATE_MONTH-DATE_MDAY... grammar. Otherwise this returns Status, and we do not truncate the TSpan.
WithTransformation, which is like WithRestriction, except it takes exactly one parser and exactly one transformation function which can convert the parsed value to some other value of some other type.
WithLookup, which accepts exactly one parser and exactly one lookup function. It is useful for looking up the returned value as the key in some map and returning its value instead. It can be thought of as a synonym for WithRestriction where the restriction is being-in-the-map, and WithTransformation where the transformation is to-the-matching-value-in-the-map.

The full list of combinators (and their implementations) lives here: https://github.com/ambuc/latis/blob/master/src/formula/parser_combinators.h.

Parsing, altogether.

In the end we compose many parser combinators and parsers into one big function, which accepts user input and outputs a data structure (actually a protobuffer) which contains nested formulae, expressions, values, string literals, and table lookup locations.

Evaluation

Evaluation is comparatively simple: we walk the data structure described above and “crunch” the component parts. If a node is a table lookup, we perform that lookup (or fail). If a node is a mathematical expression, we evaluate that expression.

In practice this means translating MINUS(A4, A3) -> 3.4 - 1.2 -> 2.2. This is relatively simple.

TODO(ambuc): Write about the MVC part.

Rendering the Julia set in Golang

Sun, 17 Nov 2019 00:00:00 -0400

Github	https://gist.github.com/ambuc/a36d007d177c7dd90153dc9ab174ee12

Introduction

In anticipation of Advent of Code 2019 I decided to brush up on http://golang.org/. I had written a crypto (codebreaking, not currency) library in Go in 2016 but I didn’t remember much of it.

The Julia set

The Julia set is a fractal. It can be rendered by, for each point $(x,y)$ in a grid (ideally centered around $(0,0)$), taking the complex number $z = x + iy$ and applying $f_c(z) = z^2 + c$ to it repeatedly until it escapes some threshold from the origin. The precise values used are variable and somewhat open to artistic interpretation; in the code below, we use $c = -0.8 + 0.156i$ and a threshold of $1.9$.

Here is a gif of the lower-right-hand-quadrant of the Julia set where each frame has one more iteration of $f_c(z)$ than the previous one.

And here is the code which produces it:


package main
// Renders a series of julia_n.pngs which can be zipped together into a gif.
//
// Example usage:
// go run julia.go
// convert /tmp/julia*.png -loop 0 animation.gif
import (
"fmt"
"github.com/fogleman/gg"
"image/color"
"math"
"math/cmplx"
)
const (
// Variables for the Julia set.
kConst complex128 = -0.8 + 0.156i
kThreshold float64 = 1.9
// The scaling factor between pixels and floating point coordinates. A higher
// number means a more zoomed-in image.
kScaling float64 = 600.0
// The dimensions of the image.
kDim int = 500
// The number of frames to render at the most.
kSteps int = 50
)
// Computes a fractional |mu|-value given the integer number of steps |i| and
// the complex value |z|.
func Mu(i int, z complex128) float64 {
return float64(i) + 1.0 - math.Log(math.Log(cmplx.Abs(z)))/math.Log(2.0)
}
// Computes the shade for each pixel in a 2D array and returns the maximum
// mu-value (shade analogue) encountered during the aforementioned process.
func Compute(pixels *[kDim][kDim]float64, steps int) float64 {
var max_mu float64 = 0.0
for x := 0; x < kDim; x++ {
a := float64(x) / kScaling
for y := 0; y < kDim; y++ {
b := float64(y) / kScaling
z := complex(a, b)
for i := 0; i < steps; i++ {
z = cmplx.Pow(z, 2) + kConst
if cmplx.Abs(z) > kThreshold {
var mu float64 = Mu(i, z)
if mu > max_mu {
max_mu = mu
}
pixels[x][y] = mu
break
}
}
}
}
return max_mu
}
// Maps a floating-point number between 0 and 1 to a grayscale color between 0
// and 255.
func Shade(n float64) color.Color {
return color.Gray{uint8(n * (math.MaxInt8 - 1))}
}
// Renders a 2D array of pixels to a gg.Context object.
func Render(max_mu float64, pixels [kDim][kDim]float64) *gg.Context {
dc := gg.NewContext(kDim, kDim)
for x := 0; x < kDim; x++ {
for y := 0; y < kDim; y++ {
dc.SetColor(Shade(pixels[x][y] / max_mu))
dc.SetPixel(x, y)
}
}
dc.SetRGB(0, 0, 0)
dc.Fill()
return dc
}
func main() {
for f := 0; f < kSteps; f++ {
fmt.Printf("Step %v\n", f)
var pixels [kDim][kDim]float64
max_mu := Compute(&pixels, f /*steps*/)
Render(max_mu, pixels).SavePNG(fmt.Sprintf("/tmp/julia_%v.png", f))
}
}

Writing a Quadtree library for Rust

Sat, 06 Apr 2019 00:00:00 -0400

App	https://crates.io/crates/quadtree_rs
Github	http://github.com/ambuc/quadtree

Introduction

I wrote and published a quadtree crate for Rust. It is published on crates.io and has docs on docs.rs.

What is a quadtree?

A quadtree is a tree data structure in which each internal node has exactly four children. Quadtrees are the two-dimensional analog of octrees and are most often used to partition a two-dimensional space by recursively subdividing it into four quadrants or regions. The data associated with a leaf cell varies by application, but the leaf cell represents a “unit of interesting spatial information”. - Wikipedia

What is a quadtree good for?

For graphics, visualization, and other applications which require spatial information at a variable density, quadtrees are a good solution to the problem of storing high-density location data without paying the cost of uniformly high-density partitioning. As always, a picture says a thousand words:

Why did I write a quadtree library?

I found a number of quadtree implementations on crates.io. Some of them were simply too outdated to work with modern Rust, some of them were too gamedev-specific, and some were beyond my needs.

Specifically, I wanted to be able to

insert both points and regions,
insert mutliple overlapping regions in 2d space,
query by object handle and mutate the value (but not the location) in-place, and
later query a region and find all intersecting results.

No library I found supported all these requirements.

Implementation

The solution implemented in quadtree_rs makes a few compromises.

First, value/region associations are cheap to insert, cheap to query, and expensive to delete. This is ideal for gamedev, where a 2d map is constructed once and then rendered frequently (such as on a per-frame basis).

Second, regions are stored directly at the levels which describe them.

Here is what I mean: in a quadtree with buckets (such as that illustrated in the Wikipedia article, points are bucketed, i.e a single node can have up to n values before it is subdivided. (In the illustration, that bucket size appears to be one.)

In the quadtree_rs implementation, a handle (a key in some hashmap which points to the user-inserved value) is inserted at multiple points in the quadtree.

Insert operations

Let’s walk through inserting some points and regions to explore the design of quadtree_rs.

Inserting a point

Associating a value with a point, which is represented by a region with dimensions 1x1, means traversing the full height of the quadtree.

Let’s initialize a quadtree which covers the square region between $(0, 0)$ and $(4, 4)$. The left column will be a tree respresentation, the middle column will be a graphical representation, and the right column will be the data store.

tree graphical data store
==== ========= ==========
(0,0)->4x4 +---+---+---+---+
| |
+ +
| |
+ +
| |
+ +
| |
+---+---+---+---+

Now let’s insert the value 'a' at the point $(0, 0)$. In quadtree_rs, points are regions with dimensions 1x1.

We subdivide the quadtree twice. Inserting a point means traversing the full depth of the tree.

If the quadtree were of depth n, the width and height of the region would be 2^n, and inserting a point would require n traversal steps.

We first insert 'a' into the data store, returning the handle 001. We then insert 001 at each node in the tree which is wholly enclosed in the region (0, 0)->1x1.

(0,0)->4x4 +---+---+---+---+ 001 <=> 'a'
(0,0)->2x2 |001| | |
(0,0)->1x1 [001] +---+ + +
| | |
+---+---+ +
| |
+ +
| |
+---+---+---+---+

Inserting a convenient region

Now let’s insert the value 'b' at a rectangular region anchored at $(0, 0)$ with dimensions 2x2.

We first insert 'b' into the data store, returning the handle 002. We then insert 002 at each node in the tree which is wholly enclosed in the region (0, 0)->2x2.

(0,0)->4x4 +---+---+---+---+ 001 <=> 'a'
(0,0)->2x2 [002] |001| | | 002 <=> 'b'
(0,0)->1x1 [001] +---+ + +
| 002| |
+---+---+ +
| |
+ +
| |
+---+---+---+---+

Because there is a node which perfectly describes our insertion region, we only insert the handle 002 once in the tree.

Inserting an inconvenient region

What happens if we insert a region which cannot be wholly described by a leaf node?

Let’s insert the value 'c' at a rectangular region anchored at $(0, 0)$ with dimensions 3x3.

(0,0)->4x4 +---+---+---+---+ 001 <=> 'a'
(0,0)->2x2 [002,003] |001| |003| | 002 <=> 'b'
(0,0)->1x1 [001] +---+ +---+---+ 003 <=> 'c'
(0,2)->2x2 |002,003|003| |
(0,2)->1x1 [003] +---+---+---+---+
(1,2)->1x1 [003] |003|003|003| |
(2,0)->2x2 +---+---+---+---+
(2,0)->1x1 [003] | | | | |
(2,1)->1x1 [003] +---+---+---+---+
(2,2)->2x2
(2,2)->1x1 [003]

In the upper-left quadrant, the new region is described by the second-level leaf node at (0,0)->2x2, so the handle (003) is inserted there.

All other quadrants are subdivided until the division in question is either wholly within or without the insertion region.

The handle type is lightweight, copyable, and can be inserted multiple times. A handle type is used so that the actual value need not be copyable.

Schema Conclusions

As a result of our handle-based design, insertion is fast and trivially parallelizable (although that optimization is unimplemented).

Querying means describing the region, deduping the set of handles, and looking up each handle in the data store.

Deleting means describing the region, collecting the set of affected handles, and deleting those handles (and their associated values) from the data store.

Caveats

There are a few problems with this implementation.

First, areas must have positive, nonzero dimensions. To avoid runtime exceptions, we use the derive_builder pattern to derive an AreaBuilder type, which is somewhat verbose.

Second, coordinate types are subject to integer overflow. A client of this library using u8 types may experience hard-to-debug saturation effects at the boundaries of their quadtree region.

Third, the quadtree requires a block of memory and is subject to frequent reallocation. Thus a client of this library might want to describe the majority of their canvas up-front.

Conclusions

If you use this library (or want to) but it is unsuited for your application, feel free to leave me a github issue. I’m interested in actively maintaining this library.

Pipes in Haskell

Tue, 23 Oct 2018 00:00:00 -0400

Github	http://github.com/ambuc/pipes

Introduction

This project remakes the game Pipe Mania in Haskell using Brick, a declarative terminal user interface library and box-drawing characters, which are a form of semigraphics for drawing lines and rectangles. Pipe Mania comes in many forms, such as an updated Metro design, a vintage Windows 95 theme, and online flash game. Each variant is slightly different, so I didn’t really copy any one game in particular.

You can browse the source at github.com/ambuc/pipes, but this post will be a short walkthrough of the most interesting parts of its development.

Graphics

Pipes runs in the terminal, consumes keyboard events, and redraws a screen full of Unicode characters every frame. Box Drawing characters are used to render empty/full, connected/isolated pipes at all angles and thicknesses. These characters have been around since v1.0.0 (October 1991) and are commonly used for drawing terminal interfaces such as tmux.

How do we consume a tile and decide which character to draw? In our case, we have more data than which legs are absent or present – we want to have control over each of the four limbs, and we want to dictate whether that limb is absent, present, or present and bold.

Braille

In Unicode, Braille patterns are encoded in a sensible way. There are typically six dots, but there can be as many as eight. Those dots are indexed like so:

Indexing Base 16
======== =========
(1) (4) ( 1) ( 8)
(2) (5) ( 2) (10)
(3) (6) ( 4) (20)
(7) (8) (40) (80)

So, for example, the Unicode position of the character ⠓ (which has dots 1, 2, and 5 raised) can be computed by taking the sum of the hexidecimal powers of two which correspond with the desired inputs, plus some offset, like so:

$$[1,2,5] \rightarrow \Sigma [1_{16},2_{16},10_{16}] \rightarrow 13_{16} \rightarrow (2800_{16} + 13_{16}) \rightarrow \text{U+2813} \rightarrow \boxed{⠓}$$

This is only possible because the Unicode characters are ordered lexicographically:

 Code Point Character Dots Binary
========== ========= ===== ========
U+2801 ⠁ 1 00000001
U+2802 ⠂ 2 00000010
U+2803 ⠃ 1,2 00000011
U+2804 ⠄ 3 00000100

Box-Drawing Characters

This is not the case for box-drawing characters, which are grouped primarily by shape, secondarily by rotation, and tertiarily by thickness.

 0 1 2 3 4 5 6 7 8 9 A B C D E F
U+250x ─ ━ │ ┃ ┄ ┅ ┆ ┇ ┈ ┉ ┊ ┋ ┌ ┍ ┎ ┏
U+251x ┐ ┑ ┒ ┓ └ ┕ ┖ ┗ ┘ ┙ ┚ ┛ ├ ┝ ┞ ┟
U+252x ┠ ┡ ┢ ┣ ┤ ┥ ┦ ┧ ┨ ┩ ┪ ┫ ┬ ┭ ┮ ┯
U+253x ┰ ┱ ┲ ┳ ┴ ┵ ┶ ┷ ┸ ┹ ┺ ┻ ┼ ┽ ┾ ┿
U+254x ╀ ╁ ╂ ╃ ╄ ╅ ╆ ╇ ╈ ╉ ╊ ╋ ╌ ╍ ╎ ╏

Given some input data like {n: bold, e: absent, s: bold, w: regular}, what is our preferred schema? My answer was this:

N 012012012012012012012012012012012012012012012012012012012012012012012012012012012
E 0--1--2--0--1--2--0--1--2--0--1--2--0--1--2--0--1--2--0--1--2--0--1--2--0--1--2--
S 0--------1--------2--------0--------1--------2--------0--------1--------2--------
W 0--------------------------1--------------------------2--------------------------
╵╹╶└┖╺┕┗╷│╿┌├┞┍┝┡╻╽┃┎┟┠┏┢┣╴┘┚─┴┸╼┶┺┐┤┦┬┼╀┮┾╄┒┧┨┰╁╂┲╆╊╸┙┛╾┵┹━┷┻┑┥┩┭┽╃┯┿╇┓┪┫┱╅╉┳╈╋

So that we can convert our desired weights into an enum on $[0,1,2]$ and index into some hard-coded schema string, like so:

 0 1 2
n: bold ==> . . X ==> 2 * 3^0
e: absent ==> X . . ==> 0 * 3^1
s: bold ==> . . X ==> 2 * 3^2
w: regular ==> . X . ==> + 1 * 3^3
----------
47 -> schema[47] -> ┨

So that’s how Pipes renders tiles of various orientations/thicknesses/shapes.

Animation

One of the goals of writing this game was that it would not only respond to cursor movement and rotation (the way all Pipes Mania-style games do) but that the pipes which were connected to the drain, i.e. had water in them, would pulse gently.

This animation relies on tweening, which uses heterogeneous characters like ╼ and ╾ in-between homogeneous characters like ─ and ━ to give the appearance of finer-resolution motion. Here is an example:

Horizontal Vertical
Locomotion Locomotion
========== =================
0 ─── 0 ½ 1 ½ 2 ½ 3 ½ 4
1 ╾── │ ╿ ┃ ╽ │ │ │ │ │
2 ━── │ │ │ ╿ ┃ ╽ │ │ │
3 ╼╾─ │ │ │ │ │ ╿ ┃ ╽ │
4 ─━─
5 ─╼╾

When we explore the connected graph of pipes, we mark each limb as being an inlet or an outlet and then generate the appropriate tile given both the distance from the tap and the current time. This lets us stagger the animation across the tile so that the water appears to flow in from the limb nearer to the tap and flow out from the others.

Conclusion

Brick is the perfect framework for a project like this. If you’re interested in playing with the code (or even just playing the game), you can get started by installing Stack, the Haskell Tool Stack and running:

bash


$ git@github.com:ambuc/pipes.git
$ cd pipes
$ stack build
$ stack exec pipes-exe

OSC-Responsive 3D Graphics in Rust

Fri, 02 Feb 2018 00:00:00 -0400

Github	https://github.com/ambuc/voxel-preview

Introduction

As preparation for an upcoming hardware-intensive project involving an 8x8x8 LED cube display, We want a way to preview the behavior of the display remotely. Enter voxel-preview: like the intended physical display, the rendered cube listens over UDP for OSC packets and updates the voxels accordingly.

Requirements

Rust and Cargo, ideally by way of Rustup
send_osc for testing

Installation

voxel-preview can be downloaded, built, and run with cargo.

bash


$ git clone https://github.com/ambuc/voxel-preview.git
$ cd voxel-preview
$ cargo build

Usage

bash


$ cargo run

At this point, an OpenGL window will pop up and show a slowly-revolving rainbow cube; the default dimensions are 8x8x8.

You can send individual packets with send_osc. voxel-preview listens on 127.0.0.1:1234 by default.

Schema

The schema is:

// port x y z r g b
send_osc 1234 /0/2/4 0.0 0.5 1.0

where x, y, and z are the xyz coordinates of the voxel to color, and r, g, and b are the rgb coordinates thereof.

voxel-preview will drop malformed packets within reason (x > CUBE_WIDTH, or r > 1.0, for example), but it’s not that smart.

Conclusion

This isn’t so much a project as a tool. We aim to write a controller which interfaces nicely with something like TouchOSC, which will ultimately serve as a sort of platform for a series of abstract 3D games / toys / visualizations over the coming weeks or months.

Writing a Solitaire TUI with Lenses and Brick

Sat, 02 Dec 2017 00:00:00 -0400

Github	http://github.com/ambuc/solitaire

┌───────────── Solitaire ──────────────┐
│┌──┐│┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐│┌ ┐│ Score: 0
││λ=││┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐│7♠││ │
│└──┘│┌──┐┌──┐┌──┐┌──┐┌──┐│K♥│└──┘│└ ┘│ Moves: 0
│┌──┐│┌──┐┌──┐┌──┐┌──┐│J♣│└──┘ │┌ ┐│
││3♠││┌──┐┌──┐┌──┐│6♦│└──┘ │ │ [New]
│┌──┐│┌──┐┌──┐│9♣│└──┘ │└ ┘│
││3♥││┌──┐│Q♠│└──┘ │┌ ┐│ [Undo]
│┌──┐││4♠│└──┘ │ │
││7♦││└──┘ │└ ┘│
│└──┘│ │┌ ┐│
│ │ │ │
│ │ │└ ┘│
│ │ │ │
└──────────────────────────────────────┘

I’d wanted to write an implementation of Solitaire a.k.a. Patience, Klondike, etc in Haskell ever since I learned about brick, a library for programming terminal user interfaces (TUIs). I liked it because, as the docs say, it

…exposes a declarative API. Unlike most GUI toolkits which require you to write a long and tedious sequence of “create a widget, now bind an event handler”, brick just requires you to describe your interface using a set of declarative combinators. Then you provide a function to transform your application state when input or other kinds of events arrive.

The other component of this project involved learning about lenses. Lenses are a Template Haskell solution to the record problem, which concerns the difficulty of reading from, writing to, and editing in-place deeply-nested record variables. Although Haskell is an immutable language, sometimes in-place modification is simply too convenient to abandon. Lenses are an elegant set of combinators for working around this.

Application Overview

This essay will be a high-level architecture of the game, but the code itself is decently commented, and only spans one Main.hs and four small helper libaries.

Brick

As discussed above, brick lets us define

an app :: App State Event () application state object, and
an appEvent :: State -> Event e -> EventM () (Next State) event handler and that’s almost entirely it. There’s a bit more business for styling and click region detection, but the core of the game takex place in the event loop within appEvent.

haskell


appEvent :: GSt -> BrickEvent Ext e -> EventM Ext (Next GSt)
appEvent s (VtyEvent e) = case e of
Vty.EvKey Vty.KEsc [] -> halt s
Vty.EvKey (Vty.KChar 'q') [] -> halt s
Vty.EvMouseDown col row _ _ -> do
extents <- map extentName <$> findClickedExtents (col, row)
case extents of
[ActionX New] -> continue $ newGame s
[ActionX Undo] -> continue $ undoMove s
_ -> if hasWon s
then continue s
else continue $ doMove s extents
_ -> continue s
appEvent s _ = continue s

In the above, some keys halt the game, but most of them continue the game either

with the state s as-is, or
with the state s modified by some function (newGame, undoMove, or doMove).

Rules of Solitaire

Before we continue let’s just speak briefly about Solitaire.

+-------+----------------------+
| Stock | | |
+-------+ Tableau | Foundation |
| Waste | | |
+-------+----------------------+

Cards start either facedown in the stock or in seven piles of lengths 1, 2,.. in the tableau.
The stock is always facedown, but can be dealt three at a time to the
The piles in the tableau are splayed downwards, and start with only their top card visible.
Nothing starts in the foundation, but cards can accumulate there face-up.

Cards can be moved like so:

+-------+----------------------+
| Stock | | |
| ^ | <-- |
+-- | --+ Tableau | Foundation |
| v | --> |
| Waste -> | |
+-------+----------------------+

Some more rules:

in the tableau only a King can go on an empty pile, but any card can go on any other card as long as it has a different color and is of exactly one rank less.
in the foundation only an Ace can go on an empty pile, and any card can go on a foundation pile as long as it matches the base suit and is of exactly one rank more.

I’m not sure Solitaire is a very interesting game to play, but abstracting the core ideas of cards, displaycards, piles, lists of piles, and operations between them was a lot of fun.

Custom Types

I think Haskell is fairly readable, so it might be best to just look at the CardTypes.hs source. But just as a quick overview, we define:

a Card (rank and suit),
a DCard, a display-card which wraps a Card and contains a preference for being displayed face-up or face-down
a Pile, which is a list of DCards with an opinion on what sort of card can go at its base (for example, only a King, or only an Ace) as well as a preference for its cards being displayed stacked or splayed out.
a GSt, a game state which wraps the stock, waste, tableau, and foundation, as well as containing the current score, the elapsed move count, a random seed, and a history of prior fields and scores.

`Show` instances

We can make our own type instance of a few of the above custom typeclasses by defining what it means to Show a Rank or Suit.

haskell


instance Show Rank where
show RA = "A";
show R2 = "2"; show R3 = "3"; show R4 = "4"; show R5 = "5";
show R6 = "6"; show R7 = "7"; show R8 = "8"; show R9 = "9";
show R10 = [toEnum 0x2491] :: String; -- unicode ligature for one-char width
show RJ = "J"; show RQ = "Q"; show RK = "K";
instance Show Suit where
show Spade = [toEnum 0x2660] :: String -- unicode characters for suits
show Heart = [toEnum 0x2665] :: String
show Diamond = [toEnum 0x2666] :: String
show Club = [toEnum 0x2663] :: String

Lenses 101

We want to define our record fields with underscores like so:

haskell


data DCard = DCard { _card :: Card
, _facedir :: FaceDir }
deriving (Eq, Show, Ord)

So that the Lens library can, at compile time, create functions like card or facedir which can be called on DCard objects, like so:

haskell


> let dc = DCard { _card = Card RA Club
, _facedir = FaceDown
}
> dc
DCard { _card = Card A ♣, _facedir = FaceDown }
> dc ^. card
Card A ♣
> dc & facedir .~ FaceUp
DCard { _card = Card A ♣, _facedir = FaceUp }

where (^.) is a getter and .~ is a setter (sorta). For more read the lens tutorial.

By the same convention, a deeply-nested object could be accessed with

haskell


obj & fieldOuter . fieldInner . fieldVeryInner %~ mutationFn

which makes it super easy for us to just pass around the Field or the GSt gamestate and modify it at any level. Thanks, Lenses!

Output

Just as we wrote a set of abstract data types above which can be composed into flexible Piles, etc., we want to write a set of abstract render functions which can be composed to draw a Pile, or a DCard, or whatever. Brick wants us to define our app like so:

haskell


app = App { appDraw = drawUI
, ...
}

where drawUI :: GSt -> [Widget ()] handles every part of the program, from the field to the score counters. It is a pure function of the game state and doesn’t need callbacks or promises or event handlers at all, except that we can name certain regions so that, when clicked, Brick handles a BrickEvent Ext (Vty.EvMouseDown col row _ _) where extents = map extentName $ findClickedExtents (col,row) lets us interpet the observed column and row and get a list of clicked extents. We can report a named extent by wrapping it in reporteExtent ExtentName.

Brick provides some primitive combinators for stacking widgets (rectangles) next to (<+>) or above (<=>) each other, as well as some primitive widgets for displaying text (str :: String -> Widget ()), wrapping widgets in styled borders, ( withBorderStyle unicodeRounded $ borderWithLabel (str "title") $ myWidget), etc. As before, the code is fairly readable, so I’ll just cover some interesting mechanics here briefly before moving on.

Custom Borderstyles

A typical card looks like this: a string 7♦ wrapped in a unicodeRounded border:

┌──┐
│7♦│
└──┘

but we want to be able to draw custom border too, in the case of our empty piles:

┌ ┐
└ ┘

Brick lets us define custom borderstyles like so:

haskell


rrGhost :: Widget Ext -- renders a 'ghost' card with no content
rrGhost = withBorderStyle ghostRounded $ border $ str " "
where ghostRounded = BorderStyle
{ bsIntersectFull = toEnum 0x253C
, bsCornerTL = toEnum 0x256D , bsCornerTR = toEnum 0x256E
, bsCornerBR = toEnum 0x256F , bsCornerBL = toEnum 0x2570
, bsIntersectL = toEnum 0x251C , bsIntersectR = toEnum 0x2524
, bsIntersectT = toEnum 0x252C , bsIntersectB = toEnum 0x2534
, bsHorizontal = ' ' , bsVertical = ' '
}

Where those unicode 0x.... codes are just various box-drawing characters, and the bsVertical and bsHorizontal codes are (intentionally) spaces.

Piles

Once we have a drawCard function, we can stack the cards by cropping their bottom or right borders as necessary, with more of the card cropped if it is meant to be face-down than if it is meant to be face-up. For example,

stacked face-up | stacked face-down
┌──┐ │┌──┐
│3♥│ │┌──┐
┌──┐ ││4♠│
│7♦│ │└──┘
└──┘ │

Otherwise, Render.hs is mostly composing existing Brick primitives in easy ways.

Input

OK, here’s where the complexity of the game begins to shine through.

In computer solitaire, we typically expect to be able to click on a card and it will, it possible, move to the next open position. Thus, whenever a card gets clicked on, we should be able to figure out the next valid pile it could be moved to and move it there.

We can do so with lenses – and we can define our own lenses with independent getters and setters to make doing so easier.

For example, here’s a lens which writes to or reads from the stock. Its type is stockL :: Lens' Field [DCard], and it either reads and returns a list of DCards or accepts a list of DCards and writes them to the stock. The syntax is

haskell


fooLens = Lens (anonymous getter) (anonymous setter)

haskell


-- creates a lens from the field to the stock
-- operates on lists of displaycards
stockL :: Lens' Field [DCard] --all
stockL = lens (\f -> f ^. stock.cards)
(\f dcs -> f & stock.cards .~ dcs)

Actually, let’s use this opportunity to flip the cards at read/write-time. We can use each to iterate over each of the returned or processed objects and apply some transformation with (.~).

haskell


stockL = lens (\f -> f ^. stock.cards & each.facedir .~ FaceUp)
(\f dcs -> f & stock.cards .~ (dcs & each.facedir .~ FaceDown))

Perfect. In Movement.hs you can see custom lenses for the stock, the waste, as well as two lens generators for the tableau and foundation which instead a) return Piles instead of [DCard]s, and b) accept an integer index for which tableau pile / foundation pile to return. They are of type tableLN :: Int -> Lens' Field Pile, where N is a convention for indexed generators.

`doMove`

Eventually we want to be able to, upon reading a list of extents from a clicked region, continue with our game by calling

haskell


appEvent :: GSt -> BrickEvent Ext e -> EventM Ext (Next GSt)
appEvent s (VtyEvent e) = case e of
Vty.EvMouseDown col row _ _ -> do
extents <- map extentName <$> findClickedExtents (col, row)
case extents of
_ -> if hasWon s
then continue s
else continue $ doMove s extents

We’ll write hasWon :: GSt -> Bool later, but for now let’s write doMove :: GSt -> [Ext] -> GSt, which tries to move the clicked card and, if successful, returns a changed GSt with incremented moves ticker, mutated score, and augmented history.

haskell


doMove :: GSt -> [Ext] -> GSt
doMove s exs = if wasChange
then s & field .~ newField
& history %~ ((oldField, oldScore):)
& score %~ scoreFn
& moves %~ succ
else s
where
wasChange = oldField /= newField
oldField = s ^. field
oldScore = s ^. score
(newField, scoreFn) = tryMove exs oldField

Here we can see chained

haskell


foo & fieldA .~ newFieldA
& fieldB .~ newFieldb

operator chaining for the first time, which is pretty snazzy. Here, doMove expects a tryMove function which will return not just the new field, but a score mutator (+5, -10, id, etc.).

Extents

haskell


data Ext = StockX | WasteX | TableX | FoundX
| IdX Int | DCX DCard | ActionX Action
deriving (Eq, Show, Ord)

Before we write tryMove, we should talk about Extents and what they look like in practice. They end up being lists of clicked extents where the innermost extents are first. We can wrap our stock, waste, etc. in StockX, WasteX, etc. extent labels, and we can report the DCard directly with a DCX wrapper. Later we’ll use the ActionX wrapper to report something of type Action.

Finally, we can use IdX Int as a wrapper for a row/col index.

For now let’s write tryMove by pattern-matching on the reported extents. Each region will have a different shape so we should be able to striate our regions fairly easily.

[StockX]: reporting just an empty StockX region means there are no cards, so we should refresh it from the waste.
[_, StockX]: reporting a non-empty stock means we want to take three cards from the stock and move them to the waste.
[DCX dc, IdX 0, WasteX]: reporting from the top of the waste stack means we should try to move it. We don’t pattern-match on just any index in the waste since none of the others are actionable.
[DCX dc, Idx row, FoundX]: reporting from any row in the foundation means we should try and move its topmost card.
[DCX dc, Idx row, Id col, TableX]: reporting from the tableau means we expect a row and column index, which tells us where in the tableau structure to try and read from. Uniquely, we can read a card or a stack of cards at a time from the tableau and move them all as a unit, as long as the stack of cards doesn’t leave the tableau.

One more thing to do before we can write tryMove:

Movement Lenses

Eventually, we want to be able to write (pseudocode below):

haskell


process state =
if (canMove?)
then state & newLocation %~ (card:) -- add one or more cards
& oldLocation %~ (drop n) -- drop n cards
else state

these newLocation and oldLocation lenses will have to be deduced from context.

Let’s get a list of our tableau and foundation lenses:

haskell


inTableau :: Functor f0 => [(Pile -> f0 Pile) -> Field -> f0 Field]
inTableau = map tableLN [0..6]
inFoundation :: Functor f0 => [(Pile -> f0 Pile) -> Field -> f0 Field]
inFoundation = map foundLN [0..3]

These are almost of type Lens' Field Pile, but not quite. We define them differently here because they aren’t setters or getters yet. If we defined them as Lens' types, they’d be polymorphic, and the process of evaluating them thru a filter cond ls mechanism would solidify them as setters, when ideally we want to be able to later turn around and use them as getters.

Each location can provide its own set of candidate lenses (usually either inFoundation++inTableau or inTableau, but it will depend) and evaluate them through findSpot, which takes a list of lenses and a card and a field and returns the index of the first matching lens, if possible.

haskell


findSpot :: [Getting Pile s Pile] -> Card -> s -> Maybe Int
findSpot pLenses c f = findIndex (\pL -> canPlace c (f ^. pL)) pLenses

canPlace is a manual bit of pattern-matching which lives in `Utils.hs and runs through the types of piles and types of cards to provide a true/false.

In practice it is convenient to provide two helpers to findSpot:

haskell


isSpot pLs c f = isJust $ findSpot pLs c f
mkSpot pLs c f = fromJust $ findSpot pLs c f

We can use the first in canMove, and the second in mkMove. canMove tells us whether there is a spot for a card to go elsewhere in the field, and mkMoveL will, assuming there is a spot, return both a lens to that spot and the piletype of the spot the card can go to.

haskell


canMove :: Int -> DCard -> Field -> Bool
canMove _ DCard{_facedir=FaceDown} _ = False
canMove 0 DCard{_card=c} f = isSpot (inFoundation ++ inTableau) c f
canMove _ DCard{_card=c} f = isSpot inTableau c f
mkMoveL :: Functor f => Int -> Card -> Field
-> ( (Pile -> f Pile) -> Field -> f Field, PileType)
mkMoveL 0 c f = if idx <= 3
then (foundLN idx , FoundP)
else (tableLN (idx - 4) , TableP)
where idx = mkSpot (inFoundation ++ inTableau) c f
mkMoveL _ c f = (tableLN $ mkSpot inTableau c f , TableP)

OK, let’s write tryMove. If you don’t like lenses, the above was the worst of it.

`tryMove`

We expect tryMove to have the form:

haskell


tryMove :: [Ext] -> Field -> (Field, Int->Int)

`tryMove [StockX]` Moving from the Stock (i)

Let’s write the tryMove [StockX] function first, since it is the simplest:

haskell


tryMove [StockX] f = (f',id)
where f' = f & stockL %~ (reverse load ++)
& wasteL .~ []
load = f ^. wasteL

Even for Haskell, this is pretty esoteric. we read a load from the waste using the wasteL custom lens, reverse it, and prepend it (++) to the stock by using the in-place mutation operator (%~), while overwriting the waste with an empty list (.~). We return that new field f' and a scoreFn id, which keeps the score as-is.

`tryMove [_, StockX]` Moving from the Stock (ii)

This is pretty similar to the last function, except that we are reading from the stock and writing to the waste instead. We drop 3 and take 3 at a time. Remember that the need to flip our cards over is handled innately in the stockL and wasteL lenses!

haskell


tryMove [_, StockX] f = (f',id)
where f' = f & stockL %~ drop 3 --drop 3 from stock
& wasteL %~ (reverse load ++) --add 3 to waste
load = f ^. stockL & take 3 --get 3 from stock

`tryMove [DCX dc, IdX 0, WasteX]` Moving from the Waste

We’ve already solved the hardest subproblem, that if determining whether or not a card can move anywhere else in the field. So we can just use canMove rowIndex displaycard field to decide whether or not to try to evaluate f'. If we do, it lazily evaluates mkMoveL, which returns the moveL lens which we can use to write one card to the location in question. We also use the computed PileType to inform our scoring mutator.

haskell


tryMove [DCX dc, IdX 0, WasteX] f
| canMove 0 dc f = (f', scoreFn)
| otherwise = (f , id)
where (moveL, pType) = mkMoveL 0 (dc ^. card) f
f' = f & moveL . cards %~ (dc:) --write 1 to _
& wasteL %~ drop 1 --drop 1 from waste
scoreFn
| pType == FoundP = (+10)
| otherwise = (+5)

`tryMove [DCX dc, IdX row, FoundX]` Moving from the Foundation

haskell


tryMove [DCX dc, IdX row, FoundX] f
| canMove row dc f = (f', scoreFn)
| otherwise = (f , id)
where (moveL, pType) = mkMoveL row (dc ^. card) f
f' = f & moveL . cards %~ (dc:) --write 1 to _
& foundLN row . cards %~ drop 1 --drop 1 from found.
scoreFn i = i - 15

This is starting to feel familiar; we know how to move one card at a time. The only difficulty comes when it’s time to move from the tableau; we could be moving one card or more at a time.

`tryMove [DCX dc, IdX row, Idx col, TableX]` Moving from the Tableau

haskell


tryMove [DCX dc, IdX row, IdX col, TableX] f
| canMove row dc f = (f', scoreFn)
| otherwise = (f , id)
where load = f ^. tableLN col . cards & take (succ row)
(moveL, pType) = mkMoveL row (dc ^. card) f
f' = f & moveL . cards %~ (load++) --write n to _
& tableLN col . cards
%~ drop (succ row) --drop n from tableau
& tableLN col . cards . _head . facedir
.~ FaceUp --flip underlying card
scoreFn
| pType == FoundP = (+15)
| otherwise = (+5)

OK, this was definitely the most difficult one, But we’ve built ourselves a nice set of primitives, so that flipping the underlying card, or dropping n cards from the tableau row in question become pretty readable.

This is great! A well-formed tryMove mean we can write doMove, and the core of our game is finished.

Final Touches

Now that we know how to use lenses, a lot of the remaining functions are pretty simple:

haskell


-- if a game is won, all 52 cards are in the foundation
hasWon :: GSt -> Bool
hasWon s = length (s ^. field . found . traverse . cards) == 52

haskell


-- undoing a move means rolling back the field, the history, the score, and
-- the moves counter
undoMove :: GSt -> GSt
undoMove s = if hasHistory
then s & field .~ oldField
& history %~ drop 1
& score .~ oldScore
& moves %~ pred
else s
where (oldField, oldScore) = s ^. history ^?! _head -- assured if called
hasHistory = not $ null $ s ^. history

haskell


-- given a game with a seed, get a new seed and use it to spawn a new game
newGame :: GSt -> GSt
newGame s = let seed' = snd $ R.next $ s ^. seed
in mkInitS seed'

Now we can finally finish appEvent and our app is done!

haskell


appEvent :: GSt -> BrickEvent Ext e -> EventM Ext (Next GSt)
appEvent s (VtyEvent e) = case e of
Vty.EvKey Vty.KEsc [] -> halt s
Vty.EvKey (Vty.KChar 'q') [] -> halt s
Vty.EvMouseDown col row _ _ -> do
extents <- map extentName <$> findClickedExtents (col, row)
case extents of
[ActionX New] -> continue $ newGame s
[ActionX Undo] -> continue $ undoMove s
_ -> if hasWon s
then continue s
else continue $ doMove s extents
_ -> continue s
appEvent s _ = continue s

Conclusions

I think a good UI framework is one where the bulk of the difficulty of writing the app is the internal logic of the underlying app itself, not fighting with the framework. Brick fit right into my functional understanding of frameworks like React or Angular, and although there was some learning curve for lenses, the final product is, like all Haskell, surprisingly short and readable.

If you’ve never played with Haskell before, I think Brick is an excellent place to start. I encourage you to download and play Solitiare if you’re interested in getting a feel for the ecosystem, or just reading through some of the code if you’re interested in how a comparatively large app feels at a low level.

Multiprocessing Conway's Game of Life in Erlang

Thu, 12 Oct 2017 00:00:00 -0400

Github	http://github.com/ambuc/conway

This is an implementation of Conway’s Game of Life written in Erlang, a general-purpose, concurrent, functional programming language. A lot of this essay will be an attempt to document not just the novel syntax but the different problem-solving and architecting ideas that go into developing in Erlang.

The Game

Conway’s Game of Life is a cellular automaton, which means it’s a set of cells which turn themselves on and off frame-by-frame according to some set of rules. Specifically, Conway’s GOL takes place on an infinite 2D grid of squares, each of which cares about its eight cardinal neighbors. The entire game consists of

a) a starting configuration, and
b) a set of rules by which to evaluate if a cell lives or dies. In this case, Conway relies on rules which can be written as B3/S23, which means a cell is born if it has three living neighbors, and survives if it has either two or three living neighbors. (There are lots of variants.)

Conway’s GOL has become famous for the shockling high complexity and variety of its emergent patterns, as you can see in the 100x100 randomly-seeded grid above.

Computing The Game

In practice, the complexity of computing Conway’s Game of Life depends on the size of the grid in question and the length of the simulation. It would be fairly easy to render the world as a matrix of binary 1s and 0s, or Trues and Falses; each tick in the world could be a matrix and each next tick could read off the states of the previous tick.

But I think the problem generalizes nicely to Erlang in the sense that it fits the Actor model, in which each cell might be its own process living on some VM, and each update / neighbor-check might be a message or series of messages passed between the elements of the grid.

Erlang

Erlang is a little esoteric but not much more so than Haskell or any functional language. The basics for us go something like this:

erlang


Ref = spawn(module, function, [arg1, arg2..])
Msg = {foo, bar}
Ref ! Msg

spawn spawns a process, the function function from module module with args [arg1, arg2...]; Ref captures the PID of that process, and ! lets us pass messages to a unique instance of a process. This is the whole mechanism for Erlang; the VM aggressively cleans up processes which are done processing things (or waiting to process things).

Semaphores

Before we get into the specifics of simulating Conway’s Game of Life, let’s discuss two small abstractions which make message passing between objects slightly easier.

Latch

One is a latch, which is basically a counter; you give it a spring-loaded message, and it only sends that message once it’s reached a certain number of recieved messages.

erlang


-module(latch).
-compile(export_all).
% Starts a latch reporting to Ref, waiting for N pings.
init(Ref, N) -> spawn(?MODULE, loop, [Ref, N]).
% Ends a latch reporting to Ref.
loop(Ref, 0) -> Ref ! pong;
% Recieves a ping and returns a latch waiting for N-1 pings.
loop(Ref, X) ->
receive ping -> loop(Ref, X-1)
after 1000 -> erlang:error(latch_timeout)
end.

Collector

The other is a collector, which waits for a certain number of bits of information, and then sends them all in aggregate somewhere.

erlang


-module(collector).
-compile(export_all).
% Starts a collector reporting to Ref, waiting for N reports.
% Optionally bundled with Metadata of any type, as a secondary payload.
init(Ref, Meta, N) -> spawn(?MODULE, loop, [Ref, Meta, [], N]).
% Ends a collector reporting to Ref.
% Sends a payload like {data, Meta, Data}
loop(Ref, Meta, Data, 0) -> Ref ! {data, Meta, Data};
% Recieves a payload and returns a collector waiting for N-1 more payloads.
loop(Ref, Meta, Data, X) ->
receive D -> loop(Ref, Meta, [ D | Data ], X-1)
after 1000 -> erlang:error(collector_timeout)
end.

I defined the collector here with the ability to carry some bit of metadata over its lifetime, from initialization to final payload. This becomes useful in preserving the relative statelessness of each of our cells.

Writing A Game Of Life

Now that we have a sense of how the game works and language and tools in which to write it, let’s try and design how the board and cell objects look and interact.

The `board`

We want to initialize the board with dimensions, a starting pattern, and a lifespan for which to run. It should create, control, and eventually destroy the cells. It should also collate the current state of each board and output that state in some useful way.

Each tick of the board should consist of three stages:

the board should ask each cell to report its current state, and then the board should output that aggregate state.
then the board should ask each cell to check_ns check its neighbors and decide which state it would like to assume next. Once the cells are done, they should report back, so that the board knows it’s alright to move on to the next phase,
when the board asks each cell to alter_st alter its state. Once the cells are done, they should report back…

so that the board knows it’s alright to loop these three stages over and over until the lifespan of the game is run out.

erlang


% Starts a GOL with Frames (an integer) frames left to live.
% Its initial state is a list of 1s or 0s, and it has dimensions X by Y.
init(Initial_State, Frames, {X, Y}) ->
io:format("Drawing ~w frames on an ~w x ~w grid...~n",[Frames, X, Y]),
out:cleanOutputFolder(),
Size = X * Y,
Is = lists:seq(1,Size),
io:format("Initializing ~w cells...~n",[Size]),
Cs = [ cell:init(I,L) || {I,L} <- lists:zip(Is,Initial_State) ],
S = #state{frames=Frames, stage=report, size=Size, cells=Cs, x=X, y=Y},
% Once we have created the cells, we need to broadcast out a list of their
% neighbor's PIDs to them.
io:format("Linking ~w cells...~n",[Size]),
[ C ! {moore, neighbors:getNPids(I,X,Y,Cs)} || {I,C} <- lists:zip(Is,Cs) ],
io:format("Linked ~w cells...~n",[Size]),
action(S).

We have a base case: when a board has no frames left to run, it dies.

erlang


action(#state{frames=0}) ->
io:format("Writing out to /tmp/conway/gif.gif.~n")
, os:cmd("convert -delay 20 -loop 0 $(ls /tmp/conway/frame_* | tac ) /tmp/conway/gif.gif")
, io:format("Wrote out to /tmp/conway/gif.gif.~n")
;

And some not-base cases. Sometimes a board has an action it needs to take.

erlang


action(S) ->
case S#state.stage of
% If we need to collect the states of all the cells, we create a Collector
% which knows to report back to the Board when it's done. We tell the
% Collector it needs to collect X*Y data points.
%
% Then we broadcast out {CollectorPid, report} to each of the cells, to tell
% them to self-report their {index, life} to the Collector.
%
% Then we switch over to waiting for the Collector to ping us back.
report -> C_Ref = collector:init(self(), nil, S#state.size),
[ C ! {C_Ref, report } || C <- S#state.cells],
waiting(S);
% Similarly, if we need to tell all the cells to check their neighbors, we
% create a Latch which knows to report back to the Board when it's done. We
% tell the Latch it needs to collect X*Y pings.
%
% Then we broadcast out {LatchPid, check_ns} to each of the cells, to tell
% them to check their neighbors and ping the Latch when they're done.
%
% Then we switch over to waiting for the Latch to ping us back.
check_ns -> L_Ref = latch:init(self(), S#state.size),
[ C ! {L_Ref, check_ns} || C <- S#state.cells],
waiting(S);
% FInally, if we need to tell all the cells to alter their states, we create
% a Latch and broadcast our message just as we did above.
alter_st -> L_Ref = latch:init(self(), S#state.size),
[ C ! {L_Ref, alter_st} || C <- S#state.cells],
waiting(S);
_ -> erlang:error(weird_stage)
end.

When our board is waiting for a report, it expects a payload like {data, Meta, Data}. It collects the Data, uses it to draw the gameboard at that frame, and then calls action() at the next stage, check_ns, and with one fewer frame left to go.

erlang


waiting(S = #state{stage=report}) ->
receive {data, _, Data} -> out:writeData(S#state.frames, S#state.x, Data),
io:format("~w frames left.~n",[S#state.frames]),
action(S#state{ stage=check_ns
, frames=(S#state.frames-1)
})
after 1000 -> erlang:error(board_timeout)
end;

When our board is waiting for anything else, it expects a simple pong. Depending on the current stage, it will know to switch over to the next stage in the cycle.

erlang


waiting(S) ->
receive pong ->
case S#state.stage of check_ns -> action(S#state{stage=alter_st});
alter_st -> action(S#state{stage=report })
end
after 1000 -> erlang:error(board_timeout)
end.

The `cell`s

Each cell of the board should know its own index and current state. When asked, they should be able to report one or both of those bits of information. Additionally, they should know the PIDs of their neighbors so that, if asked, they can query those neighbors (through a Collector) to discover their states and determine its next state.

This neighbor determination actually occurs in the board.erl initialization process, and the neighbor determination algorithm is abstracted away into neighbors.erl.

We have an initialization function init, which starts a cell with knowledge of its own index and starting state.

erlang


init(Index, Life) -> spawn(?MODULE, loop, [ #state{index=Index, life=Life} ]).

A cell always is waiting to receive a signal. When the game is over, the main/1 function in conway.erl ends and all these other processes die automatically.

erlang


% we are waiting to receive...
loop(S) ->
receive
% ... a moore neighbor space,
{moore, NPids} -> loop(S#state{npids=NPids});
% ... a request to check their neighbors' states, decide their desired
% state, and ping back to a latch L when done,
{L, check_ns} -> Ref = collector:init(self(),L,length(S#state.npids)),
[ NPid ! {Ref, alive} || NPid <- S#state.npids ],
loop(S);
% ... a payload from the above collector, allowing them to decide their
% desired state, and ping a latch on receipt,
{data, L, NData} -> L ! ping,
loop(S#state{desire=getDesire(S#state.life,NData)});
% ... a request from the board to ping a latch and flip to their new state,
{L, alter_st} -> L ! ping,
loop(S#state{life=(S#state.desire)});
% ... a request to report their {index,life},
{C, report} -> C ! {S#state.index, S#state.life},
loop(S);
% ... a request to report their life,
{Ref, alive} -> Ref ! S#state.life,
loop(S);
% ... or a request to die.
die -> ok;
_ -> erlang:error(weird_input)
after 10000 -> erlang:error(cell_timeout)
end.

The actual math of Conway’s GOL can be written quite simply:

erlang


% Takes a current state and data about the states of their neighbors, and
% decides whether to live or die.
getDesire(Curr, NData) ->
decide(Curr, length(lists:filter(fun(X) -> X =:= 1 end, NData))).
% Encodes the GOL rules.
% - Any live cell with fewer than two live neighbours dies, as if caused by
% underpopulation.
% - Any live cell with two or three live neighbours lives on to the next
% generation.
% - Any live cell with more than three live neighbours dies, as if by
% overpopulation.
% - Any dead cell with exactly three live neighbours becomes a live cell, as if
% by reproduction.
% Formally, this might be encoded as "B3/S23".
decide(0,3) -> 1;
decide(0,_) -> 0;
decide(1,2) -> 1;
decide(1,3) -> 1;
decide(1,_) -> 0.

Output

The board object collects a sorted list of all nodes and states, like

erlang


[(0,0),(1,0),(2,1),(3,0)... (<index>,<life>)]

We need a way to translate that into a still frame (a .png) of the gif we want to write eventually. Sadly, this task is best abstracted into a language with better graphics rendering capabilities. We write out this data into plaintext files and then run renderFrame/render.hs, which looks in /tmp for the file in question and writes it in-place to a .png.

The render script (render.hs) is really just a wrapper around Graphics.Rasterific:

haskell


size = 5
white = PixelRGBA8 255 255 255 255
black = PixelRGBA8 0 0 0 255
-- is called once per frame, like
-- $ render.hs /tmp/conway/data0001 /tmp/conway/frame0001.png
main = do
[inPath, outPath] <- getArgs
grid <- fmap words $ readFile inPath
let height = length $ grid
let width = length $ head $ grid
let datum = id
$ map snd
$ filter ((=='1').fst)
$ zip (concat $ grid)
[(x,y) | y <- [0..height-1], x <- [0..width-1]]
let img = renderDrawing (width*size) (height*size) white
$ mapM_ (uncurry pixelAt) datum
writePng outPath img
pixelAt :: Int -> Int -> Drawing PixelRGBA8 ()
pixelAt x y = withTexture (uniformTexture $ PixelRGBA8 0 0 0 255)
$ fill
$ rectangle (V2 (fromIntegral $ x*size) (fromIntegral $ y*size))
(fromIntegral size)
(fromIntegral size)

Tying it all together

We just need one central conway.erl which exports main/1, which lets us call this from the command line.

erlang


-module(conway).
%% API exports
-export([main/1]).
% Modify this file to generate your own.
main([Pattern]) ->
case Pattern of
"random" -> board:init( fog:getFog(100,100), 100, {100,100} );
"blinker" -> board:init( [0,0,0,0,0
,0,0,1,0,0
,0,0,1,0,0
,0,0,1,0,0
,0,0,0,0,0], 2, {5,5});
% board:init(<initial_state>, <runtime>, {<width>,<height>})
...
end.

I wrote a teeny fog.erl module which wraps the builtin random number generator, which is how we achieve the main gif at the top of the page, where the starting state is a random haze of pixels. For the other patterns, we manually define the starting pattern with a list (not array) of ones and zeros.

Performance

It took about 30s to render the 100x100 grid above for 100 frames, which is not too bad. One optimization that could have helped would have been to decouple the time it takes to write out the frame from the main board tick loop by spawning a process and not waiting for it to complete before dying. There might be a resource constraint there where it’s not great to have more than, say, 10 copies of render.hs running at once; a mutex might be a useful resource for solving that issue in a concurrent way.

Additionally, it would have been very cool to learn how to write bitmaps in raw binary. Erlang isn’t so good at image rendering, but it’s quite good at interfacing with the machine at a lower level; writing out raw bitmaps with individual pixels colored in (or not) might have been an elegant solution here.

Results

OK, here are some cool oscillators I stole from Wikipedia. You can call them by name as the first argument to the conway executable under Run. They are:

`blinker`

`toad`

`beacon`

`pulsar`

`pentadecathlon`

`random` (seen at the top of the page)

Puzzle Pong III - Irreversible Cube II

Sat, 02 Sep 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/84fca250c25f72b46a16dd28eb653708

The Puzzle

This is a continuation of Puzzle Pong - Irreversible Cube I. In the first part, Josh Mermelstein posed me a series of questions about the Irreversible Cube:

Oskar van Deventer {1} presents an Irreversible Cube in his 2013 video {2} which is an ordinary 2x2x2 Rubix Cube where you are only allowed to turn any face clockwise, and only once in a row.

By the end of part 1), I had a fairly poor approximation of an isometric projection, which was able to take a set of points and turn them into tilted tiles along one of three skew planes. This was pretty good for seeing what state the cube might be in at any given stage, but it was not a true 3D rendering, meaning that my higher goals of animating a real turn were next-to-impossible.

This inspired a separate Haskell library, Cornea for isometric 3D graphing and rendering, which I discuss here. Cornea has the benefit of being easily mapped to write out either a single image or a series of images, which can be stitched together into animations.

In this post, I’ll discuss wrapping the Irreversible Cube solver from part I into something which can render animations of the cube in the process of being solved.

Changes

Recall our custom type definitions:

haskell


data Side = F | B | U | D | L | R deriving (Eq, Bounded, Show, Enum, Ord)
data Axis = X | Y | Z deriving (Eq, Show)
data Cardinality = Pos | Neg deriving (Eq, Show)
type Rotation = (Coord -> Coord)
type Coord = [Int]
type Tile = Coord
type Cube = [Tile]

The biggest change we must make from the old way of doing things is to rewrite mkRot :: Cardinality -> Axis -> Rotation to rely on a much more general rotate :: Float -> Axis -> [x,y,z] -> [x',y',z'] under the hood. That way, we can still do things like

given a turn on face L
-> run through sideToCardinalityAndAxis s2CA(L) = (Neg, Y)
-> get cardinality Neg and axis Y
-> mkRot Neg Y -> (\[x,y,z] -> rotate (-90) Y [x,y,z])

Or, when we need to start calculating in-between frames (tweens) for our side rotation animation, we can do things like

rotateFace :: Float -> Axis -> Obj -> Obj
rotateFace <angle> <axis> (Face pts) = Face (map (rotate <angle> <axis>) pts)

Here’s the code that makes that happen.

haskell


mkRot :: Cardinality -> Axis -> Rotation
mkRot c a = map (\x -> round x :: Int) . rotate (toAngle c) a . map fromIntegral
s2Rot :: Side -> Rotation
s2Rot = uncurry mkRot . s2CA
s2CA :: Side -> (Cardinality, Axis)
s2CA F = (Pos, X); s2CA R = (Pos, Y); s2CA U = (Pos, Z);
s2CA B = (Neg, X); s2CA L = (Neg, Y); s2CA D = (Neg, Z);
rotate :: Float -> Axis -> [Float] -> [Float]
rotate t X [x,y,z] = [ x , cos t * y - sin t * z , sin t * y + cos t * z]
rotate t Y [x,y,z] = [ cos t * x + sin t * z , y , -sin t * x + cos t * z]
rotate t Z [x,y,z] = [ cos t * x - sin t * y , sin t * x + cos t * y , z ]
rotateFace :: Float -> Axis -> Obj -> Obj
rotateFace t a (Face pts) = Face (map (rotate t a) pts)
toAngle :: Cardinality -> Float
toAngle Pos = pi/2; toAngle Neg = -pi/2

Now we can just write twist as

haskell


twist :: Side -> Cube -> Cube
twist side = map (\x -> if side `sees` x then s2Rot side x else x)
sees :: Side -> (Coord -> Bool)
(sees) F = (>0) . (!!0); (sees) R = (>0) . (!!1); (sees) U = (>0) . (!!2);
(sees) B = (<0) . (!!0); (sees) L = (<0) . (!!1); (sees) D = (<0) . (!!2);

Seqeuence of Moves

As for the algorithm, seed and kids stay the same; we end up producing the sequence of moves the same way with the same call.

haskell


moves = reverse $ snd $ head $ filter (solved.fst) $ concat
$ iterate (concatMap kids) seed

Rendering a Cube

Things have changed a little bit; instead of projecting squares and skewing/translating them, we have to actually describe the four corner coordinates of a tile in able to render it in 3d space.

Recall that we store Tiles as 3-tuples describing the center of the tile in question; if a tile is on the top face of the cube, it will have coordinates $(\pm 1, \pm 1, +2)$, etc. Tiles don’t come bundled with normal vectors describing their face orientation, so there’s nothing to it here but to hard-code this logic.

haskell


toTile :: [Int] -> Obj
toTile [x,y,z] = p2t' [fromIntegral x, fromIntegral y, fromIntegral z]
where p2t' [ x, y, 2] = Face [ [x+a, y+b, n] | (a,b) <- rg ]
p2t' [ x, y,-2] = Face [ [x+a, y+b, -n] | (a,b) <- rg ]
p2t' [ x, 2, z] = Face [ [x+a, n, z+b] | (a,b) <- rg ]
p2t' [ x,-2, z] = Face [ [x+a, -n, z+b] | (a,b) <- rg ]
p2t' [ 2, y, z] = Face [ [ n, y+a, z+b] | (a,b) <- rg ]
p2t' [-2, y, z] = Face [ [-n, y+a, z+b] | (a,b) <- rg ]
rg :: Num a => [(a,a)]
rg = [(1,1),(1,-1),(-1,-1),(-1,1)] --range
n = 5 --offset

We use n as a way to control how “exploded” the cube is; at the beginning I rendered cubes as n=2 to draw the cube realistically; later we can tune it up to explode the cube more and more.

Animation

We have a couple of options here; let’s start simple and work our way up in complexity.

We can scanr and sequentially apply moves over a solvedCube to get a sequence of cubes in various staged of solved-ness.

If we write toImage <cube> <viewpoint> to return an Image px of the cube (zipped with our custom kolors color-sequence),

haskell


toImage :: [Obj] -> (Float, Float) -> Image PixelRGBA8
toImage cs v = render 500 500 40 $ world `seenFrom` v
where world = map (second solid) $ zip cs kolors

Then we can write an animate function. In this case, because we want to do our styling in toImage, we only need an array of [Obj]s as our input. animate accepts a series of cubes, a series of viewpoints, and a series of filenames:

haskell


animate :: [[Obj]] -> [(Float,Float)] -> [String] -> IO ()
animate cs vs fs = mapM_ (\(c,v,f) -> writePng f $ toImage c v) $ zip3 cs vs fs

This is great. Let’s call something like:

haskell


main = do
let frames = map (map toTile) $ reverse $ scanr twist solvedCube moves
let views = repeat isometric
let filenames = map (\i -> "/tmp/frame" ++ show i ++ ".png") [100000..]
animate frames views filenames

We can see the turns a bit more clearly if we explode the cube by tuning up n, as noted above:

Animating Motion

This is pretty good, but the whole point of a real isometric projection library is the ability to draw tiles in places other than along x-y, x-z, or y-z planes. Let’s try tweening frames.

Tweening is a concept from animation wherein, given a start and end position and a desired number of inbetween frames, we can generate those inbetween frames. This is a little like interpolation, but there are lots of different easing curves out there. For now we’ll stick with linear motion, though.

We want tween to take not a beginning- and end-state cube, but instead a beginning-state cube and a Side to turn (and a number of frames across which to turn it.

haskell


tween :: Int -> Side -> Cube -> [[Obj]]
tween num side cube = map (`swivel` cube) angles
where (cardinality, axis) = s2CA side
angles = map (* toAngle cardinality) $ init
$ map (/ fromIntegral num) [0..(fromIntegral num)]
swivel :: Float -> Cube -> [Obj]
swivel ang = map (\t -> if side `sees` t
then rotateFace ang axis $ toTile t
else toTile t
)

swivel is just a local implementation of twist above, with an inline renderer (toTile) which returns [Obj]s instead of Cubes. We generate a sequence of angles by using toAngle from above, and then simply return a series of cubes with more and more of the desired twist angle applied to it.

Now our frames looks like:

haskell


let frames r = concatMap (uncurry $ tween r)
$ zip (reverse moves) (reverse $ scanr twist solvedCube moves)

where r the framerate, sort of - the number of frames across each turn should occur.

If we write something like

haskell


main = do
let frames = concatMap (uncurry $ tween 20)
$ zip (reverse moves) (reverse $ scanr twist solvedCube moves)
let views = repeat isometric
let filenames = map (\i -> "/tmp/frame" ++ show i ++ ".png") [100000..]
animate frames views filenames

We might get something like

Roving Camera

Just for fun, let’s create a series of views which, knowing the length of the frameset, does a complete yaw rotation. (Also we’re retuning n=3 here for a more exploded view.)

haskell


mkViews :: Int -> [(Float,Float)]
mkViews n = zip ps ys
where ys = take n [0, (360 / fromIntegral n).. ]
ps = [35,35..]

haskell


main = do
...
let views = mkViews (length frames)
animate frames views filenames

Conclusion

These are all pretty fast to render, with the bulk of the difficulty being from running convert after a run to stitch the produced .pngs together into a gif. Presumably convert holds the frames in-memory, which gets expensive for longer animations; I found that using Codec.Picture to do the same thing in-Haskell was equally or more expensive.

Cornea, an Isometric 3D Graphing Module for Haskell

Wed, 30 Aug 2017 00:00:00 -0400

Github	http://github.com/ambuc/cornea

While working on the rendering my solution for the Irreversible Pocket Cube, I ended up writing a faux isometric rendering engine which could turn my specific Rubix Cube datastructure into something like an isometric projection of that cube. This my attempt to do it the right way.

The full code lives at ambuc/Cornea.

Mathematics

To quote Wikipedia,

$$ \begin{bmatrix} b_x \\ b_y \\ 0 \end{bmatrix} = \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 0 \end{bmatrix} \begin{bmatrix} 1 & 0 & 0 \\ 0 & \cos\alpha & \sin\alpha \\ 0 & -\sin\alpha & \cos\alpha \end{bmatrix} \begin{bmatrix} \cos\beta & 0 & -\sin\beta \\ 0 & 1 & 0 \\ \sin\beta & 0 & \cos\beta \end{bmatrix} \begin{bmatrix} a_x \\ a_y \\ a_z \end{bmatrix} $$

where $\alpha$ and $\beta$ are the pitch and yaw of the camera angle; that is, how far from the equator and meridian in spherical coordinates our viewpoint resides, if the center of the scene is at the origin. This projection matrix works for any 3d point $ \begin{bmatrix} a_x & a_y & a_z \end{bmatrix}^\intercal $ and results in 2d coordinates $ \begin{bmatrix} b_x & b_y & 0 \end{bmatrix}^\intercal $.

haskell


metric :: (Float, Float) -> Matrix Float
metric (p, w) = m1 * m2
where m1 = fromList 3 3 [1, 0, 0, 0, 1, 0, 0, 0, 0]
m2 = fromList 3 3 [1, 0, 0, 0, cos a, sin a, 0, -sin a, -cos a]
* fromList 3 3 [cos b, 0, -sin b, 0, 1, 0, sin b, 0, cos b]
where a = p * pi / 180; b = w * pi * 2 / 360

That’s really all the projection math we need. The name metric is sort of a play on isometric, except the function is extensible and can return a transformation matrix for any viewing angle, not just the default $(35.264,45)$ isometric viewing angle.

Describing the World

haskell


data Obj = Cord [Float] | Edge [[Float]] | Face [[Float]] deriving (Eq, Show)
type Style = ([Primitive] -> Drawing PixelRGBA8 ())
type World = [(Obj, Style)]

Let’s define an Obj object as either

a single point, a [Float] list of three floating point numbers describing its $(x,y,z)$ coordinates, or
a list of points describing a line or polyline, or
a list of points describing a face

Styling the World

We want to be able to style each of these objects. Because I like Graphics.Rasterific, we’ll use their types and define style as a mapping between a [Primitive] and a final Drawing px (). In practice we would use the builtin withTexture (uniformTexture <color>) . fill for a solid fill, or withTexture (uniformTexture <color>) . stroke <width> JoinRound (CapRound, CapRound) for a stroke (used for a line, polyline, or point). In practice it would be nice to provide synonyms in the form of solid k and mark k n.

haskell


solid :: Geometry geom => PixelRGBA8 -> geom -> Drawing PixelRGBA8 ()
solid k = withTexture (uniformTexture k) . fill
mark :: Geometry geom => PixelRGBA8 -> Float -> geom -> Drawing PixelRGBA8 ()
mark k n = withTexture (uniformTexture k)
. stroke n JoinRound (CapRound, CapRound)

Projecting an Object onto a Drawing

Let’s define a convenient type synonym View for our pitch/yaw tuple:

haskell


type View = (Float,Float)

and write a proj v <obj> function which can take a coordinate and project it into the plane.

haskell


proj :: (Float,Float) -> Obj -> V2 Float
proj v (Cord [x,y,z]) = (\[x,y] -> V2 x y) $ take 2 $ toList
$ metric v * Data.Matrix.transpose (fromList 1 3 [y,-z,x])

Great. Now we can plot a coordinate by simply projecting it into the plane. We should be able to plot a line or polyline by projecting each of its coordinates, and a face (or polygon) the same way.

haskell


drawFrom :: (Obj, [Primitive] -> t) -> (Float, Float) -> t
(Cord coord, sty) `drawFrom` v = sty $ circle (proj v $ Cord coord) 0.5
(Edge pts , sty) `drawFrom` v = sty $ polyline $ map (proj v . Cord) pts
(Face pts , sty) `drawFrom` v = sty $ polygon $ map (proj v . Cord) pts

Very cool. Let’s construct a sample world and try writing it to a .png.

Writing to `.png`

Here’s our calibration world:

haskell


calibWorld :: World
calibWorld = [ ( Edge [[0,0,0], [15, 0, 0]] , mark (PixelRGBA8 255 100 100 255) 1)
, ( Edge [[0,0,0], [ 0,15, 0]] , mark (PixelRGBA8 100 255 100 255) 2)
, ( Edge [[0,0,0], [ 0, 0,15]] , mark (PixelRGBA8 100 100 255 255) 3)
]

Now we need a function which can turn a list of these (Obj,Style) tuples into a single Drawing px () item. We really want to map drawFrom over each of them, and then sequence_ [] the list; we can write that as mapM_ instead, which maps a monad over a list of inputs, discarding the intermediate results along the way.

haskell


seenFrom :: World -> (Float,Float) -> Drawing PixelRGBA8 ()
world `seenFrom` v = mapM_ (`drawFrom` v) world

The very final piece of our puzzle is something which takes a Drawing px () and actually turns it into an Image px, which can be written to .png with Rasterific’s writePng.

We’ll need to supply render with a width/height/scale

haskell


render :: Int -> Int -> Float -> Drawing PixelRGBA8 () -> Image PixelRGBA8
render x y s d = renderDrawing x y (PixelRGBA8 255 255 255 255)
$ withTransformation ( translate (V2 (fromIntegral x / 2)
(fromIntegral y / 2)
) <> scale s s
) d

Great. Let’s write this Drawing px () out to an Image px () and eventually to a file IO ().

haskell


main = writePng "canvas.png" $ render 500 500 12 $ calibWorld `seenFrom` (35,45)

That’s super! Let’s try something more complicated: define myWorld to be a bunch of intersecting squares along the x-y and y-z planes:

haskell


myWorld :: World
myWorld = [ ( Face [[0,0,0], [0, 10,0], [ 10, 10,0], [ 10,0,0] ] , solid $ PixelRGBA8 255 100 0 255)
, ( Face [[0,0,0], [0,-10,0], [ 10,-10,0], [ 10,0,0] ] , solid $ PixelRGBA8 255 120 0 255)
, ( Face [[0,0,0], [0,-10,0], [-10,-10,0], [-10,0,0] ] , solid $ PixelRGBA8 255 140 0 255)
, ( Face [[0,0,0], [0, 10,0], [-10, 10,0], [-10,0,0] ] , solid $ PixelRGBA8 255 160 0 255)
, ( Face [[0,0,0], [ 10,0,0], [ 10,0, 10], [0,0, 10] ] , solid $ PixelRGBA8 255 180 0 255)
, ( Face [[0,0,0], [-10,0,0], [-10,0, 10], [0,0, 10] ] , solid $ PixelRGBA8 255 200 0 255)
, ( Face [[0,0,0], [-10,0,0], [-10,0,-10], [0,0,-10] ] , solid $ PixelRGBA8 255 220 0 255)
, ( Face [[0,0,0], [ 10,0,0], [ 10,0,-10], [0,0,-10] ] , solid $ PixelRGBA8 255 240 0 255)
]

And render it as before:

haskell


main = writePng "canvas.png" $ render 500 500 12
$ (calibWorld++myWorld) `seenFrom` (35,45)

Uh-oh. We’re running into the visibility problem, wherein we don’t know which order to render the faces in so that the things nearer the camera would be visible over the things farther from the camera.

The Visibility Problem

There are a bunch of ways to solve this problem, but I ended up computing a vector from the origin to the centroid of each object, defining a vector from the origin to the position of the camera, and ranking the objects by the scalar projection of each object’s centroid-vector onto the camera-vector.

haskell


scalarProject u v = dot v (unit u)
where dot a b = sum $ zipWith (*) a b
unit n = map (/ norm n) n
norm = sqrt . sum . map (^2)
avgPts :: [[Float]] -> [Float]
avgPts = map (\xs -> realToFrac (sum xs) / genericLength xs)
. Data.List.transpose
centroid :: Obj -> [Float]
centroid (Cord coord) = avgPts [coord]
centroid (Edge pts ) = avgPts pts
centroid (Face pts ) = avgPts pts
closeness :: (Float,Float) -> [Float] -> Float
closeness (p,w) [x, y, z] = scalarProject (toBaseline p w) [x,y,z]
where toBaseline :: Float -> Float -> [Float] -- pitch, yaw in degrees
toBaseline p w = [cos theta * sin phi, sin theta * sin phi, cos phi]
where theta = w * c; phi = (90-p) * c; c = pi / 180;

Now, instead of just mapM_ (`drawFrom` v) world we can write:

haskell


seenFrom :: World -> (Float,Float) -> Drawing PixelRGBA8 ()
world `seenFrom` v = mapM_ (`drawFrom` v)
$ sortBy (comparing $ closeness v . centroid . fst) world

Which uses a Data.List builtin sortBy (comparing <comparison_fn>) list to reorder a list according a custom comparison_fn. You could write one like (\a b -> if a > b then a else b), or we could use comparing to rank by an implicit function of each item.

In this case, that implicit function is closeness v . centroid . fst, which takes each (Obj, Style) tuple, extracts the Obj, finds its centroid, and finds the closeness by calculating the scalar product of that centroid-origin vector with the viewpoint-origin vector.

This gets us something a little more reasonable:

Animation

This is pretty cool, but what if we want to animate our world?

Let’s define a series of pitches and yaws to make a cool wobbling sweep around our world. Again, mapM_ lets us map our writePng function over a list of 3-tuples containing the pitch, yaw, and frame number. We can write them out to /tmp/canvas*.png…

haskell


pitches = ( map (\x -> 20 * (sin (x * pi / 12) + 1.5)) [0,1..] )
yaws = [0,5..355]
main = do
mapM_ (\(p,w,i) -> writePng ("/tmp/canvas" ++ show i ++ ".png")
$ render 500 500 $ (calibWorld++myWorld) `seenFrom` (p,w)
) $ zip3 pitches yaws [10..]

…and compose them together into a .gif later with convert -loop 0 /tmp/canvas* \<filename\>.

Here’s that contrasted with an animation from before we solved the visibility problem:

Animating with `Codec.Picture.Gif`

Codec.Picture supports assembling Images into gifs in Haskell, without having to write the frames out to a file and assembling them with convert. It’s a lot slower, though. I’ll present it here just out of interest, but in practice I found it anywhere from 8x-10x slower.

haskell


import Codec.Picture
import Codec.Picture.Gif
import Codec.Picture.Types
import Cornea -- this is our module! If you check out the repo
-- at the very top of the page, you can see how we wrap it into
-- an importable module.
-- same calibWorld and myWorld as above
options :: PaletteOptions
options = PaletteOptions { paletteCreationMethod=MedianMeanCut, enableImageDithering=True, paletteColorCount=256 }
main = head $ rights
$ [ writeGifImages "animation.gif" LoopingForever
$ map ( (\(i,p) -> (p,2,i)) --arbitrary framerate
. (\(p,w) -> palettize options
$ dropAlphaLayer
$ render 500 500 12 $ (calibWorld++myWorld) `seenFrom` (p,w)
)
) $ zip ( map (\x -> 20 * (sin (x * pi / 120) + 1.5)) [0,1..] )
[0,1..359]
]

This took ~3min and I see a bit of flickering – probably because the command-line convert utility understands color and framerate better than I do.

Conclusions

This is a neat little library, just powerful enough to handle the matrix multiplication necessary to take a scene depicted in raw coordinates and render it in a useful way. I have no idea what its performance will be like for a larger scene, but I’ll continue to use it in the future and we’ll see what sorts of optimizations can be made.

I’ve put it on Github here: ambuc/cornea in the hopes that someone else might get a kick out of it.

Puzzle Pong III - Irreversible Cube I

Tue, 22 Aug 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/84fca250c25f72b46a16dd28eb653708

The Puzzle

Josh Mermelstein and I have decided to begin challenging each other to a series of a math/programming puzzles. Here was his most recent puzzle:

Oskar van Deventer presents an Irreversible Cube in his 2013 video which is an ordinary 2x2x2 Rubix Cube where you are only allowed to turn any face clockwise, and only once in a row.

(1) Give this cube a single twist from solved position. How many twists should it take, at minimum, to return to a solved position?

(2) For this cube, what is God’s Number?

I’ll address 1) in this post and 2) in another.

I didn’t think that the math involved in representing the cube, performing turns on it, or validating its solved-ness should be very difficult. What concerned me was difficulty in debugging these operations in the first place. Without a visualizer, it would be hard to know that my turn was working as intended. I wanted to build an engine which could take my representation of a cube and draw it, preferably in a way close to its actual 3d appearance.

Representing a Cube

We represent a cube as an ordered list of points in 3d space. Implicitly, the first four are red, the second four are yellow, etc. This makes it easy to perform twists on the cube. Half the list will be on one side or another of the x, y, or z-plane, and they can be rotated about some axis while remaining put in the list.

A solved cube looks like this:

[ [ 1, 1, 2], [ 1,-1, 2], [-1, 1, 2], [-1,-1, 2]
, [ 1, 1,-2], [ 1,-1,-2], [-1, 1,-2], [-1,-1,-2]
, [ 1, 2, 1], [ 1, 2,-1], [-1, 2, 1], [-1, 2,-1]
, [ 1,-2, 1], [ 1,-2,-1], [-1,-2, 1], [-1,-2,-1]
, [ 2, 1, 1], [ 2, 1,-1], [ 2,-1, 1], [ 2,-1,-1]
, [-2, 1, 1], [-2, 1,-1], [-2,-1, 1], [-2,-1,-1]
]

Our coordinate axis is such that the very center of the cube is $(0,0,0)$, and each tile is of dimensions $2\times 2\times 0$, such that the cube is in total $4\times 4\times 4$ in dimension. This places the centers of the tiles on the faces of the subcubes at points like $(1,1,2)$; all four tiles on a the top face would have centers $(\pm 1, \pm 1, 2)$, and the four tiles on the bottom face would have centers $(\pm 1, \pm 1, -2)$.

haskell


type Coord = [Int]
type Tile = Coord -- convenient synonym
type Cube = [Tile]

Drawing a Cube

Because the cube type carries no color information with it, the way we draw the cube is up to us. For ease of visualizing which unique tiles are which (telling apart two otherwise-identical red tiles, for example) I’ve chosen to draw each tile at a slightly different hue, generally grouped by the uniform colors a real cube might have.

I’m using the excellent Graphics.Rasterific package, which I’ve used before.

haskell


import Codec.Picture
( PixelRGBA8( .. ), writePng, Image)
import Graphics.Rasterific
import Graphics.Rasterific.Texture
(uniformTexture)
import Graphics.Rasterific.Transformations
(translate, skewX, skewY, rotate, scale)

I define some kolors which are cute little palettes of similar hues.

haskell


kolors :: [PixelRGBA8]
kolors = [ PixelRGBA8 255 x 0 255 | x <- [000,050,100,150] ] -- reds
++ [ PixelRGBA8 x 0 128 255 | x <- [000,050,100,128] ] -- purples
++ [ PixelRGBA8 0 x 255 255 | x <- [000,050,100,128] ] -- cyans
++ [ PixelRGBA8 x 255 0 255 | x <- [150,170,190,210] ] -- greens
++ [ PixelRGBA8 255 0 x 255 | x <- [255,200,150,100] ] -- pinks
++ [ PixelRGBA8 x x x 255 | x <- [100,125,150,175] ] -- greys

And of course the solvedCube itself:

haskell


solvedCube :: Cube
solvedCube = [ [ a, b, 2] | a <- [1,-1], b <- [1,-1] ] -- F
++ [ [ a, b,-2] | a <- [1,-1], b <- [1,-1] ] -- B
++ [ [ a, 2, b] | a <- [1,-1], b <- [1,-1] ] -- R
++ [ [ a,-2, b] | a <- [1,-1], b <- [1,-1] ] -- L
++ [ [ 2, a, b] | a <- [1,-1], b <- [1,-1] ] -- U
++ [ [-2, a, b] | a <- [1,-1], b <- [1,-1] ] -- D

Here’s the meat and potatoes.

Our drawing style is inspired by the following exploded isometric drawing, which I accidentally stole from a tutorial for Direct3D 11

This is roughly isometric, which means we’ll need to concern ourselves with which tile to draw first, so that nearer tiles are layered over (drawn later than) further tiles.

To draw a cube (which is just an ordered list of 3d points, the centers of the 24 tiles), we zip it with the list of kolors, and then re-order the entire list by z-index, which we approximate by the sum of the three coordinates themselves. (the sortBy (comparing $ sum . fst) bit.). Then we uncurry drawTile, which takes each element of the [(coordinate, color)] list of tuples, calls drawTile crd clr, and then sweeps thru the list calling mapM_, which composes the monadic Drawing PixelRGBA8 () I/O type nicely.

haskell


:t renderDrawing Int -> Int -> px -> Drawing px () -> Image px
:t writePng FilePath -> Image px -> IO ()

We get a final Drawing * () which we can renderDrawing <drawing> to turn into an Image *, and finally writePng <filepath> <image>. That’s just how Rasterific handles things.

haskell


drawCube :: Cube -> Image PixelRGBA8
drawCube c = renderDrawing 600 600 (PixelRGBA8 255 255 255 255)
$ mapM_ (uncurry drawTile)
$ sortBy (comparing $ sum . fst)
$ zip c kolors

OK, here’s the crazy bit. We take a coordinate crd (and a color clr to shade it, draw that as a $100x100$ pixel square in the upper-left-hand corner of the canvas, and then use a composition of several translate and scale and rotate and skewX / skewY linear matrix transformations to move the tile into the position we want it.

We compose these transformations by calling functions resize, move0, turn, skew, move1 as functions of [x,y,z], which know by how much to resize, move, turn, skew, etc. each individual tile based on its desired eventual location, angle, what have you.

It would be cool to in the future write a simple projection library which can take a 3d tuple and an assumed camera position and generate this transformation automatically. I did a bit of hand-tuning.

haskell


drawTile :: Tile -> PixelRGBA8 -> Drawing PixelRGBA8 ()
drawTile crd clr = withTransformation (center<>resize<>move0<>turn<>skew<>move1)
$ withTexture (uniformTexture clr)
$ fill $ rectangle (V2 0 0) 100 100
where [x ,y ,z ] = crd
[x',y',z'] = [fromIntegral x, fromIntegral y, fromIntegral z]
center = translate (V2 300 300)
resize | abs z == 2 = scale 1.0 1.0
| otherwise = scale 0.9 0.9
move0 | x == 2 = translate (V2 (-250) 50 ) --F
| x == -2 = translate (V2 150 (-200)) --B
| y == 2 = translate (V2 150 120 ) --R
| y == -2 = translate (V2 (-250) (-140)) --L
| z == 2 = translate (V2 0 (-230)) --U
| z == -2 = translate (V2 0 120 ) --D
| otherwise = translate (V2 0 0 )
turn | abs z == 2 = rotate 0.7853
| otherwise = rotate 0
skew | abs z == 2 = skewX (-0.2) <> skewY (-0.2)
| abs y == 2 = skewY (-0.6)
| abs x == 2 = skewY 0.6
| otherwise = skewX 0
move1 | abs z == 2 = translate (V2 ( 50*y') ( 50*x'))
| abs y == 2 = translate (V2 (-50*x') (-50*z'))
| abs x == 2 = translate (V2 ( 50*y') (-50*z'))
| otherwise = translate (V2 0 0 )

To print an image we can simply write:

haskell


main = do
writePng "solved.png" $ drawCube solvedCube

And here’s what our solved cube looks like, finally.

Manipulation

There are basically two things you can do with a $2\times 2\times 2$ cube – either turn the entire thing about an axis or twist exactly half of it about an axis.

Let’s define some new data types to make thinking about this easier.

haskell


data Side = F | B | U | D | L | R deriving (Eq, Bounded, Show, Enum, Ord)
data Axis = X | Y | Z
data Cardinality = Pos | Neg
type Rotation = (Coord -> Coord)

At the most basic level, we want the ability to rotate a point clockwise or counter-clockwise exactly a quarter-turn (that is, $90^\circ$ or $\pi/2 \text{rad}$) about a line.

Pivoting

There is a pretty general form for rotating a vector any turn about any line. But rather than deal with $\sin$s and $\cos$s, let’s see if we can’t limit that transformation to only quarter-turns. Using a robotics convention, we will write $\sin\theta$ as $s\theta$ and $\cos\theta$ as $c\theta$ for brevity.

$$ R_x(\theta) = \begin{bmatrix} 1&0&0 \\ 0&c\theta&-s\theta \\ 0&s\theta&c\theta\end{bmatrix} \qquad R_y(\theta) = \begin{bmatrix} c\theta&0&s\theta \\ 0&1&0 \\ -s\theta&0&c\theta \end{bmatrix} \qquad R_z(\theta) = \begin{bmatrix} c\theta&-s\theta&0 \\ s\theta&c\theta&0 \\ 0&0&1 \end{bmatrix} $$

We can apply this rotation matrix to a vector with basic matrix multiplication, like so:

$$ \begin{bmatrix}a&b&c \\ d&e&f \\ g&h&i\end{bmatrix} \begin{bmatrix}x \\ y \\ z\end{bmatrix} = \begin{bmatrix}ax+by+cz \\ dx+ey+fz \\ gx+hy+iz\end{bmatrix} $$

So what if $\theta=\pm90^\circ$? We get much simpler forms for $\pm R_x$, $\pm R_y$, and $\pm R_z$:

$$
\begin{align*} R_x (+90^\circ) &= \begin{bmatrix}1&0&0 \\ 0&0&-1 \\ 0&1&0\end{bmatrix} & \qquad R_x (-90^\circ) &= \begin{bmatrix}1&0&0 \\ 0&0&1 \\ 0&-1&0\end{bmatrix} \\ R_y (+90^\circ) &= \begin{bmatrix}0&0&1 \\ 0&1&0 \\ -1&0&0\end{bmatrix} & \qquad R_y (-90^\circ) &= \begin{bmatrix}0&0&-1 \\ 0&1&0 \\ 1&0&0\end{bmatrix} \\ R_z (+90^\circ) &= \begin{bmatrix}0&-1&0 \\ 1&0&0 \\ 0&0&1\end{bmatrix} & \qquad R_z (-90^\circ) &= \begin{bmatrix}0&1&0 \\ -1&0&0 \\ 0&0&1\end{bmatrix} \end{align*} $$

If we apply these simplified transformation matrices to $$\begin{bmatrix}x&y&z\end{bmatrix}^\intercal$$, we get extremely efficient, simple vector transformation anonymous functions:

haskell


mkRot :: Cardinality -> Axis -> Rotation
mkRot Pos X = \[x,y,z] -> [x,-z,y]; mkRot Neg X = \[x,y,z] -> [x,z,-y];
mkRot Pos Y = \[x,y,z] -> [z,y,-x]; mkRot Neg Y = \[x,y,z] -> [-z,y,x];
mkRot Pos Z = \[x,y,z] -> [-y,x,z]; mkRot Neg Z = \[x,y,z] -> [y,-x,z];

Writing the pivot function, which looks like newCube = pivot <cardinality> <axis> oldCube, for example, is really just a map:

haskell


pivot :: Cardinality -> Axis -> Cube -> Cube
pivot r a = map (mkRot r a)

Twisting

Let’s look into the future just a little bit.

It’s the future. We’ve written our pivot/twist functions and we start exploring the space of possible cubes. Oh no! We have two cubes and we want to know if they’re the same. It’s possible that they are the same colors in the same configuration, but one is the pivoted version of another. If we just compare the points one by one, they won’t match up. And we can’t possibly generate all 24 possible pivots of $\text{cube}_A$ just to see if any of them matches $\text{cube}_B$.

What we really want is a default position for any cube. resolve takes a cube and returns that same cube, rotated according to a regular set of rules. In this case, we want to rotate the cube so that the center of the very first tile in it (the first red tile, or what have you) is located at point $(1,1,2)$.

If it’s not, but it’s located at $(?,?,2)$, we give the whole thing a clockwise Z-axis pivot and check again. It’ll get there eventually. If it’s located at $(?,?,-2)$, we flip it and try again. (Etc, etc.)

This iterative algorithm is on average quite a bit faster than checking all 24 possible pivots of a cube.

haskell


resolve :: Cube -> Cube
resolve c = resolve' $ head c
where resolve' [ 1, 1, 2] = c
resolve' [ _, _, 2] = resolve $ pivot Pos Z c
resolve' [ _, _,-2] = resolve $ pivot Pos X $ pivot Pos X c
resolve' [ _, 2, _] = resolve $ pivot Pos X c
resolve' [ _,-2, _] = resolve $ pivot Neg X c
resolve' [ 2, _, _] = resolve $ pivot Neg Y c
resolve' [-2, _, _] = resolve $ pivot Pos Y c

OK, now we can write our twist function.

haskell


twist :: Side -> Cube -> Cube
twist side = resolve . map (\x -> if isOn side x then s2Rot side x else x)
where
isOn :: Side -> (Coord -> Bool)
isOn F = (>0) . (!!0); isOn R = (>0) . (!!1); isOn U = (>0) . (!!2);
isOn B = (<0) . (!!0); isOn L = (<0) . (!!1); isOn D = (<0) . (!!2);
s2Rot :: Side -> Rotation
s2Rot F = mkRot Pos X; s2Rot B = mkRot Neg X;
s2Rot R = mkRot Pos Y; s2Rot L = mkRot Neg Y;
s2Rot U = mkRot Pos Z; s2Rot D = mkRot Neg Z;

We need two helper functions, isOn and s2Rot, which only need to be scoped here. isOn takes a side and returns a function which, given a coordinate, evaluates whether or not that coordinate is on that side or not. s2Rot takes a side and returns a rotation function, so that s2Rot <side> <coord> does what you’d expect.

Solving a Cube

To solve a cube we need to define what a solved cube looks like. Luckily we already know what a solved cube looks like – because tiles are indexed and we expect to always pass them around in their resolved position, we can simply write:

haskell


solved :: Cube -> Bool
solved = (== solvedCube)

That’s a great first step.

Solving the Return from a Single Offset Problem

To recall the video, our current problem is to find the minimum number of moves it might take to, given a solved cube with a single twist in any direction, return to a solved position.

How do we explore the space of cubes? Well, for a 2x2 cube there’s actually only:

$$ \dfrac{ 8! \times 3^7 }{ 24 } = 7! \times 3^6 = 3,764,160$$

possible turns. Even trying all of thes positions just isn’t that bad. As we end up doing more complex things, we’ll spend more time optimizing this, but for now let’s just a) take our starter cube, b) give it all possible twists from that position, c) take all possible twists from those positions, etc. until we find a cube which is solved.

Here’s the caveat: because this cube is irreversible, we have to carry a history of the last turn. For convenience, we might as well carry a history of all turns, to make it easier to animate this solution later.

Let’s make our seed cube, which is a tuple; the first item is a twisted cube (doesn’t matter what side is twisted), and the second item is a list of performed moves so far.

haskell


seed :: [(Cube, [Side])]
seed = [ (twist U solvedCube, [U]) ]

Now let’s make a function to explore the space of possible “children” of a given cube. We’ll inspect the most recent turn, disallow it, and try the other two.

Even though a cube has six sides, we can only turn any given side clockwise, and turning the top face clockwise is actually the same as turning the bottom face clockwise. So we can really only operate on [R,F,U], not [R,F,U,L,B,D].

haskell


kids :: (Cube, [Side]) -> [(Cube, [Side])]
kids (c, h:hs) = [ (twist dir c, dir:h:hs) | dir <- delete h [R,F,U] ]

Ok, great! Let’s use iterate to explore the space; we can concatMap to apply the kids function to a list of input cubes and get out a flat list of output cubes. iterate applies the function to its own output over and over and returns a list of outputs; concat flattens the stream, and we can filter by which cubes are solved and print just the head (the snd of which is the winning sequence itself).

haskell


main = do
print $ snd $ head $ filter (solved.fst)
$ concat $ iterate (concatMap kids) seed

bash


j@mes $ ghc -O2 l.hs && time ./l
[1 of 1] Compiling Main ( l.hs, l.o )
Linking l ...
[F,R,F,R,F,R,U,F,R,F,R,F,R,U]
real 0m0.551s
user 0m0.547s
sys 0m0.003s

This is super fast, so I don’t really care yet about optimizing. But I do want to see what it looks like.

haskell


main = do
let seq = snd $ head $ filter (solved.fst)
$ concat $ iterate (concatMap kids) seed
mapM_ ( \(n,c) -> writePng ("frame" ++ show n ++ ".png")
$ drawCube $ resolve c
) $ zip [10..] $ scanr twist solvedCube seq

We can use scanr to gradually scan the list of turns across the solvedCube base by applying twist zero times, one time, two times, etc. We end up with a list of altered cubes, which we can zip with a list of indices. We can use mapM_ (which is a synonym for sequence_ . map) to write each cube out to a .png using writePng <filename> drawCube <cube>. Then we can run convert -delay 10 -loop 0 frame* animation.gif (bash, not Haskell) and get:

And that’s the 13-turn sequence it takes, at minimum, to return to a solved position from a single initial offset from a solved irreversible cube.

Conclusions

The next entry will deal with finding God’s Number.

Puzzle Pong II - Least Nonconstructable Positive Integer

Sun, 25 Jun 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/731f2d9b789a5e4e32bdafbd60bf7ff8

The Puzzle

Josh Mermelstein and I have decided to begin challenging each other to a series of a math/programming puzzles. Here was his most recent puzzle:

Given a) the list of numbers $[1, 2, 3, 4, 5]$, b) unlimited parentheses, and c) the operations $+$, $-$, $\times$, $/$, $\wedge$, and $!$, it is possible to construct many integers. For example,

$1 = 1 + 2 - 3 - 4 + 5$, and

$2 = 1 + (((2 + 3) * 4!) / 5!)$, etc.

What is the least positive integer that cannot be written this way?

Numbers must appear in order, each exactly once.

You may not take the factorial of a factorial (i.e. $(3!)! = 720$).

Concatination is forbidden (i.e. $1 + 23 + 4 + 5$).

Unary negative is forbidden (i.e. $13 = (-1) + 2 + 3 + 4 + 5$)

For some inspiration, please enjoy: {1} {2}

Let’s define this function a little more. I’d like to call the output the least nonconstructable positive integer, or $\text{LNPI}$ of an ordered list. In this case, the ordered list is $[1,2,3,4,5]$.

OK, how do we start?

Abstract Syntax Trees

Let’s represent an expression like $(1!+2)-3$ as an abstract syntax tree; terminal nodes are integers, and all the other nodes are operators.

$$(1! + 2) - 3$$

It makes sense to have two types of operators; functions of one argument, like the factorial, and combining functions of two arguments, like all the rest.

Haskell makes it easy to create abstract data types and start playing with them.

AST Implementation

We can represent our values Val as unrounded ratios of long ints, or Integers. This means we never lose precision to rounding / near-zero numbers.

haskell


type Val = Ratio Integer

As we discovered before, there are two things we can do to Vals:

take a function of one of them: $y = f(x)$
perform an operation on two of them: $y = f(x_1, x_2)$.

haskell


data Fn = Id | Fact deriving (Bounded, Enum)
data Op = Plus | Sub | Mult | Div | Exp deriving (Bounded, Enum)

Here Id is the identity function $y(x) = x$. The rest should be self-explanatory.

Finally we need an expression type Expr, which can be either:

a raw Val: V (Ratio Integer),
an expression E1 of 1 argument, which takes a function Fn and an expression to operate on, or
an expression E2 of 2 arguments, which takes an operation Op and a tuple of two expressions to operate on.

haskell


data Expr = V Val | E1 Fn Expr | E2 Op (Expr,Expr)

Let’s even derive custom Show instances so we can pretty-print them, for debugging purposes.

haskell


instance Show Op where
show Plus = "+"
show Sub = "-"
show Mult = "*"
show Div = "/"
show Exp = "^"
instance Show Expr where
show (V a) = show $ round a
show (E1 Id e) = show e
show (E1 Fact e) = show e ++ "!"
show (E2 o (e1,e2)) = "(" ++ show e1 ++ show o ++ show e2 ++ ")"

If we play with this in a ghci shell, we see:

> E2 Sub ( E2 Plus ( E1 Fact ( V 1 ), V 2 ), V 3 )
((1!+2)-3)

This is good. Let’s figure out how to evaluate these expressions.

Evaluation

The type signature of eval should be eval :: Expr -> Maybe Val, since not all expressions return values. (Imagine taking the factorial of a non-integer, or dividing by zero). To accomplish this in an elegant way we make use of monad stuff like =<<, <$>, and <*>, which is worth exploring in some detail in a moment.

haskell


eval :: Expr -> Maybe Val
eval (V a) = Just a
eval (E1 f e) = calc1 f =<< eval e
eval (E2 o (e1, e2)) = calc2 o =<< (,) <$> eval e1 <*> eval e2
calc1 :: Fn -> Val -> Maybe Val
calc1 Id a = Just a
calc1 Fact a = guard (isInt a && a<100 && a>0) >> Just f
where f = facts !! (pred . fromIntegral . numerator) a
calc2 :: Op -> (Val, Val) -> Maybe Val
calc2 Plus (a,b) = Just $ a + b
calc2 Sub (a,b) = Just $ a - b
calc2 Mult (a,b) = Just $ a * b
calc2 Div (a,b) = guard (b/=0) >> Just (a/b)
calc2 Exp (a,b) = makeExp
where makeExp
| a == 0 = Just 0
| a == 1 = Just 1
| not (isInt b) = Nothing
| abs b > 1023 = Nothing
| otherwise = Just $ a ^^ numerator b

Obviously not all computation is valid. We refuse to:

take the factorial of any negative number,
take the factorial of any non-integer, or
divide by zero.

One hurdle of this problem was the discovery that it is possible to quickly generate numbers too large for the computer to handle: for example,

$$\texttt{1+(2^(3^(4^5)))} = 1 + 2^{3^{4^5}} \approx 10^{10^{488}}$$

So we end up doing a fair bit of bounds checking. We also refuse to:

compute the factorial of any integer greater than a hundred,
take an exponent to the power of any non-integer,
take an exponent to the power of any number outside $[-1023..1023]$,

Additionally, we also precompute the factorial of all numbers for which the factorial is allowed, $[0..100]$, and store them in facts; thus calc1 Fact a is just a lookup with guards.

Finally, we avoid some computation by noticing that $a^1 = a$ and $0^b = 0$.

OK, let’s try evaluating the above expression!

haskell


input output
> eval $ E2 Sub (E2 Plus (E1 Fact (V 1), V 2), V 3) Just (0 % 1)
> eval $ E2 Sub (E2 Plus (E1 Fact (V 1), V 2), V 4) Just ((-1) % 1)
> eval $ E2 Div (V 1, V 0) Nothing

Perfect: when an expression is valid, we compute the Val as a Just (Ratio Integer); when an expression is invalid, we return Nothing.

Maybes and Monads

Let’s take a moment and explore some of the above Haskell in detail. I’m going to try and explain how I accidentally invented the Monad while trying to solve a subproblem, as was predicted in You Could Have Invented Monads! (And Maybe You Already Have.), a wonderful article about this exact phenomenon.

Imagine a function like calc1 :: Fn -> ? -> ?. How should we write this?

First Try

Writing it like calc1 :: Fn -> Maybe Val -> Maybe Val essentially requires us to write two cases:

haskell


calc1 :: Fn -> Maybe Val -> Maybe Val
calc1 _ Nothing = Nothing
calc1 Id (Just a) = Just a
calc1 Fact (Just a) = if (canFactorial a) then Just (factorial a) else Nothing

I’m not sure that will carry over well to calc2:

haskell


calc2 :: Fn -> (Maybe Val, Maybe Val) -> Maybe Val
calc2 _ (Nothing, _ ) = Nothing
calc2 _ (_, Nothing) = Nothing
calc2 Plus (Just a, Just b ) = Just $ a + b
calc2 Minus ...

This is OK, but let’s find a better way – maybe by assuming we won’t pass invalid expressions in the first place.

Second Try

Writing it like calc1 :: Fn -> Val -> Maybe Val assumes a valid expression, so we can write:

haskell


calc1 :: Fn -> Val -> Maybe Val
calc1 Id a = Just a
calc1 Fact a = if (canFactorial a) then Just (factorial a) else Nothing
calc2 :: Fn -> (Val, Val) -> Maybe Val
calc2 Plus (a,b) = Just $ a + b
calc2 Minus ...

This is much better. So if our type signatures look like

haskell


calc1 :: Fn -> Val -> Maybe Val
calc2 :: Fn -> (Val, Val) -> Maybe Val

then what does eval look like? It would need to do something like

haskell


eval :: Expr -> Maybe Val
eval (V a) = Just a
eval (E1 f e) = calc1 f (???)

And here’s where our trouble begins. Remember that we want to evaluate e before passing it into calc1. So we’d have to check if it was valid first.

haskell


eval (E1 f e) = if (isJust $ eval e)
then (calc1 f (fromJust $ eval e))
else Nothing

This is nuts. Luckily this type of implicit Maybe checking is easy, since the Maybe type is a monad, and implements the Monad, Functor, and Applicative types.

Functors, really quick

Quick functor recap:

map lets us apply a function over a list: map fn [x,y] = [fn x, fn y]
fmap lets us apply a function inside a container type: fmap f (m a) = m (f a).

Note also that <$> is an infix synonym for fmap. Confused? See the following examples:

haskell


> map (+1) [1,2] [2,3]
> fmap (+1) (Just 1) Just 2
> (+1) <$> Just 1 Just 2
> (+1) <$> Nothing Nothing

One benefit of fmapping over the Maybe monad is that if we pass it Nothing, it doesn’t need to unwrap and apply; it’ll just pass Nothing through unscathed.

`fmap`, really quick

So remember the above problem:

haskell


> calc1 Fact (4%1) Just (24%1)
> calc1 Fact Nothing <error>

OK, that’s expected. Let’s try using <$>

haskell


> calc1 Fact <$> Just (4%1) Just (Just (24%1))
> calc1 Fact <$> Nothing Nothing

So, good news and bad news. We can unwrap Just a and apply the function to the interior, but we pass it back re-wrapped, since that’s what <$> does. Sadly, that’s also what calc1 does. Here’s a clue:

haskell


> :type (<$>) (<$>) :: Functor f => (a -> b) -> f a -> f b

This makes sense: <$> expects a function like (a -> b) which doesn’t have an opinion on how to re-wrap b itself. So maybe <$> isn’t the function we want?

Monads, really quick

At this point I searched Hoogle for (a -> f b) -> f a -> f b and got, of course… the Monad.

haskell


> :type (=<<) (=<<) :: Monad m => (a -> m b) -> m a -> m b
> :type (>>=) (>>=) :: Monad m => m a -> (a -> m b) -> m b

There’s lots more to the monad, but for now we can use it as a way to take a value in context, apply a context-aware function, and return some output in context.

haskell


> calc1 Fact =<< Just (4%1) Just (24%1)
> calc1 Fact =<< Nothing Nothing

What about calc2? It needs to take a tuple of Exprs, and neither of them can be Nothing. Turns out we can use the fmap infix <$> and their friend the sequential application infix <*>. Here’s a set of three trials:

haskell


(+) <$> Just 1 <*> Just 2 Just 3
(+) <$> Just 1 <*> Nothing Nothing
(+) <$> Nothing <*> Just 2 Nothing

So finally we can simply write calc2 o =<< (,) <$> eval e1 <*> eval e2. Thus,

haskell


eval :: Expr -> Maybe Val
eval (V a) = Just a
eval (E1 f e) = calc1 f =<< eval e
eval (E2 o (e1, e2)) = calc2 o =<< (,) <$> eval e1 <*> eval e2

Solving the Puzzle

Technically this is all we need to start solving the puzzle. Now that we have a way to compose and evaluate expressions, we just need to generate and evaluate all of them.

Generating all expressions

Let’s talk about partitioning a strictly ordered list.

One interesting aspect of this problem is that because our numbers have to be in order, the nodes containing the values (for example) $[1..3]$ will appear in order, from left to right, as the terminal nodes of our AST. This means that we can generate all possible ASTs by taking our root node and splitting the numbers $[1..3]$ at some point, throwing the lesser half on the left, and the greater half on the right.

It’s easy to see how we can apply this recursively to generate all tree shapes. Then we can insert all possible iterations at each op node, and all possible functions at each function. There are only two functions, and one is Id which leaves the value untouched.

We implement the partition algorithm as:

haskell


mkPart :: [a] -> [([a],[a])]
mkPart xs = tail $ init $ zip (inits xs) (tails xs)

such that

haskell


> mkPartitions [1,2,3] [([1],[2,3]),([1,2],[3])]

`valuesFrom` in Theory

This is excellent. Let’s write the function valuesFrom, which takes an ordered list and returns all possible values which can be generated from combining it as described above. Note:

valuesFrom 1 will just be [1, 1!] = [1,1]
valuesFrom 3 will just be [3, 3!] = [3,6]

haskell


valuesFrom :: [Val] -> [Val]
valuesFrom [x] = mapMaybe eval [ E1 f (V x) | f <- functions ]
valuesFrom xs = mapMaybe eval [ E1 f $ E2 o (V va, V vb)
| f <- functions
, o <- operations
, (as, bs) <- mkPartitions xs
, va <- valuesFrom as
, vb <- valuesFrom bs
]

We use mapMaybe to map eval over a list and discard the Nothings (and fromJust the Just as). This is great! It doesn’t check for duplicates or anything, but it’s a good start.

Caching

In practice, we would like to cache valuesFrom.

Here’s why: in calling valuesFrom [1,2,3,4,5], we end up evaluating valuesFrom [2,3,4] twice: once as part of [1,2,3,4] and once as part of [2,3,4,5]. See the above tree, which is an expansion of the earlier one for a larger ordered list.

You can see we end up evaluating f([2,3]) twice, f([1,2]) twice, f([3,4]) twice, etc.

You can imagine how this inefficiency bares its teeth for higher-length ordered lists; evaluating f([1,2,3,4,5]) will evaluate [2,3] four times; as a part of [1,2,3],[1,2,3,4],[2,3,4], and [2,3,4,5].

So let’s generate a big Map. On that note, Map is Haskell’s version of a key/value pairing, what would be a dict in Python. Here’s what it will contain:

the keys in this map should be consecutive sequences like [1], [1,2], [2,3,4], [4,5], etc., and
the values should be sets of values S.Set Val which can be created from combining those numbers in the key.

To generate this recursively from the bottom up, we can first generate a map of all keys of length 1, and then use it to quickly generate a map of all keys of length 2, and so on and so on and so on.

Let’s do it.

`valuesFrom` in Practice

Here’s how it all looks together: valuesFrom range does a M.findWithDefault (S.empty) range on a map, which is the union of two smaller maps:

$$ \text{Map}([1..n]) = \text{Map}(n) \ \bigcup \ \text{Map}([1..(n-1)]) $$

where prevMap is the mkMap of a smaller subset, and thisMap is the set of the values of the expressions generated in exprsFrom, which uses valsFrom the partitioned right- and left-available values. Check it out:

haskell


valuesFrom :: [Val] -> S.Set Val
valuesFrom range = M.findWithDefault S.empty range
$ mkMap (length range)
where
mkMap :: Int -> M.Map [Val] (S.Set Val)
mkMap 0 = M.empty
mkMap n = M.union prevMap thisMap
where
prevMap = mkMap $ pred n
thisMap = foldr (\sq -> M.insert sq $ mkSet sq) M.empty $ subsequences n
mkSet = S.fromList . mapMaybe eval . exprsFrom prevMap
exprsFrom :: M.Map [Val] (S.Set Val) -> [Val] -> [Expr]
exprsFrom prevMap [x] = [ E1 f (V x) | f <- functions ]
exprsFrom prevMap xs = [ E1 f $ E2 o (V va, V vb)
| f <- functions
, o <- operations
, (as, bs) <- mkPartitions xs
, va <- valsFrom as
, vb <- valsFrom bs
]
where valsFrom xs = S.toList $ M.findWithDefault S.empty xs prevMap
subsequences n = filter ((== n) . length) $ map (take n) $ tails range

So, with caching, here’s what each valuesFrom function call ends up looking like:

Putting it all together

We’re so close to the end here.

We can get a set of all possible numbers from a range xs with valuesFrom xs. This returns a set we can filter for just positive integers; then we want to turn that into a list and find its first gap; where

haskell


-- > firstGap [1,2,3,5,6] = 4
firstGap :: (Num a, Eq a) => [a] -> a
firstGap ls = 1 + ls !! (head . findIndices (/=1) . gaps) ls
where gaps :: Num t => [t] -> [t]
gaps [x] = []
gaps (x:xs) = (head xs - x) : gaps xs

Finally, we can define

haskell


lnpi :: [Val] -> Integer
lnpi = numerator . firstGap
. S.toList . S.filter (>0)
. S.filter isInt. valuesFrom

So, let’s try it!

haskell


> lnpi [1..5] 159

and that’s our final answer; 159 is the smallest integer we can’t construct from the numbers $[1..5]$.

For the complete code, please see this gist.

Runtime

Finally, the runtime…

bash


j@mes $ ghc -O2 lnpi.hs && time ./lnpi
[1 of 1] Compiling Main ( lnpi.hs, lnpi.o )
Linking lnpi ...
159
real 0m0.332s
user 0m0.327s
sys 0m0.003s

This is phenomenal. Early drafts of this took anywhere from one to ten minutes. The secret to this low runtime is evaluating the values early for re-use in other expressions, and nubbing down lists to sets as early as possible, for fewer iterations.

The Puzzles

So Josh actually posed me a set of puzzles. Once we discussed how the performance was and how easy it was to play around with different ideas in this space, we settled on a set of bonus problems; provided here are their questions, answers, runtimes, and some comments on performance.

Puzzle One

Find the least nonconstructable integer from the ordered list [1,2,3,4,5]:

This was the original problem. The solution 01.hs was trivial:

bash


$ ghc -O2 operationsLibrary.hs 01.hs && time ./01
159
0m0.333s

Puzzle Two

Find the least nonconstructable integer from any length five, strictly increasing sublist of [0..9]:

haskell


main = print $ first (map numerator)
$ minimumBy (compare `on` snd) $ map (id &&& lnpi) $ sets [0..9] 5

bash


$ ghc -O2 operationsLibrary.hs 02.hs && time ./02
([0,2,6,8,9],2)
0m39.127s

So I actually played a lot with trying to parallelize this one. A first attempt to compute one large cached map of all sublists of [0..9] took a very large amount of time, and was too large to fit entirely in memory; the process of swapping bits of it in and out was expensive. It turned out to be faster to compute lnpi([]) from scratch each time, at anywhere from 0.03s to 3s each, depending on how many possible products were exponentially large and could be dropped immediately.

I did play with the Control.Parallel library for a bit, and ended up using pseq and par to parallelize this independent computation of lnpi([]) across four cores, for a slightly better runtime:

haskell


main = print
$ first (map numerator)
$ a `par` b `par` c `par` d `pseq` reduceFunc [a,b,c,d]
where [a,b,c,d] = map (reduceFunc . map mapFunc)
$ segmentInto (sets [0..9] 5) 4
reduceFunc = minimumBy (compare `on` snd)
mapFunc = id &&& lnpi
segmentInto xs n = map (\x -> take y $ drop (y*x) xs) [0..pred n]
where y = succ $ div (length xs) n

bash


$ ghc -j -O2 -threaded -rtsopts operationsLibrary.hs 02b.hs --make -fforce-recomp && time ./02b +RTS -N4
([0,2,6,8,9],2)
0m23.407s

Puzzle Three (a,b)

What lists can’t make one?

Here we end up using valuesFrom directly; we don’t care about the lnpi at all. We can use map (f &&& g) which takes an input x and returns a tuple (f x, g x). We use list function elem to see that 1 isn’t a possible value, and print the (empty) list.

haskell


main = print
$ filter (not.snd)
$ map ( id &&& elem 1 . valuesFrom ) $ sets [0..9] 5

bash


$ ghc -O2 operationsLibrary.hs 03.hs && time ./03
[]
0m36.4s

This performance was a little lacking, but we can reoptimize by fetching the list of expressionsFrom and evaluating one-by-one to see if they are Just (1%1); we skip the process of mapping ids and the cost of holding all the values in memory instead of printing an empty list lazily.

haskell


main = print
$ map (map numerator)
$ filter (isNothing . find1)
$ sets [0..9] 5
where find1 xs = if null ls then Nothing else Just (head ls)
where ls = filter (\e -> eval e == Just (1%1)) $ expressionsFrom xs

bash


$ ghc -O2 operationsLibrary.hs 03b.hs && time ./03b
[]
0m7.087s

What’s `expressionsFrom`?

It’s a lot like valuesFrom, except we don’t evaluate the expressions at every possible step. To write both valuesFrom and expressionsFrom I was able to extract a lot of shared abstractions. Here is the code for them both, all in one place. This looks different from the form of valuesFrom above, but it has the same performance and interface.

haskell


makeMap :: Ord a => [a] -> ((M.Map [a] b, [a]) -> b) -> M.Map [a] b
makeMap range insertFn = mkMap (length range)
where mkMap 0 = M.empty
mkMap n = M.union prev this
where prev = mkMap (n-1)
this = foldr f z ls
where f sq = M.insert sq $ insertFn (prev, sq)
z = M.empty
ls = filter ((==n).length) $ map (take n) $ tails range
valuesFrom :: [Val] -> [Val]
valuesFrom range = S.toList $ M.findWithDefault S.empty range $ makeMap range insFn
where insFn = S.fromList . mapMaybe eval . exprsFrom
exprsFrom :: (M.Map [Val] (S.Set Val), [Val]) -> [Expr]
exprsFrom (prevMap, [x] ) = [ E1 f (V x) | f <- functions ]
exprsFrom (prevMap, range) = [ E1 f $ E2 o (V va, V vb)
| f <- functions
, o <- operations
, (as, bs) <- mkPart range
, va <- valsFrom as
, vb <- valsFrom bs
]
where valsFrom range = S.toList $ M.findWithDefault S.empty range prevMap
expressionsFrom :: [Val] -> [Expr]
expressionsFrom range = M.findWithDefault [] range $ makeMap range exprsFrom
where exprsFrom :: (M.Map [Val] [Expr], [Val]) -> [Expr]
exprsFrom (prevMap, [x] ) = [ E1 f (V x) | f <- functions ]
exprsFrom (prevMap, range) = [ E1 f $ E2 o (ea, eb)
| f <- functions
, o <- operations
, (as, bs) <- mkPart range
, ea <- exprsFrom (prevMap, as)
, eb <- exprsFrom (prevMap, bs)
]

Puzzle Three (c)

Print how each list can make one.

By using expressionsFrom we can find the first expression that evaluates to $1$, and avoid evaluating the entire possible tree.

haskell


main = mapM_ print $ map (map numerator &&& find1) $ sets [0..9] 5
where find1 xs = if null ls then Nothing else Just (head ls)
where ls = filter (\e -> eval e == Just (1%1)) $ expressionsFrom xs

bash


$ ghc -O2 operationsLibrary.hs 03c.hs && time ./03c
([0,1,2,3,4],Just (0+(1+((2-3!)+4))))
([0,1,2,3,5],Just (0+(1+(2+(3-5)))))
([0,1,2,4,5],Just (0+((1*2)+(4-5))))
([0,1,3,4,5],Just (0+(((1+3)!/4)-5)))
([0,2,3,4,5],Just (0+(2+((3-4)^5))))
([1,2,3,4,5],Just (1+((2-(3+4))+5)))
([0,1,2,3,6],Just (0+(1+((2*3)-6))))
([0,1,2,4,6],Just (0+(1+(2+(4-6)))))
([0,1,3,4,6],Just (0+((1*3)+(4-6))))
([0,2,3,4,6],Just (0+(2+(3-(4!/6)))))
...
0m7.085s

Return Volley

Josh, here is my puzzle:

I saw a Sol Lewitt exhibition at a museum a few years ago which consisted of a series of variations of incomplete cubes. There were 122 of them, and each was a contiguous subset of lines which traced the twelve edges of the skeleton of a cube. The trick was that these subsets were unique across rotation but not reflection.

Create a script / renderer to generate the table of Varations of Incomplete Open Cubes, and then apply it to the skeleton of each platonic solid.

Some light reading: Analysis of Variations of Incomplete Open Cubes by Sol Lewitt, a paper by Michael Allan Reb (2011).

Puzzle Pong I - Generating All Possible 4x4 Crosswords

Sat, 27 May 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/ac4ed787e1b9bb3eba08bb02c9b25c49

The Puzzle

Josh Mermelstein and I have decided to begin challenging each other to a series of a math/programming puzzles. He asked me to generate all possible valid English-language four-by-four crossword grids; that is, a grid of sixteen letters where every row and column is a real English word. One caveat was that no grid could have the same word twice.

An example grid:

bash


ACTS --> (across) acts, lore, idea, teem
LORE ( down ) alit, code, tree, seam
IDEA
TEEM

The Difficulty

It’s easy to think of a two really bad ways to solve this problem:

You could try all $26^{16} = 4.36\times10^{22}$ grids and filter by validating their component words, or
you could find real four-letter english words (there are a little over 2000 of them, so $ 2354 \text{ choose } 8 = 2.31\times10^{22}$ possible grids ) and try and fit them, eight at a time, on a grid.

The Solution

The best way I found was to:

precompute a dictionary (called paths here) with
- keys like "a", "ab", "abc", and
- values corresponding to the lists of letters which, if put after their keys, would lead to real four-letter words.
- (For example, paths["wok"] = ['e','s'], or (perhaps less obviously), paths["z"] = [('a','e','i','o'].)
lay out all possible starting grids, where
- the top row and leftmost column were filled out
- with two real four-letter words
- whose first letters were the same
for each grid (node, really),
- find the next blank,
  - find the partial word above it,
  - find the partial word to the left of it,
  - look them both up in paths,
  - take the intersection of the resultant lists
  - for each character in this intersection,
    - create a list of child nodes with the blank square filled in.

In this way, we guarantee that any placement will always lead to a real word in that row and column.

Annotated Code

I’ll present the code annotated below, or in its entirety in the attached gist.

haskell


import qualified Control.Monad as N (forM)
import qualified Data.Maybe as B (isJust, isNothing, catMaybes)
import qualified Data.Char as C (isAsciiLower)
import qualified Data.Function as F (on)
import qualified Data.List as L (all, nub, groupBy, intercalate)
import qualified Data.List.Split as L (chunksOf)
import qualified Data.Map.Strict as M (Map, insert, empty, unions, findWithDefault)
import qualified Language.Words as W (allStringWords)
-- A box can either have a single character or nothing. Using the Maybe monad
-- here turned out to be a really useful decision, with functions like isJust
-- and catMaybes doing the heavy lifting for the most part.
type Box = Maybe Char
-- A grid is just a list of boxes. This was originally implemented as a
-- `Data.Matrix Maybe Char`, but it turned out to be very slow compared to a
-- stupid list. That said, I ended up having to rewrite the getters and setters,
-- as seen below.
type Grid = [Box]
-- One issue I ran into a lot was confusing row and col indices. Defining a
-- custom datatype akin to Either helped solve this -- it's a lot harder to pass
-- a Row index as a Column if the compiler catches it ;)
data Idx a = Row a | Col a deriving (Eq, Ord, Show)
-- This is the precomputed dictionary discussed above -- it maps Strings (like
-- "a" or "abc") to list of chars (printed as `['a', 'e', 'i'...]`)
type Paths = M.Map String [Char]
-- This is the width of the grid. Can be changed, but it would be a hassle to
-- extricate into a command-line argument or even a main-block variable.
n = 4
-- Here begins the set of getters and setters I mentioned above. You can see
-- that while gridSet takes an element to insert, a tuple of the row and column
-- at which to insert it, the original grid, and returns the resultant grid. The
-- _type_ of `Row r` and/or `Col c` are `Idx Int`, since they are of type `Idx`,
-- which is just a wrappeer for the `Int` index itself. By naming their types on
-- the left-hand side of the definition, we can use `r` and `c` in the
-- computation without unwrapping.
gridSet :: Num a => Char -> (Idx Int, Idx Int) -> Grid -> Grid
gridSet el (Row r, Col c) g = take i g ++ [Just el] ++ drop (i+1) g
where i = (r-1)*n + (c-1)
-- Another trick with `Idx` -- we can pattern-match on the type, returning one
-- computation for the nth row of a grid, and another for the mth column.
-- This uses Data.List.chunksOf, which I', a big fan of.
gridGet :: Grid -> Idx Int -> [Box]
gridGet g (Col x) = map head $ L.chunksOf n $ drop (x-1) g
gridGet g (Row x) = take n $ drop (n*(x-1)) g
-- This is a pretty-printer for a grid -- it unwraps a list of [Maybe Char]s,
-- replacing Nothings with _; then it segments that into chunks of 4 and
-- recombines them with "\n".
gridPrint :: Grid -> String
gridPrint xs = L.intercalate "\n" $ L.chunksOf n $ unwrap xs
where unwrap [] = ""
unwrap (Just x : xs) = x : unwrap xs
unwrap (Nothing: xs) = '_' : unwrap xs
-- This is a foldr implementing `gridSet` across a list of elements and a list
-- of (Row, Col) pairs. By zipping the chars and locs and `uncurry`ing them, we
-- avoid having to write something like
-- gridWrite [] _ g = g
-- gridWrite (c:cs) (l:ls) g = gridSet c l $ gridWrite cs ls g
gridWrite :: String -> [(Idx Int, Idx Int)] -> Grid -> Grid
gridWrite cs ls g = foldr (uncurry gridSet) g $ zip cs ls
-- All the words we care about. There are 98k words in
-- Language.Words.allStringWords, probably taken from usr/share/dict/words. Of
-- those, 64 are lowercase ascii, and 2.3k are four lettersr long.
allWords :: [String]
allWords = filter (\x -> length x == n)
$ filter (L.all C.isAsciiLower) W.allStringWords
-- Here's where the magic happens. dictMake i creates a Paths, where:
-- type Paths = Map String [Char]
-- but only where the keys are of length `i`. We call it a few types and
-- `M.unions` them together later on to commbine them into one Map in memory.
dictMake :: Int -> Paths
dictMake len = foldr (\xs -> M.insert (key xs) (val xs)) M.empty nglyphs
where key = take len . head
val = S.fromList . map (head . drop len)
nglyphs = L.groupBy ((==) `F.on` take len) $ map (take $ len+1) allWords
-- Working backwards, assuming len = 2 for this example:
-- allWords ~ ["abed", "abet", "able", "ably", "abut"...]
-- map (take $ len+1) allWords ~ ["abe", "abe", "abl", "abl", "abu"...]
-- L.groupBy ((==) `F.on` take len) $ map (take $ len+1) allWords
-- ~ [["abe", "abl"..], ["ace", "ace", "ach"]..]
-- from this list, we can map `key`, which gets just the first `len` letters
-- from the first item in each list, and
-- `val`, which gets the list of remaining letters.
-- ~ Map ["ab"] -> ['e','l'..]
-- ["ac"] -> ['e','h'..]
-- Then we fold this `(\xs -> M.insert (key xs) (val xs))`
-- over `nglyphs`, with
-- base `M.empty`.
-- If the data being intersected is complex and needs to be sorted and nubbed,
-- treating the items as Sets is often efficient. That's why the following
-- function, `children`, used to do a Set intersection, and `paths` used to
-- contain values of `S.Set Char`.
--
-- But it turns out that the values in `Paths` comes pre-sorted and pre-nubbed
-- by virtue of its origins in `W.allStringWords`. So we don't want the overhead
-- of creating, comparing, and toList-ing `Data.Set`s. We don't even want the
-- overhead of `Data.List.intersection`, which sorts the arrays before taking
-- their intersection. For that reason, we implement `intersect` ourselves,
-- below.
intersect :: [Char] -> [Char] -> [Char]
intersect [] _ = []
intersect _ [] = []
intersect (a:as) (b:bs)
| a == b = a : intersect as bs
| a < b = intersect as (b:bs)
| a > b = intersect (a:as) bs
-- `children` accepts a `paths` dictionary to hold inline, which end up being
-- fairly efficient -- I believe the compiler notices it is unchanged between
-- calls of `children` and makes it something like a global.
--
-- Anyway, `children` accepts a `paths` dictionary and a grid and returns the
-- possible child grids, as decribed above. This is just a list comprehension
-- where the location of the next blank is described by `(r,c)`, which zips the
-- grid with the locations of its squares and drops filled squares until we get
-- the location of the first blank.
--
-- Additionally, we find the `poss`ible next letters by taking the intersection
-- of the two `setValid` valid lists along the `c` column and `r` row indices,
-- where `setValid` utilized `Data.Maybe.catMaybes` to strip the `Nothing`s from
-- a list of `[Maybe Char]`s, and uses a macro'd `Data.Map.findWithDefault`
-- titled `nextIn`. to find it in the `paths` map.
children :: Paths -> Grid -> [Grid]
children p g = [ gridSet l (r,c) g | l <- poss g ]
where (r,c) = snd $ head $ filter (B.isNothing . fst) $ zip g indices
indices = [ (Row i, Col j) | i<-[1..n], j<-[1..n] ]
nextIn s = M.findWithDefault [] s p
poss g = intersect (setValid c) (setValid r)
where setValid = nextIn . B.catMaybes . gridGet g
-- We want to start with grids with filled top rows and leftmost columns. We use
-- `gridWrite` from before to write full words along lists of locations,
-- described by `firstRow` and `firstColumn`. We write these into a `blank` grid
-- of sixteen `Nothing`s. This, too, is a list comprehension, which is
-- convenient for applying the restrictions which make our grids unique.
--
-- Specifically, we want the top and left words to be different, have the same
-- first letter, and not appear again in the opposite configuration later on.
-- Luckily, we can compare `wa < wb` to make sure this holds.
seeds :: [Grid]
seeds = [ gridWrite wa firstRow $ gridWrite wb firstCol blank
| wa <- allWords , wb <- allWords , wa < wb, wa /= wb, head wa == head wb
]
where firstRow = [ (Row 1, Col x) | x <- [1..n] ]
firstCol = [ (Row x, Col 1) | x <- [1..n] ]
blank = replicate (n^2) Nothing
-- As usual, we utilize the `until cond fn seed` pattern to apply `fn` to `seed`
-- over and over ([x, f(x), f(f(x))..]) until one of the elements fulfills
-- `cond`. In this case, we define `paths` right here, inline, as the union of
-- the `dictMake` dicts for a range of integers from 1 til one less the side
-- length.
--
-- Additionally, we `filter` our answer to make sure none of the grids have
-- repeating words. Eliminating these grids with duplicate words at the very end
-- is more efficient than whittling down the `paths` dictionary recursively. We
-- build `noRepeats` with `wordsIn`, which gets each row and column with
-- `gridGet`, builds a list, nubs it, and inspects its length.
grids = filter noRepeats
$ until (B.isJust . last . head) (concatMap $ children paths) seeds
where paths = M.unions $ map dictMake [1..(n-1)]
noRepeats g = 2*n == length (wordsIn g)
wordsIn g = L.nub
$ map (gridGet g)
$ concatMap (\x -> [Row x, Col x])
[1..n]
-- And that's it! Initially, we just want to print the number of grids, but
-- we may do more interesting things with `grids` later.
main = print $ length $ grids

With comments, this is ~160 lines; without, this is ~70.

Final Answer

OK, what you came for. There are $686739$ distinct four-by-four crossword grids in English with no repeats and no diagonal symmetry. The script runs in just over a minute and uses far short of 100% of my memory (unlike several intermediate versions).

Runtime

Run normally, this script is fairly fast:

bash


j@mes $ ghc -O2 words.hs
[1 of 1] Compiling Main ( words.hs, words.o )
Linking words ...
j@mes $ time ./words
686739
real 1m1.138s
user 1m0.810s
sys 0m0.303s

But it was not always so. During development I made extensive use of the built-in GHC profiler:

bash


j@mes $ ghc -prof -fprof-auto -rtsopts -O2 words.hs
[1 of 1] Compiling Main ( words.hs, words.o )
Linking words ...
j@mes $ time ./words +RTS -p
686739
real 2m8.759s
user 2m8.277s
sys 0m0.470s

This writes out to words.prof and looks something like: (see the full words.prof profiler output on Gist.)

bash


Sun May 28 00:13 2017 Time and Allocation Profiling Report (Final)
words +RTS -p -RTS
total time = 107.52 secs (107523 ticks @ 1000 us, 1 processor)
total alloc = 134,700,416,432 bytes (excludes profiling overheads)
COST CENTRE MODULE %time %alloc
children.nextIn Main 20.8 0.0
children.(...) Main 13.1 14.1
gridGet Main 11.0 16.8
children Main 10.0 6.1
gridSet Main 9.4 20.8
build Data.List.Split.Internals 7.7 9.9
chunksOf Data.List.Split.Internals 7.1 18.8
grids Main 5.7 2.6
children.poss.setValid Main 5.5 6.3
intersect Main 5.3 1.8
grids.wordsIn Main 1.9 1.2
children.poss Main 1.4 1.4

Which gives a bit of a hint where things might be taking up a lot of time. In this case, nextIn is taking up 20% of our time, and it’s an $O(\log n)$ pre-optimized Map lookup function. Might be time to stop optimizing, with a near-one-minute runtime.

More Fun with our Solver

What else can we do with our program now that we have a pretty speedy crossword solver? Well, because Haskell is lazy it’s not that hard to see if there exists a 5x5 or 6x6 grid. By doing main = putStrLn $ gridPrint $ head grids we end up executing incredibly fast:

Here are some grids I found:

0.062s 0.164s 54.0s
ABED ABACI ABBESS
BLUR BOWED SEESAW
EERY AXIAL CATTLE
TWOS SENSE ERRATA
EDGED NEATER
DRYERS

Palindromes

Additionally, we can find “palindromic” crosswords, where the words are valid even if the grid is rotated 90, 180, or 270 degrees:

In 6.627s it finds the following palindromic 4x4:

DRAB WARD DRAW BARD
RAGA AJAR RAJA AGAR
AJAR RAGA AGAR RAJA
WARD DRAB BARD DRAW

There are 10 such palindromic 4x4s; eight of them rely on the quartet raga/raja/ajar/agar at their centers; the other two rely on time/tide/emit/edit.

DRAB DRAB DRAB DRAB DRAW DRAW TRAM TRAM STEP STEP
RAGA RAJA RAGA RAJA RAGA RAJA RAGA RAJA TIDE TIME
AJAR AGAR AJAR AGAR AJAR AGAR AJAR AGAR EMIT EDIT
WARD WARD YARD YARD YARD YARD PART PART WETS WETS

Word Frequency

By running

haskell


main = Control.Monad.forM grids
$ \g -> appendFile "grids.txt" $ gridPrint g ++ "\n"

We can write a list of all grids to a file grids.txt and perform some rudimentary Bash-level analysis on what sorts of words appear in the rows most commonly:

bash


j@mes $ cat grids.txt | sort | uniq -c | sort -h | tail
14642 west
15424 oboe
15516 oral
16678 pest
17451 test
19541 psst
22165 aria
26541 oleo
28531 area
85689 urea

These don’t quite look like the letter distributions we’re used to in full-fledged English – let’s look at letter frequencies and see how different it is for four-letter words, and which letters are more likely to appear in crosswords.

bash


j@mes $ awk -vFS="" '{for(i=1;i<=NF;i++)w[$i]++}END{for(i in w) print w[i],i}' grids.txt | sort -hr
1673174 e
1428194 a
1307329 s
781441 t
722476 o
709668 l
693442 r
450942 p
448701 n
424290 i
324295 d
296590 m
246367 w
236242 c
221680 u
204857 h
199943 b
185596 g
114375 k
106834 v
104330 y
80840 f
17625 x
4530 j
4030 z
33 q

Looks like q only appears 33 times; only ever in the context of quay, aqua, quip, quad, quit, or quid.

Conclusion

I have challenged Josh Mermelstein to solve the following puzzle:

For a set of n letters ('a','b','d') you can make m real English words ("bad", "dab", etc...). Find the subset of all 26 letters with the highest ratio of words to letters; in other words, the most bang for your buck.

Solving One Tough Puzzle

Sat, 29 Apr 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/b8ce48c034a1843d7ab1def052654d15

This is a puzzle from 538’s Puzzler. The puzzle is as follows:

You play a game with four balls: One ball is red, one is blue, one is green and one is yellow. They are placed in a box. You draw a ball out of the box at random and note its color. Without replacing the first ball, you draw a second ball and then paint it to match the color of the first. Replace both balls, and repeat the process. The game ends when all four balls have become the same color. What is the expected number of turns to finish the game?

The Solution

We can simplify this problem down from (all possible combinations of colors) to (all possible combinations of the number of balls of each color).

The initial state (red, yellow, green, blue) can be written as (1,1,1,1); the final state (with all balls of the same color) can be written as (4).

It turns out there are only five possible states: [(1,1,1,1),(2,1,1),(3,1),(2,2),(4)].

So the most important thing will be figuring out how often state i goes to state j. Once we get a complete list of those states and probabilities, it turns out we can draw a Markov chain, turn its edges into cells in a stochastic matrix, and then find the expected number of turns to finish. The expected number of turns to finish is also known as the expected hitting time. We will get into all that a bit later.

The Code

Writing `pDist`

First, we want to write a function which can take a state and figure out which other states it can go to and how likely it is to do that. Our function pDist does that. Since the states will soon be nodes in a graph, we refer to them as node inline.

haskell


import Control.Arrow (second, (&&&))
import Data.Either (rights)
import Data.List (sort, group, permutations, delete)
import Data.Map.Strict as Map (Map, empty, fromList, keys, elems, insert,
findWithDefault)
import Data.Matrix as Matrix (Matrix, fromList, multStd, inverse, identity,
submatrix, nrows)
import Data.Ratio (Ratio, (%))
import Data.Set as Set (Set, toList, difference, fromList)
import Prelude as P
import System.Environment (getArgs)

Here’s our spec: pDist i will return a map where the keys are the nodes j it is possible to reach from i, and the values are the probability of reaching j from i.

First we turn the node ([1,1,1,1]) into an actual list of different “colors”. We call this toUniqueRepresentation. It takes a node like [1,1,1,1] and returns a list like [1,2,3,4].

Then we call a custom allPairings on that unique representation. This is a reduced form of Data.List.permutations which generates all possible pairings we actually care about. For example, [1,2,3,4] and [1,2,4,3] are different and might both be generated by permutations, but in practice we really only care about the order of the first two and the contents (but not order) of the rest of the list. This is done with delete, which searches through a list in $O(n)$ time to delete the first instance of a passed argument. This returns a list of potential boxes.

Then we perform the paint operation on each potential box. This involves taking two balls, painting them both the color of the first, and returning them to the box.

This paint function is done inside a larger decorate decorator, which paints, sorts, groups, replaces each group with its length, and sorts those numbers. This is computationally the bottleneck of the solution, but it is the bit of logic which attempts to resolve [A,B,B,C] and [A,A,B,C] to the same underlying distribution [2,1,1].

After decorateing each potential box, we probably end up with a long list of resultant states with a lot of repetition. We don’t want the whole list of resultant states; we want a histogram! We run it thru freqMap, which does something like:

freqMap [1,1,2] -> [(1, 2%3), (2, 1%3)], where the keys of the resultant map are the possible end states, and the values are the probabilities (as fractions).

haskell


pDist :: [Int] -> Map [Int] (Ratio Int)
pDist = freqMap . P.map decorate . allPairings . toUniqueRepresentation
where toUniqueRepresentation :: [Int] -> [Int]
toUniqueRepresentation node = concat $ zipWith replicate node [1..]
allPairings :: [Int] -> [[Int]]
allPairings ns = [ x : y : delete y (delete x ns)
| x <- ns, y <- delete x ns
]
decorate :: [Int] -> [Int]
decorate = sort . P.map length . group . sort . paint
paint :: [Int] -> [Int]
paint (x:y:xs) = x:x:xs
freqMap :: [[Int]] -> Map [Int] (Ratio Int)
freqMap xs = Map.fromList
$ P.map ( second (% length xs) . (head &&& length) )
$ group $ sort xs

Phew. Now that we have a function like pDist, let’s see how it behaves. Inside ghci:

haskell


*Main> pDist [1,1,1,1]
fromList [([1,1,2],1 % 1)]
*Main> pDist [1,1,2]
fromList [([1,1,2],1 % 2),([1,3],1 % 3),([2,2],1 % 6)]

Very nice. It looks like [1,1,1,1] always goes to [1,1,2], with a ratio of 1%1 or 100%. It also looks like there are lots of places [1,1,2] could go; it loops back in on itself half the time.

Writing `makeArrows`

Eventually we want to get a list of all reachable states in the puzzle, and turn those states into a set of nodes. Once we have the nodes, we can create a graph with arrows from node to node, and think about our puzzle like that. This is shaping up to be a Markov chain, so we might as well embrace it and prepare for the stochastic matrix which is to come.

Our function makeArrows is another classic haskell until condition function seed, which applies function to seed over and over until some condition is met. We will use this to build a 2D Map, where the keys are states and the values are also maps from states to probabilities. Think about it like this:

haskell


Map key = state i
value = Map (key = state j )
(value = prob. of transition i -> j)

We don’t know any of this at the beginining, so we seed our function with the initial state [1,1,1,1] and let it build itself lazily. The initial 2D map is just Map.insert seed (pDist seed) Map.empty, which inserts: map[seed] = (pDist seed) into an empty map.

How do we know we’re done making this 2D map? There are lots of states in this space which are not reachable; we only care about states which either have arrows coming from or going to them. We’ll be done when every node which is the endpoint of an arrow is also the beginning of an arrow. Said another way, we’ll be done when every node j in the list of state js is also in the list of state is.

We’ll write some helper functions, is and js, which return the set of all states with arrows leaving and entering them, respectively. diff does a set difference, so we’re finished when that diff is null!

If we’re not finished, we want to take a step forwards in finishing this 2D map. We find the diff, take the first node, and perform Map.insert node (pDist node) on the old arrows 2D map.

haskell


makeArrows :: [Int] -> Map [Int] (Map [Int] (Ratio Int))
makeArrows seed = until finished step $ Map.insert seed (pDist seed) Map.empty
where finished :: Map [Int] (Map [Int] (Ratio Int)) -> Bool
finished = P.null . diff
step :: Map [Int] (Map [Int] (Ratio Int)) -> Map [Int] (Map [Int] (Ratio Int))
step arrows = Map.insert node (pDist node) arrows
where node :: [Int]
node = head $ Set.toList $ diff arrows
diff :: Map [Int] (Map [Int] (Ratio Int)) -> Set [Int]
diff arrows = Set.difference (js arrows) (is arrows)
is :: Map [Int] (Map [Int] (Ratio Int)) -> Set [Int]
is = Set.fromList . Map.keys
js :: Map [Int] (Map [Int] (Ratio Int)) -> Set [Int]
js = Set.fromList . concatMap Map.keys . Map.elems

Trying it, we find:

haskell


*Main> makeArrows [1,1,1,1]
fromList [([1,1,1,1],fromList [([1,1,2],1 % 1)]),([1,1,2],fromList [([1,1,2],1 % 2),([1,3],1 % 3),([2,2],1 % 6)]),([1,3],fromList [([1,3],1 % 2),([2,2],1 % 4),([4],1 % 4)]),([2,2],fromList [([1,3],2 % 3),([2,2],1 % 3)]),([4],fromList [([4],1 % 1)])]

I’ll clean this up for you.

haskell


*Main> makeArrows [1,1,1,1]
fromList [ ([1,1,1,1],fromList [([1,1,2],1 % 1)])
, ([1,1,2], fromList [([1,1,2],1 % 2)
,([1,3], 1 % 3)
,([2,2], 1 % 6)])
, ([1,3], fromList [([1,3], 1 % 2)
,([2,2], 1 % 4)
,([4], 1 % 4)])
, ([2,2], fromList [([1,3], 2 % 3)
,([2,2], 1 % 3)])
, ([4], fromList [([4], 1 % 1)])
]

This is great! We can look up a key for state i, look up another key for state j, and find a probability P_{i,j}. If it doesn’t exist, we know you can’t reach j from i. But we don’t need a 2D map, we need a matrix to do matrix arithmetic on.

Writing `makeMatrix`

Data.Matrix has a utility fromList to take a list and turn it into an n by m matrix; we can simply turn makeArrows _ into a list with 0s in the appropriate places.

If we get a list of all possible nodes, we can do a list comprehension like [probability (or zero) from i to j | i <- nodes, j <- nodes]. We use nodes = Map.keys arrows to represent all the states we care about, and use a doubly-nested Map.findWithDefault to perform a lookup with two defaults.

If i isn’t in the map, we return an empty map to perform our second lookup on; if j isn’t in that second map, we return the zero ratio (0%1). This looks like [ Map.findWithDefault (0%1) j $ Map.findWithDefault Map.empty i arrows | i <- nodes, j <- nodes ].

Writing this with nodes and some dimension n defined inline, we get:

haskell


makeMatrix :: Map [Int] (Map [Int] (Ratio Int)) -> Matrix (Ratio Int)
makeMatrix arrows = Matrix.fromList n n list
where list :: [Ratio Int]
list = [ Map.findWithDefault (0%1) j $ Map.findWithDefault Map.empty i arrows
| i <- nodes, j <- nodes
]
n :: Int
n = length nodes
nodes :: [[Int]]
nodes = Map.keys arrows

Let’s try it:

haskell


*Main> makeMatrix $ makeArrows [1,1,1,1]
( 0 % 1 1 % 1 0 % 1 0 % 1 0 % 1 )
( 0 % 1 1 % 2 1 % 3 1 % 6 0 % 1 )
( 0 % 1 0 % 1 1 % 2 1 % 4 1 % 4 )
( 0 % 1 0 % 1 2 % 3 1 % 3 0 % 1 )
( 0 % 1 0 % 1 0 % 1 0 % 1 1 % 1 )

This looks exactly right to me. Just for fun, let’s use dot/graphviz to draw this chain with its proper nodes and edges, for comparison to the stochastic matrix which represents it.

Writing `expectedValue`

The final step will be to tease an average lifetime from this matrix. Our problem is actually asking for the expected hitting time of the Markov chain. This is the part which actually requires some math.

If we write our stochastic matrix $\textbf{P}$, we can remove the bottom row and rightmost column to remove the influence of our end state on the average lifetime. We write this reduced matrix as $\textbf{T}$, a submatrix 1 n 1 n p.

$$ \textbf{P} = \begin{bmatrix} 0 & 1 & 0 & 0 & 0\\0 & \frac{1}{2} & \frac{1}{3} & \frac{1}{6} & 0\\0 & 0 & \frac{1}{2} & \frac{1}{4} & \frac{1}{4}\\0 & 0 & \frac{2}{3} & \frac{1}{3} & 0\\0 & 0 & 0 & 0 & 1 \end{bmatrix} $$

$$ \textbf{T} = \begin{bmatrix} 0 & 1 & 0 & 0\\0 & \frac{1}{2} & \frac{1}{3} & \frac{1}{6}\\0 & 0 & \frac{1}{2} & \frac{1}{4}\\0 & 0 & \frac{2}{3} & \frac{1}{3} \end{bmatrix} $$

Here I begin quoting the Wikipedia Stochastic matrix page

$E[k] = \tau(I + \textbf{T} + \textbf{T}^2 + …)\textbf{1}$
$\phantom{E[k]} = \tau(I-\textbf{T})^{-1}\textbf{1}$ is the expected hitting time of the final state, where
$\textbf{T}$ is the truncated matrix above,
$\tau = \begin{bmatrix} 1 & 0 & 0 & 0 \end{bmatrix}$ is an array as long as the number of relevant states $n = 4$ with the initial state marked (in this case, state 1),
$I$ is a 4x4 identity matrix, and
$\textbf{1} = \begin{bmatrix} 1 & 1 & 1 & 1 \end{bmatrix}^{T}$ is a column vector of ones, as high as the number of relevant states $n$.

Luckily Haskell has some nice Matrix handling faculties.

haskell


expectedValue :: Matrix (Ratio Int) -> Matrix (Ratio Int)
expectedValue p = P.foldr1 multStd [tau, inv, one]
where tau = Matrix.fromList 1 n (1:[0,0..]) -- [1,0,0..]
one = Matrix.fromList n 1 [1,1..] -- [[1],[1],...]
inv = head $ rights $ (:[])
$ inverse (identity n - t) -- (I - T)^(-1)
t = submatrix 1 n 1 n p -- P, but w/o last row / last col
n = nrows p - 1

Tying it all together

We wrap this in a main function which allows a seed to be passed in as a CLI argument, and finally call (exectedValue . makeMatrix . makeArrows) seed.

haskell


main = do
args <- getArgs
let seed = read (head args) :: [Int]
print $ expectedValue $ makeMatrix $ makeArrows seed

That’s all! If we call ghc to compile it first, it takes 0.006s.

bash


j@mes ~/dev/math-problems/four-color-balls $ ghc colorful.lhs -O2
j@mes ~/dev/math-problems/four-color-balls $ ./colorful [1,1,1,1]
( 9 % 1 )

Thus, the expected number of turns until the game is over is $9$.

You can see the complete (unannotated) haskell code on gist.

Writing an Aaronson Oracle

Sun, 23 Apr 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/01187518b73c21029e8ef427cc9137be

The Aaronson Oracle is a game where you type f and d at random and the Oracle tries to guess which you’re gonna type next. It looks at your input history and tries to find patterns.

haskell


import Data.Map as M
import Data.Maybe
import Numeric

We use a Map [Bool] Double structure (called a brain here for no good reason) to store sequences and how often they occur. Instead of storing f and d, we store Booleans True and False (True = "f").

We improve the brain with learn, which takes the history of sequences and uses it to increment subsequence occurrence counts. We store sequences between three and five characters long, and simultaneously create and/or update them with:

Map.insertwithKey f key newValue, where
f key oldValue newValue = oldValue + newValue, which can be written
f _ = (+) or
f = const (+)

We fold this learn' operation across the brain a few times and return the new brain.

haskell


learn :: [Bool] -> Map [Bool] Double -> Map [Bool] Double
learn hist brain = Prelude.foldr learn' brain [3..5]
where learn' n = M.insertWithKey (const (+)) (take n hist) 1.0

We want to use the brain to “guess” how likely an f or d will be. This will be a weighted average, where the value is how likely a given lookback period would indicate, and the weight is how many datapoints we have for a given lookback period.

For example, take a brain with key/value pairs:

haskell


[ T T ] -> 2
[ F T ] -> 3
[ T T F ] -> 3
[ F T F ] -> 1

Imagine we’ve just typed F and then T. Looking back only one character (just at the T) would indicate that F will follow 3 out of 5 times, but looking back two characters would indicate that T will follow 3 out of 4 times. We can weight those values by certainty to get a pretty good prediction.

haskell


guess :: Map [Bool] Double -> [Bool] -> Bool
guess brain hist = wAvg (Prelude.map guess' [2..4]) >= 0.5
where wAvg xs = sum (Prelude.map (uncurry (*)) xs) / sum (Prelude.map snd xs)
guess' n = (occ True / (occ True + occ False), occ True + occ False)
where occ val = fromMaybe 0.0 $ M.lookup (val : take n hist) brain

M.lookup key map returns a Maybe val, so we wrap it in a fromMaybe default to ensure some real number gets returned.

Then it’s time to play a turn! Each turn needs to be aware of what turn number it is (turn), how many games were won and held before it (wons, total), the prior history (hist), and the prior brain (brain).

We get the keypress, judge it against the guess brain hist, and print a message to the user.

Then we kick off a new round with an incremented turn number, potential incremented win number, incremented total games number, augmented history, and new and improved brain.

haskell


play :: Int -> (Double, Double) -> [Bool] -> Map [Bool] Double -> IO a
play turn (wons, total) hist brain = do
press <- getLine
let key = press == "f"
let right = key == guess brain hist
let wins = (if right then succ else id) wons
print $ "I guessed " ++ (if right then "RIGHT!" else "wrong.")
++ " My avg: " ++ showFFloat (Just 2) (wins / succ total) ""
play (succ turn) (wins, succ total) (key:hist) (learn (key:hist) brain)

The main block prints instructions and kicks off the game at round zero, with zero wins for zero total games, an empty history array, and an empty brain.

haskell


main = do
print "aaronson oracle | Press 'f' or 'd' over and over (followed by enter)"
print " | and we'll try to predict which you'll press next."
play 0 (0.0, 0.0) [] M.empty

You can see the full code here, in a gist.

Solving One Tough Puzzle

Sun, 22 Jan 2017 00:00:00 -0400

Github	https://gist.github.com/ambuc/ec5d72fcc6d931afa745e3c8ac100edb

The Puzzle

One Tough Puzzle is a physical jigsaw puzzle made up of nine square pieces. Each side of the square as either a tab or a blank in the shape of one of the four card suits. The goal is to put them all together so they fit, like any jigsaw puzzle.

I will use this post as a tour of some cool Haskell features I’ve been enjoying for the past few months doing Project Euler problems.

The Problem

We number the spaces like so:


0	1	2
3	4	5
6	7	8

Nine pieces in nine slots gives us $9! = 362880$ positional combinations, and nine pieces which can be rotated any of four ways gives us $4^9 = 262144$ rotational combinations, for a total of just over $23\times 10^9$ combinations (accounting for rotational symmetry). Too many to brute force.

The Solution

We can instead try to solve the problem a little bit at a time. Our algorithm will be as follows:

For position n:
- generate all possible options for position n
- validate position n with regard to the pieces around it
- repeat for position n+1 until done

This has the advantage of trimming the search space as quickly as possible, to avoid having to validate all twenty-three billion possible grids. We will check in at the end and see how many grids or fractions thereof we actually did have to validate.

Using Haskell

My language of choice for this is Haskell, mostly because I’ve been doing Project Euler problems in it recently and I really like the custom data types and flexibility.

`data`

Haskell has the ability to define custom data types, and compose and define them in interesting ways. In this puzzle we want to be able to inspect and compare tabs and blanks, puzzle pieces, etc.

haskell


data Suit = Club | Heart | Diamond | Spade deriving (Show, Read, Eq)
data Sex = Out | In deriving (Show, Read, Eq)
data Side = Side { suit :: Suit , sex :: Sex} deriving (Show, Read)
data Piece = Piece { north :: Side , east :: Side
, south :: Side , west :: Side } deriving (Show, Read, Eq)

deriving after a custom data type tells Haskell to infer how to print (show), read, or compare variables of that type. Comparisons can be

Eq, which lets us tell whether or not two things are equal.
Ord, which lets us tell whether one thing is bigger than another.

In our case, we don’t really have a way to decide whether one Suit or Sex is “bigger” than another, but we do want to check equality.

We define Side and Piece with named fields, which lets us extract those fields with generated getters:

haskell


λ> let foo = Side {suit=Club, sex=Out}
λ> suit foo
Club

For two puzzle pieces to be able to meet at an edge, they need to have the same Suit and opposite Sex es. This makes it convenient to define a custom instance of Eq for Side variables. This lets us redefine a == b to check whether two sides are compatible, rather than equal.

haskell


instance Eq Side where x == y = (suit x == suit y) && (sex x /= sex y)

Input

I defined the nine pieces in plaintext as follows:

haskell


[ "HDdh", "CHsh", "DCcd", "SDsh", "SDhd", "SShc", "CHdc", "HDcc", "HSsc"]

where each character is the tab or blank on the North, East, South, and West faces of a piece. Each letter stands for Heart, Diamond, Spade, or Club, and is uppercase if the side sticks out rather than in.

We have to write a bit of parsing code to turn this a list of Piece objects.

haskell


parsePiece [n,e,s,w] = Piece { north = parseSide n, east = parseSide e
, south = parseSide s, west = parseSide w }
where parseSide c = Side { suit = parseSuit c, sex = parseSex c }
parseSuit c | toLower c == 'c' = Club
| toLower c == 'd' = Diamond
| toLower c == 's' = Spade
| otherwise = Heart
parseSex c = if isLower c then In else Out

Later, we can call

haskell


let allPieces = map parsePiece $ [ "HDdh", "CHsh", ... ]

`explore`

Theory

At the core of this solution is a function I named explore, which takes a known grid and a list of candidates and generates a list of potential grids and their remaining candidates. We represent a grid as a list of pieces [Piece].

haskell


explore :: ([Piece], [Piece]) -> [([Piece], [Piece])]

Here is an example of explore in action.

haskell


-- known grid
-- | candidates
-- | |
-- v v
λ> explore ([1, 2], [3, 4, 5])
[ ([1, 2, 3], [4, 5]),
([1, 2, 4], [3, 5]),
([1, 2, 5], [3, 4]) ]

One caveat here is that we don’t just append all the items in the candidates pool to the known grid; because these are puzzle pieces, we need to append all possible rotations of each candidate. So a closer approximation with lower- and upper-case letters might be:

haskell


λ> explore ([], ['c', 'd', 'e'])
[ (['c'], ['d', 'e']),
(['C'], ['d', 'e']),
(['d'], ['c', 'e']),
(['D'], ['c', 'e']),
... ]

Once we have this explore function, we can validate the list it generates, and then call explore on every remaining grid again. We can repeat this until we are left with complete, valid grids.

Practice

Here’s what the real explore function looks like:

haskell


explore :: ([Piece], [Piece]) -> [([Piece], [Piece])]
explore (list, pool) = concatMap pluck [0..(length pool - 1)]
where pluck i = [ (list ++ [c], excise i pool)
| c <- take 4 $ iterate rotate (pool!!i) ]
excise i xs = take i xs ++ drop (i+1) xs
rotate piece = Piece { north = east piece, east = south piece
, south = west piece, west = north piece }

We define a few helper functions which are pretty useful.

pluck i implicitly takes the list pool, and returns a list of tuples of the form(newList, newPool), where
- the newList is the old list plus the selected candidate (at index i), and
- the newPool is the old pool minus the selected candidate. The whole thing is wrapped in a list comprehension so that rather than returning a tuple, pluck actually returns a list of all four rotations for a selected rotation. concatMap applied pluck to every item in the pool.
excise i xs returns the xs minus the element at the ith index.
rotate takes a piece and rotates it 90 degrees. take 4 $ iterate rotate returns a list of the piece at (xs!!i), that piece rotated once, that piece rotate twice… etc, four times. This serves the list comprehension, and then concatMap flattens it into a normal list.

`validate`

We need to validate each grid or portion of a grid which is generated in an efficient way. If we add pieces in slots zero through nine in order, then each new piece only needs to be compared against the pieces above or to the left of it (if they exist). Thus:

haskell


validate :: Int -> [Piece] -> Bool
validate n xs = (not hasAbove || matchAbove) && (not hasLeft || matchLeft)
where hasLeft = n `mod` 3 /= 0
hasAbove = n >= 3
matchLeft = west (xs!!n) == east (xs!!(n-1))
matchAbove = north (xs!!n) == south (xs!!(n-3))

matchLeft and matchAbove both take advantage of our custom instance of Eq for Sides. The getters north, east, south, and west were also generated implicitly from the named fields above.

OK. Let’s put it together.

Finding the solution

haskell


step 0 xs = explore ([], xs)
step n xs = filter (\(xs,_) -> validate n xs)
$ concatMap explore $ step (pred n) xs
main = do
let allPieces = map parsePiece
$ [ "HDdh", "CHsh", "DCcd",
"SDsh", "SDhd", "SShc",
"CHdc", "HDcc", "HSsc" ]
let sol = fst $ head $ step 8 allPieces

Cool. We can get our list of potential position 0 s easily with step 0 allPieces.

We can then get our list of potential position 1 s with:

haskell


step 1 allPieces
-- which turns into
filter (\(xs, _) -> validate 1 xs)) $ concatMap explore $ step 0 xs

This recursion means we validate a list of potential grids before returning it. So, step 8 allPieces generates the list of all potential 8th-poisition grids, which requires Haskell to generate the list of all potential 7th-position grids first, and so on and so on.

Filtering

How much does this save us? Let’s look at the numbers.

haskell


λ> print $ length $ step 0 allPieces
36
λ> print $ length $ step 1 allPieces
138
λ> print $ length $ step 2 allPieces
470
λ> print $ length $ step 3 allPieces
1350
λ> print $ length $ step 4 allPieces
474
λ> print $ length $ step 5 allPieces
144
λ> print $ length $ step 6 allPieces
175
λ> print $ length $ step 7 allPieces
28
λ> print $ length $ step 8 allPieces
4

One note – some of these numbers will be off by a factor of four, since a solved grid is the same across any rotation. That’s why there are $4$ valid solutions in the last row – it’s all the same solution across four rotations.

This means there were 36 valid pieces in position 0 (makes sense, since $9\times4$), but only 138 valid pairings for slots 0 and 1 adjacent, far less than the 1152 potentials. We peak at 1350 potential three-in-a-row combinations, and then filter down steadily.

Summing across these numbers, we see that validate must have been called something like 2800 times. Much, much better than validating all 23 billion grids.

Printing

Finally, we define a solution grid like so:

haskell


let sol = fst $ head $ step 8 allPieces

Unfortunately this gives us an output like this:

haskell


λ> main --solves the puzzle, returns the first valid grid.
[Piece {north = Side {suit = Heart, sex = In}, east = Side {suit = ...

Hard to read and inspect visually. I wrote a prettyprinter which turns that into this:

haskell


λ> main
.h. | .c. | .d.
s S | s H | h S
.D. | .S. | .D.
----|-----|----
.d. | .s. | .d.
D h | H h | H c
.H. | .C. | .C.
----|-----|----
.h. | .c. | .c.
S c | C d | D c
.S. | .D. | .H.

Which is much easier to inspect and validate. Here’s the prettyprinter:

haskell


renderGrid :: [Piece] -> [String]
renderGrid = intercalate ["----|-----|----"] . map renderRow . chunksOf 3
where renderRow xs = [ intercalate " | " $ map (\x -> renderSq x!!n) xs
| n <- [0..2] ]
renderSq p = [ "." ++ [unParse $ north p] ++ "."
, [unParse $ west p] ++ " " ++ [unParse $ east p]
, "." ++ [unParse $ south p] ++ "."
]
unParse s
| suit s == Club = f 'c'
| suit s == Spade = f 's'
| suit s == Diamond = f 'd'
| otherwise = f 'h'
where f = if sex s == Out then toUpper else id

Understanding this particular function is left as an exercise to the reader.

Full Code

You can see the full code here, in a gist.

Writing a TextTwist Implementation

Sat, 03 Dec 2016 00:00:00 -0400

Github	http://github.com/ambuc/text-twist

bash


$ runhaskell text-twist.hs
┌ T E X T T W I S T
├ Please enter a seed word:
domino
┏━━━━━━━━━━━━━━━━━━━━━┓
┃ ~~~ ~~~ ~~~~ ~~~~ ┃
┃ ~~~ ~~~ ~~~~ domino ┃
┃ ~~~ ~~~ ~~~~ ┃
┃ ~~~ ~~~ ~~~~ ┃
┗┯━━━━━━━━━━━━━━━━━━━━┛
├ Please enter a guess:
mind
┏━━━━━━━━━━━━━━━━━━━━━┓
┃ ~~~ ~~~ ~~~~ ~~~~ ┃
┃ ~~~ ~~~ mind domino ┃
┃ ~~~ ~~~ ~~~~ ┃
┃ ~~~ ~~~ ~~~~ ┃
┗┯━━━━━━━━━━━━━━━━━━━━┛
├ Please enter a guess:
mood
┏━━━━━━━━━━━━━━━━━━━━━┓
┃ ~~~ ~~~ ~~~~ ~~~~ ┃
┃ ~~~ ~~~ mind domino ┃
┃ ~~~ ~~~ ~~~~ ┃
┃ ~~~ ~~~ mood ┃
┗━━━━━━━━━━━━━━━━━━━━━┛

Text Twist is a classic old internet flash game in which the objective is to, given a starting word, find all the unique words which can be made from its letters.

This is a implementation in Haskell, playable from the shell. I hope the code is fairly readable.

You can just play the game:

bash


$ runhaskell text-twist.hs

or, compile it first if you like:

bash


$ ghc text-twist.hs
[1 of 1] Compiling Main ( text-twist.hs, text-twist.o )
Linking text-twist ...
$ ./text-twist
┌ T E X T T W I S T
│ Please enter a seed word:
...

Solving the Pairs of Percentages Puzzle

Sat, 29 Oct 2016 00:00:00 -0400

Here’s a math puzzle inspired by the election. I noticed a while back that the two candidates were at 81.5% and 18.5%, respectively. The numbers 185 and 815 are anagrams, and add to 1000 ($10^3$). How many such pairs of positive integers add to $10^3$?

I’ve been doing a bit of Haskell recently, so that’s my language of choice.

Exploring the space

The first step is to define a function which takes an integer pair and decides if the pair is valid (that is, if the two integers are anagrams or not.)

haskell


import Data.List
valid :: Int -> Int -> Bool
valid a b = list a == list b
where list = sort . filter (/=0) . digits
digits n = map (\x -> read [x] :: Int) (show n)

Let’s use this valid function to check a range of numbers (a,b) where $a+b=1000$, and valid a b == True.

haskell


import Data.List
λ> [(a,b) | a <- [1..500], let b = 1000 - a, valid a b]
[(95,905),(185,815),(275,725),(365,635),(455,545),(500,500)]

This is pretty cool. Let’s fit this into a function $f(n)$, where

$f(n)$ is the power $10^n$ we’re matching against,
pairs n returns the list of potential pairs,
validPairs n = filter(\(a,b) -> valid a b) $ pairs n, and
f n = length $ validPairs n, which is what we’re ultimately trying to find an expression for.

haskell


pairs :: Int -> [(Int, Int)]
pairs pow = [(a, (10^pow)-a) | a <- candidates]
where candidates pow = [0,5..(div (10^pow) 2)]
validPairs = filter(\(a,b) -> valid a b) . pairs
f = length . validPairs

If we run validPairs 4, we see a cool pattern.

haskell


λ> validPairs 4
[(995,99005), (1895,98105), (1985,98015), ... (49055,50945), (49505,50495), (50000,50000)]
λ> f 4
6
λ> f 5
141
λ> f 6
...

Before we go further, a few notes on this: for performance reasons, we only compute pairs (a,b), not (b,a). Because the last pair computed is always something like (50,50), (500,500), etc., the total number of pairs is actually $2f(n) - 1$. We’ll keep this in mind for later.

Here’s what we have so far:

`n`	1	2	3	4	5	6
`f(n)`	1	1	6	6	141	141
`2*f(n)-1`	1	1	11	11	281	281

Computing $f(6)$ took a really long time, so let’s eventually wrap this in a .hs file, compile, and execute it with timing.

But before we go further, let’s check the Online Encyclopedia of Integer Sequences to see if any of the sequences (1,1,6,6,141,141), (1,6,141), or (1,11,281) appear at all. It turns out (1,6,141) are the first few digits of A241015, which is the

Number of pairs of endofunctions $f$, $g$ on $[n]$ satisfying $g(g(g(f(i)))) = f(i)$ for all $i$ in $[n]$.

…whatever that means.

If our pattern matches theirs, we might expect the next number in the sequence to be is 6184. We’ll find out in a bit, but first let’s bring runtime down a bit.

Profiling

OK, it’s time to wrap this in a file, compile, and execute it with timing.

haskell


--puzzle.hs <num> (L | _)
import System.Environment
import Data.List
import Data.Char
valid :: Int -> Int -> Bool
valid a b = list a == list b
where list = sort . filter (/=0) . digits
digits n = map (\x -> read [x] :: Int) (show n)
pairs :: Int -> [(Int, Int)]
pairs pow = [(a, (10^pow)-a) | a <- candidates pow]
where candidates pow = [0,5..(div (10^pow) 2)]
validPairs = filter(\(a,b) -> valid a b) . pairs
f = length . validPairs
main :: IO ()
main = do
[num, action] <- getArgs
let n = digitToInt (head num)
let shouldList = (head action == 'L')
if shouldList
then print $ validPairs n
else print $ f n

Just for kicks, ./puzzle takes two arguments; the first is the number $n$, and the second is either L, to print the full list of matches, or _, to print the value $f(n)$.

We have a few ways to run this. One is to open up a ghci shell, import the file, and run validPairs <num> or f <num> right there in the shell:

with `ghci`

bash


$ ghci
GHCi, version 7.10.3: http://www.haskell.org/ghc/ :? for help
λ> :l puzzle
[1 of 1] Compiling Main ( puzzle.hs, interpreted )
Ok, modules loaded: Main.
λ> validPairs 3
[(95,905),(185,815),(275,725),(365,635),(455,545),(500,500)]
λ> f 3
6

This is great for testing, but we don’t get too many stats. Let’s use a real-time thing like runhaskell.

with `runhaskell`

bash


$ runhaskell puzzle.hs 3 L
[(95,905),(185,815),(275,725),(365,635),(455,545),(500,500)]
$ runhaskell puzzle.hs 3 _
6

To add stats, we use the +RTS runtime system flag with the -s summary flag.

bash


$ runhaskell puzzle.hs 3 _ +RTS -s
6
101,696 bytes allocated in the heap
3,464 bytes copied during GC
68,912 bytes maximum residency (1 sample(s))
13,008 bytes maximum slop
1 MB total memory in use (0 MB lost due to fragmentation)
Tot time (elapsed) Avg pause Max pause
Gen 0 0 colls, 0 par 0.000s 0.000s 0.0000s 0.0000s
Gen 1 1 colls, 0 par 0.000s 0.000s 0.0001s 0.0001s
INIT time 0.000s ( 0.000s elapsed)
MUT time 0.001s ( 0.189s elapsed)
GC time 0.000s ( 0.000s elapsed)
EXIT time 0.000s ( 0.000s elapsed)
Total time 0.006s ( 0.189s elapsed)
%GC time 2.5% (0.1% elapsed)
Alloc rate 178,562,837 bytes per MUT second
Productivity 96.1% of total user, 2.9% of total elapsed

Very cool. As a final step, we’ll properly compile and optimize it with ghc.

with `ghc`

bash


$ ghc -Odph puzzle.hs -rtsopts
[1 of 1] Compiling Main ( puzzle.hs, puzzle.o )
Linking puzzle ...
$ ./puzzle 3 _
6

We can run this with +RTS -s too. $ ./puzzle 3 _ +RTS -s generates the following table for f(1) through f(7):

n	1	2	3	4	5	6	7
`f(n)`	1	1	6	6	141	141	5591
time	0.001s	0.001s	0.003s	0.017s	0.190s	2.301s	26.711s

Let’s see if this matches our sequence from earlier. We now have the next value, putting our sequence at (1,6,141,5591). This is not in the OEIS.. So we’ll have to find an expression ourselves, and check with the scripts.

Unfortunately, our timing statisics are not optimistic. At this rate, $f(8)$ will take around five minutes to calculate. It would be a good idea to parallelize.

Parallelization

We can use the Control.Parallel library, (see the docs for more) which gives us the handy par and pseq functions, which force the compiler to split evaluations into separate threads and then wait to recombine. Much of the code has to be modified slightly. I run this on a four-core processor, so I rewrote this to split up the list of candidates into four roughly equal parts, evaluate the validity of each element in each of them, compute the length of that valid sublist, and recombine afterwards.

We’ll call this new file puzzle-parallel.hs. You’ll notice we drop support for printing the full list – constructing the sum was easier to parallelize.

bash


-- ghc -O2 --make puzzle-parallel.hs -threaded -rtsopts
-- ./puzzle-parallel <n> +RTS -N4 -s
--
import Control.Parallel
import Data.List.Split
... -- all the same imports as before
valid :: Int -> Int -> Bool -- as before
pairs :: Int -> Int -> [(Int, Int)]
pairs pow core = [(x, (10^pow)-x) | x <- candidates]
where candidates = [a+5,a+10..b] -- not as before!
a = (core - 1) * (div (10^pow) 8)
b = (core - 0) * (div (10^pow) 8)
-- validPairs can no longer be point-free, since it takes
-- two arguments: pow and core. There's probably a nice currying fix, though.
validPairs pow core = filter(\(a,b) -> valid a b) $ pairs pow core
f n = s1 `par` s2 `par` s3 `par` s4 `pseq` (s1 + s2 + s3 + s4)
where
s1 = length $ validPairs n 1
s2 = length $ validPairs n 2
s3 = length $ validPairs n 3
s4 = length $ validPairs n 4
main :: IO ()
main = do
[num] <- getArgs
-- we drop support for `./puzzle <num> L`, since computing these
-- large lists, sorting, and printing them is sort of out of
-- scope for the moment.
let n = digitToInt (head num)
print $ f n

The file puzzle-parallel.hs can now be compiled to be multithreaded with ghc:

bash


$ ghc -O2 --make puzzle-parallel.hs -threaded -rtsopts

and executed on four cores with the +RTS flag -N4 (or -N2, or however many cores you have. The above code is written for four cores, but it’s not hard to modify for any other number of cores.)

bash


$ ./puzzle-parallel <n> #unparallelized
$ ./puzzle-parallel <n> +RTS -N4 #force 4 cores
$ ./puzzle-parallel <n> +RTS -N4 -s #with stats

n	1	2	3	4	5	6	7	8
`f(n)`	1	1	6	6	141	141	5591	5591
time w/o parallelization	0.001s	0.001s	0.003s	0.017s	0.190s	2.301s	26.711s	501.863s
time w/ parallelization	0.001s	0.001s	0.003s	0.021s	0.133s	1.567s	18.489s	208.285s

We see around a 2x speedup from this – we expect a 4x from threading, but there is some loss to overhead. This speedup helps more the higher $n$ grows. This is better performance across the board. Now calculating $f(9)$ isn’t quite as impossible.

Expression

Rather than delve deeper into optimization, let’s focus on trying to find a closed-form expression for this sequence. We do this first by visual inspection of the types of pairs generated.

bash


$ ./puzzle 1 L
[(5,5)]
$ ./puzzle 2 L
[(50,50)]
$ ./puzzle 3 L
[(95,905),(185,815),(275,725),(365,635),(455,545),(500,500)]
$ ./puzzle 4 L
[(950,9050),(1850,8150),(2750,7250),(3650,6350),(4550,5450),(5000,5000)]
$ ./puzzle 5 L
[(995,99005),(1895,98105),(1985,98015),(2795,97205),(2975,97025),(3695,96305),
(3965,96035),(4595,95405),(4955,95045),(5495,94505),(5945,94055),(6395,93605),
(6935,93065),(7295,92705),(7925,92075),(8195,91805),(8915,91085),(9095,90905),
...
(45815,54185),(45905,54095),(46355,53645),(46535,53465),(47255,52745),
(47525,52475),(48155,51845),(48515,51485),(49055,50945),(49505,50495),
(50000,50000)]

Let’s introduce some nomenclature here to turn this from a programming puzzle into a math puzzle. For some $n$, we define $f(n)$ to be the number of possible pairs, and $S(n)$ to be the set of pairs itself. Thus, f(n) = length S(n).

Some observations:

For all even values $n$, we can see S(n) = [10*i for i in S(n-1)]; that is, every element of S(even n) is an element of S(odd n) multiplied by ten.
Thus, $f(n) = f(n-1)$ for even n.

Mapping to a simpler domain

We can see from the examples above that for sets generated by, say, $n=3$ and $n=4$, only the first two digits really fluctuate. We suspect the problem reduces to a combinatorics problem focused on strings of that length, which we call $m$. So, let’s map the domain of possible $n$ values to a simpler domain:

bash


m(n)
^
6 | o o
5 |
4 | o o
3 |
2 | o o
1 +-+-+-+-+-+-+-+--> n
1 2 3 4 5 6 7 8

We’ll switch to Python here for readability, and also because our algorithm will be imperative in a moment:

python


def M(n):
return ((n-1)//2)*2

This alongside future memoizations will help us avoid having to calculate $f(n)$ when $f(n-1)$ is known.

The 9-pair

We first define the concept of a 9-pair. A 9-pair is a set of two positive numbers which add to 9. 9-pairs are: (0,9), (1,8), (2,7), (3,6), and (4,5).

Numbers and 9-pairs

Here is an example pair from $S(n=5)$: (48155,51845). We can reduce this to its tuple of interest: (4815, 5184). It seems (1,8) and (4,5) are the 9-pairs which compose the alphabet from which this tuple was generated.

Since 1 and 8 are a 9-pair, if 1 appears in the first number of the tuple, then we know for sure that:

1 appears in the second item of the tuple,
8 appears in the first item of the tuple,
8 appears in the second item of the tuple.

Generalization: elements and element pairs

Let’s generalize this away from digits and number and into elements, sets, and permutations.

We will call (a,b) a tuple, a and b strings in that tuple, and the characters in the strings a and b characters.

For a given string a or b, any character in a or b uniquely defines its counterpart within an element-pair (i,j): if i in a, then j in b. Since the strings a and b are by definition anagrams, this means j in a as well. Thus a is a unique ordering of pairs of characters, selected from a known alphabet of character pairs.

Combinatorics on that domain

We can reduce this problem to finding the number of unique orderings of a list composed of selecting $x$ element-pairs from a list of $p$ element-pairs. We call this function $G(x,p)$. Because our real problem lies on the domain of digits, there will only eve be five element-pairs (the five 9-pairs), so $p=5$, always.

This is simple (if inefficient) in Python:

python


def G(x,p):
result = 0
# since p=5 always, this domain is always ['1','2','3','4','5']
domain = (str(i) for i in range(p))
itr = itertools.combinations_with_replacement(domain,x)
for i0 in itr:
# turns ['1','2'] into ['1','1~','2','2~'] for proper element-pairs
alphabet = list(i0) + list( map((lambda x: str(x)+"~"), i0) )
#the number of unique permutations in that alphabet of length 2x
result += len(set(list(itertools.permutations(alphabet,2*x))))
return result

To get our desired $f(n)$, we can just write:

python


def f(n):
# the same as M(n) above
m = ((n-1)//2)*2
# the answer is recursive -- G(x,5) alone will only return pairs of length x.
# we must also consider pairs of length y<x, right-padded by zeroes.
def inner_f(n):
return (G(n,5) + inner_f(n-1)) if (n > 0) else 0
# divided by two because (185, 815), (815, 185) are the same pair.
# plus one because (500, 500) won't be found by G5(x)
return inner_f(m)/2 + 1

Unmemoized timing `t0`

We can run this with timing:

python


for n in range(1,12):
start = time.time()
localF = f(n)
end = time.time()
print "f({0})\t{1}\t{2}".format(n, localF, end-start)

n	1	2	3	4	5	6	7	8	9	10
`f(n)`	1	1	6	6	141	141	5591	5591	281566	281566
`t0`	5.9e-6s	1.3e-5s	4.2e-5s	2.2e-5s	1.5e-4s	1.4e-4s	4.3e-3s	4.0e-3s	0.94s	0.94s

Memoization `t1`

We can improve performance a lot through memoization. Functions like $G(n,5)$ get called repeatedly for the same value of $n$, for example.

python


G5memo = {}
def G5(x):
if x not in G5memo:
G5memo[x] = G(x,5)
return G5memo[x]

n	1	2	3	4	5	6	7	8	9	10
`t1`	9.1e-6s	3.1e-6s	5.5e-5s	3.1e-6s	1.6e-4s	2.9e-6s	5.5e-3s	4.1e-6s	0.91s	1.6e-5s

The most obvious boost is that $f(n)$ where $n$ is even now takes almost no time to compute, since $f(n) = f(n-1)$ for even $n$.

Memoization `t2`

We can memoize further. The alphabet of characters fed into len(list(set(itr(alphabet)))) is usually something like ['a','A','a','A'] or ['b','B','b','B']. However, it seems obvious to us that the number of unique pairs from the first of these two alphabets will be the same as that of the second. It would be useful to create a non-unique hash of some kind, representing the pair distribution within an alphabet, and check whether len(list(set(itr(alphabet)))) for an equivalent alphabet has already been calculated.

python


# takes an alphabet like ['1', '1', '2', '3', '1~', '1~', '2~', '3~'] and returns
# \ / | |
# \ / | |
# (2) (1) (1) --> returns [1,1,2] as a list-hash
def makeListHash(alphabet):
d = {}
for i in alphabet[0:len(alphabet)/2]:
try:
d[i] += 1 #if i in d
except:
d[i] = 1
return list(str(x) for x in sorted(d.values()))
# just a wrapper for makeListHash which returns a string ("1,2,2") instead.
def makeStringHash(alphabet):
return ",".join(makeListHash(alphabet))

This lets us rewrite $G(x,p)$ as:

python


def G(x,p):
result = 0
alphabet = (str(i) for i in range(p))
itr = itertools.combinations_with_replacement(alphabet,x)
lMemo = {} #inline since memoization is only useful across a single value of x
for i0 in itr:
alphabet = list(i0) + list( map((lambda x: str(x)+"~"), i0) )
key = makeStringHash(alphabet)
if not key in lMemo:
lMemo[key] = len(set(list(itertools.permutations(alphabet,2*x))))
result += lMemo[key]
return result

This memoization brings down computation time even further, and lets us calculate $f(11)=f(12)$ for the first time ever.

$n$	1	2	3	4	5	6	7	8	9	10	11
$f(n)$	1	1	6	6	141	141	5591	5591	281566	281566	16397596
`t2`	6.9e-6	3.1e-6	6.8e-5	1.3e-5	1.4e-4	3.1e-6	6.9e-4	5.0e-6	6.8e-2	7.2e-6	10.5

Conclusions

That’s all! I wasn’t able to further optimize the problem, and I’m not convinced a closed-form solution necessarily exists. That said, we found the number of anagram pairs which sum to $100,000,000,000$, and that’s pretty cool. I also learned a lot about parallelization in Haskell and using the built-in optimization flags in ghc, and a bit of memoization in Python.

Update (11/11/2016)

It’s been around a week since last I touched this puzzle. My buddy Josh bounced the problem to his boss Piotr, who came up with this phenomenal closed-form solution for $G(x,p=5)$. It’s brilliant and involves reducing the combinatorics problem, searching for and finding the elusive closed-form solution in the literature, and writing a small haskell script to implement it. In short:

The combinatorics section above describes a

sequence $a_n^N := \Sigma \left( \dfrac{n!}{p_1! p_2! … p_N!}\right)^2$, where the sum runs over sets of non-negative integers $p_1,..p_N$ summing to $n$.

This sequence can be found by a recurrence relation, and was performed in Sums of squares of binomial coefficients, with applications to Picard-Fuchs equations by H. A. Verrill in 2008.

Table 1 in the above paper describes recurrence relations for $a_n^N$, and we care about the case where $N=5$: the fourth equation is the object of our desire. It reads:

$$ 0 = n^4 a_n^5 - (35n^4 - 70n^2 + 63n^2 - 28n + 5)a^5_{n-1} + (n-1)^2(259(n-1)^2 + 26)a^5_{n-2} - (3 \cdot 5)^2(n-1)^2 a^5_{n-3} $$

Piotr implemented this as so: (I’ve changed it the tiniest bit to better perform testing on it.)

haskell


import System.Environment
import Data.List
import Data.Char
next :: Integer -> Integer -> Integer -> Integer -> Integer
next n prev1 prev2 prev3 =
((35*n*n*n*n - 70*n*n*n + 63*n*n - 28*n + 5) * prev1 -
((n-1)*(n-1)*(259*(n-1)*(n-1) + 26)) * prev2 +
15*15*(n-1)*(n-1)*(n-2)*(n-2) * prev3)
`div` (n*n*n*n)
vals :: [Integer]
vals = 1 : 5 : 45 : (zipWith4 next [3..] (drop 2 vals) (drop 1 vals) vals)
choose :: Integer -> Integer -> Integer
choose n 0 = 1
choose 0 k = 0
choose n k = choose (n-1) (k-1) * n `div` k
finalvals = zipWith (\v n -> v * (choose (n*2) n)) vals [0..]
main :: IO ()
main = do
[num] <- getArgs
let n = read num :: Int
print $ (finalvals !! n)

and called with runhaskell math.hs <num> +RTS -s (assuming you save it as math.hs.)

As expected, this has a phenomenal runtime.

$n$	1	10	1e2	1e3	1e4	2e4	3e4	4e4	5e4
runtime	0.183s	0.183s	0.180s	0.198s	0.542s	1.232s	2.032s	3.203s	4.643s

I think that’s about as far as this problem goes. Thanks to Josh and Piotr for doing the actual difficult mathematics.

Building a Siteswap Visualizer in d3.js

Fri, 25 Dec 2015 00:00:00 -0400

App	http://jbuckland.com/juggling-graph
Github	http://github.com/ambuc/juggling-graph

Siteswap is a juggling notation used to describe or represent juggling patterns. It encodes the number of beats of each throw, which is related to their height, and the hand to which the throw is to be made: “The idea behind siteswap is to keep track of the order that balls are thrown and caught, and only that."[1] It is an invaluable tool in determining which combinations of throws yield valid juggling patterns for a given number of objects, and has led to previously unknown patterns (such as 441). However, it does not describe body movements such as behind-the-back and under-the-leg.

(from Wikipedia.)

This is a visualization engine for Siteswaps, a notation system used in juggling to represent patterns in space. It accepts input in the form of numbers 0-9, letters a-z, and brackets [ ], which denote multiplexes, i.e. synchronous events. juggling-graph draws arrows from each valid throwable position to each valid catch position. Multiplexes throw from their contents, but recieve at their opening bracket.

This project was my first venture into exclusively-compiled web development, utilizing Coffeescript and Jade. Both were a joy to use.

Design and Construction of a Walking Alarm Clock

Sun, 15 Nov 2015 00:00:00 -0400

Paper	ME270 Team Project Final Report
App	https://goo.gl/photos/BAEoTaT7WMQ4G2Av5
Github	http://github.com/ambuc/watchdog

The WatchDog is an electromechanical walking alarm clock built by Chris Olsen, Andrew Mott, David Thunga, Mike Bloom, and myself for the Design for Manufacturability (ME270) course at the University of Illinois in Fall 2015.

From the product description:

The WatchDog is an interactive novelty alarm clock that deters the user from overusing the snooze button. After the alarm has been snoozed once, the WatchDog is programmed to begin barking and running at the end of the snooze cycle to ensure the user must get out of bed to turn off the alarm. The WatchDog is a complex electro-mechanical system in which an Arduino controls both the alarm clock functionality and the rotation of two small servo motors. These servos were attached to eight-bar linkages (Jansen mechanisms) that were created using laser cut acrylic and held together with dowel pins and retaining rings. These linkages allow the WatchDog to move with fluid, canine-like motion thus adding to the aesthetic value of the design. The Arduino circuit and servos are housed within a segmented, 3D-printed torso that is held together with snap fits. The two endcaps of the torso are attached to a dog-like head and tail to add to the friendliness of the design.

The majority of my contributions to the project were towards its circuit design and Arduino programming, as detailed in the paper.

Scraping Wikipedia to Build a Historical Trivia Game

Tue, 11 Aug 2015 00:00:00 -0400

App	http://jbuckland.com/test-of-time
Github	http://github.com/ambuc/test-of-time

The Test of Time is a historical trivia game where you order events chronologically, guessing which events came before and after each other. As the round goes on, it becomes harder to pinpoint exactly when obscure events happened. That’s pretty much all there is to it.

Julian and I decided to build this after thinking about how much excellent data was locked up inside Wikipedia as unformatted plaintext. We found a fantastic corpus created by Dr. Daniel Heinert for extracting chronological events, downloaded a bunch of events, and reformatted them into JSON. The interface uses the Materialize CSS library and Google’s Material Icons.

Generating Fractals with Lindenmayer Systems

Thu, 06 Aug 2015 00:00:00 -0400

App	http://jbuckland.com/lindenmayer
Github	http://github.com/ambuc/lindenmayer

About Lindenmayer Systems

L-systems are formal grammar structures used in the study of both botany and mathematics, usually to simulate iterative or recursive structures, such as algae or fractals. In this case, we employ them to render fractals.

As noted, in the Wikipedia article on L-systems (from which much of this math is cribbed), an L-system can be represented by the tuple $$\v G = (V, \omega, P)$$

where $\v G$ is the alphabet,
$\omega$ is the seed, the first string, and
$P$ is the set of production rules, by which the current string is replaced by definitions from the alphabet.

Dragon Curve

Let’s take the famous Dragon Curve for example. Here,

$\v G = [X, Y]$,
$\omega = FX$, and
$P = (X \longrightarrow X+YF+,\quad Y \longrightarrow -FX-Y)$.

In this example, $X$ and $Y$ are variables, which get replaced iteratively with the definitions in $P$; $+$ and $-$ are right and left turns, respectively, and $F$ means go forwards.

At a depth of 0, we have only the initial string $\omega$:
- $FX$
At a depth of 1, we get
- $FX \longrightarrow F[X]$
- $ \phantom{FX} \longrightarrow F[X+YF+] $
- $ \phantom{FX} \longrightarrow FX+YF+ $
At a depth of 2, we get
- $FX+YF+ \longrightarrow F[X]+[Y]F+$
- $\phantom{FX+YF+} \longrightarrow F[X+YF+]+[-FX-Y]F+$
- $\phantom{FX+YF+} \longrightarrow FX+YF++-FX-YF+$

You can see where this is going.

The dragon curve takes a number of iterations to get going, but many of the other curves show high levels of self-similarity at a depth of only 1 or 2. It depends on the rewriting rules.

Design of the Application

Josh Mermelstein and I wrote a very simple Python script which can parse these sorts of string rules, stored in a dictionary (later, a Javascript object). It then iteratively replaces the necessary strings, swaps out those strings for an array of commands, and then evaluates each of those commands. Using Turtle Graphics, Python then drew that pattern on-screen. The webapp is simply a javascript port of the same code, with the ability to modify the constants and redraw the fractal in real time.

Pseudo-psuedocode

python


from turtle import *
# recursively rewrites $str to a given $depth using an $alphabet
def rewrite(str, alphabet, depth):
if depth == 0:
steps = ''
for char in str:
if char in alphabet:
steps += alphabet[char]
else:
steps += char
return steps
else:
return rewrite(rewrite(str, alphabet, 0), alphabet, depth-1)
# translates a series of $steps into commands using an $alphabet
def translate(steps, alphabet):
commands = []
for char in steps:
commands.append(alphabet[char])
return commands
if __name__ == '__main__':
T = Turtle()
T.speed("fastest")
segmentLength = 10
depth = 3
# the entire fractal is here
rewritingRules = {
'L' : '+RF-LFL-FR+' ,
'R' : '-LF+RFR+FL-'
}
alphabet = {
'L' : '' ,
'R' : '' ,
'+' : 'T.lt(90)' ,
'-' : 'T.rt(90)' ,
'F' : 'T.fd(segmentLength)'
}
seed = 'L'
steps = rewrite(seed, rewritingRules, depth)
instructions = translate(steps, alphabet)
for item in instructions:
if item:
eval(item)

Building a Zoomable JSON Visualizer

Wed, 29 Jul 2015 00:00:00 -0400

App	http://jsrmath.github.io/seesaw
Github	http://github.com/jsrmath/seesaw

Seesaw is a web-based tool Julian and I built for inspecting complex JSON structures, without having to click to expand and collapse folders. You can click a box to zoom to it, or use the arrow keys to navigate around the structure.

The central conceit of Seesaw is that everything is either a bottom-level key-value pair, or a box containing either key-value pairs or other boxes. Every JSON element is drawn onscreen on load, and each associated div is printed nested inside its parent. Bottom-level key-value pairs are colored consistently, so that a name key is, for example, always red. This, coupled with the tendency of arrays to look visually consistent, makes exploring a complex, nested data structure much easier.

The up and down arrows go up and down a level in the object, and the left and right arrows navigate to siblings.

Seesaw uses Janne Aukia’s library Zoomooz for a suspiciously smooth zooming experience across browsers.

Cultural and Ecological Analysis of Mining in Norrbotten, Sweden

Wed, 15 Jul 2015 00:00:00 -0400

Paper	The Norrbotten Technological Megasystem: Impact on Society and Environment

This is a report Jessica Malmberg and I compiled during the summer of 2015 under the direction of Dag Avango and Dr. Mark Safstrom, as a part of the course AK1214 Environment and Society in a Changing Arctic, hosted jointly by KTH in Stockholm and the University of Illinois at Urbana-Champaign.

The course involved three weeks of lectures in Stockholm on the topic of environmental and social change in the Arctic region, with an emphasis on Norrbotten, Sweden, as well as two weeks of travel and field research in Norrbotten, including on-site visits to Aitik, Malmberget, and Kiruna, as well as a stay at the Tarfala Research Station in the Tarfala Valley and visits to the Samí Museum in Jokkmokk, Laponia national park, and other cultural heritage sites in Norrbotten.

The paper incorporates first-hand research into the environmental and social impacts of mining, hydropower, industrialization, and the railway - together known as the Norrbotten Technological Megasystem.

Design and Operation of a Crowd-Run Distributed Outdoor Game

Mon, 01 Jun 2015 00:00:00 -0400

App	http://hideandseek.ninja/stockholm.html

NB: This project is down for maintenance.

The Pre-Game

In May 2015, Aaron Luo, Anna Robbins, Claudio Paganini, and I sat down and designed a model for a new type of event: a free, outdoor, massive game of hide-and-seek. We would attract attention through a Facebook group, and have participants read rules and register on a website (http://hideandseek.ninja/) (which I would build and maintain) during the game.

What was the incentive for such an unusual event?

Legal Considerations

We were inspired by stories of people playing Hide and Seek in an Ikea. This is both a) very Swedish, and b) very illegal. Private property and unregistered events don’t mix well. So our event had to be outdoors, public, unlisted, and legal.

We realized that concerns of legality rarely had to do with attendance – they had more to do with density. Enough people in the same place would clog traffic, call attention, get us shut down, etc. But thousands of people could still play - as long as they were not all in the same place.

But, most importantly, it had to be disorganized. The idea of standing in a city square with a megaphone trying to shout instructions to hundreds of people was not an appealing one.

Thus was born the distributed game.

Imagine twenty or so little games of Hide-and-Seek going on all around the city. There are under 40 people per game, and each game is self-contained, each with its own meeting point and region. Stray too far from one zone, and you begin to encounter players from another. The game could grow organically as more and more people were invited, and it wouldn’t affect gameplay at all – as long as we distributed the game over a large enough area.

But how would the game work?

Math and Scoring

Hide and Seek in Gamla Stan operated on a unique scoring system designed by Claudio Paganini.

Each player starts with 100 points. They then share these 100 points with those seekers find them. Thus, if I am found three times, each seeker recieves 25 points, and I, the hider, keep 25 points of my points. When the roles are reversed, I do my best to find many hiders and recoup my losses.

(How do you prove you found me? We’ll get there in a moment.)

The benefit of this system is that suddenly the game requires strategy. In a short game period, the seeker can only find so many hiders. The share system means that seekers are rewarded not only for quantity of finds, but quality – those hiders who are more difficult to find are found less, and each share of their points is worth more. One really good find can be worth as many as 50 points. A bad find could easily be worth 5.

How would you prove you found someone?

Proof of Find

From the beginning, we wanted people to be able to play without supervision or oversight. Thus, rather than verify finds by hand (impossible) or rely on an honor system, we chose to verify finds mathematically, with a small bit of information.

Each hider was, at registration, given a secret code (mine was B030) to share with those seekers who found them. The seekers would then write down the code in a notepad, on their phone, whatever. After the game, they could go to the website, enter the code, and verify their find.

As the players logged their finds, we began to generate a graph of finds across town.

How were the codes generated?

Design of the Secret Code

Anna Robbins and I struggled with the concept of a ‘secret code’ for a few days. A short text string was easier than something more verifiable, like a QR code, but language barriers, spelling errors, and handwriting meant that strings, words, phrases, were untenable. We wanted it to be short and sweet, something easy to write and easy to type in afterwards.

Additionally, the codes had to be salted: that is, it ought to be difficult to randomly guess a string and have it be an extant secret code.

$$\underbrace{\texttt{B}}_{\texttt{email_string[0]}} \overbrace{\texttt{030}}^{\texttt{dec2hex}(id)}$$

The first character is an alphanumeric character, the first in their email. The next three characters are the truncated hexadecimal representation of their identification number ($id) in the database. (The $id represents if they were first, second, etc. to sign up for the game.)

The first bit was known to the user; the second was not. The second bit was easy to figure out, if you knew hex; the first was not. It doesn’t stand up to real cryptographic analysis, of course, but it did the trick – we didn’t detect any cheating.

An additional failsafe against cheating was that anybody sharing codes with their friends was effectively diminishing the value of the code. A 25pt find, split an additional way, becomes a 20pt find.

How did we invite people?

Once the game was designed, the rest was simple. We started a Facebook event and invited every student we knew. I personally asked a few social mavens to invite everyone they knew.

After the first few days, Facebook’s attendance measurement began to lose digits of accuracy. Thus, I only have rate-of-attendance data for the first thousand attendees or so. We eventually reached just over 6k invited / 3.5k attending on Facebook, with just over 1k of those people actually registering to play on http://hideandseek.ninja.

Those Attending on Facebook, vs…

…those Officially Registered on the Website.

The registration system collected the player’s first and last name, email, and hometown. Upon submission of the registration form, each player recieved a customized email containing more detailed gameplay instructions, their secret code, their team (whether they were to hide first or seek first), and their Zone – initially, merely a random number between 1 and 24. (24 is a very divisible number.)

How did we assign zones?

Zones

Once we reached ~800 registered, we began to divide up Gamla Stan and the surrounding neighborhood into 12 zones, and demarcate a region of fair play.

We picked (hopefully) good meeting points (public squares, parks, places far from traffic and palaces) and emailed instructions on a per-zone basis, indicating where to meet, when to begin playing, etc.

Players needed to bring a pen and pad, to write down the secret codes they found. They also needed a watch or something similar to keep an eye on the time – each team had 15 minutes to hide, and 30 minutes in which to stay hidden while the other team sought. Then, after another 15 minutes, they would switch. The game wouldn’t work if people didn’t know where to go when.

Additionally, the players needed another key ingredient…

Socks

The game was called, colloquially, Hide and Sock. Players had to know who was playing and who was just a bystander. We instructed players to wear a sock on their hand, so that they could be found. So they had to bring a sock.

The Game

On the day of the event, I got my sock, pen, paper, watch, secret code, zone, etc – everything I needed – and went to my assigned location, where I found – a dozen or so people hanging around, waiting to meet their zone. It turned out not all of our players were college students – plenty of families, tourists, elderly, etc. We synced knowledge about gameplay and schedules, discussed how we found out about the event, and then - suddenly - it was time to hide.

I hid quite badly, because I wanted to see how many people were actually playing. I was found just over 40 times in 30 minutes, which I think is quite impressive - close to 1000 people were actually playing that day, and I personally shook the hand of just over 1/25 of them.

The game went fast - I regret how tight we made the schedule, and how long we made the hiding period. Too many people were too good at hiding, and were never found.

The Aftergame

As per instructions, we all met in Kungstradgarden for a group photo, where I met many of the players and got feedback on how the event went. We also used Aaron’s selfie stick to take a group photo. (I’m in the center, behind the photographer.)

Countries of Origin

When a player registered, we collected their first and last name, email, and hometown (just for fun data analysis). We ended up with 1141 registered players, hailing from 127 regions (countries, large cities, neighborhoods). It’s difficult to graph, but the top three countries were Sweden, Germany, India, Italy, France, Singapore, China, and then over one hundred more with shares under 1%.

Finds

We expected players from each group to mostly end up finding players from their own group. Instead, most people in most zones had the bright idea of spreading as far from their home base as they could. As a result, there was far more cross-pollination than expected. With 1105 registered finds from 139 participating players, 1026 of those finds (92.8%) were of players from other zones. Some zones contained no same-zone finds. The groups quickly disseminated and play roamed free across the city – as intended.

Finds between Zones. Each find is a very light red line. The more inter-zone finds, the darker the red line becomes. Point location is approximate ;)

Altogether, the game was a rousing success, with some players scoring as high as 481 points (found 13 people, was found once).

What Did We Learn?

People are Reliable

The groups were surprisingly self-organizing, and the players were polite, honest, and fun. I met a ton of people, and I think everyone had a great time. (It helped that the weather was great.)

People are Unreliable

On Facebook, anyway. We had 6k invited, 3.5k attending, 1k registered, and just over 150 estimated participants. Under 100 showed up for the final photo.

Knowing this now, we could have made the map a lot denser - I heard reports that some zones were so sparsely populated that finding anybody at all was a challenge.

¯\_(ツ)_/¯

A Walkthrough of the Advection-Differencing Scheme

Thu, 28 May 2015 00:00:00 -0400

$$ \def\phi{\varphi} $$

Disclaimer: This is something a little different. I’m going to step through solving a practice problem for the MJ2424 Numerical Methods final exam, partially as practice teaching (and understanding) the material, partially as practice writing scientifically, and partially for fun. I’ll be working off my own derivation, but checking my answers, so I really hope the material is accurate.

What is Computational Fluid Dynamics?

CFD is the process of reducing problems in Fluid Dynamics to stepwise, iterative processes computers can solve. Specifically, it involves taking a real-life continuum and reducing it to a finite-volume calculation with a set number of cells, across each of which a very simple calculation will be performed. This allows us to turn a complex calculus problem, difficult for computational problem solving, into a linear algebra problem, which is much simpler.

The Problem

As seen in Classroom Example 3 of Section 4.7 Discretising Advection of David D Apsley’s CFD Notes:

A pipe of cross-section $A = 0.01 m^2$ and length $L = 1 m$ carries water (density $\rho = 1000 kg / m^{3}$ at velocity $u = 0.1 m / s$.

A faulty valve introduces a reactive chemical into the pipe half-way along its length at a rate of $0.01 kg /s$. The diffusivity of the chemical in water is $\Gamma = 0.1 kg / m s$. The chemical is subsequently broken down at a rate proportional to its concentration $\phi$ (mass of chemical per unit mass of water), this rate amounting to $–\gamma\phi$ per metre, where $\gamma = 0.5 kg / m s$.

Assuming that the downstream boundary condition is $\d{\phi}{x}=0$, set up a finite-volume calculation with 7 cells to estimate the concentration along the pipe using:

(a) central

(b) upwind

differencing schemes for advection.

The Method

From the normal steady-state one-dimensional advection diffusion equation

$$\pd{\rho\phi}{t} + \div(\rho\phi\v u) = div(\Gamma\grad\phi) + S_\phi $$

We make the equation steady-state and one-dimensional:

$$\d{}{x}\left(\rho u A \phi - \Gamma A \d{\phi}{x} \right)=S$$

We must now introduce the east/west convention. The current cell in question is $P$; its east and west neighbors are $E$ and $W$. Its east and west faces - that is, the boundaries it shares with those neighbors - are designated as the lowercase versions of those cardinal directions, $e$ and $w$. We can then write:

$$\d{}{x}\left( \rho u \phi \right)^e_w = \d{}{x}\left( \Gamma \d{\phi}{x} \right)^E_W$$

Integrating the transport equation, we find:

$$(\rho u A \phi)_e - (\rho u A \phi)_w = (\Gamma A)\left(\d{\phi}{x}\right)_E - (\Gamma A)\left( \d{\phi}{x} \right)$$

We define the constants: $ F = \rho A u_w^e$ and $D = \left( \frac{\Gamma A}{\Delta x} \right)_w^e$

Such that the integrated convection-diffusion equation reads:

$$F_e \phi_e - F_w \phi_w = D_e(\phi_E - \phi_P) - D_w(\phi_P - \phi_W)$$

The Central Differencing Scheme (CDS)

Here we introduce a scheme for finding the values of a given property - in this problem, a chemical concentration - at a boundary between two cells, given its value at the centers of those two cells. We introduce:

$$\phi_e = \frac{\phi_E + \phi_P}{2} \qquad \phi_w = \frac{\phi_P + \phi_W}{2} \qquad \text{(This is the CDS)}$$

Expanding generally - we will expand a little more specifically in a moment - we find:

$$F_e \phi_e - F_w \phi_w = D_e (\phi_E - \phi_P) - D_w (\phi_P - \phi_w)$$

Expanding out for our CDS:

$$\frac{F_e}{2}(\phi_P + \phi_E) - \frac{F_w}{2}(\phi_W + \phi_P) = D_e(\phi_E - \phi_P) - D_w (\phi_P - \phi_W)$$

And, finally, gathering by $\phi$:

$$\left(\left(D_w + \tfrac{F_w}{2}\right)+\left(D_e - \tfrac{F_e}{2}\right)+\left(F_e - F_w\right)\right)\phi_P = \left(D_w + \tfrac{F_w}{2}\right)\phi_W + \left(D_e - \tfrac{F_e}{2}\right) \phi_E$$

Essentially, this allows us to define a set of variables, and use them repeatedly to solve this generalized cell at unique conditions, such as at boundaries or sources.

$a_W = D_w + \tfrac{F_w}{2}$
$a_E = D_e - \tfrac{F_e}{2}$
$a_P = a_w + a_e + F_e - F_w$

Sources

Our problem has an additional complexity - the variable in question, $\phi$, the concentration of a given chemical, has both an internal (not boundary) source, and a constant rate of dissipation. Thus we must introduce a source term. Each cell is assigned a quantity $S_u$ corresponding to the rate of material addition, and a scaling quantity $S_P$, corresponding to the dissipation of the material over space.

$$\Sigma S = S_u + S_p \phi_p$$

The problem description tells us that material is injected only once, at cell #4, at a rate of $\dot m = 0.01 kg/s$. Thus $S_u(4) = 0.01$, and $S_u = 0$ elsewhere. Additionally, the chemical dissipates at a rate $\gamma\phi$ per meter, where $\gamma = 0.5 kg / m s$. Thus, $S_P = \gamma\Delta x$, where $\Delta x$ is the step distance ($1m / 7$). $S_P$ is applicable on all cells, not just those with the chemical.

We introduce these terms on the right-hand side of the quation, as seen in the normal steady-state one-dimensional diffusion equation at the top of the page. Thus, the general form:

$$F_e \phi_e - F_w \phi_w = D_e (\phi_E - \phi_P) - D_w (\phi_P - \phi_w)$$

becomes:

$$F_e \phi_e - F_w \phi_w = D_e (\phi_E - \phi_P) - D_w (\phi_P - \phi_w) + S_u + S_P \phi_P$$

and the $S_P \phi_P$ term is often factored to the left-hand side, as above.

Solving the Problem

We solve this problem on four unique cases, where we simplify $D_e = D_w$, $F_e = F_w$, and $S_p = \gamma\Delta x$ always.

The Default Cell (Cells 2, 3, 5, 6)

If the cell has no sources and no boundaries, the transport equation is unchanged. We write:

$$F_e \phi_e - F_w \phi_w = D_e (\phi_E - \phi_P) - D_w (\phi_P - \phi_W) + S_u + S_p\phi_P$$

where $S_u = 0$. We expand by CDS and find:

$$(2D - S_P)\phi_P = (D+\tfrac{F}{2})\phi_W + (D-\tfrac{F}{2})\phi_E$$

And thus, $a_W = D+F/2$, $a_E = D-F/2$, $S_u = 0$, $a_p = a_E + a_W - S_P = 2D - S_P$.

The Injection Cell (Cell 4)

The Injection Cell behaves in a very similar manner to the Default Cell, except that there is a source, so $S_u$ is nonzero. Thus: $a_W = D+F/2$, $a_E = D-F/2$, $S_u = 0.1$, $a_p = a_E + a_W - S_P = 2D - S_P$.

The Left Boundary (Cell 1)

The boundary conditions are unique – on the left-hand face, designated $A$, we know $\phi(A) = 0$. We expand the standard form more slowly:

$$F_e \phi_e - F_w \phi_w = D_e (\phi_E - \phi_P) - D_w (\phi_P - \phi_W) + S_u + S_P \phi_P$$

Expanding by CDS:

$$F_e \tfrac{\phi_E + \phi_P}{2} - F_a \phi_A = D_e (\phi_E - \phi_P) - D_A \phi_A + S_u + S_p \phi_P$$

We note $\phi_A = 0$. This allows us to regroup as:

$$(3D + \tfrac{F}{2} - S_p)\phi_P = (0)\phi_W + (D-\tfrac{F}{2})\phi_E + S_u$$

Thus, $a_W = 0$, $a_E = D-F/2$, $S_u = 0$, $a_p = 3D + F/2 - S_P$.

The Right Boundary (Cell 7)

The right boundary is the inverse of the left boundary. We know that $\pd{\phi}{x}(B) = 0$, so the $B$ terms similarly go to zero. Thus, $a_W = D+F/2$, $a_E = 0$, $S_u = 0$, $a_p = D + F/2 - S_P$

Numerically

We know $D=\Gamma A / \Delta x = 0.007 kg/s$, $F = \rho A u = 1 kg/s$, and $S_P = \gamma\Delta x = -0.07 kg/s$. We can thus solve:

n	$a_w$	$a_e$	$a_p$	$S_u$
1	$\ 0$	$\ -0.493$	$\ 0.592$	$\ 0$
2,3,5,6	$\ 0.507$	$\ -0.493$	$\ 0.085$	$\ 0$
4	$\ 0.507$	$\ -0.493$	$\ 0.085$	$\ 0.01$
7	$\ 0.507$	$\ 0$	$\ 0.578$	$\ 0$

These constants hold for any instance of:

$$a_P \phi_P = a_W \phi_W + a_E \phi_E + S_u$$

Using all seven iterations of this equations, we can populate a linear equation with real numerical values, and solve:

$$ \begin{pmatrix} 0.592 & 0.493 & 0 & 0 & 0 & 0 & 0\\ -0.507 & 0.085 & 0.493 & 0 & 0 & 0 & 0\\ 0 & -0.507 & 0.085 & 0.493 & 0 & 0 & 0\\ 0 & 0 & 0 & -0.507 & 0.085 & 0.493 & 0\\ 0 & 0 & 0 & 0 & -0.507 & 0.085 & 0.493\\ 0 & 0 & 0 & 0 & 0 & -0.507 & 0.578 \end{pmatrix} \begin{bmatrix}\phi(1)\\phi(2)\\phi(3)\\phi(4)\\phi(5)\\phi(6)\\phi(7)\end{bmatrix} = \begin{pmatrix}0\\0\\0\\0.01\\0\\0\\0\end{pmatrix} $$

Which we can solve in a computer (or by hand, if you’re a sadist) to get real values for $\phi(n)$ for all values in $n = [1..7]$.

Energy Optimization of an HVAC System via Numerical Modeling

Fri, 15 May 2015 00:00:00 -0400

Paper	Systematic Energy Utilization Optimization in DesignBuilder

This is a report Akshaya Kumar and I compiled in May 2015, as part of the MJ2437 Modelling of Energy Systems / Energy Utilization course at KTH, in Stockholm. Under the direction of Dr. Jaime Arias, we created a 3D model of one of the lab buildings on campus, complete with elevation / climate information, construction / insulation methods, and first-hand research on HVAC / lighting / power load details. We then populated the model with real information about average activity throughout the year. Tuning this model to match actual power usage data, we were then able to recommend specific HVAC changes, such as the inclusion of a heat recovery system, or the use of a variable air volume HVAC system. Analyzing costs of power vs costs of renovation, we present risk assessments and payback periods for each measure presented.

The model was constructed in a CAD system and the energy simulated using a copy of DesignBuilder furnished by KTH.

Simulating Wind Flow with Star-CCM+ as a Method of Locating High-Velocity Regions

Mon, 04 May 2015 00:00:00 -0400

Paper	Methods of Wind Turbine Placement with Computational Fluid Dynamics

This is a report Tamas Pal and I compiled in May 2015, as part of the MJ2424 Numerical Methods course at KTH, in Stockholm. Under the direction of Bahram Saadatfar and Reza Fakhrai, we created a 3D model of the entire KTH campus, complete with boundary conditions. We then populated the model with real building geometry and elevation/climate data. We then tuned the model with reasonable wind speeds data. Analyzing streamlines and velocity gradients, we were then able to recommend specific locations on KTH campus for the placement of a wind turbine, for maximum annual average wind velocity and minimal downtime.

The model was constructed in a CAD system and the fluid dynamics flow simulated using a copy of Star-CCM+ furnished by KTH.

Design and Characteristics of a Solar Field

Tue, 17 Mar 2015 00:00:00 -0400

Paper	MJ2412 Renewable Energy Technology - Morocco Proposal

This is a report Alexandre Oudet, Jean-Fraņcois Olivier, Heinrich Boeing, Akshaya Kumar, and I compiled in March 2015, as part of the MJ2412 Renewable Energy Technology course at KTH, in Stockholm. We designed and evaluated the feasibility and necessary physical and mechanical constraints on a number of potential technologies involved in the construction and operation of a solar field. Physical models were developed in conjunction with financial data, to estimate the potential supply and forecasted demand in the region. An iterative method was used to calculate all relevant power plant variables to some optimal efficiency.

Abstract

The Government of the Kingdom of Morocco has recently launched a program to increase the penetration of solar power in the national energy market. Thus, an contract has been promised to the independent energy production corporation able to deliver 100 MWe of base-load capacity from a concentrated solar power (CSP) plant to the grid at the lowest price.

At SolenKRAFT AB, our group of R&D Engineers has been appointed responsible for providing a suitable initial design to meet the required capacity and operating strategy. This report will present a technically viable solution, and clearly state the limitations and problems with the project. No cost estimation will be performed. Of the different types of solar concentrators (presented in Figure 1) we consider those suitable for industrial use at medium to high power at temperatures of above 250°C.

These devices use reflective surfaces to mirror sunlight, and are differentiable by their variable geometries. There are three types: a) parabolic trough, b) central tower, and c) parabolic-mirror CSP plants.

We choose the parabolic trough in order to meet our base-load capacity requirement of 100 MWe. In a parabolic trough, sunlight is concentrated towards a receiver carrying a heat transfer fluid. With water as the transfer fluid, steam is directly generated for use in a power plant. However, the stability of a water-based receiver is uncertain, and steam-based heat storage is complex. We thus propose the use of an oil-based fluid for heat transfer. These oils are single-phase fluids with an efficient heat transfer coefficient, and a temperature range fitting our needs, as well as the possibility for direct storage. Synthetic oils are preferred over mineral oils for their lesser flammability. We will employ this working fluid in a thermodynamic Rankine cycle, detailed in Section 4.

Partial Mechanical Design of a Pantograph

Fri, 14 Mar 2014 00:00:00 -0400

App	http://jbuckland.com/pantograph
Github	http://github.com/ambuc/pantograph

I was inspired by the above video (depicting a set of record players in control of a pantograph) to derive a closed-form solution for the vector position of the pen in terms of the angles of rotation for each of the arms

Derivations

Derivation of nodes $A$, $B$, $P$, $Q$, and $M$

For our pantograph assembly, we define the centers of two circles $A$ and $B$, each with a radius $r_a$ and $r_b$, respectively. The current positions of nodes $P$ and $Q$ are determined by angles $\theta_a$ and $\theta_b$.

Taking the position of $A$ as the origin, we can find

$$ \vec{A} = \Big(0,\ 0\Big) $$

$$ \vec{B} = \Big(0,\ (r_a + d + r_b)\Big) $$

$$ \vec{P} = \vec{A} + \Big( r_a\ \angle\ \theta_a \Big) $$

$$ \vec{Q} = \vec{B} + \Big( r_b\ \angle\ \theta_b \Big) $$

$$ \vec{M} = \frac{1}{2}\left( \vec{P} + \vec{Q}\right) = \Big( \tfrac{1}{2}(P_x + Q_x), \tfrac{1}{2}(P_y + Q_y) \Big)$$

Derivation of node $R$

Attached to the points $P$, $Q$ are two rigid bodies of length $\ell_1$, which meet at variable point $R$. By finding the midpoint $M$ between $P$ and $Q$, we can find the right triangle $\triangle PMR$. From the definition of slope, we find $\overline{PQ}$ to be $$m_{\overline{PQ}} = \dfrac{Q_y - P_y}{Q_x - P_x}$$

Because $\overline{MR} \perp \overline{PQ}$, we can find the slope of the line $\overline{MR}$ to be

$$ m_{\overline{MR}} = \left(m_{\overline{PQ}}\right)^{-1} $$

In addition, we can construct the right triangle $\triangle PMR$ with known side lengths $a$ and $g$, where

$$g = \tfrac{1}{2}|\overline{PQ}| = \tfrac{1}{2}{\sqrt{(Q_x - P_x)^2 + (Q_y - P_y)^2}}$$

Thus, $h = \sqrt{(\ell_1)^2 - g^2}$. This allows us to find

$$\vec{R} = \vec{M} + \left( h\ \angle\ \tan^{-1}\left(m_{\overline{MR}}\right) \right)$$

$$\vec{R} = \vec{M} + \left( \sqrt{a^2 - g^2}\ \angle\ \tan^{-1}\left( \dfrac{-1}{m_{\overline{PQ}}} \right) \right) $$

Derivation of nodes $S$, $T$

We can easily find $\varphi_a$, $\varphi_b$ from the slopes of lines $\overline{PR}$ and $\overline{QR}$, respectively.

$$ \varphi_a = \tan^{-1}\left( \dfrac{R_y - P_y}{R_x - P_x} \right) $$

$$ \varphi_b = \tan^{-1}\left( \dfrac{R_y - Q_y}{R_x - Q_x} \right )$$

We can then write nodes $S$ and $T$ as $$\vec{S} = \vec{R} + \left( \ell_2\ \angle\ \varphi_b\right) $$ $$ \vec{T} = \vec{R} + \left( \ell_2\ \angle\ \varphi_a\right)$$

Derivation of node $U$

It is trivial to present a construction of triangle $\triangle TUS$ that directly mirrors that of triangle $\triangle QRP$. We find

$$\vec{N} = \frac{1}{2}\left(\vec{S} + \vec{T}\right) $$

$$ d = \sqrt{(\ell_3)^2 - c^2} $$

$$ m_{\overline{NU}} = \dfrac{-1}{m_{\overline{ST}}} = -\dfrac{T_x - S_x}{T_y - S_y}$$

Thus, we can write node $U$ as $$\vec{U} = \vec{N} + \left(d\ \angle\ \tan^{-1}\left( m_{\overline{NU}} \right)\right)$$

Distressingly, this appears to be a function that cannot be resolved into a one-to-one mapping from the vector space $(\phi_a, \phi_b)$ onto the $(x,y)$ coordinate system of the pen by any conventional means: that is, for each $(x,y)$ on the pad, there are two or three sets of $(\phi_a, \phi_b)$ positions that could achieve that position.

At a loss with the tools of continuous mathematics, I turned to discrete simulations: a set of three processing.js simulations illustrating what turned out to be a very complex space.

Demos

Demo $\alpha$: Mouse-driven geometry demo of pantograph behavior
Demo $\beta$: Mouse-driven geometry demo of point names
Demo $\delta$: Sample space of points available from an array of rotational values

Using d3.js to Model the NYC Subway Map Independent of Physical Geometry

Thu, 12 Dec 2013 00:00:00 -0400

App	http://jbuckland.com/subway
Github	http://github.com/ambuc/subway

Here I attempted to render the NYC Subway system as a force-directed graph in d3.js. The purpose of a force-directed graph is to

position the nodes of a graph in two-dimensional or three-dimensional space so that all the edges are of more or less equal length and there are as few crossing edges as possible, by assigning forces among the set of edges and the set of nodes, based on their relative positions, and then using these forces either to simulate the motion of the edges and nodes or to minimize their energy.
~ Wikipedia

The subway data was entered manually, (doing the work by hand took less time and energy than its automation would have) and is rendered live in your browser. The hard part is finding a satisfying set of parameters for a clean display. Still, it’s fun to play around with.

Dimensional Analysis through Brute Force

Wed, 04 Dec 2013 00:00:00 -0400

App	http://jbuckland.com/moon
Github	http://github.com/ambuc/moon

WA dimensional analysis engine based on the SI Base/Derived Units. Uses input on the seven base units (mass, distance, time, electric current, temperature, luminous intensity, and amount of substance) to display many common derived units of measurement. Basically a unit calculator.

Designed and built by Julian and me.

Design and Manufacture of an Dodecahedral Planetarium Made of Laser-Cut Acrylic

Sat, 12 Jan 2013 00:00:00 -0400

When I first came to college, I had big plans to cover my room in glow-in-the-dark stars. It occurred to me upon arrival that my roommate might not be as crazy about the idea as I was.

During some research into low-cost cardboard construction methods, I stumbled across this picture of a press-fit geodesic dome, which was made at the MIT media lab, laser-cut from a sheet of cardboard. I realized that a smaller, simpler geometric shape could easily approximate the perfect sphere that a real planetarium could require.

I began by designing a sky map spread across twelve pentagons, to be folded into a dodecahedron shape. Using some simple geometry and Wolfram MathWorld, I found the dihedral angle necessary for the joining pieces. I got the star patterns off John Walker’s Fourmilab, and spread them by hand across the pentagons. (This should have been done geometrically via Mathematica, alas.)

I lasercut the patterns from a large piece of opaque blue acrylic, and cut the joiners from clear acrylic scrap. I discovered too late, as a planetarium, my project failed: I got too large of a lightbulb (I got a little excited at the Home Depot) and the focal length was totally wrong; the light shone out of the holes but would not project outwards onto the walls. With this in mind, I repurposed the planetarium into a hanging lamp.

Tolerancing Laser-cut Acrylic

Sat, 12 Jan 2013 00:00:00 -0400

While working at the Champaign-Urbana Community Fab Lab on a previous project, I discovered a sheet of opalescent acrylic. At first transparent, it became unpredictably multicolored when a light was shone through it. I decided it would make a brilliant lamp.

I designed the TARDIS in Illustrator, modeling its proportions after whatever photo references I could find. The edges are connected by well-toleranced finger joints, and the entire body, including the base, are constructed without any glue or sealant. The base was built using an LED, some resistors, and a single D-cell battery.

Design and Manufacture of an Orrery Made of Wood

Fri, 11 Jan 2013 00:00:00 -0400

While working at the Champaign-Urbana Community Fab Lab, I stumbled upon plans for a clock built entirely from wooden gears; the plans had been made in a previous decade, and were designed to be cut carefully by scroll saw. The possessor of the plans mentioned that the lasercutter was the perfect tool to create precision shapes such as gears.

I realized that a long-time fascination of mine, the orrery, would be the perfect project to attempt with this technology: it’s small but very extensible, requires some clever mathematics for gear ratios, and also involves a level of precision that my previous projects often lacked.

This project is still a work in progress: the following are pictures of my first draft of the tellurion portion, which only depicts the sun, moon, and earth. The current draft has a few flaws: although the frequencies of orbital ratios are accurate (3:40), the sun rotates (it shouldn’t), and the earth doesn’t (it should).

The gears were made using an online gear template generator, and the calculations were inspired by a 1938 paper by Charles E. Balleisen titled Revised Orrery Calculations, and aided by the American Scientist article On the Teeth of Wheels as well as an AMS article on Stern-Brocot trees.

The orrery in profile.

Another profile.

Top-down view.

Partially disassembled.

Close-up of Earth-Moon linkage.

Teeth failing to mesh.

Circuit Design and Programming of an Arduino Alarm Clock

Sat, 03 Nov 2012 00:00:00 -0400

Paper	Alarm Clock Automation

In my first semester as a Freshman at Illinois, I took IEFX Projects, an ENG 198 course focused on letting students work on their own self-assigned projects to completion.

This fully automated alarm clock, which I built with Chris Marry and Steve Hefferman as a final project for ENG 198: IEFX, can turn the rod on a set of venetian blinds to let in the sunlight in the morning. My responsibilities were to construct the circuit board and program an Arduino backend to mirror the functions of a real alarm clock.

Simulating Galactic Chemical Evolution in Python

Mon, 30 Jul 2012 00:00:00 -0400

Paper	On the Role of Viscous Transport in the Oxygen Abundance Gradient over Extended Galactic Disks

This is a report Catherine Hong and I compiled during the 2010-2011 academic year under the direction of Colin McNally, as a part of the NASA Science Research Mentoring Program at the American Museum of Natural History in NYC.

Abstract

Inspired by recent observations of radial abundance gradients in the extended HI disks of galaxies, we present a numerical model to address the role of viscous transport with regard to the oxygen distribution in extended galactic disks. The viscocity in our one-dimensional disk approximation is provided by turbulent motions of the interstellar medium. These motions mix oxygen and other metals throughout the gaseous component of the galaxy. Our model runs for 7-10 Gyr, with the galaxy attaining mass through infalling gas and forming stars based on the Schmidt-Kennicutt law. Through supernovae, these stars enrich their neighborhood of the galaxy with oxygen. Our model shows that viscous transport alone cannot account for the observed abundance of oxygen past the boundary of star formation in sample galaxies. These results argue in favor of the existence of another mechanism for the transport of oxygen.

Comprehensive Design and Thermodynamic Analysis of a Greenhouse

Thu, 01 Sep 2011 00:00:00 -0400

Paper	Comprehensive Design and Thermodynamic Analysis of a Greenhouse

Context

This is a report Michael Clark, Nick Jones, Chase Kauffman, Thomas Mayo-Smith, Cory Nissly, and I compiled in Summer 2011, as part of the Cornell Summer College program at Cornell Univeristy, in Ithaca, NY.

As part of the report, we performed a thorough economic analysis on potential locations, a small amount of construction rendering and CAD, a thermodynamic analysis of energy balance and thermal conductivity, and a model circuit.

Abstract

The recent discoveries involving carbon emissions and global warming have led to worldwide concern for more “green” ways of producing goods and energy; our team has been researching and conceptually designing a “green” greenhouse, to produce crops in an energy efficient and environmentally friendly manner. In a modern world, where capitalist democratic policies reign in most civilized countries, it is important to understand global concerns and to adapt business and production methods to what the world needs, collectively. In this, pursuing this “green” greenhouse was a legitimate business endeavor as well as an attempt to meet the world’s desires.

Since different geographical locations all have their respective crops, prices, and growing seasons, it was important to understand what the people wanted and where that product could be grown cheaply. Our team researched the prices of crops in different places, the prices of land in different countries, the efficiency of each location’s growing seasons, and many other factors of the business end of things. As a result of the geographical information that we reviewed, we decided that the best location for a greenhouse would be the Dominican Republic for its cheap land and climate stability. Our economic research into the construction and energy costs of a greenhouse yielded a very efficient rectangular model, designed to maximize sun time and climate stability on minimal energy usage and pollution. Our crop research showed that the most economically feasible crops were Garlic Chives, Cilantro, Spinach, Poinsetta, and Orchid. Given all of this information and the calculated results that constituted them, the T14 group has constructed a very comprehensive array of graphs and statistics, a physical scale-model of their future greenhouse, a detailed and very accurate computer aided design of the model to portray it for the public in a reasonable fashion.

The implications of this very well thought out design are that these ideas are completely feasible. It has overarching energy, economic, and environmental implications for the future that are relatively astounding. With the proper research, motivation, funding and willpower this new greenhouse just may be the future of crops and the water to douse the fire of global energy demands.

Lockpick

Thu, 01 Sep 2011 00:00:00 -0400

This post, and the programming it contains, were some of the first programming I ever did. As a result, they’re really quite bad. I include it for posterity, and because it’s funny.

The problem

In high school I used to use a Wordlock on my locker. It had four dials of ten letters each, and each ring rotated independently. Predictably, one summer I returned to school to find that I had forgotten my combination - one of a thousand possibilities.

But not probabilities. There were a few caveats. Most of the words that could have been formed (AEJX, WQRX) were unlikely. I had the advantage of knowing that I would have chosen a real word (MATH, OXEN) rather than a jumble of letters. I figured the 1000 possibilities could be narrowed down to just a few (~100) probabilities, and that a little scripting would do the trick.

`lockpick_combogen.py`

I had been learning just a little bit of Python over the summer and this challenge seemed like the very definition of a real-world application. It was combinatorics, arrays, recursion, and language analysis. I found the Enchant module for Python (although, in retrospect, just a simple check against wordlist.txt would have done the trick).

python


#!/usr/bin/env python
import numpy
import enchant
d = enchant.Dict("en_US")

After a standard preamble, I wanted to create a structure to approximate the physical structure of the rings on the real lock. My ring function took the alphabet and turned it from a straight string of characters into an array of string literals.

python


alphabet = 'abcdefghijklmnopqrstuvwxyz'
def ring(x):
y = []
for i in range(len(x)):
y.append(x[i])
return y

The four rings ran [k,t], [a-j], [u-z], and [k-t] again, respectively. I assigned four ring arrays using the ring function.

python


r1 = ring(alphabet)[10:20]
r2 = ring(alphabet)[0:10]
r3 = ring(alphabet)[20:30]
r4 = ring(alphabet)[10:20]

Then came the combinatorics. Using every possible combination of the four rings, I wanted to compile the string literals back into a word, check the word against a dictionary, and, if it was a real word, print it. Despite there being a thousand combinations, there were rarely more than about 50 words.

python


for i in range(len(r1)):
for j in range(len(r2)):
for k in range(len(r3)):
for l in range(len(r4)):
x = (r1[i])+(r2[j])+(r3[k])+(r4[l])
if d.check(x) == True:
print x

Using this method, I found my combination (NEXT) almost immediately from the list of twenty or so words, but the thought occurred to me: what if there had been fifty words to sift through? A hundred?

`lockpick_freqgen.py`

The next thing I did was to write a frequency generator. I compiled a few large, well-known texts off Project Gutenberg (the Declaration of Independence, Sherlock Holmes, Leaves of Grass, Huckleberry Finn, and Ulysses - that seemed to cover all my bases) and wrote a script to strip the text of punctuation, divide it by spaces into words, and create a table with each word and the number of times it appears in a good sampling of the english language.

python


# !/usr/bin/env python
import re, string, operator, pickle
regex = re.compile('[&#37;s]' &#37; re.escape(string.punctuation)) #regex rule
a = {} #frequencies dictionary
b = {} #output dictionary
temp = []
def strip(x): #strips a string of punctuation
for i in x:
temp.append(regex.sub('',i).lower())
return temp
# stages: plaintext to string to words
f = strip(open('/home/james/code/declaration.txt', 'r') .read().split(None))
for i in f:
a[i] = a.get(i,0) + 1
klist = sorted(a, key=a.get)
# write python dict to a file
output = open('frequencylist.pkl', 'wb')
pickle.dump(a, output)
output.close()

The script took nearly no time at all to run, and it gave me a pickl’d version of the dictionary class I could import later into another program without having to run lockpick_freqgen.py all over again. The next step was to take my list of candidates and reorder them by frequency.

`lockpick_sort.py`

Once the dictionary (not the Enchant english-language dictionary, the python-array-classification dictionary) was imported, every word in the candidates was checked against the array and sorted into a new list by frequency; words like this went to the top, and words like tank went to the bottom. I assumed (hopefully with some degree of accuracy) that the words most likely to be chosen for a word lock would fall somewhere near the middle-top; not too likely, but not seriously obscure either.

python


#!/usr/bin/env python
import pickle
pkl_file = open('frequencylist.pkl', 'rb')
list = pickle.load(pkl_file)
pkl_file.close()
candidates = {}
rejects = []
words = open('/home/james/code/words.txt', 'r').read().split(None)
for word in words:
if list.has_key(word) == True:
candidates[word] = list.get(word,0)
else: rejects.append(word)
candidates = sorted(candidates.items(), key=lambda(k,v):(v,k))
print "candidates:", candidates
print "rejects:" , rejects

Conclusion

The general workflow was to take the 1000 possibilities, reduce them down to far, far fewer probabilities, and sort them byfrequency in the hopes of finding the correct combination sooner than later. There were a few implicit assumptions, however:

That the combination would have meaning. (WQXR rather than XRQW)
That the combination would be a real word. (WOOT rather than WQXR)
That the word would be in the dictionary. (FORK rather than WOOT)
And then a final hope that the word would be a likely one.

As it turned out, the script worked nearly perfectly, running in under five seconds total and figuring out my combination nearly immediately. However, there were a few issues:

The scripts were written very early on during my Python learning curve, and are thus clunky. They do array manipulations that could have more easily been done with mapping or list comprehensions, they juggle strings and string literals, and they’re actually pretty slow. Compared to the far preferable grep-based solution, five seconds is abysmal.

They make assumptions. In a real cryptographic situation, this would be a last-ditch effort, hoping the password was truly password rather than p4s5w0r_d
The scripts were distributed. They did in three scripts what should have been just one. This is because I wasn’t sure of the exact terms and conditions of the problem I was working on, and I wasn’t confident enough to risk damaging the first step in the process to add the second step in the same script. There’s lots of juggling of text files and pickled dictionaries and the like.

To my further shame, I learned a few weeks later that regular expressions (of which I heard much but understood little) were designed to handle exactly these sorts of problems. With 20/20 hindsight, opening up a terminal and entering

shell


egrep "^[k-t][a-j][u-z][k-t]$" /usr/share/dict/words

would have done the trick about a million times faster, but that wasn’t the point, was it?