TeXpr 🧮 #

TeXpr is a Dart library that parses and evaluates mathematical expressions using LaTeX syntax. It compiles input strings into an Abstract Syntax Tree (AST) to support numerical evaluation, symbolic differentiation, and structural analysis.

✨ Capabilities #

• 🎯 LaTeX Parsing – Parses standard LaTeX mathematical notation directly into Dart objects.
• 🧮 Symbolic Calculus – Computes derivatives and gradients (\nabla) using algebraic rules.
• 🔢 Advanced Mathematics – Supports summations, products, limits, integrals, and special functions.
• 📈 Linear Algebra – Supports matrix and vector operations, including determinants, inverses, and arithmetic.
• 🔢 Type Safety – Returns results as Numeric, Complex, Matrix, or Vector via Dart 3 sealed classes.
• 🚩 Domain Constraints – Validates mathematical domains (e.g., $x > 0$ ) during evaluation.
• 🧩 Implicit Multiplication – Supports implicit syntax such as $2 \pi r^2$ or $\sin{2x}$. (can be disabled)
• 🎲 Equation Solving – Solves linear and quadratic equations symbolically.
• 🚨 Piecewise Functions – Evaluates and differentiates conditional expressions.
• ✨ Unicode Input – Accepts mathematical symbols directly: √, ∑, ∫, π, Greek letters, and more.

🚀 Quick Start #

Add the dependency to your pubspec.yaml:

dependencies:
  texpr: ^0.0.1

Basic Usage #

import 'package:texpr/texpr.dart';

final evaluator = Texpr();

// 1. Numeric evaluation
final result = evaluator.evaluateNumeric(r'\frac{\sqrt{16}}{2} + \sin{\pi}');
print(result); // 2.0

// 2. Evaluation with variable binding
final vars = {'x': 3.0, 'y': 4.0};
final hypotenuse = evaluator.evaluateNumeric(r'\sqrt{x^2 + y^2}', vars);
print(hypotenuse); // 5.0

🛠️ Features #

1. Symbolic Calculus & Differentiation #

The library supports exact symbolic differentiation and gradient computation rather than finite difference approximations.

// Differentiate with respect to x
final derivative = evaluator.differentiate(r'x^3 + \sin{x}', 'x');

// Evaluate the derivative at x = 0
print(evaluator.evaluateParsed(derivative, {'x': 0})); // 1.0

// Compute Gradient (\nabla)
// Auto-discovers variables in the expression
final grad = evaluator.evaluate(r'\nabla{x^2 + y^2}', {'x': 1, 'y': 2});
print(grad.asVector()); // [2.0, 4.0]

// Differentiate piecewise functions
final piecewise = evaluator.differentiate(r'|\sin{x}|, -3 < x < 3', 'x');
print(evaluator.evaluateParsed(piecewise, {'x': 1})); // cos(1)

2. Complex Numbers & Matrices #

Evaluates expressions involving complex numbers and linear algebra components.

// Euler's identity evaluation
final euler = evaluator.evaluate(r'e^{i*\pi}');
print(euler.asComplex().real); // -1.0

// Complex trigonometry
final sinComplex = evaluator.evaluate(r'\sin(1 + 2*i)');
print(sinComplex.asComplex()); // Complex(3.1658, 1.9596)

// Matrix arithmetic
final matrixResult = evaluator.evaluate(r'''
  \begin{pmatrix} 0.8 & 0.1 \\ 0.2 & 0.7 \end{pmatrix} ^ 2
''');

3. Diagnostics #

Exceptions #

• TexprException: Base class for all library exceptions.
• ValidationResult: Detailed validation information.

Security #

• Security Considerations: Overview of security mitigations and limits. The parser provides error location offsets and suggestions for syntax errors.

final validation = evaluator.validate(r'\frac{1{2}');
if (!validation.isValid) {
  print('Error at ${validation.position}: ${validation.errorMessage}');
  // Suggestion: "Add a closing brace '}'"
}

// Function name suggestions
try {
  evaluator.evaluate(r'\sinn{x}');
} on EvaluatorException catch (e) {
  print(e.suggestion); // "Did you mean 'sin'?"
}

4. Caching #

The Texpr includes a configurable multi-layer LRU cache for repeated evaluations.

// Parse once, evaluate multiple times (Recommended for loops)
final ast = evaluator.parse(r'\sin(x) + \cos(x)');
for (var x = 0.0; x < 100; x += 0.01) {
  evaluator.evaluateParsed(ast, {'x': x});
}

Performance Modes

Benchmark Context

Results from MacBook Air M1 8GB, macOS 15.7.2:

5. Export #

Parsed expressions (AST) can be exported to other formats.

final expr = evaluator.parse(r'\int x^2 dx');

// Export to JSON for tooling/debugging
print(expr.toJson());

// Export to SymPy for Python interoperability
print(expr.toSymPy()); // Output: integrate(x**2, x)

📚 Examples #

Below is a selection of examples showcasing the library's capabilities.

📖 Documentation #

• Getting Started
• LaTeX Commands Reference
• Symbolic Algebra
• Function Reference
• Extending the Library
• Export Features
• Security Considerations

🤝 Contributing #

Contributions are welcome. Please open a Pull Request or Issue on GitHub.

📄 License #

This project is licensed under the MIT License. See the LICENSE file for details.