Component Guide 1: Overview; Atomic Components
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:
- Click the desired component on the component pallet; components are identified by their icons and tool tips that appear when the mouse hovers over a component.
- Click on the model canvas at the location chosen for this component; do not drag the component from the component pallet.
- When prompted, provide a component name (a default name will be provided if you choose not to provide one).
A new component requires two actions to integrate it into the model:
- Connections must be made to components with which this component will interact; and
- The new component must be programmed; in the simplest case, this involves providing a component equation that defines the value represented by this component. Specific programming tasks for each component type will be described below.
- Atomic Components
- Tranditional systems dynamic components Stock, Flow, Term (called converters in Stella); along with Sequence, Local Variable, DataInput, DataOutput, and Command
- 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.
- These are special purpose components consisting of Code Chip and Label.
- These are extensions to the component set and have various functions. They appear in the Dashboard and as stubs in the Model Canvas.
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.
A 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.
A 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.
A 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.
- Initial Value. The initial value can be a number, or an expression (equation).
- History. Specifies how long values are retained by this Stock. If set to 0, values are kept for the length of the simulation.
- Interactive Graph. Determines the type of graph displayed during Interactive Mode.*
- Non-Negative. If this box is checked, the value of the Stock will never go below zero. If a flow connected to the Stock removes more objects than the Stock has, the value of the Stock will simply be set to 0.
- Sequence. When checked, the Stock becomes a Sequence.
- Local Variable. When checked, the Stock becomes a Local Variable
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.
- Value. The amount moved in our out of the connected Stock. The value can be a number, or an expression (equation).*
- Uniflow. A uniflow Flow will only support non-negative values (i.e., a negative value acts as a zero). Content only moves in one direction.
A 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 simulation 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.
A Property is a type of Term where the value is computed before the first timestep and never changes over the course of a run.
- Value. The quantity represented by this Term. The value can be a any legal NovaScript expression.
- Property. When checked the Term becomes a Property; its value will only be computed once during simulation reset.
- Interactive. Determines how this Term is represented during Interactive Mode. If checked, the Term becomes a Slider.
- Precision. Calibrates the Slider used by an Interacitve Term during Interactive Mode.
- Batch Mode. Enables and sets properties used for Batch Mode.
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.
- PreUpdate / PostUpdate. Determines if the Command runs in the timestep before are after Stocks, Sequences, etc. have been updated to their new values. See Simulation Concepts for details.
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.
- Value, Property, Interactive Precision, Batch Mode. Same as for Terms; note however the value of an Input Pin only serves as a default in the event that the corresponding connector pin is disconnected.
- Pin Number. Permits the user to set the pin number of the component, assuming that pin number is possible (recall all DataInputs are numbered lower than DataOutput). Other DataInputs/Outputs are renumbered as needed.
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.
- On the Component Pallet click on the Arrow.
- 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.
- 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