lukasschwab.me • blog

Spain Bibliography

2025-05-26T00:00:00Z

Spain Bibliography« blog 2025-05-26

Spain Bibliography

I spent two weeks in Spain and read these books along the way. The best texts are marked with ✷.

✷ The Spanish Labyrinth: Gerald Brenan. Published by Cambridge University Press, 1950. Library.

This was the clear highlight of my reading in Spain. Brenan — who lived in Spain from 1919 — offers deep background, centuries of background, for the Spanish Civil War. Though there are centuries of ideological division, the key thing to understand is the “agrarian question:” even in the early 20th century, Spain’s peasant farmers lived in bitter precarity. On the eve of the revolution, a bourgeois Republican government collapses because they can’t switfly redistribute the land. Their coalition bungles the election, which benefits the Falange and the Communists in turn; in the chaos of their contest, Franco rallies forces in Morocco and invades. The rest, as they say…

This summary omits everything impressive in the book. The War is just a motivating conclusion for Brenan’s general history of Spanish politics, an ancient mass of overlapping tensions.

Spain has a host of local nationalisms and national identities (most pronounced in Catalonia and the Basque Country). The agrarian question had distinct regional characteristics, thanks to regional conventions for landownership and leases. Spain also has unusually sharp differences between particular cities, thanks to an old royal tendency to grant monopolies — important industrial monopolies to Bilbao and Barcelona; a monopoly on early trade with the Americas to Sevilla — in addition to the natural concentration of political and military power in the capital, Madrid. There are universally recognizable class struggles, but even these are more nuanced. The agricultural worker is typically an anarchist, the industrial worker a syndicalist.

This web is further tangled by Madrid’s tendency to pit local factions against each other to weaken them. Memorably, Brenan argues Josep Dencàs — nominally a Catalan separatist and effectively a local breed of fascist — must have been an instrument of the ascendant Right in Madrid: why else would he disband his paramilitaries and escape to France via Barcelona sewer within ten hours of forcing a Catalan secession?

I put my money where my mouth is and bought a personal paper copy of this book, which will stand next to my Robert Caro biographies. I look forward to reading Brenan’s memoirs; apparently he once tried to walk to China.

✷ Cities of Spain: David Gilmour. Published by I.R. Dee, 1992. Library.

Gilmour’s introduction is important. Spain, he argues, doesn’t have a historically primary city the way France and England do; nor does it have historically independent city-states, as in Italy. The cities of Spain have distinct characters and specializations. Over the centuries, cultural and political hegemony shifted from place to place. Toledo is home to Church and Court until Phillip II moves to Madrid. Sevilla enjoyed a monopoly on American trade that was loosed by the shifting sands of the Guadalquivir. Córdoba was capital to the most developed civilization in Europe… then, suddenly, it wasn’t.

This system is ideal for travel book: you too will see Spain one city at a time. Gilmour’s depictions are a little romantic, but he roots the present vibe of a place in its historical development. If you need to convince someone who travels to “live like a local” that they should also care about history, Cities of Spain is a strong argument to that effect.

The book covers Toledo, Córdoba, Santiago de Compostela, Sevilla, Salamanca, Cádiz, Barcelona, San Sebastián, and Madrid.

One complaint: Gilmour overquotes the impressions of earlier British travelers, especially when they comment on the character of Spanish women. I’ll read his earlier book on Lebanon, but I hope it’s in a different style.

Blue Guide: Spain: Ian Robertson. Published by A & C Black, 1993. Library.

It’s hard to find a good travel guide. It isn’t a Schwab family vacation unless someone complains about how hard the Rough Guide series fell off. The universal teal-and-orange color schemes, smeared with full-color photos, scream “please steal my passport, I am hapless.”

The Blue Guide can’t fall off because it’s out of print. The Blue Guide, despite the name, is barely blue, and it has text instead of photos. Usually the text is small, but the “asides” are truly microscopic. The Blue Guide doesn’t say “shake me, take currency;” it says “do not talk to me; I am a vicious, unapologetic pedant.” (This is a joke: you will not meet anyone who recognizes the Blue Guide.)

Unfortunately, this book is organized for a tour by car (which I didn’t do). Also, because it predates your smartphone by several decades, its walking tours are described verbally, not mapped. This is a hopeless proposition in the most interesting neighborhoods — the oldest, and therefore the most mazelike.

Nonetheless, I was impressed! It’s nice to have a guide that’s dense and brainy. If I had thirty minutes on the train before the next Andalusian city, I spent those thirty minutes cramming the Blue Guide.

Find a copy of the Blue Guide if you’re interested in Spain’s churches. Harvey’s Cathedrals of Spain focuses strictly on the cathedrals, and only on their architecture; Robertson, with saintly patience, describes even the art and decorative details of relatively minor buildings. These interior walking tours (chapel by chapel) are indispensable justification for the €4 to €10 entry fee the Church just squeezes out of you at every entrance.

Finally, Robertson’s pithy city histories serve better as reference texts than do the chapters of Cities of Spain, and of course the Blue Guide histories cover Spanish cities more comprehensively.

The Cathedrals of Spain: John Hooper Harvey. Published by Hastings House, 1957. Library.

The young John Hooper Harvey was a prominent member of the Imperial Fascist League in the 1930s, a British political movement founded by a camel doctor because the nascent British Union of Fascists wasn’t, uh, fascist enough. This connection is mentioned on Harvey’s Wikipedia page and alongside his brief mention in Gothic Architecture in Spain (below), but neither describes the extent of his commitment, the viciousness of his writings, or the sheer fucking weirdness of his friends as clearly as Graham Macklin’s article, “The Two Lives of John Hooper Harvey.”¹

After the end of the Second World War, Harvey wrote prolifically on English architecture and history, especially of the late Middle Ages. His 1948 book The Plantagenets was widely used as a textbook, despite a passage repeating a blood libel and endorsing Edward I’s decision to expell all Jews from England in 1290. It seems there were minor controversies along the way, but Harvey enjoyed public respectability as a historian until his death in 1997. His fascist sympathies were widely publicized after his death.

The overt racism and nationalism espoused in Harvey’s early writings make him a strange author for any foreign architectural history. This is especially true in Spain, where so much historical architecture (and so much of what makes up its “national style”) is originally Islamic or Jewish. The Mosque-Cathedral of Córdoba is one clear example; any good walking tour of Toledo, through church and mosque and synagogue, is another. Spain was ruled by Franco’s fascist dictatorship when Harvey wrote the book; I can’t help but wonder if that made it subtly more appetizing.

Thankfully, The Cathedrals of Spain stands out in Harvey’s oeuvre for its even-handedness. Harvey is straightforwardly sympathetic to Spain’s Jews and mudéjar (those Muslims who stayed in Iberia after the Christian reconquest), and he credits the erstwhile Islamic government of Al-Andalus for its religious tolerance in comparison to the Catholic monarchs who ousted them. The editors of Gothic Architecture in Spain concede Harvey’s “prejudices,” at least, “do not surface clearly.” Macklin wonders if Harvey had “moderated his opinions” by the time he wrote this book. At the same time, be ideologically on guard — while his work to popularize an idea of Spanish “national style” here seems benign, his project to do the same for Britain (in other volumes) is more politically, and racially, tinged.

The book’s organization is ungainly. Buildings are described by region. Regional sections are apparently meant to be read through linearly, but then comparative references are scattered throughout. The index is thorough, but it’s a headache. Imagine a reader in the Catedral de Sevilla tries to read about that building; the index directs them, no joke, to pages 57, 58, 59, 102, 103, 183, 206, 217, 223, 227, 230–6, 239, 242, 260, 8, 120, and 146–8.² I think Harvey is writing for a popular rather than an academic audience (his callout of “Dr. Pevsner” suggests Harvey addresses a reader familiar with Pevsner’s Architectural Guides³), but he lands in awkward middle ground.

This book’s primary strength is its breakdown of the major, architectural elements — when a feature of a cathedral was built or rebuilt, by whom, and so on. Its secondary strength, in my opinion, is Harvey’s taste; I think he’s unfair to Zaragoza’s Catedral basílica (an “extraordinary pile,” in his words), but his groans about La Almudena in Madrid and the cathedral in Granada are apt.

The book’s primary weakness as a travel companion is its ignorance of art and interior details; for these, refer to the Blue Guide.

Interestingly, neither the Blue Guide nor The Spanish Labyrinth have anything nice to say about Antoni Gaudí’s Sagrada Familia in Barcelona, by now one of the main tourist attractions in Spain. (Cities of Spain, for its part, quotes Brenan.) I expected Harvey, archconservative as he is, to join their criticism; instead, he calls Gaudí “the most profound architectural genius of modern times,” and his masterwork “at once the culmination of the Spanish cathedral and the link which holds together its past and future.”

Ghosts of Spain: Travels Through a Country’s Hidden Past: Giles Tremlett. Published by Holtzbrinck, 2007. Library.

Tremlett’s memoirs as a foreign correspondent are most enthusiastic when he’s explaining some salacious aspect of “the Spanish character.” This tendency isn’t meanspirited, but it can feel condescending. Certain chapters are strong — the one on flamenco is heartfelt — and Tremlett is often genuinely funny, but this book, only loosely organized by locale, wasn’t useful to this traveler.

Gothic Architecture in Spain: Invention and Imitation: Ed. Tom Nickson and Nicola Jennings. Published by the Research Forum of The Courtauld Institute of Art, 2020. Available online.

This one is for the fanatics! Gothic Architecture in Spain is academic, not fun. If you’re interested, it rewards with references to some off-the-beaten-path structures (e.g Sevilla’s Atarazanas [shipyards], currently under restoration); good documentary photographs; and a documented picture of France’s stylistic influence.

I did not stop reading about Spain.

Impressed by Spanish Labyrinth, I skimmed Gerald Brenan’s memoirs (A Life of One’s Own and A Personal Record, 1920–1972) and some minor texts (Thoughts in a Dry Season). Unfortunately, the most memorable passage among these was the chapter recounting how, well into his thirties, he employed an illiterate 15 year old so he could ‘seduce’ her.⁴ Brenan only calls Juliana — the mother of his only child! — by her first name. I don’t detect much remorse.

I found ✷ Babel in Spain by John Haycraft because Brenan wrote its introduction. Haycraft’s reminiscences on two years spent teaching English with his wife in Córdoba are affectionate, even poetic. I read it cover to cover.

David Gilmour’s Lebanon: the Fractured Country is only a Spain book because it’s by one of my Spain authors. I would love to find a short book to recommend instead of Pity the Nation, Robert Fisk’s firsthand account of the Lebanese Civil War. Gilmour’s history is condensed, but it lacks intensity. Read Gilmour’s 1990 review of Pity the Nation, and then read that book instead.

The Blue Guide is dotted with quotes from Richard Ford’s three-kilo Handbook for Travelers in Spain (1845), so I schlepped those home from the library. Two things impressed. First, volume 1 describes a number of skeleton tours: given an interest, Ford provides a shortlist of cities and describes the major sites briefly. Second, Ford really writes. For example: when major Catholic services were still performed in Toledo, “then the vast space [of the Cathedral] was crowded with ant-like myriads, and the city of the sleeper awoke as by a touch of the wand, and filled its streets…”⁵

Rebels of the Rif by David Woolman describes the africanist colonial disaster at Anual in 1921, in which a small confederation of Berber tribes wrecked the Spanish army for three straight weeks, forcing King Alfonso XIII’s abdication in favor of a military dictator. Woolman paints with a little too much orientalist color at points, but he takes a real interest in the lives and motivations of Morocco’s rebel leaders. Read it for the biographies of Riasuli and Abd el-Krim.

Hemingway is unavoidable. I read most of Death in the Afternoon, his nonfiction guide to the Spanish bullfight. The Blue Guide calls this book a “dated curiosity,” but I really enjoyed the chapter on syphilis.

My friends will be relieved to hear I’m done reading about Spain for now.

Macklin, Graham. 2008. “The Two Lives of John Hooper Harvey.” Patterns of Prejudice 42 (2): 167–90. Macklin draws in particular on the MI5 record of Harvey’s correspondences within the Imperial Fascist League and with its outside supporters. There is, needless to say, a shocking volume of documented antisemitism. There’s also an episode in which Harvey dresses up in a “Robin Hood tunic with leather-belt, sandals, and brown tweed tights” and plays flute for a pretender to the crown of Poland.↩︎
If you bring Cathedrals of Spain, memorize the index key: “Numerals in italics indicate the principal references to buildings; those in heavy type refer to the figure numbers of the illustrations.” Unfortunately, the italic and regular typefaces in the 1957 edition are hard to discern.↩︎
See Cathedrals of Spain pages 241 (footnote) and 271.↩︎
A Personal Record, 1920–1972, from page 210.↩︎
A Handbook for Travelers in Spain, Vol. III, pages 1250–1251. A bonus for the rare footnote-reader: one of the skeleton tours is billed a “Tour for the Idler and Man of Pleasure.” These readers, Ford writes, should just go to Paris instead.↩︎

Gothic Micro-Architecture

2025-03-19T00:00:00Z

Gothic Micro-Architecture« blog 2025-03-19

Gothic Micro-Architecture

I want to highlight an architecture paper I enjoyed: François Bucher’s “Micro-Architecture as the ‘Idea’ of Gothic Theory and Style,” published 1976.¹ It’s short: just six pages, plus photos and notes.

Bucher’s opening paragraph warns of a “strange reversal of reference.” For many, ‘Gothic’ is all about the big stuff, the buildings — both our most visible relics of the Middle Ages and the main inspirations for later Gothic revivals. For Bucher, the buildings are formal precursors and a theoretical distractions. Gothic architecture, he says, really gets going in miniature.

Abbot Suger of St. Denis is often credited with more or less inventing Gothic architecture wholesale in his design of a light-filled ambulatory for the Basilica of St. Denis, just north of Paris, in 1140ce. Suger didn’t cut the stones himself, and the new pointy-arched style wasn’t without architectural precedent, but Suger had a rare instinct for self-promotion.²

The Abbot was also a magpie, deeply occupied with the treasures glittering in the light of his huge new windows. He’s oft credited with an “anagogic” philosophy of Gothic architecture, wherein the architecture is supposed to draw a worshiper’s attention towards the promise of a celestial architecture (“this church has the biggest windows I’ve ever seen; I bet the windows in heaven will blow my mind!”). According to the Bucher paper, Suger’s early-Gothic anagogy is more correctly a philosophy about small objects — “gee, that’s the biggest opal I’ve ever seen…” — than about the pointy arches and flying buttresses of the Basilica. Art historian Erwin Panofsky is more insistent: the close association between Suger’s architecture and his anagogy is a popularized “misreading.” “In reality,” Panofsky writes, Suger’s most famous passage on anagogy “describes only the trancelike state induced by the intense contemplation of lustrous pearls and precious stones.”³

In spite of this original emphasis on the miniature — those “pearls and precious stones” on the high altar at St. Denis — the Gothic style develops, through the early and high Gothic periods, into 12th century mega-architecture (“megalomania” or “Gothic gigantism” in Bucher’s words). These are the huge projects most popularly associated with the Gothic: Notre Dame de Paris, Chartres, Amiens, and so on, grand demonstrations of the spiritual primacy of the Church and the earthly hegemony of their patrons. As their constructions become technically ultra-sophisticated — ever lighter, ever thinner, with more sculptural vaulting and more tenuous statics — the master-builders grow powerful in their own right. Consolidating the disbursement of artistic patronage, these architects begin “to impose their aesthetic vocabulary upon the world of reliquaries, stalls, fonts, pulpits, tombs, etc.,” the world of what Bucher terms “micro-architecture.”⁴

In the mid-13th century, the micro-architecture surpasses the macro. Small elements like screens and lecterns flower into “magnificently abstract works of refined architecture.” Bucher describes what I’d call simulacrum-architecture at small scale: sacred objects constructed from the same basic tenets as a Gothic building, but modeling a building that would be materially impossible (either because of its insane extrapolated scale or a fineness unachievable in iron-reinforced stone).

At around the same time, macro-architecture encounters material impossibility. The 47.5m-high vault of Beauvais Cathedral — still absolutely mind-numbing today, the highest Gothic choir in the world — collapses in 1284. The 1300s ce turn out to be a hard century for grand projects in western Europe, years dotted with power struggle, feudal war, plague, financial collapse, and popular rebellion. Patronage gets smaller, and architecture with it. Already-refined micro-architectural elements replace buildings as the main focus; projects emphasize “enrichment of details, sophisticated treatment of materials, and daring designs.” Gothic macro-architecture collapses in on itself, folds over into something “marvelously prickly […] the seeming disarray of ever more complex cantilevering, branchwork, double curved and utterly surrealistic ribs and bent finials.”

Bucher argues it’s this micro-architecture of the late middle ages that best exemplify the Gothic aesthetic rationale, something “detached [from] exacting architectural discipline,” a style “gloriously deranged.” If you believe Panofsky’s reading of Abbot Suger — that the exegetic power he saw in St. Denis lay in its treasures, not in its building — this derangement-in-miniature closes the loop. The Gothic architects gave light to sacred objects, then increasingly gave them form; finally, at the end of the middle ages, Gothic openwork is the exegetic expression of Suger’s glittering vision.

Consider the original inscription of St. Denis’s portal:⁵

Whoever thou art, if thou seekest to extoll the glory of these doors,
Marvel not at the gold and the expense but at the craftsmanship of the work.
Bright is the noble work; but, being nobly bright, the work
Should brighten the minds, so that they may travel, through the true lights,
To the True Light where Christ is the true door.
In what manner it be inherent in this world the golden door defines:
The dull mind rises to truth through that which is material
And, in seeing this light, is resurrected from its former submersion.

Bucher, François. “Micro-Architecture as the ‘Idea’ of Gothic Theory and Style.” Gesta 15, no. 1/2 (1976): 71–89. DOI 10.2307/766753. Available online.
The uncited quotations in the body of this post are all from this paper.↩︎
Suger’s writings describe how often his name was recorded on — physically engraved into! — the Basilica of St. Denis. His likeness appears in at least two of the stained glass windows, in the central tympanum above the main entrance, and on the monumental bronze doors.
Suger’s writings served as defenses of his projects at St. Denis — think “medieval subtweets” — and drew correspondences between certain aesthetic priorities in Gothic architecture (e.g. the emphasis on light) and religious principles, like the anagogic relationship discussed here. Whether or not he invented it, Suger gathered the Gothic style together and wrote it all down. He is unavoidable.↩︎
Panofsky, Erwin and Gerda Panofsky-Soergel. Abbot Suger on the Abbey Church of St. Denis and Its Art Treasures: Second Edition. United Kingdom: Princeton University Press, 1979. Page 191. Emphasis mine.
Beware: my description of anagogy is extremely shallow. It’s a complex concept both in the mystical Sugerian meaning and as a mode of scriptural exegesis. Ask your theologian if anagogy is right for you.↩︎
I’ll confess a doubt: this is an underdeveloped point in Bucher’s argument. It’s entirely plausible that cathedral architects, as intermediaries between patrons and the masses of artists involved in a construction, leveraged their control of funding into direct aesthetic control over their sculptors, woodworkers, and so on (“the traditional wish of architects — including Wright, Le Corbusier, Mies, and so on…”). The simple emergence of architectural motifs in Gothic sculpture is not enough to prove that dynamic. Maybe there’s stronger evidence in annals of cathedral construction somewhere.↩︎
Panofsky, Erwin and Gerda Panofsky-Soergel. Abbot Suger on the Abbey Church of St. Denis and Its Art Treasures: Second Edition. United Kingdom: Princeton University Press, 1979. Page 47, translated from Suger’s “Liber De Rebus In Administratione Sua Gestis.”↩︎

Bring Your Own Linter

2025-03-09T00:00:00Z

Bring Your Own Linter« blog 2025-03-09

Bring Your Own Linter

This is a practical guide for integrating a custom linter into your Go project.

The first two sections briefly describe writing and running a custom linter — a single, atomic rule you want to enforce.
The third section describes using your custom linter with Go’s most common metalinter, golangci-lint: at the command line, in your editor, and in your continuous integration environment (CI).

Finally, this is a rant about tool complexity and my defense of a simpler Go metalinter: glint.

Write a custom linter: `analysis`

The golang.org/x/tools/go/analysis package is the rich soil to Go’s linter ecosystem. A simple linter typically defines an analysis.Analyzer — or, for a complex linter, a graph of several mutually dependent Analyzers — that passes over files line-by-line and publishes diagnostics about them. The package’s published overview is short and very clear; if you want to write or debug lint rule, go read that overview.

nilinterface defines a single Analyzer without any dependencies: it inspects each node in each file’s AST, and uses pass.Reportf to alert if any given node is the literal nil and serving as an interface-typed argument to a function.

Note where the Analyzer is defined: in its own package, pkg/analyzer. All the code therein is strictly independent of what tools you use to run the analysis (whether a standalone command-line binary or a metalinter like golangci-lint); the package naturally separates concerns between the analysis itself and the means of invoking it.

The analysistest subpackage lets you test your Analyzer by feeding it real code samples, with expected diagnostics as inline code comments, from a testdata directory. See analyzer_test.go for an example.

One tip: LLM code generation is really useful for writing Analyzers, so long as you can precisely describe the linter behavior you want. Let the AI massage the polymorphic AST types so you can focus on the specific diagnostic conditions. Test-driven development works well here: write your analysistest examples (start with true-positive cases, issues you want the linter to detect) so you can validate the AI-generated contributions.

Build a standalone linter; run it

The simplest means of invoking an analysis.Analyzer is to build it into a standalone binary you can run from the command-line. The analysis package kindly provides a one-liner utility for that: just create a package main and call singlechecker.Main.

package main

import (
    "github.com/lukasschwab/nilinterface/pkg/analyzer"

    "golang.org/x/tools/go/analysis/singlechecker"
)

// main is an entry-point for running the nilinterface analyzer as a standalone
// binary. The analyzer process exposed by [singlechecker.Main] is additionally
// compatible with `go vet -vettool`.
func main() {
    singlechecker.Main(analyzer.Analyzer)
}

Congratulations! Before, you just had an analyzer; now you have a linter. You can install this main package and run it like you would any other command-line tool:

go install github.com/lukasschwab/nilinterface/cmd/nilinterface@latest
nilinterface --help
nilinterface ./...

Moreover, this singlechecker.Main command line interface is compatible with go vet:

go vet --vettool=$(which nilinterface) ./...

This is comfortable enough for one or two custom rules, but building and invoking so many individual binaries is tedious for a complex project. That’s where metalinters like golangci-lint come in: they coordinate a mass of smaller linters. Perhaps you’re already using golangci-lint for the bundle of linters it provides out of the box. How do you incorporate your custom linter into that bundle?

Customize `golangci-lint`

First, a rant. The amount of space dedicated to golangci-lint in this article is not to that project’s credit.

Before this weekend, I naturally conceived of metalinters as coordinators in an ecosystem of lightweight modular linters. That’s not quite right. golangci-lint, out of the box, is a gatekept¹ fixed set of linters, baked into the tool at build time. Your massive .golangci.yml config? That’s not adding anything new — just picking rules from among what golangci-lint sees fit to offer.

Its list of linters belies an uncomfortable but inevitable tension. On one hand, there’s pressure to keep the list short: each linter makes the golangci-lint executable bigger; each one enabled by default makes it slower by default; linting with too many rules is unhelpful; and extending the list, especially with redundant options, makes selecting linters tedious. On the other hand, there’s reason to keep extending the list: there are lots of conceivably useful lint rules to provide.

The individual linters yield to this tension by being over-capable and configurable (i.e. non-atomic). Some (e.g. revive and staticcheck) are practically metalinters in their own right. These complex linters have complex configuration spaces — making them work for your project’s particular needs requires wading into the ls .*.yml mire you try not to think about.²

The solution to this tension is proper modularity among atomic linters with minimal configurability. The only thing in your way is the trickiness of golangci-lint’s plugins system. It works — more below — but with rough docs and scant examples. It’s opaque.

The first thing to understand is that golangci-lint documents two different plugin systems: there’s the new module plugin system,³ which I’ll use here, and an older “Go plugin” system based on using cgo to compile linters as *.so files. Many custom-linter discussions online don’t explicitly specify one or the other; often, these are discussions about the Go plugin system because it came first.

If one red herring wasn’t enough, the module plugin system suggests there are two ways to add custom linters: “The Automatic Way” and “The Manual Way.” These are two ways to do the same thing: build a custom golangci-lint binary with some additional linters rolled in. You don’t need to learn them both. The “automatic way” specifies the new linters in a YAML file, then uses a build tool included in golangci-lint to integrate them; the “manual way” has you explicitly clone, modify, and build golangci-lint from source. I’ll use the “automatic way.”

There are tens of thousands of public GitHub repositories using golangci-lint; at time of writing, only 34 of them customize it with module plugins.

Adapt your `Analyzer`

golangci-lint doesn’t integrate with Analyzers directly, or through some analysis-provided interface. It needs to pass on the linter’s share of YAML settings, and it needs to understand what information about a program the linter analyzes.

It does both through a registration pattern defined in golangci/plugin-module-register.

Wrap your analyzer to implement the interface register.LinterPlugin.
In practice, you want to return one of the two string constants in register. There’s scant documentation on the difference between LoadModeSyntax and LoadModeTypesInfo — analyzers with LoadModeTypesInfo receive strictly more data, but may run a little slower.⁴ If you provide any other string, golangci-lint defaults to the data-rich mode.
Define a factory function (this type is confusingly named NewPlugin) that receives untyped configuration from .golangci.yml and returns the LinterPlugin defined in step 1.
Define an init function that calls register.Plugin to register the factory function defined in step 2.

I won’t get into the implementation details — for an atomic linter without configuration variables, this adapter package should be short and the logic largely reusable between linters. Here’s the adapter for nilinterface; I isolated all the golangci-specific logic in its own package so it doesn’t muddle the analysis.

Build the linter binary

At this point you can shift your focus from linter to lintee — the project you’re checking with golangci-lint. If you’re content without customization, linting this project is simple: you go install a command line tool, optionally provide it a configuration file, and you’re off to the races.

Using golangci-lint without plugins: provide it a YAML configuration (conventionally in .golangci.yml) when you analyze your code.

The “fixed set of linters” available in this installation are actually baked into the installed executable. Even if you haven’t enabled tagliatele, for example, it’s lurking in there somewhere.

Your new custom linter, unfortunately, is not — at least not until the maintainer accepts a PR adding it. The clever idea behind golangci’s module plugin system is that the linter executable you installed also includes a build tool, golangci-lint custom, for building another version of itself from scratch, with additional Go modules — Go modules that register LinterPlugins — rolled in!

Using golangci-lint with plugins (“The Automatic Way”) adds a build step: run golangci-lint custom -v to build a custom version of golangci-lint, then provide configuration to that binary to analyze your code. The custom-gcl tool is interchangeable with golangci-lint; it just has your custom linter baked in!

You define custom modules in the .custom-gcl.yml file, distinct and upstream from the familiar .golangci.yml file. Running the build tool yields a custom linter binary, which itself reads configuration from .golangci.yml like golangci-lint did before.

Don’t worry, this is nondestructive: the original golangci-lint executable you installed is retained unchanged. If you want to rip out custom linting, you can delete custom-gcl and .custom-gcl.yml and you’re back to the way things were.

For example, here’s a configuration file for a version of golangci-lint with nilinterface:

version: v1.63.4
plugins:
  - module: 'github.com/lukasschwab/nilinterface'
    import: 'github.com/lukasschwab/nilinterface/pkg/golangci-linter'
    version: v0.0.6

The module field defines a Go module, the same way you would import it in a go file. import identifies a package inside that module, the adapter package described above (see “Adapt your Analyzer”). You could include several custom linters by defining plugins beyond this one.

Running custom-gcl is exactly the same as running bog-standard golangci-lint: the command-line interface and YAML settings are the same. Keep in mind, baking a linter into golangci-lint doesn’t mean it’ll run by default; you may need to update .golangci.yml to explicitly enable it. Using nilinterface as an example:

# This example file is grossly simplified.
linters-settings:
  custom:
    nilinterface:
      type: 'module'
      description: 'forbids passing `nil` as an interface argument to function calls'

# If you have `disable-all: true`, add nilinterface to your enabled linters.
linters:
  disable-all: true
  enable:
    - nilinterface

With the preceding changes to our YAML files, we can go from a clean golangci-lint to our custom analysis with this pair of shell commands:

golangci-lint custom -v
./custom-gcl run ./...

The first command, the build step, is way too slow to run every time you need to lint your project. golangci-lint custom downloads and builds golangci-lint from source — not a fast process. Of course, it doesn’t make sense to commit a binary built for your system into shared source control either… so sometimes you’re gonna have to suck it up and rebuild the thing.

Thankfully, you only need to rebuild this custom linter binary when you change .custom-gcl.yml. Makefiles are great for conditioning builds on file changes, and lazily building only what’s definitely necessary. If you define targets in your project Makefile like so —

.PHONY: lint
lint: custom-gcl
    ./custom-gcl run

custom-gcl: .custom-gcl.yml
    golangci-lint custom -v

— you can run make lint in lieu of the pair of shell commands above. The slow golangci-lint custom process will only run when custom-gcl (the executable it builds) is out of date.

Custom `golangci-lint` in VS Code

There’s a silver lining to building a drop-in replacement for golangci-lint: tools that integrate tightly with golangci-lint can integrate tightly with your custom-gcl instead. If you use VS Code, specify it as an alternate lint tool to see your custom linter applied in the editor:

{
  "go.lintTool": "golangci-lint",
  "go.alternateTools": {
    "golangci-lint": "${workspaceFolder}/custom-gcl"
  }
}

${workspaceFolder} dynamically evaluates to your current VS Code workspace. If you’re sharing a single linter across several workspaces, specify the binary’s absolute path instead.

Custom `golangci-lint` in GitHub Actions

The golangci-lint team maintains an official GitHub Action for running their linter, but it has no support for custom linter modules as I write this: it’ll use your .golangci.yml, but totally ignore the custom linters pinned in .custom-gcl.yml.

I built an alternative: golangci-lint-custom-plugins-action should tide you over until the official Action supports the same. This alternative Action follows the steps diagrammed above: download golangci-lint, use it to build a customized version of itself, then run that customized version. Like the official Action, this one persists linter binaries and caches to save time.

Getting back to basics

The foregoing complexity stems from an unforced but fundamental aspect of golangci-lint’s design: the decision to ship a binary, not a library, customizable through a baroque system of configuration files rather than as code. The underlying code here, the analyzers themselves, have reasonable APIs with unambiguous documentation.

Consider the problem of determining whether a linter config is valid. To ship a closed binary, golangci-lint reads configuration from a file — typically .golangci.yml — with no application-specific types. This is a big declarative hullaballoo for a process that, when you configure an Analyzer imperatively in Go, is entirely guaranteed by the type system.

We can — and should — return our focus from the tool to the code. We should consider custom extensibility a first-class priority in a metalinter.

You should be able to set up a linter to your Go project by adding a standalone cmd/lint/main.go “metalinter” program:

Explicitly imports and constructs only the analyzers you want to run, using their exported types to configure them.
Runs those analyzers as a group, outputting their diagnostics for consumption by other tools.

Why are we all still using golangci-lint?

The most important answer is performance, and the most significant factor is golangci-lint’s cache: if a package hasn’t changed, neither have the lint results. The metalinter stores per-package results indexed by hashes of the package contents. Luckily, there’s nothing really special going on: golangci-lint forks the native Go build cache and wraps it in package-hashing logic.

Less importantly, golangci-lint has a first-movers advantage: it filled the vacuum left by go lint’s 2020 deprecation, and Go engineers have been building (and squabbling over) its gatekept linter-set ever since.

An experimental metalinter: `glint`

In glint, I’m solving those problems for myself. That project aims to provide a minimal harness for running sets of analyzers defined in Go, with

Very simple customization
Reasonable performance
Reasonable compatibility with CI environments and editors
No registration requirements; just the analysis.Analyzer type

Focusing on analysis.Analyzer means drop-in compatibility with the major golangci-lint linters: pkg/golangci describes them, and cmd/glint demos wrapping them in the harness.

Adding a custom linter is a matter of defining an analyzer and adding it to the list passed to glint.Main. These programs work with VS Code and go vet -vettool, and yield annotations in GitHub Actions.

Why use glint over analysis/multichecker?: multichecker is the package Go ships to help you solve this metalinter problem: “[t]his package makes it easy for anyone to build an analysis tool containing just the analyzers they need.”; Unfortunately, analysis/multichecker emits diagnostics to os.Stderr, which VS Code takes as an indication the lint run is erroring rather than revealing issues. Its public API also isn’t easy to extend — it calls os.Exit and depends on a complex group of internal packages.
What’s next for glint?: Improved performance with caching, especially for incremental runs on large project (near-instantaneous for golangci-lint).; Storing go vet results in the Go build cache and stressing usage with go vet -vettool is an interesting idea, but might require new workarounds for use with VS Code.

References

Reference	Description
`analysis`	Go’s static analysis builtins: `Analyzer`, `singlechecker`, etc. Strong docs.
`nilinterface`	A model custom linter.
`golangci-lint-custom-plugins-action`	GitHub Action for building, caching, and running `golangci-lint` with a custom linter.
`tiir`@5fe5d30	Diff upgrading a project from standard `golangci-lint` to a custom `golangci-lint`.
`glint`	An experimental Go-defined metalinter.

See e.g. the maintainer’s categorical prohibition of warning-style linters like nilaway.↩︎
And it is usually YAML. The docs say you can opt for TOML or JSON; few public projects on GitHub actually do:
Filename Count on GitHub, Feb. 2025
.golangci.yml 27,700
.golangci.yaml 6,600
.golangci.toml 624
.golangci.json 200
The golangci-lint examples are all provided in YAML, of course.↩︎
The new module plugin system, introduced March 2024, mimics a pattern introduced by the Go webserver project caddy. The older Go plugins seem prohibitively awkward.↩︎
The golangci-lint issues include discussions of the impact of load modes: here are graphs of the different linter runtimes.
These are proxy values for packages.LoadMode settings, which determine what information about a package is loaded for analysis. Performance suffers if you load unused data.↩︎

Deriving Safe ID Types in Go

2025-02-01T00:00:00Z

Deriving Safe ID Types in Go« blog 2025-02-01

Deriving Safe ID Types in Go

This is entirely my advice, but I realized it while contracting for Alpaca —
special thanks to that team for their patience and good ideas.

Suppose you’re applying Safety Through Incompatibility in Widget Corp.’s widget fulfillment system. You want compile-time incompatible ID types for different collections, but you don’t have the luxury of starting from scratch: Widget Corp made the sensible¹ decision to use random UUIDs for all their canonical identifiers years ago, and has thousands of those identifiers in the wild. What’s the lightest-touch way to bring that living system up to speed?

Whereas my post on “Safety Through Incompatibility” was largely language-agnostic, this one will focus on a language-specific example: switching to UUID-based typed IDs in Go, using Google’s uuid.UUID. There are several ways to do the same thing — or so it seems — and I found scant guidance online on how to choose between them!

Assumptions

You already use UUIDs as IDs. You generate IDs for new records, but also exchange records with the outside world: customers order widgets through a JSON API, and you record widget IDs in your logs for debugging and accounting. Thus, in addition to the intrinsic safety of type incompatibility (that a Widget ID be unusable where an Order ID is needed), you want three things from your ID type:

In JSON, your IDs should json.Marshal to the standard UUID format: a hexadecimal JSON string like "f3f2e850-b5d4-11ef-ac7e-96584d5248b2".
They should have the same format in your plaintext logs.²
json.Unmarshal should extract IDs from the same format, e.g. when you parse an API request body.

I capture these requirements in this file of tests.

Defining a new `string` type

If you’re using raw strings to represent your UUID IDs, switching to a new type defined by string is dead-simple: serialization works out of the box.

type ID string

Update the places you construct IDs — something like widget.ID(uuid.New().String()) — and boom, the widget fulfillment system has a dedicated widget ID type.

The downside is a different aspect of ID safety: not incompatibility, but validity. You might be really confident all your IDs are UUIDs, but (as for the raw string type you started with) there’s no type guarantee they always will be. Maybe you have a test that pretends "MY-PET-ID" is a valid UUID. Maybe you’ll get nonsense data over the wire. You can call uuid.Parse to validate your strings, but that’s a secondary process — you have to remember to do it — and one you can’t quite push to the system boundary.

It’s easier to call a spade a spade: just use uuid.UUID for UUIDs.

Embedding `uuid.UUID`

type ID struct { uuid.UUID }

This exemplifies a Go technique called Struct Embedding. ID is a struct — Go’s basic composite data type — with a single, anonymous component: a UUID.

Like aliasing string, serialization just works. Unlike aliasing string, UUID validity is enforced at the system edge: json.Unmarshal will error if you provide a string that’s too long, or too short, or includes UUID-incompatible characters.

To tell you the truth, my problems with a struct-embedding ID like this are all nitpicky. For one, the underlying uuid.UUID is a public field; you can access it (e.g. access widgetID.UUID). Strictly speaking, that kind of conversion back into a uuid.UUID is possible for all the approaches I describe here, but it’s a conversion to generally discourage: it’s a leaky abstraction, and it allows comparing incompatible UUID-derived IDs as if they were plain uuid.UUIDs. Why dangle a public field if you don’t want anyone to use it?

Moreover — and this is really a matter of taste — the construction ID{uuid.New()} just feels wrong. Are there more (unset) fields in the ID struct? Single-field struct embedding uses a nonatomic composite data type to represent a conceptually atomic identifier.

Defining a new `uuid.UUID` type

type ID uuid.UUID

Like the type ID string declaration considered earlier, type definition creates a wholly new type — ID — with the same memory layout as uuid.UUID. In fact, uuid.UUID itself is defined through a construction like this: type uuid.UUID [16]byte. Unlike in a public struct-embedding, the underlying type isn’t exposed.

The main draback here is the serialization. Out of the box, this thing serializes like a [16]byte: expect JSON like "[243,242,232,80,181,212,17,239,172,126,150,88,77,82,72,178]" instead of anything recognizable.

You solve this by explicitly reimplementing some common single-method interfaces already implemented by uuid.UUID, essentially by invoking those UUID implementations.

func (id ID) String() string { ... }: Implements fmt.Stringer.
func (id ID) MarshalJSON() ([]byte, error) { ... }: Implements json.Marshaler.
func (id *ID) UnmarshalJSON(data []byte) error { ... }: Implements json.Unmarshaler.; This implementation may be a little tricky for new Go programmers: you have to cast the pointer id without dereferencing it. Here’s my implementation.

These implementations take a little more effort on your part to make this approach pass the tests, and the implementations themselves are dense little typesystem tongue-twisters. Defining a new uuid.UUID type is less sloppy than struct embedding, but maybe we can find something less verbose?

Aliasing `uuid.UUID`

type ID = uuid.UUID

There’s a subtle difference between declaring a new type using another — as in the type ID uuid.UUID example above — and aliasing a type in Go. Syntactically, the difference is small: the = in the alias declaration. In practice, the difference is much bigger.

An aliased type (ID) preserves the receiver methods defined on the original type (uuid.UUID)! In this case, that includes the existing standard interface implementations MarshalJSON, UnmarshalJSON, and String Google ships. Not only does aliasing uuid.UUID give you built-in validation (unlike defining a new string type); it doesn’t expose a misleading inner field (unlike struct-embedding uuid.UUID); and it serializes as expected out of the box (unlike defining a new uuid.UUID type) because it automatically implements the necessary interfaces!

Where’s the catch? Spot it in this passage from the Go Blog’s intro to alias declarations:

In contrast to a regular type definition
type T T0
which declares a new type that is never identical to the type on the right-hand side of the declaration, an alias declaration
type A = T  // the "=" indicates an alias declaration
declares only a new name A for the type on the right-hand side: here, A and T denote the same and thus identical type T.
Alias declarations make it possible to provide a new name (in a new package!) for a given type while retaining type identity:
package pkg2

import "path/to/pkg1"

type T = pkg1.T
The type name has changed from pkg1.T to pkg2.T but values of type pkg2.T have the same type as variables of type pkg1.T.

In simpler terms, a type alias is not a new type — it’s entirely compatible with the old one, and with other aliases of the same original type. Remember the original mission: safety through incompatibility! If you can interchange your widget.IDs and order.IDs, you haven’t made anything safer.

Summary

I introduced these approaches naïvely as four equivalent options. Divide them instead into two groups: the first, a group of one, is built on fundamentally the wrong type (string); the other options, based on uuid.UUID, have more promise.

The type alias is fool’s gold: it’s syntactically minimal and it passes our tests, but it doesn’t prevent interoperability.

Prefer one of the remaining two. If you’re pressed for time or worried about introducing something that looks complex, the struct embedding is a minimal drop-in replacement for raw strings.

In a mature codebase, I prefer defining a new uuid.UUID type (type ID uuid.UUID) and implementing the serialization interfaces yourself. These are verbose, but you can copy-paste my implementations for starters. You might also take advantage of the custom implementations — to prefix your logged UUIDs with a type identifier, say, so widget f3f2e850-b5d4-11ef-ac7e-96584d5248b2 appears more unambiguously as Widget_f3f2e850-b5d4-11ef-ac7e-96584d5248b2.

Approach	Pros	Cons
Defining a new `string` type: `type ID string`	Passes tests out of the box	No protections against non-UUID values
Embedding `uuid.UUID`: `type ID struct { uuid.UUID }`	Non-UUID values are impossible Passes tests out of the box	Exposes the embedded `uuid.UUID` implementation
Defining a new `uuid.UUID` type: `type ID uuid.UUID`	Non-UUID values are impossible	Must reimplement `json.Marshaler`, `json.Unmarshaler`, and `fmt.Stringer`
Aliasing `uuid.UUID`: `type ID = uuid.UUID`	Non-UUID values are impossible Passes tests out of the box	Dangerous compatibility!

You can find implementations and tests for all the approaches described here on GitHub. The root testfile demonstrates each solution satisfies the serialization properties; swap widget imports to run the same tests against each. Two more parts to note:

uuid_alias_test.go demonstrates the type-compatibility — and, therefore, the danger — of true type-aliased IDs.
pkg/generic_uuid_type is a generic adaptation of the verbose type ID uuid.UUID approach I prefer. It implements the interfaces once (the generic T provides incompatibility) for any number of collections.

In Defense of New Boggle

2025-01-18T00:00:00Z

In Defense of New Boggle« blog 2025-01-18

In Defense of New Boggle

They literally don’t make Boggle like they used to.

The words you can spell in a Boggle game depend on the letters on 16 dice rolled into a four-by-four grid. The letters on the dice are carefully selected — like in Scrabble, common letters like E and A appear more often than uncommon ones like V or the QU ligature. In fact, depending on when your English-language game of Boggle was manufactured, you have one of two sets of dice.

The “Classic Boggle” set, produced from 1976 to 1986.
The “New Boggle” set, produced from 1987 to today.

There’s scant info about the 1986 redesign online — none from the designers themselves — but notably New Boggle makes letters F and K mutually exclusive, rendering FUCK unplayable.¹ This blog post by ‘Bananagrammer’ describes the differences between the dice sets in detail.

Dice set Average # of words Average Boggle score Average length of longest word
New Boggle ~104 ~150 6.8
Classic Boggle ~93 ~128 6.6
[…] Of course, these calculations only confirmed what I already knew: the older version of the game is harder and is the one for me. I bought a copy of classic Boggle from eBay. The dice are made of wood rather than plastic. The timer has sand in it and doesn’t make some noise to tell me when time is up. Succinctly, I think it is skookum.

Dice set	Average # of words	Average Boggle score	Average length of longest word
New Boggle	~104	~150	6.8
Classic Boggle	~93	~128	6.6

I think Bananagrammer got this wrong.

The fun in Boggle isn’t really in the score — it’s in the words themselves: quality over quantity, style points, that kind of thing. A good evening of New Boggle yields higher per-board word counts, but how does it affect the diversity of play?

Dictionaries

A set of Boggle dice sets certain hard constraints on word formation. Each dice set contains a single Z; kiss JAZZ goodbye. Moreover, letters that share die are mutually constraining, since only one side of a given die affects any given game. Classic Boggle’s only QU and only J are on the same die, so JERQUE is impossible (just like FUCK in New Boggle). You can speak of a given die set’s “dictionary;” start with a standard dictionary (CSW19) and filter out the categorically unplayable words.

Classic Boggle has a substantially larger dictionary: 276,339 playable words, 14,536 more than New Boggle. A full 5.3% of the Classic dictionary is unplayable today! Only 127 words are uniquely playable in New Boggle.

At this juncture, it seems like Bananagrammer has a point: New Boggle gives you more words per game on average, in a smaller (dumbed-down??) dictionary.

Same-games

Let’s return to the question: diversity of play. A comparison between Classic and New Boggle should consider typical boards, not theoretical maximum dictionaries. Vanishingly few games of Classic Boggle admit 15-letter UNDEREMPLOYMENT; its 1987 exclusion barely impacts the game’s diversity in practice. A good set of dice don’t just admit a large theoretical dictionary of words, but also provide difference game-to-game. A good set of dice yields Boggle games that aren’t samey.

Suppose you play 10 games of Classic or New Boggle in an evening. How many unique words can you actually find across those games?

Classic and New Boggle have similar diversity of words discoverable in ten-game sessions. New Boggle is somewhat more diverse.

By this criterion, there really isn’t a reason to prefer Classic Boggle over New Boggle. While it has a substantially larger dictionary, Classic Boggle offers fewer words per game — Bananagrammer’s preference, but not mine — and offers only a modest difference in the variety of words actually encountered game-to-game.²

Play and Experimentation

The Boggle solver I wrote for these experiments ships with a terminal interface for solitaire games with my house rules.³ You can play a hosted game by running ssh boggle.fly.dev, or install the game from source:

go install github.com/lukasschwab/boggle@latest

Games look like this:

$ boggle
0/50 • 2m41s • bGNsbmFuYnVhYXBoc3Jsbg==
┌──────────────┐
│  l  c  l  n  │
│  a  n  b  u  │
│  a  a  p  h  │
│  s  r  l  n  │
└──────────────┘
> club|
[enter] submit word • [ctrl+c] quit

You can play with either dice set — see boggle --help. See the experiments branch (especially the cmd directories) to reproduce the results in this post.

If you’re interested in Boggle solvers, implement one yourself! This was a good data-structures exercise, and tweaking the game’s parameters . Curious about optimization problems across Boggle boards, e.g. a search for the Boggle board with the greatest number of findable words? Read Dan Vanderkam’s “What up with Boggle” series.

Dan Lewis speculates FUCK motivated the 1986 redesign here and, more directly, here. I’m skeptical. Only 1,572 of the ~14,700 words lost contain both F and K. If the only goal of the redesign were to exclude FUCK (and FUCKUP, and FUCKWIT, and so on), the designers would’ve incurred less collateral damage.↩︎
I’ve published files containing the “exclusive” words, playable in one version of Boggle but not the other.↩︎
My house rules:
- No words under 4 letters. The set of three-letter words is small; rote-spotting them to deny your opponents points is a waste of time.
- Count unique words, rather than letters, to determine scores. Word length is a factor in the tie-breaker, word quality (always negotiable).
- At home we play with a dynamic negotiated dictionary (Googling and arguing), but the solver I implemented uses CSW19.
These are important if you want to reproduce the specific distributions in this post, but the emergent similarities between these dice sets should be robust against dictionary changes and/or inclusion of three-letter words.↩︎

"Mystery Box" Economics

2024-12-23T00:00:00Z

“Mystery Box” Economics« blog 2024-12-23

“Mystery Box” Economics

Robinhood announced a new “Mystery Box” points redemption feature to Gold [credit] Card customers today. Launching a loot crate minigame for consumer debt is an odd move — Robinhood, after all, spent the last few years insisting it’s an accessible but responsible consumer financial services company (c.f. their debit and retirement products) and not a gambling app for candy-crushing your life’s savings away into short-call options. Between their recent event contracts experiment and Vlad’s chatter about sports betting, they seem lately less afraid of the casino comparison.

A “Mystery Box” costs 1, 000 points. The result of about $333 in spend, 1, 000 points have a $10 value in cash-back redemption.¹ Each Box yields a reward in one of three forms:

A fixed number of points — greater than the 1, 000 spent.
An elevated cash-back rate for all spend over some time period (24 hours, one week, or 30 days).
An elevated cash-back rate on your next purchase, either generally or in a certain category (e.g. “groceries,” “restaurants,” “automotive refuel”).

Importantly, the 2nd and 3rd reward forms — boosted cashback rates — do not stack on the standard 3% cash-back rate offered by the card. You should think of the reward as just the marginal increase over 3%: a 4% elevated rate only nets you 1% additional cash-back.

When does it make sense to buy a “Mystery Box” instead of redeeming to cash in a Brokerage account? The expected value depends on how you expect to spend after buying it. If you have specific plans — e.g. a large single purchase you need to make on Amazon — the expected value may exceed the $10 price tag.

I am not a financial advisor and this is not financial advice. These reward definitions are from the Robinhood Gold Card Rewards Program Rules as of ~~December 23, 2024~~ March 31, 2026; they may change.²

Reward	Expected spend	Reward value	Probability	Expected value
100,000 points	⎯	$1,000.00	0.001%	$0.01
10,000 points	⎯	$100.00	0.20%	$0.20
7,500 points	⎯	$75.00	0.30%	$0.23
5,000 points	⎯	$50.00	0.50%	$0.25
2,500 points	⎯	$25.00	1.00%	$0.25
1,500 points	⎯	$15.00	1.50%	$0.22
1,250 points	⎯	$12.50	2.00%	$0.25
10% cashback on next grocery purchase	$100		5.00%
5% cashback on next grocery purchase	$100		8.00%
10% cashback on next automotive refuel	$50		2.00%
5% cashback for 30 days	$3000		0.25%
5% cashback for 1 week	$500		2.00%
10% cashback for 24 hours	$250		0.50%
5% cashback for 24 hours	$250		6.00%
4% cashback for 24 hours	$250		17.00%
15% cashback on your next purchase	$100		3.00%
10% cashback on next mobile wallet purchase	$100		4.00%
15% cashback on next restaurant order	$100		5.00%
10% cashback on next restaurant order	$100		25.749%
5% cashback on next restaurant order	$100		16.00%
"Mystery Box" cost				$10.00
Total "Mystery Box" expected value

The ranges on these sliders are capped to the spend limits stated in the reward terms, even if those limits seem unrealistic.

“Reward value” assumes the points are to be redeemed “for Cash Back in Robinhood Brokerage Cash Account” (see definition in the Terms). At time of writing, this redemption rate is $0.01 per point. Points redeemed in the Travel and Shop portals, or redeemed for gift card value, are redeemed at the same rate. Points redeemed for statement credit or special items (e.g. metal card upgrades) have a less-than-$0.01 value.↩︎
See the previous calculator for the original December 2024 rewards.↩︎

Postmortems are for Reading

2024-12-05T00:00:00Z

Postmortems are for Reading« blog 2024-12-05

Postmortems are for Reading

You probably have a folder of old technical incident writeups — that time you dropped an important database table, or accidentally disabled an error rate monitor, or sent every customer a test email. Every company has a corporate euphemism for these writeups; I’ll call them “postmortems.”

In Trevor Kletz’s advice to process plant managers, this history takes physical form: the little ‘black book.’

Keep a ‘black book’ or ‘memory book’ in each control room, a folder of reports on accidents that have occurred. Do not include falls and bruises, but only accidents of technical interest, and include accidents from other plants.¹

Now be honest: do you read your own postmortems? Has anyone revisited them since they were first written and approved? “The black book should be compulsory reading for newcomers, at all levels,” Kletz continues, “and old hands should dip into it from time to time to refresh their memories.” Postmortem writeups shouldn’t just serve to marshal an initial response; if you’re serious about preventing repeat incidents, they should be a living part of your operational culture.

In their control room, a process plant manager like Kletz could see evidence of that role in wear and tear.

If spotlessly clean, like poetry books in libraries, they are probably never read and the reasons for this should be sought. Perhaps they are incomprehensible. [… One] may be surprised how often they are out-of-date, or cannot readily be found or are spotlessly clean.²

Software engineers often ignore this secondary role of incident postmortems — to teach future engineers and incident-responders — in favor of immediately pragmatic tasks: satisfy requirements from on high; assuage fears; outline a narrow root cause. Managers of software engineers aren’t much better.

You can have a laudable incident management culture — a blameless and honest one, earnest about improving your processes — that still shits out dry, perfunctory, box-ticking reports for nobody to read ever again.

Instead, make postmortem readability an explicit value (not just “this can be read,” but “I want to read it”). A postmortem’s author should step back from the obligatory template and consider what they want various readers to remember.

Audience	Questions to consider
Peer engineers	Is this failure part of a pattern of preventable incidents in your system? Has some link in this incident’s causal chain cropped up in other incidents? Do other parts of your product have similar failure modes? Even if you won’t rewrite the code in remediation, could this have been pre-empted with a different design/implementation?
New hires	What’s the single most important rule or reminder to take away? Does the indicent demonstrate anything unique about your system, a characteristic failure mode the uninitiated wouldn’t expect?
Outsiders	How would you describe th eincident to a friend on another team, or one writing software at a different company? How would you describe it to a chemical process engineer? Is that narrative — the memorable, widely-relatable version — clear in your written report?

These ‘black book’ summaries can go in your primary report or live in some team-internal folder. They shouldn’t interfere with writing a precise and descriptive report, and your responsibility to write something interesting doesn’t override responsibilities to your colleagues (fairness) or customers (objectivity).

Postmortems can be great reads. The NTSB and USCSB have small cult followings, largely outside their respective industries; I only arrived at “Safety Through Incompatibility” because the USCSB’s YouTube backlog tickles my brain. A failure that seems highly specific may exemplify a much broader class of failures outside your domain, just as chemical process failures are (surprise!) good analogies for crummy software engineering.

Keep in mind: it’s a privilege (one worth exercising) to treat incident management lightheartedly. The tradition of keeping ‘black books’ and revisiting them was a hard-learned lesson in process engineering; I remember Kletz’s somber epigraph for Learning from Accidents:

This book has been written
to remember the dead and injured
and to warn the living

Kletz, Trevor. Learning from Accidents. Routledge, 2007. Page 313. Available online. He gave the same advice, in almost identical language, in an internal memo in 1975:
One method which has been used successfully on at least one plant in the Division is the plant black book. On this plant there is a folder containing reports of every serious incident and near miss that has occurred on the plant, together with reports of incidents in similar plants in other companies. This is compulsory reading for all managers and engineers when they first join the plant, and the old hands dip into it from time to time to refresh their memory.
Why not start a similar folder on your plant? It may look a little thin at first, but nevertheless it may help your successor. I can probably help you fill it.
The [runaway reaction] incident described in the next item might have been prevented by a plant black book.
Imperial Chemical Industries Limited, Petrochemicals Division. Safety Newsletter No. 72. 1975. Available online. This newsletter is notable as an early specific example of how Kletz writes about safety directly and among peers; the books cited here are his (meta-)writings about writing about safety.↩︎
Kletz, Trevor. An Engineer’s View of Human Error, Third Edition. Taylor & Francis, 2001. Page 71.↩︎

Applying the "Hierarchy of Controls"

2024-12-03T00:00:00Z

Applying the “Hierarchy of Controls”« blog 2024-12-03

Applying the “Hierarchy of Controls”

One of the US Chemical Safety Board’s “Key Lessons” from the Atchison, Kansas accidental mixing incident is that the operator in question, and others like it, should

apply the [National Institute for Occupational Safety and Health (NIOSH)] hierarchy of controls when evaluating controls and safeguards for preventing inadvertent mixing. For all chemical unloading activities that require human interaction, […] identify and address human factors issues that may increase the potential for an incorrect connection.¹

The Hierarchy’s basic premise is that there may be several ways to mitigate a hazard, but some of those strategies are stronger than others:

At the strong end, you can eliminate the hazardous part of your system entirely, then smack the big red ‘Easy’ button on your desk.
At the weak end, you can give Mike a pair of safety goggles (PPE) so the tank of magmatic polymer ooze won’t blind him when it burns off all his skin.

I’ve had the privilege to work on several software teams who take systems of controls (in security, compliance, and in plain program correctness) very seriously. Some practices from process engineering, e.g. the “blameless” retrospective reports we write after major failures, are commonplace “best practices” in tech already: after a major incident, the responding team will usually draw up some take-aways and propose some changes (to code or process) to prevent the issue from re-occurring.

That juncture — comparing candidate controls — is your cue to pull up the NIOSH diagram! The Hierarchy and its common examples are written for industrial environments, but the applicability is straightforward.

You might eliminate an long-disused table of sensitive data, substitute a vetted vendor for a sketchy one, introduce regression tests — an engineering control — or tweak your code review practices, an administrative one.

Some teams emphasize “defense in depth” when they pick controls.” A recent manager of mine put special emphasis on depth in the causal chain: can we add a control that makes recurrence less likely along with a monitoring control for detecting it sooner?

That’s a useful principle, and totally compatible with the Hierarchy of Controls model: a process plant doesn’t eschew PPE just because they’ve substituted a lesser hazard for a greater one; they, too, defend in depth. Practicing defense in depth without a Hierarchy of Controls has three main shortcomings:

It prompts an “incremental” defense. The call for a “preventative” control subtly promotes solutions where the same failure mode can still structurally occur but is less likely. This underemphasizes options for Elimination and Substitution (e.g. stop retaining that sensitive user data rather than trying to secure it). This is part of the additive bias I discuss in “Safety Through Incompatibility.”
It encourages quantity over quality. It underemphasizes the difference between Engineering controls and Administrative controls. Anything that must be read by engineers, enforced in code review, covered in training, etc. is an Administrative control. If “we’ll make sure it doesn’t happen again” is the best your team has to offer after an incident, you have no plan (only a shallow root-cause analysis).
The last layer of defense, automated monitoring, is some mix of Administrative control (“thou shalt respond to this page”) and PPE (“don the masks and douse the flames before they spread”). That’s valuable only if well-designed — if you’re Substituting a component for the hazardous one, your monitoring improvements should cover the new component’s failure modes.

Just use the Hierarchy. The next time you’re working on an incident retrospective, tag the controls you propose by their type — Elimination, Substitution, Engineering, Administrative, and PPE. Refer to them by name when you review postmortem plans. Complex schemes of weak controls mean waste and risk (and wasted weekends, paged to death). No more!

Safety Through Incompatibility

2024-11-22T00:00:00Z

Safety Through Incompatibility« blog 2024-11-22

Safety Through Incompatibility

October 21, 2016: a Harcros Chemicals delivery truck arrives at the MGPI Processing plant in Atchinson, Kansas for a routine early-morning delivery of sulfuric acid. Together with a plant operator, the driver runs a hose from their trailer tank of pressurized sulfuric acid to one of the facility’s fill lines, checks for leaks, and starts the transfer of acid.

Not fifteen minutes later, a yellow-green cloud erupts from one of the facility’s holding tanks. It swallows the delivery truck. It engulfs the nearby control building; the operators scramble from the plant on foot. The driver takes refuge in a wastewater treatment plant nearby, and the green cloud — highly toxic chlorine gas — drifts northeast, on the wind, over Atchison.

How does a routine delivery cause an uncontrolled release of chlorine? Through a reaction between the delivered acid and a tank of sodium hypochlorite. At the MGPI plant, stocks of these two “incompatible” chemicals are loaded from the same connection area, using an identical hose connection. The driver connected to the wrong unmarked fill line.

Anyone who’s done their time on a rushed software engineering team has cleaned up an analogous accident: two things, usually separated, are mixed by accident or mistaken design.

What did it cost you? A couple hours of work and some griping in Slack? For a chemical process engineer (or any other species of real engineer), the stakes are astronomically higher. We have much to learn.

Industrial chemical accidents in the U.S. are subject to investigation by the U.S. Chemical Safety and Hazard Investigation Board (USCSB). According to their report, the Atchison incident teaches a “Key Lesson:” if components should never be connected, make it impossible to connect them!

Work with chemical distributors to select hose couplings and fill line connections with uniquely shaped and color-coded fittings for each chemical or class of chemicals, especially where severe chemicals are unloaded in close proximity. This can include a combination of accepted fittings with unique shapes (e.g., square for acids, hexagon for bases) or different sized diameters (e.g., 2-inch or 3-inch round) for each fill line.²

An early-career software engineer generally works additively. One starts with some raw stuff (an empty project structure, then some language primitives, some data…) and accrues features and affordances until the program is at least capable of completing some task.

Considering capabilities as hazards doesn’t come as naturally, even though examples abound. There are examples in our ancient jokes: rm is hazardously compatible with your precious root directory. That’s fine for a library, but death in a system³ — you don’t need an API endpoint that drops your production database, even though your database libraries could do so.

Unfortunately for our safety analysis, the raw stuff of software engineering is less definite than the raw stuff of chemical plants (you know, the chemicals).

One valuable analogy is types. A function’s parameters are its fill lines — they constrain what sorts of data can be pumped into it. Whereas chemical process engineers use incompatible hose couplings, programmers can elect to use incompatible types to avoid mix-ups.

Strongly typed identifiers are a classic example of this principle. While there’s some underlying primitive type (e.g. an integer representing auto-incrementing IDs, or a string representation for a UUID⁴) it’s categorically incorrect to use an ID from one table to perform a lookup in another.

You can incorrectly mix IDs from different tables in queries, of course. Consider this buggy SQL query:

SELECT cart.id, cart.customer_id
FROM customers AS customer
JOIN carts AS cart
  -- This *should* match cart.customer_id to customer.id, but doesn't.
  ON customer.id = cart.id;

A library may allow this kind of mistake, but your program shouldn’t. A good ORM should support strongly typed identifiers out of the box. You may need to carefully massage raw ID representations into the correct ID types at your system boundaries (e.g. in your API handlers), but then you can code within that boundary without paranoia.

These kinds of mistakes happen. They make nightmarish bugs: updates meant for one entity are applied to an arbitrary other entity in its table (Customer A adds an item to Customer B’s cart — yikes!). They also slip through code review, especially in tandem with over-abbreviated variable names. A team I worked with recently switched to typed IDs, and uncovered a handful of these bugs in production, tucked away in sleepy code-paths where their filthy impact went unnoticed.

// Less safe: inadvertent mixing.
func unsafeDeleteCustomer(id int) { ... }
func unsafeOperation(c Cart) {
  // Compiles, but uses a cart ID to look up a customer.
  unsafeDeleteCustomer(c.id)
}

// More safe, and more expressive to boot!
func deleteCustomer(id CustomerId) { ... }
func operation(c Cart) {
  // Compiler error! c.id is not a CustomerId.
  deleteCustomer(c.id)
}

This type-level safety through incompatibility is the generalized response to the code smell Martin Fowler terms “primitive obsession.”⁵ Using proper closed enums over grab-bags of named values is another neat example; as for typed IDs, a good ORM and a good database schema do much of the heavy lifting.

Other incompatibilities are more specific to your system, your business logic, or the quirks of the data you inherited; these are harder to spot, but just as important. I recently worked on a system where two different sources of activity data were keyed differently:

Granular transactions, dated by when they occurred.
Daily summaries, dated by when they are generated. The summary with date August 10, 2024 actually summarizes transactions dated to August 9, 2024!

The difference in those dates — a poor data model design, to be sure — was a constant stumbling block for new engineers: it seemed like the two dates would naturally correspond, but treating them interchangeably (comparing them to join sets of transactions with summaries) is completely misleading!⁶

We initially tried to solve this with what the USCSB would term an “administrative control:” authors were expected to understand the difference between the two dates, and reviewers were expected to confirm they were used correctly. Even if you can remember to do it, this is hard code to refactor. That activityDate argument date your function receives — what kind of date is it? Has it already been shifted?

Selective incompatibility proved a stronger solution. These were both dates, sure, but they should not mix. Define two wrappers for date types — SnapshotDate and TransactionDate — that can’t be directly compared. Instead, define projections from one type into the other.

The higher-level lesson for a software engineer reading the Atchison incident report isn’t specific to “accidental mixing” (whether acids or IDs). This incident analysis, with its parallels in software, illustrates the value of drawing safety lessons from older, more spectacularly dangerous engineering disciplines.⁷ There is nothing new under the sun.

Nothing new for process safety engineers, either.

Trevor Kletz’s 1985 Engineer’s View of Human Error describes “wrong connections.” His explanation of the concept gives an example from the dawn of anesthesia:

Figure 2.13 shows the simple apparatus devised in 1867, in the early days of anaesthetics, to mix chloroform vapour with air and deliver it to the patient. If it was connected up the wrong way round liquid chloroform was blown into the patient with results that could be fatal. Redesigning the apparatus so that the two pipes could not be interchanged was easy; all that was needed were different types of connection or different sizes of pipe. Persuading doctors to use the new design was more difficult and the old design was still killing people in 1928. Doctors believed that highly skilled professional men would not make such a simple error but as we have seen everyone can make slips occur however well-motivated and well-trained, in fact, only when well-trained.⁸

The book’s third edition (2001) includes another example:

Do not assume that chemical engineers would not make similar errors. In 1989, in a polyethylene plant in Texas, a leak of ethylene exploded, killing 23 people. The leak occurred because a line was opened for repair while the air-operated valve isolating it from the rest of the plant was open. It was open because the two compressed air lines, one to open the valve and one to close it, had identical couplings, and they had been interchanged. […]⁹

The problem wasn’t solved in 1989, and it wasn’t solved in 2016; I’d bet the U.S. still hasn’t consigned inadvertent mixing accidents to history. The ultra-serious process engineers are still learning from their past mistakes. So should we — from their mistakes and ours.

U.S. Chemical Safety and Hazard Investigation Board. Key Lessons for Preventing Inadvertent Mixing During Chemical Unloading Operations: Chemical Reaction and Release in Atchison, Kansas, No. 2017-01-I-KS. 2017. Available online.↩︎
U.S. Chemical Safety and Hazard Investigation Board. Key Lessons for Preventing Inadvertent Mixing During Chemical Unloading Operations: Chemical Reaction and Release in Atchison, Kansas, No. 2017-01-I-KS. 2017. Available online.
This lesson about incompatible hose couplings is one of eleven in this report. Several others have useful analogues in software engineering: applying the hierarchy of controls in hazard analysis; introduce interlocks to make manual processing safer; physically separate and clearly mark incompatible equipement, e.g. the fill lines for acid and bleach here; train workers on where to find their PPE and how to use emergency shutoff mechanisms.↩︎
This is an important point. Writing code on a team, you can assert that there are categorically incorrect ways to use certain resources/services — at least from the current standpoint — and you’d do well to preclude that incorrect usage initially. Type-level restrictions are easy to unwind later, but hard to introduce after the fact.↩︎
UUIDs are intrinsically safer than incrementing integer IDs, since a given UUID should be globally unique (or, rather, there’s a negligible risk of a collision). Rather than updating an arbitrary entity, the following examples would update nothing — that’s preferable.
This is a kind of global, data-level safety-through-incompatibility without a clear analog in the Atchison incident or USCSB report, and a major advantage for these kinds of ID schemes.↩︎
Fowler, Martin. Refactoring: improving the design of existing code. Addison-Wesley Professional, 2018. See also this short summary.↩︎
The two date sets should really be comparable, but their inclusion in myriad accounting and operations queries (with little offsets assuming their mismatch!) complicated that migration. A database view on summaries with a shifted date is probably the right starting point.↩︎
I’ve enjoyed books by Trevor Kletz and papers by Nancy Leveson on this point. It bears mentioning that much of software safety culture — e.g. blameless retrospectives, root-cause analysis, and “technical risk assessments” — are derived from principles in industrial safety (usually after some watering-down). We share an underlying language of “controls.”↩︎
Kletz, Trevor. An Engineer’s View of Human Error, Third Edition. Taylor & Francis, 2001. Pages 31–32.↩︎
Kletz, Trevor. An Engineer’s View of Human Error, Third Edition. Taylor & Francis, 2001. Pages 31–32.↩︎

'Magic' in Elixir's `Logger`

2024-11-03T00:00:00Z

‘Magic’ in Elixir’s Logger« blog 2024-11-03

‘Magic’ in Elixir’s `Logger`

I first drafted this post in December 2022. I stopped following progress in Elixir shortly after; maybe its logging has completely changed! That’s besides the point: this is a post about control and cognitive load, specifically with process-scoped global variables. Even if the examples go stale, the principle holds.

Consider this Elixir function:

def log_and_operate(trace_id) do
  Logger.metadata(trace_id: trace_id)
  Logger.info("Reached pre-operation")
  operate()
  Logger.info("Reached post-operation")
end

Setting a trace_id in your structured logger should contextualize one log entry by locating it in a stream of other log entries with the same key. You include it because you want to fetch your logs later, search for something like trace_id:"correct-horse", and see logs like this:

{trace_id: "correct-horse", message: "Reached pre-operation"}
# ...logs from operate()
{trace_id: "correct-horse", message: "Reached post-operation"}

But, in Elixir¹, operate() has free access to all the logger metadata, including the trace_id field doing the correlating! If it so chooses, it’ll break your trace_id connection between the pre- and post-operation log lines.

def operate() do
  Logger.metadata(trace_id: "battery-staple")
  Logger.info("Changed the trace ID")
end

{trace_id: "correct-horse", message: "Reached pre-operation"}
{trace_id: "battery-staple", message: "Changed the trace ID"}
{trace_id: "battery-staple", message: "Reached post-operation"}

Of course, that’s a reductive example. In practice, your trace_id has to survive a huge tree of conditionally-connected codepaths, any of which could trample your precious log metadata. You have to read a lot of code to feel confident that won’t happen.

Logger metadata is a process-scoped variable, so it’s intrinsically tied to what happens in that process, and in what order (“control”²). Even if a function with Logger calls doesn’t receive any logger-specific arguments — that is, it doesn’t explicitly depend on logging elsewhere — its behavior can implicitly depend on all sequentially prior operations in the same process. If you imagine the process’s execution as the depth-first traversal of a tree of function calls, this means knowing all the previously-visited vertices, not just the lexical parents of the current vertex.

Elixir’s standard Logger does what Peter Bourgon calls magic: it obscures a complex process-global data-interdependency. Unfortunately, ruling out influence is an indispensable part of reading code. When influence extends to a whole process, and when your program is anything but strictly non-recursive, you can’t just treat code lexically: you have to mentally model the process execution as you read it.

Functional work-arounds

One work-around is to, for some particularly sensitive metadata keys, defer to those already on the logger:

# safe_set_trace_id is a dedicated setter for a single Logger metadata field.
def safe_set_trace_id(trace_id) do
  if !Logger.metadata(:trace_id) do
    Logger.metadata(trace_id: trace_id)
  end
end

# protected_metadata and safe_set_metadata protect a static set of metadata
# keys.
@protected_metadata [:trace_id, :others]
def safe_set_metadata(opts) do
  opts
  |> Enum.each(fn {key, value} ->
    if !Enum.member(@protected_metadata, key) || !Logger.metadata(key) do
      Logger.metadata(key, value)
  end)
end

This requires either sharing a canonical set of precious metadata keys, then enforcing that every Logger call checks the list, or writing a module wrapping Logger and forbidding direct Logger calls.

Alternatively, you can enforce that keys for correlation be unchanged by redundantly(?) re-setting them:

def log_and_operate(trace_id) do
  Logger.metadata(trace_id: trace_id)
  Logger.info("Reached pre-operation")
  operate()
  Logger.info("Reached post-operation", trace_id: trace_id)
end

The Go approach is to relay the updates through return values: an updated logger or context.Context, which callers can take or leave selectively.

In Go convention, instead of having process-scoped logger metadata, loggers (with metadata) are objects. Of course, you commonly want to inherit some logger metadata; that’s why you see code building on a service-wide base logger:

func (s *Server) Operate() {
  s.Logger.With("key", "value")
}

Extracting a logger from a received context:

func Operate(ctx context.Context) {
  log.From(ctx).With("key", "value")
}

Or receiving a logger from the caller, then forking it — extending the received logger’s metadata in a local copy:

func Operate(logger *zap.SugaredLogger) {
  var value string
  logger = logger.With("key", "value")
}

Even in Go, sometimes you do want to modify a logger for the caller scope. How do you do this without process-scoped magic? Return values that let the caller decide what to do with their own logger. Admittedly, this can feel a little clumsy — threading contextual data up and down the callstack resists later refactoring, and including an updated logger among return values feels even weirder. Regardless, at least the Go approach is explicit.

That’s one of my main complaints about Elixir. Every function call implicitly delegates — even just briefly — control of the caller’s logger. If you want to make any strong guarantees about the logging behavior of any given function, you have to know

Everything that ran in the process before the function was called, if you want to make assumptions about the original state.
Everything that runs between logging calls in that function, all the way down.

And I don’t want to know that much! Excluding swaths of code from consideration is essential to being productive in a big, shared codebase (and especially for doing the kind of parachute-in spot debugging routinely required in a live product).

My point isn’t that you should pick Go³, but that you should spurn ‘magic,’ particularly the “comprehension-subverting magic of globals” (Bourgon), a point on which the Go community is pretty disciplined. Think less, get more done; better to be ugly and explicit than opaque.

At its heart, Elixir’s Logger really uses the metadata management API exposed by Erlang’s logger module.↩︎
For some more formal discussion, see Moseley, Ben, and Peter Marks. “Out of the tar pit.” Software Practice Advancement (SPA) 2006 (2006):
Control is basically about the order in which things happen.
The problem with control is that very often we do not want to have to be concerned with this. […]
This is because the person reading the code above must effectively duplicate the work of the hypothetical compoiler — they must (by virtue of the definition of the language semantics) start with the assumption that the ordering specified is seignificant, and then by further inspection determine that it is not (in cases less trivial than the one above determining this can become very difficult). The problem here is that mistakes in this determination can lead to the introduction of very subtle and hard-to-find bugs. (p. 8-9)
Available online.↩︎
This isn’t to say the language you write doesn’t matter. Choose wisely! Some things to consider:
1. Strong structured logging.
2. Static types.
3. Linters. Do they exist? Are they extensible?
4. Talent. Is the language niche? How much time will engineers spend learning it? Can you find community-maintained clients for common APIs, or will you have to roll your own?
Anecdotally, the functional PLs I’ve written professionally (Scala and Elixir) have disappointed in several of these respects. ↩︎

Applying "Laws" of Software Evolution

2024-10-26T00:00:00Z

Applying “Laws” of Software Evolution« blog 2024-10-26

Applying “Laws” of Software Evolution

Common models can be didactically useful even if they are, basically, not correct. That’s how I feel about Lehman’s “Programs, Life Cycles, and Laws of Software Evolution,” published in IEEE Vol. 68, 1980. The “laws” themselves — reinterpreted to death¹ — are neither surprising nor axiomatic today.

One of the models Lehman uses to construct his laws, on the other hand, is a didactic gem: his hierarchy of program complexities (S-, P-, and E-programs).²

Here’s a very condensed version of those concepts:

Class	Characteristic	Example	Characteristics
S	Specified	Solution to the classical travelling salesman problem	“Programs whose function is formally defined by and derivable from a specification.”
P	Abstract	Simulation game where the player directs virtual salespeople	“It is a model of an abstraction of a real-world situation, containing uncertainties, unknowns, arbitrary criteria, continuous variables.”
E	Reflexive	Program for managing real salespeople	“The program has become a part of the world it models, it is embedded in it.”

Section II of the Lehman paper — “Programs as Models” — includes extended examples of each category. Of course, the categories aren’t unrelated! Basically “all large programs (software systems) will be constructed as structures of S-programs,” Lehman explains.³ There’s an analogous compositional relationship between P and E:

At the complex end, we aren’t typically cobbling several independent P-programs together to form E-programs. Instead, think of E-programs as P-programs in the real world. For example,

As a product with users: through use, it generates new problems, desires, and requirements in the market it addresses. In other words, organizational composition.
As an evolving system: it reflexively influences its own progress from P₀ → P₁ → ⋯ → P_n because each version encourages or discourages subsequent versions. In other words, temporal composition.

In the second sense, technical debt is a self-contained E-program problem: the code you write today impacts your program’s viscosity — its resistance to change — but also determines the nature and urgency of future changes. Managing tech debt well requires foresight.

Almost by definition, useful software engineering contributes at least indirectly to some E-program, “mechanize[s] a human or societal activity.”⁴ Even really simple programs — basic Unix commands, for example — are E-programs by nature of their widespread use.

In fact, E-program-style problems are so ubiquitous we should question Lehman’s trichotomy. Are they really a distinct kind of program? Or should we focus on E-programming as a verb instead, a way of forecasting-despite-reflexivity in S- and P-programs?

E-program skills are not underrated, but they are under-discussed.

Randall Koutnik suggests we replace traditional SWE levels with terms for the kind of work we do. In this model, we develop autonomy rather than seniority. You started as an “implementer” of concrete specs, became a “solver” of more loosely-defined problems, and finally grew to be a “finder” of problems to solve. Sounds familiar? That three-stage development corresponds to the kinds of thinking required by each of Lehman’s program classes.

Koutnik level⁵	Koutnik role	Lehman program class
Junior	Implementer	S-programs
Regular	Solver	P-programs
Senior	Finder	E-programs

You can think of promotion between the Koutnik roles as the combination of two things:

Effectiveness in your present role.
Comfort decomposing the next Lehman program class into the present one.

For example, promotion from “Implementer” to “Solver” requires that you can decompose P-programs into S-programs — complex problems into simple behaviors — and that you can effectively implement those decomposed elements. Per the diagram above, “decompose” typically means functional decomposition.

Promotion from “Solver” to “Finder” requires breaking E-programs down into P-programs, preferably for delegation. The two kinds of E → P composition I described have inverses:

Temporal decomposition

Consider P_n when you’re implementing P₀. Can you solve this problem once instead of solving n variants before consolidating?
- This doesn’t mean you always should. How confident are you about the future variants?
- Similarly: does the work you’re doing today unnecessarily resist future changes, e.g. by making unsafe assumptions about product model constraints?
How is your team’s tempo and trajectory? This is where planning, headcount, and talent development come into play.
- Can you make your teammates more effective? What skills do you think each of them should develop most urgently?
- Given the opportunity, what skill does your team need most desperately? Does the sourcing you’re doing find candidates with that skill? Does your interview loop detect it unambiguously?
- After that hire, what’s the next limiting factor?

Organizational decomposition

Where are there new product opportunities?
- Consider induced demand. Does the product you ship today generate new needs/requirements?
- Consider your domain. Answer Hamming’s question: “what are the important problems in [your] field?”⁶
What interface does your program provide the rest of the organization?
- Does it encourage reuse, expansion, investment?
- How apparent is its value? Would a different interface demonstrate value more clearly, or offer you more leverage in planning?

Setting aside my specific examples, decomposition from E- to P-programs means determining what problems to solve in a reflexive E-program environment, where the problem you solve today determines what new problem you’ll want to solve tomorrow.

“Temporal” and “organizational” aren’t an exhaustive list of E-program (de)compositions — shoot me an email if you think of another. No matter what source of program-reflexivity you focus on, you’re likely to wind up with a focus area more actionable than the typical Regular-to-Senior values (e.g. unspecific “leadership”).

To engineers: your workplace might encourage you to cede exercising foresight to your Product or Engineering Manager. Don’t! These are important aspects of your craft; engage them, even if you don’t have the autonomy to act on your own predictions. Engage them out of self-respect if nothing else.

In the early stages, earning engineering autonomy means writing the P-program you need today. Later, it’s about navigating the E-program you’re building indefinitely. Don’t miss the forest for the trees.

See myriad other attempts to get you to care, e.g. Adrian Colyer’s “Programs, life cycles, and laws of software evolution” (2020) or Matt Rickard’s “Laws of Software Evolution” (2021).↩︎
Lehman, Meir M. “Programs, life cycles, and laws of software evolution.” Proceedings of the IEEE 68, no. 9 (1980): 1060-1076. Available online.↩︎
Lehman, p. 1061.↩︎
Lehman, p. 1062.↩︎
We might call these levels “Software Engineer,” “Senior Software Engineer,” and “Staff Software Engineer” today.↩︎
Hamming dedicated one half-day per work week to stepping back and considering his field in its entirety; from “You and Your Research”:
Along those lines at some urging from John Tukey and others, I finally adopted what I called “Great Thoughts Time.” When I went to lunch Friday noon, I would only discuss great thoughts after that. By great thoughts I mean ones like: “What will be the role of computers in all of AT&T?”, “How will computers change science?” […] Friday afternoons for years — great thoughts only — means that I committed 10% of my time trying to understand the bigger problems in the field, i.e. what was and what was not important. I found in the early days I had believed ‘this’ and yet had spent all week marching in ‘that’ direction. It was kind of foolish. If I really believe the action is over there, why do I march in this direction? I either had to change my goal or change what I did. So I changed something I did and I marched in the direction I thought was important. It’s that easy.
↩︎

Paris Redux

2024-02-19T00:00:00Z

Paris Redux« blog 2024-02-19

Paris Redux

I’m looking forward to visiting Paris again this spring. That’s as good an excuse as any to share two Paris snippets from my recent reading.

Friedensreich Hundertwasser wrote about looping strolls through Paris —

I have a bicycle. Paris is big. I want to say that the lines I draw with my bicycle through this great city are extraordinary. The lines are just as wonderful as all the other lines I cross traced by all the other people. I ride around people and obstacles. I am happy at last to be in harmony and in contact with the others. These lines, for which I need many hours and which form an enormous circle by the time I come back and which make me tired, are more beautiful, more genuine and more justified than those I could draw on paper. And I dare say that the lines I trace with my feet on the pavement walking to the museum are more important than the lines I will find there hanging on the walls inside. And it pleases me enormously to see that the line I trace is never straight, never confused, but has a reason to be like this in every tiny part. Beware of the straight line and the drunken line. But above all beware of the T-squared straight line. The straight line leads to the downfall of humanity. La ligne droite conduit à la perte de l’humanité.¹

— and Rilke imagined warm welcomes:

I walked right along the Quai d’Anjou, and into one side-turning after another, as though I were burdened with a lot of memories which in fact I don’t possess at all — it was such a strange afternoon. Somewhere, at a particularly carefully muffled high window, a corner of the curtain was lifted as I went past, and I thought it must be a sign meant for me; there was a feeling here, and then again, as if I had only to walk in, as if everything would be explained even to the very smell that meets you, as if one had been long expected, as if a kind of relief must overwhelm all these silent houses if one decided to go in… a staircase, a hall, not a moment’s hesitation, that is the door, ‘Ah, c’est vous enfin’, does someone say? no matter, it is in the air, in the dusk, the fire on the hearth knows it, all things are quite sure…²

Ah, c’est vous enfin… I can’t wait.

Three-Step Lifted Interfaces

2023-12-30T00:00:00Z

Three-Step Lifted Interfaces« blog 2023-12-30

Three-Step Lifted Interfaces

Look — I might just be a types person. I admit it! Mea maxima culpa! Strong static types are a major factor in how quickly I learn a programming language and how confidently I come to use it. There are myriad other factors, but many of those factors themselves rely on static types (or a very convincing simulation thereof).

Thankfully, I’m in okay company. Today I revisited a Jonathan Blow stream in which Jon pauses to gloat about how much C++’s static types simplify his work.

You just break your program and then you fix all the compile errors. When the compile errors are fixed, you know your program works again. This is something that these dynamic languages don’t let you do, and it’s actually one of the most powerful programming techniques. No troll.
We’re just doing a bunch of not-very-interesting but also not-very-scary drudge work, but we’re using this to migrate us from one place in the space of all possible programs to another one, by a safe route where we don’t smash everything up.¹

Jon demonstrates one such route: rooting out all inner usage of an outer-scope variable by defining a conflicting variable with an incompatible type (2:46).

I also lean on statically typed languages to guide my refactoring. That reliance is especially pronounced when I’m “lifting interfaces” out of single-class implementations, a precursor step to introducing alternative implementations or test doubles. My one weird trick for three-step lifted interfaces is… broken partial renames.

Example: refactoring a logger

You’ve implemented a cute little Logger that writes to a file. Your application — main — passes it around as a value (to functions foo and bar).

package main

import "os"

type Logger struct {
    file *os.File
}

func (l Logger) Info(message string) {
    l.file.WriteString("[INFO] " + message + "\n")
}

func (l Logger) Warning(message string) {
    l.file.WriteString("[WARN] " + message + "\n")
}

func main() {
    var f *os.File
    logger := Logger{file: f}

    foo(logger)
    bar(logger)
}

func foo(l Logger) {
    l.Info("Called foo")
    bar(l)
}

func bar(l Logger) {
    l.Warning("Called bar")
}

Ah, single-implementation serenity. go build demo.go works, foo and bar chug cheerfully along logging things. Imagine a happy little green diagram — the Logger type and the three ways this code uses it:

A happy little green diagram. Logger is used in three ways: in a constructor in main, as a function argument type in foo and bar, and via method calls in those functions.

It’s almost too serene. For one reason or another, you want more from this program.

Maybe you want to selectively use a different logger with the same main routine, one that routes your messages to a log server or stdout.

Maybe you need a mock logger for your unit tests, to confirm foo and bar emit key log messages without simultaneous tests racing for the file.²

If you want main to work with a variety of loggers interchangeably, you have to drive an abstracting wedge between the implementation and its users: an interface. A refactor like this has three goals:

Lift an interface capturing the existing logger’s public surface (Info and Error functions).
Update the file-writing logger to implement that interface.³
Update functions to ambivalently receive any implementation of the logger interface — a logger for tests, a logger for your log server, whatever!

Just like Jon Blow’s C++ compiler, the Go compiler won’t let you build confused code where you’re accidentally passing one type in lieu of another. In theory you could refactor manually and unsystematically, and when eventually something builds you’ve likely achieved your goals. Like Jon, you’d be using type safety “to migrate […] from one place in the space of all possible programs to another one, by a safe route.”

Of course, some routes are shorter than others. I take this one because it’s short.

Step 1: break everything

Seriously, break everything. Maybe you proceed cautiously when you adding new functionality to a program — incrementally adding bits and pieces, careful to resolve issues whenever you introduce them. Refactoring working code is a fundamentally different flow: break the build confidently and selectively, then let the type system guide you back to a correct program.

Step 1 is to rename Logger to something (almost anything!) else. FileLogger is a fine name here.

The key is to rename it locally, not to reach for an IDE-automated “Refactor → Rename” that updates every reference to Logger. Let those references break; you want them to be broken. Break everything.

// FileLogger is Logger after a rename; otherwise unchanged.
type FileLogger struct { … }

func (l FileLogger) Info(message string) { … }

func (l FileLogger) Warning(message string) { … }

func main() {
    var f *os.File
    logger := Logger{file: f}   // 🚨 undefined: Logger

    foo(logger)
    bar(logger)
}

func foo(l Logger) { … }        // 🚨 undefined: Logger

func bar(l Logger) { … }        // 🚨 undefined: Logger

Where it once succeeded, go build main.go lists compiler errors (undefined: Logger) at each broken reference to the old name. FileLogger is fine: unused, but internally consistent. Everything else needs you to define a type called Logger — the very definition you just removed!

In his example, Jon Blow uses the compiler’s list of broken references as a checklist for manual corrections: he investigates the compiler errors one by one, resolves them sensibly, and then he’s done (“safe route”).

Your safe route is slightly different. The rename doesn’t just break everything to yield a checklist; it also opens space for a new type, one that will clear most of that checklist at once.

Step 2: lift the interface

Instead of getting bogged down in the compiler error nitty-gritty, focus on the goal of the refactor: you’re driving an interface, like a wedge, between FileLogger and its callers.

Step 2 is to introduce that interface — in this example, it’s just the FileLogger methods Info and Warning.

Here’s the trick: call the new interface what FileLogger used to be called.

// Logger is the lifted interface.
type Logger interface {
    Info(message string)
    Warning(message string)
}

// FileLogger implicitly implements Logger: it defines Info and Warning.
type FileLogger struct { … }

func (l FileLogger) Info(message string) { … }

func (l FileLogger) Warning(message string) { … }

func main() {
    var f *os.File
    logger := Logger{file: f}   // 🚨 invalid composite literal type Logger

    foo(logger)
    bar(logger)
}

func foo(l Logger) { … }        // ✅ Fixed!

func bar(l Logger) { … }        // ✅ Fixed!

By reoccupying the vacated typename Logger, lifting the interface next to the implementation instantly resolves the undefined: Logger build errors.

You didn’t have to track down foo and bar, much less edit them — they just receive interfaces now (tada!) because the name of the type they already received, Logger, now references a compatible interface. This is the chief advantage of the three-step approach: in the real world you might have hundreds of individual functions analogous to foo and bar.

main, of course, is still broken. The build error, invalid composite literal type Logger, means that Logger is an interface, but you’re trying to instantiate it as if it were a concrete class.

Reintroducing a type called Logger satisfies the function signature usage (and the method calls downstream of those). There’s a new type error for the constructor.

At this point, you’ve achieved all three of the goals laid out at the beginning of the refactor: you’ve lifted an interface, the old file-writing logger implements that interface, and the functions main calls are ambivalent about what kind of Logger you give them!

Now all you need is a program that builds.

Step 3: fix the build

This is it: the “not-very-interesting but also not-very-scary drudge work.”

Because introducing the interface resolved all the references in foo and bar, there’s not much left for you to fix: just the constructor call in main is broken. You can’t directly construct the Logger interface, so you have to construct something that implements it.

Great news: there’s no wrong choice! The only available Logger implementation is FileLogger with the original file-writing behavior.

Step 3 is to replace the broken constructor reference with the new implementation name FileLogger.

type Logger interface {
    Info(message string)
    Warning(message string)
}

type FileLogger struct { … }
func (l FileLogger) Info(message string) { … }
func (l FileLogger) Warning(message string) { … }

func main() {
    var f *os.File
    logger := FileLogger{file: f} // ✅ Fixed!

    foo(logger)
    bar(logger)
}

func foo(l Logger) { … }

func bar(l Logger) { … }

With that manual update, everything clicks satisfyingly into place. go build demo.go succeeds. All three of your goals for the refactor are satisfied. The diagram is green. To quote the fortune-cookie fortune taped to my monitor at home, “☺ The job is well done. ☺”

Now that main constructs an implementation, all the type references in our program refer to appropriate type definitions.

At this point you’re free to proceed with what you set out to achieve: additional Logger implementations.

You’re also free to swap in different names (e.g. reverting FileLogger to Logger and naming the interface ILogger if that’s more your style). Now that you have the type relationships you wanted, your IDE’s “Refactor → Rename” functionality can take care of the semantic fixes.

Shortest paths

This was a simple example, but this three-step method works for complex interfaces, with more diverse users, in far, far gnarlier codebases.

But beware! Selectively vacating names before redefining them with compatible types is a neat trick, but it isn’t the right path for every refactor. Static type-checking provides “safe route[s] where we don’t smash everything up,” but it’s up to you to pick a short one.

In this logger interface example, you break references to the implementation because, after the migration, you expect to have many more references to the interface Logger (hundreds of function signatures) than to the implementation FileLogger (a handful of constructors: easy to update manually).

Were that relationship were reversed — if you were interfacing a type that’s frequently constructed and infrequently received — manually reconnecting the constructors would be tedious. You would actually save time by updating the few function signatures without renaming. Then again, if something’s frequently constructed and infrequently received, you’re less likely to be replacing it with an interface!

To be sure, you can follow this three-step refactor path in a language without static types, but you have to very cautiously assess whether you’re actually done. Jon Blow again:

Yeah, the type safety part of Python — or the lack thereof — is huge. A lot of the stuff that we did today, these grunt work refactors I’m doing, would be a lot scarier in Python. You’d be like, “I don’t know if I just broke something.” We’ve done ten things today, at least, where you’d be like “I don’t know if that broke something,” where in C++ you’re like “yeah, I know I didn’t break something.” It’s very different.⁴

Every broken build is a blessing in disguise: it could’ve been a runtime exception. So long as your language has your back, break things with confidence. You might just be a types person.

Four Translations of Todesfuge

2023-06-10T00:00:00Z

Four Translations of Todesfuge« blog 2023-06-10

Four Translations of Todesfuge

German Art After 1960 at SFMOMA includes two huge Anselm Kiefer canvases, heavy oil paintings matted with straw. Sulamith (1980) depicts a low groin-vaulted interior like a crypt, built of brown and blackened stones. Small flames burn at the end of a row of alcoves. The painting’s name — Hebrew in origin, a princess in the Song of Songs — is scratched into the upper left.

Margarethe (1981) looks like a series of wicks, each a long bent tangle of straw topped with a little painted flame. Ash dapples the ground, and the background sky is dotted with what could be stars behind a cool milky-grey wash like wet smoke. The name “Margarethe” is scrawled prominently across its center in dark-grey looping cursive. In an earlier, cheerier watercolor version of this composition, Kiefer paints golden wheat bowing under a blue sky.

The museum insciption explains these titles refer to the Paul Celan poem Todesfuge (Deathfugue), in which the narrator — a Jewish prisoner forced by his blue-eyed guard to dig graves in a German concentration camp — repeats “your golden hair Margarete” (dein goldenes Haar Margarete) and “your ashen hair Sulamith” (dein aschenes Haar Sulamith).

Goldenes and aschenes are descriptors rich with nonvisiual connotations. Obviously blondness is of vain importance to aryanism, but gold specifically has been a German national color since the Napoleonic Wars: in the tricolor, gold is classically associated with the promise of a liberated future, the goldene Licht der Freiheit (golden light of freedom). Sulamith’s ashen hair, on the other hand, confirms the Jewishness of her name. “Ashen hair” aligns Hebrew-Biblical mourning (II Sam. xiii. 9; Josh. vii. 6; Job ii. 12¹) with the Nazi extermination camps’ crematoria.

“Dein aschenes Haar Sulamith wir schaufeln ein Grab in den Lüften da liegt man nicht eng;” does Celan address Sulamith directly? Are the prisonsers digging a grave for her? Is ein Grab in den Lüften (approx. “a grave in the air”) a metaphor for cremation, or an image for collective memory? When you read Todesfuge in English, your interpretation of these ambiguities is at your translator’s mercy. Each takes a different approach. Together they demonstrate the difficulties of translation, broadly, but also — by necessarily foregrounding different aspects, and falling short in different ways — they reveal what resonates in the original.

Todesfuge (1948)

Paul Celan, born in 1920 to a German-speaking Jewish family in Cernăuți (Chernivtsi), survived a Romanian forced labor camp, lost his parents to the S.S., and began publishing original poetry pseudonymously after the war. Here he’s recorded reading Todesfuge:

Todesfuge

Schwarze Milch der Frühe wir trinken sie abends
wir trinken sie mittags und morgens wir trinken sie nachts
wir trinken und trinken
wir schaufeln ein Grab in den Lüften da liegt man nicht eng
Ein Mann wohnt im Haus der spielt mit den Schlangen der schreibt
der schreibt wenn es dunkelt nach Deutschland dein goldenes Haar Margarete
er schreibt es und tritt vor das Haus und es blitzen die Sterne er pfeift seine Rüden herbei
er pfeift seine Juden hervor lässt schaufeln ein Grab in der Erde
er befiehlt uns spielt auf nun zum Tanz

Schwarze Milch der Frühe wir trinken dich nachts
wir trinken dich morgens und mittags wir trinken dich abends
wir trinken und trinken
Ein Mann wohnt im Haus der spielt mit den Schlangen der schreibt
der schreibt wenn es dunkelt nach Deutschland dein goldenes Haar Margarete
Dein aschenes Haar Sulamith wir schaufeln ein Grab in den Lüften da liegt man nicht eng

Er ruft stecht tiefer ins Erdreich ihr einen ihr andern singet und spielt
er greift nach dem Eisen im Gurt er schwingts seine Augen sind blau
stecht tiefer die Spaten ihr einen ihr andern spielt weiter zum Tanz auf

Schwarze Milch der Frühe wir trinken dich nachts
wir trinken dich mittags und morgens wir trinken dich abends
wir trinken und trinken
ein Mann wohnt im Haus dein goldenes Haar Margarete
dein aschenes Haar Sulamith er spielt mit den Schlangen

Er ruft spielt süsser den Tod der Tod ist ein Meister aus Deutschland
er ruft streicht dunkler die Geigen dann steigt ihr als Rauch in die Luft
dan habt ihr ein Grab in den Wolken da liegt man nicht eng

Schwarze Milch der Frühe wir trinken dich nachts
wir trinken dich mittags der Tod ist ein Meister aus Deutschland
wir trinken dich abends und morgens wir trinken und trinken
der Tod ist ein Meister aus Deutschland sein Auge ist blau
er trifft dich mit bleierner Kugel er trifft dich genau
ein Mann wohnt im Haus dein goldenes Haar Margarete
er hetzt seine Ruden auf uns er schenkt uns ein Grab in der Luft
er spielt mit den Schlangen und träumet der Tod ist ein Meister aus Deutschland

dein goldenes Haar Margarete
dein aschenes Haar Sulamith

Translations

After seeing the Anselm Kiefer paintings, I found and typed translations of Todesfuge by John Felstiner, Michael Hamburger, Jerome Rothenberg, and Karl S. Weimar respectively (all reproduced below), and generated these files highlighting their pairwise differences:²

	Hamburger	Rothenberg	Weimar
Felstiner	felstiner-hamburger.diff	felstiner-rothenberg.diff	felstiner-weimar.diff
Hamburger		hamburger-rothenberg.diff	hamburger-weimar.diff
Rothenberg			rothenberg-weimar.diff

Each translator has his editorial priorities. Weimar carefully preserves the original’s meter, Hamburger its verbal simplicity. Felstiner’s untranslated German phrases fragment the closing stanzas. I’ve included short notes on what sets each apart.

One could spend ages doing these comparisons. Weimar critiques several prior translations I haven’t read: Gertrude C. Schwebell’s (1962), Donald White’s (1966), and Joachim Neugroschel’s (1971). Felstiner notes at least “fifteen published English translations of Todesfuge (and several unpublished),” and that was almost forty years ago! These are just a few examples.

John Felstiner (1986)

Deathfugue

Black milk of daybreak we drink it at evening
we drink it at midday and morning we drink it at night
we drink and we drink
we shovel a grave in the air where you won't lie too cramped
A man lives in the house he plays with his vipers he writes
he writes when it grows dark to Deutschland your golden hair Margareta
he writes it and steps out of doors and the stars are all sparkling he whistles his hounds to stay close
he whistles his Jews into rows has them shovel a grave in the ground
he commands us play up for the dance

Black milk of daybreak we drink you at night
we drink you at morning and midday we drink you at evening
we drink and we drink
A man lives in the house he plays with his vipers he writes
he writes when it grows dark to Deutschland your golden hair Margareta
Your ashen hair Shulamith we shovel a grave in the air where you won't lie too cramped

He shouts dig this earth deeper you lot there you others sing up and play
he grabs for the rod in his belt he swings it his eyes are so blue
stick your spades deeper you lot there you others play on for the dancing

Black milk of daybreak we drink you at night
we drink you at midday and morning we drink you at evening
we drink and we drink
a man lives in the house your goldenes Haar Margareta
your aschenes Haar Shulamith he plays with his vipers

He shouts play death more sweetly this Death is a master from Deutschland
he shouts scrape your strings darker you'll rise up as smoke to the sky
you'll then have a grave in the clouds where you won't lie too cramped

Black milk of daybreak we drink you at night
we drink you at midday Death is a master aus Deutschland
we drink you at evening and morning we drink and we drink
this Death is ein Meister aus Deutschland his eye it is blue
he shoots you with shot made of lead shoots you level and true
a man lives in the house your goldenes Haar Margarete
he looses his hounds on us grants us a grave in the air
he plays with his vipers and daydreams der Tod ist ein Meister aus Deutschland

dein goldenes Haar Margarete
dein aschenes Haar Sulamith

Published in “Selected Poems and Prose of Paul Celan,” 2001.³

Felstiner published his notes, which describe Celan’s personal history and the poem’s cultural significance in postwar Europe, under the title “Paul Celan’s Todesfuge” (1986).⁴ After Todesfuge achieved wide recognition, Felstiner recalls, Celan’s verse grew more abstruse; he resisted Todesfuge’s inclusion in anthologies; he resented the poem’s public palatability (what Felstiner politely terms “too congenial a reading,” the one that wound up in German grade school textbooks).

Like any good translator, Felstiner hems and haws over words: “what do you do, for instance, with Meister — a god, a champion, a guildsman, a master of arts or theology, a labour-camp overseer, a musical maestro, a rabbi, the ‘master’ race, not to speak of Richard Wagner’s Meistersinger von Nurnberg…” He gives special care to the flawed assonance of Rüden (hounds) and Juden (Jews) in the first stanza, explicitly rejecting Rothenberg’s “draw near”/“appear” rhyme in favor of “stay close” and “into rows.” Actually, Weimar’s solution — “come up” and “come out” — best captures the original effect.

Words aside, Felstiner’s translation is my favorite among these four because it captures the tumbling, subtly accelerating cadence of Celan’s reading. “In translating,” Felstiner writes, “I [went] back again and again, longingly, to Celan’s own recorded voice — he read with ‘a cold heat,’ one friend said — to absorb his rhythms, pauses, emphases, retards, quickenings, caustic articulation.”

The translation’s progressive dissolution back into German is key: at first, “Death is a master from Deutschland,” then “Death is a master aus Deutschland,” “ein Meister aus Deutschland,” and finally “der Tod ist ein Meister aus Deutschland.” In the final couplet, even the names are left unadapted. The effect is undeniably fuguelike (feverish swirling, multiplicity of voices).

Of course, Celan’s original doens’t have this progression or anything like it. Weimar’s structural analysis considers the Tod ist ein Meister aus Deutschland refrain a distinct “voice,” distinguished by the repetition. Break each repetition into translated and untranslated portions and the repetition is gone.

What place does a change this blatantly editorial have in translation? My anthology of Felstiner’s translations includes original German texts, in which a detail-oriented non-germanophone can spot the original repetition. Readers with a dedicated interest in Celan translations might have more “neutral” (less editorial!) points of reference, like the Hamburger translation below. Less dedicated readers might not recognize the translator’s hand.

Felstiner’s preface to “Selected Poems” argues this license is authentic: Celan himself relied on it for his translations into German.

For Celan as translator, faithful often did mean fresh. Vis-à-vis French or Russian or English verse, he was given to fracturing, contracting, omitting, specifying, intensifying, inventing, repeating where the original had no repetition, changing nouns into verbs, indicatives into imperatives or gerunds, and so on.
[…]
Too easily, I believe, lyric poetry gets labeled untranslatable, especially in the case of someone [Celan] whose personal losses rendered his German language at once precarious and privileged, inalienable yet irreplicable; someone calling himself “whitegravel stutterer;” someone speaking from his “true- / stammered mouth” about “eternity / bloodblack embabeled,” blutschwarz umbabelt. But then why not think of translation as the specific art of loss, and begin from there?⁵

Michael Hamburger (1972)

Death Fugue

Black milk of daybreak we drink it at sundown
we drink it at noon in the morning we drink it at night
we drink and we drink it
we dig a grave in the breezes there one lies unconfined
A man lives in the house he plays with the serpents he writes
he writes when dusk falls to Germany your golden hair Margarete
he writes it and steps out of doors and the stars are flashing he whistles his pack out
he whistles his Jews out in earth has them dig for a grave
he commands us strike up for the dance

Black milk of daybreak we drink you at night
we drink in the morning at noon we drink you at sundown
we drink and we drink you
A man lives in the house he plays with the serpents he writes
he writes when dusk falls to Germany your golden hair Margarete
your ashen hair Shulamith we dig a grave in the breezes there one lies unconfined

He calls out jab deeper into the earth you lot you others sing now and play
he grabs at the iron in his belt he waves it his eyes are blue
jab deeper you lot with your spades you others play on for the dance

Black milk of daybreak we drink you at night
we drink you at noon in the morning we drink you at sundown
we drink and we drink you
a man lives in the house your golden hair Margarete
your ashen hair Shulamith he plays with the serpents

He calls out more sweetly play death death is a master from Germany
he calls out more darkly now stroke your strings then as smoke you will rise into air
then a grave you will have in the clouds there one lies unconfined

Black milk of daybreak we drink you at night
we drink you at noon death is a master from Germany
we drink you at sundown and in the morning we drink and we drink you
death is a master from Germany his eyes are blue
he strikes you with leaden bullets his aim is true
a man lives in the house your golden hair Margarete
he sets his pack on to us he grants us a grave in the air
he plays with the serpents and daydreams death is a master from Germany

your golden hair Margarete
your ashen hair Shulamith

Published in “Poems of Paul Celan,” 1972.⁶

Hamburger seems to assign the adverbs süßer and dunkler strangely: they describe the calls rather than the playing. This construction is true to the original word order, and with the right punctuation the call could read as a forced second-position verb:

He calls out, “more sweetly play death…”

Unfortunately, there isn’t any punctuation to prompt this interpretation, so we read “He calls out more sweetly, ‘play death…’” Even if they were punctuated, these lines would be awkward. Distracting. I’m doubly puzzled because Hamburger isn’t always precious about word order: er pfeift seine Juden hervor lässt schaufeln ein Grab in der Erde is rendered as “he whistles his Jews out in earth has them dig for a grave.” Maybe Hamburger just prefers awkward phrasings.

Otherwise, this translation seems the most neutral of the bunch — the closest to word-by-word translation, without left fragments of German or unseemly new images…

Jerome Rothenberg (2005)

Death Fugue

Black milk of morning we drink you at dusktime
we drink you at noontime and dawntime we drink you at night
we drink and drink
we scoop out a grave in the sky where it's roomy to lie
There's a man in this house who cultivates snakes and who writes
who writes when it's nightfall nach Deutschland your golden hair Margareta
he writes it and walks from the house and the stars all start flashing he whistles his dogs to draw near
whistles his Jews to appear starts us scooping a grave out of sand
he commands us play up for the dance

Black milk of morning we drink you at night
we drink you at dawntime and noontime we drink you at dusktime
we drink and drink
There's a man in this house who cultivates snakes and who writes
who writes when it's nightfall nach Deutschland your golden hair Margareta
your ashen hair Shulamite we we scoop out a grave in the sky where it's roomy to lie

He calls jab it deep in the soil you men you other men sing and play
he tugs at the sword in his belt he swings it his eyes are blue
jab your spades deeper you men you other men play up again for the dance

Black milk of morning we drink you at night
we drink you at noontime and dawntime we drink you at dusktime
we drink and drink
there's a man in this house your golden hair Margareta
your ashen hair Shulamite he cultivates snakes

He calls play that death thing more sweetly Death is a gang-boss aus Deutschland
he calls scrape that fiddle more darkly then hover like smoke in the air
then scoop out a grave in the clouds where it's roomy to lie

Black milk of morning we drink you at night
we drink you at noontime Death is a gang-boss aus Deutschland
we drink you at dusktime and dawntime we drink and drink
Death is a gang-boss aus Deutschland his eye is blue
he hits you with leaden bullets his aim is true
there's a man in this house your golden hair Margareta
he sets his dogs on our trail he gives us a grave in the sky
he cultivates snakes and he dreams Death is a gang-boss aus Deutschland

your golden hair Margareta
your ashen hair Shulamite

Published in “Paul Celan: Selections,” 2005,⁷ but this translation is much older — Rothenberg translated Todesfuge for a City Lights booklet published in 1959.⁸

Frankly, this one isn’t for me. “Roomy” and “scooping” have childish sounds and sandcastle connotations. “Sword” is an improbable translation of Eisen (lit. “iron”). Why is den Tod rendered “that death thing?”

Why is Meister — which has a musical second meaning — rendered “gang-boss,” apparently referring to the blue-eyed commandant? In the other translations, this stanza suggests personification by melding fragmented references to Death, the musical master from Germany, and the gang-boss. Eliminating the musical connotations of Meister aus Deutschland eliminates a character from that trio and bluntly joins the other two.

I get the impression Rothenberg injects what Weimar calls an “artificially poetic element.” Steigen is a simple verb suggesting motion (lit. “to climb”), but Rothenberg picks “hover,” suggesting stillness. Abends becomes “dusktime;” mittags, “noontime;” morgens, “dawntime.”

The uncapitalized sie in the original first stanza is a third-person pronoun (the other translations here use “it,” then switch to “you” in later stanzas when Celan uses du). Did Celan really mean the formal, second-person, capitalized Sie or, more likely, does this translation efface the third- to second-person shift?

Another pronominal controversy: Weimar complains Rothenberg defuses the dramatic tension of Celan’s original by using “who” instead of “he” in the first and second stanzas.

The actions are simple and swift and Celan’s intention, clearly reflected in the almost breathless monotonous way in which he himself reads the work and in the complete absence of the printed text, is to infuse the poem with a relentless, irresistible momentum […] Both Schwebell’s and Rothenberg’s translations destroy this unity of short, tense, disconnected sentences, especially when they render the domonstrative pronoun der (l. 5 [Ein Mann wohnt im Haus der spielt…]) as a relative pronoun.⁹

Elsewhere he calls Rothenberg’s word choice “boldly scabrous.”

Like Felstiner, Rothenberg leaves Deutschland (and its prepositions) untranslated, but the untranslated phrases don’t progress stanza to stanza. This is a reasonable minimum: can you really imagine Hamburger and Weimar’s blue-eyed men writing to “Germany?”

Karl S. Weimar (1974)

Fugue of Death

Coal-black milk of morning we drink it at evening
we drink it at noon and at daybreak we drink it at night
we drink and we drink
we shovel a grave in the skies there is room enough there
A man lives in the house he plays with his vipers he writes
he writes when it darkens to Germany your golden hair Marguerite
he writes it and steps out of doors and the stars are shining he whistles his dogs to come up
he whistles his Jews to come out to shovel a grave in the ground
he commands us strike up a tune for the dance

Coal-black milk of morning we drink you at night
we drink you at daybreak and noon and we drink you at evening
we drink and we drink
A man lives in the house he plays with his vipers he writes
he writes when it darkens to Germany your golden hair Marguerite
Your ashen hair Shulamite we shovel a grave in the skies there is room enough there

He shouts dig deeper into the earth you here and you there start singing and playing
he clutches the gun in his belt he waves it his eyes are blue
dig deeper your spades you here and you there keep playing that dance tune

Coal-black milk of morning we drink you at night
we drink you at noon and at daybreak we drink you at evening
we drink and we drink
a man lives in the house your golden hair Marguerite
your ashen hair Shulamite he plays with his vipers

He shouts play the death tune sweeter death is a master from Germany
he shouts strike up the fiddles more darkly you'll rise like the smoke to the sky
you'll have your own grave in the clouds there is room enough there

Coal-black milk of morning we drink you at night
we drink you at noon death is a master from Germany
we drink you at evening and at daybreak we drink and we drink
death is a master from Germany his eye is blue
he hits you with bullets of lead his target is you
a man lives in the house your golden hair Marguerite
he sets loose his dogs after us he gives us a grave in the sky
he plays with his vipers and dreams death is a master from Germany

your golden hair Marguerite
your ashen hair Shulamite

Published with translator notes in “Paul Celan’s ‘Todesfuge’: Translation and Interpretation,” 1974.¹⁰

Weimar takes the poem’s title (fuge, meaning “fugue”) as a suggestion to focus on its meter in translation. “Coal-black,” like schwarze, is a spondee: two syllables, with stress on the first.¹¹

I have mixed feelings about “coal” here. On one hand, the focus on meter sets this translation apart, and Celan’s reading is distinctively rhythmic. On the other, “coal” is a baggaged noun — especially in a German modern-industrial context, and in the Holocaust more specifically, where Weimar’s “coal-black” prefigures “the smoke to the sky” more than the original German schwartze. Moreover, Weimar weakens Celan’s reference to a Rose Ausländer poem mentioning black milk.

Elsewhere (“golden hair” and “ashen hair”) Weimar focuses on retaining the metric parallel rather than the specific meter: both adjectives lose a syllable. “Aureate” might’ve worked, but he rejects it: it’s too posh and there isn’t a good grey equivalent. Like Hamburger’s selective preservation of word-order, this puzzles me; if you’ll settle for parallels, ditch “coal-black!”

Weimar’s structural and metric analysis does a lot to convince me of a translation I still don’t particularly like reading. Because they focus on the translator’s task and directly critique other translations (especially Rothenberg’s), the notes are a useful companion.

Jewish Encyclopedia. Ashes. Available online.↩︎
diff -u michael-hamburger.txt john-felstiner.txt yields a simple diff; piping that to diff-so-fancy yields a GitHub-style token-by-token diff; aha converts the output to self-contained HTML. All together:
```
diff -u michael-hamburger.txt john-felstiner.txt | diff-so-fancy | aha > hf.diff.htm
```
Not anymore! I regenerated these diffs with a tool I wrote: poem-diff. The results are semantically clearer than aha output and don’t suggest a pre- and post-edit state like a typical code-diff tool.
↩︎
Paul Celan, trans. John Felstiner. Selected Poems and Prose of Paul Celan (New York: W. W. Norton, 2001), 30–33.↩︎
Felstiner, John. “Paul Celan’s Todesfuge.” Holocaust and genocide studies 1, no. 2 (1986): 249-264.↩︎
Paul Celan, trans. John Felstiner. Selected Poems and Prose of Paul Celan (New York: W. W. Norton, 2001), xxxiii.↩︎
Paul Celan, trans. Michael Hamburger. Poems of Paul Celan. (New York: Persea Books, 1972), 62–65.↩︎
Paul Celan, ed. Pierre Joris and Jerome Rothenberg. Paul Celan: Selections. (Berkeley: University of California Press, 2005), 46–47.↩︎
Jerome Rothenberg. “‘Reading Celan’ (1959, 1995, 2020) for the hundredth anniversary of Paul Celan’s birth.” Available online.↩︎
Karl S. Weimar. “Paul Celan’s “Todesfuge”: Translation and Interpretation.” PMLA 89, no. 1 (1974): 85–96.↩︎
Karl S. Weimar. “Paul Celan’s “Todesfuge”: Translation and Interpretation.” PMLA 89, no. 1 (1974): 85–96.↩︎
Poetry Foundation has a good little gloassary of poetic meters. I’m sure there are good reasons for the historic names, but they’re easily rendered as binary strings: a length (number of syllables), where each syllable is stressed (1) or unstressed (0).
Metric foot Example Syllabic emphasis
pyrrhic to a 00
iamb unite 01
trochee highway 10
spondee hog-wild 11
dactyl poetry 100
anapest underfoot 001
You’d think they’d at least get demonstrative names, but “dactyl” is one unemphasized syllable short of actually being a dactyl.↩︎

Ceci n'est pas...

2023-03-19T00:00:00Z

Ceci n’est pas…« blog 2023-03-19

Ceci n’est pas…

Marcel Broodthaers’s career as a visual artist begins where his career as a poet — in the traditional poems-on-paper sense — comes to an abrupt end: in 1964, in an oblong blob of plaster. The work, La Pense-Bête, stands as a cenotaph to earnest meaning. “I, too, wondered whether I could not sell something and succeed in life,” Broodthaers writes in the exhibition prospectus. “For some time I had been no good at anything. I am forty years old… Finally the idea of inventing something insincere crossed my mind and I set to work straightaway.”¹

Forty-four copies of Broodthaers’s last book of poems stand upright, closed and partially wrapped in newspaper, in a haphazard glob of plaster. A faded-orange orb like a shattered buoy (the Tate Gallery’s 1980 retrospective calls it “nacreous”) nestles in the high mound of plaster at the books’ spines. A plaster egg is crushed into the far end of the agglomeration, where it peters into the inked fiberboard base.

La Pense-Bête’s plaster mass sits in S.M.A.K (acronym for “Stedelijk Museum voor Actuele Kunst”). I visited S.M.A.K. in October 2021, part of a weeklong march through Belgium’s art museums, the day after my first introduction to Broodthaers: an exhibit of his Industrial Poems at WIELS (not an acronym, capitalized anyway).

The Industrial Poems are a series of 120 plaques manufactured in groups of seven between 1968 and 1972. The signs are glossy plastic, vacuum-formed on plywood matrices and then painted. In a self-published self-interview, Broodthaers facetiously points out “[t]hese plaques are fabricated like waffles.”²

Each sign sports color-blocking unique in its group. Though they have a common formed surface, the paint selects which raised features to foreground and which to leave back. Seven plaques from the same mold suggest different meanings through selective emphasis: one highlights just diacritic marks; another highlights certain words; another certain other words; and so on. Though any plaque, taken individually, is cryptic, their arrangement together invites a game of subset-selection: “perhaps some different subset of these words/shapes holds the meaning.” Broodthaers refers to the plaque-puzzles as “rebuses,” intentionally opaque demonstrations of the “difficulty of reading that results when you use this substance.”³

That “difficulty of reading” is the central concept of Broodthaers’s oeuvre, a thread he started pulling in that 1964 inaugural exhibit. La Pense-Bête, he writes, turned a book into “the object of a prohibition:”

I took a bundle of fifty copies of a book called Pense-Bête and half-embedded them in plaster. The wrapping paper is torn off at the top of the “sculpture,” so you can see the stack of books (the bottom part is hidden by the plaster). Here you cannot read the book without destroying its sculptural aspect. It is a concrete gesture that passes the prohibition on to the viewer — at least that’s what I thought would happen.⁴

The thread continues through his other work. A 2019 Ghent exhibition of unreadable books called Broodthaers a “leader of illegibility.”⁵ Through blacked-out concrete poetry, text on crumpled packing paper, miniscule atlases, and cat interviews, Broodthaers explores tantalizing illegibility. Sometimes, as with La Pense-Bête, there’s a sculptural “prohibition.” By contrast, the Industrial Poems are sculpturally legible but dubiously meaningful, at least in a direct way — are they cryptic, or are they entirely nonsensical?

Unsurprisingly, commentaries on Broodthaers often connect his fixation with meaning to contemporary semiology. These are the 1960s in francophone Europe: Jacques Derrida is dissolving structuralist linguistics into a phenomenological fever-dream, and Roland Barthes is announcing La mort de l’auteur (1967). Broodthaers shares their solidarities — when Paris’s universities spark the May 68 general strike, he occupies the Brussels Palais des Beaux-Arts — and makes insincere references to their work: “[h]is comment on Magritte takes the form of directing the reader to Michel Foucault’s essay ‘Ceci n’est pas une pipe,’ which at that time existed only as a published lecture that [he] had almost certainly not read.”⁶

Art historian Benjamin H.D. Buchloh relates Broodthaers’s illegibility (“the linguistic sign becoming the object of semiological and poetical decomposition”) to Ferdinand de Saussure’s bipartite theory of signs: the separation of a signifier — an image or an utterance or what have you — from a signified, that concept it represents.⁷ In practice, the jump from signifier to signified can appear so automatic Saussure’s distinction seems pedantic. An iconographic signifier (e.g. the illuminated seatbelts-fastened sign in an airplane) visually resembles its signified (you buckling your damn seatbelt). But signs aren’t always so direct. An illustrated eagle could iconographically signify a certain bird, but it could also represent a heraldic national identity; same sign, different signifieds!

For Buchloh, Broodthaers’s industrial poems assert the Saussurean dichotomy by refusing to usefully fulfill it. Rather than presenting a straightforward signified, their writing “refuse[s] the visual or sensual data which the viewer demands.” Maybe they’re cryptic — signifying something inaccessible — but we can’t rule out that they’re nonsensical, they signify nothing at all! Buchloh calls these ‘anomic objects,’ defined by their “withdrawal from systems of communication, [their] self-imposed condition of muteness and silence.”⁸ Whereas La Pense-Bête prohibited reading by embedding books in plaster, the Industrial Poems allow reading but inhibit its automatic effect (the reader’s translation from sign to signifier).

Ethnographer Michael Oppitz, on the other hand, identifies Broodthaers with Roland Barthes’s reaction to Saussure, wherein signifier and signified are more weakly coupled by the interpreting reader.⁹

My lasting impression from the WIELS exhibit is that both Buchloh and Oppitz miss an opportunity to treat the Industrial Poems as objects first and foremost. By considering the plaques differently, we can reconsider how a museum should stage encounters with meta-referential art.

In essence, this requires a generalizing step-back from signs to tools. In general, Saussure treats each instance of a sign (e.g. the inked imprint of a word) as a tool for meaning-making. For the most part — as with our automatic interpretation of the seatbelts-fastened indicator — they signify smoothly, so long as they belong to a familiar lexicon or fit into a familiar structure. “We read in two ways,” he writes: “a new or unknown word is spelled out letter by letter; but a common, ordinary word is embraced by a single glance, independently of its letters, so that the image of the whole word acquires an ideographic value.”¹⁰

The difference between familiar (automatic) and unfamiliar (letter-by-letter) signs mirrors Heidegger’s notion of the tool ready-to-hand (zuhandenheit), a sort of teleological status where an object disappears into a task without you having to think about it. When you’re hammering nails, the hammer-as-object disappears into the hammer-as-purpose. You don’t consider this hammer. You just hammer.¹¹

You’re rudely introduced to the tool-analogue of Saussure’s unfamiliar sign when you take a swing and the head of the hammer flies off. A broken hammer refuses to be reduced, invisibly, to its purpose. You can only get back to the purpose (the bliss of hammering) by considering this hammer as an object (or, suddenly, two objects). How did it break? What are the handle and head materials? How are they textured? The broken tool interrupts its own invisibility, the same way an unfamiliar word interrupts ideographic reading and forces you to consider the individual letters.

If the Industrial Poems were just words, Heidegger’s tool-phenomenology wouldn’t tell us anything Saussure can’t. They’re more than words: they’re tools with words on them! Whereas Saussure’s familiarity model implies a one-way flow of signifiers (from unfamiliar to familiar), Heidegger’s tool analysis allows familiar objects to become unfamiliar. That’s how the plaques function: they appear legible at first.

Broodthaers’s promotional materials cautioned his audience against reducing the Industrial Poems to semiological demonstrations. “What kinds of simpletons do you catch with your plaques?” he asks himself; “those who take these plaques for pictures and hang them on their walls. Although there’s no proof that the real simpleton isn’t the author himself, who thought he was a linguist able to leap over the bar in the signifier/signified formula, but who might in fact have been merely playing the professor.”¹² The Tate Gallery delivers a direct caution. Because “[t]he plastic panels contain a series of puzzles with no solution […] the sophisticated, unable to read them, but recognizing them as signs, would perhaps find in them an art of semiology — but they would be wrong.” Like the other object-assemblages Broodthaers exhibited (the books in plaster, the miniscule atlas, etc.), the Industrial Poems’ “meaning was primary and had no status as metalanguage. They are made up of elements drawn from the culture but do not directly comment on it or describe it.”¹³

This deepens Broodthaers’s prohibition on intelligibility: you can’t discern a direct meaning from the Industrial Poems, and you’re instructed to avoid secondarily interpreting them as the didactic expression of a semiotic concept.

Moreover, the Industrial Poems take the form of plaques. A museum is full of plaques-as-tools, sometimes descriptive — little white museum labels — and sometimes prohibitive. Broodthaers’s Industrial Poems camouflage themselves as tools in the tool-world of signage. Some even purport to be museum signs, bearing museum-specific descriptions (e.g. Porte A) or prohibitions (e.g. Museum. Enfants non admis). That camouflage invites an unwitting viewer to see them as tools first, and to run headlong into interruption when their signifiers make no sense.

That risk-of-interruption is a function of the Industrial Poems’ status as tool objects. If you reduce them to their rebuses — present them as prints, say, with pictureframes, behind glass — the trap of their brittle readiness-to-hand gives way to an actual, unbroken readiness-to-hand as art objects.

Oppitz remarks that René Magritte was “unable to protect his painting [The Treachery of Images] against the art-historical significance it would acquire […] as art object,” and hopes Broodthaers’s work fares better.¹⁴ Broodthaers designed the Industrial Poems with similar concerns in mind, fears developed in what he saw as the failure of La Pense-Bête. He thought his concrete gesture would render La Pense-Bête illegible, but he’d inadvertently formed an art object for which that prohibition held no weight: their status as art stripped the books of their status as books.

viewers reacted quite differently from what I had imagined. Everyone so far, no matter who, has perceived the object either as an artistic expression or as a curiosity. “Look! Books in plaster!” No one had any curiosity about the text; nobody had any idea whether this was the final burial of prose or poetry, of sadness or pleasure. No one was affected by the prohibition.¹⁵

The Industrial Poems’ advantage is their subtlety, the possibility that they can slip — at least for a moment, for an unfamiliar viewer — out of the world of art, into the world of tools. Their plasticity plays a special role. “These plaques,” Broodthaers explains in his introduction to their exhibition, “occupy the border between object and image. According to their mechanical production they seem to deny their status as art objects.”¹⁶ At WIELS, the painstakingly comprehensive display of Industrial Poems undermined this denial and ensuing surprise: mounting the Poems in sets from the same mold invites the viewer to try comparative interpretation or, worse, to lose the individual plaques in the candy-colored mass of the edition.

Memorably, I saw one more Industrial Poem in a dim corner of Mu.ZEE in Ostend. It was a surprise, not least because of its slippery crimson-and-gold shine (on a floor of blue-green pontilists, in the greyest city in the world). The plaque seems utilitarian there, even commercial; even if you discern the irony, you could mistake it for the same tongue-in-cheek trendiness forcing the capitalized museum names. It’s too bad my recognition prevented me puzzling over the French.

Broodthaers, of course, exhibited the Industrial Poems together. Unlike WIELS, his 1972 exhibition bore a disclaimer on every object, “a label saying either in French, German, or English ‘This is not a work of art!’”¹⁷

If they’re not works of art, nor intelligible texts, nor didactic semiology, how should you consider them? Broodthaers’s prospectus for his inaugural solo exhibition, the one that entombs his poetry and declares his insincerity, at least appears to support my hunch.

CE QUE C’EST?
EN FAIT, DES OBJETS.

WHAT IS IT?
IN FACT, IT IS OBJECTS.

Marcel Broodthaers. London: Tate Gallery, 1980. Pages 12-13.↩︎
Broodthaers, Marcel, Irmeline Lebeer, and Paul Schmidt. “Ten thousand francs reward.” October 42 (1987): 41. Trés belge!↩︎
Broodthaers, Marcel, Irmeline Lebeer, and Paul Schmidt. “Ten thousand francs reward.” October 42 (1987): 41.↩︎
Broodthaers, Marcel, Irmeline Lebeer, and Paul Schmidt. “Ten thousand francs reward.” October 42 (1987): 44.↩︎
BOEKS, Stoppen met lezen. (Ghent: KASK, 2019).↩︎
Compton, Michael. “In Praise of the Subject.” Marcel Broodthaers (1989), Walker Art Center: 51.↩︎
Buchloh, Benjamin H.D. “Marcel Broodthaers: Allegories of the Avant-Garde” in Artforum (May 1980). Online.↩︎
Buchloh, Benjamin HD. “Open letters, industrial poems.” October (1987): 73.↩︎
Oppitz, Michael, and Chris Cullens. “Eagle/Pipe/Urinal.” October 42 (1987): 155–56.↩︎
Bally, Charles, Albert Sechehaye, and A. Riedlinger. “Ferdinand de Saussure: Courses in General Linguistics.” London: Peter Owen (1960). Quoted in Buchloh (1987, p.77).↩︎
Everyone’s trying to make sense of Heidegger. Mark Foster Gage offers a thorougher example:
Heidegger’s tool analysis posits that while a tool is functioning [ready-to-hand], or its function is visible, the mind registers it as equipment and, as such, it is rendered invisible to our attention. For example, the keyboard on which I type is equipment insofar as it looks like what it does and is being used for a particular function. As Heidegger might say, the keyboard recedes into the background and is inconspicuous while in use or while ready to be used. As I use the keyboard I do not notice its aesthetic properties or other qualities. However, if the keyboard ceased to function, it would become visible to my attention as an object, no longer mentally processed as background equipment.
Of course, we could both be completely and embarrassingly wrong. See Gage, Mark Foster. “Killing Simplicity: Object-Oriented Philosophy in Architecture.” Log 33 (2015): 97.↩︎
Broodthaers, Marcel, Irmeline Lebeer, and Paul Schmidt. “Ten thousand francs reward.” October 42 (1987): 42.↩︎
Marcel Broodthaers. London: Tate Gallery, 1980. Page 18.↩︎
Oppitz, Michael, and Chris Cullens. “Eagle/Pipe/Urinal.” October 42 (1987): 155–56.↩︎
Broodthaers, Marcel, Irmeline Lebeer, and Paul Schmidt. “Ten thousand francs reward.” October 42 (1987): 44.↩︎
Broodthaers, Marcel. BROODTHAERS, exhibition announcement for Galerie Gerda Bassenge, Berlin (1969). Available online in the original German; translated in Buchloh, p. 96. Emphasis added.↩︎
Compton, Michael. “In Praise of the Subject.” Marcel Broodthaers (1989), Walker Art Center: 51.↩︎

Easier OCR on macOS

2023-02-18T00:00:00Z

Easier OCR on macOS« blog 2023-02-18

Easier OCR on macOS

Scanning a document digitizes an image of a printed page, but doesn’t digitize the text on that page: you can’t search for a keyword or copy a relevant passage into another document. Optical Character Recognition programs interpret the scanned images, “see” the individual letterforms, and overlay that textual information over the image (a PDF “text layer”) so you can search and copy-paste the scanned document to your heart’s content. For example, search for “asymmetry” in this scanned page before and after OCR.

Adobe would love to charge you for OCR (built into Acrobat), but the best-in-class OCR engine — Google’s Tesseract, initially developed by HP in the 1980s — is free and open-source.

The issue is the interface: rather than being an end-user program like Acrobat, Tesseract is a tool for building an end-user program. My favorite program, OCRmyPDF, is a little better: it’s designed for end-users, but only end-users comfortable working at the command line.

Rather than navigating folders and running OCRmyPDF from Terminal, you can use Apple’s built-in Shortcuts (available with macOS 12 Monterey and later) to run OCR by right-clicking on a PDF in Finder.

Install OCRmyPDF

Unfortunately, this setup is a two-step process. Unlike an app you can download form the App Store or an installable *.pkg file you download and install from the internet, OCRmyPDF is distributed via a common macOS package manager, Homebrew. First you install Homebrew, then you use Homebrew to install OCRmyPDF.

You can install both from the command line, the most ancient way to interact with the machine you know and love. You might be used to mouse-navigated apps with buttons and menus; at the command line there’s nothing but text.

You type instructions (commands) and press enter to run them; as long as they’re cogent, the computer will obey! Below I’ve included the specific commands to run this way.

Open the application Terminal. You can search for it in Finder or find it at Applications → Utilities → Terminal.
Install Homebrew if you don’t have it.
To check if you already have Homebrew installed, type which brew into Terminal and press enter. If you see an output like /opt/homebrew/bin/brew, you have Homebrew installed and you can proceed to step 3.
If you see an output like brew not found, install Homebrew by copying the “Install Homebrew” command listed on brew.sh into your Terminal and pressing enter. As that installation process runs, it may prompt you for additional input or approval. You may also need to input your computer password.
For a more detailed tutorial on installing Homebrew, see DigitalOcean’s ‘How To Install and Use Homebrew on macOS.’
Once Homebrew is finished installing, confirm the installation: type brew --version into Terminal and press enter.
Install OCRmyPDF: type brew install ocrmypdf into Terminal and press enter.

It’s worth briefly touching on how to use OCRmyPDF from the Terminal. At any given time, the Terminal is operating in a certain folder on your computer — you can use the command pwd to see what folder you’re in, the command ls to list files and child folders from your current position, and the command cd to move into another folder.

When you’re in a folder with a PDF — let’s call it ‘my-scan.pdf’ — running ocrmypdf my-scan.pdf my-scan_ocr.pdf creates a new PDF (my-scan_ocr.pdf) with the same pages as my-scan.pdf, but with the searchable and copyable PDF text layer added.

Add a Shortcut

Install the “OCR PDF” Shortcut using this iCloud sharing link.¹
The last action, “Run Shell Script,” may come with a warning message: “This action cannot be run because Scripting actions are disabled.” Hit the ‘Open Preferences’ button, then ‘Allow Running Scripts.’
Diving into advanced settings to toggle off a security-minded default might reasonably make you nervous: shell scripts are powerful tools, so in theory ‘Allow Running Scripts’ could let a malicious shortcut manipulate your computer. The good news is this script is short: it only runs OCRmyPDf, which is trustworthy.
Use the button in the upper-right-hand corner of the Shortcuts window to navigate to the ‘Shortcut Details.’ Check ‘Use as Quick Action’ and ‘Finder’ to add the “OCR PDF” action to your right-click menu.

Now you can run OCRmyPDF from Shortcuts! Use the ‘Play’ button in the upper-right of this window (it’ll prompt you to select a PDF) or right-click on a PDF and use Quick Actions → OCR PDF.

While your PDF is being processed, you’ll see a Shortcuts status indicator in the menu bar at the top of your screen. When it’s finished, look for a freshly OCR’d PDF in the same folder as the one you selected (if you right-clicked on ‘my-scan.pdf’, expect ‘my-scan_ocr.pdf’). This can take a few minutes for large files.

In retrospect, I wish I’d used OCR much more in college, when my course readings were often chapters scanned from university library books. I imagine it’s also a useful tool for working with big and relatively low-tech corpuses, like public records. Sure, a university student or a public records professional might have an institutional Adobe license, but we should expect more!

This technology has been in development since the mid-80s, and free for almost 20 years… if you’re the right kind of computer-user, comfortable writing your own scripts and troubleshooting at the command line. A consumer low-code app like Shortcuts, by providing a generic graphical interface for shell scripts, extends the same options to a wider range of users.

Comparing Vertex Cover Algorithms

2022-10-30T00:00:00Z

Comparing Vertex Cover Algorithms« blog 2022-10-30

Comparing Vertex Cover Algorithms

In “Graphs at Work” I claim

To improve the customer experience, what you need to understand is the distribution of strategy performances for a given algorithm on real-world graphs, not the theoretical worst case.

Of course, that’s a simplification. Theoretical worst-case performance does impact the customer experience, either on accident or because some adversary wants to throttle your program. Worry less if your “customer concerns are well-isolated,” but they rarely are.

By “real-world graphs” I suggested a family of associations graphs, distinct from the family of all possible associations graphs, might describe the bulk of customer desires. For example, if the typical customer associates Contacts, Deals, and other objects via a mutual association with a Company, those customers’ “real-world graphs” will approximate stars with the Company at the center.

Parameterizing those graph families, you can simulate the candidate algorithms’ performance against a wide range of possible customer configurations (even configurations impossible in practice, e.g. because of a limit on the number of HubSpot types).

Experiment space

All the uncertainty about what’s “real-world” translates into a huge experimental space. Any given experiment embeds a set of assumptions about what the user probably wants and what they have in HubSpot. All the experiments taken together are only useful if they describe the problem well enough, in all its dimensions, to react to user information as it comes in.

Most of the variables here are discrete categories — different vertex cover algorithms, different topological families of graphs, and different weighting schemes for vertices. For these purposes, there isn’t a continuous space between Vazirani’s algorithm and Lavrov’s.

Some of those categories introduce scalar variables, like the size of a random graph or the probability two vertices are adjacent.

Vertex cover algorithms

An unweighted vertex cover algorithm will never k-approximate a minimal weighted vertex cover. Unweighted algorithms behave as if all vertices have the same weight, then minimize the number of vertices in the cover V_req. When you add weights to G = {V, E}, V_req might be arbitrarily bad: each vertex in V_req can be arbitrarily expensive, and vertices in V − V_req can be arbitrarily cheap.

Obviously the best an unweighted algorithm can perform on a weighted graph is to accidentally suggest the weighted optimal strategy.

How should we expect it to perform given a random distribution of weights? I think of a single graph with its topology-determined minimum unweighted vertex cover V_req. The expected weight of that vertex cover is μ∥V_req∥ where μ is the mean of the weight distribution.

What if weights aren’t distributed randomly, and instead correlate with graph topology? I’m not sure what to expect. That question is easier to simulate than to theorize.

I implement three of the algorithms discussed in my last post.

clever

The greedy algorithm I previously implemented in Elixir. I came up with it independently, but I take the name from Michel Zito.¹

The punchline: this algorithm isn’t clever. It performs so badly on tricky graphs it doesn’t k-approximate minimal vertex covers. To this algorithm’s credit, it has an intuitive heuristic: add the highest-degree vertex in G to V_req, remove it from G, and recurse for a minimal vertex cover on what remains.

lavrov

the “2-approximating [unweighted] vertex cover” variation suggested by Mikhail Lavrov:

Start with V_req = ∅. Then, as long as V_req doesn’t cover every edge, we pick an uncovered edge and add both endpoints to V_req.²

My implementation is an even greedier variant, at the cost of some runtime complexity: rather than arbitrarily picking an uncovered edge, it picks the uncovered edge with the highest combined degree between its incident vertices. Lavrov proves the 2-approximation.

vazirani: The only weighted vertex cover algorithm I implement. Rather than removing vertices outright, it relaxes virtual weights t(v) for the vertices incident on a “taken” (uncovered) edge, then adds one or both to V_req depending on the result. My implementation leaves edge-selection arbitrary, per Vazirani’s definition.³

As the only k-approximation of a minimum weighted vertex cover, it’s safe to assume vazirani should perform the most stably. That doens’t moot the experiment. As I noted, there are graphs where it yields a worse result than clever!

Topologies

Well, what’s a “real-world graph?” In the absence of customer data — I don’t have any — we can try simulating several parameterized families of graphs instead of just guessing. I implement two families.

random

A graph with n vertices. Any pair v₁, v₂ ∈ V are connected with probability p. Notably, these graphs have a nondeterministic total connectivity — there’s always a p^2ⁿ chance of getting a complete graph! — but that’s just a reason to simulate repeatedly.

tricky

“Tricky” graphs follow a construction from Lavrov designed to force the clever algorithm into arbitrarily bad vertex covers. Instead of taking a number of vertices, the construction starts with integers a and k ≤ a; then

On one side of the graph, put n vertices, for some (large) n. Call the set of these vertices A.
On the other side of the graph, put k − 1 “blocks” of vertices, numbered B₂, B₃, ..., B_k. Block B_i will have ⌊n/i⌋ vertices.
Each vertex in A gets one edge to a vertex in B_i, and they are distributed as evenly as possible: each vertex in B_i ends up with either i or i + 1 neighbors in A.⁴

What makes it tricky? Initially the highest-degree vertices are in B_k. When clever has included those in the cover V_req, the highest-degree vertices are in B_k − 1. This continues until V_req = B₂ ∪ B₃ ∪ ... ∪ B_k, even though there’s a smaller vertex cover staring right at us: A!

These graphs have a ⋅ H_k vertices, where H_k is the kth harmonic number: ∥A∥ = a and ∥B_i∥ = (i⁻¹)a.

There are potentially many more families to explore. Like I mention above, stars might capture HubSpot’s ontology for built-in types well: it’s a CRM, so pretty much everything associates, directly or indirectly, with a Company. Graphs composed of stars, joined at the leaves, might reflect HubSpot customers using custom objects to hang subontologies off of the built-in types: a Company’s association with a Deal indirectly associates it with a collection of Deal-specific custom object types.

I considered testing a “small-world” family of graphs, with vertices highly-adjacent to “neighbors” and adjacent to non-“neighbors” with some lower probability, but I’m not sure it’s relevant to the HubSpot problem definition. There’s no natural concept of “neghbors” among HubSpot object types. Remember: customer “configurations” are subgraphs of a complete graph of types. Emergent graphs — especially physical networks — may well have small-world properties, but it’s less clear why a subtractive configuration-selection process would yield them.

Weight schemes

The cost of requesting the objects of a HubSpot type is the number of members divided by the APIs request page size. How many objects of each type exist? Who knows! Like with graph families, it’s easier to simulate several of them than to evidence-free agonize over which is “realest.”

uniform: Assigns every vertex the same weight, unweighting the vertex cover problem.
random: Assigns each vertex a random weight on the half-open interval [0, 1).
degree-negative: A weight scheme where a vertex’s weight is negatively correlated with its degree. To keep weights positive, I use (d(v)+ϵ)⁻¹, where ϵ is a small positive constant to prevent divison-by-zero panics on disconnected vertices.
degree-positive: Each vertex’s weight is its degree.
degree-positive-superlinear: Each vertex’s weight is the square of its degree.

I expect degree-negative and degree-positive to reward and punish the clever algorithm, respectively. clever gobbles high-degree vertices into V_req oblivious to their weight. In one case that greedy strategy correlates with low weights, in the other case with high.

Project structure

Why reach for Go? My first instict was to use built-in benchmarking to compare algorithms. That is a cool tool (one of my favorite take-home interview hacks) but I don’t wind up using it. Runtime performance is just too dependent on implementation details; I’m better off spending my time building a graph package with a decent interface than, say, using separate graph implementations optimized for each algorithm.

There are other, better reasons to write Go. Static types prevent a suite of bugs I’d encounter in Python — Go’s a “when it compiles, it does what you mean” experience — and module management is simpler than in Typescript. The standard testing library is pleasant. godoc is built in, and linters abound.

The stand-out advantage, I found, is a convention: the standard Go project layout, which separates reusable library code in pkg subdirectories from applications in cmd, is well-suited to experimentation. I wound up with a project structure like this:

README.md
pkg
- graph
- cover
cmd
- 01-lavrov-clever
  - README.md
  - main.go
- 02-clever-vazirani
- 03-another-experiment

The simulation models depend on one another, but they’re independent of the experiments that use them. pkg/graph exports weighted and unweighted graphs, along with some known graphs used in tests. pkg/cover implements vertex cover algorithms on those graph types.

Both packages include tests. Testing is especially useful in pkg/cover, where it tests two kinds of correctness: that my code behaves how I expect it to, and that my expectations match the algorithm definitions in literature! By testing on known graphs (defined in pkg/graph/fixtures.go), I check my implementations match examples from papers. TestClever_Tricky confirms clever selects V_req = B like Lavrov claims; if it doesn’t, there’s some mistake in the implementation even if it yields valid vertex covers.

Experiments go in subdirectories of cmd. Each directory is space for notes, outputs, experiment-specific helper code, and so on. Because there’s no risk of one experiment impacting the others — there aren’t interdependencies in cmd — these are scratchpads.

In summary:

Put reusable simulation components in pkg.
Use unit tests to confirm your implementations against prior art examples.
Explore in cmd.

Next time I might reach for a scientific computing package like Gonum to aggregate data in experiments. It even ships with a graph package, albeit one suited for edge-weighted problems over vertex-weighted ones.⁵

Simulations

Any pair of experiments should be comparable at a glance. Absolute vertex cover weights are sensitive to graph topology and individual vertex weights, which makes it hard to compare an algorithm’s performance on a ten-vertex graph against another algorithm’s performance on a hundred-vertex graph.

Instead, since my goal is to compare algorithms, I measure relative cover weight against a baseline: vazirani. Because it’s a 2-approximation, it guarantees a bound on any algorithm’s relative performance: if it’s implemented correctly, nothing can do more than 50% better than vazirani.

In the heatmaps below,

-50 (teal) denotes a vertex weight 50% better than vazirani on the same graph.
0 (yellow) denotes a vertex weight at parity with vazirani.
50 (red) denotes a vertex weight 50% worse than vazirani. Worse performances are the same deep red — without a k-approximation, an algorithm can be worse up to the total weight of V!

Each cell averages ten relative performances: ten times, the simulation generates a graph G with the given parameters, then finds vertex covers on that G with the vazirani and tested algorithms.

For starters, we can visually confirm a behavior predicted in literature: Lavrov’s tricky graphs are designed to arbitrarily damage the clever algorithm’s performance.

As Lavrov suggests, the “clever” algorithm is tricked for large a, k. (Note: while k is an integer in Lavrov’s tricky graph construction, here it’s expressed as a multiple of the number of vertices in A.) Does the lavrov algorithm do better?

Indeed it does! Strikingly, lavrov performs just as well as vazirani on a uniformly-weigted graph. Upon reflection, I realize vazirani and lavrov are equivalent in a uniformly-weighted context: t(v) always goes to zero for u and v at every step, because both have the same starting weight!

To my surprise, clever outperformed vazirani on tricky graphs when vertex weights corresponded 1:1 to degree.

On reflection, this makes sense too. Any vertex cover of a degree-positive-weighted graph covers every edge, which means it has a minimum weight ∥E∥. By minimizing redundant coverage, clever approximates that optimal cover. Since vazirani is a 2-approximation, the optimal cover is at most 50% better.

What if vertex weights are superlinearly positively correlated with vertex degree?

Huh! To my surprise, except for a low-n low-k blip, clever still generally outperforms vazirani. Even weirder:

I expected degree-negative weighting would reward the clever algorithm for picking high-degree vertices, but it doesn’t!

`lavrov` overview

A weight-naïve version of vazirani, lavrov achieves parity when it isn’t punished for weight-naïveté (when weights are uniform). Otherwise, vazirani’s performance lower-bounds it; you’d only prefer lavrov if you need its programmatic simplicity.

Weight/Topology	`random`	`tricky`
`uniform`
`random`
`degree-negative`
`degree-positive`
`degree-positive-superlinear`

`clever` overview

As expected, clever does poorly on tricky graphs with uniform and random vertex weights.

Unexpectedly, it performs quite well on tricky graphs where vertex weight correlates positively with vertex degree! In domain-specific terms, that suggests clever is good choice if your HubSpot account’s most-associated types are also your most numerous collections.

I still gut-distrust this conclusion. It’s just so easy to think up a small but plausible associations graph where clever’s dismal because, say, you have hundreds of thousands of Contacts.

Weight/Topology	`random`	`tricky`
`uniform`
`random`
`degree-negative`
`degree-positive`
`degree-positive-superlinear`

If you want to poke around the experimental results, check out the full set of interactive graphs. If you want to reproduce them or inspect my implementations, see the source code on GitHub.

Zito, Michele. “Vertex Cover.” (2005). Also see Lavrov (2020).↩︎
Lavrov, Mikhail. “Lecture 36: Approximation Algorithms” (2020). 2-3. Note: I’ve modified the definition to share variables with the other algorithms.↩︎
Vazirani, Vijay V. Approximation Algorithms. Vol. 1. Berlin: Springer, 2001.↩︎
Lavrov, Mikhail. “Lecture 36: Approximation Algorithms” (2020). 2-3. Note: I’ve modified the definition to share variables with the other algorithms.↩︎
Since there’s a minimal Steiner tree weighted-edge equivalent to this vertex cover problem — see my addendum in Graphs at Work — I could compare Steiner tree algorithms using gonum.org/v1/gonum/graph.
There are advantages to reimplementing graph, though. For example, clever and lavrov both recurse into searches on subgraphs, so my graph package defines an easy-to-call (*Weighted).Without(removed Vertex) function.↩︎

Graphs at Work

2022-09-03T00:00:00Z

Graphs at Work« blog 2022-09-03

Graphs at Work

You might never invert a binary tree, but graph theory — and graph algorithms — worm their way into software engineering, whether you recognize them or not. This problem wormed its way into my brain last week, where it reminded me API engineering isn’t all just flat-mapping responses. Conceiving this as a graph problem doesn’t just guide implementation: it determines the product’s attributes, which will impact its direction.

One of Sequin’s products is a two-way integration betwen our customers’ HubSpot accounts and their Postgres databases, using the HubSpot API to live-update the database and forward writes to Postgres back to HubSpot. There’s a variety of entities in HubSpot: Companies, Contacts, Deals, and all the custom object types our customers’ hearts desire. (Want to index Cars in HubSpot? Make a custom Car type.) Our customers might have thousands of Contacts, hundreds of Companies, and so on.

Of course, these entities aren’t islands; a Contact works for a Company, a Deal binds a company and is negotiated by a Contact, and so on. Rather than capturing every possible relationship on each type, HubSpot has a separate associations model for connecting two objects. For example, an association might declare “Contact Lukas Schwab is associated with Company Sequin.” Those associations are always bidirectional; if I’m associated with Sequin, Sequin’s also associated with me.

Because associations are a core part of HubSpot’s product model, Sequin’s sync needs to scrape them into Postgres. HubSpot’s API makes that a little tricky; I’ll try to explain this in brief, because it’s important to undertanding the task at hand.

If you want to fetch all associations between Contacts and Companies from the HubSpot v3 API, you can use either of two endpoints:

/crm/v3/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}
This tells you all of the associations between a single object — specified by fromObjectType and fromObjectId — and objects of toObjectType. For example, you could GET /crm/v3/objects/contact/1860/associations/companies to list all Companies associated with Contact 1860.
Of course, if you have 10,000 Contacts, you’ll have to call this endpoint 10,000 times to get a complete picture of Contact ↔︎ Company associations. If you also want associations between Contacts and Deals, you’ll have to make another 10,000 requests with toObjectType set to deal.
/crm/v3/objects/{fromObjectType}
This endpoint for listing objects of fromObjectType, 100 at a time, has a handy associations parameter. When specified, the response includes all associations with objects of the specified types!
If you have 10,000 Contacts and you want to get Contact ↔︎ Company and Contact ↔︎ Deal associations, 100 requests will do the job.¹

Because HubSpot limits each customer’s daily API usage, the second endpoint is the much more desirable access pattern. Still, we have to pick a request strategy. Given the association types a customer wants synced to Postgres — type pairs like Contact ↔︎ Company — what fromObjectTypes should Sequin list? The project requirements are to design a request strategy which

Systematically pulls all associations the customer desires, specified as pairs of types.
Minimizes the number of requests to HubSpot’s API.

For instance, a customer’s desired association types might look like this:

From	To
Contact	Company
Deal	Contact
Company	Deal
Company	Car
Company	Policy
Car	Policy
Company	Owner

But it’s easier to start thinking about a simpler configuration:

From	To
Contact	Company
Deal	Contact

This is when I recognized graphs would be good visualizations for request strategies. Make each unique type (in this example, Contact, Company, and Deal) a vertex; then the associations we want to fetch are edges on the graph. The customer configuration is essentially an adjacency list!

Coloring the types you’d list with GET requests gives you a visual representation of each request strategy.

Request strategy	Visualization
`GET` contacts `associations=[company]` `GET` deals `associations=[contact]`
`GET` contacts `associations=[company, deal]`
`GET` deals `associations=[contact]` `GET` companies `associations=[contact]`

Now that you’re working with graphs, you have access to a pithier expression of the problem. The set of desired associations defines a graph G = (V,E), where the edges E are desired associations and the vertices V are the HubSpot types involved. Our search for a “request strategy” is a search for an optimal subset V_req ⊆ V such that every e ∈ E is incident upon — touching — at least one object type v ∈ V_req.

All of the strategies in the table above satisfy that condition, but one of them — and only one valid strategy for that graph! — only lists objects of a single type, Contacts.

There isn’t always a single-type silver bullet. For some graphs, no single vertex is incident on every edge.

You’re faced with the algorithmic question I faced on Friday: given any graph like this, how can you systematically produce a valid minimal strategy?

Cracking the graph

As a rule of thumb, greedy graph algorithms — approaches which repeatedly apply a single heuristic to make local decisions — are easier to stomach. Because the heuristic is the crux of the implementation, you can focus on documenting that. With any luck, it won’t give your code reviewer a headache.

Luckily, there’s an intuitive greedy heuristic for selecting V_req from V! Consider your start state and end state:

When your algorithm starts, you have an empty V_req; you don’t know what types to request. By definition, the set of edges E_req incident on V_req is empty: no vertices, no edges.
When your algorithm ends, E_req = E: every edge in the graph is incident on V_req.

At any intermediate step, what change to the V_req you’re building makes the most progress towards that end state? The one that adds the most new edges in E to E_req!

More formally, given an associations graph G = (V,E),

Let V_req = {}, E_req = {}.
While E ≠ {}:
- Find v ∈ V with the greatest number of incident edges.
- Add v to V_req. Add the incident edges to E_req.
- Remove v from G.
Return V_req.

G shrinks with each step, so this is guaranteed to terminate for any finite associations graph (and, since there’s a finite limit to the number of object types in a HubSpot account, G is guaranteed to be finite — phew). I’ll call this the clever-greedy algorithm, after Zito.²

This has a straightforward — if inefficient — recursive implementation,³ but don’t sweat it if you don’t want to read code. You can use the visualizations to see successive applications of the algorithm chip away at G as it builds the set of types V_req.

Step	V_req	E_req	Evaluation
0	∅	∅	Company and Deal both have three incident edges. Take Deal.
1	{Deal}	Deal↔︎Contact Deal↔︎Company Deal↔︎Policy	Company has two incident edges; Contact and Policy each have one. Take Company.
2	{Deal, Company}	Deal↔︎Contact Deal↔︎Company Deal↔︎Policy Company↔︎Contact Company↔︎Policy	There aren’t any more edges in G, so we have a valid V_req!

Problem solved, right? You reframed the problem in terms of graphs, which led you to a greedy algorithm — just a couple-dozen lines of code — that’ll produce a valid, seemingly minimal request strategy every time.

There’s one issue. In practice, what’s optimal? What do the project requirements say about optimality?

Systematically pulls all associations the customer desires, specified as pairs of types.
Minimizes the number of requests to HubSpot’s API.

Are you minimizing API usage with the greedy strategy? Not necessarily! You’re minimizing the number of types you have to list, true, but the API cost of listing a type is nonuniform. Because each GET request only returns a page of ≤100 objects, the number of API requests we have to make for a strategy scales with the total number of objects of the types in our strategy.

Do fewer types mean fewer objects? That’s not an unreasonable guess if you know nothing about the system, but you don’t have to look far for a counterexample. Consider a tweaked version of our initial simple associations graph, where you have additional info about the number of objects in HubSpot: there are 300 Contacts, 100 Companies, and 100 Deals.

Strategy	V_req	API cost
	{Contact}	300 contacts. ∴ Three requests.
	{Deal, Company}	100 Deals. 100 Companies. ∴ Two requests.

The first strategy is simpler — it only involves listing objects of one type — but it’s costlier. The project requires optimizing API cost, not strategy simplicity!

Can you get there by modifying the greedy strategy? That’s not clear. The simple heuristic (“pick the vertex that adds the most new edges in E to E_req”) also needs to factor in each vertex’s cost. Sometimes a voluminous type is worth requesting because it’s incident on many edges; sometimes it isn’t. In complex graphs, it’s hard to figure out locally whether a given vertex will wind up being a good pick or a bad one. Hmm.

The graph cracks back

Looks can be deceiving! This puzzle is a minimal vertex cover problem disguised as a HubSpot API question. Introducing cost minimization makes it a weighted minimal vertex cover problem. With or without weights, the optimization problem is NP-hard: as far as the career math-freaks know, there isn’t a solution that works in polynomial time. Any general algorithm for truly optimizing your HubSpot associations-fetching is going to be really, really slow. Bummer!

If you don’t care about performance, there’s a brute-force solution in O(2ⁿ):

Filter the 2ⁿ subsets of V for vertex covers of G, the valid API strategies.
For each, calculate the API cost.
Take the lowest-cost strategy.

What’s wrong with the clever-greedy algorithm? Provided a graph designed to trip it up, it can’t even guarantee results within any constant-factor multiple of the optimal weight!⁴ There are other greedy algorithms for vertex cover guaranteeing results no larger than twice the minimum (2-approximations).⁵ My favorite is Savage’s, which simply prunes the leaves from a spanning tree.⁶

It stands to reason that introducing weights makes this harder; unfortunately, since we’re working with weighted vertices, you can’t just apply Savage’s reasoning to a minimum weighted spanning tree (which you could build with Prim’s algorithm). There are 2-approximation algorithms for weighted vertex cover, like this one adapted from Vazirani:⁷

2.11 Consider the following algorithm for the weighted vertex cover problem. For each vertex v, t(v) is initialized to its weight), and when t(v) drops to 0, v is picked in the cover.
Algorithm 2.17
Initialization:
V_req ← ∅
∀v ∈ V, t(v) ← weight(v)
While V_req is not a vertex cover do:
Pick an uncovered edge, say (u,v). Let m = min (t(u),t(v)).
t(u) ← t(u) − m.
t(v) ← t(v) − m.
Include in V_req all vertices having t(v) = 0.
Output V_req.

This has essentially the same halting condition as our greedy algorithm, but it decreases a vertex’s weight t(v) as its neighbors are added to the eventual set cover V_req. Intuitively, a vertex with a high initial weight is unlikely to ever hit t(v) = 0, so it’s unlikely to wind up in V_req. An algorithm like Vazirani’s might make a fine solution for getting an okay minimization.

Is it the solution for you? Like the earlier question about whether a “small” strategy was optimal, this comes down to the requirements — implicit and explicit — of the project. The pragmatizing effect of project requirements is really, in some sense, what sets software engineering apart from computer science.

This puzzle explicitly requires you minimize API usage. Unfortunately, neither the clever-greedy algorithm nor Vazirani’s algorithm guarantee optimal outcomes. Vazirani guarantees at worst a 2-approximation of the optimal strategy, whereas the clever-greedy algorithm can’t even promise a constant factor for an unweighted set cover. Practically, though, worst-case performance might not matter! User-provided lists of assosiations to fetch usually won’t be the graphs that trick clever-greedy into poor outcomes. If customer concerns are well-isolated, an adversarial customer can force your algorithm into an inefficient solution… but they can’t impact anyone else’s experience. To improve the customer experience, what you need to understand is the distribution of strategy performances for a given algorithm on real-world graphs, not the theoretical worst case. Here clever-greedy might be better, even if it assumes constant vertex weights.⁸

Instead, implicit project requirements — values inherent to the engineering task — could reasonably determine what you implement. New engineers will have to read and modify the algorithm you choose; because that time trades off with other work, your customers may be better-served holistically if you pick a simple, maintainable algorithm here over a strong n-approximation. That’s the principle behind minimizing tech debt.

Lehman describes the evolution of programs through a system of three nesting levels:

S-programs implement specifications: “return the lowest common multiple of two integers.”
P-programs, made up of S-programs, strive to perform optimal behaviors: “play chess.”
E-programs, made up of P-programs, “mechanize a human or societal activity.” Software prducts, by nature of having collaborators and users, are E-programs.⁹

The HubSpot project requirements ask you to design a P-program. At several junctures, feeling comfortable working with graphs helped break that task into S-programs: graphs gave us a natural visualization, which helped design a greedy algorithm. Recognizing a well-studied problem in graph theory, the vertex cover, exposed flaws in that greedy algorithm — the adversarial cases — and led to the conclusion all known optimal solutions are inefficient.

Critically, though, graph theory is handy for understanding the relationship between P-program and E-program. Discovering an existing 2-approximation like Vazirani’s might be the difference between a worthwhile feature and a waste of time. Having the vocabulary to study the associations graphs you see in practice lets you study whether worst-case performance matters, or if maybe something simpler (unweighted) will usually do better.

In summary, this isn’t just engineering navel gazing; recognizing a minimum weigted vertex cover problem when you see one impacts your bottom line. Losing engineering hours to battling P ≠ NP or reading abstruse optimizations won’t keep the lights on.

Brush up on your graph theory, and wield it, but remember you’re building a product — don’t miss the forest for the trees.

I didn’t recognize the weighted vertex cover problem at first. Intead, I worked through expressing this problem as two other NP-hard optimization problems, distrusting my own conclusions. Here’s a bit more math for anyone curious!

My first theory was that I could calculate the minimum edge cover of a modified line graph L(G) — a task much easier than NP-hard — but that was wrong. For our problem, the edges in L(G) are non-independent; you have to take or leave all the Contact edges as a batch. If I successfully reduced minimum vertex cover to minimum edge cover, I would suddenly be very, very popular.

Fiddling with line graphs led me to this more fruitful representation of the three-vertex weighted example discussed above:

The root is an artificial vertex. It’s connected to each vertex in V by an edge weighted by the cost of listing all objects of that type. The final row of vertices represents the association types we want to fetch. An association vertex’s parents are the types at either end of the association. Once you’ve paid the cost of listing Contacts, you have all the associations involving contexts; that holds for any type, so all of these edges are weighted 0.

The optimal request strategy is a subgraph spanning the blue terminal vertices, the subgraph with the smallest total edge weight that does so. Think of it this way: the bottom row of vertices represents the data we need to get to. We can either go through (list) Deals to get the Contact↔︎Deal associations, or we have to go through (list) Contacts.

We’re looking for a minimal Steiner tree in a directed graph — like a minimal spanning tree, but free to ignore non-terminal vertices. The terminal vertices are in blue above: the root and the desired association types.

Certain properties of these graphs make them a simpler than the general class of Steiner tree problems (namely, their fixed height guarantees that they’re pseudo-bipartite), but that doesn’t save it from NP-hard status.

Computing minimum-cost r-Steiner trees is NP-hard for r ≥ 4, even if the underlying graph is quasibipartite. The complexity status for r = 3 is unresolved, and the case r = 2 reduces to the minimum-cost spanning tree problem.¹⁰

I’ll spare you the details, but r here is one plus the highest degree of a vertex in G — three for this simple example case, and often greater than or equal to four in practice.

Still, I wondered if there was some other relevant feature of these graphs that simplifies the problem. I looked for a more familiar representation, and found one: a weighted set cover.

For brevity, I’ll use shorthand for the HubSpot types; instead of Contact, Company, Deal, etc., I’ll write A, B, C, and so on. You’re looking for a number of associations specified by unique unordered pairs of those types; for example, {(A,B), (B,C), (B,D), (C,D)}.

This set of pairs is the universe 𝒰 to be covered. The sets doing the covering represent the endpoints we can call: for each type, the associations in 𝒰 incident on that type:

A_set = {(A,B)}
B_set = {(A,B), (B,C), (B,D)}
C_set = {(B,C), (C,D)}
D_set = {(C,D)}

These constitute a family 𝒮 of subsets of 𝒰. The set cover problem is to find a minimal number of members in that family such that their union spans 𝒰, analogous to the optimal HubSpot API strategy. In this case you can get all desired associations by listing objects of two types: B_set⋃C_set = {(A,B), (B,C), (B,D)}⋃{(B,C), (C,D)} = {(A,B), (B,C), (B,D), (C,D)} = 𝒰.

Bad news: finding a minimal set cover is NP-hard.

As you might imagine, the weighted set cover assigns a weight to each member of 𝒮 and demands you minimize the weights. For this problem, you’d assign a weight A_set with the API cost of listing all objects of type A… but don’t bother: solving weighted set cover isn’t any easier.

Interestingly, there are exceptions! Finding a minimum set cover on 2-sets is equivalent to finding a minimum edge cover, which is easier. Tugging on this thread¹¹ led me to discovering the weighted vertex cover problem, which exactly matched my original project definition.

That match confirmed it: any weighted vertex cover problem can be expressed as a question about HubSpot associations, so optimizing this HubSpot API strategy is, in fact, NP-hard.

A request for a page of Contacts, with Company and Deal associations included, takes this form. Note the weird URL-encoding.

curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/contacts?limit=10&associations=contact&associations=deal&associations=company&archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

↩︎

Zito, Michele. “Vertex Cover.” (2005). Also see Lavrov (2020).↩︎

Here’s an Elixir implementation of the greedy strategy for finding V_req:

@spec greedy_V_req(list({String.t(), String.t()})) :: list(String.t())
def greedy_V_req([]), do: [] # Base case: no edges in G.

def greedy_V_req(graph) do
  # Greedily take the highest-degree vertex.
  taken =
    graph
    |> Enum.flat_map(&Tuple.to_list(&1))
    |> Enum.frequencies()
    |> Enum.max_by(fn {_k, freq} -> freq end)
    |> elem(0)

  # Remove taken from graph; recurse.
  subgraph =
    graph
    |> Enum.filter(fn pair -> taken not in Tuple.to_list(pair) end)

  [taken | greedy_V_req(subgraph)]
end

&greedy_V_req/1 receives graph as an adjacency list of order-agnostic tuples. To specify the example graph:

greedy_V_req([
  {"Contact", "Company"},
  {"Contact", "Deal"},
  {"Deal", "Company"},
  {"Policy", "Deal"},
  {"Policy", "Company"}
])

This implementation is inefficient — O(|V|²) — but it isn’t worth optimizing.↩︎

Lavrov, Mikhail. “Lecture 36: Approximation Algorithms” (2020). 1-2.↩︎
Zito, Michele. “Vertex Cover.” (2005). Also see Lavrov (2020).↩︎
Savage, Carla. “Depth-first search and the vertex cover problem.” Information processing letters 14, no. 5 (1982): 233-235. A very tidy three pages.↩︎
Vazirani, Vijay V. Approximation Algorithms. Vol. 1. Berlin: Springer, 2001. My adaptation renames C to V_req for consistency with earlier examples, and removes steps updating c(e) — our problem doesn’t require we track edge “costs,” part of Vazirani’s exercise.↩︎
I want to test this on random graphs. For now, consider the strategy Vazirani’s algorithm picks for this simple weighted graph:
Notably, this four-request solution is still a 2-approximation of the optimal 2-request solution from running clever-greedy on the unweighted graph. You could tweak Vazirani’s last step (“Include in C all vertices having t(v) = 0”) to guard against trivially-unnecessary additions like this.
Counterintuitively, one 2-approximation algorithm for the unweighted set cover intentionally includes vertices which redundantly cover a given edge; doing so thwarts the clever-greedy adversarial case.↩︎
Lehman, Meir M. “Programs, life cycles, and laws of software evolution.” Proceedings of the IEEE 68, no. 9 (1980): 1060-1076.↩︎
Könemann, Jochen, David Pritchard, and Kunlun Tan. “A partition-based relaxation for Steiner trees.” Mathematical Programming 127, no. 2 (2011): 345-370. The introduction to this paper is the clearest overview of Steiner trees I found.↩︎
Thanks to David Richerby for answering “Set cover problem with sets of size 2” (July 5, 2017).↩︎

Technical Writing for Sequin

2022-08-27T00:00:00Z

Technical Writing for Sequin« blog 2022-08-27

Technical Writing for Sequin

I joined Sequin earlier this year. I joined in part because they promised I could wear many hats; they’re true to their word, and I’m moonlighting in content marketing!

I’m focused on improving two aspects of my technical writing:

Writing conversationally. My usual written style’s a little stilted, but someone’s more likely to read your marketing blog if you seem, uh, cool.
Explaining visually. Whimsical is a solid diagram editor; I’m using it outside of work.

See Blogging with TikZ, State Machines via Jorge Luis Borges, and Processing PDFs with Cloud Functions for examples of (loosely) technical writing outside my work.

I’ll keep this list up-to-date instead of cross-posting articles.

What to do without HubSpot Webhooks: Published July 11, 2022.; A review of shortcomings in HubSpot’s CRM Webhooks API. Webhooks should be a neat system for triggering event-driven tasks outside HubSpot, but these have a number of shortcomings. So does HubSpot’s low-code automation system, a commonly-recommended alternative.
Stripe metered billing, simplified: Published August 26, 2022.; Stripe’s metered billing strategy lets you bill customers according to how much they use your product. That should let you tether your billing to the value your product provides, at the cost of requiring you constantly report cusotmer usage to Stripe. Reading Stripe data through Sequin saves an API call in each reporting cycle.

Managing Emails from Recruiters

2022-07-06T00:00:00Z

Managing Emails from Recruiters« blog 2022-07-06

Managing Emails from Recruiters

I have a GitHub profile, so I’m doomed to receive emails from tech recruiters until the end of time.

Until recently, I just archived emails that didn’t interest me. An unfortunate proportion of the recruiters take this as an invitation to email me again (and again) to ask if I’ve seen the first. This is a bad strategy on their part.

I’ve taken to sending a short, generic template email explicitly declining their invitations:

Hello––thanks for reaching out!
I’m not looking for new job opportunities at this time, but I’ve read and labeled your email so I can find it if my priorities change.
Best of luck in your search,
Lukas
labelRecruiting

“Read and labeled?” Sometimes it really is useful to have these emails categorized:

When you’re selling a SaaS product.
When you’re looking for examples of strong/weak recruiting emails.
When you’re hiring for an effective recruiter.
When (if!) you really do become interested in the advertised role.

As you might’ve noticed, I include a line in white text at the end of my template: labelRecruiting.

This is the crux of my trick: Gmail filters are evaluated for outgoing mail. I set up a filter on label:sent labelRecruiting that applies the label Recruiting.

Image of the Gmail query panel: label:sent captures all sent mail, and labelRecruiting searches email text for that token.

It takes two clicks to fill the template response. When an inbound email is especially good or especially off-base, I add a short note to that effect before sending. The filter notices the lazily-hidden keyword and applies my label.

As much as it chafes to dignify plainly spammy recruiters with a response, replying does usually prevent pushy follow-ups. The underlying mechanism — using a hidden string to trigger filter behavior — should be useful whenever you need to bulk reply-and-categorize. Let me know if you think of something clever!

Tech Debt and Taxes

2022-03-14T00:00:00Z

Tech Debt and Taxes« blog 2022-03-14

Tech Debt and Taxes

In Reframing Tech Debt, Leemay Nassery suggests framing technical housekeeping positively — as building “tech wealth” — to convince business and product stakeholders it’s worthwhile.

If I were one of those stakeholders, a self-professed customer-obsessive, I’d balk (rightfully!) at the idea of a secondary system of value independent from the user experience. “What does ‘tech wealth’ mean for a customer?” Fair question!

I think a negative framing is more useful here, but Nassery’s suggestion that, say, refactoring a program yields a resource to reinvest gets at the issue with calling it “debt.” Technical “debt” sounds like a fixed cost that can be deferred; more accurately, we should say debt exacts an ongoing tax from go-to-market teams. The costs of quick development may be hidden, but they aren’t externalized.

If you make implementation shortcuts in the name of product velocity, but you don’t have the discipline to clean them up, those shortcuts will eventually be counterproductive to the speed-of-delivery you hoped to prioritize. Changes to a codebase are more often integrative than strictly additive: they have to contend with the code that’s already there. Writing sloppy code today means writing code slowly tomorrow.

Imagine a minor update to to a webhook implementation. If the webhook’s baseline behavior is undocumented (tech debt!), or its input validation is rickety (tech debt!), verifying the change is a herculean task of either retroactively establishing that baseline with unit tests or, worse, manually testing sample inputs. Even though the update’s minor and implemented well, the QA process spends time on the multitude of poorly-implemented cases just because it modifies debt-addled code.
Imagine you want to release a new billing page to admin users. If the permissions module (which canonically establishes whether a given user is an admin) has an unclear interface, your engineer’s more likely to initially misuse it. Either they’ll catch the mistake, then burn time debugging it, or you’ll have a product permissions bug in production. Either way, a dark cloud over what should be a joyous feature release, all because it uses debt-addled code.
Imagine you’re testing a new feature, and you want to release it to a beta testing group behind a feature flag. Your frontend engineer has added n feature flags already; why’s this one taking them so long? Maybe they’re stuck testing 2^n + 1 possible configurations because your flagged features are mutually-dependent.¹ Yikes!

Even unused and unmodified code taxes productivity. If you have a deprecated service, changes to its dependencies still require changes in the disused service! At its most insidious, this dynamic prevents you from improving joint dependencies with the highest-value parts of your product, where inefficiencies are really costly.

In each of these cases, tech debt’s the common enemy of the product stakeholder and even the most navel-gazing, customer-indifferent engineer. While the underlying debt isn’t addressed, the stakeholder pays a tax — as a delay, or as systematic under-verification that’ll eventually yield bugs.

This dynamic is particular to API and product debt — unnecessary complexity in how parts of the system interact with each other (interface and data model design, documentation, and testing practices) or the space of customer states (feature flags and billing). These forms of debt tax new projects in proportion to those projects’ complexity; big projects and radical changes in product behavior are proportionally punished. Of course, not all “tech debt” should be prioritized this way; poor database performance might usually be considered debt, but it’s less likely than an unexpressive API to derail your next feature.

The usual refrain — including in Nassery’s article — is to preallocate blocks of time for building tech wealth. The “tax” translation from tech into customer impact should let a team prioritize specific tech debt initiatives, according to the same criteria as features.²

Unsurprisingly, it falls to engineers and their managers to use this framing device effectively.

If an element of tech debt really can’t be translated to customer impact, even when taking tech tax into consideration, deprioritize it.
Keep a shared list of known issues. This can be simple: a short name, a quick description, and a way to voice agreement.
Measure tech tax while you work. How much time did you burn grappling with tech debt? Dealing with unexpected integration or testing issues? Associate the tax with an underlying issue (“known-bad permission API: one day”) and aggregate costs across projects.
Keep engineering leaders abreast of implementation details and the stumbling blocks therein. If individually-contributing engineers aren’t involved in early planning, it’s a manager’s or tech lead’s responsibility to explain the relationship between tech debt and their team’s productivity.
If the best you can do is preallocate blocks, try to allocate time early in the planning period rather than at the very end! An allocation is easier to justify if it yields improvements in the same iteration. Leave enough time before the quarterly retrospective that you have something to show for your efforts.

Business and product stakeholders can take some proactive action.

Clean up after experiments. Suppose you test a new billing model with a handful of customers, but ultimately decide against it. If you roll those customers into one of the pre-existing tiers, engineers can remove the experimental code to leave billing as simple and inspectable as when the experiment started, and customers love free upgrades!
Negotiate firm sunset timelines for deprecated features. Ideally, keep them short. Ensure users who postdate a feature’s deprecation won’t start to depend on it; usage should dwindle before feature support ends.
Practice empathy: engage your engineers over why — not just whether — a project runs late or turns out buggy. If you spot common issues, speak up! Bell Labs researcher Richard Hamming credits scientists in other departments with solving his resourcing struggles.
Every time I had to tell some scientist in some other area, “No I can’t; I haven’t the machine capacity,” he complained. I said “Go tell your Vice President that Hamming needs more computing capacity.” After a while I could see what was happening up there at the top; many people said to my Vice President, “Your man needs more computing capacity.” I got it!
This should help you hit your targets, and it’ll definitely make you friends.

The issue with “tech debt” and “tech wealth” is that they underemphasize software’s impact on a company’s agility, its ongoing ability to adapt to serve its users’ needs. Without recourse to customer value, advocating against technical debt means advocating for a separate and competing system of value, something business and product stakeholders are right to treat with skepticism.

Emphasis on the productivity impact makes technical debt expressible in the primary system of value, where it’s comparable against — and can be prioritized over — any other company initiative.

Process Plants: A Handbook for Inherently Safer Design (Kletz 1998) reminded me of this essay. A process plant designer can intervene to prevent hazards (e.g. a “snakepit” plant layout), but investors don’t value hazard mitigation for its own sake. Quoting Kirkland,

This cannot all be the fault of the “money men” and their failure to understand us. It is often much more our inability to express ourselves in a language they can understand.³

I’m more optimistic than Kirkland. I think the “money” stakeholders do understand hazards, but that they’re better-equipped to predict and prioritize money. To that end, Kletz offers napkin math:

Remember that if it costs $1 to fix a problem at the conceptual stage, it will cost
about $10 at the flowsheet stage,
about $100 at the line diagram stage,
about $1000 after the plant is built,
about $10,000 to clean up after an accident.⁴

Software could use some equivalent with costs in various stages of planning, development, and deployment. “Hazard” may be a better analogy than “tax” for describing the running cost of technical debt.

Jamie Brandon discusses technical debt in terms of a team’s “complexity budget.” That post argues complexity compounds rather than exacting a tax:

Complexity limits how much of the system can fit into the heads of the developers, and in doing so breeds more complexity. Every time you are forced to do something ugly in one place because of existing ugliness in another place you are feeling this cost.

Moreover, complexity isn’t linearly costly: at certain thresholds, a small complication may dramatically impact your effectiveness. Conversely, when the team is small — maybe it’s just you! — and the program is simple, complexity seems free. That’s what makes technical debt so pernicious!

Worse, there are cliffs in the cost. As soon as a particular subsystem cannot fit into the head of a single developer there are huge additional overheads for communication. Opportunities for improvements or simplification are missed because no one person can see all the parts of the problem.

In hindsight, “interest” is a better extension of the debt analogy than “tax.” Avery Pennarun follows that terminology to extend the metaphor even further: differentiating between high- and low-interest technical debt, describing debt-income ratios (a better formulation than my sketchy footnote calculus), and so on.

Take the time to keep your feature flags mutually independent, even if that means running migrations to split or merge flags; make invalid states unrepresentable. If you don’t, each new flag effectively doubles the user interface surface you design and test.↩︎
Development acceleration should have a double-integral relationship to the value delivered by new development, but expressing this accurately would require some complex discounting.
Imagine you can divide your fixed engineering time in a quarter between t_debt and t_feat. Customer value delivered looks something like (v+t_debt) ⋅ t_feat, where v is your initial product velocity. As t_feat approaches zero, the team spends all of its time preparing to deliver value… but none of its time actually doing so.
This model is short several coefficients, but hopefully you get the idea.↩︎
Kirkland, C. J. The Channel Tunnel: Engineering under Private Finance — Innovation or Frustration (London: Fellowship of Engineering, 1989). Quoted in Kletz, page 157.↩︎
Kletz, Trevor. Process plants: A handbook for inherently safer design. CRC Press, 2010. Page 165. For specific examples of how “chang[ing] early” saves money, see page 202.↩︎

Collected Memories of Evans Hall

2022-02-13T00:00:00Z

Collected Memories of Evans Hall« blog 2022-02-13

Collected Memories of Evans Hall

Berkeley’s Evans Hall is unmitigatably ugly, inside and out, even at a great distance; to the discerning student, Evans is the ugliest structure on campus. Last week The Daily Californian reported it’s to be demolished as part of the University’s 2021 Long Range Development Plan.

This news is a long time coming. As the Daily Californian and SFGATE articles discuss, Evans has been widely disliked since it was built to Gardner Dailey’s design in 1971. The University floated a proposal to demolish Evans, and build a complex of low buildings on the site, in 2000; they punted that decision, citing budgetary constraints and a long line of competing seismic priorities.¹ Now Evans is on the docket again: it’s just unacceptably bad to look at.

This perspective is true, but it elides a deeper reading of the value in buildings. There’s a sort of memory in Evans Hall itself: of institutional dehumanization; of the studentry’s miniature ingenuity; of milestones, and major pests, in computer science; and of love (yes, even in Evans).

Always the best primer for a UC Berkeley building, The Loafer’s Guide notes Evans Hall’s

main stairwell balcony that faces a concrete wall, eye level with a bare fluorescent light fixture. This building, Davis, and Wurster are Neobrutalist, derived from the French word for “exposed concrete.” Before its completion, the Daily Cal printed an editorial entitled “Love can’t live in an ugly temple.” In addition to design and mechanical problems beginning Day 1 at “Fort Evans,” students began to paint and otherwise “adapt” the building. The “Death of Archimedes” and other unsanctioned artworks are worth checking out.²

John Rhodes, Professor Emeritus of Mathematics, remembers those “unsanctioned artworks” as a kind of antifascist gesture. The department was moved into Evans Hall in 1971, the year it was completed. Striving to do creative work, they felt consigned to a building so austere Rhodes found it dehumanizing.

Sometime after this seminar [on creativity in mathemtatics], I organized a one-hour talk in 60 Evans by an assistant professor in the architecture department entitled Fascism and Architecture, being as Evans Hall was despised by many as a dehumanizing workplace. The subject of the talk was the effect of architecture on politics and the spirit. I remember the speaker showed slides of Hitler waving to crowds from the balcony of buildings in Berlin.
After the applause abated at the end of this well-received talk, I passed out paintbrushes and paint cans. Even Sarah Hallam (senior administrative assistant of the Department for many, many years) grabbed a paintbrush. We rushed upstairs and painted some of the walls on the 7th to 10th floors.
Voilà! That’s how the “murals” got there. Some were painted by famous mathematicians — [William] Thurston and [Dennis] Sullivan. And I know La Mort de Galois on the 7th floor was painted by my son’s uncle, Jack Knutson. I thought perhaps some of you — young and old — might like to know the history of these paintings. I hope as many of them can be preserved as possible.³

The painting of Galois included here is dated December 1971; it may be La Mort de Galois, but I’m not sure. Sullivan also reports it was 1971.⁴ Remember, Evans was completed in ’71; the math department got mad fast. Sarah Hallam’s retirement in 1978⁵ is a latest date. In any case, I’ll try to photograph these murals the next time I’m on campus.

Evans was only painted its current institutional grey-green in the late 1990s, part of a renovation to prevent “large pieces of concrete […] falling off the face of Evans Hall without warning” (yikes).⁶ Apocryphally, the color was selected to blend the towering blight into the hillside; in practice, this marks the building as a place of great aesthetic shame. Béton brut was better.

In 2002, shortly after the repainting, first-year architecture student Alfred Twu ran the Evans Hall Coloring Contest: entrants printed, then recolored, folding scale models of Evans. First and second place went to trompe l’oeil panoramas, braver (and more surreal) imaginings of the hidden-in-plain-sight grey-green. The competition’s a great example of lighthearted Berkeley creative initiative.⁷ All contest submissions and the vote tally are here.

Of course, there’s more to Evans than its aesthetics. The departments it houses have astounding academic records; at work, I regularly use software spawned in its miserable greenish bowels. All that the comes from hardworking people, decades of students and academics, and the building is a testament to their experience inasmuch as they tell stories about its architecture.

The most elaborate such stories are in the CSUA Encyclopedia.¹⁰ Though it was written after the Computer Science Undergraduate Association’s relocation to Soda Hall, the Encyclopedia can’t disentangle the CSUA’s history and in-jokes from Evans itself.

Sometimes Evans was a nuisance:

elevatorP
Incantation to summon the elevator to the basement of Evans. Also, a means to subvert the security measures of Evans. Largely obsolete. Usually initiated from the tvi920c in the WEB print room.
In ye olden days, the public computers at Berkeley were grouped in two locations — in the WEB, located in the basement of Evans, and in E260, located on the second floor of Evans. The WEB was easilly accessible, but E260 was in an area of Evans which was locked in the evenings. Fortunately, the elevators on the south side of the building could be used to subvert the lackluster security measures; unfortunately, the elevators could not be called from the basement. elevatorP was initiated by students in the WEB to call out to their brethren in E260, and so summon elevators down to the WEB. Could also be used to gain access to the former CSUA office in E238.
Lock Collection
Holy CSUA artifacts. A set of locks rumored to have once adorned the secret north door of Evans Hall.
Little is recorded regarding how the Lock Collection might have come into existence, but according to quiet whispers, the north door of Evans might once have been a secret entrance to the hallowed lands of E260 and the CSUA office in E238. It has been suggested that, perhaps, if the lock on the north door went missing, it would have been easier for computer students to attain the computers of the second floor Evans, but archaelogical evidence is too scant to verify this. In all likelihood, the CSUA Lock Collection is actually composed of discarded locks and has no relation to this theory.
Three Evans Route
Secret path through the Evans Security Perimeter.
The administration tried very hard to maintain the Evans Security Barrier, manning the area with campus police and fixing the occasional mysteriously missing lock; one must given them credit for that. However, no one ever said they were very bright in their efforts. Take a case-in-point, the Three Evans Route.
Locked glass doors can be used to prevent student scum from entering the upper reaches of Evans without barring them from the twin nirvana of WEB and vending machines; no question about it. But, what if there were a room, say 3 Evans, which had two entrances, one on either side of these magic glass doors? If there were such a theoretical bone-headed design, it would be very simple to slip past the Perimeter, without having to wait for a doosher to notice the call of elevatorP.
Purely theoretical, and in any case the administration remembered to lock the outer Three Evans doors on occasion.

And sometimes Evans was a place to practice being a nuisance:

CSUA Bat (or CSUA Baseball Bat)
Holy CSUA artifact and the symbol of office for the Vice President. A black Louisville slugger, well-worn and loved. […] Particularly useful for obsoleting CRTs, gaining votes at politburo meetings, emphasizing points at general meetings, and hitting Evans to relieve stress (the last being its original purpose, according to rumors).
Fencing Club
Saber-rattling bunch of CS students nearly foiled by the UC police. Their motto: “don’t take a fence.”
Picking up fences and hauling them across campus is very funny. Explaining to UC police that you weren’t doing so is even funnier. Still funnier is getting a chain-link fence, dragging it through the Evans Security Perimeter, and then using it to block off the office of a beloved lecturer. Even the beloved lecturer will agree it’s as funny as anything, while plaintively asking that said chain-link fence please be removed.

And sometimes Evans was more than the sum of its nuisances. Deep in the CSUA Encyclopedia, in the “Poetry” entry, in a full-alphabet acrostick, there’s an extraordinary name.

i is for ikiru, Euphrasia Lavette Alzena Guri Scientia Ventura Ikiru; and then
j is for more ikiru, Alvera Ganbatte Gelasia Curvilinearjky… van Bezooijen

ikiru pased away in 2011. She took the additional “van Bezooijen” when she married Eric van Bezooijen (CSUA Encyclopedia contributor) in 1997. Eric’s eulogy for Euphrasia paints a brilliant and complicated picture, though reading it feels uncomfortably like an intrusion on something personal: “I could spend all day telling you the things she gave me.”

“How did I meet Euphrasia? We met in the early 1990s in Evans Hall room 260, a UC Berkeley computer lab, not the most romantic of all places.”

Actually, I think this captures the romance of architectural memory. Our common architectural referent — Evans — makes Eric and Euphrasia real, makes their experience seem immediate. Locating Eric’s story sets up an exchange of meanings: it marks Evans 260 as a place, in Marc Augé’s sense.¹¹ That means, in turn, Evans 260’s existence testifies to the reality of their experience. The place is an encounter between us, now, and them, then.

Moreover, Evans’s architectural memory is alive; students are still groaning about the green-grey, about the slow elevators, about the hulking blight. Evans isn’t a museum of the work that was done there; it’s a place to take part in the continuation of that work, to participate (even in some miniscule way) in the history that is the very basis for this memory.

Of course, participation means imagining something better. Working in Evans Hall every day made me unahppy, and would make me unhappy again. The University’s plan to raze Evans Hall is even older than the Coloring Contest plans to dress it up as nature. They’re right to prioritize current and future academics over campus history: UC Berkeley isn’t a museum, it’s a workplace.

One shouldn’t desperately conserve miserable places, but one should read buildings — beyond their aesthetics and functionality — for what they remember: our collective memory, in architecture.

Keller, Josh. “No Stirrings of Pride” in The Chronicle of Higher Education. (2007).↩︎
Dougherty, Carolyn. “The Existing Campus” in The Loafer’s Guide to UC Berkeley.↩︎
Rhodes, John. “A History of the Murals in Evans Hall” in Berkeley Mathematics Newsletter, Fall 2002 Vol. IX, No. 1. (2002)↩︎
Mosher, Lee and Bill Casselman. “What is… A Train Track?” in Notices of the AMS, Vol. 50, No. 3. (2003). According to Thurston, the mural-painting continued — over administrative protestation — after Rhodes’s start:
Last fall Sullivan wrote to Mosher: “In 1971 I was a guest of the University of California giving lectures in the Math Dept. At the same time there was a confrontation between the trustees and the graduate students et al. The latter planned to continue decorating the walls of the department by painting attractive murals and the trustees forbade it. At tea some students came up and invited me to join their painting the next day. I became enthusiastic when one bearded fellow [Thurston] showed me an incredible drawing of an embedded curve in the triply punctured disk and asked if I thought this would be interesting to paint. I said, ‘You bet,’ and the next day we spent all afternoon doing it.
[…]
Thurston wrote in a note to Mosher that the project “was in response to a little flurry with administration sanctions of some sort when John Rhodes painted the wall outside his office, I think with a political slogan related to one of the issues of the times (Vietnam war, invasion of Cambodia, People’s Park?).”
↩︎
Felde, Marie. “Hallam Bequest Benefits Math” in The Berkeleyan, March 13, 1996.
There’s some disagreement: a departmental chronicle reports Hallam retired six years earlier, in 1972. Interestingly, it also reports she was hired half-time by Evans — the building’s namesake — in 1936, for a $400 salary. See Mathematics at Berkeley: A History by Calvin C. Moore (2007).↩︎
Keller, Josh. “No Stirrings of Pride” in The Chronicle of Higher Education. (2007).↩︎
The Evans Hall Coloring Contest is theoretically interesting. Using scale models as a means of participatory architecture would be right at home in Log 50: Model Behavior — and it would stand out. The authors are largely focused on one-off canonical models (the stuff of architecture exhibitions) or models as devices for iterative studio design, and they all reference the same Borges story and enumerate the issue-theme multi-entendre.
The Evans Hall Coloring Contest’s paper models are cheaply reproduced, structurally simple, and accessible to nonprofessional participants.↩︎
Twu, Alfred and contestants. Evans Hall Coloring Contest Winners. (2002).↩︎
Twu, Alfred and contestants. Evans Hall Coloring Contest Winners. (2002).↩︎
Appelcline, Shannon with pictures by Eric van Bezooijen. Welcome to soda.csua.berkeley.edu, Now Go Home! or When Geeks Collide. (1994).
This is really a remarkable document; well worth the read if you have any affiliation with UC Berkeley Computer Science.↩︎
See vaguely Augé, Marc. Non-places: Introduction to an anthropology of supermodernity. (1992).↩︎

Hearst Hall: Continued Reading

2021-07-04T00:00:00Z

Hearst Hall: Continued Reading« blog 2021-07-04

Hearst Hall: Continued Reading

Writing typically hurries one of my interests out of its “all-consuming” phase and into “embarrassed retirement,” but Hearst Hall keeps coming up. I borrowed Kenneth Cardwell’s Bernard Maybeck: Artisan, Architect, Artist from the SF Public Library, and suddenly I’m all-consumed again.

That last post was heavy on my own, uh, sketchily-supported commentary. Cardwell, to my relief, supports a number of those claims. He dedicates the better part of a chapter to Hearst Hall—in Cardwell’s telling of Maybeck’s career, it’s prototypical of his first professional phase: redwood buildings, mixing gothic-evocative forms and prominent structural rhythms (especially of trusses and arches).

The book has its shortcomings. Cardwell praises unrelentingly. When a Maybeck building disappoints, it’s always because the owner had poor taste, or meddled in rennovations, or that Maybeck must’ve been too hands-off. Cardwell refuses to discuss Maybeck in relation to his contemporary architects besides, very briefly, a teacher (Louis-Jules André) and a student (Julia Morgan). Greene & Greene, who built the William R. Thorsen House in Berkeley, are conspicuously absent. John Galen Howard is treated like a bureaucratic gadfly. Cardwell, after all, dedicated much of his career to Maybeck alone: building an archive of Maybeck’s documents for Cal’s College of Environmental Design. Some auteurism is to be expected.

I won’t introduce any truly new ideas. Instead, I’ll string together excerpts (mostly, but not exclusively, from Cardwell, and with emphasis added) pertinent to the arguments in the last essay: that Hearst Hall’s bare structure is notable; that Maybeck’s philosophy stressed the adaptability of spaces, even to the point of accepting their destruction; and that Maybeck exemplifies certain foundational principles of modernism.

Style and Structure

I did my best to argue the prominence of Hearst Hall’s structure—those laminated archies—in its deisgn, but I only had a handful of interior and exterior photos. Cardwell describes that structure, and the means of its production, in finer detail.

The reception pavilion, Hearst Hall, was built on the south side of Channing Way, adjoining Mrs. Hearst’s residence on Piedmont Avenue. It was a building sixty feet in width and one hundred forty feet in length, with its principal axis oriented in a north-south direction on a site which sloped gently to the south and west. The structure—the engineering of which was worked out in collaboration with Maybeck’s university colleague Herman Kower—was an exciting and bold concept that employed laminated arches and diaphragms to create sections of the buildings as independent, movable, and re-assembled units. Twelve wooden arches rising fifty-four feet above the ground floor level were paired to form six structural bays. Single arches were used at the walls of the end bays. These arches were constructed of laminated two-by-eight timbers, formed horizontally on the site by nailing the timbers to a radius of approximately sixty feet. Holes were then drilled and bolts placed which were tightened after erection loads had been imposed. The arches were given lateral stability by the floor of the main hall which was twelve feet above the ground floor. it consisted of a diagonal grid of beams and joists, which was left exposed in the ceiling of the lower room. The arches were further tied, at approximately half height, by a horizontal plane surrounding the exterior of the arches, creating a floor for an outdoor gallery. The exterior walls of the building were curtain walls of stud construction with columns at each arch. These columns were tied at the middle to the arch by horizontal members which extended through the exterior to support planting boxes.²

Laminated timber seems a pretty modern technical decision, but I’ll come to a stronger point about concrete later. The real surprise in this passage is about the ties between the arches and the curtain walls extending to form Hearst Hall’s exterior planters. The ogive arches are outwardly apparent in Hearst Hall’s front elevation—that might suffice to argue its structural frankness—but these planters give outward expression to these ties, these much more obscure structural elements. There’s a similar structural extension through the building in Maybeck’s Outdoor Art Club building in Mill Valley.

The design for the Outdoor Art Club (1904) in Mill Valley added a new roof variation. It has a simple rectangular plan spanned by rafters trussed with a king post and collar ties. The ties extend through the roof covering and join a vertical extension of the wall columns, thereby strengthening the weakest part of the rafter chord between the tie and the support. Maybeck probably adopted this form for two reasons: first, the spaciousness of an uninterrupted vertical volume under a roof plane pleased him; second, the adaptation of a king post truss thrusting through the roof fulfilled his desire to indicate the nature of the building’s framing from the exterior.³

Speaking of exterior extensions, the “weird turret-obelisk” dangling from the Hall’s west face serves a purpose:

The tower at the right contained the flue from the heating plant. It also embellished the terrace roof garden gallery.⁵

It seems Maybeck didn’t bother moving it—the chimney is bare in all photos of Hearst Hall on campus—and I can’t say I blame him. Hearst Hall’s exterior sillhouette isn’t all that charming (an effect worsened in black and white), but the integration of the original chimney seems slapdash, after-the-fact, like a towering wart. I haven’t been able to find any photos of the “terrace roof garden;” it sounds fantastic.

Cardwell sheds some light on the matryoshka spaces-within-spaces effect—not the round arches of electric lights, but the alcoves and the fabric frozen in mid-air:

The alcoves formed by the spaces between the ribs of the arches were hung with Gobelin tapestries and various paintings from the Hearst collection. When the Hall was used for less formal occasions, such as afternoon teas given by Mrs. Hearst, a large canopy of Genoese rose velvet was suspended from the arches in the middle of the hall.⁶

Posh! These tapestries (“of the fifteenth and sixteenth centuries […] all historic treasures”) were relocated to the Maybeck-designed Hearst manse at Wyntoon, where presumably many were destroyed (with the castle) in a 1929 fire.

Finally, and importantly, Cardwell identifies some material decisions that don’t quite read in the interior photos.

The interior of the main hall was finished with redwood barn shakes similar to those on the exterior but treated with a sulphate of iron solution which rendered them a silvery-grey. Light came from clerestory windows covered by grilles of turned wood balusters of flemish derivation, typical of Maybeck’s ornamentation. […] The plain pine floor was covered by two large Chinese rugs of special design executed in grey-blue with a gold border. At night the room was lighted with more than a thousand incandescent bulbs. Two rows of colored lights were mounted directly on each arch of the room, and suspended from each arch were two rows of white lights with milk glass reflectors hung in an arch complementary to the structural members.⁹

These aren’t frank structural elements, but they’re interesting inasmuch as the interior presented Maybeck a margin of freedom: he could readily have built an interior that elided the Hall’s structure. Instead, the interior surfaces repeat the exterior (shingles! inside!) and lights trace the ogive arches.

Adaptation

My last essay argued Maybeck’s architecture involved a certain openness towards its occupants. I was working from two pieces of evidence: first, that Hearst Hall was primarily a multipurpose social space, and then that Maybeck reflected on the importance of architecture’s “inmates” in his written reflections: “the real interest must come from those who are to live in it.”

Luckily for me, Hearst Hall isn’t a fluke; this openness was a part of Maybeck’s practice in general, a part especially pronounced in his residential architecture.

In addition to technical and business details, he expressed his ideas on the relationship of a house, its owners, and its furnishing [to a Mr. and Mrs. Havens, clients]. “We believe that when you have seen the house and become accustomed to it,” he wrote,
there will be a thousand and one ideas come rushing to your mind to complete it… We therefore are getting an idea of the cost of things and when you have decided what you will do to put life into the rooms, you will make such a success of it that the thing as a whole will have that interest and personality which even as a plain business proposition will be a good investment… We also were under the impression that you could get your own personality into your house better if we stopped at the building proper, so as to leave you unhampered in the final work of furnishings.¹⁰

Lewis Mumford remembers not every starchitect was this open-minded:

Frank Lloyd Wright, it is said, once turned upon a client—let’s call him John Smith—who had added a few pleasant rugs and comfortable Aalto chairs to Mr. Wright’s furnishings, and exclaimed, “You have ruined this place completely, and you have disgraced me. This is no longer a Frank Lloyd Wright house. It is a John Smith house now.”¹¹

The physical openness of Hearst Hall’s floorplan isn’t unusual given the project parameters: a subdivided main space wouldn’t have suited music or theatrical performances, for example. Later in his career Maybeck advocated for open floorplans in a setting where they were unusual at the time: in residential architecture.

In 1923 Sunset Magazine published an article entitled “The Maybeck One-Room House,” in which he proposed the incorporation of house and garden into one entity, concentrating time and effort as well as cost on one handsomely proportioned and beautifully furnished space. Service rooms were to be reduced to such a minimal size that they would become mere alcoves.

Maybeck’s argument in Sunset Magazine is essentially that the “One-Room House” is economical, but it’s predicated on the idea that one “beautifully furnished space” can serve a variety of functions admirably.

Maybeck’s preference—that users should tailor and modify his work—extends to his urban- and campus-planning. A campus, he contends, is eventually “lived in” in the same cozy sense as a house.

Fifty years from now the plan of the University will have become modified and softened; it will be transformed many times, because so easily done. The buildings will have undergone changes, so planned from the beginning that they could grow. This patchwork gives the same feeling to the whole composition as the new stones in a cathedral––the newness becomes tarnished, the monotony of exactness relieved. By that time the gardens will be older, and in places a vine may soften the harshness of perfection.¹²

Loss as final adaptation

Maybeck saw an astounding portion of his work destroyed by fire. His office, with his early records and drawings, burned in the fires that followed the 1906 San Francisco earthquake. Innumerable early “Gothic houses” were leveled in East Bay blazes. Wyntoon burned. Hearst Hall, of course, burned. Twice Maybeck insists on destruction as a sort of final adaptation—a recapture into a different aesthetic scheme, a radical extension of the vine that softens the harshness of perfection.

The Palace of Fine Arts used the impression of ruination to its advantage from the getgo. Maybeck aimed to set a somber mood, to give the impression of a palace that was always already lost.

[…] Frank Morton Todd gives complete technical and physical descriptions of the structure, but when attempting to describe the character of the building in his volumes, he hesitantly states
[…] The theme itself we might attempt to state as the mortality of grandeur and to describe as having some affinity with our eternal sorrows over the vanity of human wishes…
Some such feeling as this, though vague, must have come to every responsive intelligence that looked across the Fine Arts Lagoon and the Palace itself. It represented the beauty and grandeur of the past. A cloister enclosing nothing, a colonnade without a roof, stairs that ended nowhere, a fane with a lonely votary kneeling at a dying flame, fluted shafts that rose, half hid in vines, from the lush growth of an old swamp… all these things were in the picture.
It was evident that Maybeck had succeeded in setting a mood. It was also evident that he had achieved his goal of creating a beautiful building. But all the words and the praise heaped on the building fail to explain what it was about the architectural forms that contributed to its universal appeal. Even when Maybeck wrote about the Palace, not one word refers to the building itself, or even to any of its parts. All of his explanation is devoted to the mood appropriate for an art gallery––which was “a sad and serious matter”––and this is done through repeated allusions to the haunting character of remanants of past civilizations and natural landscape forms. In his small booklet, The Palace of Fine Arts and Lagoon, he writes: “I find that the keynote of a Fine Arts Palace should be that of Sadness, modified by the feeling that beauty has a soothing influence.”¹³

Eventually, in the decades after the Exposition, Maybeck’s facsimile-ruination gave way to its less picturesque referent: by the early sixties the structure was physically crumbling… which didn’t concern Maybeck much at all.

During the period when funds were being gathered for restoration, Maybeck had his own ideas concerning the Palace of Fine Arts. They ranged from demolishing it in order to create an active community center, to heavily planting its site with redwoods in order that children of the future might find bits of ornament and sculpture of a wondrous ruin of a previous generation among the trees.¹⁴

Earlier, in 1947, Maybeck suggested encapsulating a ruined cathedral in a transparent geodesic dome to serve as a memorial rather than rebuilding it:

Several week after the conclusion of Fuller’s stay at the University [Buckminster Fuller in 1950], Annie Maybeck telephoned to report that Ben was most anxious to see me. She said “It has something to do with that man and his domes.” When I arrived at Maybeck’s studio, he had spread before him a copy of Life magazine showing Sir Basil Spence’s proposal for the reconstruction of Coventry Cathedral as a war memorial. Maybeck was visibly agitated. “Look, look,” he said, “a reconstructed Gothic cathedral is not what is needed; what should be done is to preserve the bombed ruins as a memorial.” He then suggested that a large glazed geodesic dome covering the ruins would be the perfect solution and urged me to contact Fuller to initiate such a project.¹⁵

Like with the Palace of Fine Arts, the ruins in Coventry had an affect all their own: the walls suggest vaults, the tracery suggests glass, and so on. Rebuilding would mean losing a means of authentically signifying loss. If a memorial gestures at a historic void, its form should gesture at precisely the structure that was lost.

Losing Hearst Hall

It’s surprisingly hard to find the precise date for the fire that destroyed Hearst Hall—even Cardwell just gives the year—perhaps because it’s overshadowed by the resulting rush to commission Hearst Memorial Gym. Cal’s 1923-1924 yearbook mentions the fire in a page anticipating the rebuild:

[Hearst Memorial Gym] has for several years been merely a dream, but at last our dreams have come true because Mr. William Randolph Hearst has promised the women of the University a new Building. The other Hearst Hall was used as a place for gathering as well as for a gymnasium, but the new building will be used mainly for a gymnasium. The former hall was a gift from the late Mrs. Phoebe Hearst to the University, but it was destroyed during a fire on June 20, 1922.¹⁶

The June 24, 1922 Daily Californian also dates the fire to June 20th. William Randolph Hearst promised a replacement, by telegram, the day after the blaze. “In fireproof materials.”¹⁷ Hearst specifically requested Maybeck get the assignment.¹⁸

Contemporary Blue & Gold yearbooks are the best testament to Hearst Hall’s adaptability. Plays, concerts, pep rallies, banquets, dances, insensitive “Italian carnivals”… the Hall was home to student events of all sorts.¹⁹ Cardwell calls it “the center of the campus social and cultural life;” that seems apt.

Steven Finacom penned an article about the Hearst Hall fire on its hundredth anniversary, including a contemporary account of the firefighting response and a poetic description of the building.

Modernism

Cardwell works hard to differentiate Maybeck both from the Arts & Crafts tradition and from International Style modernism. Peeling Maybeck away from Arts & Crafts is definitely the harder task, but Cardwell approaches both the same way: he diagnoses phobias in both traditions and finds Maybeck projects that broke from them.

Even though much of Maybeck’s early work received strong acclaim from people who were supporters of the ideas of John Ruskin and William Morris, he was not a proponent of a crafts revival. Maybeck started his designs on premises more sophisticated than those attributed to the Arts and Crafts movement. Exploitation of structural order, application of visual phenomena, and respect for new materials and industrial processes, as well as a firm belief in the expressive qualities of form were the bases for his work. A building was designed in the manner that Maybeck felt was appropriate for the conditions of the problem given. […] The unprecedented laminated wood arch framing of Hearst Hall was designed primarily to solve the problems of dismantling and reassembly and secondarily to provide a Gothic allusion of shape. The fact that Maybeck was ready either to adapt historic forms or to explore the boundaries of current construction technology went unnoticed by others advocating nature-inspired ornament and the infusion of handcrafts into the building process.²⁰

Frankly, it’s a stretch to argue Maybeck’s buildings are just incidentally classics of California Arts & Crafts. Maybe one could argue that A&C was already an established Bay Area vernacular style, and so similarities in Maybeck’s projects (like his monomaniacal respect for wood) are conventional. If he articulated it, this argument would seem a litte too convenient: Cardwell’s happy to attribute just about everything else to Maybeck’s genius.

Maybeck did make certain material decisions that’d make an A&C purist wince (in one episode he orders industrial sash windows for a church, to the manufacturer’s alarm). Nonetheless, Maybeck never strayed far from his crafts aesthetic: heavy redwood beams, corbels, and so on. All his technical innovation is subordinate, in his finished projects, to that aesthetic effect. That’s precisely why Cardwell can’t identify him with modernism: a true modernist would avoid the old, the romantic.

The immediate reaction was to look at Maybeck as a forerunner of the modern movement. It is true that some of his architectural innovations broke with the immediate past and used products of a machine technology in fresh and imaginative solutions to building problems. However, in the sense of “out with the old order and in with the new,” Maybeck was not a revolutionary. The architect’s primary function, he reasoned, was to fulfill one of man’s greatest yearnings––to be surrounded by beauty. As an architect he strove to produce, with modern materials and techniques, an architecture as beautiful and meaningful at that which had been created in past times and for past cultures.²¹

Their respective phobias aside, I’m not the first to claim there’s an intersection between Arts & Crafts and modernism. Cardwell invokes Nikolaus Pevsner (Pioneers of Modern Design, 1949) to claim “in architecture, particularly in the domestic field, [Arts & Crafts movement] architects produced designs with a basic simplicity and functionalism that have been identified as the beginnings of modern architecture.” Some of their efforts are “euphemistically called ‘rustic,’” but Maybeck’s are simple and functional.²²

The best argument I found (by far) is Lewis Mumford’s, cited in passing. Pevsner worships Gropius; Mumford loathes Gropius, and absolutely roasts Gropius’s imitators from his column in The New Yorker (1947). For Pevsner, Arts & Crafts posed modernism’s original problem (the unity of structure and decoration); for Mumford, on the other hand, Maybeck’s architecture softens modernism’s hard edge, makes it less afraid of comfort.

Certainly Le Corbusier’s dictum of the twenties––that the modern house is a machine for living in––has become old hat; the modern accent is on living, not on the machine. (This change must hit hardest those academic American modernists who imitated Le Corbusier and Mies van der Rohe and Gropius, as their fathers imitated the reigning lights of the Ecole des Beaux-Arts.) Mr. Siegfried Giedion, once a leader of the mechanical rigorists, has come out for the monumental and the symbolic, and among the younger people an inclination to play with the “feeling” elements in design––with color, texture, even painting and sculpture––has become insuppressible. “Functionalism,” writes a rather pained critic in a recent issue of the Architectural Review of London, “the only real aesthetic faith to which the modern architect could lay claim in the inter-war years, is now, if not repudiated, certainly called into question … by those who were formerly its most illustrious supporters.”
We are bound to hear more of this development during the next decade, but I am not alarmed by the prospect. What was called functionalism was a one-sided interpretation of function, and it was an interpretation that Louis Sullivan, who popularized the slogan “Form follows function,” never subscribed to. The rigorists placed the mechanical functionings of a building above its human functions; they neglected the feelings, the sentiments, and the interests of the person who was to occupy it. Instead of regarding engineering as a foundation for form, they treated it as an end.
[…]
Well, it was time that some of our architects remembered the non-mechanical and non-formal elements in architecture, that they remembered what a building says as well as what it does. A house, as the Uruguayan architect Julio Vilamajó has put it, should be as personal as one’s clothes and should fit the family life just as well. This is not a new doctrine in the United States. People like Bernhard Maybeck and William Wilson Wurster in California, always practiced it, and they took good care that their houses did not resemble factories or museums. So I don’t propose to join the solemn gentelmen who, aware of this natural reaction against a sterile and abstract modernism, are predicting a return to the graceful sterotypes of the eighteenth century. Rather, I look for the continued spread, to every part of our country, of that native and humane form of modernism which one might call the Bay Region style, a free yet unobtrusive expression of the terrain, the climate, and the way of life on the Coast. That style took root about fifty years ago in Berkeley, California, in the early work of John Galen Howard and Maybeck, and by now, on the Coast, it is simply taken for granted; no one out there is foolish enough to imagine that there is any other proper way of building in our time. The style is actually a product of the meeting of Oriental and Occidental architectural traditions, and it is far more truly a universal style than the so-called international style of the nineteen-thirties, since it permits regional adaptations and modifications. Some of the best examples of this at once native and universal tradition are being built in New England. The change that is now going on in both Europe and America means only that modern architecture is past its adolescent period, with its quixotic purities, its awkward self-consciousness, its assertive dogmatism. The good young architects today are familiar enough with the machine and its products and processes to take them for granted, and so they are ready to relax and enjoy themselves a little. That will be better for all of us.²³

I’m surprised that Mumford never mentions Arts & Crafts, either as a name for what he calls “the Bay Region style” or as a movement. Does he identify Maybeck with it? If not, does he share Cardwell’s reasons—that Maybeck wasn’t puritanical enough about manufactured elements?

Wurster Hall

I haven’t found anything suggesting a direct architectural influence between Hearst and Wurster Halls. This is a little disappointing, but to be expected—Hearst Hall was gone thirty-five years before Wurster Hall was commissioned. Nonetheless, I’m confident in two connections. The first is an indirect connection to that most-publicly-loathed feature of Wurster, its use of concrete. The second connection is direct: the architectural philosophy of William Wurster.

Maybeck frequently used the same materials for his projects’ structures and their interior and exterior textures. For the most part, these were wood—redwood when it was widely available. In at least one tight-budgeted project, the San Francisco Settlement Association’s Boys’ Club (1910), the outer walls and roof were left uncovered in the interior; two sides of the same boards and shingles constituted the outer and inner walls.²⁴ Wurster’s concrete interior is analogous to Hearst Hall’s interior shakes: both buildings frankly reuse their structural materials.

Maybeck even worked with raw concrete interiors. The First Church of Christ, Scientist in Berkeley is highly ornamented, but its enormous carved beams rest on lightly-adorned concrete pillars. Much of the exterior is concrete, hidden as it may be behind quintessentially Maybeck trellises. Hearst Memorial Gym? Concrete. He surfaced his own studio (1 Maybeck Twin Dr, Berkeley) in burlap sacks dipped in the stuff, an experiment in quick construction, and built his son’s house in the Berkeley hills out of pre-cast concrete slabs. “building was designed in the manner that Maybeck felt was appropriate for the conditions of the problem given.”

There are strong echoes of Maybeck’s philosophies in William Wurster’s initial dreams for Wurster Hall—most prominently, his dream of a building that will earn its character through use and adaptation.

“I wanted it to look like a ruin that no regent would like… It’s absolutely unfinished, uncouth, and brilliantly strong… The Ark [the preceding college of architecture], for instance, is a ripe building; it has been lived in; it’s been used, it’s been beaten up and everything else. It’s arrived. Our building will take twenty years to arrive.”²⁶

Like the inside-and-out shingles of Maybeck’s Boys’ Club, Wurster Hall’s concrete serves a practical purpose: economy.

The decision to construct it of concrete inside and out reflected both economic considerations and the aesthetic of the times. As often happens within the subculture of architecture, the architects were reacting to another building, the Yale School of Architecture, which had been designed by Paul Rudolph. […] For Wurster such design was anathema; he made his point loud and clear. “I want you to design a ruin,” he would say, pounding the table for emphasis. Wurster’s idea of a “ruin” was a building that achieved timelessness through freedom from stylistic quirks. While Wurster Hall has been categorized generally as a Brutalist design, the architects protest that the Brutalist aesthetic did not cause their preoccupation with consistency in the use of materials and forms.²⁷

Exposing ductwork and piping was similarly economical.

One aspect of the design that has been generally misinterpreted is the exposure of the ductwork and of the other mechanical equipment. Far from being an expression of style, the exposure was a means of avoiding the tunnel-like corridors that a dropped ceiling could produce and to obtain the effect of a high ceiling in the rooms. […] Having the mechanical equipment exposed also made maintenance easier, and was useful, to some extent, in teaching.

Concessions as these might’ve been, Wurster’s architects hardly adhered to Le Corbusier’s “machine for living” stricture. The hall’s courtyard is a sentimental feature, a callback (albeit an economized on) to the brick courtyard of the old John Galen Howard-designed architecture college (“the Ark,” now North Gate Hall) Wurster Hall would replace.

[Wurster] and others also considered a courtyard imperative. One of the most cherished parts of the old Architecture building, called the Ark, was the brick-paved court where social and ceremonial occasions took place. The new court was intended to express continuity with the old setting, to be the symbolic heart of the new college building.²⁸

This all seems like a Maybeckish mix of technical pragmatism and personality, albeit in the colder (and more fire-resistant!) concrete vernacular of the fifties. It’s not whimsical, but it’s honest; it was built to be lived in. Wurster’s comment about the Regents is a little insouciant, and I’m not sure Wurster Hall achieves “timelessness through freedom from stylistic quirks,” but he’s right about how to judge the building: what matters is not the Regents’ kneejerk griping, but how the building “arrives” via the life given it by educators and students decades down the line. As Maybeck puts it, “you could get your own personality into your house better if we stopped at the building proper.”

On sources

My access to resources on Maybeck are more or less limited to what’s available online—Google Books and the Internet Archive have been indispensible—and in the collections of the SF Public Library (which includes Cardwell’s book and reference copies of vintage Blue and Gold yearbooks). The Berkeley Library Digital Collections have scans of Daily Cal papers dating back to 1898.

UC Berkeley holds several collections that might be of interest to someone who really wants to dive deep.

The Berkeley College of Environmental Design’s Bernard Maybeck collection.
Bancroft Library’s William Randolph Hearst papers.
Berkeley’s Newspapers & Microforms Library, for contemporary reception of Maybeck’s architecture.

Berkeley’s libraries have been closed because of COVID-19, and won’t reopen until the fall.

One more text stands out, which deserves attention but doesn’t fit neatly into this essay: Ursula K. Le Guin wrote an essay, “Living in a Work of Art”, about growing up in Maybeck’s Schneider house. She covers a lot of the same ground—even borrows some of the same quotes from Cardwell, whose book she recommends—but she tells of growing up in the house, really living in it, before she understood its architectural significance. “I have trouble distinguishing the ethical from the aesthetic,” she writes,

Is it not fair to say that every building has a morality, in this sense, and not merely a metaphorical one, in the honesty and integrity of its design and materials, or the dishonesty expressed in incompetence, incoherence, shoddiness, fakery, snobbery?
I think I absorbed this morality of the building as I did the smell of redwood or the sense of complex space.
I think the moral conception of the building was as admirable as its aesthetic conception, from which it is, to me, inseparable.²⁹

Cardwell, Kenneth H. Bernard Maybeck: artisan, architect, artist. Santa Barbara and Salt Lake City: Peregrine Smith, 1977. (48)↩︎
Cardwell, Bernard Maybeck, 46–47.↩︎
Cardwell, Bernard Maybeck, 86.↩︎
Cardwell, Bernard Maybeck, 86.↩︎
Cardwell, Bernard Maybeck, 47.↩︎
Cardwell, Bernard Maybeck, 48.↩︎
Cardwell, Bernard Maybeck, 49.↩︎
Wikimedia Commons contributors, “File:American homes and gardens (1905) (17963343698).jpg,” Wikimedia Commons, the free media repository (accessed July 6, 2021).↩︎
Cardwell, Bernard Maybeck, 48.↩︎
Cardwell, Bernard Maybeck, 106.↩︎
Mumford, Lewis. “The Sky Line: Status Quo.” The New Yorker, October 11, 1947. (104-110)↩︎
Cardwell, Bernard Maybeck, 189.↩︎
Cardwell, Bernard Maybeck, 144.
Todd’s picture of “a cloister enclosing nothing, a colonnade without a roof, stairs that ended nowhere” reminds me of a very abstract explanation of a cube with a missing octant from Peter Eisenman:
Traditionally architecture, let’s say the last 400 years of architecture, has been defined by what I call a humanist architecture—that is, that man took the forms of his building and related them back, and gave them some meaning, by virtue of their relationship to some ideal, or more pure state. Something that was symmetrical, something that was contained, something that was whole. Something that was understandable as a more perfect condition than the reality of which man lived in.
Now, my argument is that that ideal state that we can refer to and get meaning from no longer exists. Man’s position relative to God and nature has changed. Man has unwittingly unleashed natural forces of terrible proportion which threatened to extinguish the civilization. We have no model of architecture which defines that condition that is the opposite of ideal. It is the negative of an ideal state. And I want to try and say, “alright, what would a design process be that starts with the negative of an ideal?”
Take these two objects. These are two partial cubes. They each have an octant cut out of them. They could be seen to be in the process of growing toward something ideal, or disappearing to a point; that is, they are in a state of instability. And I want to try and suspend the architecture between the former classical ideal notion of what architecture was, and this negative which may represent man’s destiny today—that is, the future which is, uh, nothing.
I’m not convined Eisenman’s example. He calls his cubes, well, “partial cubes”—they, like referential humanism before them, certainly refer to some ideal (a platonic solid, no less!). I suppose Eisenman isn’t arguing against all reference, but rather the inheritance of humanistic principles… but then the cube’s missing octant seems superfluous: does the missing octant make it less humanistic or more? This seems to be of grave importance to Peter.
In any case, Eisenman and Maybeck are using geometric form similarly to signify loss. We imagine the cube’s missing octant, we imagine a roof on the PFA’s colonnade; in both cases, we realize an absence. The rise of a staircase-to-nothing and the slant of a cube’s edges towards the vertex opposite the void (Eisenman touches it to punctuate “disappearing to a point”) function similarly: they imply a motion towards an end.
For Eisenman’s view of architecture and cubes, see Michael Blackwood’s Beyond Utopia: Changing Attitudes in American Architecture (1983), 47:36–49:27. I found it on Kanopy.↩︎
Cardwell, Bernard Maybeck, 152.
Cardwell mentions the October 16, 1915 “Preservation Day” and subsequent formation of a PFA preservation league, but plainly says they failed and that the Palace fell to “forty-five years of disintegration and decay;” (151) he skips, or misses, updates made in the thirties.
As a part of the process of permanent rehabilitation of the Palace of Fine Arts, [painter Frank Joseph] Van Sloun was commissioned in the spring of 1936 to execute eight large murals in the ceiling of the octagonal rotunda […] His works are destined to be viewed by countless tourists, for the lagoon and lovely building are always sought by the sight-seer.
Van Sloun’s murals were destroyed in the Palace’s 1962 demolition and reconstruction. The above quote is from California Art Research, Volume 8 (1937, pages 117-118), which describes them.
↩︎
Cardwell, Bernard Maybeck, 10. Spence’s design did preserve the footprint of the old cathedral, which now encloses a courtyard; the new cathedral sits adjacent.↩︎
1925 Blue & Gold: A Record of the College Year 1923-1924. United States: University of California, 1924. (336)↩︎
“W. R. Hearst to Rebuild Woman’s Gymnasium Given by His Mother.” The Daily Californian. June 24, 1922. (1, 6)↩︎
“Will Choose Site for a Quadrangle of Women’s Halls.” The Daily Californian. June 27, 1922.
This article mentions plans to develop a whole women’s quad, and Robert Gordon Sproul (then Comptroller, later President of the University of California) reports that the Regents are “extremely anxious, according to Mr. Sproul [Robert Gordon, then Comptroller and later President of the University of California], to embark as soon as practicable upon a policy of supplying dormitories than women.”
Cardwell mentions that Maybeck had grand plans too (his early sketches included a complex of buildings—not just a gym, but also a domed auditorium, museums, etc.). The University reined in Maybeck and only built the gym. Maybe the Regents were more anxious about the project’s soonness than its scope…↩︎
1918 Blue & Gold: A Record of the College Year 1916-1917. United States: University of California, 1917. (56) “Insensitive ‘Italian carnivals?’”
The main floor was arranged with numerous booths, decorated with chili, garlic, and onions, in which artists and fortune-tellers were busily engaged. Italian peasant girls in bandanas, bright-colored aprons and skirts, sold balloons, flowers, and candy. Organ grinders, singers, tarantula and dagger dancers afforded entertainment, and in the gaily decorated annex there was dancing. Down-stairs, peasant girls sold fruit, spaghetti, raviolas, and tamales.
Yes, tamales.↩︎
Cardwell, Bernard Maybeck, 83.↩︎
Cardwell, Bernard Maybeck, 236.↩︎
Cardwell, Bernard Maybeck, 84.
I’m a little skeptical of Cardwell’s characterization. Pevsner seems to be praising C. R. Ashbee, and only because he renounced William Morris’s “intellectual Ludditism;” “the true pioneers of the Modern Movement are those who from the outset stood for machine art.” His description of Morris is blistering, though Morris gets some credit for emphasizing stylistic unity. See Pioneers of Modern Design: from William Morris to Walter Gropius, pages 24–26.↩︎
Mumford, Lewis. “The Sky Line: Status Quo.” The New Yorker, October 11, 1947. (104-110)↩︎
Cardwell, Bernard Maybeck, 160.↩︎
Cardwell, Bernard Maybeck, 215.↩︎
Woodbridge, Sally. “Reflections on the Founding: Wurster Hall and The College of Environmental Design [Two Place Tales].” Places 1, no. 4 (1984).↩︎
Woodbridge, Sally. “Reflections on the Founding: Wurster Hall and The College of Environmental Design [Two Place Tales].” Places 1, no. 4 (1984).↩︎
Woodbridge, Sally. “Reflections on the Founding: Wurster Hall and The College of Environmental Design [Two Place Tales].” Places 1, no. 4 (1984).↩︎
Le Guin, Ursula K. “Living in a Work of Art.” Words Are My Matter: Writings About Life and Books, 2000-2016, with a Journal of a Writer’s Week. Small Beer Press, 2016. (61–62)↩︎

Genres and Subtraction Tests

2021-06-13T00:00:00Z

Genres and Subtraction Tests« blog 2021-06-13

Genres and Subtraction Tests

The Subtraction Test isn’t a mental model in itself, but it relates to one: genre. Given some corpus of texts, a genre is a pragmatic class of some members in that corpus—that is, texts don’t innately belong to a genre, but we organize them (a posteriori and inductively¹) into learned genres because it’s analytically useful to do so.

Genres are hazily, even personally, defined; Genre Theory aims to explain why some things belong and other things don’t. Rick Altman imagines an illustrative argument about musicals:

A: I mean, what do you do with Elvis Presley films? You can hardly call them musicals.
B: Why not? They’re loaded with songs and they’ve got a narrative that ties the numbers together, don’t they?
A: Yeah, I suppose. I guess you’d have to call Fun in Acapulco a musical, but it’s sure no Singin’ in the Rain. Now there’s a real musical.²

Altman goes on to decompose film genre features into syntactic features (structural elements, like that a Western involve a governmental frontier, whether that be the borders of a town or some intergalactic outer limit) and semantic features (characteristic symbols: dust and dusters for the Western, song and dance for the musical, and so on). I like this breakdown for film—syntaxes link apparently distant texts—but it doesn’t generalize to the genre mental-model.

We can make Altman more generic by setting aside the feature categories (syntactic and semantic).

Suppose we have a genre G. The simplest definition for the genre would be to decompose it into a complete set of necessary features {f₁, f₂, …f_n}, where every feature must exist in a text T if it’s to be included in the genre. That is, T ∈ G ⇔ {f₁, f₂, …f_n} ⊆ the features of T.³ Using this to filter texts gives us the “inclusive list,”

an unwieldy list of texts corresponding to a simple, tautological definition of the genre (e.g., western=film that takes place in the American West, or musical=film with diegetic music).⁴

The inclusive list is unwieldy because it doesn’t leave much room for nuance, e.g. to say that casting Elvis makes something less characteristic of the musical genre. We can complicate the definitions by adding unnecessary features and weighting them,⁵ but that gives us unwieldy definitions and a false sense of precision.

When I say we learn genres inductively, I mean we learn the genre holistically: rather than accumulating a set of atomic features {f₁, f₂, …f_n} that characterize a cluster of texts, we learn a genre duck test: “if it looks like a [musical] and quacks like a [musical], it’s a [musical].” Formally, a test function duck_G(T) → {true, false} returns true if and only if the text T belongs to the genre G.

A Subtraction Test (my invented term) is a way of revealing relationships between particular features of a text and the genres to which the text belongs.

Imagine decomposing a text T into its features: T = {t₁, t₂, …t_n}. Subtraction-testing means comparing duck_G(T) and duck_G(T\{t_i}): does removing the feature t_i change whether the text is a member of G?

duck_G(T)	duck_G(T\{t_i})	Implication for G	Example
true	true	t_i is not necessary.	High Noon without revolvers is still a Western. ∴ a Western needn’t include revolvers.
true	false	t_i may be necessary.	Annie without musical numbers is no longer a musical. ∴ a Musical may need musical numbers.
false	true	¬t_i may be sufficient.	I don’t know, can you think of one?
false	false	¬t_i is not sufficient.	No Country for Old Men without milk is still not a musical. ∴ milklessness does not a Musical make.

Note how the implications are qualified: subtraction tests are confident when subtracting a feature does not impact a text’s classification. When the classification changes—either from true → false (indicating necessity) or from false → true (sufficiency)—we learn something about the directional influence of the feature but can’t make too strong a claim. Maybe you don’t think Star Wars is a Western, but you imagine it’d pass if it didn’t have the space travel; that means you think space travel makes a film less Western-y, but it obviously doesn’t mean every space-travel-free film is a Western: Annie ain’t.

Notably, this works for multi-feature sets as well as single features: we can check duck_G(T\{t_i,t_j}). Nothing guarantees that our features contribute independently to genre membership—rolling papers signify differently in front of a Bob Marley poster and in a gumshoe’s breast pocket—but I rarely think about independence. If you’re designing Taguchi experiments, either you’re deep in the realm of false precision or your inductive categories are already sophisticated.

I’ve been leaning on films because they’re popularly associated with genre, but the model and test are portable to other informal clustering activities. Do you cluster inbound support tickets to prioritize product improvements? Pinning down litmus tests for whether a new ticket belongs in a certain cluster means you can share the task with a person who would naturally cluster differently.

We learn duck tests for informal categories all the time; Subtraction Tests inch usefully towards formalism.

Caution: not everything that looks and quacks like a Subtraction Test is one. I’m only writing any of this down because Gilman’s The Theory of Gothic Architecture and the Effect of Shellfire at Rheims and Soissons⁶ falsely reminded me of Altman’s Elvis example. Gilman, writing in 1920, discusses gothic cathedrals damaged in World War I. The War did the subtraction for him, so he needn’t imagine structures without features: where artillery removevd a particular feature, Gilman considers whether the damage cascaded (e.g. in a collapse), which would indicate that the feature was structurally necessary.

Structurally unnecessary features, he reasons, are expressions of a gothic architectural ideal unmuddled by the cathedral’s physical pragmatics. The style is purest-expressed in the ornamentatal, and Gilman’s contemporaries debated whether gothic cathedrals revealed their true structures, which might’ve otherwise been hidden, or whether the cathedrals were ornamented with faux-structure—piers that support nothing, decorative buttresses, and so on. Gilman concludes the cathedrals are sometimes honest—

Closely connected with the principle of logic is that of revelation of structure for esthetic effect. Here again the ruins generally illustrate the theory and confirm it in its broad application. In the vaulting, the manner in which the breakage has occured, as well as its extent, does confirm strikingly the theory that the ribs carry the vault cells and are not only real functioning members, but are the most important part of the vault.⁷

—and sometimes not:

Now actually we find that some of the cases often considered as revealed structure are not the real structure. At Soissons the single shaft on the lower story of the nave piers does not really support the vaulting shafts and, in turn, the vaults above […] It by no means follows that the shaft is not good design, only that it does not express the facts of this structure; it is in fact an eye-satisfying fiction, although perhaps, a proper one.⁸

The first sign that Gilman’s treatment of subtraction and genre differs from our Subtraction Tests is that subtractability leads Gilman to the opposite conclusion. In the damaged cathedral, that “the single shaft on the lower story of the nave piers does not really support the vaulting shafts”—that those single shafts are subtractible in Gilman’s sense—means we should consider them a purer reflection of a gothic architect’s ideal. That’s very different from concluding “t_i [the lower story of the nave piers] is not necessary” for a building to be gothic; that may be true (a feature can be characteristic without being necessary), but seeing a cathedral sans piers doesn’t give us evidence to that effect. It doesn’t even mean the feature is insignificant to the genre: that an architect chose a nonstructural pier rather than a nonstructural doric column makes the building more gothic, not less.

The key difference is that Gilman isn’t applying a duck test. When he sees a partially destroyed vault, he asks not “is this still gothic?,” but “is this still standing?” He isn’t comparing whether the building’s genre status changes, and he gives no reason to believe it does (a building may go from “gothic cathedral” to “gothic semi-ruins,” but nobody thinks it stops being gothic).

Gilman’s subtractions tell us about architectural intent—choices to build structurally unnecessary elements, despite their difficulty and expense—not about necessity and sufficiency to his architectural category. Be careful that your duck test is, in fact, a duck test.

Is “gothic” a genre? The category certainly developed a posteriori and inductively. Its builders were aware of their style, but I haven’t read any indication that they were self-awarely participating in a break from the sacred architecture that came before them. To the contrary,

The architect who built the choir of St Denis must have spoken to Suger about the arcus in the vaults; William of Sens in speaking to the Abbot of Canterbury no doubt used the term fornices arcutae, and Villard de Honnecourt probably spoke to his apprentices of Ogives. However, no name for the style itself is known to have existed at this time; indeed, it is unlikely that any name did exist, for, in the regions where the Gothic style was born and developed, ‘building in the Gothic style’ was simply called building.¹⁰

“Gothic” was only identified as a genre, with common architectural elements and decorative tendencies, in retrospect (typical: we have to find noncontemporary names for yesterday’s “modern”):

When in the course of the nineteenth century historical knowledge of the birth of the Gothic style, its development, and its spread increased, the Late Gothic style was still regarded as part of the Gothic style. Moreover, the growing study of the essential Gothic elements, beginning with Wetter’s book, and the attempts to interpret the essence of the Gothic, which began with the work of Viollet-le-Duc, and have continued to our own day, have neutralized the effects of personal taste and have led to a more intensive analysis of the concept of Gothic style.
The scholarly consideration of the Gothic style began with descriptions of individual buildings and so came to the study of individual members, such as pointed arches, piers, rib-vaults, windows, doorways, roofs, and towers. At the same time a desire grew to understand the essence of the Gothic style which could permeate such divergent features as piers and windows. The Gothic style was said to possess a picturesque quality, a quality of infinity, a vegetal quality, a romantic quality. All these different concepts were first formulated in the eighteenth century and were then considered more closely in the nineteenth and systematically bound into one unified concept.¹¹

Interestingly, the genre-awareness of 19th-century restorationism means “restoration” may be a misnomer for what Viollet-le-Duc went about doing. Viollet-le-Duc was widely criticized for intervening ahistorically in the buildings he restored, emboldened by his conclusions about the driving principles of Gothic style, including scrubbing them of historically authentic, if post-gothic, features. Perhaps the very notion of a unified principle is fraught: even the individual cathedrals in Voillet-le-Duc’s canon were constructed over the courses of centuries. Should we believe these principles stayed fixed over several generations of builders?

Incidentally, Frankl also offers a better term than Gilman for style expressed in the structurally unnecessary, a “margin of freedom:”

In other words, function always leaves a ‘margin of freedom’ which cannot be resolved by utilitarian considerations and which is not objectively pre-determined. […] Gothic vaults must be examined in the light of their function; […] even when these functions have been understood, the question as to why these mebers have so many different profiles in different churches still remains unanswered, since each profile fulfils the necessary static function, in so far as it exists equally well.¹²

Olsen, Stein Haugom. “The concept of literary genre.” Metodo. International Studies in Phenomenology and Philosophy 6.1 (2018).↩︎
Altman, Rick. “A semantic/syntactic approach to film genre.” Cinema Journal (1984): 6-18.↩︎
This formulation is inspired by Olsen. See especially page 56.
I’ve adjusted the notation, and I think Olsen’s direction is a little misleading: theorizing about weighted features assumes we sort texts into genres in a really precise way. In practice, when you ask yourself “is Fun in Acapulco a musical?,” you’re just applying a litmus test rather than weighting and summing.
Extracting weights would be an interesting approach if we wanted to take a corpus and learn features that predicted membership, but that means starting with a corpus and working towards a genre definition, which isn’t what Olsen’s discussing.↩︎
Altman, Rick. “A semantic/syntactic approach to film genre.” Cinema Journal (1984): 6-18.↩︎
Olsen, Stein Haugom. “The concept of literary genre.” Metodo. International Studies in Phenomenology and Philosophy 6.1 (2018).↩︎
Gilman, Roger. “The theory of gothic architecture and the effect of shellfire at Rheims and Soissons.” American Journal of Archaeology 24, no. 1 (1920): 37-72.↩︎
Gilman, Roger. “The theory of gothic architecture and the effect of shellfire at Rheims and Soissons.” American Journal of Archaeology 24, no. 1 (1920): 37-72.↩︎
Gilman, Roger. “The theory of gothic architecture and the effect of shellfire at Rheims and Soissons.” American Journal of Archaeology 24, no. 1 (1920): 37-72.↩︎
Gilman, Roger. “The theory of gothic architecture and the effect of shellfire at Rheims and Soissons.” American Journal of Archaeology 24, no. 1 (1920): 37-72.↩︎
Frankl, Paul, and Paul Crossley. Gothic architecture. Vol. 58. Yale University Press, 2000. 217-219.↩︎
Frankl, Paul, and Paul Crossley. Gothic architecture. Vol. 58. Yale University Press, 2000. 217-219.↩︎
Frankl, Paul, and Paul Crossley. Gothic architecture. Vol. 58. Yale University Press, 2000. 228.↩︎

Blogging with TikZ

2021-05-21T00:00:00Z

Blogging with TikZ« blog 2021-05-21

Blogging with TikZ

Programming Langauges and Compilers (CS 164) with Paul Hilfinger was the hardest class I took in college, bar none. I recommend it to anyone studying CS at Cal: the correspondence between formal grammars and state machines-as-parsers has been pretty personally impactful. State machine diagrams were an indispensible part of Hilfinger’s notes on those subjects, and drawing out a state machine diagram to tap out the state transitions is how I recall those notes now.

State machine diagrams are indespensible to State Machines via Jorge Luis Borges because, without all my mnemonic drawing and tapping, I wouldn’t have recognized the connection between text and theory. The diagrams are also an indespensable way to concretize the examples in that post. I’m not prepared to explain (non)determinism without converting a specific graph, and I don’t have the patience to squeeze all ambiguity out of mock-Borges prose.

Diagramming also presented an opportunity to go further than the CS 164 notes: rather than just presenting diagrams and counting on readers to understand the rules governing state transitions, I wanted the diagrams to demonstrate those rules by illustrating dynamic user input.

I did all of this with TikZ, a LaTeX extension for specifying diagrams (probably the same extension Hilfinger used). This might seem like an odd choice for interactive demos, but there’s a logic behind the bodge!

Arriving at TikZ

pandoc-blog, the static site generator I use, is full of opinions. It uses Pandoc to convert Markdown and LaTeX source to HTML documents in order to

Avoid big dependencies.¹
Prefer print-friendliness.
The primary motivation in using Pandoc was to be able to swap out converters: rendering a blog post as a PDF should be as simple as pandoc -s source.md -o out.pdf. Avoid drawing content with Javascript: it shouldn’t take PhantomJS to produce a PDF.
Prefer semantic markup.
In practice, this mostly means not abusing HTML elements to do things they aren’t intended to do, but it’s also reason to prefer a diagram specified in the DOM over a raster image (when possible).

State Machines imposed particular requirements. All of my diagrams would have a great deal in common; they should represent states and transitions, with labels, in a consistent style. Given that similarity, I wanted a tool that’d let me define the state machines as minimally as possible. Each diagram definition should be easy to read and version.

Finally, I needed something I could make interactive: node appearances need to change according to user input.

Avoiding big dependencies and preferring print-friendliness meant eschewing Javascript libraries for drawing graphs, even though a JS-controlled canvas element would probably serve well for interactivity.²

That interactivity requirement, along with the preferences for semantic markup and for concise and versionable definitions, rules out tools for drawing graphs that only output raster images.

HTML canvas and svg elements are natural fits for the technical requirements. They’re lightweight, reasonably print-friendly, and semantic (which, in turn, means they’re scriptable for interactivity). The trouble is SVG is just too flexible—I want to be quickly defining labeled states and edges rather than individually arranging SVG elements.

That’s where TikZ comes in: it’s concise.³ The problem with TikZ is that it’s a LaTeX extension meant for generating PostScript; I need it to generate SVG.

Implementation

Converting TikZ to SVG

Defining a state machine diagram in TikZ is fairly straightforward:

Define a set of states, with their positions, labels, and IDs.
Define a set of edges, with labels, between states.

These steps are just a matter of using styles and macros provided by the tikz-automata TikZ library; for an in-depth explanation, check out Drawing Finite State Machines in LaTeX using tikz. In practice, a TikZ state machine diagram is defined like this:

\begin{tikzpicture}
  % 1. Define the states, with their positions, labels, and IDs.
  \node[state, accepting, initial] (Rc) {$C$};
  \node[state, below=of Rc] (Rb) {$B$};
  \node[state, right=of Rc, yshift=-2cm] (Ra) {$A$};
  % 2. Define the edges, with labels, between states.
  \draw
    (Rc) edge[bend right, left] node{1} (Rb)
    (Rb) edge[bend right, right] node{0} (Rc)
    (Rb) edge[bend right, below] node{0} (Ra)
    (Ra) edge[loop right, right] node{1} (Ra)
    (Ra) edge[bend right, above] node{1} (Rc);
\end{tikzpicture}

This syntax isn’t perfect—in particular, I found positioning nodes pretty fiddly—but it’s concise (each node and edge on its own line) and readable (as readable as the labels and IDs one chooses).

Normally this tikzpicture would be embedded into a LaTeX document; how can it be turned into a standalone SVG? There’s an answer on the TeX Stack Exchange:

Use the standalone TeX package to generate a PDF of just the TikZ figure, without any other document cruft.
Use pdf2svg to convert that PDF to an SVG file. Miraculously—I have no idea how this works—that SVG file is reasonably human-readable, if verbose: each element in the PDF is converted to an SVG path element.

Using standalone is as simple as wrapping our tikzpicture in a document with the standalone class. Doing so (and adding some TikZ style directives to the preamble) gives us our final definition of our figure:

% This preamble is reused for every diagram.
\documentclass{standalone}
\usepackage{xcolor}
\usepackage{tikz}
\usetikzlibrary{automata, positioning, arrows}
\tikzstyle{defaults}=[
  ->,
  >=stealth',
  every state/.style={thick, fill=gray!10},
]

\begin{document}
  \nopagecolor
  % The same tikzpicture as before.
  \begin{tikzpicture}
    [defaults, node distance = 3cm]
    \node[state, accepting, initial] (Rc) {$C$};
    \node[state, below=of Rc] (Rb) {$B$};
    \node[state, right=of Rc, yshift=-2cm] (Ra) {$A$};
    \draw
      (Rc) edge[bend right, left] node{1} (Rb)
      (Rb) edge[bend right, right] node{0} (Rc)
      (Rb) edge[bend right, below] node{0} (Ra)
      (Ra) edge[loop right, right] node{1} (Ra)
      (Ra) edge[bend right, above] node{1} (Rc);
  \end{tikzpicture}
\end{document}

I wrote a short script, tikz2svg, which handles the TikZ → PDF → SVG conversion. Running tikz2svg nfa-conversion-pre.tex yields the SVG we’re after:

nfa-conversion-pre.svg: the state machine diagram produced by tikz2svg nfa-conversion-pre.tex.

Building images in `pandoc-blog`

pandoc-blog’s build processes are managed with make: if one modifies a post’s Markdown source, the gen/%.html target rebuilds that post’s generated HTML document.

Converting .tex precursors to .svg images manually is a hassle. This reconversion should happen automatically, the same way Markdown is reconverted to HTML: whenever a tex precursor is modified, rebuild the corresponding SVG.

Doing this for State Machines involved adding one Makefile and modifying another. The relevant directories are structured like this:

Makefile
posts
- borges-automata.md
img
- borges-automata
  - Makefile
  - nfa-conversion-pre.tex
  - nfa-conversion-pre.svg
gen
- borges-automata.html

Most of this is typical of pandoc-blog:

A root blog/Makefile (re)builds the full site.
The blog/posts directory contains Markdown source files for each post; make generates corresponding HTML files in blog/gen.
The blog/img directory holds static assets that can be referenced in post markup. Those assets are organized into subdirectories for tidiness: one for each post.

What’s atypical is the inclusion of our precursor (nfa-conversion-pre.tex) and its build product (nfa-conversion-pre.svg) in blog/img/borges-automata: generated content outside of blog/gen!

blog/img/borges-automata/Makefile builds all the diagrams in blog/img/borges-automata:

SOURCES = $(wildcard *.tex)
TARGETS = $(patsubst %.tex,%.svg,$(SOURCES))

all: $(TARGETS)

%.svg: %.tex
    tikz2svg $<

.PHONY: clean
clean:
    rm *.svg

You can imagine any blog/img/*/Makefile exposing the same interface. The main blog/Makefile can delegate figure-generation to the img subdirectory for each blog post; this one happens to be TikZ-specific, but for future blog posts I can write image-generating Makefiles that encapsulate whatever other behavior I need.

We can update blog/Makefile to run make in each blog post’s subdirectory:

POSTS=$(shell find posts/*)
# OUT contains all names of static HTML targets corresponding to markdown files
# in the posts directory.
OUT=$(patsubst posts/%.md, gen/%.html, $(POSTS))
# IMAGEDIRS is a list of img/ subdirectories containing makefiles.
IMAGEDIRS=$(shell find img/*/Makefile | xargs -0 -n1 dirname)

all: $(OUT) $(IMAGEDIRS) index.html

# ... most targets unchanged from pandoc-blog/Makefile.

# Runs `make` in the target directory.
img/%: img/%/*.tex img/%/Makefile
    $(MAKE) -C "$@"
    @touch "$@"

Now the make watch loop provided by blog/Makefile automatically rebuilds the diagrams whenever we save a change to the TikZ source!

This isn’t a super novel way of composing Makefiles, but it’s a fun complication of pandoc-blog. I didn’t originally expect to be generating images, and I’m pleased the root Makefile isn’t sullied with blog-post-specific targets.

Adding interactivity

Diagrams are well and good, but you can’t build an interactive state machine demo without, well, implementing a state machine. Generically, this means turning a topology (all the various states and transitions between them) and initial state into some object that exposes an interface for feeding it input.

I do this with an Automaton class, which I won’t discuss in depth. The key to an Automaton’s connection to an SVG diagram is buried in the nodes constructor argument: each state is defined with two callback functions, enter and exit, which are called when input causes the Automaton to enter and leave that state, respectively. When it enters state A, it calls A.enter(); when it receives any subsequent input, it calls A.exit() before proceeding.

To represent the Automaton’s state in the diagram, A.enter() should turn the SVG element corresponding to A blue; A.exit() should reverse the change. All we need is a reference to that SVG element.

The problem: those SVG elements were defined by pdf2svg. Some of them have automatically-assigned IDs, but (for some reason) the circular paths demarcating states do not. I found the right paths with Chrome’s dev tools and added ids manually to match the TikZ IDs:

<path
  id="R0"
  style="fill-rule:nonzero;fill:rgb(94.999695%,94.999695%,94.999695%);fill-opacity:1;stroke-width:0.79701;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;"
  d="M 123.198937 42.518875 C 123.198937 49.397781 117.620812 54.972 110.745812 54.972 C 103.866906 54.972 98.292687 49.397781 98.292687 42.518875 C 98.292687 35.643875 103.866906 30.06575 110.745812 30.06575 C 117.620812 30.06575 123.198937 35.643875 123.198937 42.518875 Z M 123.198937 42.518875 "
  transform="matrix(1,0,0,-1,53.137,83.722)"
/>

Which leaves us to define enter and exit:

const enter = () => {
  document.getElementById("R0").style.fill = "cyan";
}
const exit = () => {
  // The original fill is a light grey.
  document.getElementById("R0").style.fill = "rgb(94.999695%,94.999695%,94.999695%)";
}

…and so on for each node in the graph; see the deterministic-binary-fsa.html source for a full example of a modified SVG and Automaton configuration bundled into an HTML document.

The final demo—of a nondeterministic finite state machine handling input alongside its deterministic equivalent—introduces a last complication. There’s no structural issue with plopping two generated SVGs into an HTML document side-by-side, but there’s a semantic one: ID collisions.

SVG’s <use> element lets you duplicate another element by its ID. This is a neat little optimization: if you have a complex path you need to use twice, better to define it once and reuse it by reference! pdf2svg seizes on this optimization. The form of the digit 1 is only defined once; all the other 1s are defined, in source, by <use> elements referencing the original. The browser looks up the original element by its ID and re-renders it.

Remember how some of the pdf2svg-generated elements have IDs? Those are of the form glyph0-0, glyph0-1, and so on, which means that every pdf2svg-generated SVG has (and perhaps uses) a glyph0-0.

This wouldn’t be an issue but for the way we’re combining them: plopping the SVG source unceremoniously into an HTML document. When the browser looks up the DFA’s glyph0-0 by reference… it finds the NFA’s glyph0-0 instead. The first diagram is fine; the second one is a garbled mess of glyphs from the first.

The solution: prefix each SVG’s IDs. Find-and-replace is robust enough:

Replace all instances of id=" with id="{prefix}.
Replace all instances of "# with "#{prefix}.

I’ve since updated tikz2svg to do this ID replacement automatically; now it prefixes generated SVG element IDs with the source filename. If you want to reuse filenames, insert a random component instead.

The Javascript animating this compound diagram is somewhat more complicated: it instantiates two Automatons, and feeds inputs to them simultaneously. See the nfa-conversion.html source for details.

Future work

Ideally, I’d like to have a script to convert a TikZ state machine definition directly to an encapsulated demo.

TikZ itself is an academic diagramming syntax; it offers a great deal of flexibility that must be excluded if the script is to extract a working state machine definition (that is, a topology).
The multi-step process for producing an SVG—renderinga PDF, then running that through pdf2svg—means TikZ-specified data like state IDs are missing from the generated SVG. Remember: we re-added these IDs manually.

These issues are solved by avoiding TikZ, and instead building diagrams from some other domain-specific format. Javascript representations of the automaton topologies, like those configuring the interactive demos, would work. On the other hand, that means resigning TikZ’s advantages. Honestly? I don’t think I’ll bother!

I’d like to make some other incidental improvements (avoiding embedded iframes; referencing a single LaTeX header file between diagrams; things like that).

For now, I have what I need. Blogging with TikZ allowed me to avoid big dependencies, to keep my blog print-friendly, to keep its markup semantic, and to share interactive demos with the next generation terrorized by CS 164.

If my commitment to the ideological purity of my Pandoc-generated blog seems extreme, check out phiresky’s “Hosting SQLite databases on GitHub Pages”.

That blog’s written as Pandoc Markdown; the Pandoc artifact is postprocessed with React to generate charts and runnable code blocks (including queries of a statically-hosted SQL database). That’s commitment.

Relevant: Maciej Cegłowski’s evergreen slides on Chickenshit Minimalism. I’m proud to keep this site hard-to-read without any help from npm.↩︎
Graph-drawing libraries are smaller than I expected, but not so small. The entirety of State Machines (complete with its diagrams and demos) is about the same size as minified d3.js: 94.5 and 83.6 kB, respectively.↩︎
There was another draw to TikZ which I didn’t ever ultimately achieve: I figured that, for the static diagrams, I could define TikZ diagrams inline (in a LaTeX environment) in my post’s Markdown source. I still think this is possible, but it’d take writing a custom Pandoc extension to extract the TikZ picture, convert it to an SVG, and replace it with an HTML img referencing that SVG.
I decided it’d take too much fiddling to make that Pandoc extension reusable (especially outside of pandoc-blog), and that I might not actually have reason to reuse it.↩︎

State Machines via Jorge Luis Borges

2021-02-19T00:00:00Z

State Machines via Jorge Luis Borges« blog 2021-02-19

State Machines via Jorge Luis Borges

This post is, first and foremost, an introduction to state machines (also called “automata”) via an extended Borgean allegory about an existence in a labyrinth, a sort of infinite gallery of mazes. It introduces several significant concepts—equivalence, finitude, acceptance, determinism, and the powerset construction—as a succession of realizations about that existence.

Why Borges? I picked up Labyrinths in early February, an anthology and a maze of furtive interreferences in its own right. Borges toys with combinatorics. He writes that “Lully’s machine, Mill’s fear and Lasswitz’s chaotic library can be the subject of jokes, but they exaggerate a propension which is common: making metaphysics and the arts into a kind of play with combinations.” He joins them, even reconstructing Lasswitz’s library in The Library of Babel. The stories and essays are replete with villas subdivided into infinitely many rooms, repetitions collapsed into single events, points that contain all points, and so on.

I realize adding the allegory risks muddling the subject matter. My hope is that the metaphysical confusion of the labyrinth is relatable in a way that makes the mathematics feel more familiar. If I get away with that binding, it’ll work in reverse: if the math resembles familiar philosophy, we can use the mathematical concepts as a grammar for their philosophical doubles.

I’ve written another post about generating these diagrams and interactives with TikZ.

All the parts of the house are repeated many times, any place is another place. There is no one pool, courtyard, drinking trough, manger; the mangers, drinking troughs, courtyards, pools are fourteen (infinite) in number. The house is the same size as the world; or rather, it is the world.
The House of Asterion¹

Imagine, if you will—though you can relate to this freely if it sounds familiar—that you live your life in a vast labyrinth of circular rooms, with marked doors that open into passageways which bring you from one room to the next. Each room is indistinguishable, except maybe by the number and labels of its exits. You’re so disoriented that you can’t know how you entered the room you’re in. In fact, there may be no way to return to the room from whence you came—the passages seem to close up behind you as you step out of them. There’s no backtracking; you can only progress into the labyrinth, choosing among the doors each room affords you.

In your heart you know this is not a labyrinth one leaves. The labyrinth is the same size as the world; or rather, it is the world.

In one of the maze’s innumerable connected rooms you’re visited by the whisper of a blind sorcerer. The sorcerer explains he built the labyrinth—designed its general schematic, its endless succession of identical rooms, the workings of its corridors, the labels on its innumerable doors, etc.—but, blind, he can’t read the signs, can’t travel the monotonous expanse of corridors and galleries he devised.

This is the sorcerer’s proposition: starting in some fixed room in the maze, you are to travel through a series of doors, following exactly his instructions for which door to select. If, at any point, he gives you an instruction you can’t follow—gives you some label that does not match any door out of the room you’re in—you can cry out, and (zap!) he will teleport you back to the starting room to receive a new set of instructions. When a set of instructions can be followed to the end, you are (zap!) also teleported back.

In this way, with you as a proxy, the sorcerer explores the great maze. In return, he promises, the many forms of the labyrinth and the meaning of your hermitude will be revealed.

Naturally curious, you accept.

This assemblage—you in your maze, following instructions—is essentially a state machine:

Each room is a state; you can be in one state at a time.
The fixed topology of the labyrinth determines which state transitions are allowed. A given room does not necessarily allow passage into every other room in the labyrinth; you can only move to a successive state available from your present state.
Your task is to discover whether the sorcerer’s inputs can be followed, whether they’re acceptable to the state machine.²

Equivalence

The universe (which others call the Library) is composed of an indefinite and perhaps infinite number of hexagonal galleries, with vast air shafts between, surrounded by very low railings. From any of the hexagons one can see, interminably, the upper and lower floors. The distribution of the galleries is invariable.
The Library of Babel

The first room has two doors: one marked left, the other marked right. The sorcerer’s first instruction, left, takes you through that left door and its narrow passageway, into another room with two doors: one marked left, the other marked right.

In fact, every door—left or right—opens on another indistinguishable room with identical doors; there is always a left door and a right door to pass through. Each foray ends either with some unfollowable instruction (e.g. to take a door marked south, or salad bar, or de Broglie: none of these doors is ever available) or with the exhaustion of the sorcerer’s sequence, at which point (zap!) you begin, with a new sequence, from the start. A lifetime of lefts and rights passes. The sorcerer’s instructions are inexhaustible; some sequences take eons to follow.

In fact, if it’s constructed how it appears—each room leading to two more rooms—this labyrinth must fork infinitely towards the horizon, right? And, since only one set of left-right instruction sequences leads you to any one of the infinite rooms, the sorcerer has a literally inexhaustible list of routes to explore: one route for each room.³ We can diagram the start of this maze as follows:

A Garden of Forking Paths. Each room has two doors—one marked left, one marked right—each of which leads to a room with two doors, and so on ad infinitum. The ellipses at the right of this diagram indicate continuation. In fact, at each ellipsis begins a series of forks exactly like the one pictured.

While it explains what you observe of the maze, this seems a bleak existential outlook… but you’re rightfully suspicious of existential certitudes! In fact, out of the mire of indistinguishable rooms and doors and passageways surfaces a suspicion about the maze itself.

The sorcerer’s instructions seem farsical. Predictably, choosing the left door or the right door makes no difference: they lead to indistinguishable rooms. What if the left and right doors mark, in truth, two passageways into the one room?

Here, it seems, there are fewer rooms to see. Whereas before there was one room for every acceptable sequence of instructions, now there is only one room for every length of acceptable instructions. Any sequence of three instructions—be it left-left-right, right-right-right, or some other—leads you to the third room. There are precisely 2ⁿ paths to the n^th room.

This does little to relax the absurdity of your agreement with the sorcerer. First of all, no sequence of sorcerers’ instructions will ever disambiguate an infinite Braid from an infinite Garden of Forking Paths, even though their diagrams look different. An instruction valid in one is always valid in the other; an instruction invalid in one is correspondingly invalid.

Second, and more importantly, an infinite Braid is still infinite. Though there may be more than one path to a given room in the sequence, there is still an infinite number of rooms; the sorcerer will never visit them all. If you were to draw out a map of this labyrinth which admits an infinite number of paths, the map would extend infinitely to one side (this map would, you realize, expand to cover the labyrinth itself, no matter how small its lines and letters).

In one of your travels, after an eternity, something occurs to you about the indistinguishability of the rooms: just as two doors may be identical aside from their labels, as in the Braid diagrammed above, perhaps two indistinguishable rooms…

You stop the blind sorcerer between instructions. You explain to him that he has, in visiting this room, visited the labyrinth. In fact, for all the vertigo of his infinite acceptable sequences, this room is equivalently the labyrinth.

The sorcerer, with an air of didactic satisfaction, asks for an explanation.

It’s a little roundabout to start an explanation of finite state machines with an allegory involving infinite rooms—infinitely many states, a sort of “infinite state machine.” These don’t have any practical application except to illustrate the relationship between the topology of the maze and the set of instructions it accepts. First we have a maze that accepts an infinite number of instruction sequences, and where no distinct sequences lead to the same room; then we have another maze that accepts an infinite number of instruction sequences (the very same!), but where distinct sequences can lead us to the same place.

These two labyrinths, the Garden and the Braid, also introduce the idea of equivalence. If two state machines accept the same inputs—if there’s no series of instructions from the sorcerer that reveals, via its acceptability in one and unacceptability in the other, in which maze we’re trapped—then the two state machines are equivalent.

From here on we’ll deal with finite state machines (labyrinths with a finite number of rooms and doors), beginning with your answer to the sorcerer. Finite state machines are more useful: we can actually write programs that implement them, we can draw them out in finite diagrams, and there’s nothing we can express in an infinite maze that we can’t equivalently express in a finite one.

Finitude

Today, one of the churches of Tlön Platonically maintains that a certain [room with two doors is] the only reality. All men, in the vertiginous moment of coitus, are the same man. All men who repeat a line from Shakespeare are William Shakespeare.
Tlön, Uqbar, Orbis Tertius

This is your explanation: these rooms are indistinguishable to your explorations; every state permits the same two state transitions as the start state, so every state transition is essentially a return to the start state. Framing the state machine this way simplifies it: we can think of a single room instead of an infinite number of rooms!

Importantly, this simplification doesn’t change what instructions the maze allows: any among the infinite number of instruction sequences accepted by the infinite state machines diagrammed above is also accepted by the one-room simplified state machine diagrammed here. It’s a finite maze with an infinite number of paths.

In fact, any finite maze with a cycle—any way to leave a room and eventually return to it—accepts an infinite number of paths, because you can validly move through the cycle once, twice, or any number of times. This one is a one-room cycle: you can transition from the one state to itself.

This dynamic is what makes finite state machines so useful: they’re concise.

Sometimes they offer minimal notations for sequences that are otherwise hard to describe.⁴ It’s easy to describe “any sequence of lefts and rights,” but sometimes we want to describe more complicated families of instructions. Compare the following diagrams to the verbal descriptions of the instructions they allow:

Description	Diagram
Any sequence of `left`s and `right`s where odd-indexed instructions are `right`.
Any sequence of `left`s and `right`s, but where every third instruction can also be `up`.
Any number of `up` instructions, followed by any number of repetitions of the order `right-up-left`.

Each of these mazes describes a distinct infinite set of instruction sequences. The diagrams are clearer than the verbal descriptions.

The set of instructions the maze allows is locked into the maze’s topology; the maze is a grammar for its own instructions. We can use the maze to generate instructions, not just test them: if the sorcerer were to ask you to produce a valid instruction sequence for a maze (some “syntagm” in the maze’s grammar), you can take an arbitrary series of doors to build one.

Note, these state machines’ properties are stable independent of their labels. We’ve been working with directional labels (left and right) because they suit the labyrinthine theme, but nothing changes if we replace left with 0 and right with 1.

If we replace the lefts and rights, with 1s and 0s respectively, we have a state machine that accepts any finite binary string.

In fact, there are more equivalent finite labyrinths—labyrinths with a finite number of rooms, that admit any sequence of binary instructions—than those covered here. Their construction is left as an exercise for the reader.⁵

The blind sorcerer listens quietly to your explanation of the infinite maze with one room, which perfectly describes every instruction you could ever accept from him—every path in the Garden of Forking Paths. He smiles, apparently satisfied with the explanation; “if all its infinite rooms are one room, this is a crummy corner of my labyrinth. Let’s find someplace with variety.”

As he says these words (zap!) you are transported to a wholly different maze.

Acceptance

When it was proclaimed that the Library contained all books, the first impression was one of extravagant happiness. All men felt themselves to be the masters of an intact and secret treasure. There was no personal or world problem whose eloquent solution did not exist in some [room].
The Library of Babel

In the interest of difference, the sorcerer introduces a new rule. At first you were to accept any set of instructions you could follow; now you are to reject unfollowable instructions, but also to object if the last instruction in a followable sequence doesn’t lead you to a room containing a MacGuffin.

Two rooms with the same doors—up to this point, indistinguishable—might now be different: perhaps one contains a MacGuffin and the other one does not. Moreover, two rooms which are indistinguishable to their occupant at a point in time (two rooms with the same doors, neither of which contains a MacGuffin) may be provably distinct because they have different positions relative to MacGuffin rooms in the maze’s topology.

As you explore these mazes, you’re struck by their insistence on their own size. If an infinite braid of rooms has a single MacGuffin in the hundredth rooms, the rooms before the MacGuffin can’t be summarized as a single room: one is just before the MacGuffin room; the room before that is two rooms before the MacGuffin; and so on. Even though they have the same doors, these rooms are clearly distinguishable.

Past the MacGuffin, though, you have no such information. You know there is a room after the MacGuffin, but since you will never encounter another MacGuffin you can never know whether there are rooms after that one (e.g. in an infinite braid) or whether it’s a single trick room with exits that lead you back into it.

Before this introduction of MacGuffins, in the language of state machines, every node was an acceptor—it was as if every room contained a MacGuffin. Now only certain nodes are acceptor states. If, after exhausting input, a state machine is an acceptor state, it “accepts” the input sequence.

State machine diagrams denote acceptors with double-walled circles (which is why the diagrams before this section have all had double-walled rooms: every room was an acceptor). Single-walled circles are not acceptors—these are the rooms we can pass through but don’t want to end in.

If this dynamic isn’t clear, take a moment to pretend to be the sorcerer. The room you’re in is colored cyan; you can use the 0 and 1 buttons to provide input (to select doors to take. The checkbox at the bottom indicates whether the state machine accepts the input: it’s checked when you’re in the acceptor state R₁, but not when you’re in any other state.

Significantly, these mazes can more finely restrict what instruction sequences they accept. Without these special MacGuffin rooms, any prefix of an acceptable instruction was itself an acceptable instruction; if less than every room contains a MacGuffin, that’s not necessarily the case! Before, every room was an acceptor, every state an acceptable terminal state. Now there are nonterminal states: valid instructions can take us through them, but can’t end there. Now we can design mazes where a prefix of a valid instruction sequence isn’t guaranteed to be acceptable:

Description	Diagram
Any nonempty binary string that begins and ends with the same digit. This accepts `1-0-0-0-1`, but not `1-0-0-0`.
Any binary string ending in `0-0`. This accepts `1-1-1-0-0`, but not `1-1-1` or `1-1-1-0`.

As your understanding of the labyrinths deepens, your exploration with the sorcerer seems to accelerate, as if freed from ponderous existential questions. Your juvenile dread that the great labyrinth might be meaningless is supplanted by a vertigo of interpretations: a din of instructions, a nauseating race through passageway after passageway, MacGuffin and non-MacGuffin rooms, accepted and rejected sequences, and the blind sorcerer’s increasingly frenetic jumps (zap! zap! zap!) from one maze to the next.

Determinism

In all fictional works, each time a man is confronted with several alternatives, he chooses one and eliminates the others; in the fiction of the almost inextricable Ts’ui Pên, he chooses—simultaneously—all of them. He creates, in this way, diverse futures, diverse times which themselves also proliferate and fork.
The Garden of Forking Paths

That nausea is interrupted, suddenly, by a dilemma. In a new maze, you’re confronted with choice: one door is marked 0, and two doors are marked 1. When the sorcerer instructs you to pass through the door marked 1, through which door should you pass?

In this two-room maze we must end up in the acceptor room R₁; any instructions that leave us in R₀ are invalid. Depending on how we interpret the last 1, the instruction set 0-0-0-0-1 could either be valid (if we take the door leading from R₀ to the acceptor room R₁) or invalid (if we take the door leading from R₀ back into R₀).

“You will take both doors,” explains the blind sorcerer. Your task is to find out whether the instructions lead you to a MacGuffin through either door. This puzzles you, but the sorcerer explains that there are a couple ways to take it literally:

Whenever you encounter several identical door, the sorcerer can conjure an avatar of you to pass through each door in parallel. If two avatars would meet in some room down the line, they are consolidated into one.
This prospect deeply unsettles your sense of self (are you the avatar? or the original?), and the sorcerer admits it gives him migraines: conjuring avatars takes time and effort, and delivering simultaneous instructions to innumerable (and maybe ever-multiplying!) avatars is, he says, “a pain in the ass.”
You can pass through both doors by backtracking. When you choose one door over another identical one, note the decision; then, if the first door doesn’t lead you to accept the instructions, you can return to take the second door.
This constant retracing, of course, takes time: you have to return to a room once for each identical door, and subsequent rooms can themselves have identical doors. Before, you would pass through at most n rooms to (in)validate a sequence of n instructions. Now you may need to pass through many more

You commit to backtracking (since, if you have to spend your existence trying to make sense of an infinite labyrinth for a mad sorcerer, you might as well feel existentially unique while you do it). The vertigo returns, but you have the kernel of an idea to eliminate the problem of choice.

These mazes—with several indistinguishable exits from a given room—are nondeterministic finite state machines (NFAs). They’re “nondeterministic” because your state at a given time isn’t totally determined by a set of instructions; you could be in several states at a given time, depending on which doors you chose. The two strategies proposed by the sorcerer correspond to two strategies available to a program implementing an NFA: they can evaluate possible states sequentially, or they can track multiple states in parallel. Both of these strategies are undesirable: you can have avatars in up to every room of a maze at once, which makes applying inputs burdensome. Regular expression implementations use NFAs; these dynamics are what make certain regular expressions inefficient.

You think, in all the time you now spend backtracking, about the avatars. Some number of avatars, in certain rooms in a finite maze, receive a certain instruction and at once spring into certain other rooms. In this process, some avatars will split, some will consolidate, and those for whom the instructions are unfollowable will blink out of existence.

It’s difficult to imagine the possible configurations of avatars in rooms because there are so many⁶, but a marvelous fact occurs to you: from the sorcerer’s perspective, a configuration of avatars behaves deterministically. If avatars are in some set of rooms, then after receiving a certain instruction they will be in a certain determinable second set of rooms regardless of how they traveled to that prior arrangement.

Is this passage from configuration to configuration really so different from you passing, deterministically, from one room to the next?

You interrupt the sorcerer a second time, and you make him an offer: for any finite maze confused with choice, you say, any maze burdened with identical doors, you can design for him a finite equivalent maze devoid of choice.

This is what the avatars reveal: every nondeterministic finite state machine is equivalent to some deterministic one!

Your proposal:

For every configuration of avatars in rooms in the nondeterministic maze, build a room in our new deterministic maze. If a configuration has an avatar in a room with a MacGuffin, then put a MacGuffin in the new room corresponding to that configuration.
For each configuration of avatars, consider each instruction that at least one avatar could validly follow (in other words, consider the set of door-labels the avatars see at once). For each instruction I:
1. Figure out what every avatar would do if given this instruction: some move simply into another room, some split and move into several. This gives you a successor configuration.
2. In the new deterministic maze, build a door out of the room corresponding to the initial configuration that leads to the successor configuration. Label it with the instruction I.
Some rooms in our new maze may not be reachable from the maze’s start. Demolish these; they’re superfluous.

Since we never repeatedly assess the same instruction applied to the same configuration of avatars, we will never build two doors in the same room of our new maze that have the same label. Thus, the new maze can be explored deterministically.

Since any configuration in the nondeterministic maze accepts the same instructions as its corresponding room in the deterministic one, we haven’t changed the followability of any instructions. Because every room with a MacGuffin in the new maze corresponds to a configuration in the nondeterministic maze where some avatar is in a room with a MacGuffin, the mazes make the same terminal judgements of followable sequences. They’re equivalent!

Of course, since there are so many possible configurations of avatars in mazes, the new deterministic maze may be considerably larger than the nondeterministic maze it models.

This algorithm—the powerset construction, adapted for our allegory—is best explained with an example. Consider the following nondeterministic finite maze, with rooms labeled A, B, and C:

A nondeterministic maze. There are two doors out of room B marked 0 and two doors out of room A marked 1. Any instruction sequence that leaves an avatar into room C is accepted.

Our first step is to plan out the rooms in the new maze, a finite state machine with one state for each possible configuration of avatars in the nondeterministic maze. We can use set notation to describe the arrangements of avatars:

{C} is the state corresponding to the configuration with a single avatar in room C,
{A, B} is the state corresponding to the configuration with an avatar in room A and another in room B,

and so on. Any state with an avatar in room C is an acceptor state, and at the start there is only one avatar (in room C). We can list out the seven states corresponding to the seven possible arrangements of avatars in the three-room maze:

State in new maze	Acceptor?	A	B	C
{A}	No	✔️
{B}	No		✔️
{C} (start state)	Yes			✔️
{A, B}	No	✔️	✔️
{A, C}	Yes	✔️		✔️
{B, C}	Yes		✔️	✔️
{A, B, C}	Yes	✔️	✔️	✔️

Next, we need to consider the possible transitions out of each of these states. Thankfully this is a pretty simple maze: we only need to consider what happens to each of these states if the sorcerer delivers the instruction 0 or the instruction 1:

State	+`0`	+`1`
{A}	{A, C}	Invalid
{B}	Invalid	{A, C}
{C}	{B}	Invalid
{A, B}	{A, C}	{A, C}
{A, C}	{A, B, C}	Invalid
{B, C}	{B}	{A, C}
{A, B, C}	{A, B, C}	{A, C}

Finally, we prune the unreachable states and diagram our deterministic finite state machine. It’s worth taking a moment to compare it to the tables above: confirm that each of the acceptor states includes an avatar in room C; check that the state transitions correspond to those described in the instruction table.

This process lets us do away with all the complexity of avatars and backtracking, without changing which instructions are accepted and rejected, for any finite state machine, no matter how complex. You and the sorcerer can explore these deterministic mazes without any insufferable nondeterminisms; though this deterministic state machine looks nothing like the equivalent it models, exploring it is essentially exploring the collective experience of the avatars in their nondeterministic maze. For any arrangement the avatars would realize collectively, you reach a corresponding state.

If you need to convince yourself of this correspondence, you can use the interactive demo below to provide simultaneous inputs to the nondeterministic and deterministic equivalent state machines. Cyan nodes indicate the presence of an avatar in a room; note that the state of the deterministic machine always identifies the occupied rooms in the nondeterministic one.

Allegory

Augustine had written that Jesus is the straight path that saves us from the circular labyrinth followed by the impious; these Aurelian, laboriously trivial, compared with Ixion, with the liver of Prometheus, with Sisyphus, with the king of thebes who saw two suns, with stuttering, with parrots, with mirrors, with echoes, with the mules of a noria and with two-horned syllogisms. […] Like all those possessing a library, Aurelian was aware that he was guilty of not knowing his in its entirety; this controversy enabled him to fulfill his obligations to many books which seemed to reproach him for his neglect.
The Theologians

The sorcerer (Borges) and his mazes are an indulgent conceit for an explanation of state machines. For a reader really interested in the mathematical concepts, the comparison might confuse more than it makes clear: it may be harder to imagine yourself splitting into multiple indistinguishable avatars than it is to imagine a multi-node state, and so my explanations in this essay become less allegorical as the concepts become more disorienting.

I’m satisfied with my exploration of the correspondence between state machines and sequences, but the allegory says nothing about the “meaning of your hermitude” in the maze. To do so requires stepping back out of the diegetic “you” in the allegory, the little traveler in the labyrinth, and considering the you reading the allegory.

First, I can offer you a shallow meaning: state machines are useful tools for turning seemingly complex grammars or agents into simple, applicable programs. That’s how they were covered in my undergraduate computer science curriculum. It’s not a wrong justification—these applications are worthwhile—but it’s partial.

The other justification is to recognize that this essay is a reversal of work Borges has already done. His stories don’t discuss mathematics explicitly (they’d be worse—more gimmicky—if they did) but they rework topology and combinatorics into phenomenological and existential puzzles. I can explain topology via a phenomenological puzzle about a maze because Borges establishes, in various narrative guises, the structure of the allegory. Even if Borges hadn’t, at certain touchpoints the allegory is obvious. Topology connects intuitively to the everyday way one moves between physical spaces; surprising topological twists, like the equivalence of an infinite maze and a minimal one, correspond to uncanny views of the everyday.

Borges skillfully extends these allegories beyond their natural correspondences. The magic of A New Refutation of Time is that it imagines a kind of spatialized time, wherein two indistinguishable moments are ontologically one:

That pure representation of homogeneous objects—the night in serenity, a limpid little wall, the provincial scent of the honeysuckle, the elemental earth—is not merely identical to the one present on that corner so many years ago; it is, without resemblances or repetitions, the very same. Time, if we can intuitively grasp such an identity, is a delusion: the difference and inseparability of one moment belonging to its apparent past from another belonging to its apparent present is sufficient to disintegrate it.

This is precisely the same radical idealism that lets us say an infinite maze is a single room. If you prefer a philosophical connection, Borges treats the phenomenology of time the way Augé treats place.

Where does Borges’s labyrinth lead? To a dizzying metaphysics, as compelling as it is disconcerting. The Borgean maze is a trap, an entanglement of symbols and experiences, reflections and repetitions. I hope that following his allegories in the opposite direction—beginning with the existential allegory, but taking it as a point of departure into the mathematics Borges adapts but elides—has the opposite effect: mazes can be games, too. The trick is to enjoy them.

Jorge Luis Borges. “The House of Asterion.” In Labyrinths: Selected Writings & Other Stories. New York: New Directions Books, 1962. Note: all subsequent quotations from Borges short stories are from this translation.↩︎
Using a state machine to accept or reject inputs might be foreign to readers who use state machines to, for example, determine the actions of an agent in a game. In the interest of keeping the Borgean allegory as simple as possible—it can be hard to follow as it is—this story concerns itself with state machines as they’re used in pattern-matching: we give the sorcerer a boolean output.↩︎
Note, there is one acceptable route to each room (that is, a sequence of lefts and rights). There are also innumerable unfollowable instructions—which say to pick a door marked axaxaxas mlö, for example—but we won’t sweat that here.↩︎
Minimal notation is really a feature of formal grammars. Diagrams of state machines corresponding to those grammars are handy visualizations (I find them much easier to skim).↩︎
This is a cheeky suggestion. There’s an infinite number of finite state machines that admit any sequence of binary instructions; they just need to end in some cycle (either a single-node cycle, where one constantly reenters the room they’re in, or a multi-node cycle like a looped braid).
Those terminal cycles can be preceeded by any non-cyclical labyrinth (e.g. the tree in figure 1, the braid in figure 2, or some other directed acyclic graph) as long as every room has a door labeled 0 and a door labeled 1.
And, finally, there are unexplored dimensions: a finite state machine that accepts a superset of the set of finite binary inputs satisfies our requirements.↩︎
After a certain set of instructions, each room can either contain or not contain an avatar. Thus, for a maze with n rooms, you have 2ⁿ possible configurations of avatars in the maze.
Note, though, that this is an upper bound. If the only way into room R_left is a door marked left and the only way into room R_right is a door marked right, then no set of instructions will simultaneously put avatars in R_left and R_right (because no sequence can end with both left and right).↩︎

Making Things Worse on Purpose

2021-02-13T00:00:00Z

Making Things Worse on Purpose« blog 2021-02-13

Making Things Worse on Purpose

Lately I’ve enjoyed breaking bad habits and resolving little frictions in my life by tweaking apps that cause and enable them.

news-feed-eradicator specifically eliminates Facebook’s news feed, that erstwhile attention-trap. More generically, you can customize an ad blocker to block arbitrary content on a website; I use this to hide comment sections which would otherwise waste my time. These social features make products “better” inasmuch as they make them more profitable (via user engagement), but the psychology of a bottomless social feed is such that my engagement doesn’t necessarily correspond to it providing me any value at all.

YouTube’s default video quality throttling mismanages my computer’s resources rather than my attention: their playback quality throttling considers bandwidth, but not the client’s graphics hardware or playback speed. The fan on my 2013 laptop is screaming after a minute of streaming 1440p video at 60 frames per second and 2.5x normal speed.

Because YouTube’s player controls store a manually-set quality limit in Chrome’s Local Storage (as yt-player-quality), a Chrome extension can simulate manually correcting the defaults. I don’t need to abide by YouTube’s expectation that I prefer higher-quality video.

Unfortunately, we don’t have this degree of flexibility in mobile browsers (which lack the extensibility of desktop browsers) or closed-source native apps (which don’t share a single customizable client). This is the same product-user dynamic that makes syndication feeds important: allowing end-users to tinker with an interface alleviates some pressure to predict what they need.

Tinkering is a gratifyingly active kind of usership, one that — at its extreme — cuts against applications’ commercial drive to be desirable, to induce dependency.

Hearst Hall

2020-11-22T00:00:00Z

Hearst Hall« blog 2020-11-22

Hearst Hall

An urban college campus is an interesting place for architectural archaeology. UC Berkeley is dense, and in constant redevelopment; for a couple hundred years, layers of Berkeley have been plowed under to make way for new buildings, programs, and generations of students.

That plowing-under is so complete that, for five years, I lived a short walk from what has become one of my favorite buildings in California: a hall built and rebuilt by Bernard Maybeck, a star of the California Arts & Crafts movement, to house a women’s social center-slash-theater-slash-concert hall. Hearst Hall is full of gothic drama and prefigurations of modernism. For five years I didn’t realize it because Hearst hall no longer exists.

I only discovered Hearst Hall after walking past the Swedenborgian Church in San Francisco—also a Maybeck building—enough times to remember to look it up. That church led me to Maybeck, who designed a great number of notable buildings in Berkeley and San Francisco in his idiosyncratic medieval-revivalist mashup style.

Phoebe Anderson Hearst turned to philanthropy, including a long patronage of the University of California, after her husband’s death in 1891. In 1896 she funded a $100,000 competition to design an expanded general plan for the University (the third such general design commissioned, after an original design by F.L. Olmstead and an 1870 David Farquarson expansion Olmstead bitterly resented). As the competition’s sponsor, she not only moved to Berkeley but commissioned from Bernard Maybeck—then a professor—a new building to host competitors and judges: Hearst Hall.¹

The Hall’s main chamber is striking: the 16-meter-tall vault of a gothic arch, extruded like an A-frame but closed at the ends, strung with round arches of incandescent lights. It’s as if Maybeck sliced the top off of an enormous redwood gothic basilica.

The decorators’ clever use of suspension (both in the decor for this sitting-room arrangement and the gymnastic equipment pictured below) gives the impression of matryoshka volumes, one inside the other. A fabric hung unevenly by its four corners looks like it’s caught mid-fall. The furniture is eclectic and sparse. Planters flank the alcoves. The sense of space in these photos—the nested volumes drawing attention to the voids between them—reminds me of this Paris Review line about Berlin living rooms:

In my romance, the apartment is large enough for a given room to have whatever purpose the occupant chooses for it. The point of a Berlin apartment of this kind is to enjoy the emptiness.²

Which, to my surprise, fits Maybeck’s architectural philosophy:

The house after all is only the shell and the real interest must come from those who are to live in it. If this is done carefully and with earnestness it will give the inmates a sense of satisfaction and rest and will have the same power over the mind as music or poetry or any healthy activity in any kind of human experience.³

Hearst, like Maybeck, wanted the hall to serve a succession of different virtuous purposes. Phoebe Hearst brought Berkeley a world-class education in classical music—an event series complete with individual invitations to students. When she left Berkeley for Pleasanton, Hearst had the hall disassembled, moved, and reassembled on the university’s campus to serve as a women’s social center (for “Saturday afternoon receptions, musicals on Sundays, ‘At Home’ Wednesdays, dinners three evenings a week”⁴). Hearst and Maybeck may have had that move in mind from the start: the hall is a construction of “laminated arches and diaphragms… sections of the building [were] independent, movable, and easily re-assembled units.”⁵ Realizing that “the women’s physical education program was almost non-ecistent since the facilities of Harmon Gymnasium were available to them only during those few hours a week when wthe men were engaged in drill,” Hearst paid to repurpose and expand the building as a women’s gymnasium.⁶

The Hall was destroyed by a fire in 1922, three years after Phoebe Hearst’s death. Its adjoining swimming pools—built when it became a gym—were used for swimming and hydrological experiments until they were cleared in 1955 to make way for Wurster Hall.⁷

William Randolph Hearst—Phoebe Hearst’s son—commissioned a new women’s gym in his mother’s memory from Maybeck and Julia Morgan;⁸ that’s the Hearst Memorial Gymnsium on Cal’s campus today. Hearst Gym has none of former Hearst Hall’s bohemian charm: it trades in the quirky medieval revivalism for a much more fireproof stone-and-cinderblock Beaux-Arts. George Hearst’s namesake builing, the Hearst Mining building in the northeast corner of campus, is much prettier.

Wurster is an interesting point of dialog for its predecessor. It houses Berkeley’s College of Environmental Design (CED), including Cal’s architecture library; people without a taste for concrete joke about it driving architecture students crazy. Personally I think Wurster Hall’s ugliness is way overrated (Evans is a far more visually offensive, and neighboring Law School commits the double-sin of being ugly and boring), but it certainly can’t be mistaken for a Maybeck building: there’s nothing in the least bit handcrafted or medieval about it, maybe save its general external menace. Wurster Hall doesn’t exactly project whimsy.

Beneath this concrete surface, though, Wurster Hall shares Hearst Hall’s philosophical bones.

The modern hulk is named for William Wurster, founding president of the CED. Wurster, a student of Maybeck’s, graduated from Berkeley in 1919. Like Maybeck, Wurster’s professional style tended quirky, low and modern but quintessentially Californian. Why would he commission such a stark building for his department?

Bill Wurster wanted the designers to design what he called a ruin, a building that “achieved timelessness through freedom from stylistic quirks.” […] Historian Sally Woodbridge neatly sums up both William Wurster’s ideals and the building that was named after him: “As Wurster Hall weathered without mellowing, it reflected Wurster’s opinion that a school should be a rough place with many cracks in it. Perpetually unfinished, Wurster Hall was an open-ended and provocative environment for teaching and questioning.”¹⁰

Woodbridge quotes Wurster’s Oral History:

“I wanted it to look like a ruin that no regent would like… It’s absolutely unfinished, uncouth, and brilliantly strong.”¹¹

“A ruin.” Maybeck’s Palace of Fine Arts in San Francisco was famously designed as a “forgotten and overgrown Roman ruin” in 1915.¹² Though they’re ruins in very different styles, Wurster Hall and the PFA reference ruination to signify a similar openness. Wurster talks about achieving timelessness through quirklessness, but “ruin” evokes more than just bareness: ruins point back at a pre-ruined history. Maybeck’s point back is nostalgic for medieval handcrafts and classical arts, a rebellion against industrial production. Wurster Hall feels altoghether bleaker; it looks skeletonized, burned clean. Whereas the PFA points hauntologically at an unrealized enlightened progression out of classicism, Wurster Hall points back at biblical warnings: “MENE, MENE, TEKEL, UPHARSIN.”

“Perpetually unfinished.” Wurster’s vision is consistent with Maybeck’s philosophy, in which “the house after all is only the shell.” Wurster’s bareness leaves it ready for contstant reconfiguration—as an event space, as galleries of removable walls for end-of-semester showcases, for students working in all kinds of groups on all manner of projects. While the building itself can’t be disassembled and moved like Hearst Hall was, its interior is constantly disassambled and rebuilt.

This isn’t surprising for a modern design college, but I’m surprised to spot echoes of the 19th century building once built on the same ground. I’d go so far as to say that Wurster is the only building at Cal channeling Hearst Hall’s ethos: this openness to rearrangement, the deference to the building’s inhabitants to give it purpose and interest. Moreover, it’s one of very few buildings (along with the Hearst Mining building, donated by Phoebe Hearst in memory of her mining magnate husband), that reveals its own structure: whereas Hearst Hall bared its ribcage of laminated arches, Wurster Hall flaunts slab concrete.

The comparison doesn’t only spice up Wurster Hall; it reveals Hearst Hall to be, in some respcts, modern. Modularism, repurposing spaces, and the unity of structural and aesthetic elements seem like modernism’s innovations, but they’re all present in this 1899 building by an architect whose architect was in rebellion against industrialist modernization.

Buildings are weird texts; they don’t lend themselvves to comparative analysis. So much of architecture—Hearst Hall, for example—is unique: they aren’t reproduced like books from an ur-text, which means that when Hearst Hall burns down I’ll never really be able to “read” it as I can read an extant building. Even extant buildings are complicated. As a building’s purpose shifts, so does the way its occupants experience it. I like the idea, though, that buildings point into the past like the Archaeological Research Facility points, tongue in cheek, at its frat origins: “look what used to be where I am now; consider the purpose I was given then; consider the ruin I will eventually become.” Like Hearst Hall’s nested arches, spaces inside spaces.

After some continued reading on Bernard Maybeck, I’ve written a follow-up to this essay. It uses stronger evidence to cover much the same ground, and extends my discussions of Maybeck’s architectural philosophy and the design of Wurster Hall.

Corbett, Michael. “Hearst Memorial Gymnasium Historic Structure Report.” 2005: 12-13. Note: the most useful detailed, but brief, chronology of Phoebe Hearst’s involvement with UC Berkeley I could find.↩︎
Nabokov, Dominique & Darryl Pinckney. “Berlin Living Rooms.” Paris Review, 2017.
Never mind that I’m using this quote in a wildly different architectural context. It’s funny to compare International Style sparseness with Arts & Crafts sparseness. Two departures from 19th century maximalism, but departures towards very different metaphysics: medievalism and handcraftsmanship on one hand, modernism and industrial production on the other.↩︎
Cardwell, Kenneth H. Bernard Maybeck: artisan, architect, artist. Santa Barbara and Salt Lake City: Peregrine Smith, 1977. (157)
Also quoted in Le Guin, Ursula K. “Words Are My Matter: Writings About Life and Books, 2000-2016.” (52)
Le Guin grew up in a Berkeley house designed by Maybeck. Apparently quite a quirky one: “our house, for example, originally had no stairs to the basement. ‘Maybeck was moody about stairs.’” (53)
Le Guin calls Maybeck’s architectural philosophy premodern. I read The Left Hand of Darkness recently; maybe there’s an inspiration here for Karhide’s distinctly premodern cities, with their unreachable doors?
For more on Maybeck’s medievalism, see also Mitchell, James. Medieval San Francisco: Neo-Gothic Architecture in Northern California, 1900-1940 (2016), 89-96.↩︎
Kantor, J.R.K. “Cora, Jane, & Phoebe: Fin-de-Siècle Philanthropy.” Chronicle of the University of California 1, no. 2 (1998): 6.↩︎
Miller, Leta E. “Practical Idealism: The Musical Patronage of Phoebe Apperson Hearst.” Journal of the Society for American Music 10, no. 4 (2016): 397.↩︎
Kantor, J.R.K. “Cora, Jane, & Phoebe: Fin-de-Siècle Philanthropy.” Chronicle of the University of California 1, no. 2 (1998): 6.
For a gushing contemporary account of the events and activities to which Hearst Hall was home, see the 1904 Blue and Gold excerpt on page 9. For a detailed discussion of its impact on women’s athletics at Cal, see “A Gym of Their Own” (Park) in the same volume, especially pages 25-26.↩︎
Dougherty, Carolyn. The Loafer’s Guide to UC Berkeley.↩︎
Maybeck and Morgan were surprising choices: Phoebe Hearst vocally supported John Galen Howard, the Supervising Architect hired in the campus expansion competition she sponsored.
Howard turned out to be something of a tyrant. From The Loafer’s Guide to UC Berkeley, with my emphasis added:
[Howard] had always insisted on complete control of campus design, as well as the sole right to design campus buildings; this the Regents were no longer willing to grant him. In 1922 they awarded the design of the new Hearst Gym to Bernard Maybeck and Julia Morgan while Howard was in Europe. This building, and the attached buildings and grounds originally planned, were the seed of a “revolt” organized by Bernard Maybeck, Julia Morgan and William Randolph Hearst, whose memorial gym for his mother had originally been intended as the nucleus of a “countercampus” in the style of San Simeon.
There’s probably a much more dramatic way to tell this story: three generations of Hearsts (mining, publishing, and bank-robbing); fires; rival architects with their respective patrons…↩︎
UC Berkeley College of Environmental Design. College History.↩︎
UC Berkeley College of Environmental Design. College History.↩︎
Woodbridge, Sally. “Reflections on the Founding: Wurster Hall and The College of Environmental Design [Two Place Tales].” Places 1, no. 4 (1984).↩︎
National register of Historic Places. Registration Form: Palace of Fine Arts.↩︎

Web Syndication with JSON Feeds

2020-11-02T00:00:00Z

Web Syndication with JSON Feeds« blog 2020-11-02

Web Syndication with JSON Feeds

Sometime in the last ten years, while you were mourning the loss of Google Reader, we entered the golden age of content syndication. Our social media overlords hit the syndication Comstock Lode. For all their dystopic visioneering, I doubt the feed-accelerationists at Microsoft and Netscape in the mid 90’s foresaw these particular macroeconomics.

Arguably, though, we’re also in a golden age of nondystopic author-managed syndication. Free and nearly-free tools for hosting static sites are only outnumbered by static site generators; new ones are released every week. These tools, like blogosphere-era blogging platforms, can generate feeds as side effects of the routine publishing activity of their users; many do so by default. Even if it’s only a feed of content previews (to draw users onto the publisher’s site), each feed is a contribution to the digital commons.¹

Syndicated feeds — for which RSS, Atom, and JSON Feed are specifications — are essentially different from the feeds turning social media users into blue-app-anxiety foie gras. Rather than an algorithmically ranked and collated series of texts from a variety of sources, syndicated feeds just list items as a single source; the categorizing, collating, and display of those items is left up to feeds’ consumers. This has accessibility upsides, makes feeds easy to process programmatically, and provides a neat interface for users waiting on sparse updates (e.g. a blog that only updates once in a blue moon).

Providing a feed might mean content loses ad impressions to feed readers, but feeds generally align the interests of author-publishers who want their work read with the folks doing the reading.

The social challenge: maintaining and checking a feed reader will reward users only if their favorite sources of content provide feeds to be followed. For those sources of content, maintaining a feed (trickiest during site migrations!) is only worthwhile if readers would not otherwise follow them.

An introductory note on feed formats — RSS has the longest history and is the most widely-known, but its XML specification is pretty deeply janky. I would not recommend writing code for working with RSS feeds. Atom, RSS’s successor in the XML feed tradition, is a strict improvement. Most feed readers support both.

JSON Feed is a relative newcomer, introduced by the authors of NetNewsWire and Micro.blog. It has less client support than Atom/RSS, but it’s a sweet format to tinker with. I find JSON easier to read than XML, and my languages of choice these days (Go, Python, Typescript) have much nicer support for parsing and writing JSON objects than for XML (even with Python’s feedparser).

JSON feeds make syndication so simple that I’ve written a cluster of interrelated tools for working with them. Here’s a narrative breakdown of how they came to be and how I use them together.

Habitually collecting feeds makes one very aware of how many sites don’t (but should!) have them; how many have feeds but don’t prominently list links to them; and how many publications offer central aggregate feeds but not feeds broken down by category or author. I’ve built myself a few tools to help with this.

feedscan is a bash utility for discovering feeds by checking the routes that commonly host them: /feed, /atom.xml, and so on. If I find a sweet blog at lukasschwab.me/blog, I try feedscan https://lukasschwab.me/blog before digging for a link on the site itself. It’s totally disconnected from the other projects discussed here, but it has saved me a lot of frantic searches.

jsonfeed is a JSON feed parser and constructor package written in Python, the backbone to most of my other JSON feed tools. I wrote a Go equivalent, go-jsonfeed, but haven’t used it much. This very blog is generated with a fork of pandoc-blog, which generates a JSON feed using the jsonfeed package I authored.

I discovered a little running project for myself in building and hosting public feeds for sites that don’t offer them. I got my start with arxiv-feeds, which converts Atom to JSON using jsonfeed, but it’s a relatively boring wrapper. Blogs and news sites are more fun because they involve scraping feed items from the sites on demand. I wrote separate Python scraper/generator apps for a couple of sites, then realized those generators shared a certain procedural structure:

Fetch some target page.
Parse the target page HTML (with Beautiful Soup).
Extract feed items from the parsed HTML, an operation unique to each site.
Return the constructed feed.

Steps 1, 2, and 4 were essentially shared, so I factored them out into jsonfeed-wrapper, which takes the site-specific HTML-to-feed transform and wraps it with the standard fetching and feed-serving logic. I originally designed it for use with Google App Engine, but last weekend I rewrote it to expose a Google Cloud Function target.² Cloud Functions save me a couple bucks a month.

I generate and host feeds for It’s Nice That, Bandcamp artists, The Baffler, and Atlas of Places. Generating feeds from scraped HTML is somewhat brittle, but these have been reliable enough for the last few months. Adding a new site to the list takes about an hour of filling out a jsonfeed-wrapper template; shortening that time is the jsonfeed-wrapper project’s north star. Everything deserves a feed.

The next frontier: feed filters with CEL. cel-go works neatly with raw JSON, but the JSON Feed schema is well defined — why not create a CEL environment with types and macros for filtering feeds?

I have a Cloud Function that does nothing but parse Bruce Schneier’s RSS feed, filter out the feed items involing squid (Bruce’s hobby outside of security), and re-host the feed. There’s no reason this filtered feed should be re-hosted on its own when it could instead compile a CEL expression it receives from a client:

!item.tags.exists_one(t, t == "squid")

…and just return items where that expression returns true. User-defined CEL expressions are non-Turing-complete and safe to execute, so I can use them in lieu of parsing and documenting some feed-specific filter API. Different requests, passing different CEL expressions, can fetch differently filtered feeds from the same endpoint.

I will probably never convince anyone to host a feed that behaves this way, but that’s the neat thing about syndication: I can mirror or aggregate other feeds in a feed of my own that provides the interface I want. No need to ask anyone else to implement anything.

Podcasts are a good example of syndication working as expected: a system of RSS/Atom feeds means your podcast is available in whatever listening environment you like, including as a raw audio file. Platform-exclusive podcasts are trendy but somewhat toxic.↩︎
Rewriting jsonfeed-wrapper from something App Engine specific to something that could equivalently provide a Cloud Function was super simple because of how each of those Cloud Services register the code’s entry points.
Google App Engine’s Python runtime requires a WSGI-compatible object (in this case, a bottle application). Google’s Cloud Function runtime, on the other hand, asks you to define a function for handling requests.
The platform-ambivalent rewrite of jsonfeed-wrapper exports interfaces for constructing both, and everything but the request/response handling code is shared. Moreover, since instantiating a bottle app doesn’t do the hard work of actually running it, leaving the app definition in the Cloud Function code has a minimal impact on performance.
The result: each of my jsonfeed-wrapper applications can be deployed either as a Cloud Function or as an App Engine app without changing a single line of code.↩︎

Processing PDFs with Cloud Functions

2020-10-19T00:00:00Z

Processing PDFs with Cloud Functions« blog 2020-10-19

Processing PDFs with Cloud Functions

Two months ago I found the trove of papers on Nancy Leveson’s MIT homepage ¹, which planted the seed of a thought. Academic homepages are full of interesting reading (unpublished rambles; administrivia; pre-prints, the published versions of which are inaccessible behind paywalls). Academic homepages are also woefully ill-maintained. Why not scrape them?

They’re good candidates. Most are hand-written static sites with simple DOMs. Most are reachable from central departmental indices.

In the days after I found Dr. Leveson’s homepage, in the breaks between her papers, I threw together a scrapy spider for pulling PDF URLs a department at a time, and for jotting those URLs down into text files… but that’s where the project stalled out.²

https://arxiv.org/pdf/1711.02226.pdf
http://proceedings.mlr.press/v70/carmon17a/carmon17a.pdf
http://proceedings.mlr.press/v70/namkoong17a/namkoong17a-supp.pdf
https://web.stanford.edu/~jduchi/projects/SinhaDu16.pdf
...

My scraper was fast, but I had no interest in actually downloading tens of gigabytes of PDFs––tens of thousands of files!––that I would, realistically, never read. The code would be annoying to write and molassify my home network. I moved on to other work.

But what is cloud computing for, if not the senseless accumulation of online stuff? Google Cloud Platform (or the competing cloud platform of your choice) has everything we need to store and index the papers my scraper discovers:

A dirt-cheap blobstore for stashing files: Cloud Storage. Tens of gigabytes? Easy.
Ephemeral, networked compute resources: Cloud Functions. These achieve two tasks.
1. Ingestion: coordinate transfering PDFs into Cloud Storage.
2. Processing: once a PDF is stored, extract useful metadata from it (e.g. its text contents for search).

I haven’t used Cloud Functions much in the past (I often reach for App Engine out of habit, even when Cloud Functions will suffice). My impressions from this project:

Advantages	Disadvantages
+ Concurrency without code + Easy IAM permissioning + Built-in event triggers + Multi-language pipelines	- Awkward local debugging - Awkward remote debugging - Multi-minute deployments

Instead of focusing on their shortcomings, we’ll walk through what they handled well: I’ve indexed more than 20,000 PDFs––just over 20 gigabytes––and extracted 500 megabytes of plain text.

$ gsutil ls "gs://documents-repository/**" | grep ".pdf$" | wc -l
  20243

$ gsutil du -e "*.txt" -sh "gs://documents-repository/"
20.07 GiB    gs://documents-repository

$ gsutil du -e "*.pdf" -sh "gs://documents-repository/"
498.76 MiB   gs://documents-repository

All this without using ssh to connect to a server, configuring a network, sharing a client among concurrent routines, or spending more than $1.00.

Uploading documents

Our first challenge: process the old files of jotted-down URLs and persist the PDFs. Several properties of this problem make Cloud Functions attractive.

I can pipe the PDFs straight from the network into Cloud Storage without holding an entire file in memory.
Since there are so many PDFs, I’d like to download as many of them concurrently as possible. A highly concurrent program on a single device might end up I/O-bottlenecked, but each Cloud Function has its own network resources! Need more concurrent uploads? GCP will automatically provision more Cloud Function instances.
Since invoking a Function is lightweight––a POST request with a URL––we can eventually invoke it directly from my scraper instead of writing PDF URLs to an intermediate file. If the scraper code had to download and upload files itself, it’d be unworkably slow.
The scraper doesn’t validate the URLs; they end with .pdf, but they could point at anything. Some may lead to sites that no longer exist. Some may point at redirects. Since we have few guarantees about the quality of our input, we don’t have to bother managing failures in individual uploads. Let them fail!

We can split uploading documents into two scripts: a Cloud Function which takes a single URL and pipes the PDF to Cloud Storage, and a script that turns my scraped files into invocations of that Cloud Function.

Piping PDF data from a response body into GCS reminded me of Chris Roche’s post on splitting io.Readers Since this Cloud Function is self-contained and provides a neatly defined interface ((url) => pdf), we don’t have to worry about our upload language being suitable for analyzing/indexing the PDFs. We’re free to choose whatever language fits our upload style. In Go:

// Package nmt contains a Cloud Function for streaming documents to GCS.
package nmt

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"

    "cloud.google.com/go/storage"
)

// message is the data to parse from an invocation body. At this stage, there
// is no metadata besides a PDF URL.
type message struct {
    URL string `json:"url"`
}

// Name for the bucket to which documents should be written. This Cloud
// Function assumes the bucket is in the same GCP project.
const bucketName = "documents-repository"

// Ingest streams the file at a URL to Cloud Storage.
func Ingest(w http.ResponseWriter, r *http.Request) {
    // Parse invocation body for PDF URL.
    var decoded message
    if err := json.NewDecoder(r.Body).Decode(&decoded); err != nil {
        http.Error(w, "Failed to decode message", 400)
        return
    }
    filename, url, err := parseURL(decoded.URL)
    if err != nil {
        http.Error(w, "Failed to parse URL", 400)
        return
    }

    resp, err := http.Get(url.String())
    if err != nil {
        http.Error(w, "Failed to request URL", 404)
        return
    }
    defer resp.Body.Close()
    if resp.Header.Get("Content-Type") != "application/pdf" {
        http.Error(w, "Not a PDF", 404)
        return
    }

    // Create a storage client.
    ctx := context.Background()
    storageClient, err := storage.NewClient(ctx)
    if err != nil {
        http.Error(w, "Failed to create storage client.", 500)
        return
    }
    defer storageClient.Close()
    // Initialize a storage object by creating a writer for it.
    writer := storageClient.Bucket(bucketName).Object(filename).NewWriter(ctx)
    defer writer.Close()

    // Return a 200 status.
    w.WriteHeader(http.StatusAccepted)
    // Pipe PDF body to Cloud Storage.
    writer.ContentType = resp.Header.Get("Content-Type")
    written, err := io.Copy(writer, resp.Body)
    if err != nil {
        fmt.Println("Error encountered when piping to Cloud Storage", err)
    }
    fmt.Printf("Wrote %d to Cloud Storage\n", written)
}

// parseURL parses a URL. The returned filename is the URL host and URL path,
// concatenated. GCS treats the `/` tokens as folder separators.
func parseURL(input string) (filename string, url *url.URL, err error) {
    url, err = url.Parse(input)
    filename = fmt.Sprintf("%s%s", url.Host, url.Path)
    return filename, url, err
}

Less than a hundred lines, and not a buffer in sight! That io.Copy() call––from the HTTP response to the newly initialized GCS object––is doing the bulk of the work. Almost everything else is error handling.³ There’s pleasantly little tool-specific boilerplate, so this could be refactored into an HTTP handler function on a webserver if we saw fit.

Once this Cloud Function’s deployed, we can invoke it in a fairly tight loop: additional Cloud Function instances are automatically provisioned to manage the load. I wrote a short aiohttp Python script for this. Uploading 20 GB of PDFs––hundreds of PDFs at a time––takes just minutes. Conveniently, the object names are their URLs.

Extracting text

Extracting text from PDFs is hard. PDFs are essentially visual documents; they’re meant to be read visually rather than parsed programmatically. There are, broadly, two ways of turning them into plain text:

Optical Character Recognition (OCR) programs like Tesseract trade off efficiency and ease of configuration to play by this expectation: they extract text by considering a PDF visually. With intense computational requirements and long runtimes, OCR programs suit persistent compute resources.
Some PDFs (the ones wherein you can highlight text, copy/paste, etc.) have text embedded in them; we can use programs to extract that text dirextly. Unfortunately, this just doesn’t work if a PDF doesn’t include encoded text.

OCR is overkill for our PDF-indexing use case; extracting a bag of words will do just fine, and there’s such a wealth of PDFs on academic homepages that we can satisfy ourselves with indexing most of them. That’s not to say this text extraction is a simple thing to build yourself, or even easy to solve with libraries in a variety of languages: I struggled for hours with a Go module before giving up and switching to Python.

This is a sweet feature of a radically modular infrastructure: for a given stage of our data pipeline, we’re free to pick the language with the best support. When we need to pull text from PDFs, we can pick the language with the most effective published tools (like we picked a language that suited our ingestion strategy). Python has plenty; pdfminer.six is decent. In a cloud function:

from google.cloud import storage
import tempfile
from pdfminer.high_level import extract_text
from flask import abort


def main(request):
    """main is theCloud Function entry point. It downloads the specified
    existing PDF from GCS to a temporary location, extracts the text from that
    PDF, then uploads that text to a new GCS object.

    request -- the Flask request that invoked this Cloud Function.
    """
    # Parse object name from request.
    request_json = request.get_json()
    objectName = request_json['object']
    assert objectName.endswith(".pdf")
    print("Got request to handle", objectName)
    # Connect to GCS bucket.
    client = storage.Client()
    bucket = client.bucket("documents-repository")
    # Initialize temporary file for downloaded PDF.
    pdf = tempfile.NamedTemporaryFile()
    try:
        # Download blob into temporary file, extract, and uplaod.
        bucket.blob(objectName).download_to_filename(pdf.name)
        return extract(bucket, objectName, pdf.name)
    except Exception as err:
        return abort(500, "Exception while extracting text", err)


def extract(bucket: storage.Bucket, objectName: str, pdf: str):
    """extract pulls text out of a downloaded PDF and uploads the result to a
    new GCS object in the same bucket.

    bucket -- the GCS bucket to which the resulting text will be uploaded.
    objectName -- the prefix for the uploaded text object. Usually this is the
        object name for the processed PDF.
    pdf -- the filename for a downloaded PDF from which to extract text.
    """
    # TODO: silence pdfminer noisy logging.
    text = extract_text(pdf)
    # Upload extracted text to new GCS object.
    dest_blob = bucket.blob(objectName + ".txt")
    dest_blob.upload_from_string(text)
    return text

Downloading a PDF to a temporary file is clumsy, but the published tools expect filenames (and, as I said, they’re complex enough to dictate my implementation). Like the upload Cloud Function before it, we can invoke this one in a tight loop using the scraped URLs from before… et voilà! After a few minutes, the pdfminer output for each stored PDF is tucked next to its corresponding PDF in the bucket.

Listening for storage events

This extraction strategy works, but it involves manually triggerig both stages: first, we trigger PDF ingestion; second, after the upload is finished, we separately trigger our text extraction function. Instead, we can just trigger the ingestion, and have the “after the upload is completed” event trigger our Function automatically/immediately.

Google Cloud Storage Triggers are a neat Pub/Sub interface for invoking Cloud Functions. Instead of manually announcing “hey, I uploaded this object, it’s ready for processing,” the Cloud Function can consume the GCS-published finalize event marking the Storage object creations and updates. Refactoring our code from before:

def on_finalized(event, _):
    """on_finalized is the Cloud Function entry point for handling GCS object
    finalized events. It downloads the specified PDF from GCS into a temporary
    file, extracts the text from that PDF, then uploads that text to a new GCS
    object.

    event -- the received GCS event. Includes the bucket name and the name of
        the finalized object.
    """
    bucket = event['bucket']
    objectName = event['name']
    # Skip non-PDF files: this function writes to the bucket it watches.
    if not objectName.endswith(".pdf"):
        print("Skipping request to handle", objectName)
        return

    print("Extracting text from", objectName)
    # Connect to GCS bucket.
    client = storage.Client()
    bucket = client.bucket(bucket)
    # Initialize temporary file for downloaded PDF.
    pdf = tempfile.NamedTemporaryFile()
    try:
        # Download blob into temporary file, extract, and uplaod.
        bucket.blob(objectName).download_to_filename(pdf.name)
        extracted = extract(bucket, objectName, pdf.name)
        print("Success: extracted {} characters".format(len(extracted)))
    except Exception as err:
        print("Exception while extracting text", err)

The extract function––and, indeed, everything but the code to pull the objectName from the Pub/Sub message––is unchanged. With this update, there’s no need to invoke anything but the ingestion function: once a PDF has been streamed into GCS object, the text extraction will automatically kick off; we don’t need any second pass over scraped URLs.

We can daisy-chain this further by writing Cloud Functions invoked by finalize events on .txt objects, or publish events to Pub/Sub topics linking successive pipeline stages. TFIDF? Elasticsearch? Write the next stage in Typescript? The sky’s the limit.

I skimmed most of the PDFs listed on Dr. Leveson’s site. If you’re interested in software-system safety analysis, my personal favorites were
- “Systems Theoretic Process Analysis (STPA) of an Offshore Supply Vessel Dynamic Positioning System.” I skipped a lot of the topic-specific detail, but its STPA overview is one of the best I read and its example (maintaining the relative positions of two ships without running either aground) is memorable.
- “Software Deviation Analyis: A ‘Safeware’ Technique.” Discusses modeling a software system and, well, kind of Chaos Monkeying it: see what happens when different combinations of the software’s controls are violated.
- “Inside Risks: An Integrated Approach to Safety and Security Based on Systems Theory.” A strong case for cross-applying principles from system safety (Leveson’s primary focus) into information security (my primary focus these days).
Leveson doesn’t index them by title, but they’re in there!↩︎

The scraper that produces the lists of PDF URLs is pretty janky. It requires some tweaking for each academic department. The abridged code:

import scrapy
from scrapy.linkextractors import LinkExtractor

class CustomLinkExtractor(LinkExtractor):
  def __init__(self, *args, **kwargs):
      super(CustomLinkExtractor, self).__init__(*args, **kwargs)
      # Keep the default values in "deny_extensions" *except* for PDFs.
      self.deny_extensions = [ext for ext in self.deny_extensions if ext != ".pdf"]

class Spider(scrapy.Spider):
  name = "nmt-spider"
  # allowed_domains limit the domains to be scraped rather than the PDF links
  # to be extracted.
  allowed_domains = ['department.domain.edu', 'personal.sites.domain.edu']

  def start_requests(self):
    # An iniial entry point; usually a faculty index.
    yield scrapy.Request(url="department.domain.edu/faculty")

  def parse(self, response):
    pdf_extractor = CustomLinkExtractor(allow=r'.*\.pdf$')
    with open("jots.txt", "a") as f:
      for pdf_link in pdf_extractor.extract_links(response):
        f.write(url + "\n")
    for link in LinkExtractor.extract_links(response):
      # ...filter out problematic links here before yielding.
      yield response.follow(link, callback=self.parse)

Running scrapy runspider scrape.py yields a file jots.txt full of PDF URLs.↩︎

I made a conscious effort to stick to “The Kyoto School of Go Nihilism”––every err checked, every deferred function executed.↩︎

Web App Product Ontologies

2020-08-22T00:00:00Z

Web App Product Ontologies« blog 2020-08-22

Web App Product Ontologies

Web apps with user interfaces lend themselves to object-orientation. It’s in the middle of the acronym: Document Object Model. This isn’t to say you a “functional” product model is impossible, but visualizing a function involves expressing it with an object; to shoehorn a product model into a UI is to congeal it into an assemblage of objects.

Articulating a good product model requires picking the most expressive classes of objects and describing how they’re conceptually related: developing a product ontology.¹

Formal XML-derived syntaxes have been developed for physical product ontology, but the primacy of physical components makes them awkward fits for describing the product models behind web applications. Whereas physical product ontologies describe concrete units—an air purifier with one fan assembly and one filter assembly, working together—a web product model is essentially nonconcrete until runtime.

Lee and Suh’s meta-product ontology divides entities into physical and abstract entities.² Web app product models rarely have equivalents to physical Objects (global and static), but deal heavily in SetOrClass and Datatype entities that are instantiated by users.

Rather than describing a collection of identifiable entities and their relations, then, a description of a web product specifies classes of entities and the relations between their classes. A user who udnerstands those classes and relations can use the product to express and control the concrete, identifiable stuff.

In some respects, this is an easier task than developing a formal language for describing air purifiers! Web product planning can borrow the notion of an underlying, describable ontology without falling into the mire of rigidity/nonrigidity, subassemblies, and so on. Because the product’s implementation in code is an unambiguous and analyzable expression of the product’s structure, a web product-modeler doesn’t have to be as exhaustive.

What are your product’s primary concepts, its objects under manipulation? When a user uses your product, what do they control?

I think of this as nailing down a product model’s noumena, those stubborn concepts that persist independent of their representation. Whether or not they’re expressed directly—whether or not the user even conceives of the product in their terms—these are the product’s underlying objects. An app for scheduling events, no matter what interface exposes, works with some internal notion of what constitutes an “event;” this is its primary noumenal class.³

Describing noumena and interdependencies early could kick off data model design before, or concurrently with, interface design. A well-expressed product model can be the joint precursor to both, rather than building one to fit the other.

That said, sketching a product ontology shouldn’t be mistaken for data model design. The engineering task is to produce a data model that can unambiguously represent the space of permitted product model states. There may be multiple data models that achieve this. In my experience, a single product model will be implemented and reimplemented with a succession of data models before it’s changed.

As a result, it’s easy to think through other products’ ontologies without thinking about the details of their implementation.

An example: Trello is essentially a tool for organizing cards representing records. Their product involves other nouns—lists, boards, etc.—these are derivative concepts for organizing and displaying cards. Regardless of whether you click on a card on a board, in a calendar view, or in the archived query view (when a card has been disassociated from its board/list), the card is readable and editable in exactly the same popover format. Easy to recall, easy to teach.

An unpleasant example: I can’t think up a tight product ontology for Notion. Is it for organizing records (in table or gallery views)? Is it for organizing lightly interactive pages, like a wiki with embedded forms? Or am I organizing the sections of content on those pages, which are drag-and-drop rearrangebale? There must be some underlying consistent data model, but I can’t find it in the fog of concepts and interactions.

A good product teaches its users to perceive its abstract product model, and to intuit based on their understanding thereof. While the noumena in that model may not be represented directly or consistently, users will learn them more effectively when they are.

Controlling noumena

We can turn sketched classes of product entities into a fistful of representational litmus tests. The product we build around our ontology will necessarily involve mechanisms for users to view, organize, and modify our noumena. Representing the entities in the product model directly and comprehensively should keep the user’s model of the system state close to the system’s internal state; keeping a user’s understanding accurate should minimize corrective error.⁴

Consider your product as a control interface for each class of entities: how ergonomically can a user assess the state of an entity and cause precisely the represented change they intend? To that end…

How many instances of a given noumenal class do you expect a user to have to manage? If this number is unbounded, consider building query and filter interfaces from the jump.
Are all the properties on a noumenon represented directly? Is there a place in your product where they’re represented together in one place, viewable at once on standard screens?
Does the user control a value indirectly when they could reasonably control it directly?
This can lead to miscorrections. This is a common control pattern in physical systems—you can’t directly control the location of a boat (“position control”), but you can control the location indirectly with the throttle (“heading control”)—but not for web apps.⁵

Is the manner of control consistent throughout your application? Can a user possibly modify a noumenon without realizing they’re doing it? Punishing!

The Cognitive Dimensions of Notations framework⁶ is a list of digital product usability anti-patterns (with some neat properties, e.g. pairwise independence). It may seem a stretch to think of web apps as “notations,” but these antipatterns can appear anywhere users do composition (whether they’re composing a vacation, their account settings, or a program). Users work to get a product to express their intent. Blandford and Green turned the Cognitive Dimensions of Notation into a set of usability litmus tests like the ones I propose above.⁷

Besides this usability-forecasting, a well-specified product model offers a nice starting point for breaking a product into reusable components. It might be sensible to build a single component to manage representing a noumenon in a variety of contexts; “cards” (neatly arranged into arrays; vertically more forgiving than table rows) are a common pattern for this. If certain contexts require the card to be too compact to be a good control surface, clicking on it can pop a more articulate modal:⁸ picking noumena that exist independent of outside context should mitigate the context-downside of hiding the rest of the page.

Comparative advantage

Instead of beginning with ontology, we could begin with functionalism: “what do users want to do with our product?” This doesn’t avoid creating a product ontology, but it defers to an imaginary user’s incumbent ontology. If a product would simplify a complex workflow, this approach cements into its heart an model just as unwieldy as the one it should replace.⁹

Focusing on user workflows too early also runs the risk of tailoring our data model too closely to a particular representation that achieves a very specific function. Since representations are immediately user-facing, they’re more likely than the data models to be subject to early user feedback and iteration. Better to build a flexible data model and leave our UI easy to invalidate.

Directness and comprehensiveness are useful heuristics for UI options. Conversational interfaces are hip for their humanism, but a conversation with intense control requirements is frustrating: it’s untransparent, which makes it error prone.

Winograd (1979)¹⁰ gets at something similar, which he terms “the subject domain.” One difference: he treats it as a puzzle for programmers rather than a dedicated “product” function, so he places special emphasis on the difference between a product ontology and a data model:

This system [for organizing room assignments at a university], like every practical system, is about some subject. There is a world of rooms and classes, times and schedules, that exists completely apart from the computer system that is understood as referring to them. […] One of the primary tasks in programming is to develop a set of descriptions that are adequate for talking about the objects being represented. There are descriptions for things we think of as objects (e.g. buildings, rooms, courses, departments) and also for processes (e.g. the scheduling of events). These descriptions are relative to the goals of the system as a whole and embody a basic view of the problem. For example, what it takes to represent a room would be different for this system and for a system used by contractors in building construction.
All too often the development of descriptions in this domain is confused with the specification of data structures (which are in the domain of implementation). In deciding whether we want a course to be associated with a single teacher, or to leave open the potential representation of team-teaching, we are not making a data structure decision. The association of a teacher (or teachers) with a course may be represented in many different data structures in many different components of the system. One of the most common problems in integrating systems is that the components are based on different decisions in the subject domain, and therefore there is no effective way to translate the data structures.

Winograd argues

A programming system needs to provide a powerful set of mechanisms for building up and maintaining ‘world views’—coherent sets of description structures in the subject domain that are independent of any implementation. Each component can then implement part or all of this in a way that will be consistent with both the structure of that component and the assumptions made in other components.

Those nineties product ontology projects might be seen as languages for this kind of specification, but with the big ambition of describing any system, any “world-view” or set of relations. Teams seem to do this kind of work in documentation tools, but they rely on the total flexibility of linked text; Winograd argues docstrings are too local, too prone to inconsistency, to count.

I might just be reinventing domain-driven design. My “noumena” captured by are classes and individuals, ontology components.

I feel strongly that “noumena” was a poor choice, not least because it suggests a difference from “phenomena” for which there isn’t a product analogy.

This goal is complicated by the reflexive relationship between a product’s ontology and its functionality. Some ontology might achieve a product’s functional intent better than others… but the functions users desire are themselves formed through their understanding of the product model, and they can more articulately communicate desires in terms of the product concepts that are named for them. An ontology-axiology bind!↩︎
Lee, Jae-Hyun, and Hyo-Won Suh. “OWL-based product ontology architecture and representation for sharing product knowledge on a web.” In International Design Engineering Technical Conferences and Computers and Information in Engineering Conference, vol. 48035, pp. 853-861. 2007.↩︎
I’m self-conscious about “noumenon” being a pretentious term, but there’s a utility for me in setting up an unfamiliar category. Terms like “entity” or “object” are overloaded (esp. “object,” in an essay that’s essentially about preferring object-oriented representations for noumena).
It should be clear that we’re not talking about the instance a user perceives and interacts with. A user’s perception of the product model is wont to be inaccurate; whether there’s really a correct perception of a product model feels like a question for metaphysics.
A user’s perception of the product model may be more or less close to the designed product model, though, and the control systems reading I reference supports my opinion that closeness here is good. The term “noumenon” emphasizes the fallability of the UI phenomena you build.↩︎
I’ve been poking thorugh Åström, Karl Johan, and Richard M. Murray. Feedback systems: an introduction for scientists and engineers. Princeton university press, 2010.↩︎
“Position control” and “direct control” are terms taken from Abrecht, Blake, and N. G. Leveson. “Systems theoretic process analysis (STPA) of an offshore supply vessel dynamic positioning system.” Massachusetts Institute of Technology, Cambridge, MA (2016).↩︎
The Cognitive Dimensions are decently summarized on Wikipedia, but more clearly in Blackwell, Alan, and Thomas Green. “Notational systems - the cognitive dimensions of notations framework.” HCI models, theories, and frameworks: toward an interdisciplinary science. Morgan Kaufmann (2003).↩︎
Blandford, Ann, and Thomas Green. “OSM: an ontology-based approach to usability evaluation.” Note: the notion of user-private, device-private, and shared concepts butts up againts my idea of a “noumenon” here, but more value-neutrally. In my mind, the noumena form a starting set of shared concepts.↩︎
Trello does this, but Airtable’s modal view for a record is a great example from a more complex product. Sometimes the record is a row in a table; sometimes it’s a card in a gallery; no matter what, clicking on it will reveal all the data for the record and allow you to directly modify any of it. No matter the representation, the user is one modal-expanding click away from a consistent control experience.↩︎
Additionally, users are nonhomogeneous; overfitting to your early users’ mental models might be a mistake. This is especially true for teams with the ambition to shift up/down-market or stretch their product into new applications, or strong selection biases in their initial user base (e.g. a bias towards users from a certain accelerator cohort).↩︎
Winograd, Terry. “Beyond programming languages.” Communications of the ACM 22, no. 7 (1979): 395.↩︎

Architecture and Organs

2020-07-25T00:00:00Z

Architecture and Organs« blog 2020-07-25

Architecture and Organs

Last November, at the end of a long day of walking, I sat in Saint-Étienne-du-Mont and tried to sketch its rood loft. Without any announcement, the organ started playing. This was a striking experience: totally still and dimly-lit (memorably dimmer than it is in photos online), the body of the church was suddenly full of sound.

I’ll discuss two interplays I’ve picked out of this experience in Paris: first, between the organ and its architectural enclosure (its place), and then between the organ and the organist. I’m interested, from a theoretical perspective, in how an instrument (in the general sense: a tool) can behave as a sort of architecture.¹ My typology of organs is sloppy, but I’m particularly interested in big religious pipe organs, and especially those where the console is obscured.

This post covers the first interplay: between organs and their enclosures.

In some respects, pipe organs just occupy the space allowed to them. In churches designed with pipe organs in mind, this might mean it fills an organ loft, or it might hang from an arch or perch on a choir screen like the nest of some infernal wasp. Organ case design differs dramatically, often to the end of integrating the instruments with their surrounds. Baroque cases gild the mechanism; ornate folds and statuettes hide the sharply geometric ends of the pipes, blur the instrument’s edges, and fill the seams between an organ’s angular guts and the rounds of its enclave. Rococo organ cases are suitably ludicrous.

In gothic cathedrals (or with more modern organs) this effect might be more subtle. At the Basilique Saint-Denis, the organ is connected to the surrounding architecture by its case’s mock-tracery. The three darkened sections of Cologne Cathedral’s transept organ recall the cathedral facade’s black, tripartite bulk. In Reykjavik’s Hallgrímskirkja, where both the instrument and the church experiment with gothic forms, the clusters of pipes and their angular brackets recall the exterior’s quasi-basalt.²

Musically, on the other hand, the enclosure becomes a part of the organ. The acoustics of premodern churches might be as much by accident as by design, but each is a unique acoustic extension to the instrument it contains. This is true of other spaces and other instruments, but a given organ is fixed in a particular acoustic context and the range and timbre of pipe organs makes their music feel especially reverberal. Inasmuch as its musicality is bound up with its space, the same instrument in two different spaces isn’t really the same instrument.

The organ exterior is so static, so visually unmoved by the sounds it makes, that its music feels like sounds the space makes itself. I think this must be, at least to some extent, an association born of an organ’s unique capacity to hold notes without modulation or end: no quaver of human breath, no percussed dissipation, no reversals in the direction of a bow. What else could sound like an edifice?⁴ This connection between musicality and place is especially strong in Áine O’Dwyer’s Music for Church Cleaners: this isn’t an aterritorial instrument carted into a recording studio, but rather the music of a particular site of labor and ritual, complete with the shuffling of feet and quiet clatter of brooms.

Music For Church Cleaners by Áine O'Dwyer

By contrast, other pipe organ recordings are engineered in an effort to extricate the instrument from its architectural setting. The recording does its best to silence the architecture, but comments like this from the release notes for Kali Malone’s The Sacrificial Code admit the concomitance of an organ and its setting:

The recordings here involved careful close miking of the pipe organ in such a way as to eliminate environmental identifiers as far as possible—essentially removing the large hall reverb so inextricably linked to the instrument.

The Sacrificial Code by Kali Malone

This close relationship with place also yields an artistic association with the church/state/power trinity: there haven’t been that many pipe organs, and every one of them is an exceptional mobilization of craft and capital. It’s a quintessentially baroque instrument. Along with colonially exported baroque architecture, colonial organs signify hegemony by design. Spain razed Tenochtitlan’s Templo Mayor and built a cathedral in its place; in that cathedral the Spanish crown comissioned a succession of organs, including its twin surviving mahogany behemoths.

That the organs in Mexico City wall the choir off from the choir-aisles underscores their social function:

The clergy needed some kind of barrier to separate them from the laity, in order not to to be disturbed at their prayers, which took place seven times a gday, and it was from this need that rood-screens and screens dividing choirs from choir aisles developed. […] These high screens, which sometimes take the form of walls (for instance, at Lugo in Spain), destroy the open view that was originally intended, and, because of this, many rood-screens in France and Germany were later removed. The exclusion of the congregation was felt to be too aristocratic, and even the clergy probably found this attitude of separation presumptuous. […] Their purpose, stated barely and soberly, was to express a system of social strata.⁵

The sound itself, even absent a physical organ, has this baroque-architectural connotation. Last Year at Marienbad’s opening Möbian catalog—of stucco, carpets, hallways opening onto hallways, an architecture too slippery for memory—loops against Francis Seyrig’s ornamented organ score.

I’d call all three of these compositions “ambient.” Not all organ music is ambient, but both architecture and the organ have strong aesthetic ties to ambience. My claims about the acoustic and visual interplay between an organ and its enclosure are probably uncontroversial, but this poking at an aesthetic isometry via ambience really captures my imagination.

My assertion that organs as instruments are tied up with architecture makes me nervous. What about organs that have been restored and moved from one space to the other? What about the great trends and conflicts in organ tonal design––have I done the necessary reading to make some totalizing claim about the instrument’s connection to place?

I’ve done some nervous googling to check that I’m not way off-base. One article:

The beauty of the organ — or the curse, depending on your point of view — is that no two are alike; each is built and voiced to fit the acoustics of a particular room. A pipe organ does not travel. […] because the pipes can be located several hundred feet from the manual, they often “speak” at slightly different intervals from the moment a key is pressed.

And another:

But the organ itself is just one part of the sonic and aesthetic equation; the other is the architecture that houses it. To hear an organ fully is to experience it in what organists call “the room.” Whether an intimate hall or a vast cathedral, the size, shape, and building materials are vital factors.

“Consoles” (as in the architectural brackets) are a joint etymological ancestor for organ consoles and electronic consoles. This is probably the kernel of what I find interesting here: the console simultaneously fixes the function of a space and constitutes a part of its architectural form.↩︎
I found this brief overview of the adaptation of Gothic-architectural motifs to organ case designs. Crenellation feels like a distinctly pre-gothic inclusion on these original organs, which leads me to wonder if the earlier organs at Saint-Denis (a basilica completed in 1144) mimicked their surroundings as carefully as its current instrument (the last in a line of sevaral organs, built in 1841). If I had to guess, the stylistic similarities have probably gotten stronger as successive revivalist waves became more self-aware; this probably subjects me to a kind of recency bias.↩︎
Gilman, Roger. “The theory of gothic architecture and the effect of shellfire at Rheims and Soissons.” American Journal of Archaeology 24, no. 1 (1920): 37-72.↩︎
The impression that an organ’s sounds belong to the building itself might be especially dramatic at the S.F. Legion of Honor: the Spreckels Organ’s pipes are hidden in the building’s walls. I haven’t had a chance to catch one of their concerts yet, but I probably prefer organs I can look at anyway.↩︎
Frankl, Paul, and Paul Crossley. Gothic architecture. Vol. 58. Yale University Press, 2000. 226.↩︎

Filename	Count on GitHub, Feb. 2025
.golangci.yml	27,700
.golangci.yaml	6,600
.golangci.toml	624
.golangci.json	200

Metric foot	Example	Syllabic emphasis
pyrrhic	to a	`00`
iamb	unite	`01`
trochee	highway	`10`
spondee	hog-wild	`11`
dactyl	poetry	`100`
anapest	underfoot	`001`

lukasschwab.me • blog

Spain Bibliography

Gothic Micro-Architecture

Bring Your Own Linter

Write a custom linter: analysis

Build a standalone linter; run it

Customize golangci-lint

Adapt your Analyzer

Build the linter binary

Custom golangci-lint in VS Code

Custom golangci-lint in GitHub Actions

Getting back to basics

An experimental metalinter: glint

References

Deriving Safe ID Types in Go

Assumptions

Defining a new string type

Embedding uuid.UUID

Defining a new uuid.UUID type

Aliasing uuid.UUID

Summary

In Defense of New Boggle

Dictionaries

Same-games

Play and Experimentation

"Mystery Box" Economics

Postmortems are for Reading

Applying the "Hierarchy of Controls"

Safety Through Incompatibility

'Magic' in Elixir's `Logger`

Functional work-arounds

Better: explicit sharing

Applying "Laws" of Software Evolution

Paris Redux

Three-Step Lifted Interfaces

Example: refactoring a logger

Step 1: break everything

Step 2: lift the interface

Step 3: fix the build

Shortest paths

Four Translations of *Todesfuge*

Todesfuge (1948)

Translations

John Felstiner (1986)

Michael Hamburger (1972)

Jerome Rothenberg (2005)

Karl S. Weimar (1974)

Ceci n'est pas...

Easier OCR on macOS

Install OCRmyPDF

Add a Shortcut

Comparing Vertex Cover Algorithms

Experiment space

Vertex cover algorithms

Topologies

Weight schemes

Project structure

Simulations

lavrov overview

clever overview

Graphs at Work

Cracking the graph

The graph cracks back

Technical Writing for Sequin

Managing Emails from Recruiters

Tech Debt and Taxes

Collected Memories of Evans Hall

Hearst Hall: Continued Reading

Style and Structure

Adaptation

Loss as final adaptation

Losing Hearst Hall

Modernism

Wurster Hall

On sources

Genres and Subtraction Tests

Blogging with TikZ

Arriving at TikZ

Implementation

Converting TikZ to SVG

Write a custom linter: `analysis`

Customize `golangci-lint`

Adapt your `Analyzer`

Custom `golangci-lint` in VS Code

Custom `golangci-lint` in GitHub Actions

An experimental metalinter: `glint`

Defining a new `string` type

Embedding `uuid.UUID`

Defining a new `uuid.UUID` type

Aliasing `uuid.UUID`

Four Translations of Todesfuge

`lavrov` overview

`clever` overview

Building images in `pandoc-blog`