nlcalc 0.1.0

Plugin-based natural language calculator for Rust and the command line
Documentation
//! Explicit population/sample statistics and finite binomial distributions.
mod models;
mod statistics;
use crate::{Context, Error, ModelPosition, Outcome, Plugin, re};
use num_rational::BigRational;
use num_traits::{Signed, ToPrimitive, Zero};

pub struct Probability;
impl Plugin for Probability {
    fn rewrite_call(
        &self,
        name: &str,
        arguments: &str,
        context: &Context,
        _: ModelPosition,
    ) -> Outcome {
        if !calls().is_match(&format!("{name}(")) {
            return None;
        }
        self.compute(&format!("{name}({arguments})"), context)
            .map(|result| result.map(|value| format!("real({value:e})")))
    }
    fn rewrite_model(&self, input: &str, context: &Context, _: ModelPosition) -> Outcome {
        models::rewrite(input, context)
            .or_else(|| statistics::rewrite(input, context))
            .or_else(|| wording(input, context))
            .map(|result| result.and_then(|expression| lower_calls(&expression, context)))
    }
    fn evaluate(&self, input: &str, context: &Context) -> Outcome {
        statistics::evaluate(super::syntax::ungroup(input), context)
            .or_else(|| models::evaluate(super::syntax::ungroup(input)))
    }
    fn rewrite(&self, input: &str, context: &Context) -> Outcome {
        let expression = match super::syntax::rewrite_groups(input, |part| {
            models::rewrite(part, context)
                .or_else(|| statistics::rewrite(part, context))
                .or_else(|| wording(part, context))
        }) {
            Some(Ok(expression)) => expression,
            Some(Err(error)) => return Some(Err(error)),
            None => input.to_string(),
        };
        match lower_calls(&expression, context) {
            Ok(lowered) if lowered != input => Some(Ok(lowered)),
            Err(error) => Some(Err(error)),
            _ => None,
        }
    }
}
impl Probability {
    fn compute(&self, input: &str, context: &Context) -> Option<Result<f64, Error>> {
        let (operation, arguments) = input.split_once('(')?;
        let folded = operation.to_ascii_lowercase();
        let operation = folded.as_str();
        if !matches!(
            operation,
            "population_variance"
                | "sample_variance"
                | "population_stddev"
                | "sample_stddev"
                | "weighted_mean"
                | "binomial_probability"
                | "binomial_cdf"
                | "binomial_tail"
        ) {
            return None;
        }
        Some((|| {
            let arguments = arguments
                .strip_suffix(')')
                .ok_or_else(|| error("invalid_expression"))?;
            let value = match operation {
                "weighted_mean" => weighted_mean(arguments, context)?,
                "binomial_probability" | "binomial_cdf" | "binomial_tail" => {
                    let arguments = split_arguments(arguments)?;
                    if arguments.len() != 3 {
                        return Err(error("invalid_expression"));
                    }
                    let n = scalar(arguments[0], context)?;
                    if n < 0.0 || n.fract() != 0.0 {
                        return Err(error("invalid_trial_count"));
                    }
                    if n > 10_000.0 {
                        return Err(error("probability_limit"));
                    }
                    let p = scalar(arguments[1], context)?;
                    if !(0.0..=1.0).contains(&p) {
                        return Err(error("invalid_probability"));
                    }
                    let k = scalar(arguments[2], context)?;
                    if operation == "binomial_probability" && k.fract() != 0.0 {
                        return Err(error("invalid_success_count"));
                    }
                    let probabilities = binomial(n as usize, p);
                    probabilities
                        .iter()
                        .enumerate()
                        .filter(|(index, _)| {
                            let index = *index as f64;
                            match operation {
                                "binomial_cdf" => index <= k,
                                "binomial_tail" => index >= k,
                                _ => index == k,
                            }
                        })
                        .map(|(_, value)| value)
                        .sum::<f64>()
                        .clamp(0.0, 1.0)
                }
                _ => {
                    let values = dataset_arguments(arguments)?
                        .into_iter()
                        .map(|input| statistics::coordinate(input, context).map(|(value, _)| value))
                        .collect::<Result<Vec<_>, _>>()?;
                    let sample = operation.starts_with("sample_");
                    if values.is_empty() || sample && values.len() < 2 {
                        return Err(error("invalid_dataset"));
                    }
                    // Center exact authored coordinates before converting to floats.
                    // Computed coordinates already carry their rounded real value.
                    let origin = &values[0];
                    let mut centered = values
                        .iter()
                        .map(|value| value - origin)
                        .collect::<Vec<_>>();
                    let magnitude =
                        |values: &[BigRational]| values.iter().map(Signed::abs).max().unwrap();
                    let mut exact_scale = magnitude(&centered);
                    if exact_scale.is_zero() {
                        return Ok(0.0);
                    }
                    if !exact_scale.to_f64().is_some_and(f64::is_finite) {
                        // Opposite finite extremes can overflow their difference;
                        // normalize the original finite coordinates in that case.
                        centered.clone_from(&values);
                        exact_scale = magnitude(&centered);
                    }
                    let scale = exact_scale
                        .to_f64()
                        .filter(|value| value.is_finite())
                        .ok_or_else(|| error("numeric_overflow"))?;
                    if scale == 0.0 {
                        return Err(error("numeric_underflow"));
                    }
                    // Welford on scaled deviations avoids overflowing the squared spread.
                    let (mut mean, mut squares) = (0.0, 0.0);
                    for (index, value) in centered.iter().enumerate() {
                        let value = (value / &exact_scale)
                            .to_f64()
                            .filter(|value| value.is_finite())
                            .ok_or_else(|| error("numeric_overflow"))?;
                        let delta = value - mean;
                        mean += delta / (index + 1) as f64;
                        squares += delta * (value - mean);
                    }
                    let variance = (squares / (values.len() - usize::from(sample)) as f64).max(0.0);
                    if operation.ends_with("stddev") {
                        variance.sqrt() * scale
                    } else {
                        let value = variance * scale * scale;
                        if value == 0.0 && variance != 0.0 {
                            return Err(error("numeric_underflow"));
                        }
                        value
                    }
                }
            };
            if !value.is_finite() {
                return Err(error("numeric_overflow"));
            }
            Ok(value)
        })())
    }
}
fn wording(input: &str, context: &Context) -> Option<Result<String, Error>> {
    let s = input.trim().trim_end_matches(['.', '?']).replace('−', "-");
    let s = re!(r"(?i)^(?:find (?:the )?|compute (?:the )?|calculate (?:the )?)").replace(&s, "");
    if let Some(c) = re!(r"(?i)^(population|sample) (variance|standard deviation) (?:of|for) (?:the )?(?:data ?set )?(.+)$")
        .captures(&s)
    {
        let operation = if c[2].eq_ignore_ascii_case("variance") {
            "variance"
        } else {
            "stddev"
        };
        return Some(Ok(format!(
            "{}_{operation}({})", c[1].to_ascii_lowercase(), c[3].trim()
        )));
    }
    if let Some(c) =
        re!(r"(?i)^(?:the )?weighted (?:average|mean) of (.+?) with (?:respective )?weights (.+)$")
            .captures(&s)
    {
        let values = c[1].replace(", and ", ", ").replace(" and ", ", ");
        let list = |input: &str| {
            if input.trim().starts_with('[') {
                input.trim().to_string()
            } else {
                format!("[{input}]")
            }
        };
        return Some(Ok(format!(
            "weighted_mean({}, {})",
            list(&values),
            list(&c[2])
        )));
    }
    if let Some(c) = re!(r"(?i)^for (\d+) independent (?:bernoulli )?trials with p\s*=\s*([^,]+), (?:find |calculate )?(?:the )?probability of exactly (\d+) successes$")
        .captures(&s)
    {
        return Some(Ok(format!(
            "binomial_probability({}, {}, {})", &c[1], &c[2], &c[3]
        )));
    }
    if let Some(c) = re!(r"(?i)^for (?:a )?binomial (?:model|variable|random variable) (?:with )?n\s*=\s*([^,]+), p\s*=\s*([^,]+), (?:calculate |find )?p\(x\s*(≥|>=|≤|<=|=|>|<)\s*([^()]+)\)$")
        .captures(&s)
    {
        return Some((|| {
            let threshold = scalar(&c[4], context)?;
            let (operation, threshold) = match &c[3] {
                "≥" | ">=" => ("tail", threshold),
                ">" => ("tail", threshold.floor() + 1.0),
                "≤" | "<=" => ("cdf", threshold),
                "<" => ("cdf", threshold.ceil() - 1.0),
                _ => ("probability", threshold),
            };
            Ok(format!("binomial_{operation}({}, {}, {threshold})", &c[1], &c[2]))
        })());
    }
    None
}

// Mark computed scalars as real values so comparisons preserve their floating provenance.
fn calls() -> &'static regex::Regex {
    re!(
        r"(?i)\b(?:population_variance|sample_variance|population_stddev|sample_stddev|weighted_mean|binomial_probability|binomial_cdf|binomial_tail)\("
    )
}
fn lower_calls(input: &str, context: &Context) -> Result<String, Error> {
    super::syntax::rewrite_calls(input, calls(), |name, arguments| {
        let expression = format!("{name}({arguments})");
        let value = Probability
            .compute(&expression, context)
            .ok_or_else(|| error("invalid_expression"))??;
        // Rust's float Display is round-trip; number() is reserved for the final answer.
        Ok(format!("real({value:e})"))
    })
}

fn error(code: &str) -> Error {
    Error(code.into())
}
fn scalar(input: &str, context: &Context) -> Result<f64, Error> {
    static MATH: std::sync::LazyLock<super::compositions::Compositions> =
        std::sync::LazyLock::new(super::compositions::Compositions::default);
    static LANGUAGE: std::sync::LazyLock<super::language::Language> =
        std::sync::LazyLock::new(super::language::Language::default);
    if super::calendar::date(input.trim(), context).is_some() {
        return Err(error("invalid_dataset"));
    }
    let expression = match LANGUAGE.rewrite(input, context) {
        Some(result) => result?,
        None => input.to_string(),
    };
    MATH.quantity_value(&expression, "1", context)
}

fn split_arguments(input: &str) -> Result<Vec<&str>, Error> {
    if input.trim().is_empty() {
        return Ok(vec![]);
    }
    let mut stack = vec![];
    let mut start = 0usize;
    let mut arguments = vec![];
    for (index, ch) in input.char_indices() {
        match ch {
            '(' | '[' => stack.push(ch),
            ')' | ']' if stack.pop() != Some(if ch == ')' { '(' } else { '[' }) => {
                return Err(error("invalid_expression"));
            }
            ')' | ']' => {}
            ',' if stack.is_empty() => {
                arguments.push(input[start..index].trim());
                start = index + 1;
            }
            _ => {}
        }
    }
    arguments.push(input[start..].trim());
    if !stack.is_empty() || arguments.iter().any(|s| s.is_empty()) {
        return Err(error("invalid_expression"));
    }
    Ok(arguments)
}
fn dataset_arguments(input: &str) -> Result<Vec<&str>, Error> {
    let input = input.trim();
    let input = if input.starts_with('[') {
        input
            .strip_prefix('[')
            .and_then(|s| s.strip_suffix(']'))
            .ok_or_else(|| error("invalid_dataset"))?
    } else {
        input
    };
    split_arguments(input)
}
fn dataset(input: &str, context: &Context) -> Result<Vec<f64>, Error> {
    dataset_arguments(input)?
        .into_iter()
        .map(|value| scalar(value, context))
        .collect()
}
fn weighted_mean(input: &str, context: &Context) -> Result<f64, Error> {
    let arguments = split_arguments(input)?;
    if arguments.len() != 2 {
        return Err(error("invalid_weights"));
    }
    let values = dataset(arguments[0], context)?;
    let weights = dataset(arguments[1], context)?;
    if values.is_empty() || values.len() != weights.len() || weights.iter().any(|w| *w < 0.0) {
        return Err(error("invalid_weights"));
    }
    let scale = weights.iter().copied().fold(0.0, f64::max);
    if scale == 0.0 {
        return Err(error("invalid_weights"));
    }
    let total: f64 = weights.iter().map(|weight| weight / scale).sum();
    let (mut sum, mut correction) = (0.0_f64, 0.0_f64);
    // Neumaier summation retains small contributions between cancelling large terms.
    for (value, weight) in values.iter().zip(weights) {
        // Multiply before dividing when the product is representable. Normalizing
        // an extremely small weight first could discard a finite contribution.
        let product = value * weight;
        let term = if product.is_finite() && product != 0.0 {
            product / scale / total
        } else {
            value * (weight / scale / total)
        };
        let next = sum + term;
        correction += if sum.abs() >= term.abs() {
            (sum - next) + term
        } else {
            (term - next) + sum
        };
        sum = next;
    }
    Ok(sum + correction)
}
fn binomial(n: usize, p: f64) -> Vec<f64> {
    let mut weights = vec![0.0; n + 1];
    if p == 0.0 || p == 1.0 {
        weights[if p == 0.0 { 0 } else { n }] = 1.0;
        return weights;
    }
    let mode = (((n + 1) as f64 * p).floor() as usize).min(n);
    weights[mode] = 1.0;
    // Start at the mode and normalize relative weights, avoiding factorial overflow
    // and underflow of p^n or (1-p)^n before a central probability is computed.
    for k in (1..=mode).rev() {
        weights[k - 1] = weights[k] * (k as f64 / (n - k + 1) as f64) * ((1.0 - p) / p);
    }
    for k in mode..n {
        weights[k + 1] = weights[k] * ((n - k) as f64 / (k + 1) as f64) * (p / (1.0 - p));
    }
    let total: f64 = weights.iter().sum();
    for weight in &mut weights {
        *weight /= total;
    }
    weights
}