# Modeling Syntax Reference¶

## Introduction¶

The VentureScript modeling language is the language in which model expressions, namely the arguments to the assume, observe, and predict instructions are written. The VentureScript inference language is the same language, but with a few additional predefined procedures and special forms.

The VentureScript modeling language is a pure-functional dialect of JavaScript. The major differences from JavaScript are

• No mutation (only inference can effect mutation, and that only in a restricted way)
• A spare set of predefined procedures and syntactic constructs
• Several constructs relating specifically to probabilistic modeling or functional programming
• Predefined procedures for random choices according to various distributions.

## Special Forms¶

The special forms in VentureScript are as follows:

quote(<datum>)

Literal data.

The datum must be a VentureScript expression. As in Scheme, a quote form returns a representation of the given expression as VentureScript data structures.

proc(<param>, ...) { <body> }

Construct a procedure.

The formal parameters must be VentureScript symbols. The body must be a VentureScript expression. The semantics are like function in JavaScript – produces an anonymous function that may read its lexical environment.

Creation of variable arity procedures is not yet supported.

if (<predicate>) { <consequent> } else { <alternate> }

Branch control.

The predicate, consequent, and alternate must be VentureScript expressions.

(cond (<predicate> <expression>) ...)

Multiple branching.

Each predicate and each expression must be a VentureScript expression. If none of the predicates match, returns nil. The above is the parsed form; no special concrete syntax for cond is provided.

and(<exp1>, <exp2>)

Short-circuiting and.

or(<exp1>, <exp2>)

Short-circuiting or.

(let ((<param> <exp>) ...) <body>)

Evaluation with local scope.

Each parameter must be a VentureScript symbol. Each exp must be a VentureScript expression. The body must be a VentureScript expression. The semantics are as JavaScript’s variable declaration and Scheme’s let*: each exp is evaluated in turn, its result is bound to the param, and made available to subsequent exp s and the body.

The concrete syntax is:

<param> = <exp>;
...
<body>

(letrec ((<param> <exp>) ...) <body>)

Evaluation with local scope.

Each parameter must be a VentureScript symbol. Each exp must be a VentureScript expression that evaluates to a procedure. The body must be a VentureScript expression. The semantics are as Scheme’s letrec (TODO). This is useful for defining locally-scoped mutually recursive procedures.

No concrete syntax is provided (yet).

quasiquote(<datum>)

Data constructed by template instantiation.

If the datum contains no unquote expressions, quasiquote is the same as quote. Otherwise, the unquoted expressions are evaluated and their results spliced in. This is particularly useful for constructing model program fragments in inference programs – so much so, that the modeling inference SPs automatically quasiquote their model arguments.

TODO: Nested quasiquotation does not work properly: all unquoted expressions are evaluated regardless of quasiquotation level.

In addition, macros intended for the inference programming language are (as of this writing) expanded in expressions of the modeling language as well. The results are generally not useful, so it’s appropriate to treat those as reserved words when writing models:

## Built-in Procedures¶

The following modeling procedures are built in to Venture (as of the generation date of this manual):

Return type:

add returns the sum of all its arguments

Deterministic

sub(<number>, <number>)
Return type:

sub returns the difference between its first and second arguments

Deterministic

mul(<number>, ...)
Return type:

mul returns the product of all its arguments

Deterministic

div(<number>, <number>)
Return type:

div returns the ratio of its first argument to its second

Deterministic

int_div(<number>, <number>)
Return type:

div returns the integer quotient of its first argument by its second

Deterministic

int_mod(<number>, <number>)
Return type:

mod returns the modulus of its first argument by its second

Deterministic

min(<number>, <number>)
Return type:

min returns the minimum value of its arguments

Deterministic

floor(<number>)
Return type:

floor returns the largest integer less than or equal to its argument (as a VentureNumber)

Deterministic

sin(<number>)
Return type:

Returns the sin of its argument

Deterministic

cos(<number>)
Return type:

Returns the cos of its argument

Deterministic

tan(<number>)
Return type:

Returns the tan of its argument

Deterministic

hypot(<number>, <number>)
Return type:

Returns the hypot of its arguments

Deterministic

exp(<number>)
Return type:

Returns the exp of its argument

Deterministic

log(<number>)
Return type:

Returns the log of its argument

Deterministic

pow(<number>, <number>)
Return type:

pow returns its first argument raised to the power of its second argument

Deterministic

sqrt(<number>)
Return type:

Returns the sqrt of its argument

Deterministic

atan2(<number>, <number>)
Return type:

atan2(y,x) returns the angle from the positive x axis to the point x,y. The order of arguments is conventional.

Deterministic

negate(<number>)
Return type:

negate(x) returns -x, the additive inverse of x.

Deterministic

abs(<number>)
Return type:

abs(x) returns the absolute value of x.

Deterministic

signum(<number>)
Return type:

signum(x) returns the sign of x (1 if positive, -1 if negative, 0 if zero).

Deterministic

eq(<object>, <object>)
Return type:

eq compares its two arguments for equality

Deterministic

gt(<object>, <object>)
Return type:

gt returns true if its first argument compares greater than its second

Deterministic

gte(<object>, <object>)
Return type:

gte returns true if its first argument compares greater than or equal to its second

Deterministic

lt(<object>, <object>)
Return type:

lt returns true if its first argument compares less than its second

Deterministic

lte(<object>, <object>)
Return type:

lte returns true if its first argument compares less than or equal to its second

Deterministic

real(<atom>)
Return type:

real returns the identity of its argument atom as a number

Deterministic

atom_eq(<atom>, <atom>)
Return type:

atom_eq tests its two arguments, which must be atoms, for equality

Deterministic

probability(<probability>)
Return type:

probability converts its argument to a probability (in direct space)

Deterministic

not(<bool>)
Return type:

not returns the logical negation of its argument

Deterministic

xor(<bool>, <bool>)
Return type:

xor(x,y) returns true if exactly one of x and y is true

Deterministic

is_number(<object>)
Return type:

is_number returns true iff its argument is a <number>

Deterministic

is_integer(<object>)
Return type:

is_integer returns true iff its argument is a <integer>

Deterministic

is_probability(<object>)
Return type:

is_probability returns true iff its argument is a <probability>

Deterministic

is_atom(<object>)
Return type:

is_atom returns true iff its argument is a <atom>

Deterministic

is_boolean(<object>)
Return type:

is_boolean returns true iff its argument is a <bool>

Deterministic

is_symbol(<object>)
Return type:

is_symbol returns true iff its argument is a <symbol>

Deterministic

is_procedure(<object>)
Return type:

is_procedure returns true iff its argument is a <SP <object> ... -> <object>>

Deterministic

list(<object>, ...)
Return type:

list returns the list of its arguments

Deterministic

pair(<object>, <object>)
Return type:

pair returns the pair whose first component is the first argument and whose second component is the second argument

Deterministic

is_pair(<object>)
Return type:

is_pair returns true iff its argument is a <pair <object> <object>>

Deterministic

first(<pair <object> <object>>)
Return type:

first returns the first component of its argument pair

Deterministic

rest(<pair <object> <object>>)
Return type:

rest returns the second component of its argument pair

Deterministic

second(<pair <object> <pair <object> <object>>>)
Return type:

second returns the first component of the second component of its argument

Deterministic

to_list(<sequence <object>>)
Return type: >

to_list converts its argument sequence to a list

Deterministic

zip(<list>, ...)
Return type: >

zip returns a list of lists, where the i-th nested list contains the i-th element from each of the input arguments

Deterministic

dict(<list k>, <list v>)
Return type:

dict returns the dictionary mapping the given keys to their respective given values. It is an error if the given lists are not the same length.

Deterministic

is_dict(<object>)
Return type:

is_dict returns true iff its argument is a <dict>

Deterministic

lookup(<mapping k v>, k)
Return type: v

lookup looks the given key up in the given mapping and returns the result. It is an error if the key is not in the mapping. Lists and arrays are viewed as mappings from indices to the corresponding elements. Environments are viewed as mappings from symbols to their values.

Deterministic

contains(<mapping k v>, k)
Return type:

contains reports whether the given key appears in the given mapping or not.

Deterministic

size(<mapping k v>)
Return type:

size returns the number of elements in the given collection (lists and arrays work too)

Deterministic

take(<integer>, <sequence k>)
Return type:

take returns the requested number of elements from the beginning of the given sequence, as another sequence of the same type.

Deterministic

debug(<symbol>, k)
Return type: k

Print the given value, labeled by a Symbol. Return the value. Intended for debugging or for monitoring execution.

Deterministic

value_error(<object>)
Return type:

deterministic value_error

Deterministic

array(<object>, ...)
Return type:

array returns an array initialized with its arguments

Deterministic

vector(<number>, ...)
Return type: >

vector returns an unboxed numeric array initialized with its arguments

Deterministic

is_array(<object>)
Return type:

is_array returns true iff its argument is a <array>

Deterministic

is_vector(<object>)
Return type:

is_vector returns true iff its argument is a <array <number>>

Deterministic

to_array(<sequence <object>>)
Return type:

to_array converts its argument sequence to an array

Deterministic

to_vector(<sequence <number>>)
Return type: >

to_vector converts its argument sequence to a vector

Deterministic

matrix(<list <list <number>>>)
Return type:

matrix returns a matrix formed from the given list of rows. It is an error if the given list is not rectangular.

Deterministic

is_matrix(<object>)
Return type:

is_matrix returns true iff its argument is a <matrix>

Deterministic

simplex(<probability>, ...)
Return type:

simplex returns the simplex point given by its argument coordinates.

Deterministic

is_simplex(<object>)
Return type:

is_simplex returns true iff its argument is a <simplex>

Deterministic

arange(<integer>[, <integer>])
Return type: >

arange([start], stop) returns an array of n consecutive integers from start (inclusive) up to stop (exclusive).

Deterministic

fill(<integer>, <number>)
Return type: >

fill(n, x) returns an array with the number x repeated n times

Deterministic

linspace(<number>, <number>, <count>)
Return type: >

linspace(start, stop, n) returns an array of n evenly spaced numbers over the interval [start, stop].

Deterministic

id_matrix(<count>)
Return type:

id_matrix(n) returns an identity matrix of dimension n.

Deterministic

diag_matrix(<array <number>>)
Return type:

diag_matrix(v) returns a diagonal array whose diagonal is v.

Deterministic

ravel(<matrix>)
Return type: >

ravel(m) returns a 1-D array containing the elements of the matrix m.

Deterministic

transpose(<matrix>)
Return type:

transpose(m) returns the transpose of the matrix m.

Deterministic

Return type: >

vector_add(x, y) returns the sum of vectors x and y.

Deterministic

Return type:

matrix_add(x, y) returns the sum of matrices x and y.

Deterministic

scale_vector(<number>, <array <number>>)
Return type: >

scale_vector(x, y) returns the product of scalar x and vector y.

Deterministic

scale_matrix(<number>, <matrix>)
Return type:

scale_matrix(x, y) returns the product of scalar x and matrix y.

Deterministic

vector_dot(<array <number>>, <array <number>>)
Return type:

vector_dot(x, y) returns the dot product of vectors x and y.

Deterministic

matrix_mul(<matrix>, <matrix>)
Return type:

matrix_mul(x, y) returns the product of matrices x and y.

Deterministic

matrix_times_vector(<matrix>, <array <number>>)
Return type: >

matrix_times_vector(M, v) returns the matrix-vector product Mv.

Deterministic

vector_times_matrix(<array <number>>, <matrix>)
Return type: >

vector_times_matrix(v, M) returns the vector-matrix product vM.

Deterministic

matrix_inverse(<matrix>)
Return type:

matrix_inverse(M) returns the (multiplicative) inverse of the matrix M.

Deterministic

matrix_solve(<matrix>, <matrix>)
Return type:

matrix_solve(A, B) returns the solution to the matrix equation AX = B.

Deterministic

apply(proc(a, ...) -> b, <array a>)
Return type: b

apply(func, vals) returns the result of applying a variadic function to an array of operands

Deterministic

mapv(proc(a) -> b, <array a>)
Return type:

mapv(func, vals) returns the results of applying a function to each value in an array

Deterministic

imapv(proc(index, a) -> b, <array a>)
Return type:

imapv(func, vals) returns the results of applying a function to each value in an array, together with its index

Deterministic

fix(<array <symbol>>, <array <exp>>)
Return type:
fix
Used internally in the implementation of letrec.

Deterministic

assess(<val>, proc(<args>, ...) -> <val>, <args>, ...)
Return type:

assess(val, func, arg1, arg2, ...) returns the log probability (density) of simulating val from func(arg1, arg2, ...)

Deterministic

branch(<bool>, <exp>, <exp>)
Return type:

branch evaluates either exp1 or exp2 in the current environment and returns the result. Is itself deterministic, but the chosen expression may involve a stochastic computation.

Deterministic

biplex(<bool>, <object>, <object>)
Return type:

biplex returns either its second or third argument, depending on the first.

Deterministic

make_csp(<array <symbol>>, <exp>)
Return type: a compound SP
make_csp
Used internally in the implementation of compound procedures.

Deterministic

get_current_environment()
Return type:

get_current_environment returns the lexical environment of its invocation site

Deterministic

get_empty_environment()
Return type:

get_empty_environment returns the empty environment

Deterministic

is_environment(<object>)
Return type:

is_environment returns true iff its argument is a <environment>

Deterministic

extend_environment(<environment>, <symbol>, <object>)
Return type:

extend_environment returns an extension of the given environment where the given symbol is bound to the given object

Deterministic

eval(<exp>, <environment>)
Return type:

eval evaluates the given expression in the given environment and returns the result. Is itself deterministic, but the given expression may involve a stochasitc computation.

Deterministic

mem(proc(a, ...) -> b)
Return type: proc(a, ...) -> b

mem returns the stochastically memoized version of the input SP.

Deterministic

tag(<scope>, <block>, <object>)
Return type:

tag returns its third argument unchanged at runtime, but tags the subexpression creating the object as being within the given scope and block.

Deterministic

tag_exclude(<scope>, <object>)
Return type:

tag_exclude returns its second argument unchanged at runtime, but tags the subexpression creating the object as being outside the given scope.

Deterministic

flip([<probability>])
Return type:

flip(p) returns true with probability p and false otherwise. If omitted, p is taken to be 0.5.

Stochastic

bernoulli([<probability>])
Return type:

bernoulli(p) returns true with probability p and false otherwise. If omitted, p is taken to be 0.5.

Stochastic

log_flip(<number>)
Return type:

log_flip(p) returns true with probability exp(p) and false otherwise. This is useful for modeling very low probability events, because it does not suffer the underflow that log_flip(exp(p)) would.

Stochastic

log_bernoulli(<number>)
Return type:

log_bernoulli(p) returns true with probability exp(p) and false otherwise. This is useful for modeling very low probability events, because it does not suffer the underflow that log_bernoulli(exp(p)) would.

Stochastic

binomial(<count>, <probability>)
Return type:

binomial(n, p) simulates flipping n Bernoulli trials independently with probability p and returns the total number of successes.

Stochastic

categorical(<simplex>[, <array>])
Return type:

categorical(weights, objects) samples a categorical with the given weights. In the one argument case, returns the index of the chosen option as an atom; in the two argument case returns the item at that index in the second argument. It is an error if the two arguments have different length.

Stochastic

uniform_discrete(<integer>, <integer>)
Return type:

uniform_discrete(start, end) samples a uniform discrete on the (start, start + 1, ..., end - 1)

Stochastic

poisson(<positive>)
Return type:

poisson(lam) samples a poisson with rate lam

Stochastic

make_beta_bernoulli(<positive>, <positive>)
Return type: proc() ->

make_beta_bernoulli(alpha, beta) returns a collapsed beta bernoulli sampler with pseudocounts alpha (for true) and beta (for false). While this procedure itself is deterministic, the returned sampler is stochastic.

Deterministic, children can absorb at applications

make_uc_beta_bernoulli(<positive>, <positive>)
Return type: proc() ->

make_uc_beta_bernoulli(alpha, beta) returns an uncollapsed beta bernoulli sampler with pseudocounts alpha (for true) and beta (for false).

Stochastic, children can absorb at applications

make_suff_stat_bernoulli(<number>)
Return type: proc() ->

make_suff_stat_bernoulli(weight) returns a bernoulli sampler (weighted coin) with given weight. The latter maintains application statistics sufficient to absorb changes to the weight in O(1) time (without traversing all the applications).

Deterministic, children can absorb at applications

exactly(<object>[, <number>])
Return type:

Force a variable to be treated as random even though its value is known.

This deterministically returns the first argument when simulated, but is willing to pretend to be able to stochastically return any object. The second argument, if given, is the penalty (in log space) for a mismatch. If not given, taken to be -infinity.

Stochastic

multivariate_normal(<array <number>>, <symmetricmatrix>)
Return type: >

multivariate_normal(mean, covariance) samples a vector according to the given multivariate Gaussian distribution. It is an error if the dimensionalities of the arguments do not line up.

Stochastic

inv_wishart(<symmetricmatrix>, <positive>)
Return type:

inv_wishart(scale_matrix, degree_of_freedeom) samples a positive definite matrix according to the given inverse wishart distribution

Stochastic

wishart(<symmetricmatrix>, <positive>)
Return type:

wishart(scale_matrix, degree_of_freedeom) samples a positive definite matrix according to the given inverse wishart distribution

Stochastic

normal(<number>, <number>)
Return type:

normal(mu, sigma) samples a normal distribution with mean mu and standard deviation sigma.

Stochastic, variationable

vonmises(<number>, <positive>)
Return type:

vonmises(mu, kappa) samples a von Mises distribution with mean mu and shape kappa. The output is normalized to the interval [-pi,pi].

Stochastic

uniform_continuous(<number>, <number>)
Return type:

uniform_continuous(low, high) -> samples a uniform real number between low and high.

Stochastic

beta(<positive>, <positive>)
Return type:

beta(alpha, beta) returns a sample from a beta distribution with shape parameters alpha and beta.

Stochastic

expon(<positive>)
Return type:

expon(theta) returns a sample from an exponential distribution with rate (inverse scale) parameter theta.

Stochastic

gamma(<positive>, <positive>)
Return type:

gamma(alpha, beta) returns a sample from a gamma distribution with shape parameter alpha and rate parameter beta.

Stochastic

student_t(<positive>[, <number>[, <number>]])
Return type:

student_t(nu, loc, shape) returns a sample from Student’s t distribution with nu degrees of freedom, with optional location and scale parameters.

Stochastic

inv_gamma(<positive>, <positive>)
Return type:

inv_gamma(alpha, beta) returns a sample from an inverse gamma distribution with shape parameter alpha and scale parameter beta

Stochastic

laplace(<number>, <positive>)
Return type:

laplace(a, b) returns a sample from a laplace (double exponential) distribution with shape parameter a and scale parameter b

Stochastic

dirichlet(<array <positive>>)
Return type:

dirichlet(alphas) samples a simplex point according to the given Dirichlet distribution.

Stochastic

symmetric_dirichlet(<positive>, <count>)
Return type:

symmetric_dirichlet(alpha, n) samples a simplex point according to the symmetric Dirichlet distribution on n dimensions with concentration parameter alpha.

Stochastic

make_dir_mult(<array <positive>>[, <array>])
Return type: proc() ->

make_dir_mult(alphas, objects) returns a sampler for a collapsed Dirichlet multinomial model. If the objects argument is given, the sampler will return one of those objects on each call; if not, it will return one of n <atom>s where n is the length of the list of alphas. It is an error if the list of objects is supplied and has different length from the list of alphas. While this procedure itself is deterministic, the returned sampler is stochastic.

Deterministic, children can absorb at applications

make_uc_dir_mult(<array <positive>>[, <array>])
Return type: proc() ->

make_uc_dir_mult is an uncollapsed variant of make_dir_mult.

Stochastic, children can absorb at applications

make_sym_dir_mult(<positive>, <count>[, <array>])
Return type: proc() ->

make_sym_dir_mult is a symmetric variant of make_dir_mult.

Deterministic, children can absorb at applications

make_uc_sym_dir_mult(<positive>, <count>[, <array>])
Return type: proc() ->

make_uc_sym_dir_mult is an uncollapsed symmetric variant of make_dir_mult.

Stochastic, children can absorb at applications

make_crp(<number>[, <number>])
Return type: proc() ->
make_crp(alpha) -> <SP () <number>>
Chinese Restaurant Process with hyperparameter alpha. Returns a sampler for the table number.

Deterministic, children can absorb at applications

make_lazy_hmm(<simplex>, <matrix>, <matrix>)
Return type: proc() ->

Discrete-state HMM of unbounded length with discrete observations. The inputs are the probability distribution of the first state, the transition matrix, and the observation matrix. It is an error if the dimensionalities do not line up. Returns observations from the HMM encoded as a stochastic procedure that takes the time step and samples a new observation at that time step.

Deterministic

make_cmvn(<array <number>>, <number>, <number>, <matrix>)
Return type: proc() -> >
make_cmvn(m0, k0, v0, S0) -> <SP () <float array>>
Collapsed multivariate normal with hyperparameters m0, k0, v0, S0, where parameters are named as in (Murphy, section 4.6.3.3, page 134).

Deterministic, children can absorb at applications

apply_function()

apply_function

Deterministic

make_gp(mean function, covariance function)
Return type: proc(>) -> >

Constructs a Gaussian Process with the given mean and covariance functions. Note that each application of the GP involves a matrix inversion, so when sampling at many inputs it is much more efficient to batch-query by passing a vector of input values. Wrap the GP in a mem if input points might be sampled multiple times. Global Logscore is broken with GPs, as it is with all SPs that have auxen.

Deterministic, children can absorb at applications

inference_action(<object>)
Return type:

inference_action constructs a inference_action record

Deterministic

is_inference_action(<object>)
Return type:

is_inference_action returns true iff its argument is a <inference_action>

Deterministic

action_func(<inference_action>)
Return type:

action_func extracts the 0 field of a inference_action record

Deterministic

You can ask your Venture installation for a current version of this list by running the vendoc program (with no arguments).

## Built-in Helpers¶

• true: The boolean True value.
• false: The boolean False value.