Repository Public MIT
1<!--2ORIX Calc3File: Packages/ORIXSymbolic/VALIDATION.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# ORIXSymbolic — validation report89State on 2026-11-20. Toolchain: Swift 6.4.2 (language mode 6, strict concurrency), macOS 27. Reference: sympy 1.14.0 and10mpmath 1.3.0 (`Reference/generate_reference.py` → `Reference/reference.json`, copied into the test bundle).1112## How results are validated13141. **Inside the engine, on every call** (recorded as `VerificationCheck`s in the result):15 * antiderivatives are differentiated and compared with the integrand at up to 10 sample points (and exactly when the16 difference simplifies to 0); a candidate that fails is discarded and the result is `.unsupported`;17 * exact definite integrals are cross-checked against adaptive quadrature; on disagreement the exact value is discarded and18 the numerical one is returned;19 * derivatives are compared with a numerical (Ridders) derivative; simplify/expand results with the input value at sample points;20 * every root of an equation is substituted into the original equation (extraneous roots are rejected and listed);21 * exact limits are compared with a numerical approach to the point; exact linear solutions are substituted exactly;22 * factorizations are multiplied back and compared exactly; closed-form sums are compared with direct summation;23 * ODE solutions are re-computed with tighter tolerances (or twice the steps) to estimate the error.242. **In the test suite**, against an independent reference. Symbolic forms differ between systems, so the comparison is25 semantic: both results are evaluated at pseudo-random points and must agree to 1e-8 … 1e-10. For integrals the reference is26 mpmath quadrature of the integrand (it does not depend on sympy finding an antiderivative). A set of exact structural27 expectations covers the canonical simple cases (`d/dx x²` prints `2x`).2829## Test inventory3031`swift test`: **58 tests in 10 suites, all passing**; `swift build` / `swift build -c release` produce no warning from this32package (the only warning printed comes from the manifest of the BigInt dependency, as in ORIXExpression).3334| Area | Cases | Reference |35|---|---|---|36| Derivatives (all elementary, trig, inverse trig, hyperbolic, inverse hyperbolic, logs in any base, u^v, partials, orders 2–5) | 83 | sympy `diff`, 6 points each |37| Derivatives of random expression trees | 150 generated | Ridders numerical derivative |38| Indefinite integrals (each also re-differentiated in the test) | 88 | mpmath quadrature, 5 intervals each |39| Definite integrals (exact, improper, numerical fallbacks) | 20 + 20 structural | mpmath quadrature |40| Simplification: idempotence and value preservation | 136 corpus + 600 random trees | sympy evaluation / direct evaluation |41| Limits (two-sided, one-sided, at ±∞, infinite, non-existent) | 37 + 16 structural | sympy `limit` |42| Taylor coefficients | 20 series (orders 3–7) | sympy |43| Polynomial equations (real roots, complex count, multiplicities) | 18 | sympy `nroots` |44| Other equations (isolation, substitution, radical, trig, parameters, numerical) | about 40 | hand-checked values, residuals |45| Polynomial division, GCD | 8 pairs + 60 random identities (a = q·b + r, product rule, Horner, composition) | sympy `div`, `gcd` |46| Factorisation (factor lists, multiplicities, `factor(expand(p))` round trip) | 18 + 12 random | sympy `factor_list` |47| Finite sums in closed form | 8 | sympy `summation` |48| Linear systems (unique, inconsistent, underdetermined, 8×8 Hilbert) | 9 | exact substitution |49| Nonlinear systems | 5 | residuals, known solution sets |50| Optimisation (1-D exact and numerical, multivariate) | 12 | closed forms |51| ODEs (decay, tolerance sweep, harmonic oscillator energy, RK4 order, logistic, coupled, failures) | 7 tests | closed forms with error bounds |52| Unsupported / refusal paths | about 45 | — |53| Bounds and performance | 3 tests | — |5455Measured: a 461-node expression is simplified in about 5 ms in a debug build (the test asserts < 50 ms for ≥ 200 nodes).5657## What is supported5859* **Simplify**: canonical sums and products (flattening, ordering, like terms, like powers), exact rational folding, simplified60 radicals (√8 → 2√2), cancellation of common polynomial factors in quotients, numeric content of sums, `sin² + cos² = 1`,61 `cosh² − sinh² = 1`, `e^(ln x)`, `ln(e^x)`, exact trigonometric values at multiples of π/6 and π/4, parity of odd/even62 functions, `i² = −1`, `√(x²) = |x|`. With `assumePositive`: `√(x²) = x`, `ln(ab)`, `ln(x^a)`, `|x| = x`.63 `expand` (products, integer powers up to 64, bounded size). `factor` over ℚ for one-variable polynomials: content,64 square-free decomposition, rational roots, factors of degree 2–4 by Kronecker's method.65* **Polynomials** (`Polynomial`, exact rational coefficients): arithmetic, division with remainder, primitive GCD, derivative,66 antiderivative, Horner evaluation, composition. Roots: exact for linear and quadratic factors (real surds, complex conjugate67 pairs with `i`) and for biquadratic quartics; multiplicities from the square-free decomposition.68* **Differentiation**: complete for the function set listed above, plus `abs`, `sign`, `floor`/`ceil`/`round`/`trunc`/`frac`69 (with a stated assumption), `erf`, `erfc`, `atan2`; any order up to 20, mixed partials, gradient.70* **Integration** (rule engine): linearity, power rule, table for exp / trig / hyperbolic / inverse functions of a linear71 argument, powers of trig and hyperbolic functions (power reduction, reduction formulas), `ln^k`, products of sines and cosines,72 `e^(ax)·sin(bx)` / `cos(bx)`, polynomial × exp / sin / cos / sinh / cosh (tabular parts), by parts with `ln` and inverse73 functions, rational functions by partial fractions (linear and irreducible quadratic factors, repeated), `1/√q`, `√q` and74 `1/q` for a quadratic q, u-substitution, linear substitution with back-substitution, expansion fallback.75 Definite integrals as described in API.md.76* **Solve**: polynomial equations, linear/quadratic with symbolic coefficients, isolation by inverse operations, one radical,77 substitutions (`e^(kx)`, a function of x, `√x`), numerical fallback on an interval. Linear systems exactly (up to 60 × 60),78 nonlinear systems numerically (1–6 unknowns).79* **Limits**: substitution, cancellation, L'Hôpital (0/0, ∞/∞, 0·∞), logarithmic transformation for u^v, limits at ±∞ (degree80 comparison, substitution x = 1/t), squeeze for bounded × vanishing, one-sided limits, locally constant functions (floor, sign).81* **Series**: Taylor polynomials up to order 30 with exact coefficients; sums of polynomials (any degree up to 24),82 arithmetic and geometric progressions, convergent geometric series, exact evaluation for numeric bounds.83* **Optimisation**: 1-D on a closed interval; multivariate local minimisation (Nelder–Mead + BFGS).84* **ODEs**: explicit first-order systems (RK4, Dormand–Prince 5(4)), second order by reduction.8586## What is explicitly unsupported (returned as `.unsupported`, never guessed)8788* Trigonometric input when the angle mode is DEG or GRAD (design choice: symbolic calculus is in radians; the π/180 factor is89 not applied silently).90* Integrals outside the rules above: non-elementary ones (`e^(−x²)`, `sin(x)/x`, `x^x`, `1/ln x`, `√(1 + x⁴)`), rational91 functions whose denominator has an irreducible factor of degree ≥ 3 over ℚ (`1/(x⁴+1)`, `1/(x³−2)`), trigonometric92 substitution in general, Weierstrass substitution, special functions as results (`erf`, `Si`, `Ei` are not produced).93 A definite integral then gets a numerical value labelled `.numerical`.94* Definite integrals with a singularity strictly inside the interval, or an integrand that is not real on part of it.95* Closed forms for irreducible cubics and quartics (no Cardano / Ferrari): their roots are numerical (Durand–Kerner with96 Newton polishing and a residual check) and labelled `.numerical`.97* Factorisation of multivariate or non-polynomial expressions; factors beyond the Kronecker bounds are left as is and flagged98 `isProvenIrreducible == false`.99* Inequalities; equations with parameters that are not linear/quadratic or isolable; linear systems with symbolic or100 floating-point coefficients; complex solutions of non-polynomial equations.101* Derivatives of `gamma`, factorial, `min`/`max`, `if`/`piecewise`.102* Infinite series other than geometric ones; products; closed-form ODE solutions (the optional symbolic ODE classes were not103 implemented); stiff ODE solvers (stiffness is detected as a failure, not solved).104105## Known limitations (honest list)106107* **Trigonometric equations** return the principal solutions only; the general solution is given as text in `note`.108* **Numerical root search** (`solve` fallback) covers the given interval only (default [−10, 10]) and can miss roots of even109 multiplicity or roots closer together than the sampling step (interval / 4000).110* **Limits**: forms needing algebraic conjugation (`√(x²+x) − x` at ∞) are not solved exactly; they come back `.numerical`111 with an extrapolation error estimate. Oscillating limits may come back `.failedConvergence`. The sign of an infinite limit112 and the "defined on this side" test use sampling near the point.113* **Taylor series at a removable singularity** (`sin(x)/x` at 0): each coefficient needs an exact limit of a derivative, which114 the limit engine often cannot produce; order 4 of `sin(x)/x` returns `.unsupported` (observed), lower orders were not115 tested. No Laurent or Puiseux series.116* **Singularity detection** for definite integrals is by sampling (1500 points, plus a pole search) on the interval clipped117 to [−60, 60]; an extremely narrow pole could be missed. The quadrature cross-check is the second line of defence.118* **Verification by sampling** is strong evidence, not a proof; the tolerance is 1e-7 relative on up to 10 points.119* **Simplification** is canonical, not maximal: no trigonometric rewriting beyond the Pythagorean identities, no logarithm120 combination, no nested-radical denesting, sums of fractions are not put over a common denominator automatically.121 Exact fractions print as fractions (`0.1 + 0.2` → `3/10`).122* **Symbolic parameters** are assumed generic (e.g. `a ≠ 0` in `a·x + b = 0`); the assumptions are listed in123 `explanation.assumptions`. Definite integrals with parameters are not checked for continuity (a warning is attached).124* **Optimisation** classifies with f″ and falls back to the sign change of f′; a critical point where f′ touches zero without125 changing sign is reported as `inflection`. Multivariate minimisation finds one local minimum from the starting point.126* **Size limits**: 20 000 input nodes, nesting depth 400, expansion 4000 term products, polynomial degree 400, repeated127 differentiation stops above 2500 nodes, at most 200 000 ODE steps. Exceeding a limit gives `.unsupported` / `.failedConvergence`.128* **Performance figures** were measured in debug builds on one machine (Apple Silicon); no device measurements were made.129130## Not validated131132* Nothing was run on iOS / iPadOS hardware or simulators: the package was built and tested with `swift build` / `swift test`133 on macOS only.134* LaTeX output of results (`text(style: .latex)`) was not checked beyond what `Printer` guarantees.135* Behaviour with user-defined functions or native functions inside expressions (they are treated as unknown functions:136 differentiation and integration return `.unsupported`).137