On this page
SD API User Manual
First edition: stocks, flows, and SDMain
Build, understand, and extend NuWebKit system-dynamics simulations with JavaScript. This guide is written for model authors familiar with classic SD ideas: stocks, flows, auxiliaries, feedback loops, and numerical integration, as found in tools such as STELLA, Vensim, and Numerus. Basic JavaScript helps; the two-phase Store discipline, the clock cycle, and the runtime protocol are introduced where needed.
A NuWebKit SD model is a JavaScript class that extends SDMain. Stocks are
Stock objects; each flow is a JavaScript function attached to a stock; the
runtime clock integrates the resulting system with Euler or RK4 and streams
results to charts. This manual relates each of those code constructs back to
the stock-and-flow diagram it implements.
Agent-based and cellular-automata modeling (NLSimMain, patches, turtles) is
covered by the separate NL API User Manual. Each manual's
page header links to the other.
Start here
- SDSir: your first stock-and-flow model. Write a Project and a Main class for the classic SIR epidemic, connect three stocks with flows, run it, and check conservation and the epidemic threshold.
The tutorial includes a complete model definition and expected observations. Follow it first, or consult the task-oriented chapters below.
Programming guide
| Chapter | What you will learn |
|---|---|
| Stocks, flows, and integration | How SD diagram elements map to code, the simulation cycle, two-phase commitment, dt, Euler versus RK4, auxiliaries, and discrete/stochastic variants |
API reference
| Reference | Contents |
|---|---|
| SDMain | Lifecycle hooks, the run loop, time and stopping, parameters, displays and logging, stock registration, and inherited utilities |
| Stock and Store | Two-phase values, creating stocks, flow functions, initialization and reset, Euler/RK4 commitment, and sequence stocks |
Internal and runtime-protocol members are classified rather than endorsed. Inventory coverage is not a promise that every helper accepts arbitrary input.
Worked models
| Modeling task | Worked material | Shipped source |
|---|---|---|
| Compartment model with three stocks and two flow processes | SDSir tutorial | sdsir.js |
| Coupled nonlinear system with auxiliaries, RK4, and a phase plot | Lotka-Volterra walk-through | lotka.js |
Discrete-time stochastic compartment model with Store and coordinate |
Stochastic SIR pattern | StocSir.html |
Scope of the first edition
The first edition covers the stock-and-flow modeling path: the SDMain
base class, Stock and Store, flow functions, the clock's Euler and RK4
integration cycles, Project inputs and displays as they appear in shipped SD
apps, and the discrete/stochastic coordinate pattern.
NuML — the modeling-language notation accepted by input parameters and
compiled by the runtime — now has its own
NuML User Manual; this manual notes where NuML
values enter the SDMain API and defers the notation to that guide.
Sensitivity (api.sens) and repeated stochastic runs (api.stoc) appear in
shipped projects and the Studio model library; they are configuration of the
hosting pages, not members of SDMain, and their NuML-driven configuration
is covered by the NuML manual's
platforms chapter.
Patch and agent modeling is outside this manual's scope; see the NL API User Manual.
Verification and maintenance
Statements in this manual are sourced from the runtime files sdmain.js, stock.js, store.js, clock.js, and integrator.js, and from the shipped applications named above. The guide tests execute the tutorial and reference models from this manual's Markdown, verify the documented commitment, reset, integration, and stopping contracts, and check the reference pages' member inventories; see Publishing this guide for the verification commands.