SPB Git

Repository Public MIT

calculation-engine.md 4.1 KB 85 lines markdown

1<!--2ORIX Calc3File: docs/architecture/calculation-engine.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Calculation engine (`ORIXExpression`)89```mermaid10flowchart LR11    Text["Input text"] --> Lexer --> Parser --> AST["Expr tree"]12    AST --> Eval["Evaluator<br/>typed values"]13    AST --> Compile["CompiledExpression<br/>Double closures"]14    AST --> Printer["Printer<br/>pretty · ASCII · LaTeX"]15    Eval --> Value16    Eval --> Steps["Explanation steps"]17    Eval --> Notes["Verification notes"]18    Value --> Formatter["NumberFormatting"]19    Compile --> Graph["Graph sampler, quadrature, root finding"]20```2122## Parser2324A hand-written tokenizer and recursive-descent parser. Text becomes an `Expr` tree and nothing else: there is no dynamic25code execution of any kind.2627```mermaid28flowchart TD29    S["statement"] -->|"name = …"| A["assignment"]30    S -->|"f(x, y) = …"| D["function definition"]31    S --> E["expression"]32    E --> Or["or"] --> And["and"] --> Cmp["comparison  = ≠ < ≤ > ≥  (chains: a < b < c)"]33    Cmp --> Add["+  −"] --> Mul["×  ÷  mod  implicit ×"] --> Un["unary −  +  not"]34    Un --> Pow["^  (right associative)"] --> Post["postfix  !  %  °"] --> Prim["number · name · call · ( ) · [ ] · | |"]35```3637Supported syntax: decimal literals with exponents, Unicode operators (× ÷ − · √ π ∞ ≤ ≥ ≠), superscripts (x², x⁻¹),38implicit multiplication (`2x`, `2(3)`, `(a)(b)`, `2 sin x`), function calls, vectors `[1, 2, 3]`, matrices `[1, 2; 3, 4]`,39absolute-value bars, comparisons, `and / or / not`, a tolerated missing final parenthesis, locale decimal comma40(with `;` as argument separator). Errors carry a character position and a plain-language message.4142## Typed values4344```mermaid45flowchart LR46    I["integer<br/>BigInt"] --> R["rational<br/>BigInt / BigInt"] --> D["real<br/>IEEE-754 double"] --> C["complex<br/>Complex&lt;Double&gt;"]47    B["boolean"]48    Vec["vector of scalars"]49    Mat["matrix of scalars"]50```5152Arithmetic promotes only as far as needed: integer ∘ integer stays an integer, a decimal literal is an exact rational,53a transcendental function produces a double, and a result leaves the real line only when complex mode is on.54Other value kinds live in their own engines: unit quantities (`ORIXUnits`), symbolic expressions (`Expr`, `ORIXSymbolic`),55cash-flow series (`ORIXFinancial`).5657## Evaluator5859A tree-walking evaluator over `Value` with:6061- **special forms** whose arguments are not evaluated eagerly: `sum`, `prod`, `deriv`, `integral`, `nsolve`, `if`, `piecewise`;62- about 100 built-in functions, user functions, and native functions registered by other packages (statistics distributions);63- **guards**: a NaN is a domain error, an unexpected infinity is an overflow error — an invalid number can never be shown as a result;64- **step recording** for ORIX Explain (each operation with its operand values and result);65- **notes** for ORIX Verified Results: loss of significance in a floating-point subtraction, an exact fraction that had to66  fall back to floating point, a large integer rounded on mixing with a double, residuals of linear solves and matrix67  inverses, error estimates of numerical integration and differentiation, the residual of a numerical root.6869## Compiled real functions7071`CompiledExpression` turns an `Expr` into nested `Double` closures (no allocation per call) for plotting and numerical72methods. It never throws: an undefined point is NaN, which is exactly what a sampler needs to find gaps.7374## RPN7576`RPNMachine` is a stack over the same `Value` arithmetic and function library, so algebraic and RPN entry cannot disagree.77A failed operation leaves the stack untouched.7879## Formatting8081Display digits are produced by exact rational arithmetic on the stored value (a double is itself an exact rational), so the82rounding shown is always correct, and the stored value is never modified by a display setting.83Notations: automatic, fixed, scientific, engineering; significant digits or fixed decimals; locale separators; exact84fractions; rectangular or polar complex form; a canonical machine format that parses back to the identical value.85
Files main
Menu

Theme