Skip to main content

​
Overview

Constants and Lookup Tables are how you separate a model’s parameters from its logic. Instead of hardcoding values inside expressions, you name them, store them in one place, and reference them from anywhere. Change the named value once, and every expression that references it updates automatically. This matters for three reasons:
  1. Tuning: adjust model parameters without hunting through expressions. Change BASE_PROCESSING_TIME from 60 to 75 and every relevant component follows.
  2. Readability: SHIFT_EFFICIENCY_FACTOR is easier to understand than 0.87 sprinkled across expressions.
  3. Non-technical access: operators and analysts who shouldn’t modify expressions can still tune the model by changing constant values.
Both Constants and Lookup Tables are factory-scoped: they live at the factory level and can be reused across models. But each model has to opt in by listing the constant or lookup table slug in the top-level constants / lookup_tables arrays of its model.json. A constant that exists in the factory but isn’t in the model’s opt-in list is invisible to that model.
Referencing a constant or table that isn’t opted in fails validation. The expression checker resolves names against the model’s opt-in lists, so a LOOKUP against a table the factory has but the model hasn’t listed produces a validation error — that’s the symptom you’ll actually see when the opt-in step was skipped.

​
Constants

A Constant is a named value with a specific type: number, text, or boolean. Each constant has:
  • Name: how expressions reference it. Names use SCREAMING_SNAKE_CASE (e.g., BASE_CYCLE_TIME)
  • Description: what it represents and what units
  • Type: number, text, or boolean
  • Value: the actual data
The type is text, not string. The schema enum is ["boolean", "text", "number"]. Writing "type": "string" in a constant definition fails validation. The UI Type dropdown labels the option Text.
Names auto-uppercase as you type. The constant-name input transforms input client-side to SCREAMING_SNAKE_CASE: typing lowercase_name saves as LOWERCASE_NAME. Underscores you type are preserved; spaces are not added for you. Reference the name as it ends up after the transform.
Expressions reference the name, not the slug. The name must therefore be a valid DSL identifier, and it can’t collide with anything else the expression checker resolves by name: reserved DSL functions, entity type slugs, component ids, state variable names, or other constant and lookup table names. Name collisions fail validation with an error naming both ends of the conflict. Reference a constant by its name in any expression:

​
Constants vs. State Variables

Constants are static for the duration of a run: they cannot be reassigned. To mutate a value during simulation, use a State Variable instead. State variables expose a runtime assign action that constants don’t. The scope differs too: constants are factory-scoped and shared across every model that opts in, while state variables are model-scoped. A constant is the right tool for a parameter you tune between runs or share between models. A state variable is the right tool for a value the simulation itself changes: current shift, rolling WIP counter, demand signal.

​
When to Use a Constant

  • Any value that appears in multiple places. If you find yourself typing 0.87 in several expressions, extract it to a constant.
  • Any value you might want to change between runs. Edit the constant, capture a new Snapshot, and the snapshot freezes that value for downstream comparison.
  • Any value a non-technical stakeholder might need to adjust. Analysts can tune a constant without knowing the expression language.
Experiments don’t auto-sweep constants. An Experiment compares Snapshots, not parameter values directly. To sweep a constant across an experiment, change its value, capture a snapshot, change it again, capture another snapshot, then add both snapshots to the experiment.

​
Managing Constants

Constants live in the Lookups modal in the Modeler’s Library panel: click the Lookups button at the bottom of the Library and open the Constants tab. The same modal also hosts Lookup Tables, State Variables, and Topics, each on its own tab. Add, edit, or delete constants there, and changes propagate to every model in the factory that has the constant in its opt-in list. Each constant is stored at factory/constants/{slug}.json.

​
Lookup Tables

A Lookup Table is a named, typed-key table queryable in expressions. Each table has a value type (number, text, or boolean) and one or more keys (called “Attributes” in the UI — these are the table’s key columns, unrelated to entity attributes). Keys are themselves typed (each can be boolean, text, or number), so a multi-dimensional lookup can mix key types. Query a table with LOOKUP:

​
Providing a Fallback Value

LOOKUP accepts an optional default:= keyword argument that returns the supplied value when no row matches:
This is the canonical way to give a lookup a fallback. Always prefer default:= over wrapping in IF(): it’s a single expression with no double-evaluation of the same lookup.
Without default:=, missing rows return type-specific zero: 0 for a numeric table, "" (empty string) for a text table, FALSE for a boolean table. That zero is silent and easily mistaken for a real result. Use default:= whenever the difference between “no row matched” and “value is exactly zero” matters.
The keyword-argument syntax uses :=, not = (which means equality in the DSL). Despite the visual resemblance to Python’s walrus operator, := here is simply a named-argument marker, not an assignment. The same := marks the filter:= and type:= keyword args on aggregation functions and ndigits:= on ROUND.

​
Multi-Dimensional Lookups

A Lookup Table can be configured with more than one key column, so a single table can capture data that varies across two or more axes at once, like “processing time by (product type, station)” or “yield rate by (shift, material class).” Query it with one positional argument per key column, in the order the table defines them:
Each key column has its own type and a required possible_keys allowlist — the enumerated set of values that column accepts. possible_keys is load-bearing, not decoration: the platform validates every table entry against it at build time, and the UI’s key dropdowns are populated from it. Design a lookup table by enumerating each key’s domain up front. Multi-key LOOKUP calls match rows where all key columns equal the values you pass in. One argument per key column. There’s no wildcard or partial-match syntax: always pass exactly as many keys as the table defines. Composite keys via CONCAT. When a natural key is a compound string, build it in the expression rather than adding a column per fragment:

​
Managing Lookup Tables

Lookup Tables are managed in the same Lookups modal as Constants: open it from the Library panel and switch to the Lookup Tables tab. Each table is stored at factory/lookup_tables/{slug}.json with:
  • type — the value type (number, text, or boolean)
  • key_definitions — the typed key columns (the UI labels these Attributes), each carrying a name, a type, and its possible_keys allowlist
  • entries — the rows, each {"keys": [...], "value": ...} with one key per column in definition order
  • dimension — the key-column count, derived from key_definitions
Entries are validated when the table is built: a keys array that doesn’t match the column count, a key outside its column’s possible_keys, or a value that doesn’t match the declared type is rejected before the table is accepted — you won’t discover a malformed row at simulation time.

​
When to Use a Lookup Table

  • Values that vary by a categorical attribute. Processing time by product type, yield rate by material, priority weight by customer tier, all natural lookups.
  • Routing and proportional splits. Different entities route differently; store the routing rules in a table rather than deeply nested IF expressions.
  • Data-driven configuration. When the “configuration” of a model is really a set of numbers tied to categories, a lookup table is clearer than encoding the same information across many fields.

​
Constants vs. Lookup Tables: Which to Use?

  • Single value used in many places → Constant
  • Value that depends on a categorical attribute → Lookup Table
  • Needs to be swept across snapshots in an experiment → Constant (one value per snapshot)
  • Large reference dataset → Lookup Table
It’s common to use both: a constant for a global factor, a lookup for per-type rates, combined in one expression.

​
Patterns

Processing time by product:
Conditional cost or surcharge with safe fallback:
Tunable shift dynamics:

​
Tips

  • DSL arithmetic is type-strict. Numbers add to numbers; text doesn’t quietly coerce. Catch type mismatches at validation rather than relying on silent conversions.
  • The value type must match the context that reads it. A boolean constant in a numeric expression, or a text lookup value feeding a numeric slot, fails validation with a type error — a common trip point after refactoring a table from number to text values.
  • Use default:= defensively. If a missing lookup row should be anything other than the type’s zero, default:= is shorter and clearer than an IF() wrapper around two LOOKUP calls.
  • Each model opts in. Adding a constant or lookup at the factory level is the first step. The model’s top-level constants / lookup_tables arrays decide whether that model sees it.