Silico formulae support a number of builtin functions with extended functionality.

Mathematical Functions

abs(x)

Return the absolute value of a number

abs(5)  => 5
abs(-5) => 5

ceil(x)

Round a number upwards (towards infinity)

ceil(5) => 5
ceil(5.1)  => 6
ceil(-5.9) => -5

exp(x)

Return the natural exponential of a number

exp(0) => 0
exp(1) => 2.718..

floor(x)

Round a number downwards (towards negative infinity)

floor(5) => 5
floor(5.1) => 5
floor(-5.9) => -6

sqrt(x)

Take the square root of a number

sqrt(4)  => 2
sqrt(16) => 4

div(x, y, z = 0)

Divide x by y. In the case where y is zero, return the fallback value z, defaulting to 0.

frac(x)

Return the fractional part of a number.

frac(5.5)  => 0.5
frac(-5.5) => -0.5

int(x)

Return the integral part of a number. This can also be thought of as rounding towards 0. Note that frac(x) + int(x) will always equal x.

int(5.5)  => 5
int(-5.5) => -5

ln(x)

Return the natural logarithm of a number.

ln(1) => 0
ln(2) => 0.6931..
ln(exp(3)) => 3

log(x, base = 10)

Return the logarithm of a number, with an arbitrary base. Defaults to the logarithm of base 10.

log(100)  => 2
log(8, 2) => 3

bound(x, min, max)

Return a number, bounded to be between min and max.

bound(0.5, 1, 2) => 1
bound(1.5, 1, 2) => 1.5
bound(2.5, 1, 2) => 2

power(x, n)

Raise a number to the nth power. Supports fractional powers.

power(4, 2) => 16

root(x, n = 2)

Find the nth root of a number, defaulting to the 2nd root (or sqrt).

root(4)     => 2
root(27, 3) => 3

sign(x)

Return the sign of a number, in the form of -1 for negative, and 1 for non-negative.

sign(-5) => -1
sign(0)  => 1
sign(16) => 1

round(x, places = 0)

Round a number towards the nearest integer. In the case of equal distance, rounds away from 0.

round(4.4)  => 4
round(4.6)  => 5
round(4.5)  => 5
round(-4.5) => -5

If places is provided, rounds to the given number of decimal places, otherwise following the same rules.

round(4.4, 1)  => 4.4
round(4.35, 1) => 4.4

round2(x, places = 0)

Round a number using convergent rounding, or bankers' rounding. In the case of equal distance, rounds to the even number.

round2(4.5) => 4
round2(5.5) => 6

As with round, can be provided with a places argument to round to a certain number of decimal places.

round2(4.65, 1) => 4.6
round2(4.75, 1) => 4.8

Aggregation Functions

All aggregation functions take any number of arguments, and return a single result.

min(x, y, ...), max(x, y, ...)

Return the minimum or maximum value of all arguments. If no arguments are provided, return 0.

min(4, 5)        => 4
min(8, 7, -2, 4) => -2
min()            => 0

max(4, 5)        => 5
min(8, 7, -2, 4) => 8
max()            => 0

Window Functions

Window functions compute a value from their argument across time periods.

moving_avg(x, periods)

Return the simple moving average of the given expression x, across the given number of time periods. 

exp_moving_avg(x, factor)

Return the exponential moving average of a given expression x, with the provided decay factor. The factor represents the fraction to which the smoothed value is updated by x. For example, a factor of 1 results in the smoothed value and x being identical. A value of 0.9 means that the smoothed value is derived by 0.9*x + 0.1*previous value, for instance if there was a jump from 10 to 100, this would give 0.9*100 + 0.1*10, or 91 as the smoothed value.

delay(x, periods, fallback = 0)

Return the value of the expression x the given number of time periods in the past. If the provided time offset would be 0 or point to before the start time of the model, return the fallback value. Note that delay can be used to break circular dependencies, as with a variable X depending on Y, Y can reference a delayed value of X safely.

time_lag(x, periods)

Returns the value of x the given number of periods in the future. Whereas delay looks backwards, time_lag writes into the variable’s future values and can stack multiple values into a single timestep in the future. This makes simulations that change the number of periods much safer. However, time_lag does not break circular references.

Time-Varying Functions

ramp(x, start_time)

Return a value increasing by x each time period, starting at the given start_time, which will default to the start of the model if not provided.

pulse(x, start_time, interval = 0)

Return a value that pulses at given times. If start_time is not provided, it will default to the start of the model. If interval is not provided, then the function will pulse only once (at start_time), otherwise after start_time the function will return the value x every interval time periods.

step(x, start_time)

Return a value that is 0 before start_time, and x at start_time or after. If a start_time is not provided, it defaults to the start of the model, and so will always return the value of x.

Random Number Functions

Silico provides a number of builtin functions for sampling from random number distributions. All of these functions uses a seeded pseudorandom number generator, and so will return the same sampled distributions. Each call to a pseudo-random function is however independently seeded, and so will not affect the results from other functions. Functionality for controlling the PRNG seeds will be coming in a future release.

random(max = 1)

Return a number sampled uniformly between 0 and max. Equivalent to rand_uniform(0, max).

rand_bernoulli(p = 0.5)

Return a sample from the Bernoulli distribution with default probability 0.5, i.e. an even chance between returning 0 or 1.

rand_binomial(n, p = 0.5)

Return a sample from the Binomial distribution with n trials and probability p.

rand_discrete(min = 0, max = 1)

Return a sample from the Discrete uniform distribution between given min and max bounds.

rand_uniform(min = 0, max = 1)

Return a sample from the Continuous uniform distribution between given min and max bounds.

rand_exp(lambda = 1)

Return a sample from the Exponential distribution with given lambda.

rand_exp_percentile(lambda = 1, percentile = 0.5)

Return the quantile function result for the Exponential distribution at the given percentile.

rand_gaussian(mean = 0, std_dev = 1)

Return a sample from the Gaussian distribution with given mean and standard deviation.

rand_gaussian_percentile(mean = 0, std_dev = 1, percentile = 0.5)

Return the quantile function result for the Gaussian distribution at the given percentile.

rand_pareto(xm = 1, alpha = 1.16)

Return a sample from the Pareto distribution with given xm and alpha.

rand_poisson(lambda = 1)

Return a sample from the Poisson distribution with given lambda.

rand_poisson_percentile(lambda = 1, percentile = 0.5)

Return the quantile function result for the Poisson distribution at the given percentile.

rand_poisson_binomial(p1, p2, p3..)

Return a sample from the Poisson binomial distribution with given p values.

rand_student(dof = 1)

Return a sample from the Student's t-distribution with given degrees of freedom.

Date/Time Functions

time_dayofweek()

Return the day of the week on the current tick as a number where Monday = 1 and Sunday = 7. If the project time settings are tick-based, rather than date-based, returns 0.

Segmentation Functions

Silico provides additional functions to work with variables with varying segmentations. The use of these functions is further explained in the segmentation documentation.

seg_sum(x)

For a input argument that is a segmented variable, this function outputs the sum across all segment values (that is, it returns a scalar value).

seg_partial_sum(segmentation, x)

If variable "x" has segmentations "A", "B" and "C", then seg_partial_sum("A", "x") will give a value that has segmentations "B" and "C", and whose values are summed across the segments of "A".

seg_partial_mul(x, y)

If variable "x" has segmentations "A" and "B", and variable "y" has segmentations "C" and "D", then seg_partial_mul("x", "y") will give a value that has segmentations "A", "B", "C" and "D", and whose individual cells are computed as:

z[i,j,k,l] = x[i,j] * y[k,l]