## Abstract

Basic mathematical modules and functions.

## Synopsis

module type from_prim = {
 type t val i8 : i8 -> t val i16 : i16 -> t val i32 : i32 -> t val i64 : i64 -> t val u8 : u8 -> t val u16 : u16 -> t val u32 : u32 -> t val u64 : u64 -> t val f16 : f16 -> t val f32 : f32 -> t val f64 : f64 -> t val bool : bool -> t
}
module type numeric = {
 include from_prim val + : t -> t -> t val - : t -> t -> t val * : t -> t -> t val / : t -> t -> t val % : t -> t -> t val ** : t -> t -> t val to_i64 : t -> i64 val == : t -> t -> bool val < : t -> t -> bool val > : t -> t -> bool val <= : t -> t -> bool val >= : t -> t -> bool val != : t -> t -> bool val neg : t -> t val max : t -> t -> t val min : t -> t -> t val abs : t -> t val sgn : t -> t val highest : t val lowest : t val sum [n]: [n]t -> t val product [n]: [n]t -> t val maximum [n]: [n]t -> t val minimum [n]: [n]t -> t
}
module type integral = {
 include numeric val // : t -> t -> t val %% : t -> t -> t val & : t -> t -> t val | : t -> t -> t val ^ : t -> t -> t val not : t -> t val << : t -> t -> t val >> : t -> t -> t val >>> : t -> t -> t val num_bits : i32 val get_bit : i32 -> t -> i32 val set_bit : i32 -> t -> i32 -> t val popc : t -> i32 val mul_hi : (x: t) -> (y: t) -> t val mad_hi : (a: t) -> (b: t) -> (c: t) -> t val clz : t -> i32 val ctz : t -> i32
}
module type real = {
 include numeric val recip : t -> t val from_fraction : i64 -> i64 -> t val to_i64 : t -> i64 val to_f64 : t -> f64 val sqrt : t -> t val cbrt : t -> t val exp : t -> t val sin : t -> t val cos : t -> t val tan : t -> t val asin : t -> t val acos : t -> t val atan : t -> t val sinh : t -> t val cosh : t -> t val tanh : t -> t val asinh : t -> t val acosh : t -> t val atanh : t -> t val atan2 : t -> t -> t val hypot : t -> t -> t val gamma : t -> t val lgamma : t -> t val erf : t -> t val erfc : t -> t val lerp : t -> t -> t -> t val log : t -> t val log2 : t -> t val log10 : t -> t val ceil : t -> t val floor : t -> t val trunc : t -> t val round : t -> t val mad : (a: t) -> (b: t) -> (c: t) -> t val fma : (a: t) -> (b: t) -> (c: t) -> t val isinf : t -> bool val isnan : t -> bool val inf : t val nan : t val pi : t val e : t
}
module type float = {
 include real type int_t val from_bits : int_t -> t val to_bits : t -> int_t val num_bits : i32 val get_bit : i32 -> t -> i32 val set_bit : i32 -> t -> i32 -> t val epsilon : t
}
module bool: from_prim with t = bool
module i8: (integral with t = i8)
module i16: (integral with t = i16)
module i32: (integral with t = i32)
module i64: (integral with t = i64)
module u8: (integral with t = u8)
module u16: (integral with t = u16)
module u32: (integral with t = u32)
module u64: (integral with t = u64)
module f64: (float with t = f64 with int_t = u64)
module f32: (float with t = f32 with int_t = u32)
module f16: (float with t = f16 with int_t = u16)

## Description

module type from_prim

Describes types of values that can be created from the primitive numeric types (and bool).

type t
val i8: i8 -> t
val i16: i16 -> t
val i32: i32 -> t
val i64: i64 -> t
val u8: u8 -> t
val u16: u16 -> t
val u32: u32 -> t
val u64: u64 -> t
val f16: f16 -> t
val f32: f32 -> t
val f64: f64 -> t
val bool: bool -> t
module type numeric

A basic numeric module type that can be implemented for both integers and rational numbers.

include from_prim
val +: t -> t -> t
val -: t -> t -> t
val *: t -> t -> t
val /: t -> t -> t
val %: t -> t -> t
val **: t -> t -> t
val to_i64: t -> i64
val ==: t -> t -> bool
val <: t -> t -> bool
val >: t -> t -> bool
val <=: t -> t -> bool
val >=: t -> t -> bool
val !=: t -> t -> bool
val neg: t -> t

Arithmetic negation (use `!` for bitwise negation).

val max: t -> t -> t
val min: t -> t -> t
val abs: t -> t
val sgn: t -> t

Sign function. Produces -1, 0, or 1 if the argument is respectively less than, equal to, or greater than zero.

val highest: t

The most positive representable number.

val lowest: t

The least positive representable number (most negative for signed types).

val sum [n]: [n]t -> t

Returns zero on empty input.

val product [n]: [n]t -> t

Returns one on empty input.

val maximum [n]: [n]t -> t

Returns `lowest` on empty input.

val minimum [n]: [n]t -> t

Returns `highest` on empty input.

module type integral

An extension of `numeric` that provides facilities that are only meaningful for integral types.

include numeric
val //: t -> t -> t

Like `/`, but rounds towards zero. This only matters when one of the operands is negative. May be more efficient.

val %%: t -> t -> t

Like `%`, but rounds towards zero. This only matters when one of the operands is negative. May be more efficient.

val &: t -> t -> t
val |: t -> t -> t
val ^: t -> t -> t
val not: t -> t

Bitwise negation.

val <<: t -> t -> t
val >>: t -> t -> t
val >>>: t -> t -> t
val num_bits: i32
val get_bit: i32 -> t -> i32
val set_bit: i32 -> t -> i32 -> t
val popc: t -> i32

Count number of one bits.

val mul_hi: (x: t) -> (y: t) -> t

Computes `x * y` and returns the high half of the product of x and y.

val mad_hi: (a: t) -> (b: t) -> (c: t) -> t

Computes `mul_hi a b + c`, but perhaps in a more efficient way, depending on the target platform.

val clz: t -> i32

Count number of zero bits preceding the most significant set bit. Returns the number of bits in the type if the argument is zero.

val ctz: t -> i32

Count number of trailing zero bits following the least significant set bit. Returns the number of bits in the type if the argument is zero.

module type real

Numbers that model real numbers to some degree.

include numeric
val recip: t -> t

Multiplicative inverse.

val from_fraction: i64 -> i64 -> t
val to_i64: t -> i64
val to_f64: t -> f64
val sqrt: t -> t

Square root.

val cbrt: t -> t

Cube root.

val exp: t -> t
val sin: t -> t
val cos: t -> t
val tan: t -> t
val asin: t -> t
val acos: t -> t
val atan: t -> t
val sinh: t -> t
val cosh: t -> t
val tanh: t -> t
val asinh: t -> t
val acosh: t -> t
val atanh: t -> t
val atan2: t -> t -> t
val hypot: t -> t -> t

Compute the length of the hypotenuse of a right-angled triangle. That is, `hypot x y` computes √(x²+y²). Put another way, the distance of (x,y) from origin in an Euclidean space. The calculation is performed without undue overflow or underflow during intermediate steps (specific accuracy depends on the backend).

val gamma: t -> t

The true Gamma function.

val lgamma: t -> t

The natural logarithm of the absolute value of `gamma`.

val erf: t -> t

The error function.

val erfc: t -> t

The complementary error function.

val lerp: t -> t -> t -> t

Linear interpolation. The third argument must be in the range `[0,1]` or the results are unspecified.

val log: t -> t

Natural logarithm.

val log2: t -> t

Base-2 logarithm.

val log10: t -> t

Base-10 logarithm.

val ceil: t -> t

Round towards infinity.

val floor: t -> t

Round towards negative infinity.

val trunc: t -> t

Round towards zero.

val round: t -> t

Round to the nearest integer, with halfway cases rounded to the nearest even integer. Note that this differs from `round()` in C, but matches more modern languages.

val mad: (a: t) -> (b: t) -> (c: t) -> t

Computes `a*b+c`. Depending on the compiler backend, this may be fused into a single operation that is faster but less accurate. Do not confuse it with `fma`.

val fma: (a: t) -> (b: t) -> (c: t) -> t

Computes `a*b+c`, with `a*b` being rounded with infinite precision. Rounding of intermediate products shall not occur. Edge case behavior is per the IEEE 754-2008 standard.

val isinf: t -> bool
val isnan: t -> bool
val inf: t
val nan: t
val pi: t
val e: t
module type float

An extension of `real` that further gives access to the bitwise representation of the underlying number. It is presumed that this will be some form of IEEE float.

Conversion of floats to integers is by truncation. If an infinity or NaN is converted to an integer, the result is zero.

include real
type int_t

An unsigned integer type containing the same number of bits as 't'.

val from_bits: int_t -> t
val to_bits: t -> int_t
val num_bits: i32
val get_bit: i32 -> t -> i32
val set_bit: i32 -> t -> i32 -> t
val epsilon: t

The difference between 1.0 and the next larger representable number.

module bool

Boolean numbers. When converting from a number to `bool`, 0 is considered `false` and any other value is `true`.

module i8
module i16
module i32
module i64
module u8
module u16
module u32
module u64
module f64
module f32
module f16

Emulated with single precision on systems that do not natively support half precision. This means you might get more accurate results than on real systems, but it is also likely to be significantly slower than just using `f32` in the first place.