# math

Dark Mode
Search:

Constructive mathematics is naturally typed. -- Simon Thompson

Basic math routines for Nim.

```import math
from sequtils import map

let a = [0.0, PI/6, PI/4, PI/3, PI/2]

echo a.map(sin)
# @[0.0, 0.499…, 0.707…, 0.866…, 1.0]

echo a.map(tan)
# @[0.0, 0.577…, 0.999…, 1.732…, 1.633…e+16]

# -1.0

echo sqrt(-1.0)
# nan   (use `complex` module)```

This module is available for the JavaScript target.

• complex module for complex numbers and their mathematical operations
• rationals module for rational numbers and their mathematical operations
• fenv module for handling of floating-point rounding and exceptions (overflow, zero-divide, etc.)
• random module for fast and tiny random number generator
• mersenne module for Mersenne twister random number generator
• stats module for statistical analysis
• strformat module for formatting floats for print
• system module Some very basic and trivial math operators are on system directly, to name a few shr, shl, xor, clamp, etc.

since, bitops

# Types

```FloatClass = enum
fcNormal, fcSubnormal, fcZero, fcNegZero, fcNan, fcInf, fcNegInf```
Describes the class a floating point value belongs to. This is the type that is returned by classify proc.   Source Edit

# Consts

`PI = 3.141592653589793`
The circle constant PI (Ludolph's number)   Source Edit
`TAU = 6.283185307179586`
The circle constant TAU (= 2 * PI)   Source Edit
`E = 2.718281828459045`
Euler's number   Source Edit
`MaxFloat64Precision = 16`
Maximum number of meaningful digits after the decimal point for Nim's float64 type.   Source Edit
`MaxFloat32Precision = 8`
Maximum number of meaningful digits after the decimal point for Nim's float32 type.   Source Edit
`MaxFloatPrecision = 16`
Maximum number of meaningful digits after the decimal point for Nim's float type.   Source Edit
`MinFloatNormal = 2.225073858507201e-308`
Smallest normal number for Nim's float type. (= 2^-1022).   Source Edit

# Procs

`proc binom(n, k: int): int {...}{.noSideEffect, raises: [], tags: [].}`
Computes the binomial coefficient.

Example:

```doAssert binom(6, 2) == binom(6, 4)
doAssert binom(6, 2) == 15
doAssert binom(-6, 2) == 1
doAssert binom(6, 0) == 1```
Source Edit
`proc fac(n: int): int {...}{.raises: [], tags: [].}`

Computes the factorial of a non-negative integer n.

Example:

```doAssert fac(3) == 6
doAssert fac(4) == 24
doAssert fac(10) == 3628800```
Source Edit
`proc classify(x: float): FloatClass {...}{.raises: [], tags: [].}`

Classifies a floating point value.

Returns x's class as specified by FloatClass enum.

Example:

```doAssert classify(0.3) == fcNormal
doAssert classify(0.0) == fcZero
doAssert classify(0.3/0.0) == fcInf
doAssert classify(-0.3/0.0) == fcNegInf
doAssert classify(5.0e-324) == fcSubnormal```
Source Edit
`proc isPowerOfTwo(x: int): bool {...}{.noSideEffect, raises: [], tags: [].}`

Returns true, if x is a power of two, false otherwise.

Zero and negative numbers are not a power of two.

Example:

```doAssert isPowerOfTwo(16) == true
doAssert isPowerOfTwo(5) == false
doAssert isPowerOfTwo(0) == false
doAssert isPowerOfTwo(-16) == false```
Source Edit
`proc nextPowerOfTwo(x: int): int {...}{.noSideEffect, raises: [], tags: [].}`

Returns x rounded up to the nearest power of two.

Zero and negative numbers get rounded up to 1.

Example:

```doAssert nextPowerOfTwo(16) == 16
doAssert nextPowerOfTwo(5) == 8
doAssert nextPowerOfTwo(0) == 1
doAssert nextPowerOfTwo(-16) == 1```
Source Edit
`proc sum[T](x: openArray[T]): T {...}{.noSideEffect.}`

Computes the sum of the elements in x.

If x is empty, 0 is returned.

Example:

```doAssert sum([1, 2, 3, 4]) == 10
doAssert sum([-1.5, 2.7, -0.1]) == 1.1```
Source Edit
`proc prod[T](x: openArray[T]): T {...}{.noSideEffect.}`

Computes the product of the elements in x.

If x is empty, 1 is returned.

Example:

```doAssert prod([1, 2, 3, 4]) == 24
doAssert prod([-4, 3, 5]) == -60```
Source Edit
`proc cumsummed[T](x: openArray[T]): seq[T]`

Return cumulative (aka prefix) summation of x.

Example:

```let a = [1, 2, 3, 4]
doAssert cumsummed(a) == @[1, 3, 6, 10]```
Source Edit
`proc cumsum[T](x: var openArray[T])`

Transforms x in-place (must be declared as var) into its cumulative (aka prefix) summation.

Example:

```var a = [1, 2, 3, 4]
cumsum(a)
doAssert a == @[1, 3, 6, 10]```
Source Edit
```proc sqrt(x: float32): float32 {...}{.importc: "sqrtf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc sqrt(x: float64): float64 {...}{.importc: "sqrt", header: "<math.h>",
noSideEffect.}```

Computes the square root of x.

```echo sqrt(4.0)  ## 2.0
echo sqrt(1.44) ## 1.2
echo sqrt(-4.0) ## nan```
Source Edit
```proc cbrt(x: float32): float32 {...}{.importc: "cbrtf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc cbrt(x: float64): float64 {...}{.importc: "cbrt", header: "<math.h>",
noSideEffect.}```

Computes the cubic root of x.

```echo cbrt(8.0)   ## 2.0
echo cbrt(2.197) ## 1.3
echo cbrt(-27.0) ## -3.0```
Source Edit
`proc ln(x: float32): float32 {...}{.importc: "logf", header: "<math.h>", noSideEffect.}`
Source Edit
`proc ln(x: float64): float64 {...}{.importc: "log", header: "<math.h>", noSideEffect.}`

Computes the natural logarithm of x.

```echo ln(exp(4.0)) ## 4.0
echo ln(1.0))     ## 0.0
echo ln(0.0)      ## -inf
echo ln(-7.0)     ## nan```
Source Edit
`proc log[T: SomeFloat](x, base: T): T {...}{.noSideEffect.}`

Computes the logarithm of x to base base.

```echo log(9.0, 3.0)  ## 2.0
echo log(32.0, 2.0) ## 5.0
echo log(0.0, 2.0)  ## -inf
echo log(-7.0, 4.0) ## nan
echo log(8.0, -2.0) ## nan```
Source Edit
```proc log10(x: float32): float32 {...}{.importc: "log10f", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc log10(x: float64): float64 {...}{.importc: "log10", header: "<math.h>",
noSideEffect.}```

Computes the common logarithm (base 10) of x.

```echo log10(100.0)  ## 2.0
echo log10(0.0)    ## nan
echo log10(-100.0) ## -inf```
Source Edit
```proc exp(x: float32): float32 {...}{.importc: "expf", header: "<math.h>",
noSideEffect.}```
Source Edit
`proc exp(x: float64): float64 {...}{.importc: "exp", header: "<math.h>", noSideEffect.}`

Computes the exponential function of x (e^x).

```echo exp(1.0)     ## 2.718281828459045
echo ln(exp(4.0)) ## 4.0
echo exp(0.0)     ## 1.0
echo exp(-1.0)    ## 0.3678794411714423```
Source Edit
```proc sin(x: float32): float32 {...}{.importc: "sinf", header: "<math.h>",
noSideEffect.}```
Source Edit
`proc sin(x: float64): float64 {...}{.importc: "sin", header: "<math.h>", noSideEffect.}`

Computes the sine of x.

```echo sin(PI / 6)         ## 0.4999999999999999
Source Edit
```proc cos(x: float32): float32 {...}{.importc: "cosf", header: "<math.h>",
noSideEffect.}```
Source Edit
`proc cos(x: float64): float64 {...}{.importc: "cos", header: "<math.h>", noSideEffect.}`

Computes the cosine of x.

```echo cos(2 * PI)         ## 1.0
Source Edit
```proc tan(x: float32): float32 {...}{.importc: "tanf", header: "<math.h>",
noSideEffect.}```
Source Edit
`proc tan(x: float64): float64 {...}{.importc: "tan", header: "<math.h>", noSideEffect.}`

Computes the tangent of x.

```echo tan(degToRad(45.0)) ## 0.9999999999999999
echo tan(PI / 4)         ## 0.9999999999999999```
Source Edit
```proc sinh(x: float32): float32 {...}{.importc: "sinhf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc sinh(x: float64): float64 {...}{.importc: "sinh", header: "<math.h>",
noSideEffect.}```

Computes the hyperbolic sine of x.

```echo sinh(0.0)            ## 0.0
echo sinh(1.0)            ## 1.175201193643801
Source Edit
```proc cosh(x: float32): float32 {...}{.importc: "coshf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc cosh(x: float64): float64 {...}{.importc: "cosh", header: "<math.h>",
noSideEffect.}```

Computes the hyperbolic cosine of x.

```echo cosh(0.0)            ## 1.0
echo cosh(1.0)            ## 1.543080634815244
Source Edit
```proc tanh(x: float32): float32 {...}{.importc: "tanhf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc tanh(x: float64): float64 {...}{.importc: "tanh", header: "<math.h>",
noSideEffect.}```

Computes the hyperbolic tangent of x.

```echo tanh(0.0)            ## 0.0
echo tanh(1.0)            ## 0.7615941559557649
Source Edit
```proc arccos(x: float32): float32 {...}{.importc: "acosf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arccos(x: float64): float64 {...}{.importc: "acos", header: "<math.h>",
noSideEffect.}```

Computes the arc cosine of x.

```echo radToDeg(arccos(0.0)) ## 90.0
Source Edit
```proc arcsin(x: float32): float32 {...}{.importc: "asinf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arcsin(x: float64): float64 {...}{.importc: "asin", header: "<math.h>",
noSideEffect.}```

Computes the arc sine of x.

```echo radToDeg(arcsin(0.0)) ## 0.0
Source Edit
```proc arctan(x: float32): float32 {...}{.importc: "atanf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arctan(x: float64): float64 {...}{.importc: "atan", header: "<math.h>",
noSideEffect.}```

Calculate the arc tangent of x.

```echo arctan(1.0) ## 0.7853981633974483
Source Edit
```proc arctan2(y, x: float32): float32 {...}{.importc: "atan2f", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arctan2(y, x: float64): float64 {...}{.importc: "atan2", header: "<math.h>",
noSideEffect.}```

Calculate the arc tangent of y / x.

It produces correct results even when the resulting angle is near pi/2 or -pi/2 (x near 0).

```echo arctan2(1.0, 0.0) ## 1.570796326794897
Source Edit
```proc arcsinh(x: float32): float32 {...}{.importc: "asinhf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arcsinh(x: float64): float64 {...}{.importc: "asinh", header: "<math.h>",
noSideEffect.}```
Computes the inverse hyperbolic sine of x.   Source Edit
```proc arccosh(x: float32): float32 {...}{.importc: "acoshf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arccosh(x: float64): float64 {...}{.importc: "acosh", header: "<math.h>",
noSideEffect.}```
Computes the inverse hyperbolic cosine of x.   Source Edit
```proc arctanh(x: float32): float32 {...}{.importc: "atanhf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc arctanh(x: float64): float64 {...}{.importc: "atanh", header: "<math.h>",
noSideEffect.}```
Computes the inverse hyperbolic tangent of x.   Source Edit
`proc cot[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the cotangent of x (1 / tan(x)).   Source Edit
`proc sec[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the secant of x (1 / cos(x)).   Source Edit
`proc csc[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the cosecant of x (1 / sin(x)).   Source Edit
`proc coth[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the hyperbolic cotangent of x (1 / tanh(x)).   Source Edit
`proc sech[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the hyperbolic secant of x (1 / cosh(x)).   Source Edit
`proc csch[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the hyperbolic cosecant of x (1 / sinh(x)).   Source Edit
`proc arccot[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse cotangent of x.   Source Edit
`proc arcsec[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse secant of x.   Source Edit
`proc arccsc[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse cosecant of x.   Source Edit
`proc arccoth[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse hyperbolic cotangent of x.   Source Edit
`proc arcsech[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse hyperbolic secant of x.   Source Edit
`proc arccsch[T: float32 | float64](x: T): T {...}{.noSideEffect.}`
Computes the inverse hyperbolic cosecant of x.   Source Edit
```proc hypot(x, y: float32): float32 {...}{.importc: "hypotf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc hypot(x, y: float64): float64 {...}{.importc: "hypot", header: "<math.h>",
noSideEffect.}```
Computes the hypotenuse of a right-angle triangle with x and y as its base and height. Equivalent to sqrt(x*x + y*y).
`echo hypot(4.0, 3.0) ## 5.0`
Source Edit
```proc pow(x, y: float32): float32 {...}{.importc: "powf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc pow(x, y: float64): float64 {...}{.importc: "pow", header: "<math.h>",
noSideEffect.}```

Computes x to power raised of y.

To compute power between integers (e.g. 2^6), use ^ proc.

```echo pow(100, 1.5)  ## 1000.0
echo pow(16.0, 0.5) ## 4.0```
Source Edit
```proc erf(x: float32): float32 {...}{.importc: "erff", header: "<math.h>",
noSideEffect.}```
Source Edit
`proc erf(x: float64): float64 {...}{.importc: "erf", header: "<math.h>", noSideEffect.}`

Computes the error function for x.

Note: Not available for JS backend.

Source Edit
```proc erfc(x: float32): float32 {...}{.importc: "erfcf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc erfc(x: float64): float64 {...}{.importc: "erfc", header: "<math.h>",
noSideEffect.}```

Computes the complementary error function for x.

Note: Not available for JS backend.

Source Edit
```proc gamma(x: float32): float32 {...}{.importc: "tgammaf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc gamma(x: float64): float64 {...}{.importc: "tgamma", header: "<math.h>",
noSideEffect.}```

Computes the the gamma function for x.

Note: Not available for JS backend.

```echo gamma(1.0)  # 1.0
echo gamma(4.0)  # 6.0
echo gamma(11.0) # 3628800.0
echo gamma(-1.0) # nan```
Source Edit
```proc lgamma(x: float32): float32 {...}{.importc: "lgammaf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc lgamma(x: float64): float64 {...}{.importc: "lgamma", header: "<math.h>",
noSideEffect.}```

Computes the natural log of the gamma function for x.

Note: Not available for JS backend.

```echo lgamma(1.0)  # 1.0
echo lgamma(4.0)  # 1.791759469228055
echo lgamma(11.0) # 15.10441257307552
echo lgamma(-1.0) # inf```
Source Edit
```proc floor(x: float32): float32 {...}{.importc: "floorf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc floor(x: float64): float64 {...}{.importc: "floor", header: "<math.h>",
noSideEffect.}```

Computes the floor function (i.e., the largest integer not greater than x).

```echo floor(2.1)  ## 2.0
echo floor(2.9)  ## 2.0
echo floor(-3.5) ## -4.0```
Source Edit
```proc ceil(x: float32): float32 {...}{.importc: "ceilf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc ceil(x: float64): float64 {...}{.importc: "ceil", header: "<math.h>",
noSideEffect.}```

Computes the ceiling function (i.e., the smallest integer not smaller than x).

```echo ceil(2.1)  ## 3.0
echo ceil(2.9)  ## 3.0
echo ceil(-2.1) ## -2.0```
Source Edit
```proc round(x: float32): float32 {...}{.importc: "roundf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc round(x: float64): float64 {...}{.importc: "round", header: "<math.h>",
noSideEffect.}```

Rounds a float to zero decimal places.

Used internally by the round proc when the specified number of places is 0.

```echo round(3.4) ## 3.0
echo round(3.5) ## 4.0
echo round(4.5) ## 5.0```
Source Edit
```proc trunc(x: float32): float32 {...}{.importc: "truncf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc trunc(x: float64): float64 {...}{.importc: "trunc", header: "<math.h>",
noSideEffect.}```

Truncates x to the decimal point.

```echo trunc(PI) # 3.0
echo trunc(-1.85) # -1.0```
Source Edit
```proc `mod`(x, y: float32): float32 {...}{.importc: "fmodf", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc `mod`(x, y: float64): float64 {...}{.importc: "fmod", header: "<math.h>",
noSideEffect.}```

Computes the modulo operation for float values (the remainder of x divided by y).

```( 6.5 mod  2.5) ==  1.5
(-6.5 mod  2.5) == -1.5
( 6.5 mod -2.5) ==  1.5
(-6.5 mod -2.5) == -1.5```
Source Edit
`proc round[T: float32 | float64](x: T; places: int): T {...}{.noSideEffect.}`

Decimal rounding on a binary floating point number.

This function is NOT reliable. Floating point numbers cannot hold non integer decimals precisely. If places is 0 (or omitted), round to the nearest integral value following normal mathematical rounding rules (e.g. round(54.5) -> 55.0). If places is greater than 0, round to the given number of decimal places, e.g. round(54.346, 2) -> 54.350000000000001421…. If places is negative, round to the left of the decimal place, e.g. round(537.345, -1) -> 540.0

```echo round(PI, 2) ## 3.14
echo round(PI, 4) ## 3.1416```
Source Edit
`proc floorDiv[T: SomeInteger](x, y: T): T {...}{.noSideEffect.}`

Floor division is conceptually defined as floor(x / y).

This is different from the system.div operator, which is defined as trunc(x / y). That is, div rounds towards 0 and floorDiv rounds down.

```echo floorDiv( 13,  3) #  4
echo floorDiv(-13,  3) # -5
echo floorDiv( 13, -3) # -5
echo floorDiv(-13, -3) #  4```
Source Edit
`proc floorMod[T: SomeNumber](x, y: T): T {...}{.noSideEffect.}`

Floor modulus is conceptually defined as x - (floorDiv(x, y) * y).

This proc behaves the same as the % operator in Python.

```echo floorMod( 13,  3) #  1
echo floorMod(-13,  3) #  2
echo floorMod( 13, -3) # -2
echo floorMod(-13, -3) # -1```
Source Edit
```proc c_frexp(x: float32; exponent: var int32): float32 {...}{.importc: "frexp",
Source Edit
```proc c_frexp(x: float64; exponent: var int32): float64 {...}{.importc: "frexp",
Source Edit
`proc frexp[T, U](x: T; exponent: var U): T {...}{.noSideEffect.}`

Split a number into mantissa and exponent.

frexp calculates the mantissa m (a float greater than or equal to 0.5 and less than 1) and the integer value n such that x (the original float value) equals m * 2**n. frexp stores n in exponent and returns m.

```var x: int
echo frexp(5.0, x) # 0.625
echo x # 3```
Source Edit
```proc log2(x: float32): float32 {...}{.importc: "log2f", header: "<math.h>",
noSideEffect.}```
Source Edit
```proc log2(x: float64): float64 {...}{.importc: "log2", header: "<math.h>",
noSideEffect.}```

Computes the binary logarithm (base 2) of x.

```echo log2(8.0)  # 3.0
echo log2(1.0)  # 0.0
echo log2(0.0)  # -inf
echo log2(-2.0) # nan```
Source Edit
```proc splitDecimal[T: float32 | float64](x: T): tuple[intpart: T, floatpart: T] {...}{.
noSideEffect.}```

Breaks x into an integer and a fractional part.

Returns a tuple containing intpart and floatpart representing the integer part and the fractional part respectively.

Both parts have the same sign as x. Analogous to the modf function in C.

```echo splitDecimal(5.25)  # (intpart: 5.0, floatpart: 0.25)
echo splitDecimal(-2.73) # (intpart: -2.0, floatpart: -0.73)```
Source Edit
`proc degToRad[T: float32 | float64](d: T): T {...}{.inline.}`

`echo degToRad(180.0) # 3.141592653589793`
Source Edit
`proc radToDeg[T: float32 | float64](d: T): T {...}{.inline.}`

`echo degToRad(2 * PI) # 360.0`
Source Edit
`proc sgn[T: SomeNumber](x: T): int {...}{.inline.}`

Sign function.

Returns:

• -1 for negative numbers and NegInf,
• 1 for positive numbers and Inf,
• 0 for positive zero, negative zero and NaN
```echo sgn(5)    # 1
echo sgn(0)    # 0
echo sgn(-4.1) # -1```
Source Edit
`proc `^`[T: SomeNumber](x: T; y: Natural): T`

Computes x to the power y.

Exponent y must be non-negative, use pow proc for negative exponents.

Example:

```assert -3.0^0 == 1.0
assert -3^1 == -3
assert -3^2 == 9
assert -3.0^3 == -27.0
assert -3.0^4 == 81.0```
Source Edit
`proc gcd[T](x, y: T): T`

Computes the greatest common (positive) divisor of x and y.

Note that for floats, the result cannot always be interpreted as "greatest decimal z such that z*N == x and z*M == y where N and M are positive integers."

Example:

`doAssert gcd(13.5, 9.0) == 4.5`
Source Edit
`proc gcd(x, y: SomeInteger): SomeInteger`

Computes the greatest common (positive) divisor of x and y, using binary GCD (aka Stein's) algorithm.

Example:

```doAssert gcd(12, 8) == 4
doAssert gcd(17, 63) == 1```
Source Edit
`proc gcd[T](x: openArray[T]): T`

Computes the greatest common (positive) divisor of the elements of x.

Example:

`doAssert gcd(@[13.5, 9.0]) == 4.5`
Source Edit
`proc lcm[T](x, y: T): T`

Computes the least common multiple of x and y.

Example:

```doAssert lcm(24, 30) == 120
doAssert lcm(13, 39) == 39```
Source Edit
`proc lcm[T](x: openArray[T]): T`

Computes the least common multiple of the elements of x.

`doAssert lcm(@[24, 30]) == 120`