Component Guide: Overview and Atomic Components

Overview

Nova models are constructed out of components, which are visual tokens that are placed on the Model Canvas.

To place a component on the model canvas:

A new component requires two actions to integrate it into the model:

Component Types

Atomic Components
Tranditional systems dynamic components Stock, Flow, Term (called converters in Stella); along with Sequence, Local Variable, DataInput, DataOutput, and Command
Containers
Nova containers consist of Chips and aggregators; the latter hold multiple instances of one or more Capsule types. (Capsules, also called submodels are described here.) Each aggregator type implements a different topology for its elements. The aggregator components are AgentVector, CellMatrix, NodeNetwork, SimWorld and NetWorld.
Controls and Displays
These include Table, Graph, Slider and Spinner. They appear in the Dashboard and as stubs in the Model Canvas.
Special
These are special purpose components consisting of Code Chip and Label.
Plugins
These are extensions to the component set and have various functions. They appear in the Dashboard and as stubs in the Model Canvas.

Properties

Each component has an associated properties window that provides the means for programming the component (and in some cases specifying connections.) The Properties Window is opened by right-clicking along the edge of the component. Components appearing in the Dashboard, with stubs in the Model Canvas (i.e., controls, displays and plugins), may open a different Properties Window depending on which is clicked. Properties Windows allow you to define the value represented by a component, set pin connections, determine what is displayed (in the case of Graphs and Tables), calibrate (in the case of Sliders and Spinners) and set any other property required by the component.

System Component Properties: The Stock, Flow, Term, Sequence, Local Variable, Command, DaatInput and DataOutput all open similar Properties Windows (the Stock Properties Window is shown here). Each of these components requires a component equation to specify its value (in the case of Stock, Sequence and Local Variable components, the value specified is an initial value.) This equation is a NovaScript expression typed into the Equation Window. To assist in constructing this expression are the Connections, Primops and Properties windows. Clicking on any entry in these windows will copy the entry at the insertion point in the Equation window.

The Connections window shows all input controls and all components connected to this component, either with arrows or pin connections. The Primops window is a list of all primitive operators (primops), and the Properties window is a list of all primitive properties (i.e., symbols representing fixed values).

Finally, the Comment window is provided for documentation purposes. It does not affect the simulation in any way.

The other properties shown here (History, etc.) are specific to Stocks. Such properties will be defined in the Component descriptions given below.

Stock

Stock represents a value that is changing over time. Changes to the stock are specified using one or more Flows, which are connected to it. Flows are either inflows or outflows, which respectively represent values being added to or subtracted from the current stock value. The value of a Stock at the end of each time step is equal to the value at the previous time step, plus the total inflow (i.e. the total flow value flowing into the stock) minus the total outflow (i.e., the total flow value flowing out of the stock). Stock values must be numerical.

Sequence is a type of Stock to which only a single inflow is connected. In this case the inflow's value replaces rather than adds to the current stock value. A sequence value may be any legal NovaScript data type.

Local Variable is a type of Stock without flows. It is used to hold values that may not require updating at each timestep of the simulation. Local Variables are used by Commands and Code Chips to store values across simulation timesteps. A Local Variable may be any legal NovaScript data type.

Properties

Stock showing 1 inflow and 1 outflow
Sequence with single inflow

Flow

A flow can be thought of as a pipe that moves content into or out of a Stock. Flows are always connected to Stocks. The Flow's value reprensents the quantity moved by the Flow at each timestep. Positive Flow values move from left to right, or from the filled or "negative" end to the clear or "positive" end of the connectors. A biflow Flow will flow in the opposite direction when when its value is negative. Flows can be connected at both ends, in which case the Stock at the negative end is decremented and the Stock at the positive end is incremented by the same amount (or vice verse for a biflow Flow with a negative value). Alternatively, a Flow may only be connected at one end (either as an inflow or outflow) in which case the "cloud" symbol represents the unmodeled source or sink of the content. Flow values must be numerical when used with Stocks, but may be any NovaScript data type when used with a Sequence.

Properties

Flow between 2 Stocks
Flow into a single Stock

Term

Term is a visual representation for an expression. Terms are typically used to hold parameter values or compute an algebraic expression based on other objects, either for display or to feed into another part of the model.

A term enabled during Batch Mode will be given start, end and increment values; the simlation repeats with the term assuming the values between start and end determined by the increment; if more than one Term is enabled during Batch Mode, the repeated simulations are nested. see Batch Mode for details.

Property is a type of Term where the value is computed before the first timestep and never changes over the course of a run.

Properties

Term used to provide birth rate in Simple Population Model
Properties used to hold coordinates and neighbor list in Game of Life

Command

A command contains code that is generally executed once per timestep (init and final commands are the exception; see below). Commands do not return values used by other components; rather they operate by side-effecting simulation state, often through the execution of primops. One common use for a Command is during program development, where the PRINT primop is used to print useful values to the console. Another important role is in the agent life cycle, where Commands may contain code to create or terminate agents, or move them in their environment.

If the Command name starts with init then the command is an initializer and is only run once during simulation startup. Similarly, a Command with a name that starts with final will only execute at the end of the run.

Properties

Commands used to control agent births and deaths in the Billiards Model.

DataInput / DataOutput

DataInputs and DataOutputs are Terms that serve as input/output channels for submodel Capsules embedded in Containers. For each DataInput/DataOutput in the submodel there exists a correspond Connector Pin on the Container which can be connected to a component in the parent Capsule. A DataInput will assume the value of the connected component. If the Connector Pin on the Container is disconnected, the DataInput's assigned value is used as a default.

A DataOutput's assigned value (usually the value of some component in its Capsule) is transmitted through the corresponding Connector Pin of its Container to whatever component that Connector Pin is connected to.

Together, the set of DataInputs and DataOutputs comprise the Interface of the Capsule in which they appear.

Pin numbering. Every DataInput/Output in a Capsule is assigned a pin number, which determines the corresponding Connector Pin in its Container. Pins are numbered consectively, with all DataInputs numbered lower than any DataOutput.

Properties

DataInputs/Outputs used in the Logistic Model submodel called Population

Arrow

Arrows are technically not components; rather they show value dependencies among components.
An arrow should be directed from component A to component B whenever computation of the value of B requires the value of A. When such an arrow is inserted, component A will appear in the Connections box in the Property Window of component B.

Connecting an arrow from component A to component B.

  1. On the Component Pallet click on the Arrow.
  2. Click component A. A dashed red line from A to the cursor will appear. You can cancel the insertion by right-clicking on the canvas.
  3. Now click component B. The arrow will appear. Clicking the arrow will cause its handle to appear, allowing you to determine the shape of its arc.

Menu actions affecting arrows.

  • Tools | Arrow Snap: causes all currently visible arrows to assume their shortest length.
  • Tools | Arrows On: causes arrows to become visible
  • Tools | Arrows Highlight: causes arrows to become visible only when the mouse hovers over one endpoint.
  • Tools | Arrows Off: causes arrows to become invisible

Connecting Pop with Pop Out

Reshaping arrow from r to Out