NuML User Manual

First edition: model logic and dashboard configuration

Write complete NuWebKit system-dynamics simulations as text with NuML, the Numerus Modeling Language. A NuML program defines a model's equations, binds its parameters to sliders and switches, routes its output to graphs and tables, configures the integration method, and can set up sensitivity and repeated-stochastic studies — all without editing any JavaScript class.

NuML is a small extension of JavaScript expression syntax built around two infix operators:

@= (model logic): differential and difference equations, initial values, intermediate terms, input bindings, and output routing.
#= (configuration): dashboard components, integration and run control, and the analytical platforms.

NuML programs run in the DynSS family of apps — such as dynss2, dynsshs, dynsslvpp, and dynsspb1 — which pair a NuML editor with a configurable dashboard, shareable presets, and an AI portal that generates NuML from natural-language prompts. NuML can also be embedded directly in a project definition (Project.model), which reduces the app's Main class to boilerplate; see Where NuML runs.

Under the hood every NuML model compiles onto the SDMain/Stock runtime documented in the SD API User Manual. Agent-based and cellular-automata modeling is covered by the NL API User Manual. Each manual's page header links to the others.

Start here

SIR in NuML: your first NuML program. Type a complete epidemic model into a DynSS app: three deriv equations, slider bindings, a configured graph, and integration settings — then run and check it.

The tutorial includes the complete program and expected observations. Follow it first, or consult the task-oriented chapters below.

Programming guide

Chapter	What you will learn
Model logic with `@=`	Model variables (`deriv`, `next`, `initial`), terms, input bindings, `update` routing, `quitWhen`, primops, blocks and the iterator tool, and how NuML compiles onto stocks and flows
Dashboard configuration with `#=`	Directive statement forms, the DynSS component inventory, slider/switch/graph/table/cobweb directives, and integration and run control
Sensitivity and stochastic platforms	`SensPlatform` and `StocPlatform` configuration — the part of NuML not covered by the wiki reference — including `quitTime` histograms and multi-histogram setups
Where NuML runs	The DynSS editor, presets, and AI portal; NuML in `Project.model`; the `'numl'` header contract; and the boilerplate Main class

Worked models

The DynSS apps ship dozens of complete NuML presets; each app's preset file stores the program under the code property.

Modeling task	Preset	Where
Continuous SIR with sensitivity analysis	SIR	dynss2.json
Lorenz attractor (three coupled `deriv` equations)	Lorenz Attractor	dynss2.json
Discrete logistic sequence (`next`)	Logistic sequence	dynss2.json
Bifurcation diagram with the `iterator` tool	Logistic chaos bifurcation graph	dynss2.json
Stochastic SIR with binomial transitions and `StocPlatform`	Ex 20: Stochastic SIR model	dynsshs.json
Population viability with `quitWhen`, `quitTime` histogram	Ex 13 Population Viability with Harvesting	dynsshs.json
Predator-prey variants (Holling, Allee, competition)	several	dynsslvpp.json
NuML embedded in a project (`Project.model`)	Lorenz app	lorenzPrj.js

Quick lookup

Scope of the first edition

This edition documents the NuML language as implemented by the shipped runtime — the @= compiler in uberbuilder.js, the #= directive engine in directive.js, and the code normalizer in numlTransformer.js — and as exercised by the DynSS presets. It includes the sensitivity- and stochastic-platform configuration that the wiki reference does not cover.

The AI portal's prompt engineering, the hosting apps' RAM/preset file format, and the Studio/Designer authoring workflow are described only as far as a NuML author needs them; they are app features, not language features.

Verification and maintenance

Statements in this manual are sourced from the runtime files named above, from sdmain.js, and from the shipped DynSS and lorenz applications and their preset files. The guide tests execute the tutorial's NuML program and this manual's statement examples against the real compiler and runtime — including term memoization, deriv/next semantics, quitWhen, the normalizer's rewrites, and the lorenz Project.model path — and check the documented directive and primop vocabularies against the engine's own lists; see Publishing this guide for the verification commands.