Difference between revisions of "Modeling in Numerus"
| (31 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
In [[Modeling 101]] you were introduced to the various paradigms and concepts of computational modeling. Here we discuss how these are realized in Numerus. | In [[Modeling 101]] you were introduced to the various paradigms and concepts of computational modeling. Here we discuss how these are realized in Numerus. | ||
It is important to understand the structure of the Numerus platform in order to implement powerful and complex dynamical system and spatial, agent-based and network models. Numerus provides an impressive range and versatility of components to effectively design and execute models. In addition, Numerus has the capability to implement designs using specialized components. To utilize Numerus's capabilities we must first understand the basics of Numerus's Capsule-based architecture. | |||
It is important to understand the structure of the Numerus platform in order to implement powerful and complex dynamical system and spatial, agent-based and network models. Numerus provides an impressive range and versatility of components to effectively design and execute models. In addition, Numerus has the capability to implement designs using specialized components. To utilize Numerus's capabilities we must first understand the basics of Numerus's | |||
==Numerus Simulation== | |||
A Numerus model is a program that drives a run-time simulation. The simulation is initialized to some initial state and executes using a ''clock'' to delineate time steps. At each time step the simulation's current state is used to compute its next state. Intermediate results may be recorded as the simulation progresses, with final results recorded upon termination. State transitions may be deterministic or stochastic (using a pseudo-random number generator). | |||
The model is comprised of components organized into a groups called ''Capsules'' forming a hierarchical structure. The simplest model consists of a single Capsule and is analogous to a system dynamics model. The use of special containers to form the hierarchy give rise to Numerus's additional expressiveness in forming spatial, agent-based and network models. | |||
==Capsule, Chip, Submodel, Programming== | ==Capsule, Chip, Submodel, Programming== | ||
<div id="capsule"> | |||
Numerus introduces a modular design feature called a ''Capsule''. A Capsule is a model space containing interacting components such as Stocks, Flows, Terms, Commands, etc. Each Numerus model is comprised of one or more Capsule instances<ref>Note the distinction between '' Capsule'' and ''Capsule instance''. A Capsule describes a model space containing interacting components. A Capsule instance represents one specific use of that Capsule. A Capsule may have many instances in a project. Capsule and Capsule instance may be used interchangeably when there is no possible ambiguity.</ref> in a hierarchical relationship. A Capsule instance called ''main'' (which can only have one instance) is at the root of this hierarchy. Instances of other Capsules can be inserted into the model space of a given Capsule using special container components. The simplest of these is called a ''Chip'' and it contains a single instance of another Capsule. The entire hierarchy of Capsules rooted at the Chip is called a ''submodel'' <ref>The only restriction is on circularity: no submodel can contain a Capsule that contains that submodel.</ref>. Other containers are used to create spatial, agent-based and network architectures and will be discussed below. | Numerus introduces a modular design feature called a ''Capsule''. A Capsule is a model space containing interacting components such as Stocks, Flows, Terms, Commands, etc. Each Numerus model is comprised of one or more Capsule instances<ref>Note the distinction between '' Capsule'' and ''Capsule instance''. A Capsule describes a model space containing interacting components. A Capsule instance represents one specific use of that Capsule. A Capsule may have many instances in a project. Capsule and Capsule instance may be used interchangeably when there is no possible ambiguity.</ref> in a hierarchical relationship. A Capsule instance called ''main'' (which can only have one instance) is at the root of this hierarchy. Instances of other Capsules can be inserted into the model space of a given Capsule using special container components. The simplest of these is called a ''Chip'' and it contains a single instance of another Capsule. The entire hierarchy of Capsules rooted at the Chip is called a ''submodel'' <ref>The only restriction is on circularity: no submodel can contain a Capsule that contains that submodel.</ref>. Other containers are used to create spatial, agent-based and network architectures and will be discussed below. | ||
</div> | |||
[[File:capsule_hierarchy.png|500px|link=]] | |||
<br clear=all> | |||
This figure shows a model built out of 4 Capsules. In (a) we observe the dependency hierarchy: Capsule '''Main''' requires Capsules '''C1''' and '''C2'''. '''C1''' requires '''C2''' but also requires '''C3'''. In (b) we see that in the structural hierarchy '''Main''' has 2 instances of '''C1''' and 1 instance of '''C2'''; consequently the model uses 2 instances of '''C1''', 3 instances of '''C2''' and 2 instances of '''C3'''. | This figure shows a model built out of 4 Capsules. In (a) we observe the dependency hierarchy: Capsule '''Main''' requires Capsules '''C1''' and '''C2'''. '''C1''' requires '''C2''' but also requires '''C3'''. In (b) we see that in the structural hierarchy '''Main''' has 2 instances of '''C1''' and 1 instance of '''C2'''; consequently the model uses 2 instances of '''C1''', 3 instances of '''C2''' and 2 instances of '''C3'''. | ||
Each component inserted into a Numerus model must be "programmed" to describe its relationship to other components and to the model as a whole. This programming uses the language ''NovaScript'', which is the JavaScript language extended with some special features. In simple models, most components represent values, in which case the program is an algebraic expression defining the value. In more advanced models some programs may make use of additional algebraic tools in the language. Along with the tools provided by JavaScript, Numerus comes equipped with special primitive operations and constants (referred to, respectively, as ''primops'' and ''primprops'') that address the needs of modeling. After determining the Capsule structure and selecting the components for each Capsule, component programming is the ultimate "glue" that solidifies your model. It will be discussed and illustrated throughout this user guide. | Each component inserted into a Numerus model must be "programmed" to describe its relationship to other components and to the model as a whole. This programming uses the language ''NovaScript'', which is the JavaScript language extended with some special features. In simple models, most components represent values, in which case the program is an algebraic expression defining the value. In more advanced models some programs may make use of additional algebraic tools in the language. Along with the tools provided by JavaScript, Numerus comes equipped with special primitive operations and constants (referred to, respectively, as ''primops'' and ''primprops'') that address the needs of modeling. After determining the Capsule structure and selecting the components for each Capsule, component programming is the ultimate "glue" that solidifies your model. It will be discussed and illustrated throughout this user guide. | ||
==Dynamical Systems Models in Numerus== | ==Dynamical Systems Models in Numerus== | ||
Numerus implements several different types of ''state'' component. | This user guide assumes the reader is familiar with basic system dynamics (SD) methodology. One place to start is [//en.wikipedia.org/wiki/System_dynamics here]. | ||
:;Stock: The standard | |||
Numerus implements several different types of ''state'' component, extending the SD concept of stock. State component, like stocks, are distinguished in SD modeling by the fact that the state values computed at one time step are used in the next, (as opposed to ''functional'' components like Terms<ref>In ''Stella'' these are called ''''Converters'''', and in ''Vensim'' they are ''''Variable-Auxiliary/Constants''''</ref>, whose values at each time step are derived entirely from the current state.) The four state components are: | |||
:;Stock: The standard SD state component to which one or more Flows can be attached. The Stock's value is updated at each time step based on the values of its Flows. | |||
:;Stock+Flow: A version of the Stock component with a single incoming Flow. Appropriate for translating a differential equation into a model element. | :;Stock+Flow: A version of the Stock component with a single incoming Flow. Appropriate for translating a differential equation into a model element. | ||
:;Sequence: A special type of Stock with a single incoming Flow. The Flow value ''replaces'' rather than adds to the Sequence's value. | :;Sequence: A special type of Stock with a single incoming Flow. The Flow value ''replaces'' rather than adds to the Sequence's value. | ||
| Line 21: | Line 29: | ||
''Flows'' in Numerus follow standard rules for system dynamics: they control the movement of value to and from Stocks. | ''Flows'' in Numerus follow standard rules for system dynamics: they control the movement of value to and from Stocks. | ||
Numerus ''Terms'' play several roles, all of which involve computing or delivering a value. A pure Term simply computes a value using the values of other components in the model. A ''constant'' Term computes this value only once and maintains it throughout the simulation. A ''Graph Function'' Term is derived from a user-defined graph. ''In Pin''s and ''Out Pin''s are used with capsule chips and described [[elsewhere]]. A ''Spy'' displays its value on the runtime dashboard. An ''External'' Term is derived from input data and is | Numerus ''Terms'' play several roles, all of which involve computing or delivering a value. A pure Term simply computes a value using the values of other components in the model. A ''constant'' Term computes this value only once and maintains it throughout the simulation. A ''Graph Function'' Term is derived from a user-defined graph. ''In Pin''s and ''Out Pin''s are used with capsule chips and described [[elsewhere]]. A ''Spy'' displays its value on the runtime dashboard. An ''External'' Term is derived from input data and is described in detail [[elsewhere]]. | ||
<!-- | <!-- | ||
In Numerus we use the Stock and Flow objects. Stocks represent a pool of what we are measuring: infected population, nitrogen in lake water, and so on. Flows represent the movement of what we are measuring from one stock to another. This would be the flow of people from uninfected to infected population, or nitrogen from lake water to the algae population. Flows can also represent a source or sink of our measured quantity. A Source flow could represent immigration and births adding people, while a Sink flow would could represent people's deaths. Similarly a Source for nitrogen could represent runoff from farmland. | In Numerus we use the Stock and Flow objects. Stocks represent a pool of what we are measuring: infected population, nitrogen in lake water, and so on. Flows represent the movement of what we are measuring from one stock to another. This would be the flow of people from uninfected to infected population, or nitrogen from lake water to the algae population. Flows can also represent a source or sink of our measured quantity. A Source flow could represent immigration and births adding people, while a Sink flow would could represent people's deaths. Similarly a Source for nitrogen could represent runoff from farmland. | ||
--> | --> | ||
==Spatial Models in Numerus== | ==Spatial Models in Numerus== | ||
Spatial modeling introduces into the model an awareness of position in 2 or 3 dimensions. In Numerus this capability is encapsulated using a component called a ''CellMatrix''. A CellMatrix is an array of cells forming a geometric lattice. The lattice can have either a cartesian or hexagonal topology<ref>Hexagonal topology is limited to 2 dimensions</ref>. Each cell is comprised of a capsule instance extended with special operators that inform the cell of its topological properties. A well-known example of a spatial model of this type is | Spatial modeling introduces into the model an awareness of position in 2 or 3 dimensions. In Numerus this capability is encapsulated using a component called a ''CellMatrix''. A CellMatrix is an array of cells forming a geometric lattice. The lattice can have either a cartesian or hexagonal topology<ref>Hexagonal topology is limited to 2 dimensions</ref>. Each cell is comprised of a capsule instance extended with special operators that inform the cell of its topological properties. A well-known example of a 2-dimensional cartesian spatial model of this type is [//www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwiVxv-36PjYAhWD0YMKHU_iBz4QFggoMAA&url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FConway%2527s_Game_of_Life&usg=AOvVaw3Ren4zMW9qfyNBCmJvYMlL Conway's Game of Life]. The cells in this model are in one of two states (“alive” or “dead”), and state transition depends on the state of a cell's 8 neighbors. In Numerus, a Life cell is Capsule with a single Sequence component representing its state. Special primitive operators allow a cell to query the state of its neighbors to determine its own state transition. | ||
==Agent Based Models in Numerus== | ==Agent Based Models in Numerus== | ||
In Numerus an agent is a Capsule instance that exists at some location in a 2 dimensional cartesian or hexagonal spatial landscape. The agent population may be fixed or may vary dynamically over the course of the simulation. Numerus uses an array container called an ''AgentVector'' to manage the set of agents. In addition to the state created by its capsule, an agent is also assigned a pair of variables that serve as its xy coordinates in the spatial landscape. As an agent moves the AgentVector adjusts its spatial coordinates accordingly. The AgentVector also manages the population of models with dynamic agent populations. Special operators allow the agent to manage its movement, determine population changes through births and deaths, and detect and query other agents within a specified distance. | |||
If an AgentVector is paired with a CellMatrix, it forms a component called a ''Simulation World'' (or ''SimWorld''). In this case the agent landscape is identified with the landscape determined by the CellMatrix, and an agent's location coordinates refer to corresponding cell coordinates. Additional operators facilitate interaction between agents and cells. | |||
A similar pairing can be made between agents and networks as described below. | |||
<!-- | |||
Agent based models in Numerus are models that make use of an AgentVector. The AgentVector contains the population of Agents, as well as their location. In addition, Numerus includes Simworlds and Networlds. A SimWorld combines an AgentVector with a CellMatrix that provides a landscape. The Networld component uses a NodeNetwork for the same purpose. The ''SIR'' model is an example of an agent vector, with agents moving about an open space in three possible states, Susceptible, Infected, and Recovered. The ''Antz'' model is a more complicated model that uses both an agent vector and a cell matrix in order to simulate how ants collect food and leave a path for other ants to follow in order to find the same food. | Agent based models in Numerus are models that make use of an AgentVector. The AgentVector contains the population of Agents, as well as their location. In addition, Numerus includes Simworlds and Networlds. A SimWorld combines an AgentVector with a CellMatrix that provides a landscape. The Networld component uses a NodeNetwork for the same purpose. The ''SIR'' model is an example of an agent vector, with agents moving about an open space in three possible states, Susceptible, Infected, and Recovered. The ''Antz'' model is a more complicated model that uses both an agent vector and a cell matrix in order to simulate how ants collect food and leave a path for other ants to follow in order to find the same food. | ||
Numerus has a lot of tools that make agent based models simpler and more robust. In particular, it is very easy to have access to all agents and cells from each individual agent, and to incorporate a wide variety of local and global effects. It also makes it simple to set up multiple Sim Worlds in order to see various outcomes simultaneously. It is also built on arrays and methods, which makes it simple to work on a small level to tweak the model to the user’s liking. On the other hand, the visual side of Numerus makes it so that it is easy to quickly and efficiently set up the shell of an agent based model and immediately get down to the more important details involved in the model. A savvy Numerus programmer will begin an agent based model visually and slowly transition over to handling the methods and functions in a more programming heavy reference frame. | Numerus has a lot of tools that make agent based models simpler and more robust. In particular, it is very easy to have access to all agents and cells from each individual agent, and to incorporate a wide variety of local and global effects. It also makes it simple to set up multiple Sim Worlds in order to see various outcomes simultaneously. It is also built on arrays and methods, which makes it simple to work on a small level to tweak the model to the user’s liking. On the other hand, the visual side of Numerus makes it so that it is easy to quickly and efficiently set up the shell of an agent based model and immediately get down to the more important details involved in the model. A savvy Numerus programmer will begin an agent based model visually and slowly transition over to handling the methods and functions in a more programming heavy reference frame. | ||
--> | |||
==Network Based Models in Numerus== | ==Network Based Models in Numerus== | ||
A network generalizes the topology of a spatial landscape. The Numerus ''NodeNetwork'' component is a container for an array of nodes, each of which is a Capsule instance. These nodes, together with a set of directed arcs, form a [//en.wikipedia.org/wiki/Graph_(discrete_mathematics) mathematical graph]. The NodeNetwork provides operators that inform the node about its arc-based topological neighborhood. A NodeNetwork can be paired with an AgentVector to create a ''NetWorld'' (analogous to a SimWorld) in which the agents move from node to node through the network. | |||
<!-- | |||
==Chip Basics== | ==Chip Basics== | ||
As the [[Glossary|Numerus Glossary]] states, a '''Chip''' is a Container component which contains a single '''Capsule''' instance. A '''Capsule''' is a prototype for a simulation unit. It contains base components and may contain other chips, inputs, and / or outputs. These definitions may appear a bit vague or broad, however, that is simply because '''Chips''' and '''Capsules''' are widely used in a variety of ways within Numerus. | As the [[Glossary|Numerus Glossary]] states, a '''Chip''' is a Container component which contains a single '''Capsule''' instance. A '''Capsule''' is a prototype for a simulation unit. It contains base components and may contain other chips, inputs, and / or outputs. These definitions may appear a bit vague or broad, however, that is simply because '''Chips''' and '''Capsules''' are widely used in a variety of ways within Numerus. | ||
| Line 47: | Line 63: | ||
*Get a run through of NumerusMB's GUI [[Frames, Menus, Toolbars|here]]. | *Get a run through of NumerusMB's GUI [[Frames, Menus, Toolbars|here]]. | ||
--> | |||
=Notes= | =Notes= | ||
<references/> | <references/> | ||
Latest revision as of 17:47, 9 June 2018
In Modeling 101 you were introduced to the various paradigms and concepts of computational modeling. Here we discuss how these are realized in Numerus.
It is important to understand the structure of the Numerus platform in order to implement powerful and complex dynamical system and spatial, agent-based and network models. Numerus provides an impressive range and versatility of components to effectively design and execute models. In addition, Numerus has the capability to implement designs using specialized components. To utilize Numerus's capabilities we must first understand the basics of Numerus's Capsule-based architecture.
Numerus Simulation
A Numerus model is a program that drives a run-time simulation. The simulation is initialized to some initial state and executes using a clock to delineate time steps. At each time step the simulation's current state is used to compute its next state. Intermediate results may be recorded as the simulation progresses, with final results recorded upon termination. State transitions may be deterministic or stochastic (using a pseudo-random number generator).
The model is comprised of components organized into a groups called Capsules forming a hierarchical structure. The simplest model consists of a single Capsule and is analogous to a system dynamics model. The use of special containers to form the hierarchy give rise to Numerus's additional expressiveness in forming spatial, agent-based and network models.
Capsule, Chip, Submodel, Programming
Numerus introduces a modular design feature called a Capsule. A Capsule is a model space containing interacting components such as Stocks, Flows, Terms, Commands, etc. Each Numerus model is comprised of one or more Capsule instances[1] in a hierarchical relationship. A Capsule instance called main (which can only have one instance) is at the root of this hierarchy. Instances of other Capsules can be inserted into the model space of a given Capsule using special container components. The simplest of these is called a Chip and it contains a single instance of another Capsule. The entire hierarchy of Capsules rooted at the Chip is called a submodel [2]. Other containers are used to create spatial, agent-based and network architectures and will be discussed below.
This figure shows a model built out of 4 Capsules. In (a) we observe the dependency hierarchy: Capsule Main requires Capsules C1 and C2. C1 requires C2 but also requires C3. In (b) we see that in the structural hierarchy Main has 2 instances of C1 and 1 instance of C2; consequently the model uses 2 instances of C1, 3 instances of C2 and 2 instances of C3.
Each component inserted into a Numerus model must be "programmed" to describe its relationship to other components and to the model as a whole. This programming uses the language NovaScript, which is the JavaScript language extended with some special features. In simple models, most components represent values, in which case the program is an algebraic expression defining the value. In more advanced models some programs may make use of additional algebraic tools in the language. Along with the tools provided by JavaScript, Numerus comes equipped with special primitive operations and constants (referred to, respectively, as primops and primprops) that address the needs of modeling. After determining the Capsule structure and selecting the components for each Capsule, component programming is the ultimate "glue" that solidifies your model. It will be discussed and illustrated throughout this user guide.
Dynamical Systems Models in Numerus
This user guide assumes the reader is familiar with basic system dynamics (SD) methodology. One place to start is here.
Numerus implements several different types of state component, extending the SD concept of stock. State component, like stocks, are distinguished in SD modeling by the fact that the state values computed at one time step are used in the next, (as opposed to functional components like Terms[3], whose values at each time step are derived entirely from the current state.) The four state components are:
- Stock
- The standard SD state component to which one or more Flows can be attached. The Stock's value is updated at each time step based on the values of its Flows.
- Stock+Flow
- A version of the Stock component with a single incoming Flow. Appropriate for translating a differential equation into a model element.
- Sequence
- A special type of Stock with a single incoming Flow. The Flow value replaces rather than adds to the Sequence's value.
- Store
- A container for a value that is modified by code. No state change takes place unless required by the code. A Store acts like a global variable for the model.
Flows in Numerus follow standard rules for system dynamics: they control the movement of value to and from Stocks.
Numerus Terms play several roles, all of which involve computing or delivering a value. A pure Term simply computes a value using the values of other components in the model. A constant Term computes this value only once and maintains it throughout the simulation. A Graph Function Term is derived from a user-defined graph. In Pins and Out Pins are used with capsule chips and described elsewhere. A Spy displays its value on the runtime dashboard. An External Term is derived from input data and is described in detail elsewhere.
Spatial Models in Numerus
Spatial modeling introduces into the model an awareness of position in 2 or 3 dimensions. In Numerus this capability is encapsulated using a component called a CellMatrix. A CellMatrix is an array of cells forming a geometric lattice. The lattice can have either a cartesian or hexagonal topology[4]. Each cell is comprised of a capsule instance extended with special operators that inform the cell of its topological properties. A well-known example of a 2-dimensional cartesian spatial model of this type is Conway's Game of Life. The cells in this model are in one of two states (“alive” or “dead”), and state transition depends on the state of a cell's 8 neighbors. In Numerus, a Life cell is Capsule with a single Sequence component representing its state. Special primitive operators allow a cell to query the state of its neighbors to determine its own state transition.
Agent Based Models in Numerus
In Numerus an agent is a Capsule instance that exists at some location in a 2 dimensional cartesian or hexagonal spatial landscape. The agent population may be fixed or may vary dynamically over the course of the simulation. Numerus uses an array container called an AgentVector to manage the set of agents. In addition to the state created by its capsule, an agent is also assigned a pair of variables that serve as its xy coordinates in the spatial landscape. As an agent moves the AgentVector adjusts its spatial coordinates accordingly. The AgentVector also manages the population of models with dynamic agent populations. Special operators allow the agent to manage its movement, determine population changes through births and deaths, and detect and query other agents within a specified distance.
If an AgentVector is paired with a CellMatrix, it forms a component called a Simulation World (or SimWorld). In this case the agent landscape is identified with the landscape determined by the CellMatrix, and an agent's location coordinates refer to corresponding cell coordinates. Additional operators facilitate interaction between agents and cells. A similar pairing can be made between agents and networks as described below.
Network Based Models in Numerus
A network generalizes the topology of a spatial landscape. The Numerus NodeNetwork component is a container for an array of nodes, each of which is a Capsule instance. These nodes, together with a set of directed arcs, form a mathematical graph. The NodeNetwork provides operators that inform the node about its arc-based topological neighborhood. A NodeNetwork can be paired with an AgentVector to create a NetWorld (analogous to a SimWorld) in which the agents move from node to node through the network.
Notes
- ↑ Note the distinction between Capsule and Capsule instance. A Capsule describes a model space containing interacting components. A Capsule instance represents one specific use of that Capsule. A Capsule may have many instances in a project. Capsule and Capsule instance may be used interchangeably when there is no possible ambiguity.
- ↑ The only restriction is on circularity: no submodel can contain a Capsule that contains that submodel.
- ↑ In Stella these are called 'Converters', and in Vensim they are 'Variable-Auxiliary/Constants'
- ↑ Hexagonal topology is limited to 2 dimensions