NumML Language Reference

What is NumML?

NumML is a small, domain-specific language (dsl) for coding SD models and configuring the UI of a Numerus WebKit (NWK) site. It is used in URAM models and in the Configuration Window. This document serves as reference for NWK authors and users wishing to use NumML in their designs.

Overview

NumML serves two purposes: (1) to specify a system dynamics (SD) model program; and (2) to override the factory settings configuration for inputs, displays, and model operation. The choice of operator in an NumML statement, from the two described in the next section, respectively determines its purpose. To specify an SD program, NumML has special operators for defining a differential or difference equation with initial values. There are also primitive operators (primops) to supply random values and compute useful mathematical functions. To override factory settings there are operators to configure properties of input and display components, and to fix integration parameters. Finally, there are operators to configure properties of the analytical platforms. Currently there is only 1 of these (sensitivity analysis), and NumML will be extended as more such platforms become available.

NumML Operators

NumML uses Javascript syntax extended with 2 infix operators (@= and #=) that are not recognized as meaningful to Javascript. NWK uses a Javascript parser extended to accept these operators to analyze NumML code and respectively generate code or change the value of specific configuration parameters. Each NumML statement has the form:

LHS @= RHS
LHS @= RHS;
LHS @# RHS
LHS @# RHS;

with slightly different rules for what is allowed on each side of the operator. In discussing NumML syntax we use the following terminology:

Language Categories

Constant

Either a string constant enclosed in single or double quotes ('Infection Stats', "SIR Model"") or a number in decimal (3.1415) or scientific notation (3.14159e5).

Identifier

Equivalent of a Javascript variable such as Sigma, N, beta, etc.

Unary Expression

An unary operator modifying a term, such as -10 or -Sigma.

Call Expression

A function name followed by a comma-separated sequence of arguments enclosed in parentheses. The function name must be an identifier; the arguments can be any list of terms.

Term

Either a constant, identifier, unary expression, or a call expression using one of the following function names, which differ for @= and @#. These functions are called primops and are discussed below.

@=:

choose, multinomial, binomial, poisson, flip, normal, irandom, random, PI, PI2, Pi2, Pi34, degToRad, radToDeg, cos, sin, tan, acos, asin, atan, atan2, cosh, sinh, tanh, acosh, asinh, atanh

@#

legend, phase, title, statDat, statParam, integration,statRuns, statLo, statHi, min, max, step, xlabel, ylabel, interval

Computational Expression

A single term or a sequence of terms connected using arithmetic operators +, -, * /, or any other legal Javascript operators.

Array

A comma-separated sequence of terms enclosed in square brackets; e.g., [Sigma, foo(1,2,3), 15.123e3].

Syntax Rules for @=

LHS can be:

An identifier

A call expression of the form:

deriv(ident)

initial(ident)

update(ident1, ident2, ...)

these are discussed below.

RHS can be

A computational expression when LHS is either deriv, initial or an identifier.

An identifier when LHS is update

Examples


deriv(S) @= -beta * S * I / N
deriv(I) @= beta * S * I / N - sigma * I
deriv(R) @= sigma * I

initial(S) @= N - I0
initial(I) @= I0
initial(R) @= 0

update(S,I,R) @= mainGraph

N @= Param1
beta @= Param2
I0 @= Param3
sigma @= Param4


Semantic Rules for @=

• deriv(Arg) asserts a that the RHS equation is the time derivative of Arg
• initial(Arg) asserts that the RHS is the initial value of Arg
• update(Arg1, Arg2, ...) asserts that Arg₁, Arg₂, ... should be downloaded to the output component with ID of the RHS. The arguments should match the legend assigned to the output component

An identifier appearing on the LHS is defined by the expression on the RHS.

Syntax Rules for #=

LHS can be

An identifier

An array of identifiers

RHS can be

A constant, primop, or array of primops

Examples:


mainGraph #= [legend(S,I,R), title("SIR Model")]
statsGraph #= title("Infection Stats")
statsGraph #= [statDat(I),statParam(Beta),statRuns(12),statLo(3.4),statHi(4.5)]
Param1 #= [legend(N),max(1000000),step(1000)]
Param2 #= [legend(Beta),max(10),step(0.1)]
Param3 #= [legend(I0),max(10),step(0.1)]
Param4 #= [legend(Sigma),max(10),step(0.1)];
[Param5, Param6] #= legend("");


Semantic Rules for #=

• Identifiers on the LHS reference component IDs or parameters such as dt
• Constants on the RHS are only used with parameters and assign values to them.
• Primops on the RHS are only used with component IDs and define attributes such as legend, max value, etc.
• Arrays on either side "multiply out" to as sequence of statements and are there for convenience.

Primops for @=

Random Number Generation

choose(size)

Randomly picks a number from 0 to size-1 with uniform probability.

choose(p0, p1, ... pn-1)

If the p_i sum to 1, then this function randomly picks a number from 0 to n-1 with the indicated probabilities. If the p_i sum to less than 1, then the function returns n with probability 1 - Σ p_i.

flip(p)

Returns 1 with probability p; 0 otherwise

binomial(n, p)

Returns the sum of n independent flip(p) calls.

multinomial(N, p0, p1, ... pn-1)

Performs N independent choose(p₀, p₁, ... p_n-1) calls and returns a vector of n (or n+1) values (v₀, v₁, ...) where v_i is the number of times i was selected.

poisson(lambda)

Returns a random value 0, 1, ... distributed using the Poisson distribution with density lambda.

normal(m, s)

Returns a random value distributed using a Gaussian distribution with mean m and standard deviation s.

irandom(y)

Returns a random integer between 0 and y.

irandom(x, y)

Returns a random integer between x and y.

Trigonometric Functions

cos, sin, tan, acos, asin, atan, atan2, cosh, sinh, tanh, acosh, asinh, atanh

Note: (atan2 y x) is (atan y/x) extended to handle the case where x == 0.

Constants

PI, PI2, Pi2, Pi34

Respectively, π, 2π, π/2, 3π/4

degToRad

π/180

radToDeg

180/π

Primops for @#

Assigned to runtime graphs and displays:

legend

title

xlabel

ylabel

interval (between plots)

Assigned to input sliders

legend

min

max

step

Integration Control

dt

integration (RK4 or Euler)

Sensitivity Analysis Platform

statParam

Parameter varied by sensitivity test

statDat

Value to be graphed

statRuns

Number of runs

StatLo, StatHi

Testing boundaries