mathlex_eval/lib.rs
1//! # mathlex-eval
2//!
3//! Numerical evaluator for mathematical expression ASTs produced by
4//! [`mathlex`](https://crates.io/crates/mathlex).
5//!
6//! Compiles a mathlex `Expression` AST into an efficient internal representation,
7//! then evaluates it with variable substitution and N-dimensional broadcasting.
8//!
9//! ## Two-phase architecture
10//!
11//! 1. **Compile** — [`compile()`] validates the AST, substitutes constants, resolves
12//! variables, and folds constant subexpressions into an optimized [`CompiledExpr`].
13//! 2. **Evaluate** — [`eval()`] creates a lazy [`EvalHandle`] that computes output
14//! shape from input shapes but defers computation until consumed via
15//! [`scalar()`](EvalHandle::scalar), [`to_array()`](EvalHandle::to_array), or
16//! [`iter()`](EvalHandle::iter).
17//!
18//! ## Quick start
19//!
20//! ```rust
21//! use std::collections::HashMap;
22//! use mathlex::{BinaryOp, Expression};
23//! use mathlex_eval::{compile, eval, EvalInput};
24//!
25//! // Build AST for: 2*x + 3
26//! let ast = Expression::Binary {
27//! op: BinaryOp::Add,
28//! left: Box::new(Expression::Binary {
29//! op: BinaryOp::Mul,
30//! left: Box::new(Expression::Integer(2)),
31//! right: Box::new(Expression::Variable("x".into())),
32//! }),
33//! right: Box::new(Expression::Integer(3)),
34//! };
35//!
36//! let compiled = compile(&ast, &HashMap::new()).unwrap();
37//!
38//! let mut args = HashMap::new();
39//! args.insert("x", EvalInput::Scalar(5.0));
40//! let result = eval(&compiled, args).unwrap().scalar().unwrap();
41//! assert_eq!(result.to_f64(), Some(13.0));
42//! ```
43//!
44//! ## Feature flags
45//!
46//! | Flag | Default | Description |
47//! |------|---------|-------------|
48//! | `serde` | yes | Serialize/Deserialize for [`CompiledExpr`] and [`NumericResult`] |
49//! | `parallel` | no | Rayon-based parallel broadcasting in [`EvalHandle::to_array()`] |
50//! | `ffi` | no | Swift FFI bridge via swift-bridge |
51
52pub(crate) mod broadcast;
53pub mod compiler;
54pub mod error;
55pub mod eval;
56#[cfg(feature = "ffi")]
57pub mod ffi;
58
59pub use compiler::compile;
60pub use compiler::ir::CompiledExpr;
61pub use error::{CompileError, EvalError};
62pub use eval::{EvalHandle, EvalInput, EvalIter, NumericResult, eval};