Designer Component Guide

Introduction

This guide documents the Component set distributed with Numerus Designer. Numerus Designer models are constructed out of Components, which are visual tokens that are placed on the Design Canvas.

To Place a Component on the Designer Canvas

• Press the left mouse button on the desired Component in the Component Palette.
• Drag the component from the component menu onto the Design Canvas.
• A default name will be provided; Alt-click on the name to change it (or change it in the Property Pane).
• The new component must be programmed; this may require the programming of squibs. See Programming References for a discussion of squib programming.

Referencing Components in Squibs

Many Components yield values that can be used (along with primops) to perform the required computations in squibs. Within a given Capsule, each value-yielding component can be referenced by its name. Referencing Components in other Capsules is different and will be discussed elsewhere.

In this document, the sections labeled Squib Reference describe the format used to access values from each Component type. In these sections the notation <name> refers to the Component's name.

Volatility

For the sake of efficiency, Designer simulations use a process called memoizing: when a squib is evaluated (or invoked on a given set of arguments) during a simulation cycle, its value is cached and the cached value is returned, rather then re-evaluating the squib, on subsequent calls during the cycle. This may not always be suitable (for example when a squib is generating a series of random numbers). Checking the Volatile box when it appears causes the squib to be evaluated each time it is called.

Basic Components

Command

A Command contains code that is executed once per time step. Commands do not return values; rather they operate by altering simulation state, often through the execution of some primitive operator. One common use for a Command is during program development, where the Console.log primop is used to print useful values to the console. Another important role is in the agent life cycle, where Commands may contain code used to create or terminate agents, or move them in their environment.

Property Pane

Contains a single Command squib.

Observer

If checked, this Command is not executed during the normal Simulation cycle, but rather intentionally from a remote Observer, such as an Agent Vector Component, or from some other Component.

Volatile

Normally Components are executed only once per cycle. If Volatile is checked, it enables multiple executions.

Squib Reference

Generally not used since Commands execute automatically. To invoke a Command from a squib use the following format:

<name>()

Constant

A Constant contains a Supplier squib that is executed once when the simulation is reset. The value is retained for the life of the simulation.

Property Pane

Contains a single Supplier squib. Return type is required.

Squib Reference

To retrieve a Constant use the following format:

<name>()

Function

A Function contains a Function squib that is executed only when the function defined by the squib is invoked on a set of arguments. Function squibs are defined here.

Property Pane

Contains a single Function squib. Return type is required.

Volatile

Described here.

Squib Reference

To invoke a Function use the following format:

<name>(arg₁, arg₂, ... arg_n)

where the args match the formal parameters in number and type.

Parameter

Constant Parameter

Slider Parameter

A Parameter is a numerical value (Double or Integer) provided either as a constant or specified with a Slider.

Property Pane

The constant Parameter value is entered into a text field. Integer or Double value type must be selected.

Checking the User Slider box changes the green Parameter icon to a slider. The slider is configured here by specifying minimum and maximum extents of the slider range, and by specifying a step value. The step value is only used when the slider knob is clicked and the slider is moved up and down using arrow keys.

The tooltip is only used by Numerus Studio.

Squib Reference

To retrieve a Parameter use the following format:

<name>()

Store

A Store is like a global variable in a programming language. It is initialized when the simulation is reset. Its value persists over the course of the simulation cycles unless changed using the update method.

Property Pane

The Store has single Supplier squib property specifying its initial value.

Squib Reference

To retrieve a Store value use the following format:

<name>()

To assign a new value use the following format:

<name>.update(arg)

The type of arg must be compatible with the type of the Store.

Term

A Term is function of no arguments, defined by a Supplier squib.

Property Pane

The Term has single Supplier squib property specifying its value.

Volatile

Described here.

Squib Reference

To retrieve a Term value use the following format:

<name>()

System Dynamics

The two system dynamics components are initialized to specified values and update their contents on each cycle.

Sequence

A Sequence is determined by an initial value and an update computation executed on each cycle. Sequence type is not restricted.

Property Pane

The Sequence has two Supplier squib properties. Initial Value determines its initial value when the simulation is reset. Next Value computes the value to be used in the next cycle. Both must return values compatible with the specified type.

Record Full History

Sequences keep a history only of the previous 100 state values unless this box is checked.

Squib Reference

To retrieve the current Sequence value use the following format:

<name>()

Stock

A Stock is similarly determined by an initial value and a flow computation executed on each cycle. The flow value is treated differently, however. Stocks are used to model continuous functions in which the flow acts as a derivative; consequently their update behavior is dictated by the choice of integration method. Stock types are restricted to Numerical types (Number, Double, Integer, etc.)

Property Pane

The Stock has two Supplier squib properties. Initial Value determines its initial value when the simulation is reset. Flow Value computes the value used by numerical integration to determine the next Stock value. Both must return values compatible with the specified type.

Non-Negative

Negative computed values are stored as 0.

Record Full History

Stocks keep a history only of the previous 100 state values unless this box is checked.

Squib Reference

To retrieve the current Stock value use the following format:

<name>()