Crate cold_iron

A Brief Introduction to Nanothaumaturgy

Witches have been using pentacles and sigils since time immemorial. Scratched into a doorframe, drawn in chalk on a basement floor, even built into a town’s skyline, they were merely a part of the landscape. No more noticeable than a pigeon or discarded glove, they nonetheless formed the underpinnings of the ancient world.

Of course, humans are naturally inquisitive creatures. Certainly someone must’ve been the first to carve a circle of power into a tree stump or a pentagram into a beloved cook-pot. How did they discover the now-famous building blocks, like Su’s Forecross and the Tecumseh Branch? Was it merely trial and error, an unknown body count in the wake of misshapen 3Z? Divine intervention, whatever deity unwilling to let humanity not glimpse the fullness of Their vision? Is this something humanity has simply always known, as a sheep dog herds or a goose flies south?

We may never know the answer to these questions. Modern Thaumaturges need to be part linguist, part historian, and part librarian. Just like the English legal system stretches beyond the horizon of recorded history, some knowledge is locked forever beyond our grasp. What we could — and did — do is study what we have. It’s clear, despite the “arcane” moniker, the makeup of wardings and summoning circles does not exceed the limits of a sharp human mind. We cross-referenced cultures, combined glyphs, and performed endless experiments, and through this investigation we were able to discover the true nature of what we’d been dutifully copying down.

Any spell contains two components: the Shape and the Direction. Shape is universal across cultures: from Paris to the Polynesian, the same constructs appear over and over again. They act as conduits for thaumic energy, directing it where it needs to go, twisting and bending it to do the creator’s will.

That will is expressed by the Direction. At one point it was believed these too were fixed constructs. Well into the 19th century spellcasters were dutifully inscribing Sumarian and Latin onto their circles, careful to not misplace a single stroke. In the end, it may not even have mattered if they got it correct: they thought it would work, and so it did. Eventually, a few bright witches got tired of translating Sanskrit and just tried writing incantations in vernacular Dutch, and were very surprised to find their magic was just as powerful, if not more so.

Fast-forward to the late 20th century. Computers are exploding, going from building-sized to button-sized in a single lifetime. Old warlocks can be stodgy, but it was just a matter of time before someone decided to hex their modem to speed it up, and from there it was off to the races.

How small a Shape can you build before it ceases to work. We have not yet found any practical limit. A modern SITA (Self-implementing Thaumaturgic Array) can encode thousand of Shape fragments a second. Days spent painstakingly drawing in chalk can be accomplished in the blink of an eye.

And as for the Direction. We engineers already form communities and alliances by the languages we use to commune with our machines. Well-commented, properly architected code has no problem at all Directing all those Shapes. The SITA on your desk can perform an incantation that would’ve taken Ming priests a month to prepare.

That’s not to say you can work miracles, of course. Unless you’re lucky enough to be located on a leyline, the ambient magic of your environs isn’t good for much more than thaumocryptography or intrusion detection. But there’s plenty of useful work to be done in this space! cold-iron aims to be robust enough for an industrial Ley Foundry, but simple enough to use for a beginning Thaum to spin their first Circle.

Take a look at the submodules below to get started! Nanothaumatology is built on the shoulders of giants, and these libraries will get you hoisted up in no time.

Comparison to libthaum

Why should you consider a pure-Rust nanothaumatology library like cold-iron, instead of the existing libthaum implementation in C, or foreign bindings like libthaum-lib? Asside from the awkward name of the latter, there are a couple reasons.

libthaum was created back at the beginning of the nanothaumatological revolution, and it’s maintained backwards compatibility since then. Provided you could find the right compiler, an incantation written in the late 80s would still work just as well today.

Such backwards compatibility is admirable, even impressive. But the resulting API can be extremely difficult to work with, even for experienced programmers. Rust’s focus on ergonomics is useful and convenient for regular programming, but for SITA programming it becomes essential.

Remember that the Direction is based partially on intent. Usually, this is an asset: even if your spelling is a little off or your penmanship less that stellar, your spell is likely to work anyway. Unfortunately with nanothaumaturgy that quickly becomes a liability. For an incantation to function, you must understand at least the gist of what it is doing. You don’t need a degree in advanced semiconductor design or kernel programming, but an opaque library makes your job that much harder.

coldiron sorts basic thaumatic components into easy-to-understand building blocks. While it can take years to be comfortable with libthaum (and even then a good programmer is wary), you can safely write your first incantation in minutes. Rust’s safety guarantees will keep you from destroying your nice new SITA, and there’s a community of helpful Thaums willing to help out.

The example directory and this documentation should help you get started!

Modules

crypt	Libraries for cryptothaumaturgy
detect	Library for building Thaumatic Intrusion Detection Systems
net	Libraries for long-distance thaumatic communication
sita	Abstraction layer for Self-Actualising Thaumatic Arrays (SITA)

Macros

mnemonic	Compile-time reminders of intent
thaumtest	Stochastic testing for intent-influenced programming

Enums

ThaumError

Represents various error conditions that result from Thaumatic programming