Modeling in Numerus

In Modeling 101 you were introduced to the various paradigms and concepts of computational modeling. Here we discuss how these are realized in Numerus.

Basic Model Design in Numerus

It is important to understand the structure of the Numerus platform in order to implement powerful and complex dynamical system and spatial, agent-based and network models. Numerus provides an impressive range and versatility of components to effectively design and execute models. In addition, Numerus has the capability to implement designs using specialized components. To utilize Numerus's capabilities we must first understand the basics of Numerus's Capsule-based architecture.

Capsule, Chip, Submodel, Programming

Numerus introduces a modular design feature called a Capsule. A Capsule is a model space containing interacting components such as Stocks, Flows, Terms, Commands, etc. Each Numerus model is comprised of one or more Capsule instances in a hierarchical relationship. A Capsule instance called main (which can only have one instance) is at the root of this hierarchy. Instances of other Capsules can be inserted into the model space of a given Capsule using special container components. The simplest of these is called a Chip and it contains a single instance of another Capsule. The entire hierarchy of Capsules rooted at the Chip is called a submodel . Other containers are used to create spatial, agent-based and network architectures and will be discussed below.

This figure shows a model built out of 4 Capsules. In (a) we observe the dependency hierarchy: Capsule Main requires Capsules C1 and C2. C1 requires C2 but also requires C3. In (b) we see that in the structural hierarchy Main has 2 instances of C1 and 1 instance of C2; consequently the model uses 2 instances of C1, 3 instances of C2 and 2 instances of C3.

Each component inserted into a Numerus model must be "programmed" to describe its relationship to other components and to the model as a whole. This programming uses the language NovaScript, which is the JavaScript language extended with some special features. In simple models, most components represent values, in which case the program is an algebraic expression defining the value. In more advanced models some programs may make use of additional algebraic tools in the language. Along with the tools provided by JavaScript, Numerus comes equipped with special primitive operations and constants (referred to, respectively, as primops and primprops) that address the needs of modeling. After determining the Capsule structure and selecting the components for each Capsule, component programming is the ultimate "glue" that solidifies your model. It will be discussed and illustrated throughout this user guide.

Dynamical Systems Models in Numerus

This user guide assumes the reader is familiar with basic system dynamics (SD) methodology. One place to start is [1].

Numerus implements several different types of state component, extending the SD concept of stock. State component, like stocks, are distinguished in SD modeling by the fact that they maintain their values across time steps, as opposed to functional components like Terms, which recompute their values at each step. The four state components are:

Stock

The standard DS state component to which one or more Flows can be attached. The Stock's value is updated at each time step based on the values of its Flows.

Stock+Flow

A version of the Stock component with a single incoming Flow. Appropriate for translating a differential equation into a model element.

Sequence

A special type of Stock with a single incoming Flow. The Flow value replaces rather than adds to the Sequence's value.

Store

A container for a value that is modified by code. No state change takes place unless required by the code. A Store acts like a global variable for the model.

Flows in Numerus follow standard rules for system dynamics: they control the movement of value to and from Stocks.

Numerus Terms play several roles, all of which involve computing or delivering a value. A pure Term simply computes a value using the values of other components in the model. A constant Term computes this value only once and maintains it throughout the simulation. A Graph Function Term is derived from a user-defined graph. In Pins and Out Pins are used with capsule chips and described elsewhere. A Spy displays its value on the runtime dashboard. An External Term is derived from input data and is also described in detail elsewhere.

Spatial Models in Numerus

Spatial modeling introduces into the model an awareness of position in 2 or 3 dimensions. In Numerus this capability is encapsulated using a component called a CellMatrix. A CellMatrix is an array of cells forming a geometric lattice. The lattice can have either a cartesian or hexagonal topology. Each cell is comprised of a capsule instance extended with special operators that inform the cell of its topological properties. A well-known example of a spatial model of this type is Conway's Game of Life [2]. The cells are in one of two states (“alive” or “dead”), and state transition depends on the state of a cell's 8 neighbors. In Numerus, a Life cell is Capsule with a single Sequence component representing its state. Special primitive operators allow a cell to query the state of its neighbors to determine its own state transition.

Agent Based Models in Numerus

Agent based models in Numerus are models that make use of an AgentVector. The AgentVector contains the population of Agents, as well as their location. In addition, Numerus includes Simworlds and Networlds. A SimWorld combines an AgentVector with a CellMatrix that provides a landscape. The Networld component uses a NodeNetwork for the same purpose. The SIR model is an example of an agent vector, with agents moving about an open space in three possible states, Susceptible, Infected, and Recovered. The Antz model is a more complicated model that uses both an agent vector and a cell matrix in order to simulate how ants collect food and leave a path for other ants to follow in order to find the same food.

Numerus has a lot of tools that make agent based models simpler and more robust. In particular, it is very easy to have access to all agents and cells from each individual agent, and to incorporate a wide variety of local and global effects. It also makes it simple to set up multiple Sim Worlds in order to see various outcomes simultaneously. It is also built on arrays and methods, which makes it simple to work on a small level to tweak the model to the user’s liking. On the other hand, the visual side of Numerus makes it so that it is easy to quickly and efficiently set up the shell of an agent based model and immediately get down to the more important details involved in the model. A savvy Numerus programmer will begin an agent based model visually and slowly transition over to handling the methods and functions in a more programming heavy reference frame.

Chip Basics

As the Numerus Glossary states, a Chip is a Container component which contains a single Capsule instance. A Capsule is a prototype for a simulation unit. It contains base components and may contain other chips, inputs, and / or outputs. These definitions may appear a bit vague or broad, however, that is simply because Chips and Capsules are widely used in a variety of ways within Numerus.

Chip structure and usage in Numerus may best be understood through example. Click here for an example of using a preexisting model (from the Model Library) and manipulating the ideas of model layers and chips.

Population Model 101

See the Simple Population Model tutorial in the Model Library. This tutorial demonstrates fundamental Numerus usage, including how to operate the Graphical User Interface, or GUI, and its algorithmic and mathematical design. You will see basic usage of the Modeling Canvas and the Dashboard as well as Numerus's intuitive mathematical design.

• Jump into NumerusMB's Operational Semantics here.

• Get a run through of NumerusMB's GUI here.