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 hold 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 NodeNetork.

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 implement the same interface; that is, they must contain identical Input/Output pin configurations. Consequently, most aggregator Connector Pins corrspond directly to some input or output pin in each of the elements: each pin creates a one-to-many input connection or 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 acts like a function that inputs the Aggregator Id and returns the value for the Output Pin in the corresponding element.

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. See Using Clocked Chips