Designer Primitive Operator Guide

From Numerus
Jump to navigation Jump to search

Primop Index

On this page the primops are grouped either as universally applicable, or according to the Components in which they are meaningful. Primops used outside their designated purview will return empty answers (such as 0 or nil).

Each primop in these lists has a short description. Those that require further elaboration contain a link to a section with more information. Use this index to find the primop that you need, and follow the link for greater detail if you need it.

How To Read These Entries

Each entry shows the return type of the primop and types of the arguments to be passed in. For example, Double foo(Double x, Integer y) can be invoked as foo(3.0, 1), or as foo(u, v), where u has type Double and v has type Integer. A return type of void means that the primop does not return a value and should be used as a command.

Variable Number of Arguments

Entries such as foo(String s, Number... z) represent primops with a variable number of arguments. In this case, a String is required as the first argument, but a sequence of Numbers of any length will be accepted for the second argument; e.g., foo("howdy"), foo("howdy", 1.0), foo("howdy", 1.0, 3, 17.5, 21), etc. (The sequence is stored in an array).

Collection

This type includes the List type, elements of which are returned by many primops. It does not include the array type. In order to use an array arr as a Collection argument, pass Arrays.asList(arr).

Universal Primops

These primops will return meaningful results when used in any context.

Math Primops

Most mathematical operations use the Java java.lang.Math class. These include Math.abs, Math.sin, Math.cos, Math.pow (for powers), etc. The complete list is contained here.

In addition to the operations in the Math class, Designer has added the following:

Integer signum(Number x)
Returns -1 if x < 0, 1 if x > 0 and 0 if x = 0.

Double normalize(Double theta)
Normalizes angle theta to fall in the range ( , π ].

Double dTotal(Function<Double, Double) f, Collection<Double> nums, Double base)
Double dTotal(Function<Double, Double) f, Collection<Double> nums)

Double iTotal(Function<Integer, Integer) f, Collection<Integer> nums)
Double iTotal(Function<Integer, Integer) f, Collection<Integer> nums, Integer base)
Returns the sum of the values in nums transformed by f added to base (In the first version base is 0.)
Example:  iTotal((x) -> x*2, {1,2,3,4,5}) ⇒ 30
iTotal((x) -> x*2, {1,2,3,4,5}, 20) ⇒ 50

Random Numbers

Designer implements certain primops associated with random number generation (RNG) using an instance of the java.util.Random class. This RNG can be seeded from the platform so that the random sequences obtained from these operators will be fixed. These primops are as follows:

Double random(), Double random(Number y), Double random(Number x, Number y)
Returns a random Double selected respectively from [0, 1), [0, y), [x, y).
Integer irandom(), Integer irandom(Number y), Integer irandom(Number x, Number y)
Returns a random Integer selected respectively from [0, 1), [0, y), [x, y).

Double normal(Double mu, Double sigma)
Returns a Gaussian-distributed RN with mean mu and standard deviation sigma.

Integer binomial(Integer N, Double prob)
Returns a binomial RN with number of observations N and probability of success prob.

Integer[] multinomial(Integer N, Double... probs)
Returns a list containing the results of a multinomial sorting of N observations, with probabilities given by the argument sequence probs. If the probabilities sum to 1, the list of outcomes will be the same length as the probability sequence. If the probabilities sum to less than 1, the list of outcomes will be 1 element longer than the number of probabilities to account for the missing slot.

Integer poisson(Double lambda)
Returns a Poisson RN with density lambda.

Boolean flip(Double prob)
Performs a Bernoulli trial and returns result.

Integer roll(Double... prob)
Performs a generalized Bernoulli trial and returns result.

Misc. Universal Primops

me()
Returns the component in which this squib is contained. Useful for accessing and applying methods from the component. Details are specific to the component.

Double time()
Returns the current model time.

void halt()
Stops the execution of the simulation.

DCoord Cart(Number u, Number v)
Returns a DCoord value d with d.x = u and d.y = v. Equivalent to new DCoord(u, v).

ICoord Mat(Integer r, Number c)
Returns an ICoord value m with m.row = r and d.col = c. Equivalent to new ICoord(r, c).