# Difference between revisions of "Primitive Operators and Properties"

(→Clocked Chip Primops) |
(→Primops) |
||

Line 175: | Line 175: | ||

;BLOCK(n) | ;BLOCK(n) | ||

;WBLOCK(n) | ;WBLOCK(n) | ||

− | :Returns: a list (array) of coordinate objects (i.e., containing row and col properties) comprising the square block of cells n units away from the caller or less. (WBLOCK is the “wrapped” version, which treats the surface as a torus). | + | :'''Returns''': a list (array) of coordinate objects (i.e., containing row and col properties) comprising the square block of cells ''n'' units away from the caller or less. ('''WBLOCK''' is the “wrapped” version, which treats the surface as a torus). |

;CELL(row, col) | ;CELL(row, col) | ||

;CELL(coords) | ;CELL(coords) | ||

− | :Returns the state object for the cell at the given coordinates, which may be passed either as separate parameters or in a coords object. The | + | :'''Returns''' the state object for the cell at the given coordinates, which may be passed either as separate parameters or in a coords object. The fields of the state object bind each of the Stocks, Terms and Flows in the cell to the current value of the corresponding component. |

;CELLS() | ;CELLS() | ||

− | :Returns the entire matrix (i.e., 2-dimensional array) of state objects for the CellMatrix. | + | :'''Returns''' the entire matrix (i.e., 2-dimensional array) of state objects for the CellMatrix. |

+ | |||

+ | CELLS()[row][col] == CELL(row, col). | ||

− | |||

;CELL_VALUE(row, col, comp) | ;CELL_VALUE(row, col, comp) | ||

;CELL_VALUE(coords, comp) | ;CELL_VALUE(coords, comp) | ||

− | :comp is a String naming a Stock, Flow or Term in the cell capsule. | + | :''comp'' is a String naming a Stock, Flow or Term in the cell capsule. |

− | :Returns: the current value of that component in the cell with the given coordinates. | + | :'''Returns''': the current value of that component in the cell with the given coordinates. |

+ | |||

+ | CELL VALUE(row, col, comp) == CELL(row, col)[comp] | ||

− | |||

;RING(n) | ;RING(n) | ||

;WRING(n) | ;WRING(n) | ||

− | :Returns: a list (array) of coordinate objects (i.e., containing row and col properties) for all cells comprising the square exactly n units away from the caller. (WRING is the “wrapped” version, which treats the surface as a torus). | + | :'''Returns''': a list (array) of coordinate objects (i.e., containing row and col properties) for all cells comprising the square exactly ''n'' units away from the caller. ('''WRING''' is the “wrapped” version, which treats the surface as a torus). |

;WRAP(row, col) | ;WRAP(row, col) | ||

;WRAP(coords) | ;WRAP(coords) | ||

:Performs a “wraparound” of the coordinates if they exceed the size of the matrix (or are negative). | :Performs a “wraparound” of the coordinates if they exceed the size of the matrix (or are negative). | ||

− | + | :'''WRAP(row, col)''' returns an array containing the new row and column; | |

− | + | :'''WRAP(coords)''' returns a Coords object containing the new row and column. | |

− | + | ||

===Hexagonal Primops=== | ===Hexagonal Primops=== |

## Revision as of 20:19, 12 December 2014

**The Properties/Primops list is correct as of Release 12, which became available on March 31, 2014**

**Primops added subsequently are identified by the version number in which they first appeared.**

Nova supports a large set of primitives divided into properties and primitive operators, or primops.

A **property** is an identifier assigned a value at the beginning of a simulation run which is not expected to change. For example, the rows and cols properties of a CellMatrix are fixed at the start of a run and don’t change. A special type of property, called an state object, is used to look up the current values of components.

**Primops** are functions of zero or more arguments. Some primitives may be used without restriction; others make sense only in specific contexts; for example rows and cols are only useful in spatial contexts such as CellMatrices, AgentVectors and SimWorlds.

Here are the properties and primops supported by the current Nova implementation, organized by type and area of applicability. All properties begin with a lower case letter, state objects begin with a capital letter, and primops are composed entirely of capital letters. Primops are always functions, and therefore require an argument list (even if empty) in order to be invoked.

Notation: *x, y* represent values (numbers or string constants or expressions); *fn* represents a Javascript function; *exp* represents a string expression; [*x, y*] represents one or more optional arguments.

## Universal Properties and Primops

These can be used in any expression in any component.

### Properties

- Self
- The state object of the enclosing simulator (Capsule, CellMatrix, etc.) Used to look up component values (see the section on state objects, coming soon).

### Control Primops

- ALERT(s)
- Displays message s in a dialog box.
- COUNT(fn, l)
*fn*is a boolean function of one argument and a*l*is list.**Returns**:**COUNT(f, l)**applies*f*to each element of*l*and returns the number of times the result is*true*.- DELAY(comp, x, [y])
**Returns**: the value of component comp delayed by*x*time units. Comp is a string naming a stateful component (i.e., stock, variable or sequence).- Optional
*y*is returned if the current time is less than*x*. If*y*is omitted then 0 is returned. - PULSE(amount, start, interval)
**Returns**: amount when current time is*start*,*start + interval*,*start + 2*interval*, etc.; 0 otherwise- STEP(x, y)
**Returns**: the value of*x*if the current time is*y*or greater; 0 otherwise.- TOTAL(fn, l)
*fn*is a numerical function of one argument and a*l*is list.**Returns**:**TOTAL(fn, l)**applies*fn*to each element of*l*and returns the sum of the results.

### Convenience Primops

These primops perform useful functions that could otherwise be programmed.

- FLIP(p)
- Simulates a Bernoulli trial.
**Returns**:*true*with probability*p*and*false*with probability*1-p*.*Available as of release 12.1*.

### Input/Output Primops

- BASEDIR()
**Returns**: the current model directory.

- LOAD(l)
*l*is a list of JavaScript or NovaScript filenames contained in the current model directory. Each is loaded into the runtime system. Should be part of simulation initialization.

In each of the following *path* designates a textfile. if *path* begins with “/” it is treated as an absolute pathname; otherwise it is treated as relative to the current model directory.

- OPENREAD(path)
- Opens
*path*for reading and returns a Java`BufferedReader`

object. The latter contains methods read and readLine to perform input. See http://docs.oracle.com/javase/7/docs/api/java/io/BufferedReader.html for complete details.

- OPENWRITE(path)
- Opens path for writing and returns a Java
`PrintWriter`

object. The latter contains methods`print`and`println`to perform output. See http://docs.oracle.com/javase/7/docs/api/java/io/PrintWriter.html for complete details.

- READFILE(path)
**Returns**: the content of the file path as a string.

### Mathematical Primops

- BINOMIAL(n, p)
*n*is an integer;*0 ≤ p ≤ 1***Returns**: a random number from the binomial distribution with*n*trials and success probability*p*.

- COS(x)
**Returns**: the trigonometric cosine of*x*.

- COSWAVE(x, y)
**Returns**:*x*cos(2πt/y),*where*t*is the current time.

- DERIVN(fn, n)
**Returns**: the value of the*nth*derivative of*fn*at the current time, with precision based on the value of*dt*.

- DISTANCE(x0, y0, x1, y1)
**Returns**: Euclidean distance between points (*x0, y0*) and (*x1, y1*).

- Math.XXX
- The JavaScript Math functions and constants; see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math.

- NORMAL(x, y)
**Returns**: a random number from the normal distribution with mean x and standard deviation y.

- POISSON(lambda)
**Returns**: a random number from the Poisson distribution with density lambda.

- RANDOM()
**Returns**: a uniformly distributed random number between 0 and 1.

- SEED(x)
**Returns**: nothing; sets the seed of the random number generator. Should be part of simulation initialization.

- SIN(x)
**Returns**: the trigonometric sin of*x*.

- SINWAVE(x, y)
**Returns**:*x*sin(2πt/y)*, where*t*is the current time.

- UNIFORM(x, y)
**Returns**: a uniformly distributed random variable between*x*and*y*.

### Matrix Primops

- COLUMNSPLIT(tab)
*tab*is a 2-dimensional array derived from a table, where the first row contains column headers.**Returns**: an object in which each property name is a column header with property value an array comprising the corresponding column.

- CSVTOMAT(csv)
*csv*is a string where line is a comma separated sequence of values.**Returns**: the matrix in which each row corresponds to a line in*csv*.

- ROWSTOOBJS(tab)
*tab*is a 2-dimensional array derived from a table, where the first row contains column headers.**Returns**: an array of objects, one for each non-header row. In each object properties are column headers bound to the entry for that column in the corresponding row.

- TRANSPOSE(mat)
*mat*is a matrix (i.e. 2-dimensional array)**Returns**: the transpose of*mat*.

### Simulation Primops

- CLOCK()
**Returns**the current clock as an object.

- DT()
**Returns**: current delta value (*dt*).

- SIMSTART()
- SIMEND()
- SIMMETHOD()
**Returns**: simulation start time, end time and integration method, respectively.

- TIME()
**Returns**: current simulation time.

### Miscellaneous Primops

- RECONFIGURE(agg, map)
*agg*must refer either to an AgentVector or SimWorld, and*map*must be an object with property names matching initializable components in the*agg*agent capsule (i.e., properties or stocks). Each property name must be bound to an array of values, with each array at least as long a the initial agent count in*agg*. RECONFIGURE reconfigures the initial AgentVector in*agg*by rebinding each of the properties named in*map*, matching the*agg*agent vector to the values in the array bound to that property in*map*.

- _.XXX
- The underscore.js library of useful functions. See http://underscorejs.org.

## Clocked Chip Primops

The following may only be used by a capsule in a Clocked Chip.

- SUPERCLOCK()
**Returns**: the clock associated with the container of the Clocked Chip.

- SUPERTIME()
**Returns**: the model time of the container of the Clocked Chip.

## Cell Properties and Primops

The following may only be used by capsules contained in a CellMatrix, or cell capsule in a SimWorld. *row* and *col* are integers representing row-column coordinates within the CellMatrix. *coords* is a `Coords`

object As of Release 12 all primops expecting coordinate pairs as parameters can either be called with separate row-column arguments or with a `Coords`

object.

Cartesian coordinates will generally be automatically wrapped; i.e. if the coordinate space has dimension *rows* x *cols*, then a negative value for *row* or *col* is treated respectively as *rows + row* and *cols + col*. Values that exceed the dimensions respectively become *row – rows* and *col – cols.* This type of space is topologically equivalent to a torus.

Neighborhood function **BLOCK** and **RING** come in two versions, one that includes wrapping (**WBLOCK** and **WRING**), and one that treats the edges as boundaries (**BLOCK** and **RING**).

### Properties

- coords
- Object whose row and col properties respectively reference the caller’s row and column coordinates within the CellMatrix.

- rows
- cols
- Bound to the total number of rows and columns, respectively.

- Super
- The state object of the enclosing container.

### Primops

- BLOCK(n)
- WBLOCK(n)
**Returns**: a list (array) of coordinate objects (i.e., containing row and col properties) comprising the square block of cells*n*units away from the caller or less. (**WBLOCK**is the “wrapped” version, which treats the surface as a torus).

- CELL(row, col)
- CELL(coords)
**Returns**the state object for the cell at the given coordinates, which may be passed either as separate parameters or in a coords object. The fields of the state object bind each of the Stocks, Terms and Flows in the cell to the current value of the corresponding component.

- CELLS()
**Returns**the entire matrix (i.e., 2-dimensional array) of state objects for the CellMatrix.

CELLS()[row][col] == CELL(row, col).

- CELL_VALUE(row, col, comp)
- CELL_VALUE(coords, comp)
*comp*is a String naming a Stock, Flow or Term in the cell capsule.**Returns**: the current value of that component in the cell with the given coordinates.

CELL VALUE(row, col, comp) == CELL(row, col)[comp]

- RING(n)
- WRING(n)
**Returns**: a list (array) of coordinate objects (i.e., containing row and col properties) for all cells comprising the square exactly*n*units away from the caller. (**WRING**is the “wrapped” version, which treats the surface as a torus).

- WRAP(row, col)
- WRAP(coords)
- Performs a “wraparound” of the coordinates if they exceed the size of the matrix (or are negative).
**WRAP(row, col)**returns an array containing the new row and column;**WRAP(coords)**returns a Coords object containing the new row and column.

### Hexagonal Primops

The following should only be used if the CellMatrix is in hexagonal mode.

- HEXRING(n)
- Returns: a list (array) of coordinate objects (i.e., containing row and col properties) for all cells comprising the hexagon exactly n units away from the caller.

- HEXBLOCK(n)
- Returns: a list (array) of coordinate objects (i.e., containing row and col properties) comprising the hexagonal block of cells n units away from the caller or less.

- HEXPATH(dir, dist)
- Returns: a list of coordinates comprising the path of length dist in the direction indicated by dir. Directions are denoted by compass directions; i.e., “N”, “NE”, “SE”, “S”, “SW”, “NW”.

### Convenience Primops

These primops perform useful functions that could otherwise be programmed.

- CELLBLOCK(n)
- CELLWBLOCK(n)
- CELLRING(n)
- CELLWRING(n)
- Returns: a list of state objects for all cells in the ring or block (wrapped or otherwise) specified by n. Available as of Nova 12.1.

- COUNT_CELLS(l, comp, value)
- l is a list of cell state objects, comp is a string naming a component in those cells (stock, term, flow, etc.), and value is any JavaScript data element.
- Returns: Returns the number of objects in l for which the current value of comp is value. Available as of Nova 12.1.

- ALL_CELLS(l, comp, value)
- NO_CELL(l, comp, value)
- SOME_CELL(l, comp, value)
- l is a list of cell state objects, comp is a string naming a component in those cells (stock, term, flow, etc.), and value is any JavaScript data element.
- Returns: Respectively returns true if for all, none or some state objects in l the current value of comp is value; false otherwise. Available as of Nova 12.1.