See Also
The mathematical builtins perform mathematical operations on their input expressions, generating a result. Most commonly, you'll use the mathematical functions to define converters, which form the micro-logic of your model. Mathematical functions do a wide variety of operations, as detailed below.
This section describes the following builtins:
The ABS builtin returns the absolute value of expression. The expression value can be either a variable or a constant.
Example:
ABS(-1) equals 1
The DERIVN builtin calculates the nth-order time derivative of input. The input value can be either a variable or a constant, but order must be a non-negative integer. The software uses a recursive finite difference technique to calculate time derivatives. The basic equation used in the calculation is:
dx/dt = (xt - x(t-dt))/dt
where t is current simulation time, and dt is DT, the simulation solution interval.
Because the DERIVN builtin uses previous values of input for its calculations, the builtin returns an initial value of 0.
Calculus cognoscenti will note that it's possible to use the chain rule to calculate dy/dx, where yand x are time-dependent model variables. Use this formula:
dy/dx = dy/dt ÷ dx/dt
Examples:
DERIVN(TIME,0) equals TIME (the zeroth-order derivative)
DERIVN(TIME,1) equals 1 (the first-order derivative)
DERIVN(SIN(TIME),4) calculates the fourth-order derivative of a sin function on time, which is equal to the sin function (except for the first 4 dts when DERIVN will return 0).
When the order argument to DERIVN is a number rather than an expression the units returned for the function are the units of the input divided by the units of time raised to the appropriate power. That is, the first derivative is per time units, the second per time units squared and so on. If the order argument is an expression, including just a variable, the units returned are the same that a number would return.
The EXP builtin gives e raised to the power of expression. The expression value can be either a variable or a constant. The base of the natural logarithm, e is also known as Euler's number; e is equal to 2.7182818... EXP is the inverse of the LN builtin (natural logarithm). To calculate powers of other bases, use the exponentiation operator (^).
Examples:
EXP(1) equals 2.7182818 (the value of Euler's constant)
EXP(LOGN(3)) equals 3
2^3 equals 8 (2 raised to the third power)
The INT builtin gives the largest integer less than or equal to expression. The expression value can be either a variable or a constant.
Because of the internal calculations associated with the Runge-Kutta methods, the INT function doesn't always return integer values when you use the 2nd- or 4th-order Runge-Kutta computation methods. When your model constructs rely on the INT function, be sure to use Euler's method.
Examples:
INT(8.9) equals 8
INT(-8.9) equals -9
The LN builtin calculates the natural logarithm of expression. The expression value can be either a variable or a constant. Natural logarithms use Euler's constant, e, 2.7182818..., as a base. For LN to have meaningful results, expression must evaluate to a positive value. LN is the inverse of the EXP function, e raised to the power of expression.
Examples:
LN(2.7182818) equals 1
LN(EXP(3)) equals 3
LN(8)/LN(2) equals 3 (the base 2 logarithm of 8)
LN(-10) returns ? (undefined for non-positive numbers and will generate a divide by 0 error message)
The LOG10 builtin gives the base 10 logarithm of expression. The expression value can be either a variable or a constant. For LOG10 to be meaningful, expression must evaluate to a positive value. LOG10 is the inverse of the letter E in scientific notation, or base 10 exponentiation (10 raised to the power of expression).
Examples:
LOG10(10) equals 1
LOG10(1E5) equals 5
LOG10(8)/LOG10(2) equals 3 (the base 2 logarithm of 8)
LOG10(-10) returns ? (undefined for non-positive numbers and will generate a divide by 0 error)
The MAX builtin gives the maximum value among the arrayed variables or expressions contained within parentheses.
Because of the internal calculations associated with the Runge-Kutta methods, the MAX builtin doesn't always return the expected value when you use the 2nd- or 4th-order Runge-Kutta computation methods, and your inputs to the MAX calculation are variables. When your model constructs rely on the MAX builtin, be sure to use Euler's method.
Example:
Purchases = MAX(0,Desired_Purchases) returns the larger value among Desired Purchases and 0. In this example, the MAX function will prevent Purchases from taking on negative values.
To report the maximum value across a subset of the dimensions of an arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension.
Example:
Maximum Value for Salary = MAX(Salaries[*,*])
The MIN builtin gives the minimum value among the arrayed variables or expressions contained within parentheses.
Because of the internal calculations associated with the Runge-Kutta methods, the MIN function doesn't always return the expected value when you use the 2nd- or 4th-order Runge-Kutta computation methods, and your inputs to the MIN calculation are variables. When your model constructs rely on the MIN builtin, be sure to use Euler's method.
Example:
Spending = MIN(Desired_Spending,Allowable_Spending) returns the smaller value among Desired Spending and Allowable Spending.
To report the minimum value across a subset of the dimensions of an arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension.
Example:
Minimum Value for Salary = MIN(Salaries[*,*])
The MOD builtin calculates the remainder.
Examples:
x MOD y equals the remainder when the value of x is divided by the value of y
5 MOD 3 equals 2
The PERCENT builtin gives the value of fraction, expressed as a percentage. The fraction value can be either a variable or a constant.
Examples:
PERCENT(.65) equals 65
PERCENT(1.22) equals 122
The PI builtin gives the number 3.14159..., an approximation of the constant Π.
Example:
10*SIN(2*PI*TIME/12)
generates a sinusoidal fluctuation with an amplitude of 10 and a period of 12. See also SIN and COS (see Trigonometric builtins).
The ROOTN builtin returns the order root of expression. The expression value can be either any expression, and the order value can be an expression or constant. If the order is not an integer it will be rounded to an integer. For meaningful results, expression must be greater than or equal to 0 when order is even. If order is 0 ROOTN returns 1. Negative orders are treated as 0.
Examples:
ROOTN(144,2) returns 12
ROOTN(4,2.3) return 2 (2.3 is rounded to 2)
ROOTN(-27,3) returns -3
ROOTN(-27,2) returns ? (undefined for negative numbers and will generate a divide by 0 error)
NoteROOTN(a,b) will return the same value as a^(1/b) when a is positive and b is a positive integer.
Note If order is a constant then the units of the expression will also have their root taken for units checking.
The ROUND builtin rounds expression to its nearest integer value.
Because of the internal calculations associated with the Runge-Kutta methods, the ROUND builtin doesn't always return integer values when you use the 2nd- or 4th-order Runge-Kutta computation methods. When your model constructs rely on the ROUND builtin, be sure to use Euler's method.
Examples:
ROUND(9.4) equals 9
ROUND(9.64) equals 10
The SAFEDIV builtin allows you to divide two things without first checking that the denominator in the expression is nonzero. It returns numerator/denominator as long as result of that computation is allowed and finite. If denominator is 0, or extremely close to 0, it will return 0, or, if onzero has been specified, it will return onzero. SAFEDIV can be used to prevent divide by zero messages stopping the simulation, and to allow other model values to be computed reasonably.
Examples:
SAFEDIV(10,5) returns 2
SAFEDIV(1,0) returns 0
SAVEDIV(1,1E-150,1E9) returns 1E150
SAFEDIV(1E150,1E-150,1E9) returns 1E9
Note You can use // as a shortcut for SAFEDIV with a//b the same as SAFEDIV(a,b)
The SQRT builtin gives the square root of expression. The expression value can be either a variable or a constant. For meaningful results, expression must be greater than or equal to 0.
Examples:
SQRT(144) returns 12
SQRT(-242) returns ? (undefined for negative numbers and will generate a divide by 0 error)