Math builtins

54 builtins of Soma 3.2.4 in the category Math, with their exact signatures, as soma describe --builtins --json prints them.

• to_fixed
• div_round
• floor_div
• mod
• divmod
• abs
• round
• floor
• ceil
• sqrt
• sin
• cos
• tan
• atan
• atan2
• asin
• acos
• pi
• log
• ln
• exp
• log10
• pow
• ipow
• min
• max
• sum
• product
• avg
• parse_int
• parse_float
• idiv
• clamp
• random
• gcd
• sqrt_int
• pow_mod
• band
• bor
• bxor
• bnot
• shl
• shr
• bit_test
• bit_set
• bit_clr
• bit_next
• bit_len
• median
• pstdev
• stddev
• stdev
• variance
• pvariance

to_fixed

to_fixed(x: Float, digits: Int) -> String

x with exactly digits decimals ("%.2f"), rounded half away from zero on the decimal text: to_fixed(1.005, 2) = "1.01".

deterministic · replay: pure

div_round

div_round(n: Int, d: Int) -> Int

Exact integer division rounded to the nearest, half away from zero (BigDecimal HALF_UP): div_round(10125 * 600, 120000) == 51, div_round(-7, 2) == -4. Money in cents stays exact.

deterministic · replay: pure

Used in verified programs:

• escrow_finance/loan_amortization, line 49: return div_round(p * r, 120000) // bps annual -> one month, rounded HALF_UP (BigDecimal style)

floor_div

floor_div(a: Int, b: Int) -> Int

Division rounded toward -∞ (Ruby/Python //): floor_div(-150, 100) = -2. idiv truncates toward zero; / is exact.

deterministic · replay: pure

mod

mod(a: Int, b: Int) -> Int

Modulo with the DIVISOR's sign (Ruby/Python %): mod(-150, 100) = 50. The % operator keeps the dividend's sign (C/Rust): -150 % 100 = -50.

deterministic · replay: pure

divmod

divmod(a: Int, b: Int) -> [q, r]

[floor_div(a, b), mod(a, b)] — q * b + r == a, with r taking the DIVISOR's sign (|r| < |b|): divmod(7, -3) = [-3, -2].

deterministic · replay: pure

abs

abs(x: Int|Float) -> Int|Float

Absolute value, arbitrary precision (abs(-9223372036854775808) is 9223372036854775808).

deterministic · replay: pure

Used in verified programs:

• algorithms/gcd_lcm, line 19: let x = abs(a)
• finance/bond_pricer, line 29: if abs(price - face_val) < 0.01 { return "par" }
• finance/compound_interest, line 37: assert abs(future_value(1000.0, 0.05, 2) - 1102.5) < 0.001
• finance/currency_converter, line 50: assert abs(to_usd("EUR", 100.0) - 108.695652) < 0.001

round

round(x: Float) -> Int | round(x: Float, digits: Int) -> Float

Round half away from zero to the nearest integer, or keep digits decimals: round(2.345, 2) = 2.35.

deterministic · replay: pure

Used in verified programs:

• math/fibonacci, line 35: return round((pow(phi, n) - pow(psi, n)) / sqrt(5.0))

floor

floor(x: Float) -> Int

Largest integer <= x.

deterministic · replay: pure

Used in verified programs:

• agents/react_calculator, line 33: if floor(k / d) * d == k { is_prime = false break }
• algorithms/binary_search_list, line 18: let mid = floor((lo + hi) / 2)
• algorithms/gcd_lcm, line 23: y = x - floor(x / y) * y // x mod y
• algorithms/insertion_sort, line 32: let mid = floor((lo + hi) / 2)

ceil

ceil(x: Float) -> Int

Smallest integer >= x.

deterministic · replay: pure

sqrt

sqrt(x: Int|Float) -> Float

Square root.

deterministic · replay: pure

Used in verified programs:

• finance/returns_stats, line 24: return sqrt(acc / (len(rets) - 1))
• math/complex, line 33: return sqrt(x.re * x.re + x.im * x.im)
• math/fibonacci, line 33: let phi = (1.0 + sqrt(5.0)) / 2.0
• math/quadratic, line 26: let sq = sqrt(d)

sin

sin(x: Int|Float) -> Float

Sine (radians). Also cos, tan, atan, atan2(y, x).

deterministic · replay: pure

cos

cos(x: Int|Float) -> Float

Cosine (radians).

deterministic · replay: pure

tan

tan(x: Int|Float) -> Float

Tangent (radians).

deterministic · replay: pure

atan

atan(x: Int|Float) -> Float

Arc tangent.

deterministic · replay: pure

atan2

atan2(y: Float, x: Float) -> Float

Arc tangent of y/x, quadrant-aware.

deterministic · replay: pure

asin

asin(x: Float) -> Float

Arc sine (x in [-1, 1], else kind range).

deterministic · replay: pure

acos

acos(x: Float) -> Float

Arc cosine (x in [-1, 1], else kind range).

deterministic · replay: pure

pi

pi() -> Float

The constant π.

deterministic · replay: pure

log

log(x: Int|Float) -> Float

Natural logarithm.

deterministic · replay: pure

Used in verified programs:

• finance/compound_interest, line 30: return log(2.0) / log(1.0 + rate)

ln

ln(x: Int|Float) -> Float

Alias of log (natural logarithm).

deterministic · replay: pure

exp

exp(x: Int|Float) -> Float

e raised to the power x.

deterministic · replay: pure

Used in verified programs:

• finance/compound_interest, line 25: return principal * exp(rate * years)

log10

log10(x: Int|Float) -> Float

Base-10 logarithm.

deterministic · replay: pure

pow

pow(base: Int|Float, exp: Int|Float) -> Float

base raised to exp (always a Float; ipow for an exact Int power).

deterministic · replay: pure

Used in verified programs:

• finance/bond_pricer, line 17: pv = pv + coupon / pow(1.0 + ytm, t)
• finance/compound_interest, line 15: return principal * pow(1.0 + rate, years)
• finance/loan_amortization, line 16: let g = pow(1.0 + r, months)
• finance/npv, line 15: return cash / pow(1.0 + rate, period)

ipow

ipow(base: Int, exp: Int) -> Int

Exact Int power (exp ≥ 0; kind range past the Int size limit). to_int(pow(3, 40)) is off by 33, ipow(3, 40) is exact.

deterministic · replay: pure

min

min(a, b) -> Int|Float | min(list: List) -> Int|Float

Smaller of two numbers, or the minimum of a list (Float if any element is). An empty list gives () (no minimum exists).

deterministic · replay: pure

Used in verified programs:

• aerospace/unreliable_airspeed, line 61: let lo = min(a_kt, min(b_kt, c_kt))
• algorithms/edit_distance, line 32: dp[i][j] = min(list(
• finance/tax_brackets, line 29: let top = min(income, cap)
• games/war, line 33: let n = min(len(deck1), len(deck2))

max

max(a, b) -> Int|Float | max(list: List) -> Int|Float

Larger of two numbers, or the maximum of a list (Float if any element is). An empty list gives () (no maximum exists).

deterministic · replay: pure

Used in verified programs:

• aerospace/unreliable_airspeed, line 60: let hi = max(a_kt, max(b_kt, c_kt))
• algorithms/counting_sort, line 17: let hi = max(xs)
• algorithms/knapsack, line 35: dp[i][c] = max(skip, take)
• algorithms/lis, line 26: return max(dp)

sum

sum(list: List) -> Int|Float

Sum of a list of numbers (Int-exact unless any element is a Float); 0 when empty. Floats are added left to right without compensation (NumPy's pairwise / Python's fsum can differ in the last bits).

deterministic · replay: pure

Used in verified programs:

• finance/moving_average, line 28: return sum(prices) / len(prices)
• finance/portfolio_pnl, line 35: return sum(pnls)
• finance/returns_stats, line 14: return sum(rets) / len(rets)
• games/conway_life, line 38: return sum(grid)

product

product(list: List) -> Int|Float

Product of a list of numbers; 1 when empty.

deterministic · replay: pure

Used in verified programs:

• math/combinatorics, line 23: return product(range(1, n + 1))
• math/primes, line 72: assert product(factorize(360)) == 360
• math/quadratic, line 49: assert abs(product(roots(1.0, 0 - 5.0, 6.0)) - 6.0) < 0.0000001

avg

avg(list: List) -> Int|Float

Mean of a list of numbers: finite operands are averaged exactly before Float rounding, avoiding intermediate overflow and cancellation. An exact mean of Ints stays an Int; () when empty.

deterministic · replay: pure

Used in verified programs:

• records/employees, line 34: return avg(rows |> pluck("salary"))
• records/students, line 30: return avg(s.scores |> pluck("pts"))

parse_int

parse_int(s: String, base: Int?) -> Int | ()

Strict integer parse: () unless the WHOLE string is an integer ("1.5", "12abc", "" → ()). parse_int("ff", 16) = 255 (base 2..36, no 0x prefix). to_int() is lenient and truncates.

deterministic · replay: pure

parse_float

parse_float(s: String) -> Float | ()

Strict float parse: () unless the whole string is a finite number.

deterministic · replay: pure

idiv

idiv(a: Int, b: Int) -> Int

Integer division truncating toward zero; errors on division by zero.

deterministic · replay: pure

Used in verified programs:

• aerospace/unreliable_airspeed, line 70: let w = try { agreed_kt.set(id, idiv(a_kt + b_kt + c_kt, 3)) }
• civic/lottery, line 70: let idx = seed - idiv(seed, len(pool)) * len(pool)
• escrow_finance/vesting_schedule, line 58: return idiv(total * month, duration) // linear in between
• games_economy/wager_duel, line 77: let half = idiv(pot.get(duel) ?? 0, 2)

clamp

clamp(v, lo, hi) -> Int|Float

Constrain numeric v to [lo, hi] using exact Int/Float comparisons; return the selected operand with its type. Reject nonnumeric operands, reversed bounds and NaN bounds; a NaN value stays NaN.

deterministic · replay: pure

random

random() -> Float | random(max: Int) -> Int | random(min: Int, max: Int) -> Int

Time-seeded PRNG: float in [0,1), or int in [0,max) / [min,max). There is no seed: for reproducible runs write your own generator (an LCG over Ints), and for secrets use random_token().

not deterministic · replay: nondeterministic: replay reports it as a divergence source

Used in verified programs:

• agents/horde_rounds, line 50: let patience = random(30)
• math/monte_carlo_pi, line 22: let x = random()

gcd

gcd(a: Int, b: Int) -> Int

Greatest common divisor (Euclid, absolute values).

deterministic · replay: pure

Used in verified programs:

• algorithms/gcd_lcm, line 70: assert gcd_iter(48, 36) == gcd(48, 36)
• math/gcd_lcm, line 21: return idiv(a * b, gcd(a, b))

sqrt_int

sqrt_int(n: Int) -> Int

Integer square root; errors on negative input.

deterministic · replay: pure

pow_mod

pow_mod(base: Int, exp: Int, m: Int) -> Int

Modular exponentiation base^exp mod m; errors if m is zero.

deterministic · replay: pure

Used in verified programs:

• math/modular, line 22: return pow_mod(a, p - 1, p) == 1

band

band(a: Int, b: Int) -> Int

Bitwise AND.

deterministic · replay: pure

Used in verified programs:

• games/card_deck, line 39: state = band(state * 1103515245 + 12345, 2147483647)

bor

bor(a: Int, b: Int) -> Int

Bitwise OR.

deterministic · replay: pure

bxor

bxor(a: Int, b: Int) -> Int

Bitwise XOR.

deterministic · replay: pure

Used in verified programs:

• games/nim, line 23: x = bxor(x, h)

bnot

bnot(a: Int) -> Int

Bitwise NOT.

deterministic · replay: pure

shl

shl(a: Int, n: Int) -> Int

Exact left shift (a * 2^n), arbitrary precision like every Int op. For a 64-bit wrapping shift (xorshift), mask: band(shl(x, 13), M) with M = shl(1, 64) - 1 bound once (a literal beyond 64 bits is not allowed in [native]); values past 2^63 run [native] code in BigInt mode — prefer 32-bit xorshift masks for speed.

deterministic · replay: pure

shr

shr(a: Int, n: Int) -> Int

Arithmetic shift right by a nonnegative Int count; arbitrarily large counts give 0 (nonnegative a) or -1 (negative a).

deterministic · replay: pure

bit_test

bit_test(a: Int, i: Int) -> Int

1 if bit i of a is set, else 0.

deterministic · replay: pure

bit_set

bit_set(a: Int, i: Int) -> Int

a with bit i set.

deterministic · replay: pure

bit_clr

bit_clr(a: Int, i: Int) -> Int

a with bit i cleared.

deterministic · replay: pure

bit_next

bit_next(a: Int, i: Int) -> Int

Index of the lowest set bit at or above i, or -1 if none.

deterministic · replay: pure

bit_len

bit_len(a: Int) -> Int

Exact number of significant bits in the magnitude, including BigInt.

deterministic · replay: pure

median

median(xs: List) -> Int | Float

Order Int/Float values exactly and preserve the middle value (mean of the two middles for even n). An Int middle stays exact; any NaN input makes the result NaN.

deterministic · replay: pure

pstdev

pstdev(xs: List) -> Float

Population standard deviation (divide by n). Preserve finite and subnormal deviations even when their variance is outside Float range.

deterministic · replay: pure

stddev

stddev(xs: List) -> Float

Same as pstdev (population).

deterministic · replay: pure

stdev

stdev(xs: List) -> Float

SAMPLE standard deviation (divide by n - 1); needs two values. Preserve finite and subnormal deviations even when their variance is outside Float range.

deterministic · replay: pure

variance

variance(xs: List) -> Float

SAMPLE variance (divide by n - 1) — statistics.variance; pvariance is the population form.

deterministic · replay: pure

pvariance

pvariance(xs: List) -> Float

Population variance (divide by n) — statistics.pvariance.

deterministic · replay: pure