simple_equation_inversion
Define an equation once, solve it for any variable — fully no_std.
simple_equation_inversion is a Rust library for solving linear equations and invertible function chains. Given an equation with one unknown variable, it isolates and computes the value of the unknown.
Usage
The crate provides three ways to express equations, plus support for custom invertible transformations.
1. Inline Expressions (solve!)
For direct computations without declaring a struct:
#
2. Struct Model (#[derive(Equation)])
For domain structs where fields represent equation variables. Define the relationship directly with #[equation(...)]:
#
You can also omit #[equation(...)] and implement EquationAutoCompute manually if needed:
#
3. Declarative Formula (declare_equation!)
Generates a struct with builder setters from a formula string. Free variables are detected at compile time, and whichever variable is omitted (None) is solved for:
#
// Solve for energy (energy is omitted):
let e = new
.mass
.v_squared
.solve?;
assert_eq!;
// Solve for mass (mass is omitted):
let m = new
.energy
.v_squared
.solve?;
assert_eq!;
# Ok
# }
An attribute macro is also available for empty structs:
#
4. Invertible Transformations
Equations can include custom transformations as long as an inverse is provided. Functions can be called directly in equations (f(x)).
Closure-based (FnTransform)
#
In declare_equation!
#
let required = new
.position
.price
.solve?;
# Ok
# }
Custom Transform Implementation
For stateful or fallible transformations, implement the Transform trait:
#
How It Works
Expressions are represented as an ElementKind tree:
Known(f64): A known scalar constant.Variable { factor, unknown, offset }: An unknown in affine form (factor * x + offset).Transformed { factor, transform, inner, offset }: A transformation applied to an expression (factor * T(inner) + offset).
When Equation::new(lhs, rhs).solve() or solve!(lhs = rhs) is called, the solver reduces the expression to lhs - rhs = 0 and isolates x:
- If the node is
Variable, $x = -\text{offset} / \text{factor}$. - If the node is
Transformed, the solver inverts the transform and recurses oninner. - If the node is
Known, returnsError::NoUnknown.
Error Handling
All solvers return Result<f64, simple_equation_inversion::Error>.
| Error Variant | Cause |
|---|---|
NoUnknown |
No unknown variable found in the equation |
SeveralUnknown |
More than one distinct unknown variable found |
DivisionByZero |
Division by a constant evaluating to 0 |
UnknownInDenominator |
Variable appears in a denominator |
SquareForbidden |
Multiplication of two variable terms ($x \cdot x$) |
TransformError |
A Transform's apply or invert returned an error |
Errors are latched during expression evaluation and returned on .solve() rather than panicking.
Diagnostics
Logging can be enabled via Cargo features:
debug-structure: Prints struct field analysis at macro expansion time.debug-setup: Logs field values and unknown detection at runtime.debug-compute: Traces equation reduction and solving steps.debug-all: Enables all of the above.
Benchmarks
Run benchmarks with Criterion:
Measurements (Intel / AMD x86_64, Linux):
| Implementation | Time |
|---|---|
Direct analytical formula (c - b) / a |
~1.5 ns |
solve! macro |
~129 ns |
declare_equation! struct |
~145 ns |
#[derive(Equation)] struct |
~200 ns |
FnTransform inversion |
~227 ns |
Examples
Run the examples in examples/:
Running Tests
License
Dual-licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.