Crate thales

Expand description

§Thales - Computer Algebra System

A comprehensive Computer Algebra System (CAS) library for symbolic mathematics, equation solving, calculus, and numerical methods. Named after Thales of Miletus, the first mathematician in the Greek tradition.

§Overview

Thales provides:

Symbolic equation solving - Linear, quadratic, polynomial, transcendental, and systems
Calculus - Differentiation, integration, limits, Taylor series, first and second-order ODEs
Numerical methods - Newton-Raphson, bisection, Brent’s method, Levenberg-Marquardt
Coordinate systems - 2D/3D transformations, complex numbers, De Moivre’s theorem
Units & dimensions - Dimensional analysis and unit conversion
Step-by-step solutions - Resolution paths for educational applications
iOS/macOS support - FFI bindings via swift-bridge

§Key Features

Zero-cost abstractions with compile-time guarantees
Memory-safe implementation (no unsafe code except FFI boundary)
970+ tests including property-based tests with proptest
Optimized for mobile targets (iOS)
Clear separation between symbolic and numerical methods

§Quick Start

§Example 1: Coordinate Transformations

Convert between Cartesian and polar coordinate systems:

use thales::{Cartesian2D, Polar};

// 2D Cartesian to Polar
let cartesian = Cartesian2D::new(3.0, 4.0);
let polar = cartesian.to_polar();
assert!((polar.r - 5.0).abs() < 1e-10);
assert!((polar.theta - 0.927295218).abs() < 1e-6);

// Polar to Cartesian round-trip
let back = polar.to_cartesian();
assert!((back.x - 3.0).abs() < 1e-10);
assert!((back.y - 4.0).abs() < 1e-10);

§Example 2: 3D Coordinate Transformations

Convert between Cartesian and spherical coordinates:

use thales::{Cartesian3D, Spherical};

// Cartesian to Spherical
let cart3d = Cartesian3D::new(1.0, 1.0, 1.0);
let spherical = cart3d.to_spherical();
assert!((spherical.r - 1.732050808).abs() < 1e-6);

// Spherical to Cartesian round-trip
let back = spherical.to_cartesian();
assert!((back.x - 1.0).abs() < 1e-10);
assert!((back.y - 1.0).abs() < 1e-10);
assert!((back.z - 1.0).abs() < 1e-10);

§Example 3: Complex Number Operations

Work with complex numbers and polar form:

use thales::ComplexOps;
use num_complex::Complex64;

// De Moivre's theorem: (r∠θ)^n = r^n∠(nθ)
let z = Complex64::new(1.0, 1.0);
let result = ComplexOps::de_moivre(z, 2.0);

// Complex conjugate (using num_complex methods)
let conj = z.conj();
assert_eq!(conj.re, z.re);
assert_eq!(conj.im, -z.im);

// Modulus (magnitude) of complex number
let modulus = z.norm();
assert!((modulus - 1.4142135623730951).abs() < 1e-10);

§Example 4: Expression and Variable Basics

Build mathematical expressions using the AST:

use thales::{Expression, Variable, BinaryOp};

// Create expression: 2*x + 5
let x = Variable::new("x");
let two_x = Expression::Binary(
    BinaryOp::Mul,
    Box::new(Expression::Integer(2)),
    Box::new(Expression::Variable(x.clone()))
);
let expr = Expression::Binary(
    BinaryOp::Add,
    Box::new(two_x),
    Box::new(Expression::Integer(5))
);

// Check variable containment
assert!(expr.contains_variable("x"));
assert!(!expr.contains_variable("y"));

§User Guides

For detailed tutorials and workflows, see the guides module:

guides::solving_equations - Linear, quadratic, polynomial, and systems
guides::calculus_operations - Derivatives, integrals, limits, ODEs
guides::series_expansions - Taylor, Maclaurin, Laurent, asymptotic
guides::coordinate_systems - 2D/3D transforms, complex numbers
guides::numerical_methods - Root-finding when symbolic fails
guides::working_with_units - Dimensional analysis
guides::error_handling - Working with ThalesError

§Feature Summary

Category	Features
Parsing	Expression parser, equation parser, LaTeX input/output
Solving	Linear, quadratic, polynomial, transcendental, multi-equation systems
Calculus	Differentiation, integration (by parts, substitution), limits, L’Hôpital
ODEs	First-order (separable, linear), second-order (constant coefficient)
Series	Taylor, Maclaurin, Laurent, asymptotic expansions, Big-O
Special	Gamma, beta, error functions with derivation steps
Numerical	Newton-Raphson, bisection, Brent’s, secant, Levenberg-Marquardt
Transforms	Cartesian ↔ Polar ↔ Spherical ↔ Cylindrical, complex operations
Units	SI base/derived units, dimensional analysis, conversions
FFI	Swift bindings via swift-bridge, iOS device + simulator

§Architecture Overview

The library follows a modular design with clear separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                    Public API Layer                     │
│  (parse_equation, SmartSolver, Cartesian2D, etc.)      │
└─────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐    ┌──────────┐
   │  Parser  │     │  Solver  │    │Transform │
   │ (chumsky)│     │ (symbolic)│    │(nalgebra)│
   └──────────┘     └──────────┘    └──────────┘
          │                │                │
          └────────────────┼────────────────┘
                           ▼
                    ┌──────────┐
                    │   AST    │
                    │(equation,│
                    │  expr,   │
                    │variable) │
                    └──────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐    ┌──────────┐
   │Numerical │     │Resolution│    │Dimensions│
   │ (argmin) │     │   Path   │    │  (units) │
   └──────────┘     └──────────┘    └──────────┘
                           │
                           ▼
                    ┌──────────┐
                    │   FFI    │
                    │  (Swift) │
                    └──────────┘

§Module Responsibilities

ast: Core data structures for mathematical expressions, equations, variables, operators, and functions. All other modules build upon these types.
parser: String → AST conversion using the chumsky parser combinator library. Handles operator precedence, function calls, and complex number literals.
solver: Symbolic equation solving using algebraic manipulation. Includes specialized solvers for linear, quadratic, polynomial, and transcendental equations. The SmartSolver automatically dispatches to the appropriate solver.
numerical: Numerical root-finding methods for equations that cannot be solved symbolically. Integrates with symbolic differentiation from the AST module.
resolution_path: Records the step-by-step solution process for educational applications. Each transformation is recorded with its operation type.
dimensions: Dimensional analysis and unit conversion. Ensures physical equations maintain dimensional consistency.
transforms: Coordinate system conversions (Cartesian, Polar, Spherical, Cylindrical) and complex number operations. Built on nalgebra for linear algebra.
ffi: Foreign function interface for Swift via swift-bridge. Provides C-compatible bindings for iOS/macOS integration. Enabled with the ffi feature flag.

§Safety Guarantees

This library adheres to strict memory safety principles:

No unsafe code in core logic: All mathematical operations, parsing, solving, and transformations use only safe Rust.
FFI boundary isolation: The only unsafe code appears in the ffi module for C interoperability, which is:
- Isolated behind the ffi feature flag
- Managed by the swift-bridge library
- Validated at the FFI boundary with explicit error handling
Ownership guarantees: The Rust type system prevents:
- Use-after-free bugs
- Data races in concurrent access
- Null pointer dereferences
- Buffer overflows
Integer overflow protection: All arithmetic operations use checked or saturating semantics where appropriate.
Thread safety: All public types are Send + Sync where semantically appropriate, with compile-time verification.

§Performance Characteristics

§Time Complexity Guarantees

Operation	Complexity	Notes
Parse expression	O(n)	Linear in input string length
Variable lookup	O(1)	HashMap-based symbol table
Coordinate transform	O(1)	Fixed number of trig operations
Linear solve	O(1)	Constant number of operations
Quadratic solve	O(1)	Discriminant calculation + sqrt
Polynomial solve (degree d)	O(d²)	Companion matrix method
Numerical solve (Newton)	O(k)	k iterations to convergence

§Space Complexity

AST storage: O(n) where n is the number of expression nodes
Resolution path: O(k) where k is the number of solution steps
Parser stack: O(d) where d is maximum nesting depth

§Optimization Features

Build configuration in release mode enables:

Link-Time Optimization (LTO): Cross-module inlining and dead code elimination
Single codegen unit: Maximum optimization at cost of compile time
opt-level=3: Aggressive compiler optimizations
Zero-cost abstractions: Generic functions specialized at compile time
SIMD auto-vectorization: Compiler-generated vectorized code where applicable

[profile.release]
opt-level = 3
lto = true
codegen-units = 1

Benchmark your performance-critical paths with:

cargo bench

§Platform Support

§Tier 1: Fully Supported

iOS Devices (aarch64-apple-ios): Native ARM64 execution on iPhone/iPad
iOS Simulator on ARM (aarch64-apple-ios-sim): M1/M2/M3 Mac simulator
iOS Simulator on Intel (x86_64-apple-ios): Intel Mac simulator

Build for all iOS targets:

# Add targets (one-time setup)
rustup target add aarch64-apple-ios
rustup target add aarch64-apple-ios-sim
rustup target add x86_64-apple-ios

# Build for device
cargo build --release --target aarch64-apple-ios

# Build for simulator (ARM)
cargo build --release --target aarch64-apple-ios-sim

# Build universal library with lipo
lipo -create \
  target/aarch64-apple-ios-sim/release/libthales.a \
  target/x86_64-apple-ios/release/libthales.a \
  -output libthales_universal.a

§Tier 2: Standard Rust Targets

The library uses only stable Rust features and should compile on any tier 1 Rust platform:

Linux (x86_64, aarch64)
macOS (x86_64, aarch64)
Windows (x86_64)

§FFI Integration

Enable Swift bindings with the ffi feature:

cargo build --release --features ffi --target aarch64-apple-ios

This generates Swift bridge code and C headers for Xcode integration.

§Version History

Current: v0.3.0 - Advanced Calculus & API Stabilization

Second-order ODEs with characteristic equation method
Nonlinear system solver (Newton-Raphson for systems)
Taylor, Maclaurin, Laurent series expansions
Asymptotic expansions with Big-O notation
Special functions (gamma, beta, erf, erfc)
Small angle approximations with error bounds
Unified ThalesError type
970+ tests including property-based tests

See CHANGELOG.md for complete version history.

§Module Reference

Module	Description
`ast`	Abstract syntax tree types for expressions and equations
`parser`	String → AST conversion with chumsky
`solver`	Symbolic equation solving
`equation_system`	Multi-equation system solver
`numerical`	Numerical root-finding methods
`integration`	Symbolic integration
`limits`	Limit evaluation with L’Hôpital’s rule
`ode`	First and second-order ODE solving
`series`	Taylor, Laurent, asymptotic series
`special`	Gamma, beta, error functions
`approximations`	Small angle and scaled approximations
`transforms`	Coordinate system conversions
`dimensions`	Units and dimensional analysis
`pattern`	Rule-based expression rewriting
`latex`	LaTeX parsing and generation
`resolution_path`	Step-by-step solution tracking
`guides`	User tutorials and workflows

§Running Tests

cargo test              # All tests
cargo test --doc        # Documentation examples only
cargo test --release    # Optimized build

Re-exports§

pub use approximations::apply_small_angle_approx;
pub use approximations::compute_approximation_error;
pub use approximations::generate_approximation_step;
pub use approximations::is_approximation_valid;
pub use approximations::optimize_pythagorean;
pub use approximations::select_exp_scaling;
pub use approximations::ApproxResult;
pub use approximations::ApproxType;
pub use approximations::ScaledExpForm;
pub use ast::BinaryOp;
pub use ast::Equation;
pub use ast::Expression;
pub use ast::Function;
pub use ast::UnaryOp;
pub use ast::Variable;
pub use dimensions::Dimension;
pub use dimensions::Quantity;
pub use dimensions::Unit;
pub use dimensions::UnitRegistry;
pub use equation_system::broyden_system;
pub use equation_system::fixed_point_system;
pub use equation_system::newton_raphson_system;
pub use equation_system::residual_norm;
pub use equation_system::solve_linear_system_lu;
pub use equation_system::validate_jacobian;
pub use equation_system::BroydenSolver;
pub use equation_system::Constraint;
pub use equation_system::ConvergenceBehavior;
pub use equation_system::ConvergenceDiagnostics;
pub use equation_system::DependencyGraph;
pub use equation_system::EquationSystem;
pub use equation_system::EquationType;
pub use equation_system::FixedPointSolver;
pub use equation_system::IntegralInfo;
pub use equation_system::MultiEquationSolution;
pub use equation_system::MultiEquationSolver;
pub use equation_system::NamedEquation;
pub use equation_system::NewtonRaphsonSolver;
pub use equation_system::NonlinearSystem;
pub use equation_system::NonlinearSystemConfig;
pub use equation_system::NonlinearSystemSolver;
pub use equation_system::NonlinearSystemSolverError;
pub use equation_system::NonlinearSystemSolverResult;
pub use equation_system::ODEInfo;
pub use equation_system::SmartNonlinearSystemSolver;
pub use equation_system::SolutionStrategy;
pub use equation_system::SolutionValue;
pub use equation_system::SolveMethod;
pub use equation_system::SolveStep;
pub use equation_system::SolverConfig;
pub use equation_system::StepResult;
pub use equation_system::SystemContext;
pub use equation_system::SystemError;
pub use equation_system::SystemOperation;
pub use equation_system::SystemResolutionPath;
pub use equation_system::SystemStep;
pub use inequality::solve_inequality;
pub use inequality::solve_system;
pub use inequality::Bound;
pub use inequality::Inequality;
pub use inequality::InequalityError;
pub use inequality::IntervalSolution;
pub use integration::definite_integral;
pub use integration::definite_integral_with_fallback;
pub use integration::definite_integral_with_steps;
pub use integration::improper_integral_to_infinity;
pub use integration::integrate;
pub use integration::integrate_by_parts;
pub use integration::integrate_by_parts_with_steps;
pub use integration::integrate_by_substitution;
pub use integration::integrate_with_substitution;
pub use integration::numerical_integrate;
pub use integration::tabular_integration;
pub use integration::IntegrationError;
pub use latex::parse_latex;
pub use latex::parse_latex_equation;
pub use matrix::BracketStyle;
pub use matrix::MatrixError;
pub use matrix::MatrixExpr;
pub use numerical::NumericalConfig;
pub use numerical::NumericalSolution;
pub use numerical::SmartNumericalSolver;
pub use ode::solve_characteristic_equation;
pub use ode::solve_ivp;
pub use ode::solve_linear;
pub use ode::solve_second_order_homogeneous;
pub use ode::solve_second_order_ivp;
pub use ode::solve_separable;
pub use ode::CharacteristicRoots;
pub use ode::FirstOrderODE;
pub use ode::ODEError;
pub use ode::ODESolution;
pub use ode::RootType;
pub use ode::SecondOrderODE;
pub use ode::SecondOrderSolution;
pub use optimization::analyze_expression;
pub use optimization::find_multiplicative_chains;
pub use optimization::optimize_computation_order;
pub use optimization::to_manual_steps;
pub use optimization::track_precision;
pub use optimization::ComputationStep;
pub use optimization::ManualStep;
pub use optimization::MultiplicativeChain;
pub use optimization::OperationConfig;
pub use optimization::OperationType;
pub use optimization::PrecisionReport;
pub use optimization::StepOperand;
pub use parser::parse_equation;
pub use parser::parse_expression;
pub use partial_fractions::decompose;
pub use partial_fractions::is_polynomial;
pub use partial_fractions::is_rational_function;
pub use partial_fractions::DecomposeError;
pub use partial_fractions::PartialFractionResult;
pub use partial_fractions::PartialFractionTerm;
pub use precision::EvalContext;
pub use precision::EvalError;
pub use precision::PrecisionMode;
pub use precision::RoundingMode;
pub use precision::Value;
pub use resolution_path::Operation;
pub use resolution_path::OperationCounts;
pub use resolution_path::PathStatistics;
pub use resolution_path::ResolutionPath;
pub use resolution_path::ResolutionPathBuilder;
pub use resolution_path::ResolutionStep;
pub use resolution_path::Verbosity;
pub use series::arctan_series;
pub use series::asymptotic;
pub use series::binomial_series;
pub use series::compose_series;
pub use series::compute_nth_derivative;
pub use series::cos_series;
pub use series::evaluate_at;
pub use series::exp_series;
pub use series::factorial;
pub use series::factorial_expr;
pub use series::find_singularities;
pub use series::laurent;
pub use series::limit_via_asymptotic;
pub use series::ln_1_plus_x_series;
pub use series::maclaurin;
pub use series::pole_order;
pub use series::residue;
pub use series::reversion;
pub use series::sin_series;
pub use series::taylor;
pub use series::AsymptoticDirection;
pub use series::AsymptoticSeries;
pub use series::AsymptoticTerm;
pub use series::BigO;
pub use series::LaurentSeries;
pub use series::RemainderTerm;
pub use series::Series;
pub use series::SeriesError;
pub use series::SeriesResult;
pub use series::SeriesTerm;
pub use series::Singularity;
pub use series::SingularityType;
pub use solver::LinearSystem;
pub use solver::SmartSolver;
pub use solver::Solution;
pub use solver::Solver;
pub use solver::SystemSolution;
pub use solver::SystemSolver;
pub use special::beta;
pub use special::erf;
pub use special::erfc;
pub use special::gamma;
pub use special::SpecialFunctionError;
pub use special::SpecialFunctionResult;
pub use transforms::Cartesian2D;
pub use transforms::Cartesian3D;
pub use transforms::ComplexOps;
pub use transforms::Cylindrical;
pub use transforms::Polar;
pub use transforms::Spherical;
pub use transforms::Transform2D;
pub use trigonometric::all_trig_rules;
pub use trigonometric::double_angle_rules;
pub use trigonometric::inverse_rules;
pub use trigonometric::parity_rules;
pub use trigonometric::product_to_sum_rules;
pub use trigonometric::pythagorean_rules;
pub use trigonometric::quotient_rules;
pub use trigonometric::simplify_double_angle;
pub use trigonometric::simplify_pythagorean;
pub use trigonometric::simplify_quotient;
pub use trigonometric::simplify_trig;
pub use trigonometric::simplify_trig_step;
pub use trigonometric::simplify_trig_with_steps;
pub use trigonometric::special_value_rules;

Modules§

approximations: Small angle and scaled form approximations for mathematical expressions.
ast: Abstract Syntax Tree definitions for mathematical expressions.
dimensions: Unit and dimension handling for physical quantities.
equation_system: Multi-Equation System Solver
guides: User Guides
inequality: Inequality solving module for linear and quadratic inequalities.
integration: Symbolic integration module for computing indefinite integrals.
latex: LaTeX expression parser for mathematical notation.
limits: Limit evaluation for mathematical expressions.
matrix: Matrix expression type with basic linear algebra operations.
numerical: Numerical approximation methods for equations.
ode: First-Order Ordinary Differential Equation Solver
optimization: Operation ordering optimizer for manual calculation.
parser: Expression and equation parser for mathematical notation.
partial_fractions: Partial fraction decomposition for integrating rational functions.
pattern: Pattern matching for expression transformations.
precision: Numerical precision controls for expression evaluation.
resolution_path: Resolution path tracking for equation solving.
series: Taylor and Maclaurin series expansion module.
solver: Algebraic equation solver with symbolic manipulation.
special: Special mathematical functions with step-by-step derivation.
transforms: Coordinate system transformations.
trigonometric: Trigonometric identity simplification.

Enums§

ThalesError: Unified error type for the thales library.

Constants§

NAME: Library name.
VERSION: Library version information.

Functions§

has_ffi_support: Check if library is compiled with FFI support.
version: Get library version string.

Crate thales

Crate thales Copy item path

§Thales - Computer Algebra System

§Overview

§Key Features

§Quick Start

§Example 1: Coordinate Transformations

§Example 2: 3D Coordinate Transformations

§Example 3: Complex Number Operations

§Example 4: Expression and Variable Basics

§User Guides

§Feature Summary

§Architecture Overview

§Module Responsibilities

§Safety Guarantees

§Performance Characteristics

§Time Complexity Guarantees

§Space Complexity

§Optimization Features

§Platform Support

§Tier 1: Fully Supported

§Tier 2: Standard Rust Targets

§FFI Integration

§Version History

§Module Reference

§Running Tests

Re-exports§

Modules§

Enums§

Constants§

Functions§

Crate thales