Equations & Complex Numbers
New to solving at the prompt? R5 — Equations walks through solve and its answers in one short lesson. This page is the reference.
import it.grypho.scala.leonardo.core.*
import it.grypho.scala.leonardo.scalar.*
import it.grypho.scala.leonardo.equation.*
import it.grypho.scala.leonardo.parser.Parser
val x = _Variable("x")
val env = new Environment()
Equations
An _Equation(lhs, rhs) is a relation node. When both sides reduce to concrete values, eval returns a _Bool using tolerance-based equality (|a − b| ≤ 0.5 × 10⁻ᵖ at precision p), so floating-point noise does not produce false negatives:
// 2x = 6 at x = 3 → true
val eq1 = _Equation(Product(_Number(2.0), x), _Number(6.0))
// eq1: _Equation = _Equation(
// lhs = Product(a = _Number(2.0), b = _Variable("x")),
// rhs = _Number(6.0)
// )
val envX3 = new Environment(5, Map("x" -> _Number(3.0)))
// envX3: Environment = it.grypho.scala.leonardo.core.Environment@547968af
eq1.eval(envX3)
// res0: Either[_Expression, _Value] = Right(_Bool(true))
// sin(π) = 0 — true despite floating-point noise
_Equation(Sin(_Number(math.Pi)), _Number(0.0)).eval(env)
// res1: Either[_Expression, _Value] = Right(_Bool(true))
Equations with free variables stay symbolic:
eq1.eval(env)
// res2: Either[_Expression, _Value] = Left(
// _Equation(
// lhs = Product(a = _Number(2.0), b = _Variable("x")),
// rhs = _Number(6.0)
// )
// )
Equality check (==)
_EqualityCheck has the same semantics as _Equation but is not accepted by solve. Use it when you want a boolean result without the intent to solve:
Parser.parse("x^2 == x * x").get.eval(envX3)
// res3: Either[_Expression, _Value] = Right(_Bool(true))
Solving equations
All solve examples use the solve(…, v) grammar, which builds a _Solve node evaluated by calling the underlying solve algorithm:
Linear equations
// 2x + 3 = 7 → x = 2
Parser.parse("solve(2*x + 3 = 7, x)").get.eval(env)
// res4: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("x"), rhs = _Number(2.0))
// )
// Inline: a*x + b = 0 with concrete a, b
Parser.parse("solve(3*x - 6 = 0, x)").get.eval(env)
// res5: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("x"), rhs = _Number(2.0))
// )
Quadratic equations
The discriminant decides the case; 0, 1, or 2 real roots are returned, computed by the numerically stable form of the quadratic formula rather than the textbook (-b ± √Δ)/2a:
// x² - 5x + 6 = 0 → x = 2, x = 3
Parser.parse("solve(x^2 - 5*x + 6 = 0, x)").get.eval(env)
// res6: Either[_Expression, _Value] = Left(
// _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(
// _Equation(lhs = _Variable("x"), rhs = _Number(2.0)),
// _Equation(lhs = _Variable("x"), rhs = _Number(3.0))
// )
// )
// )
// x² + 1 = 0 → no real roots
Parser.parse("solve(x^2 + 1 = 0, x)").get.eval(env)
// res7: Either[_Expression, _Value] = Left(
// _Solve(
// eq = _Equation(
// lhs = Sum(
// a = Power(base = _Variable("x"), exp = _Number(2.0)),
// b = _Number(1.0)
// ),
// rhs = _Number(0.0)
// ),
// v = _Variable("x")
// )
// )
A double root is recognised only when the discriminant is within its own rounding of zero, so x^2 - 0.6*x + 0.09 = 0 has the one root 0.3, while two roots 10⁻⁶ apart stay two.
Polynomials and rational functions
An equation that is a rational function of the unknown with numeric coefficients has every real root found, of any degree, a repeated one included:
// (x - 1)²(x + 5) = 0 → x = -5, x = 1
Parser.parse("solve((x - 1)^2*(x + 5) = 0, x)").get.eval(env)
// res8: Either[_Expression, _Value] = Left(
// _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(
// _Equation(lhs = _Variable("x"), rhs = _Number(-5.0)),
// _Equation(lhs = _Variable("x"), rhs = _Number(1.0))
// )
// )
// )
The roots are read from the factors as written: each factor’s roots are found alone and a written power is a multiplicity, because multiplying the factors out is what makes close roots indistinguishable — (x - 1)*(x - 1.00001) has its roots exactly in its factors, and only a cancellation in its coefficients. An inequality, domain and singularities read their points the same way, so solve((x - 1)*(x - 1.00001) > 0, x) is x < 1 or x > 1.00001. What this does not cover: a polynomial of degree three or more typed already multiplied out, whose repeated roots are found by a square-free factorisation with a tolerance — two of its roots closer than about 10⁻⁵ of their size read as one. Under exact on there is no such limit: the roots are isolated exactly.
Numeric fallback
Transcendental equations fall back to a sign-change scan over [-100, 100] followed by the bisection method, keeping the 8 roots nearest 0, in ascending order:
// sin(x) = 0.5 — the roots nearest 0: π/6, 5π/6, …
Parser.parse("solve(sin(x) = 0.5, x)").get.eval(env)
// res9: Either[_Expression, _Value] = Left(
// _Matrix(
// rows = 1,
// cols = 8,
// elems = Vector(
// _Equation(lhs = _Variable("x"), rhs = _Number(-12.042771838760874)),
// _Equation(lhs = _Variable("x"), rhs = _Number(-9.948376736367678)),
// _Equation(lhs = _Variable("x"), rhs = _Number(-5.759586531581288)),
// _Equation(lhs = _Variable("x"), rhs = _Number(-3.6651914291880923)),
// _Equation(lhs = _Variable("x"), rhs = _Number(0.5235987755982989)),
// _Equation(lhs = _Variable("x"), rhs = _Number(2.617993877991494)),
// _Equation(lhs = _Variable("x"), rhs = _Number(6.806784082777885)),
// _Equation(lhs = _Variable("x"), rhs = _Number(8.901179185171081))
// )
// )
// )
Such a list is never all of them, and at the prompt solve says so: a periodic equation (the unknown only inside sin/cos/tan/… of linear arguments with one slope) gets a note naming its period, and any other equation with more roots in the scan than were kept gets a note saying how many were found.
Matrix equations (scalar unknown)
When both sides are matrices, solve finds a scalar unknown by decomposing the equation into its per-cell scalar equations and keeping the value that satisfies every cell (the intersection of the per-cell solution sets):
// each cell agrees on x = 3
Parser.parse("solve([[x, 2*x]] = [[3, 6]], x)").get.eval(env)
// res10: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("x"), rhs = _Number(3.0))
// )
An inconsistent system — where different cells demand different values — has no solution, so the node stays symbolic:
// cell 1 wants x = 1, cell 2 wants x = 2 → no common root
Parser.parse("solve([[x, x]] = [[1, 2]], x)").get.eval(env)
// res11: Either[_Expression, _Value] = Left(
// _Solve(
// eq = _Equation(
// lhs = _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(_Variable("x"), _Variable("x"))
// ),
// rhs = _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(_Number(1.0), _Number(2.0))
// )
// ),
// v = _Variable("x")
// )
// )
Matrix equations (matrix unknown)
When the unknown is itself a matrix in a linear equation A·X = B (or X·A = B), solve returns the unique solution X = A⁻¹·B via the inverse kernel. The known matrices must be bound so the parser sees a plain product (a bare X is a scalar variable syntactically):
val A = _MatrixValue(2, 2, Array(2.0, 0.0, 0.0, 2.0))
// A: _MatrixValue = [[2.0, 0.0], [0.0, 2.0]]
val B = _MatrixValue(2, 2, Array(4.0, 6.0, 8.0, 10.0))
// B: _MatrixValue = [[4.0, 6.0], [8.0, 10.0]]
val mEnv = new Environment(5, Map("A" -> A, "B" -> B))
// mEnv: Environment = it.grypho.scala.leonardo.core.Environment@55ae0c01
// A·X = B → X = A⁻¹·B = [[2, 3], [4, 5]]
Parser.parse("solve(A * X = B, X)").get.eval(mEnv)
// res12: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("X"), rhs = [[2.0, 3.0], [4.0, 5.0]])
// )
A singular (non-invertible) A has no unique solution and stays symbolic.
Beyond the one-sided shapes, solve also recognises an affine term and a two-sided product. A constant matrix added on the unknown’s side is peeled to the right (A·X + C = B → A·X = B − C), and a matrix on each flank is handled by inverting both (A·X·D = B → X = A⁻¹·B·D⁻¹):
val D = _MatrixValue(2, 2, Array(5.0, 0.0, 0.0, 5.0))
// D: _MatrixValue = [[5.0, 0.0], [0.0, 5.0]]
val B2 = _MatrixValue(2, 2, Array(10.0, 20.0, 30.0, 40.0))
// B2: _MatrixValue = [[10.0, 20.0], [30.0, 40.0]]
val twoSidedEnv = new Environment(5, Map("A" -> A, "D" -> D, "B" -> B2))
// twoSidedEnv: Environment = it.grypho.scala.leonardo.core.Environment@f1a590e
// A·X·D = B → X = A⁻¹·B·D⁻¹ = [[1, 2], [3, 4]]
Parser.parse("solve(A * X * D = B, X)").get.eval(twoSidedEnv)
// res13: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("X"), rhs = [[1.0, 2.0], [3.0, 4.0]])
// )
The coefficients may be symbolic _Matrix literals with free variables, in which case the solution is a symbolic matrix expression (via cofactor expansion, capped at 6×6).
General linear matrix equations — the unknown appearing in several terms with coefficients on different sides — are solved by Kronecker vectorization: each term s·L·X·R contributes s·(Rᵀ ⊗ L) to a dense system over vec(X). This covers the Sylvester equation A·X + X·B = C, the Lyapunov equation A·X + X·Aᵀ = C, and scalar coefficients like 2·X = B:
// Sylvester: A·X + X·B = C with X = [[1, 0], [2, 1]] → C = [[9, 3], [14, 10]]
val sA = _MatrixValue(2, 2, Array(1.0, 2.0, 0.0, 3.0))
// sA: _MatrixValue = [[1.0, 2.0], [0.0, 3.0]]
val sB = _MatrixValue(2, 2, Array(4.0, 1.0, 0.0, 5.0))
// sB: _MatrixValue = [[4.0, 1.0], [0.0, 5.0]]
val sC = _MatrixValue(2, 2, Array(9.0, 3.0, 14.0, 10.0))
// sC: _MatrixValue = [[9.0, 3.0], [14.0, 10.0]]
val sylvesterEnv = new Environment(5, Map("A" -> sA, "B" -> sB, "C" -> sC))
// sylvesterEnv: Environment = it.grypho.scala.leonardo.core.Environment@6818e7ec
Parser.parse("solve(A * X + X * B = C, X)").get.eval(sylvesterEnv)
// res14: Either[_Expression, _Value] = Left(
// _Equation(lhs = _Variable("X"), rhs = [[1.0, 0.0], [2.0, 1.0]])
// )
The system is solvable only when it is non-singular — for Sylvester, when A and −B share no eigenvalue; otherwise the equation has no (unique) solution and the solve node stays symbolic. Exact coefficients are solved over the rationals and the answer is exact, up to 36 vectorized unknowns; numeric ones go through the dense kernel, up to 400.
Linear systems
solveSystem(equations, v₁, v₂, …) solves a linear system via Gaussian elimination (partial pivoting for concrete coefficients, symbolic row reduction otherwise, and exact elimination over the rationals when every coefficient is exact). The equations are a matrix literal, a row [[eq₁, eq₂]] or a column [[eq₁], [eq₂]]; the column reads like a system on paper:
// x + y = 3, x - y = 1 → x = 2, y = 1
Parser.parse("solveSystem([[x + y = 3], [x - y = 1]], x, y)").get.eval(env)
// res15: Either[_Expression, _Value] = Left(
// _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(
// _Equation(lhs = _Variable("x"), rhs = _Number(2.0)),
// _Equation(lhs = _Variable("y"), rhs = _Number(1.0))
// )
// )
// )
There may be more equations than unknowns, which is how “is b a combination of these vectors?” is asked. A consistent system is solved; an inconsistent one stays unevaluated, and the REPL names the equation that contradicts the ones before it:
// u = 1, v = 2, u + v = 3: consistent
Parser.parse("solveSystem([[u = 1], [v = 2], [u + v = 3]], u, v)").get.eval(env)
// res16: Either[_Expression, _Value] = Left(
// _Matrix(
// rows = 1,
// cols = 2,
// elems = Vector(
// _Equation(lhs = _Variable("u"), rhs = _Number(0.9999999999999993)),
// _Equation(lhs = _Variable("v"), rhs = _Number(2.000000000000001))
// )
// )
// )
With numeric coefficients, consistency is decided against each equation’s own terms at the display precision, so the verdict does not depend on the units the equations are written in. Coefficients whose columns are nearly dependent at that precision are declined first: there the least-squares fit has huge terms that cancel, and a residual the size of a real contradiction would pass as small against them. Exact coefficients holding surds of one radical are eliminated over that radical, so x = √2 beside 2x = √8 is solved, not read as a contradiction. Fewer equations than unknowns, a system that does not determine every unknown, a non-linear one, and a symbolic system with more equations than unknowns all stay unevaluated, each with its reason at the prompt.
Complex numbers
The imaginary unit i is a built-in constant (_Complex(0, 1)). Arithmetic closes over the complex field:
val i = _Complex.of(0, 1)
// i² = -1
Product(i, i).eval(env)
// res17: Either[_Expression, _Value] = Right(_Number(-1.0))
// (2 + 3i)(1 - i) = 5 + i
Product(_Complex.of(2, 3), _Complex.of(1, -1)).eval(env)
// res18: Either[_Expression, _Value] = Right(_Complex(re = 5.0, im = 1.0))
Euler’s identity
// e^(iπ) = -1
Exp(Product(i, _Number(math.Pi))).eval(env)
// res19: Either[_Expression, _Value] = Right(
// _Complex(re = -1.0, im = 1.2246467991473532E-16)
// )
Principal complex roots and logarithms
Negative bases with fractional exponents and logarithms of negative reals return their principal values rather than staying symbolic:
// √(-2) = i√2
Power(_Number(-2.0), _Number(0.5)).eval(env)
// res20: Either[_Expression, _Value] = Right(
// _Complex(re = 8.659560562354932E-17, im = 1.414213562373095)
// )
// ln(-1) = iπ
Ln(_Number(-1.0)).eval(env)
// res21: Either[_Expression, _Value] = Right(
// _Complex(re = 0.0, im = 3.141592653589793)
// )
Parsing complex literals
3i and 2 + 3i parse directly:
Parser.parse("2 + 3i").get.eval(env)
// res22: Either[_Expression, _Value] = Right(_Complex(re = 2.0, im = 3.0))
Parser.parse("(1 + i)^4").get.eval(env)
// res23: Either[_Expression, _Value] = Right(
// _Complex(re = -4.000000000000001, im = 4.898587196589414E-16)
// )