calculang 💬

only for calculations ⇔ numbers ⇔ workings

calculang doesn’t ‘do things’ (“side-effects”) like regular programming languages 💥

This serves to simplify, permitting the aims above for calculations, numbers, and their workings ✅️

portable 💨

calculang models compile to highly-portable Javascript modules. Besides private usecases, outputs such as numbers and visualizations can be placed directly in a blog post you read ¹, in a dashboard for your teams metrics, in your banking app, and so on.

formulas as building blocks 🧱

In calculang, formulas are the building blocks of calculations. Formulas are “pure functions” for mathematics or FP audience; for everyone else: they’re just like spreadsheet formulas.

calculang formulas are flexible ♻️: not only can they be re-used, they can be re-used with specified changes: specified at the formula-level.

calculang facilitates transparency at the same formula-level (because formulas are exported as a rule).

versus spreadsheets

In calculang, layout and presentation is separated from calculation logic: and there can be many of these.
Every formula is given a name, so that there is no need to debate v or hlookups vs. index-match 🤯
Flexible formulas and modularity allow us to give more meaningful and maintainable structure to many common patterns we create in spreadsheets.
calculang models are “code” and as such can integrate readily with state-of-the-art tools and practices around auditability, version control and testing and development.

tools 🧰

A calculang introspection API makes it convenient to build tools (even environments) that interact with calculang models and their formulas in meaningful ways.

It includes all of the information needed to transpile from calculang source into Javascript output; and more besides.

introspection output 📜

every calculang formula
- their source locations
- and their input dependencies
every calculang call within calculang code
- and their source locations
all calculang relationships (links)
information about source files, calculang scopes², and how they are related through the module graph

There is some documentation here, but you can also see introspection outputs using this experimental tool.

visualization APIs & calcudata

One calculang tool is calcuvizspec: a visualization API that uses Vega-Lite to map model features (formulas and inputs) directly to visual marks.

A presentation including some examples is here (toggle Code blocks).

This API exists due to a need model developers have: they must be able to very quickly see numbers from a model, and iterate the model and outputs quickly during the development process.

A separate API: calcuvegadata, is more efficient for development- or finalised- model outputs which respond to interactivity.

calcudata is a convenient lower-level API for querying numbers.

These APIs include a notion about a cursor: representing inputs where a single value is provided, and domains: representing inputs where a range of values are provided (and their cross-product is used).

These are opinionated APIs: none of which are prescribed. Different opinions about patterns to use models are encouraged!

chronicles of calculang, Feb 2025 (published work), and status

Examples

The examples on this website are dated: from approx. December 2023. Here are other newer examples and experimental environments that I’ve been working on since then:

Relatively new/more experimental bits:

up squine and cosquare
Savings Calculator with highlights
HowMuchIs13BillionEuros.com: a website and environment I experimented with (context)

Selected from “next-calculang-gallery” (GitLab):

Raycasting (VIDEO 📹)
bouncing ball ⚽⛹️‍♂️ Scrollytorial Here I was experimenting with some tutorial presentation - using scrollytelling and gemini transitions

Selected from “calculang-editables” (GitHub):

tixy.land clone (VIDEO 📹)
Dungeon Generator
❤️ Calculator (VIDEO 📹)
Generative Spirographs 🌀
Sun and Moon Paths WIP
Sun and Moon Paths ii WIP
Falling Sand
Editable Music (⚠️ sound Low!)
Savings Calculator with working highlighting of workings
- There is a newer and more informative (for developers) version of this here (noted above)
Reactive Inputs This was a nice experiment at reacting to model code changes. You need to checkout the repo to try it

I have other examples that I use in my blog, though readers might not notice! 💫 My blogs are usually communicative pieces using interactive calculang models to illustrate messages - I do not show the formulas as I do in calculang examples. But calculang is operating behind the scenes, and you can find the model sources on GitLab.

calculang-at-fosdem.pages.dev is a website including examples I used for one presentation at FOSDEM 2024 (recording). Using that environment I demoed “reactive workings” for the first time (double click on numbers in the Savings example to activate an overlay).

(old) in 2023 I spoke at BelfastJS: my first time presenting calculang to a crowd 🙂. A website I made is calculang-talk-belfastjs.pages.dev where I demoed “three little applications” (plus a bonus)

For completion, there are older published examples on ObservableHQ and calculang-miscellaneous-models. Other examples and an early environment in calcy-quary-vizys-online.pages.dev and models-on-a-plane.pages.dev. I partially migrated ClimateMARGO.jl which was fun. index2 has easter eggs, including a raymarching model that can use more interactive/explanatory work to be a highlight.

There has been no consolidation in environments/examples because calculang is still evolving.

📢 Soon, a key model release will be a (first ever?) interactive and visual actuarial cashflow model. Actuarial modelling can push calculang into new and interesting territory, but applications across a wide range of domains is fundamental for a language for calculations.

Themes

The examples I developed with calculang seem to cover many very different themes: pension and savings calculators, then gaming algorithms, creative coding environments, then solar system models, and other wild patterns.

Education was/is an important theme for much of it. When I develop I aim to have instant feedback as I thinker with models. This along with calculangs pure formulas distinct from general programming, could be an interesting way to introduce coding, or to “play with” and explore particular models. I am happy to discuss this with people who are interested!

Further, models have a problem whenever they do many things: this really crops up with flexibility in models. You need ways to see and interpret all the things. You need this when you are done: to communicate, and critically too while you develop.

This is why I am highly invested in visualization and interaction. It’s to solve modelling problems. Ability to explore and ability to communicate with models are modelling problems: not (by themselves) distinct new problems or interests.

Presentations

FOSDEM 2024 (Feb):

Recordings available, each is ~17mins:

calc with calculang, a language for calculations given in the Javascript devroom (There are 2x short drops due to technical issues) slides | website
declarative calcs and visualization with calculang given in the Declarative and Minimalistic Computing devroom slides

Finding calculang, a lightning presentation I gave to the Future of Coding community

Presentation about calcuvizspec, an early visualization API.

LISP Ireland, Aug 2024:

Recording (poor sound quality warning. Screen share starts at 9mins, talking starts at 5mins15s)

2023 BelfastJS talk: slides and examples (noted above under examples)

Tools

When we streamline so many different models in a consistent language, there is an opportunity to build many tools to explore calculations and models. The environments linked above can be considered tools. “Reactive workings” (mentioned above) is a tool. Other noteworthy tools are:

calculationships (wip): very rough node-link diagrams to see the relationships in calculations. I used this to make fun, and illustrative, different, node-link diagrams. This tool takes a URL to a .cul.js file and does its work (this is a pattern that all tools should permit)
metal an environment I use to show people exactly what the compiler does (not working for URL references - TOFIX)

Tools is probably the most interesting way to contribute to calculang. We need tools much better than calculationships to understand/explore models at a high- and low-level - and to manipulate them.

Integrations - Python

I basically built an integration for Jupyter notebooks by using the awesome Anywidget. It isn’t a good pattern to publish, but I can provide it if requested.

Developer branch

calculang is under development, and I am usually using a different branch. Above: the version I use differs from place to place.

Code in the main branch of calculang is extremely old and in many places obselete.

Because the compiler now works in the browser, except in old examples you can trace versions used in the source (without considering node_modules/package.json).