# gizlang:math

IEEE 754 primitives and general numerical kernels. `import * as Math from "gizlang:math"` gives `Math.floor(x)`; sqrt is built in. libm domain errors are NaN, not faults.

```gizlang
import * as Math from "gizlang:math";
```

## Types

### `CompensatedSum`

```gizlang
type CompensatedSum = { total: f64; correction: f64; }
```

Compensated linear combination; a refused term leaves the state unchanged.

- `total`: `f64`
- `correction`: `f64`

## Functions

### `floor`

```gizlang
function floor(x: f64): f64 effects {} from "m"
```

The largest integer not greater than X.

### `ceil`

```gizlang
function ceil(x: f64): f64 effects {} from "m"
```

The smallest integer not less than X.

### `trunc`

```gizlang
function trunc(x: f64): f64 effects {} from "m"
```

X without its fraction (rounded toward zero).

### `fmod`

```gizlang
function fmod(x: f64, y: f64): f64 effects {} from "m"
```

The remainder of X divided by Y, with the sign of X (C fmod).

### `fabs`

```gizlang
function fabs(x: f64): f64 effects {} from "m"
```

The absolute value of X.

### `pow`

```gizlang
function pow(x: f64, y: f64): f64 effects {} from "m"
```

X to the power Y.

### `exp`

```gizlang
function exp(x: f64): f64 effects {} from "m"
```

e to the power X.

### `log`

```gizlang
function log(x: f64): f64 effects {} from "m"
```

The natural logarithm of X.

### `log2`

```gizlang
function log2(x: f64): f64 effects {} from "m"
```

The base-2 logarithm of X.

### `log10`

```gizlang
function log10(x: f64): f64 effects {} from "m"
```

The base-10 logarithm of X.

### `sin`

```gizlang
function sin(x: f64): f64 effects {} from "m"
```

The sine of X (radians).

### `cos`

```gizlang
function cos(x: f64): f64 effects {} from "m"
```

The cosine of X (radians).

### `tan`

```gizlang
function tan(x: f64): f64 effects {} from "m"
```

The tangent of X (radians).

### `asin`

```gizlang
function asin(x: f64): f64 effects {} from "m"
```

The arc sine of X, in radians.

### `acos`

```gizlang
function acos(x: f64): f64 effects {} from "m"
```

The arc cosine of X, in radians.

### `atan`

```gizlang
function atan(x: f64): f64 effects {} from "m"
```

The arc tangent of X, in radians.

### `atan2`

```gizlang
function atan2(y: f64, x: f64): f64 effects {} from "m"
```

The angle of the point (X, Y) from the X axis, in radians (-π to π).

### `hypot`

```gizlang
function hypot(x: f64, y: f64): f64 effects {} from "m"
```

The length of the vector (X, Y), without overflow in the squares.

### `scalbn`

```gizlang
function scalbn(x: f64, exponent: i32): f64 effects {} from "m"
```

Scale by an integer power of two without constructing an overflowing intermediate power.

### `cbrt`

```gizlang
function cbrt(x: f64): f64 effects {} from "m"
```

The cube root of X.

### `sinh`

```gizlang
function sinh(x: f64): f64 effects {} from "m"
```

Hyperbolic sine (libm).

### `cosh`

```gizlang
function cosh(x: f64): f64 effects {} from "m"
```

Hyperbolic cosine (libm).

### `tanh`

```gizlang
function tanh(x: f64): f64 effects {} from "m"
```

Hyperbolic tangent (libm).

### `asinh`

```gizlang
function asinh(x: f64): f64 effects {} from "m"
```

Inverse hyperbolic sine (libm).

### `acosh`

```gizlang
function acosh(x: f64): f64 effects {} from "m"
```

Inverse hyperbolic cosine (libm).

### `atanh`

```gizlang
function atanh(x: f64): f64 effects {} from "m"
```

Inverse hyperbolic tangent (libm).

### `expm1`

```gizlang
function expm1(x: f64): f64 effects {} from "m"
```

e**x - 1, exact near 0 (libm).

### `log1p`

```gizlang
function log1p(x: f64): f64 effects {} from "m"
```

log(1 + x), exact near 0 (libm).

### `rint`

```gizlang
function rint(x: f64): f64 effects {} from "m"
```

X rounded to an integer, ties to even (libm).

### `erf`

```gizlang
function erf(x: f64): f64 effects {} from "m"
```

The error function and its complement, Gamma and log|Gamma| (libm).

### `erfc`

```gizlang
function erfc(x: f64): f64 effects {} from "m"
```

The complementary error function, 1 - erf(X).

### `tgamma`

```gizlang
function tgamma(x: f64): f64 effects {} from "m"
```

The gamma function of X.

### `lgamma`

```gizlang
function lgamma(x: f64): f64 effects {} from "m"
```

The natural logarithm of the absolute value of the gamma function of X.

### `copysign`

```gizlang
function copysign(x: f64, y: f64): f64 effects {} from "m"
```

X with the sign of Y (libm).

### `nextafter`

```gizlang
function nextafter(x: f64, y: f64): f64 effects {} from "m"
```

The next double after X toward Y.

### `abs`

```gizlang
function abs(x: f64): f64
```

The absolute value of X.

### `roundF32`

```gizlang
function roundF32(x: f64): f64
```

X rounded to the nearest binary32 value (as an `f32` field stores it), as an f64.

Effects: fail.

### `roundBf16`

```gizlang
function roundBf16(x: f64): f64
```

X rounded to the nearest bfloat16 value (ties to even), as an f64.

Effects: fail.

### `halfBits`

```gizlang
function halfBits(x: f64): u64
```

The bits of the IEEE half nearest x (ties to even; finite x below 65520 in magnitude).

Effects: fail.

### `halfValue`

```gizlang
function halfValue(h: u64): f64
```

The value of IEEE half bits h.

Effects: fail.

### `e4m3Bits`

```gizlang
function e4m3Bits(x: f64): u64
```

The FP8 E4M3 (OCP) byte nearest x, as gizhw:kernel stores it: ties to even (below 2^-6 a multiple of 2^-9),
saturated at ±448 (0x7E), NaN 0x7F; the sign kept.

Effects: fail.

### `e4m3Value`

```gizlang
function e4m3Value(b: u64): f64
```

The value of FP8 E4M3 (OCP) byte b: bias 7, no infinities, 0x7F and 0xFF NaN.

Effects: fail.

### `sigmoid`

```gizlang
function sigmoid(z: f64): f64
```

The logistic function 1 / (1 + e^-z), without overflow for large |z|.

### `silu`

```gizlang
function silu(x: f64): f64
```

x times its sigmoid, x / (1 + e^-x) (SiLU, swish).

### `softplus`

```gizlang
function softplus(x: f64): f64
```

ln(1 + e^x), x itself above 20 (where they meet in f64 to 1e-9).

### `isFinite`

```gizlang
function isFinite(x: f64): bool
```

True for finite IEEE 754 numbers; NaN and both infinities are false.

Effects: fail.

### `isNaN`

```gizlang
function isNaN(x: f64): bool
```

Whether X is NaN, as TypeScript's Number.isNaN.

### `isInteger`

```gizlang
function isInteger(x: f64): bool
```

Whether X is finite and has no fraction, as TypeScript's Number.isInteger.

Effects: fail.

### `round`

```gizlang
function round(x: f64): f64
```

Halves round up, as JavaScript's Math.round (round(-2.5) is -2).

### `min`

```gizlang
function min(a: f64, b: f64): f64
```

The smaller of A and B.

### `max`

```gizlang
function max(a: f64, b: f64): f64
```

The larger of A and B.

### `minI64`

```gizlang
function minI64(a: i64, b: i64): i64
```

The smaller and the larger of two integers.

### `maxI64`

```gizlang
function maxI64(a: i64, b: i64): i64
```

The larger of A and B.

### `floorDiv`

```gizlang
function floorDiv(a: i64, b: i64): i64
```

Integer division rounded toward negative infinity (floorDiv(-1, 86400) is
-1, where `/` truncates to 0): what day, era or bucket a value falls in.

Effects: fail.

### `addCompensated`

```gizlang
function addCompensated(state: mut CompensatedSum, term: f64): bool
```

Adds TERM to the compensated sum STATE; false, with STATE unchanged, when TERM or the total is not finite.

Effects: fail.

## Methods

### `f64.pow`

```gizlang
function f64.pow(self: f64, exponent: f64): f64
```

`x ** y` (TypeScript's exponent operator, which the parser makes this call): libm pow.

### `i64.pow`

```gizlang
function i64.pow(self: i64, exponent: i64): i64 requires exponent> = 0 { let result = 1
```

`n ** e` on integers, by squaring. An overflow fails, as `*` does.

Effects: fail.

## Constants

### `PI`

```gizlang
const PI = 3.141592653589793
```

gizlang:math: IEEE 754 primitives and general numerical kernels.
`import * as Math from "gizlang:math"` gives `Math.floor(x)`; sqrt is
built in. libm domain errors are NaN, not faults.

### `E`

```gizlang
const E = 2.718281828459045
```

Euler's number e.

### `I64_MAX`

```gizlang
const I64_MAX = 9223372036854775807
```

Largest signed 64-bit integer, for arithmetic overflow checks.

### `F64_EPSILON`

```gizlang
const F64_EPSILON = 2.220446049250313e-16
```

The distance from 1.0 to the next f64, 2^-52.

### `F64_MAX_EXACT_INTEGER`

```gizlang
const F64_MAX_EXACT_INTEGER = 9007199254740991
```

The largest integer that an f64 holds exactly, 2^53 - 1.

### `F64_FRACTION_BITS`

```gizlang
const F64_FRACTION_BITS = 52u
```

The number of fraction bits of an f64.

### `F64_EXPONENT_MASK`

```gizlang
const F64_EXPONENT_MASK = 2047u
```

The mask of the 11 exponent bits of an f64, after the shift.

### `F64_FRACTION_MASK`

```gizlang
const F64_FRACTION_MASK = 4503599627370495u
```

The mask of the 52 fraction bits of an f64.

### `F64_IMPLICIT_BIT`

```gizlang
const F64_IMPLICIT_BIT = 4503599627370496u
```

The implicit leading bit of a normal f64's significand, 2^52.

### `F64_EXPONENT_BIAS`

```gizlang
const F64_EXPONENT_BIAS = 1023
```

The bias of the exponent of an f64.

### `F64_SUBNORMAL_SCALE`

```gizlang
const F64_SUBNORMAL_SCALE = 1022
```

The exponent scale of a subnormal f64.

### `F64_MIN_QUANTUM_EXPONENT`

```gizlang
const F64_MIN_QUANTUM_EXPONENT = -1074
```

The exponent of the smallest positive f64, 2^-1074.