TeXpr

https://github.com/xirf/texpr
Admin
TeXpr is a Dart library that parses and evaluates mathematical expressions using LaTeX syntax. It...
Tokens:53,934
Snippets:786
Trust Score:9.3
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup and Run JavaScript Benchmark

Source: https://github.com/xirf/texpr/blob/master/benchmark/comparison/README.md

Install Node.js dependencies and execute the JavaScript benchmark using benchmark.js. This requires npm.

```bash
cd benchmark/comparison/js
npm install
npm run benchmark
```

--------------------------------

### Setup Python Virtual Environment for SymPy

Source: https://github.com/xirf/texpr/blob/master/test/integration/sympy/README.md

Set up the Python virtual environment and install SymPy. This is typically done once. Alternatively, install from pinned requirements.

```bash
cd test/integration/sympy
python3 -m venv .venv
source .venv/bin/activate
pip install sympy
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Verify TeXpr Installation

Source: https://github.com/xirf/texpr/blob/master/doc/guide/installation.md

A basic Dart example to verify the TeXpr installation by creating an evaluator and evaluating a simple mathematical expression.

```dart
import 'package:texpr/texpr.dart';

void main() {
  final evaluator = Texpr();
  print(evaluator.evaluate(r'2 + 2')); // 4.0
}
```

--------------------------------

### Setup and Run Python Benchmark

Source: https://github.com/xirf/texpr/blob/master/benchmark/comparison/README.md

Install dependencies and run the Python benchmark using pytest-benchmark. This includes SymPy and necessary libraries.

```bash
cd benchmark/comparison/python
pip install pytest pytest-benchmark sympy antlr4-python3-runtime
pytest benchmark_pytest.py --benchmark-only -v
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/xirf/texpr/blob/master/CONTRIBUTING.md

Commands to install project dependencies and run tests using Dart.

```bash
# Install dependencies
dart pub get

# Run tests
dart test

# Run specific test file
dart test test/evaluator_test.dart
```

--------------------------------

### LaTeX Integral Example

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Examples of definite and double integrals in LaTeX.

```latex
\int_{0}^{\pi} \sin{x} dx
\iint{x^2 + y^2} dx dy
```

--------------------------------

### Example: Cube Root Command and Evaluator

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/extensions.md

Demonstrates registering both a custom command '\cbrt' and its corresponding evaluator to compute the cube root of a number. Includes example usage.

```dart
import 'dart:math' as math;
import 'package:texpr/texpr.dart';

final registry = ExtensionRegistry();

// Register \cbrt command
registry.registerCommand('cbrt', (cmd, pos) =
  Token(type: TokenType.function, value: 'cbrt', position: pos));

// Register evaluator
registry.registerEvaluator((expr, vars, evaluate) {
  if (expr is FunctionCall && expr.name == 'cbrt') {
    final arg = evaluate(expr.argument);
    return math.pow(arg, 1/3).toDouble();
  }
  return null;
});

final texpr = Texpr(extensions: registry);

texpr.evaluate(r'\cbrt{27}');  // 3.0
texpr.evaluate(r'\cbrt{8}');   // 2.0
```

--------------------------------

### LaTeX Limit Examples

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/calculus.md

Provides examples of limits using LaTeX syntax, including symbolic results.

```latex
\lim_{x \to 0} \frac{\sin{x}}{x}      % \to 1.0
```

```latex
\lim_{n \to \infty} (1 + \frac{1}{n})^n  % \to e (≈ 2.718)
```

--------------------------------

### Run Python Benchmarks

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/performance.md

Set up and run the Python benchmarks using pytest and pytest-benchmark. Ensure sympy is installed.

```bash
cd benchmark/comparison/python
pip install pytest pytest-benchmark sympy
pytest benchmark_pytest.py --benchmark-only -v
```

--------------------------------

### Setup Python Virtual Environment

Source: https://github.com/xirf/texpr/blob/master/test/integration/mathml/README.md

Create a Python virtual environment for the MathML integration tests. No additional packages are needed as it uses the standard library.

```bash
cd test/integration/mathml
python3 -m venv .venv
# No additional packages needed - uses stdlib xml.etree
```

--------------------------------

### Run Package Get Command

Source: https://github.com/xirf/texpr/blob/master/doc/guide/installation.md

Execute the appropriate command to fetch the project dependencies after updating pubspec.yaml. Use 'dart pub get' for Dart projects and 'flutter pub get' for Flutter projects.

```bash
dart pub get
```

```bash
flutter pub get
```

--------------------------------

### Conventional Commit Example

Source: https://github.com/xirf/texpr/blob/master/CONTRIBUTING.md

An example of a conventional commit message for adding a new feature.

```git
feat: add support for hyperbolic functions

- Add sinh, cosh, tanh handlers
- Update tokenizer to recognize \sinh, \cosh, \tanh
- Add tests for hyperbolic functions
```

--------------------------------

### Registering Custom Commands and Evaluators

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Example demonstrating how to instantiate ExtensionRegistry and register a custom command '\myconst' and a custom function 'double' for evaluation.

```dart
final registry = ExtensionRegistry();

// Register \myconst as a constant
registry.registerCommand('myconst', (cmd, pos) =
  Token(type: TokenType.number, value: '42', position: pos)
);

// Register custom function evaluation
registry.registerEvaluator((expr, vars, eval) {
  if (expr is FunctionCall && expr.name == 'double') {
    return 2 * eval(expr.argument);
  }
  return null;  // Not handled, use default
});

final evaluator = Texpr(extensions: registry);
evaluator.evaluate(r'\myconst');  // 42

```

--------------------------------

### Limit Evaluation Examples

Source: https://github.com/xirf/texpr/blob/master/doc/reference/behavior.md

Demonstrates the behavior of limit evaluation for different scenarios, including convergence, evaluation at infinity, and direct substitution for indeterminate forms.

```dart
lim_{x→0} sin(x)/x     // = 1.0 (numerical convergence)
lim_{x→∞} 1/x          // = 0.0 (evaluated at large values)
lim_{x→0} 1/x          // = Infinity (direct substitution)
```

--------------------------------

### Initialize Texpr Parser

Source: https://github.com/xirf/texpr/blob/master/doc/reference/index.md

Instantiate the main Texpr class to begin parsing and evaluating expressions. No specific setup is required beyond importing the library.

```dart
import 'package:texpr/texpr.dart';

final texpr = Texpr();
```

--------------------------------

### EvaluationResult Usage Example

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Demonstrates how to use pattern matching to handle different types of EvaluationResult.

```dart
final result = evaluator.evaluate(r'e^{i\pi}');

switch (result) {
  case NumericResult(:final value):
    print('Real: $value');
  case ComplexResult(:final value):
    print('Complex: ${value.real} + ${value.imaginary}i');
  case MatrixResult(:final matrix):
    print('Matrix: ${matrix.rows}x${matrix.cols}');
  case VectorResult(:final vector):
    print('Vector with ${vector.length} elements');
}
```

--------------------------------

### Matrix LaTeX Representation

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Example of how a Matrix can be represented in LaTeX format.

```latex
\begin{pmatrix} 1 & 2 \\ 3 & 4 \end{pmatrix}
```

--------------------------------

### Tokenization Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/index.md

The tokenizer converts an input string into a stream of meaningful tokens. LaTeX commands, implicit multiplication, and Greek letters are handled.

```plaintext
[FUNCTION:sin] [LBRACE] [VARIABLE:x] [RBRACE] [OPERATOR:+] [NUMBER:1]
```

--------------------------------

### Parsing Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/index.md

The parser builds an Abstract Syntax Tree (AST) from tokens, representing the expression's structure and enforcing operator precedence and associativity.

```plaintext
     BinaryOp(+)
        /    \
  FunctionCall  NumberLiteral(1)
   (sin)
     |
  Variable(x)
```

--------------------------------

### Sin Function Evaluation Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/evaluator.md

Illustrates the step-by-step evaluation process for the sin(x) function, including argument evaluation, function dispatch, and result return.

```dart
// sin(x) evaluation:
// 1. Evaluate x → 3.14159
// 2. Call dart:math sin() → ~0.0
// 3. Return NumericResult(~0.0)
```

--------------------------------

### Format Code

Source: https://github.com/xirf/texpr/blob/master/CONTRIBUTING.md

Command to format Dart code according to the project's style guide.

```bash
dart format .
```

--------------------------------

### Uncertainty Propagation Example

Source: https://github.com/xirf/texpr/blob/master/doc/guide/intervals.md

Calculates the area of a square with an uncertain side length using interval arithmetic.

```latex
let x = [2.9, 3.1]
x^2
// Result: [8.41, 9.61]
```

--------------------------------

### LaTeX Summation and Product Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Use \sum_{i=a}^{b}{f} for summations and \prod_{i=a}^{b}{f} for products in LaTeX. Examples show summation from 1 to 10 and product from 1 to 5.

```latex
\sum_{i=a}^{b}{f}
```

```latex
\prod_{i=a}^{b}{f}
```

--------------------------------

### Define Variable and Function in LaTeX

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Use `let` for variable assignment and `f(x) = ...` for function definition. Refer to the guide on environments for more details.

```latex
let x = 5
```

```latex
f(x) = x^2
```

--------------------------------

### Implicit Multiplication Examples

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

The texpr parser supports implicit multiplication for various notations. Use this for concise mathematical expressions.

```latex
2x         to 2 * x
```

```latex
xy         to x * y
```

```latex
2\pi r     to 2 * \pi * r
```

```latex
\sin x \cos x to sin(x) * cos(x)
```

--------------------------------

### AST Representation Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/parser.md

Illustrates the Abstract Syntax Tree (AST) structure for the expression '2 * x + 1'. This tree visually represents the operations, their order, and operands.

```plaintext
       BinaryOp(+)
         /    \
   BinaryOp(*)   NumberLiteral(1)
     /    \
Number(2)  Variable(x)
```

--------------------------------

### Texpr Thread Safety Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/caching.md

Demonstrates the correct way to use Texpr instances across isolates to avoid race conditions. Each isolate should have its own Texpr instance.

```dart
// ✗ Don't share across isolates
final sharedEvaluator = Texpr();
Isolate.spawn((_) => sharedEvaluator.evaluate(...));  // Race condition!

// ✓ Create per-isolate
Isolate.spawn((_) {
  final localEvaluator = Texpr();
  localEvaluator.evaluate(...);
});
```

--------------------------------

### LaTeX Fraction Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Use \frac{numerator}{denominator} to create fractions in LaTeX. For example, \frac{x^2 + 1}{x - 1}.

```latex
\frac{numerator}{denominator}
```

--------------------------------

### Subscript Variable Examples

Source: https://github.com/xirf/texpr/blob/master/doc/reference/grammar.md

Shows how subscripts are used to create variable names with underscores. For evaluation, provide a dictionary mapping the subscripted variable name (e.g., 'x_0' or 'R_crit') to its value.

```plaintext
x_0     → Variable("x_0")
R_{crit} → Variable("R_crit")
```

--------------------------------

### Basic Simplification Rules in TeXpr

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/symbolic.md

TeXpr applies local pattern matching for simplification. These examples demonstrate successful simplifications of common additive and multiplicative identities.

```dart
// These succeed
engine.simplify(parse('0 + x'));      // → x
engine.simplify(parse('x * 1'));      // → x
engine.simplify(parse('x + x'));      // → 2x
```

--------------------------------

### Function Argument Binding Examples

Source: https://github.com/xirf/texpr/blob/master/doc/reference/grammar.md

Illustrates how functions bind tightly to their immediate arguments. \sin x^2 is parsed as sin(x^2) using function power notation, whereas \sin{x}^2 is parsed as (sin(x))^2 using standard notation.

```plaintext
\sin x^2 = sin(x^2)     ✓  (function power notation)
\sin{x}^2 = (sin(x))^2  ✓  (standard)
```

--------------------------------

### Compile Dart to WASM

Source: https://github.com/xirf/texpr/blob/master/wasm/README.md

Use the Dart CLI to compile your Dart entry point to a WASM module. Ensure you have Dart SDK 3.10+ installed.

```bash
# Compile to WASM
dart compile wasm wasm/main.dart -o wasm/build/main.wasm

# Serve (WASM requires HTTP server, file:// won't work)
cd wasm/build && python3 -m http.server 8080

# Open http://localhost:8080/index.html in Chrome/Firefox
```

--------------------------------

### Operator Precedence Example

Source: https://github.com/xirf/texpr/blob/master/doc/guide/logic.md

Understand operator precedence for correct evaluation of expressions without explicit parentheses. Arithmetic operators have lower precedence than comparisons, and logical operators follow specific ordering.

```latex
x > 0 \land y < 10
% Parsed as: (x > 0) \land (y < 10) -> Correct
```

--------------------------------

### High-Performance Cache Configuration

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/caching.md

Configure Texpr with a high-performance cache setup, specifying sizes for parsed expressions, evaluation results, and differentiation, along with an LRU eviction policy and a 30-minute time-to-live. Statistics collection is enabled.

```dart
final evaluator = Texpr(
  cacheConfig: CacheConfig(
    parsedExpressionCacheSize: 512,    // L1
    evaluationResultCacheSize: 1024,   // L2
    differentiationCacheSize: 256,     // L3
    evictionPolicy: EvictionPolicy.lru, // Least Recently Used
    ttl: Duration(minutes: 30),         // Time-to-live
    collectStatistics: true,            // Enable stats
  ),
);
```

--------------------------------

### Configure TeXpr Cache Sizes

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/performance.md

Instantiate the TeXpr evaluator with custom cache configurations to manage memory usage. This example reduces the parsed expression cache size and sets a maximum input length to reject overly long expressions.

```dart
final evaluator = Texpr(
  cacheConfig: CacheConfig(
    parsedExpressionCacheSize: 64,    // Smaller cache
    maxCacheInputLength: 2000,         // Reject very long inputs
  ),
);
```

--------------------------------

### Greedy Tokenization Example

Source: https://github.com/xirf/texpr/blob/master/doc/reference/grammar.md

Demonstrates TeXpr's greedy tokenization, where the longest possible token is always matched. This ensures that \sinx is correctly parsed as a function and a variable, while \sin, x is not treated as two separate tokens.

```plaintext
\sinx    → FUNCTION(sin), VARIABLE(x)    ✓
\sin, x  ✗ (not two separate tokens)
```

--------------------------------

### Initialize ExtensionRegistry

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/extensions.md

Set up the ExtensionRegistry to manage custom extensions. This is the first step before registering any custom commands or evaluators.

```dart
import 'package:texpr/texpr.dart';

final registry = ExtensionRegistry();

// Register extensions...

final texpr = Texpr(extensions: registry);
```

--------------------------------

### LaTeX Matrix Environment

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Use `\begin{matrix} ... \end{matrix}` for plain matrices, `\begin{pmatrix} ... \end{pmatrix}` for parenthesized matrices, `\begin{bmatrix} ... \end{bmatrix}` for bracketed matrices, and `\begin{vmatrix} ... \end{vmatrix}` for determinants. Use `&` to separate columns and `\\` to separate rows.

```latex
\begin{pmatrix}
  a & b \\
  c & d
end{pmatrix}
```

--------------------------------

### Integrate Expressions Symbolically and Numerically

Source: https://github.com/xirf/texpr/blob/master/doc/guide/concepts.md

Perform symbolic (indefinite) integration to get an AST representing the integral, or numeric (definite) integration to get a direct evaluated result.

```dart
// Symbolic (indefinite)
final integral = evaluator.integrate(r'x^2', 'x');
// Returns AST representing x^3/3
```

```dart
// Numeric (definite)
evaluator.evaluate(r'\int_{0}^{1} x^2 dx');  // 0.333...
```

--------------------------------

### Evaluation Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/index.md

The evaluator traverses the AST to compute the result, handling variable binding and type conversions. This example shows evaluating sin(x) + 1 with x = 1.

```plaintext
1. Evaluate left child: sin(x) -> sin(1) -> 0.8414...
2. Evaluate right child: 1 -> 1
3. Apply operator: 0.8414 + 1 -> 1.8414
```

--------------------------------

### Initialize SymbolicEngine and Texpr

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/symbolic.md

Initializes the SymbolicEngine and Texpr instances for use in symbolic computations. Imports the necessary library.

```dart
import 'package:texpr/texpr.dart';

final engine = SymbolicEngine();
final texpr = Texpr();

final expr = texpr.parse('0 + x');
final simplified = engine.simplify(expr);
```

--------------------------------

### Interval Addition Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/guide/intervals.md

Demonstrates the basic syntax for interval addition in TeXpr.

```latex
[1, 2] + [3, 4]
```

--------------------------------

### LaTeX Syntax for Products

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/calculus.md

Presents the general LaTeX structure for defining product expressions.

```latex
\prod_{variable=start}^{end}{expression}
```

--------------------------------

### Multi-argument Function Calls in LaTeX

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Demonstrates how to represent functions with multiple arguments and multi-argument integrals in LaTeX.

```latex
f(x,y)                   % Function with multiple arguments
```

```latex
g(a,b,c)                 % Function with 3 arguments
```

```latex
\iint_{D} f(x,y) dx dy   % Double integral with function notation
```

--------------------------------

### simplify(expr)

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/symbolic.md

Applies simplification rules to a symbolic expression. For example, it can simplify '0 + x' to 'x'.

```APIDOC
## simplify(expr)

### Description
Applies simplification rules to a symbolic expression.

### Method
SymbolicEngine.simplify

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **expr** (Texpr) - Required - The symbolic expression to simplify.

### Request Example
```dart
final engine = SymbolicEngine();
final texpr = Texpr();
final expr = texpr.parse('0 + x');
final simplified = engine.simplify(expr);
```

### Response
#### Success Response (200)
- **simplified_expr** (Texpr) - The simplified symbolic expression.

#### Response Example
```json
{
  "simplified_expr": "x"
}
```
```

--------------------------------

### COMMAND Token Definition

Source: https://github.com/xirf/texpr/blob/master/doc/reference/grammar.md

Specifies the structure for command tokens, typically starting with a backslash followed by letters.

```text
COMMAND     → '\' letter { letter }
```

--------------------------------

### Run Evaluability Fast-Path Benchmark with Enforcement

Source: https://github.com/xirf/texpr/blob/master/benchmark/README.md

Execute the evaluability fast-path benchmark script with enforcement enabled. This command enforces a minimum speedup and outputs results in JSON format. The benchmark exits with a non-zero status if the measured speedup is below the configured threshold.

```bash
dart run benchmark/evaluability_fast_path_benchmark.dart --enforce --min-speedup=1.02 --json-out=benchmark/results/evaluability_fast_path.json
```

--------------------------------

### Function Power Notation in LaTeX

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Shows how to use power notation for functions in LaTeX, including positive, negative, and fractional exponents.

```latex
\sin^2{x} + \cos^2{x}    % Pythagorean identity
```

```latex
\tan^3{\theta}           % Third power of tangent
```

```latex
\sin^{-1}{x}             % Power of -1 on sin
```

--------------------------------

### Function Arguments in LaTeX

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Demonstrates recommended and alternative ways to pass arguments to functions in LaTeX, including using braces, parentheses, or relying on implicit multiplication.

```latex
\sin{x}       % Recommended: braces
```

```latex
\sin(x)       % Also works: parentheses
```

```latex
\sin x        % Works with implicit multiplication enabled
```

--------------------------------

### Complex Number Operations

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Provides examples of common arithmetic operations on Complex numbers, such as addition, subtraction, multiplication, and division.

```dart
z1 + z2;    // Addition
z1 - z2;    // Subtraction
z1 * z2;    // Multiplication
z1 / z2;    // Division
-z;         // Negation
```

--------------------------------

### Vector Creation

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Demonstrates various ways to create Vector instances, including from a list of components and specific dimensional constructors.

```dart
final v = Vector([3, 4]);
Vector.fromXY(3, 4);      // 2D vector
Vector.fromXYZ(1, 2, 3);  // 3D vector
```

--------------------------------

### Evaluate Expression with Variables

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/evaluator.md

Evaluates an expression using a provided map of variables. The example shows how variables 'x' and 'y' are resolved to their values.

```dart
final result = evaluator.evaluate(r'x^2 + y', {'x': 3, 'y': 5});
// x → 3, y → 5
// 3^2 + 5 = 14
```

--------------------------------

### Registering a Safe Math Extension

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/security.md

Register custom evaluators for extensions. This example shows a safe 'double' function that multiplies its argument by 2.

```dart
// SAFE: Simple math extension
registry.registerEvaluator((expr, vars, eval) {
  if (expr is FunctionCall && expr.name == 'double') {
    return eval(expr.argument) * 2;
  }
  return null;
});
```

--------------------------------

### Matrix Creation

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Shows how to initialize a Matrix object with a list of lists representing its elements.

```dart
final m = Matrix([
  [1, 2],
  [3, 4],
]);
```

--------------------------------

### LaTeX Syntax for Limits

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/calculus.md

Illustrates the general LaTeX format for defining limit expressions.

```latex
\lim_{variable \to target} expression
```

--------------------------------

### LaTeX Binomial Coefficient Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Use \binom{n}{k} to represent binomial coefficients in LaTeX. An example shows \binom{10}{3}.

```latex
\binom{n}{k}
```

--------------------------------

### Disable Implicit Multiplication in TeXpr

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/tokenizer.md

Disable implicit multiplication when you need to use multi-character variable names. This example shows how to instantiate the evaluator with this option.

```dart
final evaluator = Texpr(allowImplicitMultiplication: false);
// Now "velocity" is a single variable, not v*e*l*o*c*i*t*y
evaluator.evaluate('velocity * time', {'velocity': 10, 'time': 5});
```

--------------------------------

### Run Evaluability Fast-Path Benchmark

Source: https://github.com/xirf/texpr/blob/master/benchmark/README.md

Execute the evaluability fast-path benchmark script. This command runs the benchmark without any specific enforcement flags.

```bash
dart run benchmark/evaluability_fast_path_benchmark.dart
```

--------------------------------

### Environment Methods

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Methods for managing the global environment variables.

```APIDOC
## clearEnvironment

### Description
Clear all persistent global variables stored in the environment.

### Method
`clearEnvironment()`
```

--------------------------------

### Non-Simplified Expression in TeXpr

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/symbolic.md

TeXpr does not enforce canonical forms. This example shows an expression that is not simplified further by the engine, even though a simpler form exists.

```dart
// This does NOT simplify
engine.simplify(parse('2x + 3x'));    // → 2x + 3x (not 5x)
```

--------------------------------

### Run MathML Integration Tests

Source: https://github.com/xirf/texpr/blob/master/test/integration/mathml/README.md

Execute the integrated MathML export and validation tests from the project root.

```bash
# From project root
./test/integration/mathml/run_tests.sh
```

--------------------------------

### Handling Function Domain Errors

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/evaluator.md

Shows an example of a function domain error, specifically when the input to the arcsin function is outside its valid range of [-1, 1].

```dart
evaluator.evaluate(r'\arcsin{2}');  
// Domain error: arcsin requires -1 ≤ x ≤ 1
```

--------------------------------

### Run Dart Benchmarks

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/performance.md

Execute the advanced benchmark suite for TeXpr using the Dart CLI.

```bash
dart run benchmark/advanced_benchmark.dart
```

--------------------------------

### Run SymPy Integration Tests

Source: https://github.com/xirf/texpr/blob/master/test/integration/sympy/README.md

Execute the SymPy integration tests using the provided shell script. This is the quickest way to run the full test suite.

```bash
./test/integration/sympy/run_tests.sh
```

--------------------------------

### Texpr Constructor Options

Source: https://github.com/xirf/texpr/blob/master/doc/reference/index.md

Details the available options for configuring the Texpr class constructor.

```APIDOC
## Texpr Constructor Options

### Description
Configure the behavior of the Texpr instance during initialization.

### Parameters

- **`cacheConfig`** (any) - Optional - Default: `enabled` - Configures the LRU cache behavior.
- **`extensions`** (any) - Optional - Default: `none` - Provides a registry for custom functions.
- **`maxRecursionDepth`** (integer) - Optional - Default: `500` - Sets the maximum allowed recursion depth for expression evaluation.
```

--------------------------------

### Caching Example

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/index.md

TeXpr utilizes a multi-layer cache (L1-L4) to store parsed ASTs, evaluation results, differentiation results, and sub-expression results, avoiding redundant computations.

```plaintext
If you evaluate sin(x)^2 + cos(x)^2 multiple times with different x values, L1 caches the AST so it's only parsed once.
```

--------------------------------

### Validate MathML Export with Python

Source: https://github.com/xirf/texpr/blob/master/test/integration/mathml/README.md

Activate the Python virtual environment and run the validation script to check the generated MathML test cases.

```bash
# 2. Activate Python venv and run validation
source test/integration/mathml/.venv/bin/activate
python test/integration/mathml/verify_mathml_export.py
```

--------------------------------

### Recognizing LaTeX Commands

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/tokenizer.md

When a backslash is encountered, the tokenizer reads the command name to identify FUNCTION, CONSTANT, or VARIABLE tokens. Examples include \sin, \frac, \pi, and \alpha.

```text
"\sin"    → FUNCTION(sin)
"\frac"   → FUNCTION(frac)
"\pi"     → CONSTANT(π)
"\alpha"  → VARIABLE(α)
```

--------------------------------

### Texpr Constructor

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Initializes a new TeXpr instance with configurable options for extensions, implicit multiplication, caching, recursion depth, and real-number evaluation.

```APIDOC
## Texpr Constructor

### Description
Initializes a new TeXpr instance with configurable options.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **extensions** (`ExtensionRegistry?`) - Optional - Custom commands and evaluators.
- **allowImplicitMultiplication** (`bool`) - Optional - Default: `true`. Treat `xy` as `x * y`.
- **cacheConfig** (`CacheConfig?`) - Optional - Default: `CacheConfig()`. Cache size and eviction settings.
- **maxRecursionDepth** (`int`) - Optional - Default: `500`. Max recursion for parsing/evaluation.
- **realOnly** (`bool`) - Optional - Default: `false`. Only evaluate real numbers, return NaN for complex results.
```

--------------------------------

### Registering an Unsafe Eval Extension

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/security.md

Avoid creating unsafe extensions. This example demonstrates a dangerous 'eval' function that should not be used with user input due to potential security risks.

```dart
// UNSAFE: Don't do this
registry.registerEvaluator((expr, vars, eval) {
  if (expr is FunctionCall && expr.name == 'eval') {
    // Never pass user input to Dart's `dart:mirrors` or similar
    return dangerousEval(expr.argument.toString());
  }
  return null;
});
```

--------------------------------

### Enable and Access Cache Statistics

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/caching.md

Initialize Texpr with statistics enabled to monitor cache performance. Access statistics after performing evaluations to check hit rates and counts for parsed expressions and evaluation results.

```dart
final evaluator = Texpr(
  cacheConfig: CacheConfig.withStatistics,
);

// ... perform many evaluations ...

final stats = evaluator.cacheStatistics;
print('Overall hit rate: ${(stats.overallHitRate * 100).toFixed(1)}%');
print('L1 (parsed): ${stats.parsedExpressions.hits} hits, ${stats.parsedExpressions.misses} misses');
print('L2 (results): ${stats.evaluationResults.hits} hits, ${stats.evaluationResults.misses} misses');
```

--------------------------------

### LaTeX Limit Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

The syntax for limits in LaTeX is \lim_{x \to a} f(x). An example shows the limit of \frac{\sin{x}}{x} as x approaches 0.

```latex
\lim_{x \to a} f(x)
```

--------------------------------

### Manual SymPy Test Execution Steps

Source: https://github.com/xirf/texpr/blob/master/test/integration/sympy/README.md

Manually run the Dart test to generate test cases, then activate the Python virtual environment and execute the verification script. This provides more control over the testing process.

```bash
# 1. Run Dart test to generate JSON
dart test test/integration/sympy/sympy_export_integration_test.dart
```

```bash
# 2. Activate Python venv and run verification
source test/integration/sympy/.venv/bin/activate
pip install -r test/integration/sympy/requirements.txt
python test/integration/sympy/verify_sympy_export.py
```

--------------------------------

### Define and Call Custom Functions in Texpr

Source: https://github.com/xirf/texpr/blob/master/doc/guide/environments.md

Shows how to define single and multi-parameter functions in Texpr and then call them with different arguments. Nested calls are also demonstrated.

```dart
final texpr = Texpr();

// Define a function
texpr.evaluate(r'f(x) = x^2');

// Call the function
print(texpr.evaluate('f(3)').asNumeric());        // 9.0
print(texpr.evaluate('f(5)').asNumeric());        // 25.0

// Multi-parameter functions
texpr.evaluate(r'g(a, b) = a + b');
print(texpr.evaluate('g(2, 3)').asNumeric());     // 5.0

// Nested function calls
print(texpr.evaluate('f(g(1, 2))').asNumeric());  // 9.0 (f(3) = 9)
```

--------------------------------

### Define and Use Variables

Source: https://github.com/xirf/texpr/blob/master/doc/guide/environments.md

Define variables using 'let' for use in subsequent expressions. Variables persist in the Texpr instance's global environment.

```latex
let x = 5
let y = 10
x + y  // Result: 15
```

--------------------------------

### Initialize and Run WASM Module

Source: https://github.com/xirf/texpr/blob/master/wasm/build/index.html

This snippet initializes the WASM module, captures console output, and handles status updates. It's used to load and execute the compiled WebAssembly application.

```javascript
import { compileStreaming } from './main.mjs'; // Capture console.log output const output = document.getElementById("output"); const status = document.getElementById("status"); const logs = []; const originalLog = console.log; console.log = function (...args) { originalLog.apply(console, args); logs.push(args.join(" ")); output.textContent = logs.join("\n"); }; const originalError = console.error; console.error = function (...args) { originalError.apply(console, args); status.className = "status error"; status.textContent = "Error: " + args.join(" "); }; async function init() { try { status.textContent = "Loading WASM module..."; const compiledApp = await compileStreaming(fetch('main.wasm')); const app = await compiledApp.instantiate({}); // Execute main() which sets up the exports app.invokeMain(); // Verify export if (window.texpr) { status.className = "status success"; status.textContent = "WASM loaded. API ready at window.texpr"; console.log("Found window.texpr. Testing..."); console.log("2 + 2 =", window.texpr.evaluate("2 + 2")); console.log("\\sin(0) =", window.texpr.evaluate("\\sin(0)")); } else { throw new Error("window.texpr not found after invokeMain"); } } catch (e) { console.error("WASM Init Failed:", e); } } init();
```

--------------------------------

### Calculus Methods

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Methods for performing symbolic differentiation and integration of expressions.

```APIDOC
## differentiate

### Description
Compute the symbolic derivative of an expression with respect to a variable.

### Method
`differentiate(dynamic expr, String variable, {int order = 1})`

### Parameters
- **expr** (`dynamic`) - Required - The expression to differentiate.
- **variable** (`String`) - Required - The variable with respect to which to differentiate.
- **order** (`int`) - Optional - Default: `1`. The order of the derivative.
```

```APIDOC
## integrate

### Description
Compute the symbolic antiderivative (integral) of an expression with respect to a variable.

### Method
`integrate(dynamic expr, String variable)`

### Parameters
- **expr** (`dynamic`) - Required - The expression to integrate.
- **variable** (`String`) - Required - The variable with respect to which to integrate.
```

--------------------------------

### Run Dart Benchmark

Source: https://github.com/xirf/texpr/blob/master/benchmark/comparison/README.md

Execute the advanced benchmark for texpr in Dart. Ensure you are in the texpr project directory.

```bash
cd /path/to/texpr
dart run benchmark/advanced_benchmark.dart
```

--------------------------------

### Parse Matrix Environment

Source: https://github.com/xirf/texpr/blob/master/doc/how-it-works/parser.md

The parser recognizes \begin{pmatrix}, parses expressions separated by & (columns) and \\ (rows), creates a MatrixExpr, and expects \end{pmatrix}.

```latex
\begin{pmatrix}
  1 & 2 \\
  3 & 4
\end{pmatrix}
```

--------------------------------

### Evaluate Basic Limits

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/calculus.md

Compute limits by direct substitution and numerical probing. Supports standard mathematical notation.

```dart
evaluator.evaluate(r'\lim_{x \to 0} (x + 1)');  // 1.0
```

```dart
evaluator.evaluate(r'\lim_{x \to \infty} \frac{1}{x}');  // 0.0
```

--------------------------------

### Creating Complex Numbers

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Illustrates different ways to instantiate Complex numbers, including from real and imaginary parts, and from a single real number.

```dart
Complex(3, 4);           // 3 + 4i
Complex.fromNum(5);      // 5 + 0i
```

--------------------------------

### Accessing Built-in Constants

Source: https://github.com/xirf/texpr/blob/master/doc/reference/constants.md

Demonstrates how to access built-in constants using both LaTeX command notation and variable name notation. LaTeX notation is recommended for multi-character constants.

```dart
final evaluator = Texpr();

// LaTeX command notation (Recommended for multi-character)
evaluator.evaluateNumeric(r'\hbar');  // 1.05457...
evaluator.evaluateNumeric(r'\pi');     // 3.14159...

// Variable name notation
evaluator.evaluateNumeric('pi');  // 3.14159... (if allowImplicitMultiplication is false)
evaluator.evaluateNumeric('e');   // 2.71828...
```

--------------------------------

### Complex Number Support in LaTeX

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

Illustrates how to represent and work with complex numbers in LaTeX, including the imaginary unit 'i', complex exponentiation, and complex trigonometry.

```latex
3 + 4i
```

```latex
e^{i\pi}
```

```latex
\sqrt{-1}     % Returns i
```

```latex
\sin{1 + 2i} % Complex trigonometry
```

--------------------------------

### Complex Number Creation and Properties

Source: https://github.com/xirf/texpr/blob/master/doc/reference/data-types.md

Shows how to create Complex number instances and access their real and imaginary parts, magnitude, and phase.

```dart
final z = Complex(3, 4);  // 3 + 4i
z.real;        // 3.0
z.imaginary;   // 4.0
z.abs;         // 5.0 (magnitude)
z.arg;         // 0.927... (phase angle)
z.conjugate;   // 3 - 4i
```

--------------------------------

### Evaluate Mathematical Expressions in Dart

Source: https://github.com/xirf/texpr/blob/master/doc/guide/index.md

Demonstrates basic evaluation of mathematical expressions with and without variables using the TeXpr library. Ensure the 'texpr' package is imported.

```dart
import 'package:texpr/texpr.dart';

final evaluator = Texpr();

// Simple evaluation
final result = evaluator.evaluate(r'\sqrt{16} + \sin{\pi}');
print(result.asNumeric());  // 4.0

// With variables
final hypotenuse = evaluator.evaluate(
  r'\sqrt{x^2 + y^2}', 
  {'x': 3.0, 'y': 4.0}
);
print(hypotenuse.asNumeric());  // 5.0

// Symbolic differentiation
final derivative = evaluator.differentiate(r'x^3', 'x');
final slope = evaluator.evaluateParsed(derivative, {'x': 2.0});
print(slope.asNumeric());  // 12.0
```

--------------------------------

### LaTeX Syntax for Summation

Source: https://github.com/xirf/texpr/blob/master/doc/advanced/calculus.md

Shows the standard LaTeX format for defining summation operations.

```latex
\sum_{variable=start}^{end}{expression}
```

--------------------------------

### Export AST to MathML

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Converts the expression's Abstract Syntax Tree (AST) into MathML format using MathMLVisitor.

```dart
final mathml = MathMLVisitor().visit(expr);
// <math>...</math>

```

--------------------------------

### LaTeX Integral Syntax

Source: https://github.com/xirf/texpr/blob/master/doc/reference/latex.md

LaTeX syntax for integrals includes \int{f} dx for indefinite integrals, \int_{a}^{b}{f} dx for definite integrals, \iint{f} dx dy for double integrals, and \iiint{f} dx dy dz for triple integrals.

```latex
\int{f} dx
```

```latex
\int_{a}^{b}{f} dx
```

```latex
\iint{f} dx dy
```

```latex
\iiint{f} dx dy dz
```

--------------------------------

### Texpr Class Constructor

Source: https://github.com/xirf/texpr/blob/master/doc/reference/api.md

Instantiate the Texpr class with optional configuration for extensions, implicit multiplication, caching, recursion depth, and real number evaluation.

```dart
Texpr({ 
  ExtensionRegistry? extensions,
  bool allowImplicitMultiplication = true,
  CacheConfig? cacheConfig,
  int maxRecursionDepth = 500,
  bool realOnly = false,
})
```
Tokens:
Raw