simple_equation_inversion 1.0.1

A Rust library for solving linear equations and invertible function chains.
Documentation
use crate::element::{Element, ElementKind};
use crate::error::Error;
use crate::{log_compute, log_compute_info, log_compute_step, log_compute_warn};
use alloc::string::ToString;

pub trait EquationAutoCompute {
    fn simple_equation_inversion(&self) -> Result<f64, Error>;
}

/// Type alias for [`Element`], representing a variable or constant in an equation.
pub type EquationElement = Element;

/// Represents a mathematical equation `lhs = rhs` to be solved.
#[derive(Clone, Debug, PartialEq)]
pub struct Equation {
    pub lhs: Element,
    pub rhs: Element,
}

impl Equation {
    pub fn new(lhs: impl Into<Element>, rhs: impl Into<Element>) -> Self {
        Self {
            lhs: lhs.into(),
            rhs: rhs.into(),
        }
    }

    pub fn solve(self) -> Result<f64, Error> {
        log_compute!("Solving equation: ({}) == ({})", self.lhs, self.rhs);
        let error = self.lhs.error().and(self.rhs.error());
        let reduced = self.lhs - self.rhs;
        log_compute!("Reduced to canonical form: ({reduced} = 0)");

        if let Err(err) = error.and(reduced.error()) {
            log_compute_warn!("Cannot solve: equation error encountered ({err})");
            return Err(err);
        }

        solve_target(&reduced, 0.0)
    }
}

fn solve_target(elem: &Element, target: f64) -> Result<f64, Error> {
    elem.error()?;

    match &elem.kind {
        ElementKind::Variable {
            factor,
            unknown,
            offset,
        } => {
            if *factor == 0.0 {
                return Err(Error::NoUnknown);
            }
            if let Err(err) = unknown.get_status() {
                log_compute_warn!("Cannot solve: variable error encountered ({err})");
                return Err(err);
            }

            let solution = (target - offset) / factor;
            log_compute_info!("Solved: x = {solution}");
            *unknown.unknown.borrow_mut() = solution;
            Ok(solution)
        }
        ElementKind::Transformed {
            factor,
            transform,
            inner,
            offset,
        } => {
            if *factor == 0.0 {
                return Err(Error::NoUnknown);
            }
            let y = (target - offset) / factor;
            log_compute_step!(
                "Inverting transform '{}' with target value {y}",
                transform.name()
            );

            match transform.invert(y) {
                Ok(inv_val) => {
                    log_compute_step!("Inverted '{}': {y} => {inv_val}", transform.name());
                    solve_target(inner, inv_val)
                }
                Err(msg) => {
                    let err = Error::TransformError {
                        transform: transform.name().to_string(),
                        stage: "inverse".to_string(),
                        value: y,
                        message: msg,
                    };
                    log_compute_warn!("Cannot solve: inverse transform failed ({err})");
                    if let Some(u) = inner.unknown_ref() {
                        u.set_status(Err(err.clone()));
                    }
                    Err(err)
                }
            }
        }
        ElementKind::Known(_) => Err(Error::NoUnknown),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::transform::FnTransform;
    #[allow(unused_imports)]
    use alloc::format;
    #[allow(unused_imports)]
    use alloc::string::ToString;

    #[test]
    fn test_equation_solve_simple_linear() {
        let x = Element::unknown();
        let eq = Equation::new(2.0 * x + 4.0, 10.0);
        assert_eq!(eq.solve(), Ok(3.0));
    }

    #[test]
    fn test_equation_solve_no_unknown() {
        let eq = Equation::new(4.0, 10.0);
        assert_eq!(eq.solve(), Err(Error::NoUnknown));
    }

    #[test]
    fn test_equation_solve_cancelled_unknown() {
        // x - x = 0 has no unknown remaining
        let x1 = Element::unknown();
        let x2 = x1.clone();
        let eq = Equation::new(x1, x2);
        assert_eq!(eq.solve(), Err(Error::NoUnknown));
    }

    #[test]
    fn test_equation_solve_quadratic_error() {
        let x = Element::unknown();
        let eq = Equation::new(x.clone() * x, 16.0);
        assert_eq!(eq.solve(), Err(Error::SquareForbidden));
    }

    #[test]
    fn test_equation_solve_with_transform() {
        let cube = FnTransform::from_fn(
            "cube",
            |x| x * x * x,
            |y| {
                if y < 0.0 { -(-y).cbrt() } else { y.cbrt() }
            },
        );

        let x = Element::unknown();
        let eq = Equation::new(cube.apply_to(x), 27.0);
        let sol = eq.solve().unwrap();
        assert!((sol - 3.0).abs() < 1e-6);
    }

    #[test]
    fn test_equation_solve_chained_transforms() {
        let double = FnTransform::from_fn("double", |x| x * 2.0, |y| y / 2.0);
        let add_ten = FnTransform::from_fn("add_ten", |x| x + 10.0, |y| y - 10.0);

        let x = Element::unknown();
        // add_ten(double(x)) = 30 => double(x) = 20 => x = 10
        let eq = Equation::new(add_ten.apply_to(double.apply_to(x)), 30.0);
        assert_eq!(eq.solve(), Ok(10.0));
    }

    #[test]
    fn test_equation_solve_triple_chained_transforms() {
        let add_one = FnTransform::from_fn("add_one", |x| x + 1.0, |y| y - 1.0);
        let double = FnTransform::from_fn("double", |x| x * 2.0, |y| y / 2.0);
        let square = FnTransform::from_fn("square", |x| x * x, |y| y.sqrt());

        let x = Element::unknown();
        // add_one(double(square(x))) = 19
        // double(square(x)) = 18
        // square(x) = 9
        // x = 3
        let expr = add_one.apply_to(double.apply_to(square.apply_to(x)));
        let eq = Equation::new(expr, 19.0);
        assert_eq!(eq.solve(), Ok(3.0));
    }

    #[test]
    fn test_equation_solve_transform_with_scalar_scale() {
        let double = FnTransform::from_fn("double", |x| x * 2.0, |y| y / 2.0);

        let x = Element::unknown();
        // 3.0 * double(x) + 4.0 = 28.0 => double(x) = 8.0 => x = 4.0
        let eq = Equation::new(3.0 * double.apply_to(x) + 4.0, 28.0);
        assert_eq!(eq.solve(), Ok(4.0));
    }

    #[test]
    fn test_equation_solve_transform_nested_expression() {
        let double = FnTransform::from_fn("double", |x| x * 2.0, |y| y / 2.0);

        let x = Element::unknown();
        // double(x + 5.0) = 24.0 => x + 5.0 = 12.0 => x = 7.0
        let eq = Equation::new(double.apply_to(x + 5.0), 24.0);
        assert_eq!(eq.solve(), Ok(7.0));
    }

    #[test]
    fn test_equation_solve_transform_error() {
        let sqrt = FnTransform::new(
            "sqrt",
            |x| {
                if x < 0.0 {
                    Err("neg".into())
                } else {
                    Ok(x.sqrt())
                }
            },
            |y| {
                if y < 0.0 {
                    Err("neg_inv".into())
                } else {
                    Ok(y * y)
                }
            },
        );

        let x = Element::unknown();
        // sqrt(x) = -10.0 => invert fails
        let eq = Equation::new(sqrt.apply_to(x), -10.0);
        assert!(matches!(eq.solve(), Err(Error::TransformError { .. })));
    }

    #[test]
    fn test_equation_solve_division_by_zero_error() {
        let x = Element::unknown();
        let eq = Equation::new(x / 0.0, 10.0);
        assert_eq!(eq.solve(), Err(Error::DivisionByZero));
    }

    #[test]
    fn test_equation_solve_unknown_in_denominator_error() {
        let x = Element::unknown();
        let eq = Equation::new(10.0 / x, 2.0);
        assert_eq!(eq.solve(), Err(Error::UnknownInDenominator));
    }
}