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.

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.

Numerus Simulation

A Numerus model is a program that drives a run-time simulation. The simulation is initialized to some initial state and executes using a clock to delineate time steps. At each time step the simulation's current state is used to compute its next state. Intermediate results may be recorded as the simulation progresses, with final results recorded upon termination. State transitions may be deterministic or stochastic (using a pseudo-random number generator).

The model is comprised of components organized into a groups called Capsules forming a hierarchical structure. The simplest model consists of a single Capsule and is analogous to a system dynamics model. The use of special containers to form the hierarchy give rise to Numerus's additional expressiveness in forming spatial, agent-based and network models.

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 here.

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 the state values computed at one time step are used in the next, (as opposed to functional components like Terms, whose values at each time step are derived entirely from the current state.) The four state components are:

Stock

The standard SD 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 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 2-dimensional cartesian spatial model of this type is Conway's Game of Life. The cells in this model 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

In Numerus an agent is a Capsule instance that exists at some location in a 2 dimensional cartesian or hexagonal spatial landscape. The agent population may be fixed or may vary dynamically over the course of the simulation. Numerus uses an array container called an AgentVector to manage the set of agents. In addition to the state created by its capsule, an agent is also assigned a pair of variables that serve as its xy coordinates in the spatial landscape. As an agent moves the AgentVector adjusts its spatial coordinates accordingly. The AgentVector also manages the population of models with dynamic agent populations. Special operators allow the agent to manage its movement, determine population changes through births and deaths, and detect and query other agents within a specified distance.

If an AgentVector is paired with a CellMatrix, it forms a component called a Simulation World (or SimWorld). In this case the agent landscape is identified with the landscape determined by the CellMatrix, and an agent's location coordinates refer to corresponding cell coordinates. Additional operators facilitate interaction between agents and cells. A similar pairing can be made between agents and networks as described below.

Network Based Models in Numerus

A network generalizes the topology of a spatial landscape. The Numerus NodeNetwork component is a container for an array of nodes, each of which is a Capsule instance. These nodes, together with a set of directed arcs, form a mathematical graph. The NodeNetwork provides operators that inform the node about its arc-based topological neighborhood. A NodeNetwork can be paired with an AgentVector to create a NetWorld (analogous to a SimWorld) in which the agents move from node to node through the network.