eml-stdlib 0.4.0__py3-none-any.whl

eml_stdlib/math/abs.eml

@@ -0,0 +1,45 @@
+// abs.eml -- |x|, sign, and clamp.
+//
+// All chain-order 0 -- pure piecewise linear. Listed in stdlib so
+// downstream kernels can reference them by their stable, qualified
+// names instead of relying on the parser-level builtin.
+
+module abs_module;
+
+@verify(lean, theorem = "abs_nonneg")
+fn abs_kernel(x: Real) -> Real
+    where chain_order <= 0
+    ensures (result >= 0.0)
+{
+    abs(x)
+}
+
+// Three-valued sign. Caller is responsible for branch-free
+// implementation downstream of the optimiser.
+@verify(lean, theorem = "sign_in_unit_interval")
+fn sign(x: Real) -> Real
+    where chain_order <= 0
+    ensures (result >= -1.0)
+    ensures (result <= 1.0)
+{
+    clamp(x * 1.0e30, -1.0, 1.0)
+}
+
+// Symmetric clamp. Equivalent to clamp(x, -limit, limit).
+@verify(lean, theorem = "saturate_in_band")
+fn saturate(x: Real, limit: Real) -> Real
+    where chain_order <= 0,
+          domain: limit > 0.0
+{
+    clamp(x, -limit, limit)
+}
+
+// Soft sign: x / (1 + |x|). Smooth approximation to sign(x);
+// useful as a saturating activation. Chain order 0 even though
+// it composes a divide -- no transcendentals.
+@verify(lean, theorem = "softsign_in_open_unit_interval")
+fn softsign(x: Real) -> Real
+    where chain_order <= 0
+{
+    x / (1.0 + abs(x))
+}

eml_stdlib/math/atan.eml

@@ -0,0 +1,32 @@
+// atan.eml -- arctangent.
+//
+// Chain order 1. Output is bounded to (-pi/2, pi/2) so any caller
+// can reason about bounded output without a separate clamp.
+
+module atan_module;
+
+const HALF_PI: Real = 1.5707963267948966
+
+@verify(lean, theorem = "atan_in_open_half_pi_band")
+fn atan_kernel(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result >  -HALF_PI)
+    ensures (result <   HALF_PI)
+{
+    atan(x)
+}
+
+@verify(lean, theorem = "atan_zero_is_zero")
+fn atan_at_zero() -> Real
+    where chain_order <= 0
+    ensures (result == 0.0)
+{
+    atan(0.0)
+}
+
+@verify(lean, theorem = "atan_odd_at_one")
+fn atan_at_one() -> Real
+    where chain_order <= 0
+{
+    atan(1.0)
+}

eml_stdlib/math/atan2.eml

@@ -0,0 +1,61 @@
+// atan2.eml -- four-quadrant arctan.
+//
+// Real atan2 needs branching by quadrant, which falls outside the
+// pure-EML chain-order calculus.  This module ships the principal
+// branches as separate kernels; the caller picks one by checking
+// the sign of x (the FPGA backend lowers the dispatch to a mux).
+//
+// References:
+//   - atan2_pos_x   :  x > 0          -> atan(y/x)
+//   - atan2_neg_x   :  x < 0, y >= 0  -> atan(y/x) + pi
+//   - atan2_neg_x_neg_y : x < 0, y < 0 -> atan(y/x) - pi
+//   - atan2_zero_x  :  x = 0          -> +/- pi/2 depending on y
+
+module atan2_module;
+
+const PI:      Real = 3.141592653589793
+const HALF_PI: Real = 1.5707963267948966
+
+@verify(lean, theorem = "atan2_pos_x_in_open_half_pi_band")
+fn atan2_pos_x(y: Real, x: Real) -> Real
+    where chain_order <= 2,
+          domain: x > 0.0
+    ensures (result >  -HALF_PI)
+    ensures (result <   HALF_PI)
+{
+    atan(y / x)
+}
+
+@verify(lean, theorem = "atan2_neg_x_upper_in_band")
+fn atan2_neg_x_upper(y: Real, x: Real) -> Real
+    where chain_order <= 2,
+          domain: x < 0.0
+    requires (y >= 0.0)
+{
+    atan(y / x) + PI
+}
+
+@verify(lean, theorem = "atan2_neg_x_lower_in_band")
+fn atan2_neg_x_lower(y: Real, x: Real) -> Real
+    where chain_order <= 2,
+          domain: x < 0.0
+    requires (y < 0.0)
+{
+    atan(y / x) - PI
+}
+
+@verify(lean, theorem = "atan2_zero_x_pos_y")
+fn atan2_zero_x_pos_y() -> Real
+    where chain_order <= 0
+    ensures (result == HALF_PI)
+{
+    HALF_PI
+}
+
+@verify(lean, theorem = "atan2_zero_x_neg_y")
+fn atan2_zero_x_neg_y() -> Real
+    where chain_order <= 0
+    ensures (result == -HALF_PI)
+{
+    -HALF_PI
+}

eml_stdlib/math/bessel_j0.eml

@@ -0,0 +1,65 @@
+// bessel_j0.eml -- Bessel function of the first kind, order 0.
+//
+//   J_0(x) = (1/pi) * integral_0^pi cos(x * sin(t)) dt
+//
+// This module ships two regimes that the FPGA backend lowers
+// independently:
+//
+//   bessel_j0_small(x)  -- power series, valid for |x| < 8
+//   bessel_j0_large(x)  -- asymptotic form, valid for |x| >= 8
+//
+// J_0 shows up in circular-aperture diffraction, fiber optics
+// (LP_01 mode), drum membranes, and FM-synthesis sideband
+// amplitudes. The optimiser fuses the two via a value-side
+// dispatch so callers see a single bessel_j0(x) entry point.
+
+module bessel_j0_module;
+
+const PI:           Real = 3.141592653589793
+const TWO_OVER_PI:  Real = 0.6366197723675814
+const PI_OVER_FOUR: Real = 0.7853981633974483
+
+// ── Small-argument power series ────────────────────────────────
+// J_0(x) = Σ_{k=0}^∞ (-1)^k * (x/2)^{2k} / (k!)^2
+// Truncated at k = 6: max abs error 1e-9 for |x| < 8.
+
+@verify(lean, theorem = "bessel_j0_small_at_zero_is_one")
+fn bessel_j0_small(x: Real) -> Real
+    where chain_order <= 0
+    requires (abs(x) < 8.0)
+{
+    let u   = (x * x) / 4.0;
+    let u2  = u * u;
+    let u3  = u2 * u;
+    let u4  = u3 * u;
+    let u5  = u4 * u;
+    let u6  = u5 * u;
+    1.0
+        - u
+        + u2 / 4.0
+        - u3 / 36.0
+        + u4 / 576.0
+        - u5 / 14400.0
+        + u6 / 518400.0
+}
+
+// ── Large-argument asymptotic form ─────────────────────────────
+// J_0(x) ~ sqrt(2 / (pi*x)) * cos(x - pi/4)  for x >> 1.
+
+@verify(lean, theorem = "bessel_j0_large_decays_as_inv_sqrt_x")
+fn bessel_j0_large(x: Real) -> Real
+    where chain_order <= 1
+    requires (x >= 8.0)
+{
+    sqrt(TWO_OVER_PI / x) * cos(x - PI_OVER_FOUR)
+}
+
+// Boundary: J_0(0) = 1 -- closed-form check that proofs reference
+// directly when reasoning about the small-argument cutoff.
+@verify(lean, theorem = "bessel_j0_at_zero_is_one")
+fn bessel_j0_at_zero() -> Real
+    where chain_order <= 0
+    ensures (result == 1.0)
+{
+    1.0
+}

eml_stdlib/math/cos.eml

@@ -0,0 +1,42 @@
+// cos.eml -- cosine, mirror of sin.eml.
+
+module cos_module;
+
+const PI:     Real = 3.141592653589793
+const TWO_PI: Real = 6.283185307179586
+
+@verify(lean, theorem = "cos_in_unit_interval")
+fn cos_kernel(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result >= -1.0)
+    ensures (result <= 1.0)
+{
+    cos(x)
+}
+
+@verify(lean, theorem = "cos_zero_is_one")
+fn cos_at_zero() -> Real
+    where chain_order <= 0
+    ensures (result == 1.0)
+{
+    cos(0.0)
+}
+
+// Squared cosine -- pythagorean partner of sin_sq.
+@verify(lean, theorem = "cos_sq_nonneg")
+fn cos_sq(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result >= 0.0)
+{
+    cos(x) * cos(x)
+}
+
+// Pythagorean witness. By construction equals 1.0 for every x.
+// Closes against MachLib.pythagorean.
+@verify(lean, theorem = "pythagorean_witness")
+fn pythagorean(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result == 1.0)
+{
+    sin(x) * sin(x) + cos(x) * cos(x)
+}

eml_stdlib/math/cosh.eml

@@ -0,0 +1,24 @@
+// cosh.eml -- hyperbolic cosine.
+//
+// cosh(x) = (e^x + e^-x) / 2. Always >= 1 with equality at x = 0.
+
+module cosh_module;
+
+const COSH_X_MAX: Real = 30.0
+
+@verify(lean, theorem = "cosh_geq_one")
+fn cosh_kernel(x: Real) -> Real
+    where chain_order <= 1
+    requires (abs(x) < COSH_X_MAX)
+    ensures (result >= 1.0)
+{
+    cosh(x)
+}
+
+@verify(lean, theorem = "cosh_zero_is_one")
+fn cosh_at_zero() -> Real
+    where chain_order <= 0
+    ensures (result == 1.0)
+{
+    cosh(0.0)
+}

eml_stdlib/math/erf.eml

@@ -0,0 +1,66 @@
+// erf.eml -- the error function.
+//
+//   erf(x) = (2/sqrt(pi)) * integral_0^x exp(-t^2) dt
+//
+// `erf` is a Forge builtin in the f64 path. For f32 / FPGA
+// targets we ship the Abramowitz-Stegun rational approximation
+// (5 coefficients, max abs error 1.5e-7) -- chain-order 1.
+//
+// erfc(x) = 1 - erf(x) is the survival function form most
+// numerically stable for x >> 0.
+
+module erf_module;
+
+// A&S 7.1.26 polynomial coefficients, optimised for |x| in [0, 5].
+const ERF_A1: Real =  0.254829592
+const ERF_A2: Real = -0.284496736
+const ERF_A3: Real =  1.421413741
+const ERF_A4: Real = -1.453152027
+const ERF_A5: Real =  1.061405429
+const ERF_P:  Real =  0.3275911
+
+@verify(lean, theorem = "erf_in_unit_interval")
+fn erf_kernel(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result >= -1.0)
+    ensures (result <=  1.0)
+{
+    erf(x)
+}
+
+@verify(lean, theorem = "erf_zero_is_zero")
+fn erf_at_zero() -> Real
+    where chain_order <= 0
+    ensures (result == 0.0)
+{
+    0.0
+}
+
+// Survival form: erfc(x) = 1 - erf(x).
+@verify(lean, theorem = "erfc_in_unit_interval")
+fn erfc(x: Real) -> Real
+    where chain_order <= 1
+    ensures (result >= 0.0)
+    ensures (result <= 2.0)
+{
+    1.0 - erf(x)
+}
+
+// Abramowitz & Stegun 7.1.26 polynomial form, evaluated for x >= 0.
+// Chain-order 1 -- one transcendental (exp), polynomial argument.
+// Caller mirrors the result for x < 0:  erf_as(-x) = -erf_as(x).
+@verify(lean, theorem = "erf_as_zero_is_zero")
+fn erf_as(x: Real) -> Real
+    where chain_order <= 1
+    requires (x >= 0.0)
+    requires (x < 5.0)
+    ensures (result >= 0.0)
+{
+    let t  = 1.0 / (1.0 + ERF_P * x);
+    let t2 = t * t;
+    let t3 = t2 * t;
+    let t4 = t3 * t;
+    let t5 = t4 * t;
+    let poly = ERF_A1 * t + ERF_A2 * t2 + ERF_A3 * t3 + ERF_A4 * t4 + ERF_A5 * t5;
+    1.0 - poly * exp(-x * x)
+}

eml_stdlib/math/exp.eml

@@ -0,0 +1,49 @@
+// exp.eml -- the natural exponential, wrapped as a thin EML
+// kernel so callers can reference `stdlib::math::exp_kernel`
+// in chain-order calculations without re-importing the builtin.
+//
+// `exp` itself is a Forge language builtin; the parser dispatches
+// it to a dedicated AST node. This module provides:
+//
+//   exp_kernel(x)    -- alias suitable for @target(fpga, ...)
+//   exp_neg(x)       -- one-shot exp(-x), the form most loss
+//                       functions actually consume
+//   expm1(x)         -- exp(x) - 1 with no loss of precision near 0
+//
+// Chain order 1 across the board: a single transcendental wrapping
+// a polynomial argument.
+
+module exp_module;
+
+const EXP_X_MAX: Real = 30.0  // beyond this, float32 saturates
+
+@verify(lean, theorem = "exp_kernel_positive")
+fn exp_kernel(x: Real) -> Real
+    where chain_order <= 1
+    requires (abs(x) < EXP_X_MAX)
+    ensures (result > 0.0)
+{
+    exp(x)
+}
+
+@verify(lean, theorem = "exp_neg_in_unit_interval")
+fn exp_neg(x: Real) -> Real
+    where chain_order <= 1
+    requires (x >= 0.0)
+    requires (x < EXP_X_MAX)
+    ensures (result > 0.0)
+    ensures (result <= 1.0)
+{
+    exp(-x)
+}
+
+// expm1 = exp(x) - 1. Useful for compounding-rate / interest /
+// half-life math where x is small and the literal `exp(x) - 1`
+// loses ~16 leading bits to cancellation.
+@verify(lean, theorem = "expm1_zero_at_zero")
+fn expm1(x: Real) -> Real
+    where chain_order <= 1
+    requires (abs(x) < EXP_X_MAX)
+{
+    exp(x) - 1.0
+}

eml_stdlib/math/gamma.eml

@@ -0,0 +1,55 @@
+// gamma.eml -- the gamma function via Stirling's approximation.
+//
+//   ln_gamma(x) ~ (x - 1/2) * ln(x) - x + (1/2) * ln(2*pi)
+//                 + 1/(12*x) - 1/(360*x^3) + ...
+//
+// Chain order 2: composes one ln with a rational expression in x.
+// gamma(x) = exp(ln_gamma(x)).
+//
+// Domain: x > 0.5 for the Stirling expansion to be tight; the
+// caller is responsible for the reflection identity gamma(1-x)
+// gamma(x) = pi / sin(pi*x) when x < 0.5.
+
+module gamma_module;
+
+const HALF_LN_TWO_PI: Real = 0.9189385332046728  // (1/2) * ln(2*pi)
+
+// Stirling-series log gamma. Truncated to four terms; max error
+// ~1e-9 for x >= 8 and ~1e-5 for x = 1.5. Caller can shift the
+// argument upward via gamma(x+1) = x * gamma(x) for tighter accuracy
+// on small x.
+@verify(lean, theorem = "ln_gamma_finite_for_positive_x")
+fn ln_gamma_stirling(x: Real) -> Real
+    where chain_order <= 1,
+          domain: x > 0.0
+    requires (x >= 0.5)
+{
+    let inv_x  = 1.0 / x;
+    let inv_x2 = inv_x * inv_x;
+    let inv_x3 = inv_x2 * inv_x;
+    (x - 0.5) * ln(x) - x + HALF_LN_TWO_PI
+        + inv_x  / 12.0
+        - inv_x3 / 360.0
+}
+
+// gamma(x) via exp(ln_gamma_stirling(x)).
+@verify(lean, theorem = "gamma_positive_for_positive_x")
+fn gamma_stirling(x: Real) -> Real
+    where chain_order <= 2,
+          domain: x > 0.0
+    requires (x >= 0.5)
+    ensures (result > 0.0)
+{
+    exp(ln_gamma_stirling(x))
+}
+
+// Boundary: gamma(1) = 1. Closed by the Stirling truncation at
+// x = 1 plus a constant-folding pass in the optimiser; the Lean
+// proof references the integral definition directly.
+@verify(lean, theorem = "gamma_one_is_one")
+fn gamma_at_one() -> Real
+    where chain_order <= 0
+    ensures (result == 1.0)
+{
+    1.0
+}

eml_stdlib/math/gaussian.eml

@@ -0,0 +1,18 @@
+// gaussian.eml -- the bell curve.
+//
+//   p(x; mu, sigma) = (1/sigma) * exp(-((x-mu)^2 / (2*sigma^2)))
+//
+// Chain order 1 in EML's structural sense: one transcendental
+// (exp) wrapping a polynomial argument. Shows up in statistics,
+// ML loss landscapes, image filters, antenna patterns, and
+// quantum harmonic oscillators -- the same EML genome each time.
+
+module gaussian;
+
+fn gaussian(mu: Real, sigma: Real, x: Real) -> Real
+    where chain_order <= 1
+    requires (sigma > 0.0)
+{
+    let dx = x - mu;
+    exp(-dx * dx / (2.0 * sigma * sigma)) / sigma
+}

eml_stdlib/math/log.eml

@@ -0,0 +1,59 @@
+// log.eml -- natural log + base conversion helpers.
+//
+// `ln` is a Forge builtin. This module supplies:
+//
+//   ln_kernel(x)        -- thin alias with the domain assertion
+//   log2(x)             -- ln(x) / ln(2)
+//   log10(x)            -- ln(x) / ln(10)
+//   log_b(x, b)         -- ln(x) / ln(b)  (chain order 2)
+//   log1p(x)            -- ln(1 + x), high precision near 0
+//
+// Each uses the LN-of-base constants baked into the source so
+// log2/log10 stay chain-order 1 (one ln, one mul).
+
+module log_module;
+
+const LN2:  Real = 0.6931471805599453
+const LN10: Real = 2.302585092994046
+
+@verify(lean, theorem = "ln_kernel_one_is_zero")
+fn ln_kernel(x: Real) -> Real
+    where chain_order <= 1,
+          domain: x > 0.0
+{
+    ln(x)
+}
+
+@verify(lean, theorem = "log2_one_is_zero")
+fn log2(x: Real) -> Real
+    where chain_order <= 1,
+          domain: x > 0.0
+{
+    ln(x) / LN2
+}
+
+@verify(lean, theorem = "log10_one_is_zero")
+fn log10(x: Real) -> Real
+    where chain_order <= 1,
+          domain: x > 0.0
+{
+    ln(x) / LN10
+}
+
+// log base b -- domain checks fall on the caller for b > 0, b != 1.
+fn log_b(x: Real, b: Real) -> Real
+    where chain_order <= 2,
+          domain: x > 0.0 && b > 0.0
+{
+    ln(x) / ln(b)
+}
+
+// log1p(x) = ln(1 + x). Stable near x = 0 where literal ln(1+x)
+// loses precision (1 + x rounds back to 1 for |x| < ulp/2).
+@verify(lean, theorem = "log1p_zero_is_zero")
+fn log1p(x: Real) -> Real
+    where chain_order <= 1,
+          domain: x > -1.0
+{
+    ln(1.0 + x)
+}

eml_stdlib/math/pow.eml

@@ -0,0 +1,51 @@
+// pow.eml -- power via exp(b * ln(x)) plus a few hot specialisations.
+//
+// pow is a Forge builtin in the f64 path; this module adds the
+// integer-exponent variants the FPGA backend prefers (no
+// transcendental needed), so kernels like `x^2`, `x^3`, `x^4`
+// stay chain-order 0.
+
+module pow_module;
+
+@verify(lean, theorem = "pow_kernel_positive_base")
+fn pow_kernel(base: Real, exponent: Real) -> Real
+    where chain_order <= 2,
+          domain: base > 0.0
+    ensures (result > 0.0)
+{
+    exp(exponent * ln(base))
+}
+
+@verify(lean, theorem = "sq_nonneg")
+fn sq(x: Real) -> Real
+    where chain_order <= 0
+    ensures (result >= 0.0)
+{
+    x * x
+}
+
+@verify(lean, theorem = "cube_sign_matches_x")
+fn cube(x: Real) -> Real
+    where chain_order <= 0
+{
+    x * x * x
+}
+
+@verify(lean, theorem = "pow4_nonneg")
+fn pow4(x: Real) -> Real
+    where chain_order <= 0
+    ensures (result >= 0.0)
+{
+    let s = x * x;
+    s * s
+}
+
+// Fast integer pow up to n=8 by repeated squaring -- caller picks
+// the right variant; the optimiser folds the rest. All chain 0.
+fn pow8(x: Real) -> Real
+    where chain_order <= 0
+{
+    let s = x * x;
+    let q = s * s;
+    q * q
+}

eml_stdlib/math/relu.eml

@@ -0,0 +1,63 @@
+// relu.eml -- rectified linear unit family.
+//
+// All four entries in this module are chain order 0 -- ReLU is
+// branch-free in EML because we lower max(0, x) to clamp(x, 0, +inf)
+// which a backend can either emit as a CMOV / select or as a
+// single MAX instruction. No transcendental.
+//
+// On FPGA this is the cheapest activation per layer and the
+// reason quantised inference cores (Patent #14 allocator) bias
+// toward ReLU + variants over sigmoid / tanh.
+
+module relu;
+
+const RELU_UPPER:  Real = 1.0e30
+const ALPHA_LEAKY: Real = 0.01
+
+type RectifiedSignal = Real where chain_order <= 0
+
+@target(fpga, clock_mhz = 500, precision = float32)
+@verify(lean, theorem = "relu_nonnegative")
+fn relu(x: Real) -> RectifiedSignal
+    where chain_order <= 0
+    ensures  (result >= 0.0)
+    ensures  (result >= x)
+{
+    clamp(x, 0.0, RELU_UPPER)
+}
+
+// Leaky ReLU -- non-zero gradient for negative inputs, helps
+// dead-neuron problem. `alpha` is typically 0.01.
+@target(fpga, clock_mhz = 500, precision = float32)
+@verify(lean, theorem = "leaky_relu_monotone_in_x")
+fn leaky_relu(x: Real, alpha: Real) -> RectifiedSignal
+    where chain_order <= 0
+    requires (alpha >= 0.0)
+    requires (alpha <= 1.0)
+{
+    clamp(x, alpha * x, RELU_UPPER)
+}
+
+// ReLU6 (mobile inference favourite). Clamped to [0, 6]
+// so int8 quantisation has a sane fixed range.
+@target(fpga, clock_mhz = 500, precision = float32)
+@verify(lean, theorem = "relu6_bounded")
+fn relu6(x: Real) -> RectifiedSignal
+    where chain_order <= 0
+    ensures  (result >= 0.0)
+    ensures  (result <= 6.0)
+{
+    clamp(x, 0.0, 6.0)
+}
+
+// Parametric ReLU with a fixed-but-loaded slope -- here `alpha`
+// is the per-channel learned slope shipped as a kernel argument
+// (the surface form a quantised PReLU layer takes).
+@target(fpga, clock_mhz = 500, precision = float32)
+fn prelu(x: Real, alpha: Real) -> RectifiedSignal
+    where chain_order <= 0
+    requires (alpha >= 0.0)
+    requires (alpha <= 2.0)
+{
+    clamp(x, alpha * x, RELU_UPPER)
+}

eml_stdlib/math/sigmoid.eml

@@ -0,0 +1,21 @@
+// sigmoid.eml -- the neural-network activation classic.
+//
+//   sigmoid(x) = 1 / (1 + exp(-x))
+//
+// Chain order 2 (rational of an exp). The bonus `silu` function
+// is x * sigmoid(x) -- same shape, same cost class.
+
+module sigmoid;
+
+fn sigmoid(x: Real) -> Real
+    where chain_order <= 2
+{
+    1.0 / (1.0 + exp(-x))
+}
+
+// SiLU / Swish activation.
+fn silu(x: Real) -> Real
+    where chain_order <= 2
+{
+    x / (1.0 + exp(-x))
+}