Language Reference¶

This section provides formal documentation of all Graphcal language features.

Overview¶

Graphcal is a domain-specific language for engineering calculations built around a directed acyclic graph (DAG) of computations. Every .gcl file describes parameters (inputs), nodes (computed values), and constants, connected by explicit references.

The language has a layered type system:

Layer	Feature	Purpose
1	Primitives	Primitive value types (canonical inventory)
2	Dimensions	Physical dimension algebra (compile-time types)
3	Units	Value-level scaling factors attached to dimensions
4	Algebraic Data Types	Constructors, payloads, and pattern matching
5	Indexes	Finite label sets for collections
6	DAG Blocks	Reusable computation via `dag` blocks and `include`

Reference Pages¶

Computation Model

DAG semantics, param/node/const node, the @-sigil.

Computation model
Type System

The full entity stratification, canonical primitive inventory, and explicit conversions.

Type system
Dimensions & Units

Dimension algebra, unit definitions, conversion, prelude.

Dimensions & units
Algebraic Data Types

One- and multi-constructor types, match expressions, and generics.

ADTs
Indexes

Named, coordinate, and Fin(N) indexes; for, scan, and unfold.

Indexes
DAG Blocks

Reusable computation via dag blocks and include.

DAG Blocks
Extern Functions (Plugins)

import plugin blocks: externally-provided functions with declared dimensional signatures.

Extern functions
Expressions

Operators, precedence, if/else, literals.

Expressions
Multi-File Projects

import declarations, package dependencies, aliasing, circular detection.

Multi-file
Assertions & Attributes

assert declarations, tolerance checks, #[assumes(...)].

Assertions
Plots

plot declarations, chart types, interactive visualization.

Plots
Built-in Reference

Prelude dimensions, units, constants, and functions.

Built-ins