SDMain API reference

Manual contents | SDSir tutorial | Stocks, flows, and integration | Stock and Store reference

Source: sdmain.js. Inheritance: SDMain extends SDRoot extends APIRoot. Use this page to look up a contract; use the concepts chapter for a guided explanation and the tutorial for a complete worked model.

Scope: the instance members declared by SDMain, its model-facing runtime fields, and the inherited helpers a model author actually uses. Members that exist to serve the hosting page's message protocol are classified as runtime rather than recommended. NuML parameter values are noted where they enter the API; the notation itself is documented in the NuML User Manual.

1. Import, subclass, and availability

import {SDMain} from "@nwk/api/sdmain.js";
import {Stock} from "@nwk/api/stock.js";

class Model extends SDMain {
  constructor() {super();}

  init() {
    super.init();
    this.x = Stock.create(this.X0, this);
    this.x.flow = () => -this.K * this.x.get();
    this.setup();
  }

  setup() {
    super.setup();
    this.show("OUT", this.x.get());
  }

  update() {
    super.update();
    this.show("OUT", this.x.get());
  }

  get K()  {return this.getParam("K");}
  get X0() {return this.getParam("X0");}
}

export {Model}

The constructor wires the runtime pieces: a Clock, the stocks set, a ParamManager, and a DisplayManager. dt defaults to 1.0 until the Project's value is installed. Always call super() and, in every hook you override, the corresponding super.hook().

2. The Studio template regions

Studio generates SD Main files with numbered marker comments delimiting the regions it round-trips. The shipped apps keep them:

Below the regions, Studio emits one parameter getter per Project input. If you edit a generated file by hand, keep your code inside the marked regions so a round trip through Studio preserves it.

3. Lifecycle hooks

Exact tick ordering, including the RK4 variant, is specified in the simulation cycle.

initialize(msg, delay, ws) is the runtime entry point, invoked by the dispatcher when the hosting page sends initSD: it installs parameters, display codes, dt, maxTime, and the RK4 flag, then calls your init(). Models override init(), not initialize.

4. Time, execution, and stopping

Batch mode. With Project batch: true (or the UI's batch toggle) the clock runs bursts of 250 ticks back-to-back instead of waiting delay between ticks — the mode the Lotka app ships with. The clock also guards against runaway models: if simulation time becomes non-finite or stops advancing for 250 consecutive ticks, it reports a runtime error and halts.

5. Parameters

A parameter whose string value begins with "numl" is parsed at installation into a compiled form ({code, ast}) rather than used as a plain value; parse errors are reported to the host as Numl Error(s). Authoring NuML programs is the subject of the NuML User Manual.

6. Displays and logging

Display codes come from the Project's displays; the DisplayManager buffers whatever you show and the runtime drains the buffer into the hosting page after every tick (and at launch, for anything shown during initialization).

Call show from setup() for the initial point and from update() for the per-tick points, as in the tutorial. A show issued between ticks (for example from a flow) violates the purity contract and may be sampled multiple times under RK4.

7. Stocks and synchronized stores

The two-phase semantics of the stores themselves — get, next, shift, initial values — are specified in the Stock and Store reference.

8. Inherited utilities

From SDRoot: the stores set (plain Store.create registers here so Reset can reinitialize them) and the base reset() behavior.

From APIRoot, the static utilities — call them as APIRoot.name(...) (import APIRoot from @nwk/api/apiroot.js), not as methods on this:

These are shared with the agent-based runtime and are documented in more depth in the NL manual's NLRoot and APIRoot utilities chapter. Draws use the runtime's random sources; reproducible seeding is not part of this API.

9. Runtime protocol and internal inventory

These members exist so the hosting page can drive the model. They are listed so the inventory is complete, not because models should call them.

For reference, the dispatcher messages that drive these members: initSD (launch), step, toggle (Run/Stop, batch flag), reset, params (widget change), simspeed, and history. See simdispatcher.js.

10. Verification

Contracts on this page are read directly from sdmain.js, clock.js, and simdispatcher.js at the time of writing, and cross-checked against the shipped sdsir and lotka applications. The guide tests execute this page's subclass example, verify the lifecycle, stopping, and display contracts, and check that this page inventories every declared member; see Publishing this guide for the verification commands.