Quick Programming References

Designer Architecture

Numerus Designer is a platform for building and running simulations. A simulation requires a set of state values and a clock that iterates through a sequence of time units. The simulation uses the current state at a given point in time to determine the next state. In Designer, the state is factored across a set of interacting Components managed by a container called a Capsule.

Capsules

• The fundamental structural unit for Designer is the Capsule.
• A Capsule is comprised of a set of interacting elements called Components.
• Each Capsule actually acts as a class, or blueprint for creating one or more instances of its Component set. This is true except for the top-level Capsule, for which there is only a single instance.
• When starting a new project, you are provided with an empty canvas on which to design the top-level Capsule. Many models only require a top-level Capsule. Additional Capsules are used to implement Cells and Agents in cellular and/or agent-based models. Capsules are also used to define new Components for use in other Capsules.

Components

• Components compute useful functions or serve as containers for Agents or Cells.
• Components are either stateful or stateless. Stateful Components manage some part of the state. State values determined by these components are carried from the current time step to the next. Stateless Components compute values from the current state of the simulation that are used to determine the next values for stateful Components, but these values are not retained across the transition from one time unit to the next.
• Most Components need to be programmed; i.e., provided with values or code that determine their behavior. Within that code may be references to the current values of other Components. The simplest Component programming calls for one or more constant values, however for most Components a code segment using the Java language is required.
• User-defined code segments are called squibs. Each squib either computes and returns a value, or performs a state change. The bulk of Designer programming is in writing squibs.

Overview

Platform

Design Canvas

Site of model construction.

Capsule Selection List

Choose Capsule for display on the Design Canvas.

Component Palette

Drag Components from here onto the Design Canvas.

Model Components

Components selected for inclusion in the current Canvas

Property Pane

Appears for selected Component; facilitates Component property definitions.

Property Entry

Simple property values entered into text fields or selected with Checkboxes or Radio Buttons.

Important: when entering simple numerical or textual values into a text field be sure to press return when completing the entry; otherwise the entry may not register with the system.

Squib Text Areas

Text areas containing Squib definitions.

Build Reporter

Console used to report the result of a build.

Javascript Console

Interactive command processor that can retrieve Component values; useful for debugging.

Command Bar

Current Model Time

Shows elapsed time as simulation progresses

Current Capsule

Shows the name of the Capsule being edited.

Studio Launch

Launches the current model into Numerus Studio for further development. (Note: the red script "R" appearing in property panes indicates data used to specify properties important to Numerus Studio.)

RNG Seed and Reset Mode

Including a seed value resets the random number generator to produce the same sequence of random numbers. A reset is indicated by a flash of yellow in the text field. This reset occurs by default with a double click on the Reset Button. Checking Restart RNG on Reset causes an RNG reset each time the simulation resets.

Integration Mode

Indicates the integration method used by Stocks. Choices include RK (Runge-Kutta) 4, Euler and Discrete (Euler with a DT value of 1).

DT

Model time interval between iterations of the simulation.

Model Run Speed

Adjusts the running speed. Has no effect on model time.

Model Operation Buttons

Reset, Stop and Run control the execution of the simulation. Pressing Run after Stop continues the simulation from the current model time.

Remaining Model Time

This text field is initialized for the length of the run, and decreases as the run continues. When a run is completed, pressing Run will initiate a new run for the same length of time.

Programming Squibs

Introduction

By far the most extensive programming required to specify a model is providing content to various squibs required by different Components. Simple components (e.g., Stocks, Sequences, Terms, Parameters, etc.) generally have one or two squibs, while more complex components (e.g., Cellular, Movable Agent, Classified Agent, Sim, etc.) require numerous squibs to detail their behavior. In this section we provide general information about writing squib code that applies to squibs throughout the Component set. (Some familiarity with writing Java code is expected.)

Java data consists of base types (int, float, etc.) and object types. Objects use fields to hold state data and define methods, which are code segments, to manipulate their own data and that of other objects.

Designer provides a rich set of Primitive Operators or primops to facilitate computation and define Component state. A complete list of primops appears here.

Java is statically typed language and so proper typing rules must be adhered to. Designer uses only familiar base types (integers, reals, strings) and their arrays, plus a few simple internally-defined types to specify coordinates. The types used in Designer are as follows:

Byte, Short, Integer, Long

Respectively 1, 2, 4 and 8 byte integer values.

Float, Double

32 and 64 bit floating point (i.e., real) values

Boolean

The values true and false

Char, String

Character and String types.

Void

The constant null, representing the empty value for any object.

By far, the most common types used are Integer, Double and String.

Squib Types

Squib code resembles some or part of a method definition, depending on the squib type. Components use 4 different squib types, depending on what is required by the Component. They are:

Function

This squib has one of the following forms:

(Type arg, ... Type arg) -> result

(Type arg, ... Type arg) -> {Statement; Statement; ... return result}

Use the first of these if your result can be computed with a single statement.