viva_math - v1.2.102

viva_math/scalar

Scalar mathematical functions.

This module provides pipeline-friendly scalar primitives commonly needed for ML / scientific computing. Where the Erlang stdlib already exposes a fast BIF (such as :math.erf/1, :math.erfc/1 or :math.fmod/2), we delegate through FFI rather than reimplementing.

Design rules

Erlang BIFs used (OTP 22+, confirmed on OTP 28)

:math.erf/1, :math.erfc/1, :math.fmod/2, :math.expm1/1, :math.log1p/1, :math.tanh/1, :math.exp/1, :math.log/1, :math.sqrt/1, :math.pow/2.

Values

acos

</> 
pub fn acos(x: Float) -> Float

Inverse cosine. Domain x ∈ [-1, 1]; outside crashes (BIF behaviour).

asin

</> 
pub fn asin(x: Float) -> Float

Inverse sine. Domain x ∈ [-1, 1]; outside crashes (BIF behaviour).

atan

</> 
pub fn atan(x: Float) -> Float

Single-argument arctangent. Delegates to :math.atan/1.

atan2

</> 
pub fn atan2(y: Float, x: Float) -> Float

Two-argument arctangent atan2(y, x).

cbrt

</> 
pub fn cbrt(x: Float) -> Float

Real cube root, defined for all x via sign(x) · |x|^(1/3).

clamp

</> 
pub fn clamp(x: Float, min: Float, max: Float) -> Float

Clamp to range [min, max].

clamp_bipolar

</> 
pub fn clamp_bipolar(x: Float) -> Float

Clamp to bipolar [-1, 1].

clamp_unit

</> 
pub fn clamp_unit(x: Float) -> Float

Clamp to unit [0, 1].

cos

</> 
pub fn cos(x: Float) -> Float

Cosine of x (radians). Delegates to :math.cos/1.

cube_root

</> 
pub fn cube_root(x: Float) -> Result(Float, Nil)

Real cube root with Result API for parity with square_root. Total over Float, so Ok always; kept for ergonomic chaining.

deg_to_rad

</> 
pub fn deg_to_rad(deg: Float) -> Float

Convert degrees to radians.

elu

</> 
pub fn elu(x: Float, alpha: Float) -> Float

ELU: x if x > 0 else α(e^x - 1).

erf

</> 
pub fn erf(x: Float) -> Float

Error function erf(x) = (2/√π) · ∫₀ˣ e^(-t²) dt.

Delegates to :math.erf/1 (Erlang stdlib BIF).

erfc

</> 
pub fn erfc(x: Float) -> Float

Complementary error function erfc(x) = 1 - erf(x).

Computed by methods that avoid cancellation for large x. Delegates to :math.erfc/1.

exp

</> 
pub fn exp(x: Float) -> Float

Natural exponential e^x. Delegates to :math.exp/1.

expm1

</> 
pub fn expm1(x: Float) -> Float

exp(x) - 1 accurate for small x.

Uses a 4-term Maclaurin series near zero (|x| < 1e-5) to avoid the catastrophic cancellation of exp(x) - 1.0. Falls back to the direct expression elsewhere. (Not all OTP builds ship :math.expm1/1, so we implement it portably.)

fmod

</> 
pub fn fmod(x: Float, y: Float) -> Float

Floating-point remainder x mod y (IEEE 754 fmod).

Delegates to :math.fmod/2.

gelu

</> 
pub fn gelu(x: Float) -> Float

GELU exact: x · Φ(x) using erf.

Φ(x) = ½ · (1 + erf(x / √2)). Used by BERT/GPT.

gelu_approx

</> 
pub fn gelu_approx(x: Float) -> Float

GELU tanh approximation (Hendrycks & Gimpel).

Faster, used by GPT-2/PaLM. Accurate to ~4 decimals.

hard_sigmoid

</> 
pub fn hard_sigmoid(x: Float) -> Float

Hard sigmoid: piecewise linear approximation of sigmoid.

Returns 0 for x ≤ -3, 1 for x ≥ 3, linear interpolation between.

hard_swish

</> 
pub fn hard_swish(x: Float) -> Float

Hard swish: x · hard_sigmoid(x). Used in MobileNetV3.

hard_tanh

</> 
pub fn hard_tanh(x: Float) -> Float

Hard tanh: clamps to [-1, 1].

hypot

</> 
pub fn hypot(x: Float, y: Float) -> Float

Hypotenuse √(x² + y²) without intermediate overflow.

iglu

</> 
pub fn iglu(x: Float, sigma: Float) -> Float

IGLU (Integrated Gaussian Linear Unit): continuous mixture of GELU activations under a Gaussian dispersion of “decision hardness”.

IGLU(x; σ) = x · Z(x; σ) where Z uses arctan-based gating. Provides smoother gradients than GELU near zero and heavier tails.

Reference: Aragón et al. (2026) “IGLU: An Integrated Gaussian Linear Activation Function” (arXiv:2603.06861).

iglu_approx

</> 
pub fn iglu_approx(x: Float, sigma: Float) -> Float

IGLU rational approximation — same qualitative behaviour as iglu without transcendental functions. Maximum deviation ~5 %.

Recommended when execution speed matters more than exact GELU shape (e.g. low-precision quantised inference).

lambda_gelu

</> 
pub fn lambda_gelu(x: Float, lambda: Float) -> Float

λ-GELU: hardness-parameterised GELU x · Φ(λx) with λ ≥ 1.

λ = 1 recovers standard GELU; λ → ∞ approaches ReLU. Useful for learnable activation hardness, hardware quantisation-friendly fine-tuning, and gradual ReLU substitution during training.

Reference: Cantos & Aragón (2026) “λ-GELU: A Hardness-Parameterised GELU for Smooth ReLU Substitution” (arXiv:2603.21991).

leaky_relu

</> 
pub fn leaky_relu(x: Float, negative_slope: Float) -> Float

Leaky ReLU: x if x > 0 else negative_slope · x.

lerp

</> 
pub fn lerp(a: Float, b: Float, t: Float) -> Float

Linear interpolation between a and b.

ln

</> 
pub fn ln(x: Float) -> Float

Natural logarithm ln(x). Domain x > 0.

log10

</> 
pub fn log10(x: Float) -> Float

Log base 10. Delegates to :math.log10/1. Domain x > 0.

log1p

</> 
pub fn log1p(x: Float) -> Float

log(1 + x) accurate for small x.

Uses a Maclaurin series near zero to avoid cancellation in ln(1.0 + x). Falls back to direct logarithm elsewhere.

log2

</> 
pub fn log2(x: Float) -> Float

Log base 2. Delegates to :math.log2/1. Domain x > 0.

logaddexp

</> 
pub fn logaddexp(a: Float, b: Float) -> Float

log(exp(a) + exp(b)) without overflow.

Uses the identity log(e^a + e^b) = max(a,b) + log(1 + exp(-|a-b|)). When a == b (including ±∞) short-circuits to avoid ∞ - ∞ → NaN.

logarithm

</> 
pub fn logarithm(x: Float) -> Result(Float, Nil)

Natural logarithm with domain check. Returns Error(Nil) for x ≤ 0.

logarithm_10

</> 
pub fn logarithm_10(x: Float) -> Result(Float, Nil)

Log base 10 with domain check. Returns Error(Nil) for x ≤ 0.

logarithm_2

</> 
pub fn logarithm_2(x: Float) -> Result(Float, Nil)

Log base 2 with domain check. Returns Error(Nil) for x ≤ 0.

logit

</> 
pub fn logit(p: Float) -> Float

Logit / inverse sigmoid: ln(p / (1 - p)). Domain p ∈ (0, 1).

logsumexp

</> 
pub fn logsumexp(xs: List(Float)) -> Float

log(Σ exp(xᵢ)) — log-sum-exp with max subtraction for stability.

Uses Neumaier compensated summation on the exp-shifted terms to retain precision when xᵢ values span many orders of magnitude.

mish

</> 
pub fn mish(x: Float) -> Float

Mish: x · tanh(softplus(x)).

nth_root

</> 
pub fn nth_root(x: Float, n: Int) -> Result(Float, Nil)

Generalised real n-th root (x^(1/n)) for integer n ≥ 1.

  • n = 1 → returns Ok(x).
  • n = 2 → uses square_root (errors for x < 0).
  • Odd n → defined for all real x (sign trick).
  • Even n > 2 → errors for x < 0; uses pow(x, 1/n) otherwise.
  • n ≤ 0 → Error(Nil).

pow

</> 
pub fn pow(x: Float, y: Float) -> Float

Power x^y.

rad_to_deg

</> 
pub fn rad_to_deg(rad: Float) -> Float

Convert radians to degrees.

relu

</> 
pub fn relu(x: Float) -> Float

ReLU: max(0, x).

safe_div

</> 
pub fn safe_div(a: Float, b: Float, default: Float) -> Float

Safe division.

safe_exp

</> 
pub fn safe_exp(x: Float) -> Float

Safe exp clamped to avoid overflow (exp(709) ≈ max_float).

safe_log

</> 
pub fn safe_log(x: Float, default: Float) -> Float

Safe natural log: returns default for non-positive input.

safe_sqrt

</> 
pub fn safe_sqrt(x: Float) -> Float

Safe square root: returns 0 for negative input.

selu

</> 
pub fn selu(x: Float) -> Float

SELU (self-normalizing). Scale and alpha from Klambauer et al. 2017.

sigmoid

</> 
pub fn sigmoid(x: Float) -> Float

Standard sigmoid σ(x) = 1 / (1 + e^(-x)).

sigmoid_k

</> 
pub fn sigmoid_k(x: Float, k: Float) -> Float

Generalized sigmoid with steepness k: σ(kx).

sign

</> 
pub fn sign(x: Float) -> Float

Sign function: -1, 0, or 1.

silu

</> 
pub fn silu(x: Float) -> Float

SiLU / Swish: x · σ(x).

sin

</> 
pub fn sin(x: Float) -> Float

Sine of x (radians). Delegates to :math.sin/1.

smootherstep

</> 
pub fn smootherstep(
  edge0: Float,
  edge1: Float,
  x: Float,
) -> Float

Smootherstep: quintic version (zero first and second derivatives at edges).

smoothstep

</> 
pub fn smoothstep(edge0: Float, edge1: Float, x: Float) -> Float

Smoothstep: cubic Hermite interpolation between edge0 and edge1.

When the edges coincide, behaves as a step at edge0.

softplus

</> 
pub fn softplus(x: Float) -> Float

Softplus: ln(1 + e^x). Smooth ReLU.

Uses safe identity for large x to avoid overflow: softplus(x) = max(x, 0) + log1p(exp(-|x|)).

sqrt

</> 
pub fn sqrt(x: Float) -> Float

Square root.

square_root

</> 
pub fn square_root(x: Float) -> Result(Float, Nil)

Square root with domain check. Returns Error(Nil) for x < 0.

step

</> 
pub fn step(threshold: Float, x: Float) -> Float

Step function: 0 if x < threshold, 1 otherwise.

swish

</> 
pub fn swish(x: Float) -> Float

Alias for silu. Used by Google’s original Swish paper.

tan

</> 
pub fn tan(x: Float) -> Float

Tangent of x (radians). Delegates to :math.tan/1.

tanh

</> 
pub fn tanh(x: Float) -> Float

Hyperbolic tangent. Delegates to :math.tanh/1.

try_cbrt

</> 
pub fn try_cbrt(x: Float) -> Result(Float, Nil)

Deprecated: Use `scalar.cube_root` instead.

Deprecated alias for cube_root.

try_ln

</> 
pub fn try_ln(x: Float) -> Result(Float, Nil)

Deprecated: Use `scalar.logarithm` instead.

Deprecated alias for logarithm.

try_log10

</> 
pub fn try_log10(x: Float) -> Result(Float, Nil)

Deprecated: Use `scalar.logarithm_10` instead.

Deprecated alias for logarithm_10.

try_log2

</> 
pub fn try_log2(x: Float) -> Result(Float, Nil)

Deprecated: Use `scalar.logarithm_2` instead.

Deprecated alias for logarithm_2.

try_nth_root

</> 
pub fn try_nth_root(x: Float, n: Int) -> Result(Float, Nil)

Deprecated: Use `scalar.nth_root` instead.

Deprecated alias for nth_root.

try_sqrt

</> 
pub fn try_sqrt(x: Float) -> Result(Float, Nil)

Deprecated: Use `scalar.square_root` instead.

Deprecated alias for square_root.

✨ Search Document