functionx

A powerful equation parser and solver for Dart — f(x) for your code.

Features

🧮 Expression Parsing - Strictly explicit parsing (e.g. 2*x, m*a) for maximum predictability
📊 Variable Extraction - Intelligently extract variables while filtering constants
🔢 Expression Evaluation - Multi-mode evaluation (Real, Complex, and Mixed)
⚡ Equation Solving - Algebraic and numerical solvers
🔗 System Solver - Solve systems of non-linear equations (Real & Complex)
📈 Symbolic Calculus - Differentiation and integration
🔬 Auto-resolve Constants - Automatic identification of symbols like SOL, PC and BC
🇬🇷 LaTeX Support - Greek letters and subscripts, via EquationParser

Installation

Add to your pubspec.yaml:

dependencies:
  functionx: ^2.0.3

Two API tiers

This is the thing to understand before anything else.

Tier	Class	Use when
Primary	`EquationParser`	Almost always. Handles LaTeX, Greek letters and natural constants, and returns exact values where it can.
Core components	`ExpressionParser`, `Evaluator`, `Solver`, `SystemSolver`, `Cas`	You want one specific stage on already-clean input.

EquationParser is a façade over the core components that adds LaTeX cleaning and constant resolution. The lower tier does not understand LaTeX:

EquationParser.extractVariables(r'\Delta E = h*\nu');   // [DeltaE, h, nu]
ExpressionParser.extractVariables(r'\Delta E = h*\nu'); // []  ← no LaTeX handling

The two also differ in precision. The core Solver falls back to numerical methods:

Solver.solve('F = m*a', {'F': 10, 'm': 2}, solveFor: 'a').value;
// 5.000000000032756  ← numerically approximated

EquationParser.solve('F = m*a', {'F': 10, 'm': 2}, solveFor: 'a').solvedValue;
// 5.0                ← exact

Quick Start

import 'package:functionx/functionx.dart';

void main() {
  // Extract variables from an equation
  final vars = EquationParser.extractVariables('y = m*x + b');
  print(vars); // [b, m, x, y]

  // Evaluate an expression
  final result = EquationParser.evaluate('x^2 + 2*x + 1', {'x': 3});
  print(result); // 16.0

  // Solve for an unknown
  final solution = EquationParser.solve(
    'F = m*a',
    {'F': 10, 'm': 2},
    solveFor: 'a',
  );
  print(solution.solvedValue); // 5.0

  // Solve a system of equations
  final system = SystemSolver.solve(['x^2 + y^2 = 1', 'y = x']);
  print(system.values); // {x: 0.7071, y: 0.7071}

  // Use physical constants
  final c = EquationParser.getConstant('SOL');
  print('${c?.name}: ${c?.value} ${c?.unit}'); // Speed of Light: 299792458.0 m/s
}

EquationParser

The primary API. Every method is static.

// Variables — `excludeConstants` drops recognised constant keys
EquationParser.extractVariables('F = m*a');                          // [F, a, m]
EquationParser.extractVariables('E = m*SOL^2', excludeConstants: true);

// Evaluate (supports complex results, e.g. sqrt(-1))
EquationParser.evaluate('x^2 + y', {'x': 3, 'y': 5});                // 14.0

// Solve. Give every known value; name the unknown with `solveFor`.
final r = EquationParser.solve('y = 2*x + 3', {'x': 5.0}, solveFor: 'y');
r.solvedValue;   // the answer
r.allValues;     // every root, when there is more than one
r.steps;         // List<SolutionStep> derivation
r.error;         // non-null if solving failed

// Systems — takes the equations *and* a map of already-known values
EquationParser.solveSystem(['x + y = 10', 'x - y = 2'], {}); // solvedValue: 6.0

// Constants appearing in an equation, pre-filled and ready to substitute
EquationParser.getPrefilledValues('E = m*SOL^2');                    // {SOL: 299792458.0}
EquationParser.getConstant('GC');                                   // NaturalConstant
EquationParser.naturalConstants;                                    // the whole map

// Strip LaTeX down to plain notation
EquationParser.cleanLatex(r'\Delta E = h*\nu');

solveFor is effectively required. Without it, solve returns a result whose solvedValue is null and whose error is also null — it does not infer the unknown from a missing map entry.

EquationResult

Field	Type	Meaning
`solvedValue`	`dynamic`	The computed value (`double` or `Complex`)
`allValues`	`List<dynamic>?`	All roots, where applicable
`steps`	`List<SolutionStep>`	Derivation steps (`type` + `data` map)
`error`	`String?`	Message if solving failed

NaturalConstant

Fields: value, name, unit, symbol.

EquationParser.naturalConstants carries its own set of 37 keys, which is not the same set as the Constants class below — it additionally includes the parser tokens PI, EN, IN and INF.

Expression Syntax

This parser is designed to be ergonomic but strictly explicit:

✅ Notation	📝 Example
Explicit	`2x + 3y`
Parentheses	`3(x+1)(x-1)`
Complex	`(1+IN)*IN` → `-1 + i`
Greek (via `EquationParser`)	`\Delta E = h*\nu`
Subscripts	`x_1 + x_2`

Subscripts may be words, not just digits: ATP_total = ATP_gly + ATP_etc parses fine.

Supported Operators

Operator	Description
`+`	Addition
`-`	Subtraction
`*`	Multiplication
`/`	Division
`^`	Exponentiation

Supported Functions

All verified working: sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), sqrt(x), abs(x), log(x), ln(x), exp(x), pow(x, n).

Note that log is the natural logarithm, identical to ln — log(EN) is 1.0.

Parser Tokens

Token	Value
`PI`	3.14159...
`EN`	2.71828...
`INF`	Infinity
`IN`	i (√-1)

Reserved Words & Aliases

To avoid ambiguity (like c for the speed of light vs c for a variable), functionx uses strict constant lookup. You must use the specific keys below for a symbol to resolve to a constant; common letters like c, g and h stay plain variables.

Functions: sin, cos, tan, asin, acos, atan, sqrt, abs, log, ln, exp, pow
Parser tokens: PI, EN, INF, IN
Natural constants (keys): SOL (Speed of Light), GC (Gravitational), PC (Planck), SG (Standard Gravity), AN (Avogadro), BC (Boltzmann), and others listed below

Avogadro's key is AN, not NA. NA is its symbol; Constants.get('NA') returns null.

Core Components

Use these when you want a single stage and your input is already plain notation.

ExpressionParser

final result = ExpressionParser.parse('y = m*x + b');
print(result.isEquation); // true
// also: result.expression, result.left, result.right

ExpressionParser.extractVariables('F = m*a'); // [F, a, m]

Evaluator

Evaluator.evaluate('x^2 + y', {'x': 3, 'y': 5}); // 14.0  (returns double)
Evaluator.evaluateNumeric('2 + 3 * 4');          // 14.0
Evaluator.evaluateMixed('(1+IN)*IN');            // -1 + i
Evaluator.canEvaluate('x + 1', {'x': 1});        // true

Solver

Returns a SolveResult with value, variable, steps (List<String>), isNumeric, error and success. Results are numerically approximated — compare with a tolerance rather than for equality.

final result = Solver.solve('2*x + 5 = 11', {'x': null});
print(result.value);   // 2.9999999999752447
print(result.success); // true

SystemSolver

Returns a SystemSolveResult with values (a Map<String, Complex>), success, error and iterations.

final system = SystemSolver.solve(['x^2 + y^2 = 1', 'y = x']);
print(system.values); // {x: 0.7071, y: 0.7071}

Cas (Computer Algebra System)

Symbolic differentiation and integration. Output is unsimplified, so expect mathematically correct but verbose results:

Cas.differentiate('x^2', 'x'); // ((x^2.0) * (2.0 * (1.0 / x)))
Cas.differentiate('x^3', 'x'); // ((x^3.0) * (3.0 * (1.0 / x)))
Cas.integrate('x', 'x');       // 0.5*x^2
Cas.simplify('x + x');         // (x + x)   ← does not collect like terms
Cas.evaluate('2 + 3');         // (2.0 + 3.0) ← also unevaluated

Cas.simplify currently normalises structure rather than reducing an expression; do not rely on it to collapse x + x into 2*x.

Constants

A separate collection of physical and mathematical constants, indexed by key.

final c = Constants.speedOfLight;
print(c.value);  // 299792458.0
print(c.symbol); // c
print(c.unit);   // m/s
print(c.name);   // Speed of Light

Constants.get('GC')?.value;          // 6.6743e-11
Constants.search('mass');            // 6 matches

// byCategory returns Constant objects, not keys
Constants.byCategory('fundamental').map((c) => c.key); // (SOL, PC, HBAR, GC)

Category	Keys
`mathematical`	`PI`, `EN`, `IN`, `PHI`, `SQRT2`
`fundamental`	`SOL`, `PC`, `HBAR`, `GC`
`electromagnetic`	`EC`, `VP`, `VPM`, `CC`
`atomic`	`ME`, `MP`, `MN`, `BR`, `FSC`, `RYD`, `BM`, `NM`, `PEM`
`thermodynamic`	`BC`, `AN`, `RG`, `ATM`, `SBC`, `WIE`, `C1`, `C2`
`quantum`	`MFQ`, `CQ`, `JC`, `VK`
`electrochemical`	`FC`
`earth`	`SG`, `EM`, `ER`
`celestial`	`SM`, `SR`, `AU`, `LY`

Common Constants

Property	Key	Symbol	Value
`Constants.speedOfLight`	`SOL`	c	299792458.0 m/s
`Constants.planck`	`PC`	h	6.62607015e-34 J⋅s
`Constants.gravitationalConstant`	`GC`	G	6.6743e-11 N⋅m²/kg²
`Constants.boltzmann`	`BC`	kB	1.380649e-23 J/K
`Constants.avogadro`	`AN`	NA	6.02214076e23 1/mol
`Constants.faraday`	`FC`	F	96485.33212 C/mol
`Constants.rydberg`	`RYD`	R∞	10973731.56816 1/m
`Constants.standardGravity`	`SG`	g	9.80665 m/s²
`Constants.elementaryCharge`	`EC`	e	1.602176634e-19 C
`Constants.coulomb`	`CC`	k	8987551792.3 N⋅m²/C²
`Constants.pi`	`PI`	π	3.141592653589793
`Constants.e`	`EN`	e	2.718281828459045
`Constants.imaginaryUnit`	`IN`	i	√-1 (`.value` is `NaN`)

License

MIT License - see LICENSE for details.