NLSimMain API reference

Manual contents | Programming Main | Project settings | Neighborhood reference | Supporting types | Alphabetical index

Source: nlsimmain.js. Inheritance: NLSimMain extends NLRoot extends APIRoot. Use this page to look up a contract; use Programming Main for a guided explanation and complete worked example.

Scope: the instance members declared by NLSimMain, its model-facing runtime fields, and the supporting exports in its module. Inherited helpers are mapped to existing guides below, not silently counted as declarations here. Examples assume Project.lifecycle: "aligned". Legacy-only entry points are classified rather than recommended. No method on this page is static.

1. Import, subclass, and availability

import {NLSimMain} from "@nwk/api/nlsimmain.js";

class Model extends NLSimMain {
  constructor(Patch, Turtle) {
    super();
    this.Patch = Patch;
    this.Turtle = Turtle;
  }

  initCells() {
    this.initializePatches(this.Patch);
  }

  initAgents() {
    this.initializeTurtles(this.Turtle);
  }
}

export default Model;

The runtime supplies the classes; their names here are local choices. This scaffold requires an agent Project and compatible supplied classes. For a patch-only Project omit initAgents and the Turtle field. Constructor execution is too early to read inputs, patches, or turtles.

The tables distinguish:

• Hook: override it; the runtime calls it at the right phase.
• Operation: call it from an appropriate hook/model action.
• Advanced: requires an explicit scheduling/ownership policy.
• Internal/legacy: do not call it as a model-author shortcut.

Unless stated otherwise, operations mutate state and return undefined. They do not validate arbitrary model input or invent missing configuration.

2. Lifecycle hooks and world operations

Main and patches survive ordinary aligned world reset; turtles are replaced. Synchronizing a custom Store does not arrange its reinitialization: restore it explicitly in its owner's reset. The aligned Main reset does not delegate to NLRoot reset to restore stores automatically. See state ownership and Reset versus reinitialization.

Population initialization

Customization does not copy arbitrary custom state or make the whole population available before it has been built. See initial customization.

3. Read the world and parameters

Treat these fields as runtime-owned unless your own model deliberately manages one of them. They are not constructor inputs.

Parameter access

For example, these methods belong inside Main:

get RATE() { return this.getParam("RATE"); }
get ENABLED() { return this.getBParam("ENABLED"); }

Declare matching Project inputs; Patch/Turtle can then read this.main.RATE. setParam affects the runtime parameter store, not necessarily the browser slider display. See input policies.

Whole-population built-in assignments

setSpeed(val) and setTheta(val) visit the current turtle population and assign turtle.speed / turtle.theta respectively. They require a configured population and return undefined. Values are distance per trajectory step and radians respectively. These are immediate initializing setters, replacing each turtle's local reset baseline; they are not next-state proposals. They do not update a Project default or guarantee values for later births. Default input bindings use these operations. See binding/reset caveats.

4. Lookup, neighborhoods, and collections

Query results do not execute rules or commit pending state. Membership can change after movement, death, birth, or reset; do not retain turtle references as permanent identities.

Radii accept fractions but must be finite numbers with 0 <= inner <= outer; invalid radii throw RangeError and malformed center coordinates throw TypeError. Distances use patch coordinate points, not pixels or square display centers; wrapping uses shortest cell-boundary displacement. Hex uses scaled physical spacing. Full contracts and examples: neighborhood reference.

Scan or summarize without stepping

turtleVisit(visitor) calls visitor(turtle) on every current population member, returning undefined. It does not apply the local-query visibility filter, shuffle order, run turtleStep, or clone turtles. A configured population is required. Avoid structural changes during traversal; use the queued birth/death helpers.

total(f, elts, base) has two forms:

Actual code uses base || 0; supply a finite numeric base and numeric results. elts must support map then reduce (ordinary arrays work; Sets/iterators do not). Empty arrays return the base, normally zero. No mutation or reset work.

This update body requires matching display codes:

const red = [...this.turtles.values()].filter(turtle => turtle.color === 1);
this.show("RED", red.length);
this.show("SUM", this.total(patch => patch.color, this.patches.toList()));

askTurtles(breed, fn) and filterBreed(breed, elts) are advanced legacy breed wrappers using breedMap. They are not a recommended breed API: askTurtles passes a class through a filter path that can call it as a predicate, and filterBreed needs both a registered class and a supported collection shape. They are not NetLogo breed declarations. Prefer explicit array filtering with turtle instanceof MyTurtle, followed by forEach if appropriate.

5. Patch activation and scheduler controls

Choose one activation policy for a simple environment; see Programming patches.

Persistent and transient step passes are separate; being in both can mean two calls. Transient sites and seen clear at shift. Adding entries during Set traversal can affect that traversal rather than waiting one tick. Slash modes insert an intermediate full shift and therefore complicate activation, births, and removals. Do not equate step order with selection. Callback exceptions propagate; these operations do not catch rule failures.

Clearing colors is not resetting a model

clearCells(where) has two importantly different paths:

• With a truthy where collection, uses patchVisit to propose nextColor 0 on selected patches; color commits later and reset baselines are retained.
• Without where, initializes every patch color to 0 immediately, replacing color reset baselines. Custom patch state is untouched.

Returns undefined. An empty Set is a supplied collection; visitAll can still override it. Prefer explicit per-patch nextColor writes when a synchronous rule should clear only selected colors.

6. Synchronize custom Stores

Allocate each Store once; call registration once in its owner's init.

Registration returns undefined. It replaces each Store's nextPinger; multiple registration helpers do not automatically compose. No initial pending value is committed just by registration. Assign next afterward, or initialize deliberately. Stores are kept in a Set for commitment, so repeated proposals normally commit only the final pending value at that boundary.

The three combined helpers also assign a capitalized InitializePinger field which Store does not invoke. However, Store.initialize/reinitialize assign next, so they do invoke the installed nextPinger and can report/activate the owner through that path. Do not rely on the unused capitalized branch as a separate initialization notification. Use explicit setup/activation for a clear policy. None of these methods allocates state, installs an updater, chooses a reset policy, or retires discarded turtle resources.

For a custom Store this pattern keeps those jobs explicit:

import {Store} from "@nwk/api/store.js";
import {NLSimMain} from "@nwk/api/nlsimmain.js";

class Counter extends NLSimMain {
  constructor(Patch) {
    super();
    this.Patch = Patch;
    this.counter = new Store(0);
  }
  init() {
    super.init();
    this.synchronize(this.counter);
  }
  initCells() { this.initializePatches(this.Patch); }
  coordinate() { this.counter.next = this.counter.get() + 1; }
  reset() {
    super.reset();
    this.counter.reinitialize();
  }
}

export default Counter;

Use an aligned patch-only Project. No manual Store shift or init/setup call is needed. See Store semantics.

7. Queue births and removals

These require an initialized agent population, even if its initial size is zero. Birth calls construct/init immediately, return the child, and enqueue insertion. They do not increase turtles.size at the call site.

Use arrow callbacks when lexical this is intended; arrows ignore apply-based binding. Built-in initialization precedes child init, customization follows, then shift assigns a population ID, inserts/indexes the batch, and invokes setup. Custom fields are not automatically copied. Callback errors are not rolled back: the lower-level creation has already queued the child. Local-query visibility and opportunity to step have distinct boundaries. See birth/death timing before writing a repeated population rule.

8. Publish outputs and logs

Codes must match configured destinations. Numerical results are queued until status publication; calls do not draw synchronously in the browser.

These example calls require matching Project line/text displays:

this.show("HALVES", 7, 5);
this.showList("COPY", [7, 5]);
this.log("EVENTS", "First observation", "Second observation");

The first two produce equivalent two-value payload shapes. Passing the array as one show argument would instead nest it. See display configuration and Main chart recipes.

Logger is a supporting class in this module, not a separate public export. Its code and main fields store the destination and owner. scrollToTop queues a text-display scroll marker; it is not immediate browser scrolling.

9. Stop and control execution

Do not invoke step/shift/tick recursively from an individual rule, or start a second timer. Ordinary Step is orchestrated by the clock through the dispatcher. See stopping.

10. Runtime/legacy inventory

The remaining declared methods are listed so finding a name in source does not imply that it is a safe modeling operation.

Runtime-owned bookkeeping fields include:

• Input/output plumbing: icodes, params, dcodes, paramManager, displayManager, cws, initials, RK4.
• Queues/indexing: touchedStores, sites, seen, flip, births, deaths, hss, agentGrid, nextId, visitAlwaysPatches.
• Scheduling: clock, stepModes, shiftModes, stepMode, shiftMode, _patchShift, _turtleShift, _visitAll, _stopWhenTrue, _lifecycleComplete, _memoEpoch.
• Construction/support: coordsFactory, cellSets, patchGen, turtleInit, dTurtleGen, sTurtleGen, defCoords, breedMap, stocks, diffuseDelta. Legacy optional inputs include turtleClasses and countCode.

Do not replace these collections, manually edit pending queues, or call internal initializers to work around lifecycle problems. The runtime cannot infer cleanup of arbitrary custom listeners/Stocks when their owner disappears.

11. Supporting exports and inherited helpers

The same module exports:

For example:

import {Dir, Shape, VisitMode} from "@nwk/api/nlsimmain.js";

const eastHeading = Dir.E.theta;
const circle = Shape.Circle;
const patchOnly = VisitMode.C;

Inherited instance helpers include newCoords/path, filtering/mapping, selection/extrema, and aggregation. Inherited static utilities include random/math functions and NLRoot sampling/statistics. Static inheritance does not make this.random() valid: call NLRoot.random() or another appropriate class import. See NLRoot reference, tools and utilities, and NLRoot source. This page does not certify every legacy inherited helper or collection shape.

12. Verification

The guide tests check every current NLSimMain prototype member is mentioned here, execute this page's Counter, parameter/output fragments and supporting imports, and test the documented query/activation/clearing/Store/population distinctions. Existing guide checks exercise Main initialization, customization, live parameters, repeated reset, birth/death timing, radius/neighborhood contracts, and chart payload shapes.

Inventory coverage is not proof of every behavior: internal/legacy entries are source-classified, not recommended or exhaustively runtime-certified. No browser layout, all-mode integration, or arbitrary listener cleanup is implied by these headless checks.