Component Guide 2: Containers

From Nova Documentation
Jump to: navigation, search

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 DataInputs and DataOutputs (i.e., the Interface) of the constituent Capsule type(s), although some Containers add pins. Pin connection uses a common dialog format for all Containers and is shown below.

Pins are addressed using dot notation. If Container X has Pin Y, then X.Y is a reference for the 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 realized by a set of primitive operators (primops) provided by the Container. (We refer to such primops as service providers.) The data structure of the container together with the service providers comprise an abstract data type that effects a specific topological environment.

Every aggregator has a means for uniquely identifying its members. We'll refer to this as its Aggregator Id.

Examples
  • A Chip binds the property Super to reference the State Object of the Chip's parent (a State Object is a NovaScript object that binds each component in a Capsule to its value in the current timestep). This is used by the Chip's DataInputs to channel component data from that 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 AgentVector corresponds to the topological space created by the CellMatrix.

Service provider details are given with each entry below. They are also described in depth in Properties and Primops Reference.

Connecting Container Connector Pins to components in the host Capsule

  • Right-click the Container to open its Properties Window. This window will contain a Connector Dialog, as shown below.

Help comp container connector dialog.png

  • The Input and Output Selector choosers let you select the pin you wish to connect. Eligible selections are displayed in the Input and Output *Target lists. You can select only a single input for each Input Target, however multiple outputs may be selected by using the Shift Key when selecting.
  • By rotating through all of the Input and Output Selector entries, connections can be specified for all connector pins. For those that are to remain unconnected select "None".
  • When a connection set has been accepted (by closing the Properties Window) dashed lines called connector lines will indicate the connections made to each pin. Connector line visibility is controled by the current Tools | Arrow {On, Highlight, Off} mode.

Standard Aggregate I/O Protocol

Most aggregator Connector Pins represent components of the Capsule Interface (i.e., the DataInput/Output components) of their elements. As such, each creates either a one-to-many (input) or many-to-one (output) data connection between the Aggregator and the component at the other end of the connection in the parent Capsule (i.e., the connection's source for input or target for output). To provide maximum flexibility the following protocol is used:

Input
  • 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 used only with that element.
Output
  • If the target is a plugin pin expecting input from the aggregator, the data is handled accordingly; otherwise
  • The output pin is treated like a function that inputs the Aggregator Id and returns the value for the pin's DataOutput in the corresponding element.

Example

Help comp container pins.png

The right-hand figure shows AgentVector Universe containing a Capsule type whose Interface, comprised of 2 DataInputs and 1 DataOutput, is shown at left. Since this is an AgentVector, Init_Count and AData pins are added to the Interface pins on Universe (see AgentVector, below). The Term Initial_Count contains a scalar value initializing the size of Universe (note: the "10" appearing in the component is a default value only, used only if the Init_Count pin is not connected.) Similarly, the AData pin is connected to a corresponding AData pin on the AgentViewerX stub for UniverseView.

If we assume that the Term Speed_Input represents a common speed for all agents, then Speed_Input can contain a scalar numerical value that is broadcast to all Speed DataInputs among the Universe elements. However, if we want to initialize State_In differently in each element, we can use an expression of the form function(id){...}in the Term State_In_Input that will be applied to each Agent Id to determine the value for that agent's State_In DataInput.

The State_Out pin is connected both to an input on UniverseView and to the Term State_Out_Output. The UniverseView pin, which has the label AgentColorIn, expects to be connected to an AgentVector Interface output pin and can process its data accordingly; the Term State_Out_Output can access the State_Out values of specific agents by treating the pin as a function: i.e., using expressions such as Universe.State_Out(id).

Chip

Help comp container chip.png

A Chip encapsulates an instance of a Capsule to act 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 Nova 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.

Fully connected Chip used to encapsulate an agent mover, showing connector lines.

To add a Chip to the current Capsule

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

Pins

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

Example

Click here for an example of using Chips in various ways.


Clocked Chips

Help clocked.chip.png
Specifying the clock of clocked chip

Aside from the Connector Dialog, the Chip's Properties Window contains the option of making this Chip a Clocked Chip. Clocked Chips are paired with a dedicated clock (programmed according to the parameters specified in the Properties Window). Each timestep of the parent Capsule produces a complete run of the submodel contained in the Clocked Chip.

Like the capsule chip described above, a clocked chip encapsulates a capsule submodel within a second capsule. However, whereas the contents of a capsule chip fires with same timing as its host (i.e. once per time step), the clocked chip uses a separate clock to perform a complete run for each time step of its host.

Clocked Chips are paired with a dedicated clock (programmed according to the parameters specified in the Properties Window, right). The user must provide complete clock and integration method specifications for the clocked chip. If Soft Reset is unchecked, each run reinitializes the state to initial values specified in the Stocks, Variables and Sequences; if checked, state values are retained between runs.

Since the clocked runs to completion of its clock on each firing, output pins only contain final run values. A data structure called RunData can be used to record and retrieve intermediate state values.


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 Nova 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 properties and primitive operators that enforce a topological structure on the 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 value, however, each cell must be able to identify its own coordinates and have some means of communicating with other cells in the lattice. This is the role of Nova’s aggregating components: 1) organize and provide access to a (possibly large) set of constiuent Capsules; and 2) provide a set of properties and primops that foster information transfer among those constituents. Using this fundamental design the four aggregating components currently available with Nova provide different topological organizations for their elements. Here are brief descriptions (note: all example properties and primops are restricted):

AgentVector
Organizes its constituent set into a 1-dimensional array of agents. Each agents is assigned an agent id and contains a Capsule instance. Each agent is equipped to record 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 constituent set into a 2 dimensional matrix or cells, with each assigned a row-column coordinate pair. Example property: Coords, which is bound to a Coord[1] object containing the row and column of the caller[2]. Example primop: RING(n), which returns the array containing the coordinates of all neighbors n units away from the caller.
NetWorld
Combines the topological spaces created by the NodeNetwork and the AgentVector.
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.
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)[3]. 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.
Click here for an example of using a SimWorld.

AgentVector

Help comp container agentvector.png

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.
In the current version of Nova, all elements of an AgentVector must be of the same Capsule type -- this will change in future versions of Nova, requiring only that all Capsules used to define members of a given AgentVector be compatible (i.e., have equivalent Interfaces).

Every agent is given a unique Id value which is never recycled during simulation. This serves as its Aggregator Id.

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.
An AgentVector receiving its initial count from the Agent_Count Slider and communicating with the World AgentViewerX plugin.

Properties

  • Rows, Cols. Dimension of the virtual space created by this AgentVector. In a SimWorld, same as the dimension of the corresponding CellMatrix.
  • Spotlight Agent. Determines the Agent Id used for Spotlighting.
  • Count. Contains an expression determining the default initial agent count. Overridden when a connection is made to the Init_Count pin.
  • 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 AgentVector, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection. In future versions it will be able to contain a function that can vary the Capsule type depending on Agent Id.
  • 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.

Pins

The Connector Pin set of the AgentVector 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 to a corresponding input pin on plugins designed to work with agents (again, see for example, AgentViewerX).

All other pins correspond to the Interface and use the Standard Aggregate I/O Protocol.

CellMatrix

Help comp container cellmatrix.png

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 (i.e., have equivalent Interfaces).

Every cell is identified by its row/column coordinates, which serve 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.
A CellMatrix communicating with a Raster plugin.

Properties

  • Rows, Cols. Dimension of this CellMatrix.
  • Spotlight Row/Col. Determines the cell coordinates used for Spotlighting.
  • 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 CellMatrix, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection.
  • Array Layout. Selects either a cartesian or hexagonal geometry for the CellMatrix.

Pins

All pins correspond to the Interface and use the Standard Aggregate I/O Protocol.

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 a shown in the figure, with coordinates restricted so that their sum is an even number.

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

NetWorld

Sample NetWorld.png

A NetWorld is a network topology of Capsules (i.e. a mathematical graph) that has been extended to support location, trajectory and lifecycle functionalities. The Capsules are agents, from an AgentVector, and the network where the agents live is a NodeNetwork. In this way a NetWorld is a combination of an AgentVector and a NodeNetwork. This means NetWorlds consist of cell and agent Capsules that have Node and Agent properties, respectively. In summary, NetWorlds have Nodes that can change and Agents that can interact with the Nodes. This is what differentiates them from AgentVector.
To program a NetWorld with a particule Capsule type

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

Properties

Agent Properties:

  • Spotlight Agent. Determines the Agent Id used for Spotlighting.
  • Count. Contains an expression determining the default initial agent count. Overridden when a connection is made to the Init_Count pin.
  • 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 AgentVector, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection. In future versions it will be able to contain a function that can vary the Capsule type depending on Agent Id.

Node Properties:

  • Counts. The number of nodes in this NodeNetwork.
  • Spotlight Node. Determines the Node Id used for Spotlighting.
  • 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.


Pins

The Connector Pin set of the AgentVector section of the NetWorld 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 to a corresponding input pin on plugins designed to work with agents (again, see for example, AgentViewerX).

Sample NetViewer showing 5 Nodes where Agents interact and move between

All other pins correspond to the Interface and use the Standard Aggregate I/O Protocol.

Incorporating a NetViewer

The nodes in a NodeNetwork are related to one another through a network topology. In order to visualize these nodes within a two-dimensional space we can utilize Nova's NetViewer plugin. NetViewers, as the name implies, are used to view nodes within a network. You can specify the number of rows and columns, initial node values, node size variation, and node colors.


NodeNetwork

Sample NodeNetwork.png

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.
  • Spotlight Node. Determines the Node Id used for Spotlighting.
  • 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 Standard Aggregate I/O Protocol.

Incorporating a NetViewer

The nodes in a NodeNetwork are related to one another through a network topology. In order to visualize these nodes within a two-dimensional space we can utilize Nova's NetViewer plugin. NetViewers, as the name implies, are used to view nodes within a network. You can specify the number of rows and columns, initial node values, node size variation, and node colors.


SimWorld

Sample SimWorld.png

A SimWorld is a two-dimensional array of Capsules (i.e. a matrix) that has been extended to support location, trajectory and lifecycle functionalities. The Capsules are Agents, from an AgentVector, and the matrix where the Agents live is a CellMatrix. SimWorlds are a combination of an AgentVector and a CellMatrix. This means SimWorlds consist of cell and agent Capsules that have Cell and Agent properties, respectively. In summary, SimWorlds have Cells in the background that are submodels and Agents that interact with their background, the CellMatrix.
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.
  2. Release the mouse.

Properties

Agent Properties:

  • Rows, Cols. Dimension of the virtual space created by this AgentVector. In a SimWorld, same as the dimension of the corresponding CellMatrix.
  • Spotlight Agent. Determines the Agent Id used for Spotlighting.
  • Count. Contains an expression determining the default initial agent count. Overridden when a connection is made to the Init_Count pin.
  • 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 AgentVector, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection. In future versions it will be able to contain a function that can vary the Capsule type depending on Agent Id.
  • 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.
  • Spotlight Row/Col. Determines the cell coordinates used for Spotlighting.
  • 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 CellMatrix, as described above. The string "__bogus__" is used as a placeholder prior to Capsule selection.
  • Array Layout. Selects either a cartesian or hexagonal geometry for the CellMatrix.

Pins

Example of using an AgentViewerX Plugin to visualize a 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 (again, see for example, AgentViewerX).

All other pins correspond to the Interface and use the Standard Aggregate I/O Protocol.

SimWorld Examples

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


Notes

  1. Coord object is one containing the properties row and col.
  2. by caller we mean that Capsule instance that is making the reference.
  3. Math.floor maps a real number to the largest integer less than that number; e.g., Math.floor(3.5) = 3.