Component Guide II: Containers

Overview

Containers are components that hold one or more instances of a Capsule for use within a host (or parent) Capsule. The elements of a Container are called members or elements. Containers interface with the components in their parent through Connector Pins, which are represented as horizontal lines on the left and right side of the container body. (Left and right sides correspond to input and output pins, respectively.) Every Connector Pin is given a label, and they correspond roughly to the Input Pins and Output Pins of their Capules, although some Containers add pins.

Pins are addressed using dot notation. If Container X has Pin Y, then X.Y is a reference for that Pin.

Each container type extends and enriches the environment of its elements by assigning new functionalities that are only valid within the context of the container. These new functionalities are introduced through a set of primitive operators (Primops) provided by the Container. (In the language of computer science these kinds of Primops are called service providers.) The data structure of the container together with the service providers create a topological environment for the constituent Capsules. For example, the CellMatrix container holds a set of Capsules in a lattice or grid structure. Each Capsule is assigned row and column indices, and neighborhoods of Capsules can be identified and manipulated.

Every aggregator (i.e. a container holding more than one Capsule) assigns some form of identification to each of its constituents. For example, in the case of the CellMatrix, the index pair serves to uniquely specify a particular element. We'll use the term Aggregator Id to uniformly refer to this identification strategy.

Examples

• A Chip binds the property Super to reference the Scope of the Chip's parent. This is used by the Chip's Input Pins to channel component data from the parent into the Chip.
• An AgentVector assigns a unique Agent Id to each element (or agent) and provides the means for interaction between agents using these ids for indentification. It also represents location and trajectory parameters in the virtual space provided by the AgentVector in which its agents dwell. An AgentVector also supports agent lifetime management (i.e., births and deaths).
• A CellMatrix assigns matrix Coordinates to each of its elements and supports interaction between its members (or cells) using these coordinates for identification.
• A SimWorld combines an AgentVector with a CellMatrix, so that the virtual agent space of the AgentVector corresponds to the topological space created by the CellMatrix.
• A NodeNetwork assigns a unique Node Id to each node of its graph.
• A NetWorld combines an AgentVector with a NodeNetwork so that the virtual agent space of the AgentVector corresponds to the topological space created by the NodeNetwork.

Connecting parent Capsule components to Input Connector Pins in a Container

Container Input Connection Table

The property pane of each container contains a table listing the inputs to that container.

To connect a component as an input to the container select the row containing the input and either select from the Select menu or right-click on the component.

Note: Output pins are accessed by connecting them as inputs to other components.

Common Aggregator I/O Protocol

Aggregator rules require that all member Capsules must be compatible; that is, they must contain identical Input/Output pin configurations. Consequently, most aggregator Connector Pins correspond directly to some input or output pin in each of the elements: each pin creates a one-to-many input connection or, respectively, a many-to-one output connection between the Aggregator and some component in the parent Capsule. To provide maximum flexibility the following protocol is used:

Input to the Aggregator

• If the source expression produces an ordinary NovaScript data structure (i.e., number, string, array, or object), that value is broadcast to all elements of the aggregator.
• If the source expression is a function, that function is applied to the Aggregator Id of each element, and the resulting value is sent only to that element.

Output from the Aggregator

• The output pin is a function that inputs the Aggregator Id and returns the value for the Output Pin in the element with that Id.

Examples illustrating this protocol will be given below.

Chip

A Chip encapsulates an instance of a Capsule as a submodel within a host Capsule. More than one Chip containing instances of the same Capsule, or different Capsules, may appear in a single parent. Large Numerus models can be built using stacks of submodels based on a well-structured design pattern.

Each Chip has connector pins corresponding exactly to the set of Input and Output Pins in the encapsulated submodel.

To add a Chip to the current Capsule

1. Press the mouse left button on the desired Capsule in the Capsule List and drag onto the Model Canvas to the desired location.
2. Release the mouse and the Chip will appear.

Properties

• Clocked Chip. If checked, turns this Chip into a Clocked Chip. See below.

Pins

The Connector Pins of a Chip provide direct access to the Interface (i.e., the Input/Out Pins) of the encapsulated submodel. Each pin is labeled with the name of the corresponding Interface component.

If an input pin is not connected in the parent model, the pin's value is used as a default.

Clocked Chip

Clocked Chips are paired with a dedicated clock (programmed by the parameters specified in the Properties Pane). Each timestep of the parent Capsule produces a complete run of the submodel contained in the Clocked Chip.

The user must provide complete clock and integration method specifications for the clocked chip.

Properties

• Start, End, DT, Method. Runtime properties assigned to the Clocked Chip's dedicated clock.

See Using Clocked Chips

Introduction: Aggregators

Abstraction is the process of extracting a set of interacting elements which together create a well-defined computation over a given a set of inputs, and providing the ability to access that computation with different inputs from multiple points within the overall project. The simplest example of this in Numerus is the Capsule which is used in one or more chips to implement the instances of a particular submodel. Chips are less useful when large numbers of submodels are required. In such cases it is more efficient to use some form of container to hold a set of Capsule elements. This is analogous to using arrays to manage large sets of data. Like the array, an organizing structure (i.e., the index set) is required to provide a uniform means of access to these constituents.

We can actually take this one step further by adding a set of primitive properties and primitive operators that enforce a topological structure on the constituent Capsules. For example, if we organize the Capsules into a two-dimensional lattice, each could represent a single cell in a cellular automaton. In order for this to be of any use, however, each cell must be able to identify its own coordinates and have some means of communicating with other cells in the lattice.

Element Compatibility

Numerus does not require that all of the elements of an aggregator be derived from the same Capsule (although this is usually the case). However they must satisfy the compatibility rule:

Two Capsules are compatible if they have the same number of input and output pins with the same names.

This is necessary so that the pin configuration on the aggregator matches the inputs and outputs of all of the elements. When Capsules are compatible we say they have a common interface.

Numerus' Aggregators

This is the role of Numerus’s aggregating components: 1) organize and provide access to a (possibly large) set of constituent Capsules; and 2) provide a set of properties and operators that foster information transfer among those constituents. Using this fundamental design the five aggregating components currently available with Numerus provide different topological organizations for their elements. Here are brief descriptions (note: all example properties and primops are restricted):

AgentVector

Organizes its Capsule set into a 1-dimensional array of agents. Each agent is assigned an agent id and contains a Capsule instance. Each agent is equipped to remember its location as a pair of x-y coordinates. Example property: myId, which returns the caller’s agent id; Example primop: MOVE(x, y) sets the current location of its caller to (x, y).

CellMatrix

Organizes its Capsule set into a 2 dimensional matrix of cells, with each assigned a row-column coordinate pair. Example property: Coords, which is bound to a Coord object containing the row and column of the caller. Example primop: RING(n), which returns the array containing the coordinates of all neighbors n units away from the caller.

SimWorld

Combines the topological spaces created by the CellMatrix and AgentVector aggregators into one that maps the (x, y) location of each agent to position within a cell. In this topology each CellMatrix is the size of a unit square, and so an agent with x-y coordinates (x, y) is mapped to the cell with row-column coordinates (r, c), where r = Math.floor(y) and c = Math.floor(x). Example property: rows is bound to the number of rows in the underlying CellMatrix (can be called from either a cell or an agent). Example primop: MYAGENTS() returns the list of agents currently within the calling cell.

NodeNetwork

Organizes its constituent set into a 1-dimensional array of nodes. Each node is assigned a node number and contains a Capsule instance and a set of weighted pointers referencing other nodes. Example property: myId, which returns the caller’s node number; Example primop: CONNECTIONS_IN returns a list of Objects, each containing the id and weight of a connection to this node.

Click here for an example of using a NodeNetwork.

NetWorld

Combines the topological spaces created by the NodeNetwork and the AgentVector, analogous to the SimWorld.

Visualization

Each aggregator has an associated viewer for displaying the state of the aggregator during the simulation run. Viewer properties are programmed using a dialog launched from the properties pane of the aggregator. These are described elsewhere.

AgentVector

An AgentVector is a one-dimensional array of Capsules (i.e. a vector) that has been extended to support location, trajectory and lifecycle functionalities. We refer to AgentVector members as agents and use the term agent metadata to refer to these new functionalities.
All elements of an AgentVector must be compatible. Every agent is given a unique Id value which is never recycled during simulation.

To program an AgentVector with a particular Capsule type

1. Press the mouse left button on the desired Capsule in the Capsule Set Window and drag onto the AgentVector component.
2. Release the mouse.

AgentVector Property Pane

Properties

• Input Pin Table. See Connecting parent Capsule components to Input Connector Pins in a Container.
• Initializer. The name of the Capsule used to populate the AgentVector. This string is inserted when a Capsule is dragged over the AgentVector, as described above. Alternatively, this text area may containe a Javascript function of the form function(id) { .... }, which returns the names of compatible Capsules as a function of agent id. The string "__bogus__" is used as a placeholder prior to Capsule selection.
• Default Count. The initial number of agents if no input is connected to Pin 0. See below.
• Rows, Columns. Dimension of the virtual space created by this AgentVector.
• Motion: Continuous/Discrete. Determines whether Agent position uses real or integer values. In the latter case, agents are located at discrete positions within a lattice of cells.
• Incl. Display. When checked, include one or more display. See Aggregator Displays.
• Configure Display. Click here to program a display.

Pins

The Connector Pin set of the AgentVector adds one input and one output pin. The new input pin is labeled Init_Count and always appears as Pin 0. This pin is used to initialize the agent set size and overrides the default count property. The special output pin always appears as the first output pin (i.e. on the upper right of the component) and is labeled AData. This pin transmits all agent metadata from the AgentVector to a corresponding input pin on components designed to work with agents. See Agent Examples.

All other pins correspond to the common Capsule interface and use the Common Aggregator I/O Protocol.

CellMatrix

A CellMatrix is a two-dimensional array of Capsules (i.e. a matrix) that has been extended to support interactions among the constituents. We refer to CellMatrix members as cells and use the term cell metadata to refer to these new functionalities.
All elements of a CellMatrix must be compatible. Every cell uses its row/column coordinates as its Aggregator Id.

To program a CellMatrix with a particular Capsule type'

1. Press the mouse left button on the desired Capsule in the Capsule Set Window and drag onto the CellMatrix component.
2. Release the mouse.

CellMatrix Properties

Properties

• Input Pin Table. See Connecting parent Capsule components to Input Connector Pins in a Container.
• Initializer. The name of the Capsule used to populate the AgentVector. This string is inserted when a Capsule is dragged over the CellMatrix, as described above. Alternatively, this text area may containe a Javascript function of the form function(r, c) { .... }, which returns the names of compatible Capsules as a function of row and column. The string "__bogus__" is used as a placeholder prior to Capsule selection.
• Rows, Columns. Dimensions of the CellMatrix
• Motion: Continuous/Discrete. Determines whether Agent position uses real or integer values. In the latter case, agents are located at discrete positions within a lattice of cells.
• Array Layout. Determines whether the CellMatrix uses Cartesian (i.e. grid, lattice) or Hexagonal geometry. See Using Hexagonal Geometry for a discussion of the latter.
• Incl. Display. When checked, include one or more display. See Aggregator Displays.
• Configure Display. Click here to program a display.

Pins

All pins correspond to the common Capsule interface and use the Common Aggregator I/O Protocol.

Using Hexagonal Geometry

Raster displaying 20x20 hexagonal geometry

Selecting the hexagonal array option introduces a hexagonal geometry to the cell array, as shown. In this geometry, the total number of cells is reduced by one-half. Addressing is as shown in the figure, with coordinates restricted so that their sum is an even number.

Numerus supports a special set of primops for use with hexagonal CellMatrices.

SimWorld

A SimWorld combines an AgentVector and CellMatrix to produce a space of Agents operating on the landscape created by the CellMatrix. In addition to the usual Agent and Cell operators, the SimWorld supports operators that facilitate interaction between Agents and Cells. Notably, an Agent can determine the Cell containing its current location, and a Cell can identify all Agents it currently contains.

To program a SimWorld with a particular Capsule type

1. Press the mouse left button on the desired Capsule in the Capsule Set Window and drag onto the SimWorld component, either on top to specify the Agent type, or the bottom to specify the Cell type. The SimWorld label will glow pink or green accordingly.
2. Release the mouse.

Properties

Agent Properties:

• Inputs. Table showing input pins and their sources.
• Default Agent Count. The default initial agent count, used when no connection is made to the Init_Count pin.
• Initializer. Same as the Initializer for an AgentVector. See above
• Agent Motion: Continuous/Discrete. Determines whether Agent position uses real or integer values. In the latter case, when using a SimWorld, agent position is limited to a pair Cell coordinates, and movement within a Cell is not tracked.

Cell Properties:

• Rows, Cols. Dimension of this CellMatrix and the space occupied by AgentVector agents.
• Initializer. Same as the Initializer for a CellMatrix. See above.
• Array Layout: Cartesian or Hexagonal. Selects either a cartesian or hexagonal geometry for the CellMatrix.

Pins

Example SimWorld (from Hexgrazing in the Model Library

The Connector Pin set of the AgentVector section of the SimWorld adds 2 pins (one input and one output) to the Interface of its element's Capsule type. The new input pin is labeled Init_Count and always appears as Pin 0. This pin is used to initialize the agent set. which in its simplest form involves only setting the initial agent count. (When using certain plugins in interactive mode it also initializes agent position; see, for example, AgentViewerX).

The special output pin always appears as the first output pin (i.e. on the upper right of the component) and is labeled AData. This pin transmits all agent metadata from the AgentVector section to a corresponding input pin on plugins designed to work with agents.

All other pins correspond to the Interface and use the Common Aggregator I/O Protocol.

SimWorld Examples

The Model Library has several examples of using SimWorlds including PredatorPreyGrass, Billards, and HexGrazing.

NodeNetwork

A NodeNetwork is a network topology of Capsules (i.e. a mathematical graph) that has been extended to support interactions among the constituents. We refer to the NodeNetwork members as nodes and use the term node metadata to refer to these new functionalities.

To program a NodeNetwork with a particular Capsule type

1. Press the mouse left button on the desired Capsule in the Capsule Set Window and drag onto the NodeNetwork component.
2. Release the mouse.

Properties

• Counts. The number of nodes in this NodeNetwork.
• Initializer. In the current version a string identifying the Capsule used to define elements. This string is inserted when a Capsule is dragged over the NodeNetwork, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection.
• Connector. Determines the connection between the nodes. This may either be a function that decides which nodes have what degree of connection to the others or a single value. If it is a single value all of the nodes will have that level of connection to all of the other nodes.

NetViewer displaying 400 a node topology from NetSIR in the model library

Pins

All pins correspond to the Interface and use the Common Aggregator I/O Protocol.

Notes