Getting Started

This is the fastest path from zero to a working Grid model. It assumes no prior Grid knowledge — only that you've written a spreadsheet formula or two before.

By the end you will have:

• A .grid file you understand line by line.
• A mental model of how Grid evaluates it.
• A path for expanding it with arrays, external data, and rules.

For the complete language, read reference.md. For the one-page conceptual map, read README.md. For recipes by task, see cookbook.md. For the terms used throughout these docs, see concepts.md.

1. What Grid Is

Grid is a declarative, reactive language for live computational models. It starts with familiar spreadsheet ideas such as cells, formulas, ranges, and sheets, then composes them with semantic names, types, relational queries, rules, optimization, simulation, and domain computation.

You describe a computation as addressable bindings and formulas in a .grid file. A binding can be spatial (A1, Sheet1!B2) or semantic (Revenue, tax_rate). Grid builds the dependency structure and evaluates the affected work. When an input changes, only dependent calculations recompute.

concepts.md distinguishes a binding, its address, a coordinate cell, a named calculation, and an alias.

You do not pick an engine, manage recalculation order, or write imperative update code. You write formulas; Grid figures out the rest.

2. Your First Model

Create a file called pricing.grid:

MODEL "Pricing"
DESCRIPTION "Discounted price with tax."
VERSION "1.0.0"
AUTHOR "you@example.com"
TAGS "demo"
 
# Inputs
A1 is currency   = 100000     # list price
A2 is percentage = 7pct       # discount
A3 is percentage = 21pct      # tax rate
 
# Derivations
B1 is currency = A1 * (1 - A2)        # discounted price
B2 is currency = B1 * (1 + A3)        # gross price
 
# A readable summary
C1 = `net={B1} gross={B2}`
 
END MODEL

That is a complete, deployable model. Six lines of real computation.

3. Reading It Line By Line

The header. MODEL, DESCRIPTION, VERSION, AUTHOR, and TAGS are directives. They're all optional — the file parses without them — but every shared model includes them. The body ends at END MODEL.

Inputs. A1, A2, A3 are cells. A1 is currency = 100000 assigns the value 100000 and tags it as currency. The tag is semantic metadata: it drives formatting and validation and travels with the value, but A1 is still just the number 100000 in arithmetic.

7pct is a typed literal — it means 0.07. 21pct means 0.21. Grid has a rich literal vocabulary (25bps, 5min, 45deg, d"2026-04-10", 100USD, …); see reference.md.

Derivations. B1 and B2 are formulas. They reference other cells by name. When A1, A2, or A3 change, B1 and B2 recompute automatically — that is the whole point of the dependency graph.

The summary. C1 uses a backtick interpolated string: `net={B1} gross={B2}` substitutes the current values of B1 and B2 into the text.

Comments. # ... is a line comment. /* ... */ is a block comment.

4. The Five Things To Know

You can read reference.md for the full surface, but these six ideas cover almost everything:

1. A model contains addressable reactive bindings. Spatial names (A1, Sheet1!B2) and semantic names (Revenue) participate in the same dependency model.
2. Formulas express relationships. Grid tracks dependencies and recomputes only what changed. Cycles are reported as #CIRCULAR_REF! unless iterative calculation is enabled.
3. Space and meaning compose. Revenue = A1 adds a semantic address to the same binding; data = B1:B100 gives a region a reusable name.
4. = is eager, ~= is lazy. An eager binding recomputes when its inputs change. A lazy binding waits until something reads it — ideal for expensive or external work. See assignments.md.
5. Errors are values. #N/A, #DIV/0!, #VALUE!, and friends flow through formulas. Handle them with IFERROR, TRY, DEFAULT, or ?=. See errors.md.
6. Arrays spill. A formula returning an array writes into a rectangle of cells. Refer to the whole spilled block with A1#.

5. Adding A Little More

Here is the same model with branching, an array, and an external call. Each new idea links to its deep-dive doc.

MODEL "Pricing+"
DESCRIPTION "Discounted price, tier label, and an FX conversion."
VERSION "1.0.0"
AUTHOR "you@example.com"
TAGS "demo"
 
# Inputs
A1 is currency   = 100000
A2 is percentage = 7pct
A3 is percentage = 21pct
 
# Derivations
B1 is currency = A1 * (1 - A2)
B2 is currency = B1 * (1 + A3)
 
# Branching: a single condition reads well with THEN ... ELSE
C1 = B2 > 100000 THEN "large" ELSE "standard"
 
# Arrays and aggregation
D1 = [12000, 13500, 14200, 15000, 16800]   # monthly revenue
D2 is currency = SUM(D1)
D3 is currency = ROUND(AVERAGE(D1), 2)
 
# An external call, paired with a fallback so downstream stays computable
E1 is fx_rate  = FX_RATE("USD", "EUR") DEFAULT 0.92
E2 is currency = ROUND(B2 * E1, 2)
 
END MODEL

What's new:

• THEN ... ELSE is Grid's conditional expression. For many-armed branching use CASE WHEN or MATCH; see reference.md.
• Arrays ([...]) and aggregation functions (SUM, AVERAGE, ROUND) work as in any spreadsheet. The full catalog is in functions.md.
• FX_RATE(...) is an external function: it runs in a worker and writes its result back asynchronously. Always pair external calls with DEFAULT (or IFERROR) so dependents stay computable while the worker is in flight. See external-functions.md.

6. Reacting To Change: Rules

Cells recompute when inputs change. To make a model act — set a flag, stamp a time, increment a counter — use a rule block:

# React the instant load crosses the threshold
WHEN load > threshold BECOMES TRUE THEN
  alert  = "paged"
  paged_at = NOW()
END
 
# Preserve every upload and run no more than four webhook effects at once
WHEN upload_arrived CONCURRENT 4 LEDGER THEN
  HTTP_JSON(webhook_url, upload_arrived)
END
 
# Run on a schedule (a missed-run policy is required)
EVERY duration"PT15M" SKIP MISSED THEN
  heartbeat += 1
END

WHEN can react to a touch, a true predicate, a changed settled value, or a transition into a target value. EVERY runs on an interval or cron, and AT at a specific time. Rule action bodies use = and the compound operators (+=, -=, …) but not ~= or external functions. The full contract is in rules-and-schedules.md.

7. Use It In Grid

Paste the model into the source editor or create the same cells in the authoring surface. Grid validates the source, shows diagnostics for parse or type errors, and updates dependent values as you edit inputs.

When a model gets large, use performance.md for authoring patterns that keep recalculation predictable.

8. Worked Examples

The example library includes progressively richer models:

They are written in the canonical style-guide.md style and are safe to copy from.

9. Where To Go Next