/// @module std::core::math
/// Math Functions - Optimized with Intrinsics
/// High-performance mathematical operations
// ===== Basic Statistics =====
/// Compute the sum of all values in `series`.
///
/// Routes through the PHF method dispatch — single discriminator per
/// ADR-005 §1 (W12-stdlib-intrinsic-collapse, Wave-2-Agent-G, 2026-05-14).
pub fn sum(series) {
series.sum()
}
/// Compute the arithmetic mean of `series`.
pub fn mean(series) {
__intrinsic_mean(series)
}
// min() and max() are builtin functions that handle both:
// - Single argument: series/array - finds min/max in the collection
// - Multiple arguments: numbers - finds min/max among them
// The builtin intrinsics are used internally via __intrinsic_min/__intrinsic_max
/// Compute the standard deviation of `series`.
pub fn std(series) {
__intrinsic_std(series)
}
/// Compute the variance of `series`.
pub fn variance(series) {
__intrinsic_variance(series)
}
// ===== Advanced Statistics =====
/// Compute the Pearson correlation between two series.
pub fn correlation(series_a, series_b) {
__intrinsic_correlation(series_a, series_b)
}
/// Compute the covariance between two series.
pub fn covariance(series_a, series_b) {
__intrinsic_covariance(series_a, series_b)
}
/// Return the `p` percentile of `series`.
pub fn percentile(series, p) {
__intrinsic_percentile(series, p)
}
/// Return the median of `series`.
pub fn median(series) {
__intrinsic_median(series)
}
// ===== Derived Functions =====
/// Return the coefficient of variation for `series`.
///
/// @returns `std(series) / mean(series)` when the mean is non-zero, otherwise `None`.
/// @see std::core::math::std
/// @see std::core::math::mean
pub fn coefficient_of_variation(series) {
let std_val = __intrinsic_std(series);
let mean_val = __intrinsic_mean(series);
if mean_val == 0 {
None
} else {
std_val / mean_val
}
}
/// Return the difference between the maximum and minimum values in `series`.
pub fn spread(series) {
__intrinsic_max(series) - __intrinsic_min(series)
}
/// Standardize `series` into z-scores.
///
/// @see std::core::math::mean
/// @see std::core::math::std
pub fn zscore(series) {
let mean_val = __intrinsic_mean(series);
let std_val = __intrinsic_std(series);
(series - mean_val) / std_val
}
// ===== Vec Operations =====
// Note: map, filter, reduce are built into the language
// but can use intrinsics for large arrays:
/// Map `fn` across `array`.
///
/// Uses the sequential `.map()` method. A parallel intrinsic path is planned
/// but not yet wired up, so all sizes take the same code path for now.
pub fn parallel_map(array, fn) {
array.map(fn)
}
/// Filter `array` with `predicate`.
///
/// Uses the sequential `.filter()` method. A parallel intrinsic path is planned
/// but not yet wired up, so all sizes take the same code path for now.
pub fn parallel_filter(array, predicate) {
array.filter(predicate)
}
// ===== Constants =====
/// The mathematical constant pi (3.14159...).
pub fn PI() {
3.141592653589793
}
/// Euler's number e (2.71828...).
pub fn E() {
2.718281828459045
}
/// Tau = 2 * pi (6.28318...).
pub fn TAU() {
6.283185307179586
}
// ===== Trigonometry =====
/// Return the sine of `x` in radians.
pub fn sin(x) {
__intrinsic_sin(x)
}
/// Return the cosine of `x` in radians.
pub fn cos(x) {
__intrinsic_cos(x)
}
/// Return the tangent of `x` in radians.
pub fn tan(x) {
__intrinsic_tan(x)
}
/// Return the inverse sine of `x` in radians.
pub fn asin(x) {
__intrinsic_asin(x)
}
/// Return the inverse cosine of `x` in radians.
pub fn acos(x) {
__intrinsic_acos(x)
}
/// Return the inverse tangent of `x` in radians.
pub fn atan(x) {
__intrinsic_atan(x)
}
/// Return the quadrant-aware inverse tangent of `y / x` in radians.
pub fn atan2(y, x) {
__intrinsic_atan2(y, x)
}
/// Return the hyperbolic sine of `x`.
pub fn sinh(x) {
__intrinsic_sinh(x)
}
/// Return the hyperbolic cosine of `x`.
pub fn cosh(x) {
__intrinsic_cosh(x)
}
/// Return the hyperbolic tangent of `x`.
pub fn tanh(x) {
__intrinsic_tanh(x)
}
// ===== Helpers =====
/// Clamp a value to [min, max].
pub fn clamp<T: Ord>(x: T, lo: T, hi: T) -> T {
if x < lo { lo }
else if x > hi { hi }
else { x }
}
/// Linear interpolation between two values.
pub fn lerp<T: Add + Sub + Mul>(a: T, b: T, t: T) -> T {
a + (b - a) * t
}
/// Return the sign of a number: -1, 0, or 1.
pub fn sign(x: int) -> int {
if x > 0 { 1 }
else if x < 0 { -1 }
else { 0 }
}
/// Convert radians to degrees.
pub fn degrees(rad) {
rad * 180.0 / 3.141592653589793
}
/// Convert degrees to radians.
pub fn radians(deg) {
deg * 3.141592653589793 / 180.0
}
// ===== Optimization =====
/// Minimize a scalar objective function using L-BFGS.
///
/// Uses forward-difference gradients (n+1 function evaluations per iteration)
/// and Wolfe line search for fast convergence.
///
/// @param f - Objective function: (Array<number>) => number
/// @param x0 - Initial parameter array
/// @returns Optimized parameter array
pub fn minimize(f, x0) {
__intrinsic_minimize(f, x0)
}
// ===== Interpolation =====
/// Batched quadratic B-spline interpolation on a 3D grid.
///
/// Evaluates the B-spline at multiple points given as a flat array of
/// [x0,y0,z0, x1,y1,z1, ...] coordinates. Returns an array of interpolated
/// values, one per point.
///
/// @param grid_data - Flat 3D grid values (nx * ny * nz)
/// @param nx - Grid size along x
/// @param ny - Grid size along y
/// @param nz - Grid size along z
/// @param x_lo - Grid lower bound x
/// @param x_hi - Grid upper bound x
/// @param y_lo - Grid lower bound y
/// @param y_hi - Grid upper bound y
/// @param z_lo - Grid lower bound z
/// @param z_hi - Grid upper bound z
/// @param pos_flat - Flat array of query positions [x0,y0,z0, x1,y1,z1, ...]
/// @returns Array of interpolated values
pub fn bspline2_3d_batch(grid_data, nx, ny, nz, x_lo, x_hi, y_lo, y_hi, z_lo, z_hi, pos_flat) {
__intrinsic_bspline2_3d_batch(grid_data, nx, ny, nz, x_lo, x_hi, y_lo, y_hi, z_lo, z_hi, pos_flat)
}