Nasal library/math

From FlightGear wiki
Jump to navigation Jump to search

This page contains documentation for the math namespace in Nasal. This namespace provides various mathematical functions and variables. The math namespace is sourced from two files:

Tip  Copy & paste the examples into your Nasal Console and execute them to see what they do.

Functions

abs()

math.abs(x);

Source

This simple function returns the absolute value of the provided number.

x
This argument is required and should be a number.

Examples

print(math.abs(1)); # prints "1"
print(math.abs(-1)); # prints "1"

acos()

math.acos(x);

Source

Implements the arccosine trigonometric function. Returns an angle in radians from the given ratio.

x
Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.

Example

var ratio = 1 / 1.414;
print(math.acos(ratio) * R2D); # prints the angle in degrees (approximately 45)

asin()

math.asin(x);

Source

Implements the arcsine trigonometric function. Returns an angle in radians from the given ratio.

x
Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.

Example

var ratio = 1 / 1.414;
print(math.asin(ratio) * R2D); # prints the angle in degrees (approximately 45)

atan2()

math.atan2(y, x);

Source

Implements the two-argument version This is a link to a Wikipedia article of the arctangent trigonometric function. Returns an angle in radians between the positive x-axis of a plane and the point given by the coordinates (x, y) on it.

y
Mandatory y-axis coordinate as a number.
x
Mandatory x-axis coordinate as a number.

Examples

var x = 1;
var y = 1;
print(math.atan2(y, x) * R2D); # prints the angle in degrees (45)
var x = -1;
var y = -1;
print(math.atan2(y, x) * R2D); # prints the angle in degrees (-135)

avg()

math.avg(x[, y[, z[, ...]]]);

Source — Version added: FG 2.4 (Commit)

Returns the average of the given numbers. There must be at least one argument, but there may be as many as you like.

Example

print(math.avg(1, 2, 3, 4)); # prints 2.5

ceil()

math.ceil(x);

Source — Version added: FG 2.10 (Commit)

Returns the ceiling This is a link to a Wikipedia article of a number, that is, the smallest following integer.

x
Number to return the ceiling of.

Examples

print(math.ceil(2)); # prints 2
print(math.ceil(2.1)); # prints 3
print(math.ceil(-2.9)); # prints -2

clamp()

math.clamp(x, min, max);

Source — Version added: FG 2.10 (Commit)

Clamps a number so that is within the range given. All arguments are mandatory and must be numbers.

Note  Up until FG v2016.2, the clamping algorithm was not correct, meaning that the function will not behave correctly in FlightGear versions below 2016.2. It was fixed by SimGear commit bba11c

.

x
The number to be clamped.
min
Lower limit of the clamping range.
max
Upper limit of the clamping range.

Examples

Note that none of these examples will work properly in FlightGear versions below 2016.2.

print(math.clamp(5, 1, 10)); # prints 5
print(math.clamp(0, 1, 10)); # prints 1
print(math.clamp(12, 1, 10)); # prints 10

cos()

math.cos(x);

Source

Implements the cosine trigonometric function. Returns a ratio from a given angle in radians.

x
Mandatory number that should be an angle in radians.

Example

var angle = 180 * D2R;
print(math.cos(angle)); # prints the ratio (-1)

exp()

math.exp(x);

Source

Returns the value of e raised to the given poweer.

x
Mandatory number which is the value of the exponent.

Example

printf("%.4f", math.exp(2)); # prints 7.3891

floor()

math.floor(x);

Source — Version added: FG 2.10 (Commit)

Returns the floor This is a link to a Wikipedia article of a number, that is, the largest previous integer.

x
Number to return the floor of.

Examples

print(math.floor(2)); # prints 2
print(math.floor(2.1)); # prints 2
print(math.floor(-2.9)); # prints -3

fmod()

math.fmod(x, y);

Source — Version added: FG 2.10 (Commit)

Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of x divided by y. Unlike mod() , this function uses the C library function fmod() , and has different (and more correct) behavior when negative arguments are passed to it (compare example 3 with example 3 of mod() ). Both arguments are mandatory and must be numbers.

Note  This function was initially added math.mod(), but this was overridden by another version which already existed in FGData. In FlightGear 3.0, this function was renamed to fmod().
x
The dividend.
y
The divisor. If this argument is 0, a floating point error will be generated.

Examples

print(math.fmod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
print(math.fmod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
print(math.fmod(-5, 2)); # prints -1 (2 goes into -5 -2 times with a remainder of -1; 2 * -2 + -1 = -5)

ln()

math.ln(x);

Source

Returns the natural (base e) logarithm of the given number.

x
Number to return the logarithm of. Must be greater than 0.

Example

printf("%.4f", math.ln(60)); # prints 4.0943

log10()

math.log10(x);

Source

Returns the common (base 10) logarithm of the given number.

x
Number to return the logarithm of. Must be greater than 0.

Example

printf("%g", math.log10(1000)); # prints 3

max()

math.max(x[, y[, z[, ...]]]);

Source — Version added: FG 2.4 (Commit)

Returns the highest number of the given numbers. There must be at least one argument, but there may be as many as you like.

Example

print(math.max(1, 2, 3, 4)); # prints 4

min()

math.min(x[, y[, z[, ...]]]);

Source — Version added: FG 2.4 (Commit)

Returns the lowest number of the given numbers. There must be at least one argument, but there may be as many as you like.

Example

print(math.min(1, 2, 3, 4)); # prints 1

mod()

math.mod(x, y);

Source

Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of x divided by y. Note that this function does not not return correct answers when either or both the arguments are negative (see example 3), unlike fmod(). Both arguments are mandatory and must be numbers.

x
The dividend.
y
The divisor. If this argument is 0, infinity will be returned (printed as 0e-00).

Examples

print(math.mod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
print(math.mod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
print(math.mod(-5, 4)); # prints 3 (incorrect, should be -1)

periodic()

math.periodic(min, max, x);

Source — Version added: FG 2.10 (Commit)

Normalizes the given number (e.g., a bearing) to be within a set periodic range (e.g., compass bearings, which go from 0 to 360). All the arguments are mandatory and must be numbers.

min
Lower boundary of the periodic range.
max
Upper boundary of the periodic range
x
Number to normalize.

Examples

var norm_360 = func(a){
    return math.periodic(0, 360, a);
}

print(norm_360(-90)); # prints 270
print(norm_360(45)); # prints 45
var norm_180 = func(a){
    return math.periodic(-180, 180, a);
}

print(norm_180(45)); # prints 45
print(norm_180(270)); # prints -90
print(math.periodic(0, 10, 15)); # prints 5

pow()

math.pow(b, n);

Source

Returns the base b raised to the n power. Both arguments are mandatory and must be numbers.

b
Base.
n
Exponent.

Example

print(math.pow(2, 2)); # prints 4

round()

math.round(x[, p]);

Source — Version added: FG 3.0 (Commit)

Rounds x to the optional precision (p). If the fractional part of x is 0.5, it will always be rounded up. Both argument must be numbers.

x
Mandatory number to round.
p
Optional precision to round to. For example, if this is set to 10, x will be rounded to the nearest 10. Defaults to 1, and should be greater than or equal to 1 for correct output. For rounding to decimal places, it is better to use sprintf .

Examples

print(math.round(4.2)); # prints 4
print(math.round(4.7)); # prints 5
print(math.round(4.5)); # prints 5
print(math.round(127, 10)); # prints 130
print(math.round(456, 100)); # prints 500

sin()

math.sin(x);

Source

Implements the sine trigonometric function. Returns a ratio from a given angle in radians.

x
Mandatory number that should be an angle in radians.

Example

var angle = 90 * D2R;
print(math.sin(angle)); # prints the ratio (1)

sgn()

math.sgn(x);

Source

Returns the result of the sign function on the given number. If x is less than 0, -1 one is returned. If x equals 0, 0 is returned. If x is greater than 0, 1 is returned.

x
Mandatory number to return the sign of.

Examples

print(math.sgn(-6)); # prints -1
print(math.sgn(0)); # prints 0
print(math.sgn(12)); # prints 1

sqrt()

math.sqrt(x);

Source

Returns the square root of the given number.

x
Mandatory number to return the square root of. Must be greater than or equal to 0.

Example

print(math.sqrt(9)); # prints 3

tan()

math.tan(x);

Source

Implements the tangent trigonometric function. Returns a ratio from a given angle in radians.

x
Mandatory number that should be an angle in radians.

Example

var angle = 45 * D2R;
print(math.tan(angle)); # prints the ratio (1)

Variables

e

math.e;

Source

Important mathematical constant (see e (mathematical constant) This is a link to a Wikipedia article). Value in simulation: 2.7182818284590452354

pi

math.pi;

Source

Important mathematical constant (see pi (mathematical constant) This is a link to a Wikipedia article). Value in simulation: 3.14159265358979323846