Graphcal

A type-safe, unit-aware, Git-friendly reactive programming language for engineering calculations.

Graphcal is for engineers who want more confidence than spreadsheets and ad-hoc scripts provide. Write plain-text calculation graphs, let the compiler check types and physical dimensions, and see dependent values update when inputs change.

The language server shows computed values inline, turning a text file into a live engineering worksheet.

See it in action

This example calculates rocket delta-v. Velocity and Acceleration are prelude dimensions.

param dry_mass: Mass = 1200.0 kg;
param fuel_mass: Mass = 2800.0 kg;
param isp: Time = 320.0 s;
const node g0: Acceleration = 9.80665 m/s^2;

node v_exhaust: Velocity = @isp * @g0;
node mass_ratio: Dimensionless = (@dry_mass + @fuel_mass) / @dry_mass;
node delta_v: Velocity = @v_exhaust * ln(@mass_ratio);

graphcal eval rocket.gcl
# delta_v = 3778.220768 m/s

Try the example in the browser playground without installing anything.

Why Graphcal?

• Type- and unit-safe: dimensional mistakes such as km + kg are rejected at compile time.
• Reactive: changing a parameter recomputes its dependents.
• Git-friendly: .gcl files are plain text and diff cleanly.
• Engineering-focused: build reusable computation graphs with dimensions, units, assertions, and visualization.
• Editor-friendly: the LSP provides diagnostics, references, rename, and inline computed values.
• Sandboxed extensibility: call pinned pure WebAssembly kernels.

Quickstart

Install the CLI with Rust:

cargo install graphcal --version '^0.0.1-alpha' --locked

Save the example above as rocket.gcl, then run:

graphcal eval rocket.gcl
# Try a different input:
graphcal eval rocket.gcl --param 'isp=450.0 s'
# Or bind several params from inline JSON:
graphcal eval rocket.gcl --params-json '{"dry_mass":"1500.0 kg","isp":"450.0 s"}'
# Build a shareable, self-contained HTML report (experimental; drop --static
# for an interactive page once you build the wasm engine, see the CLI reference):
graphcal report build rocket.gcl --static

For the full CLI, see the CLI reference. For a guided introduction, start with the tutorial.

Editor support

• VS Code: install the Graphcal extension.
• Zed: use the Zed extension as a development extension.
• Neovim / Helix: use the tree-sitter grammar with graphcal lsp.

See the editor setup guide for details.

Explore further

• Language reference
• Tenax integration
• Documentation home

Design influences

• Numbat — dimensions as types, units as values
• Gleam — unified type declarations
• marimo — reactive graphs in plain-text files
• Sguaba — typed coordinate frames

License

Licensed under either the MIT License or Apache License, Version 2.0, at your option.