openscad-cpp-evaluator 0.47.0__tar.gz → 0.49.0__tar.gz

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/CLAUDE.md

@@ -460,6 +460,59 @@ grep for `ponytail:`.
   unknown arguments -- `children(separate=true)` renders the wrong shape there with no warning --
   and both read as `undef` in OpenSCAD, so a guard written against them works in both.
 
+- **`linear_solve(A, b)`** (`src/builtins/function_builtins.cpp`, feature name `linear-solve`) —
+  returns `.x` (solution), `.det`, `.singular`. Dispatches on shape:
+
+  | shape | method | `.x` | `.det` |
+  |---|---|---|---|
+  | m = n | pivoted **LU** | the solution | product of U's diagonal, signed by row swaps |
+  | m > n | **Householder QR** | least squares | `undef` |
+  | m < n | **QR of Aᵀ** | minimum norm | `undef` |
+
+  Q is never formed. The reflectors are stored below the diagonal (v[0]
+  normalised to 1, scale in `taus`) and applied in forward order for `Qᵀb`,
+  reverse order for `Qy` — which is why this is far smaller and quicker than
+  BOSL2, whose QR materialises an m×m Q *and* an n×n permutation matrix and
+  then multiplies by it. **Minimum norm** comes from padding `y` with zeros to
+  length n before applying Q; a residual check alone will NOT catch getting
+  that wrong, since any solution passes it — assert the norm.
+  Rank deficiency without column pivoting cannot distinguish rank-deficient
+  from very ill-conditioned. It is a relative-tolerance heuristic on the
+  diagonal; say so rather than implying it is exact.
+
+  **Named to collide, deliberately.** BOSL2 defines `linear_solve()`, and since
+  0.47.0 a user function *shadows* a builtin — so this is unreachable from any
+  script that includes BOSL2 until BOSL2 drops its own. That is the intended
+  path (BelfrySCAD's author maintains BOSL2); callers then gain a `.x`, since
+  BOSL2's returns the bare solution and `[]` for singular. **Do not "fix" the
+  shadowing to make this reachable** — the shadowing is the correct, reference-
+  matching behaviour, and was itself a bug fix.
+
+  Measured per call, BOSL2 load subtracted, enough repetitions to clear noise
+  (harness checked: 200/2000/20000 reps at n=64 give 43/45/43 µs):
+
+  | n | BOSL2 `linear_solve` | ours | | n | BOSL2 `determinant` | ours |
+  |---:|---:|---:|---:|---:|---:|---:|
+  | 4 | 280 µs | 1.5 µs | 187× | 10 | 3.17 s | 0.33 s |
+  | 16 | 2.58 ms | 4.0 µs | 644× | 11 | 31.49 s | 0.33 s |
+  | 64 | 42.5 ms | 43 µs | 988× | | *cofactor expansion, O(n!)* | |
+
+  **Do not repeat the claim this replaces**: that BOSL2's solve "is not the
+  problem (128×128 in ~0.18s)". That was one-shot, with the solve lost inside
+  BOSL2's own load time. Keep the comparison fair though — BOSL2 does QR where
+  the square path here does LU, and it validates arguments every call.
+  Also correctness, not only speed: BOSL2's singularity test is a fixed
+  **absolute** `1e-9` on R's diagonal, unscaled by ‖A‖, so `2*I` scaled by
+  1e-10 is called singular there and solves correctly here.
+
+  **Profiling that shaped the scope** (don't redo it): NURBS *evaluation* is
+  0.6% linear algebra — basis eval 44%, type checks 25%. NURBS *interpolation*
+  is 35% at n=400, and every hot solve is **square**, so the QR paths are a
+  capability, not a measured win. `plane_intersection` (2×3, underdetermined)
+  is 0.1% of a `rounded_prism` model. The recurring cost across every workload
+  profiled is BOSL2's **argument type-checking**: 25–45%, millions of
+  `is_finite`/`is_num`/`is_nan` calls.
+
 - `include/openscad_cpp_evaluator/value.hpp`, `src/value.cpp` — the `Value` variant (OpenSCAD's
   dynamic value type) and its free-function arithmetic/comparison helpers. See the plan's §1 for
   the type-mapping table and why there's no numpy-equivalent library.

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.47.0
+Version: 0.49.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.47.0"
+version = "0.49.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/src/builtins/function_builtins.cpp

@@ -169,6 +169,306 @@ Value builtinCross(const Value& aArg, const Value& bArg) {
     return Value{};
 }
 
+// -- linear_solve(A, b) --------------------------------------------------
+//
+// One pivoted LU answers three questions at once -- the solution, the
+// determinant, and whether A is singular -- because all three fall out of
+// the same factorisation.
+//
+// The motivation is BOSL2's determinant() (linalg.scad), a cofactor
+// expansion: O(n!) time AND O(n!) intermediate list allocation. Measured
+// through this evaluator: 0.04s at n=8, 0.38s at n=9, 2.7s at n=10, and
+// projecting to minutes at n=12. This is O(n^3). BOSL2's linear_solve, by
+// contrast, was already fast (128x128 in ~0.18s after its Apr 2026
+// Householder rewrite), so speed is not the argument for the solve half --
+// a correct singularity test is. See below.
+//
+// Square systems only. BOSL2's linear_solve also handles overdetermined
+// (least-squares) and underdetermined (minimum-norm) systems via QR; LU
+// cannot, and those paths are quick enough in script. A non-square matrix
+// warns rather than silently doing something else.
+
+// Defined further down, next to the other object() helpers.
+Value objectOf(std::vector<std::pair<std::string, Value>> items);
+
+// A rectangular numeric matrix as (row-major values, column count).
+// nullopt for anything that is not a non-empty list of equal-length,
+// non-empty numeric lists.
+std::optional<std::pair<std::vector<double>, size_t>> numericMatrix(const Value& v) {
+    const ListPtr* rows = std::get_if<ListPtr>(&v);
+    if (!rows || !*rows || (*rows)->items.empty()) return std::nullopt;
+    std::vector<double> flat;
+    size_t cols = 0;
+    for (size_t r = 0; r < (*rows)->items.size(); ++r) {
+        const std::optional<std::vector<double>> row = allNumericList((*rows)->items[r]);
+        if (!row || row->empty()) return std::nullopt;
+        if (r == 0) {
+            cols = row->size();
+        } else if (row->size() != cols) {
+            return std::nullopt;
+        }
+        flat.insert(flat.end(), row->begin(), row->end());
+    }
+    return std::make_pair(std::move(flat), cols);
+}
+
+// Householder QR of a tall matrix `a` (m rows, n cols, m >= n), in place.
+//
+// On return the upper triangle of `a` is R. Below the diagonal, column j
+// holds the reflector vector v_j from element 1 onwards -- v_j[0] is
+// normalised to 1 and therefore not stored -- and `taus[j]` is its scale,
+// so H_j = I - tau_j v_j v_j^T. Q is never formed: everything that needs
+// it applies the reflectors instead, which is the whole reason this is
+// smaller and quicker than materialising an m x m matrix.
+//
+// The sign of alpha is chosen away from x[0] so that v[0] can never cancel
+// to zero -- the textbook guard against catastrophic cancellation here.
+//
+// Returns false if a diagonal falls at or below `tol`, i.e. rank-deficient
+// to the tolerance given. Without column pivoting this cannot tell
+// rank-deficient from merely very ill-conditioned; see the caller's note.
+bool householderQr(std::vector<double>& a, size_t m, size_t n, std::vector<double>& taus, double tol) {
+    taus.assign(n, 0.0);
+    for (size_t j = 0; j < n; ++j) {
+        double normx = 0.0;
+        for (size_t r = j; r < m; ++r) normx += a[r * n + j] * a[r * n + j];
+        normx = std::sqrt(normx);
+        if (normx <= tol) return false;
+
+        const double x0 = a[j * n + j];
+        const double alpha = (x0 >= 0.0) ? -normx : normx;
+        const double v0 = x0 - alpha;
+        // Store v scaled so v[0] == 1; the below-diagonal entries are the tail.
+        double vv = 1.0;
+        for (size_t r = j + 1; r < m; ++r) {
+            a[r * n + j] /= v0;
+            vv += a[r * n + j] * a[r * n + j];
+        }
+        taus[j] = 2.0 / vv;
+        a[j * n + j] = alpha;
+
+        // Apply H_j to the trailing columns.
+        for (size_t c = j + 1; c < n; ++c) {
+            double dot = a[j * n + c];
+            for (size_t r = j + 1; r < m; ++r) dot += a[r * n + j] * a[r * n + c];
+            const double f = taus[j] * dot;
+            a[j * n + c] -= f;
+            for (size_t r = j + 1; r < m; ++r) a[r * n + c] -= f * a[r * n + j];
+        }
+    }
+    return true;
+}
+
+// b <- Q^T b, for b with `k` columns. Reflectors applied in forward order.
+void applyQtranspose(const std::vector<double>& a, size_t m, size_t n, const std::vector<double>& taus,
+                      std::vector<double>& b, size_t k) {
+    for (size_t j = 0; j < n; ++j) {
+        for (size_t c = 0; c < k; ++c) {
+            double dot = b[j * k + c];
+            for (size_t r = j + 1; r < m; ++r) dot += a[r * n + j] * b[r * k + c];
+            const double f = taus[j] * dot;
+            b[j * k + c] -= f;
+            for (size_t r = j + 1; r < m; ++r) b[r * k + c] -= f * a[r * n + j];
+        }
+    }
+}
+
+// z <- Q z. Same reflectors, reverse order -- that is the only difference
+// between applying Q and applying Q^T.
+void applyQ(const std::vector<double>& a, size_t m, size_t n, const std::vector<double>& taus,
+             std::vector<double>& z, size_t k) {
+    for (size_t jj = n; jj-- > 0;) {
+        for (size_t c = 0; c < k; ++c) {
+            double dot = z[jj * k + c];
+            for (size_t r = jj + 1; r < m; ++r) dot += a[r * n + jj] * z[r * k + c];
+            const double f = taus[jj] * dot;
+            z[jj * k + c] -= f;
+            for (size_t r = jj + 1; r < m; ++r) z[r * k + c] -= f * a[r * n + jj];
+        }
+    }
+}
+
+Value builtinLinearSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bool haveB,
+                          const oscad::ASTNode& node) {
+    const auto parsed = numericMatrix(aArg);
+    if (!parsed) {
+        ev.warn("linear_solve() requires a matrix of numbers", &node.position());
+        return Value{};
+    }
+    std::vector<double> lu = parsed->first;
+    const size_t n = parsed->second;          // columns == unknowns
+    const size_t m = lu.size() / n;           // rows == equations
+    double maxAbs = 0.0;
+    for (double x : lu) {
+        if (!std::isfinite(x)) {
+            ev.warn("linear_solve() matrix contains a non-finite value", &node.position());
+            return Value{};
+        }
+        maxAbs = std::max(maxAbs, std::abs(x));
+    }
+
+    // Right-hand side: a vector of n is one column; a matrix of n rows is
+    // one column per column. Kept row-major alongside the factorisation.
+    size_t k = 0;
+    bool bWasVector = false;
+    std::vector<double> rhs;
+    if (haveB) {
+        if (const std::optional<std::vector<double>> vec = allNumericList(bArg); vec && vec->size() == m) {
+            bWasVector = true;
+            k = 1;
+            rhs = *vec;
+        } else if (const auto bm = numericMatrix(bArg); bm && bm->first.size() / bm->second == m) {
+            k = bm->second;
+            rhs = bm->first;
+        } else {
+            ev.warn("linear_solve() right-hand side must be a vector of " + std::to_string(m) +
+                        " numbers, or a matrix with that many rows",
+                    &node.position());
+            return Value{};
+        }
+        for (double x : rhs) {
+            if (!std::isfinite(x)) {
+                ev.warn("linear_solve() right-hand side contains a non-finite value", &node.position());
+                return Value{};
+            }
+        }
+    }
+
+    // Relative singularity threshold. BOSL2 compares R's diagonal against a
+    // fixed ABSOLUTE 1e-9 (its _EPSILON) with no scaling by the size of the
+    // matrix, so a perfectly well-conditioned system scaled down by 1e-10
+    // is declared singular there. Scaling by maxAbs is what makes
+    // linear_solve(A*1e-10) still solvable.
+    const double tol =
+        std::numeric_limits<double>::epsilon() * static_cast<double>(std::max(m, n)) * std::max(maxAbs, 1.0);
+
+    // Non-square: QR, and no determinant to report.
+    //
+    // m > n  overdetermined -> least squares. Factor A, apply Q^T to b, then
+    //        back-substitute the leading n x n block of R.
+    // m < n  underdetermined -> minimum norm. Factor A^T instead, forward-solve
+    //        R^T y = b, and return Q [y; 0]. Padding with zeros is what makes
+    //        it the SMALLEST solution rather than just any solution.
+    if (m != n) {
+        std::vector<std::pair<std::string, Value>> outNs;
+        std::vector<double> taus;
+        const auto answer = [&](Value x, bool sing) {
+            outNs.emplace_back("x", std::move(x));
+            outNs.emplace_back("det", Value{});      // undefined for a non-square matrix
+            outNs.emplace_back("singular", Value{sing});
+            return objectOf(std::move(outNs));
+        };
+        const auto shape = [&](const std::vector<double>& v, size_t rows, size_t cols) {
+            if (bWasVector) return numList(v);
+            std::vector<Value> rowsOut;
+            rowsOut.reserve(rows);
+            for (size_t r = 0; r < rows; ++r) {
+                rowsOut.push_back(numList(std::vector<double>(v.begin() + static_cast<long>(r * cols),
+                                                               v.begin() + static_cast<long>((r + 1) * cols))));
+            }
+            return listOf(std::move(rowsOut));
+        };
+
+        if (m > n) {
+            if (!householderQr(lu, m, n, taus, tol)) return answer(Value{}, true);
+            if (!haveB) return answer(Value{}, false);
+            applyQtranspose(lu, m, n, taus, rhs, k);
+            for (size_t row = n; row-- > 0;) {
+                for (size_t c = 0; c < k; ++c) {
+                    double acc = rhs[row * k + c];
+                    for (size_t j = row + 1; j < n; ++j) acc -= lu[row * n + j] * rhs[j * k + c];
+                    rhs[row * k + c] = acc / lu[row * n + row];
+                }
+            }
+            rhs.resize(n * k);
+            return answer(shape(rhs, n, k), false);
+        }
+
+        // m < n: factor the transpose, which is the tall one.
+        std::vector<double> at(n * m);
+        for (size_t r = 0; r < m; ++r)
+            for (size_t c = 0; c < n; ++c) at[c * m + r] = lu[r * n + c];
+        if (!householderQr(at, n, m, taus, tol)) return answer(Value{}, true);
+        if (!haveB) return answer(Value{}, false);
+        // Forward-solve R^T y = b (R is m x m upper, so R^T is lower).
+        for (size_t row = 0; row < m; ++row) {
+            for (size_t c = 0; c < k; ++c) {
+                double acc = rhs[row * k + c];
+                for (size_t j = 0; j < row; ++j) acc -= at[j * m + row] * rhs[j * k + c];
+                rhs[row * k + c] = acc / at[row * m + row];
+            }
+        }
+        std::vector<double> z(n * k, 0.0);
+        for (size_t r = 0; r < m; ++r)
+            for (size_t c = 0; c < k; ++c) z[r * k + c] = rhs[r * k + c];
+        applyQ(at, n, m, taus, z, k);
+        return answer(shape(z, n, k), false);
+    }
+
+    double det = 1.0;
+    bool singular = false;
+    for (size_t col = 0; col < n && !singular; ++col) {
+        size_t pivot = col;
+        for (size_t r = col + 1; r < n; ++r) {
+            if (std::abs(lu[r * n + col]) > std::abs(lu[pivot * n + col])) pivot = r;
+        }
+        if (std::abs(lu[pivot * n + col]) <= tol) {
+            singular = true;
+            break;
+        }
+        if (pivot != col) {
+            for (size_t c = 0; c < n; ++c) std::swap(lu[col * n + c], lu[pivot * n + c]);
+            for (size_t c = 0; c < k; ++c) std::swap(rhs[col * k + c], rhs[pivot * k + c]);
+            det = -det;
+        }
+        const double p = lu[col * n + col];
+        det *= p;
+        for (size_t r = col + 1; r < n; ++r) {
+            const double f = lu[r * n + col] / p;
+            if (f == 0.0) continue;
+            lu[r * n + col] = 0.0;
+            for (size_t c = col + 1; c < n; ++c) lu[r * n + c] -= f * lu[col * n + c];
+            for (size_t c = 0; c < k; ++c) rhs[r * k + c] -= f * rhs[col * k + c];
+        }
+    }
+
+    std::vector<std::pair<std::string, Value>> out;
+    if (singular) {
+        // Not a misuse -- "is this matrix singular?" is a legitimate
+        // question to ask linear_solve, so it answers rather than warning.
+        out.emplace_back("x", Value{});
+        out.emplace_back("det", Value{0.0});
+        out.emplace_back("singular", Value{true});
+        return objectOf(std::move(out));
+    }
+
+    if (haveB) {
+        for (size_t col = n; col-- > 0;) {
+            for (size_t c = 0; c < k; ++c) {
+                double acc = rhs[col * k + c];
+                for (size_t j = col + 1; j < n; ++j) acc -= lu[col * n + j] * rhs[j * k + c];
+                rhs[col * k + c] = acc / lu[col * n + col];
+            }
+        }
+        if (bWasVector) {
+            out.emplace_back("x", numList(rhs));
+        } else {
+            std::vector<Value> rowsOut;
+            rowsOut.reserve(n);
+            for (size_t r = 0; r < n; ++r) {
+                rowsOut.push_back(numList(std::vector<double>(rhs.begin() + static_cast<long>(r * k),
+                                                               rhs.begin() + static_cast<long>((r + 1) * k))));
+            }
+            out.emplace_back("x", listOf(std::move(rowsOut)));
+        }
+    } else {
+        out.emplace_back("x", Value{});
+    }
+    out.emplace_back("det", Value{det});
+    out.emplace_back("singular", Value{false});
+    return objectOf(std::move(out));
+}
+
 Value builtinRands(double minv, double maxv, double nArg, const Value& seedArg) {
     // ponytail: doesn't reproduce Python's Mersenne-Twister bit-for-bit --
     // no script should depend on cross-language RNG equality, only on
@@ -450,6 +750,7 @@ bool isBuiltinFunctionName(const std::string& name) {
         "chr", "ord", "is_undef", "is_num", "is_bool", "is_string", "is_list", "is_function", "is_object",
         "search", "lookup", "has_key", "version", "version_num", "parent_module",
         "object", "textmetrics", "fontmetrics", "dxf_dim", "dxf_cross", "supported_feature",
+        "linear_solve",
     };
     return names.count(name) > 0;
 }
@@ -591,7 +892,7 @@ enum class BuiltinFnId {
     TextMetrics, FontMetrics, Abs, Sign, Ceil, Floor, Round, Sqrt, Ln, Log, Exp, Sin, Cos, Tan,
     Asin, Acos, Atan, Atan2, Max, Min, Pow, Norm, Cross, Rands, Concat, Len, Str, Chr, Ord,
     IsUndef, IsNum, IsBool, IsString, IsList, IsFunction, IsObject, Search, Lookup, HasKey,
-    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature,
+    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature, LinearSolve,
 };
 
 // supported_feature("name") -> the level at which this build implements that
@@ -611,6 +912,7 @@ enum class BuiltinFnId {
 const std::unordered_map<std::string, double>& featureLevels() {
     static const std::unordered_map<std::string, double> levels = {
         {"render-expr", 1.0},        // render() in expression position
+        {"linear-solve", 1.0},       // linear_solve(A, b) -> {x, det, singular}
         {"polyhedron-vnf", 1.0},     // polyhedron(vnf) / polyhedron(object)
         {"separate-children", 1.0},  // children(..., separate=true)
         {"minkowski-diff", 1.0},     // minkowski_difference()
@@ -645,6 +947,7 @@ const std::unordered_map<std::string, BuiltinFnId>& builtinFnIds() {
         {"parent_module", BuiltinFnId::ParentModule},
         {"dxf_dim", BuiltinFnId::DxfDim}, {"dxf_cross", BuiltinFnId::DxfCross},
         {"supported_feature", BuiltinFnId::SupportedFeature},
+        {"linear_solve", BuiltinFnId::LinearSolve},
     };
     return ids;
 }
@@ -726,6 +1029,7 @@ const std::unordered_map<int, BuiltinCheck>& builtinChecks() {
         add(BuiltinFnId::ParentModule, {0, 1, "1", {kNum}});
         add(BuiltinFnId::HasKey, {-1, -1, nullptr, {{TObj, "object"}, {TStr, "string"}}});
         add(BuiltinFnId::SupportedFeature, {1, 1, "1", {}});
+        add(BuiltinFnId::LinearSolve, {1, 2, "1 or 2", {kVec}});
         for (BuiltinFnId id : {BuiltinFnId::IsUndef, BuiltinFnId::IsNum, BuiltinFnId::IsBool,
                                 BuiltinFnId::IsString, BuiltinFnId::IsList, BuiltinFnId::IsFunction,
                                 BuiltinFnId::IsObject}) {
@@ -1040,6 +1344,9 @@ Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs
         // The OpenSCAD release we track. version_num() is that same
         // year/month/day folded as y * 10000 + m * 100 + d, exactly like the
         // reference's own builtin_version_num (builtin_functions.cc).
+        case BuiltinFnId::LinearSolve:
+            return builtinLinearSolve(ev, getArg(args, 0, "A", Value{}), getArg(args, 1, "b", Value{}),
+                                       args.findPositional(1) != nullptr || args.findNamed("b") != nullptr, node);
         case BuiltinFnId::SupportedFeature: {
             const Value name = getArg(args, 0, "feature", Value{});
             const std::string* s = std::get_if<std::string>(&name);

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/tests/test_feature_detection.cpp

@@ -35,7 +35,7 @@ std::vector<std::string> echoesFrom(const std::string& src) {
 // in featureLevels() -- shows up as a 0.
 const char* kFeatures[] = {"separate-children", "minkowski-diff", "sphere-styles",   "export-name",
                             "simplify-op",       "expr-import",    "object-function", "roof-op",
-                            "render-expr",       "polyhedron-vnf"};
+                            "render-expr",       "polyhedron-vnf", "linear-solve"};
 
 } // namespace
 

{openscad_cpp_evaluator-0.47.0 → openscad_cpp_evaluator-0.49.0}/tests/test_function_builtins.cpp

@@ -725,3 +725,161 @@ TEST(StringListBuiltins, ChrIsVariadicAndRangeChecked) {
     EXPECT_EQ(asStr(evalSrc("chr(55296)", ev)), ""); // 0xD800, a surrogate
     EXPECT_EQ(asStr(evalSrc("chr(1114112)", ev)), ""); // 0x110000, one past the top
 }
+
+// -- linear_solve(A, b) --------------------------------------------------
+//
+// One pivoted LU, three answers: x, det, singular. Oracle is BOSL2 plus
+// arithmetic -- OpenSCAD has no equivalent, so there is no reference
+// binary to compare against.
+//
+// Measured against BOSL2 through the CLI, same matrices, identical
+// determinants: n=10  3.17s -> 0.33s, n=11  31.49s -> 0.33s. BOSL2's
+// determinant() is a cofactor expansion, growing x10 per step; this is
+// O(n^3).
+
+TEST(LinearSolve, SolvesASquareSystem) {
+    Evaluator ev;
+    // asList() returns a reference INTO v, so v has to outlive it -- taking
+    // asList(evalSrc(...)) directly dangles the moment the temporary dies.
+    const Value v = evalSrc("linear_solve([[2,1],[1,3]], [5,10]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 1.0, 1e-12);
+    EXPECT_NEAR(asNum(x[1]), 3.0, 1e-12);
+}
+
+TEST(LinearSolve, DeterminantComesFreeFromTheSameFactorisation) {
+    Evaluator ev;
+    EXPECT_NEAR(asNum(evalSrc("linear_solve([[2,1],[1,3]]).det", ev)), 5.0, 1e-12);
+    EXPECT_NEAR(asNum(evalSrc("linear_solve([[1,0,0],[0,1,0],[0,0,1]]).det", ev)), 1.0, 1e-12);
+    // Sign follows the row swaps, not just the magnitude.
+    EXPECT_NEAR(asNum(evalSrc("linear_solve([[0,1],[1,0]]).det", ev)), -1.0, 1e-12);
+}
+
+TEST(LinearSolve, WithNoRightHandSideThereIsNoSolution) {
+    Evaluator ev;
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[2,1],[1,3]]).x", ev)));
+}
+
+TEST(LinearSolve, ASingularMatrixAnswersRatherThanWarning) {
+    // "Is this matrix singular?" is a fair question to ask, so it is
+    // reported, not warned about: det 0, singular true, no solution.
+    Evaluator ev;
+    EXPECT_TRUE(asBool(evalSrc("linear_solve([[1,2],[2,4]], [1,2]).singular", ev)));
+    EXPECT_NEAR(asNum(evalSrc("linear_solve([[1,2],[2,4]], [1,2]).det", ev)), 0.0, 1e-12);
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,2],[2,4]], [1,2]).x", ev)));
+}
+
+TEST(LinearSolve, SingularityIsRelativeToTheMatrixNotAbsolute) {
+    // 2*I scaled by 1e-10 is perfectly conditioned, and BOSL2's
+    // linear_solve calls it singular -- its test is a fixed absolute 1e-9
+    // on R's diagonal with no scaling by the size of the matrix. Verified
+    // through the CLI: BOSL2 says SINGULAR at 1e-10 and 1e-12 where this
+    // solves correctly.
+    Evaluator ev;
+    EXPECT_FALSE(asBool(evalSrc("linear_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).singular", ev)));
+    const Value v = evalSrc("linear_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 0.5, 1e-9);
+}
+
+TEST(LinearSolve, AMatrixRightHandSideSolvesEveryColumn) {
+    Evaluator ev;
+    // Solving against the identity is the inverse; [[2,1],[1,3]] has
+    // det 5, so the inverse is [[0.6,-0.2],[-0.2,0.4]].
+    const Value v = evalSrc("linear_solve([[2,1],[1,3]], [[1,0],[0,1]]).x", ev);
+    const std::vector<Value>& rows = asList(v);
+    ASSERT_EQ(rows.size(), 2u);
+    const std::vector<Value>& r0 = asList(rows[0]);
+    ASSERT_EQ(r0.size(), 2u);
+    EXPECT_NEAR(asNum(r0[0]), 0.6, 1e-12);
+    EXPECT_NEAR(asNum(r0[1]), -0.2, 1e-12);
+}
+
+TEST(LinearSolve, RejectsWhatItCannotFactor) {
+    Evaluator ev;
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,2],[3,\"x\"]], [1,2])", ev)));   // not numeric
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,2],[3,4]], [1,2,3])", ev)));     // wrong rhs length
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,2],[3,4,5]], [1,2])", ev)));     // ragged
+}
+
+// -- non-square: QR ------------------------------------------------------
+//
+// m > n is least squares, m < n is minimum norm -- the same two answers
+// BOSL2's linear_solve gives, and cross-checked against it.
+
+TEST(LinearSolve, OverdeterminedGivesTheLeastSquaresFit) {
+    // Fit y = a + b*x to (0,1) (1,3) (2,5) (3,7): exactly on the line
+    // y = 1 + 2x, so the residual is zero and a=1, b=2.
+    Evaluator ev;
+    const Value v = evalSrc("linear_solve([[1,0],[1,1],[1,2],[1,3]], [1,3,5,7]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 1.0, 1e-10);
+    EXPECT_NEAR(asNum(x[1]), 2.0, 1e-10);
+}
+
+TEST(LinearSolve, OverdeterminedWithNoExactSolutionMinimisesTheResidual) {
+    // (0,0) (1,1) (2,2) (3,10): no line fits. The normal equations put the
+    // least-squares line at y = -1.4 + 3.1x -- computed independently, not
+    // read off this implementation.
+    Evaluator ev;
+    const Value v = evalSrc("linear_solve([[1,0],[1,1],[1,2],[1,3]], [0,1,2,10]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), -1.4, 1e-9);
+    EXPECT_NEAR(asNum(x[1]), 3.1, 1e-9);
+}
+
+TEST(LinearSolve, UnderdeterminedGivesTheMinimUmNormSolution) {
+    // x + y = 2 has infinitely many solutions; the smallest is [1,1].
+    // Anything satisfying the equation passes a residual check, so this
+    // asserts the NORM -- that is the whole claim of a minimum-norm solve.
+    Evaluator ev;
+    const Value v = evalSrc("linear_solve([[1,1]], [2]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 1.0, 1e-12);
+    EXPECT_NEAR(asNum(x[1]), 1.0, 1e-12);
+}
+
+TEST(LinearSolve, UnderdeterminedSatisfiesEveryEquation) {
+    // 2 x 3: the plane_intersection shape BOSL2 relies on.
+    Evaluator ev;
+    const Value v = evalSrc("linear_solve([[1,0,1],[0,1,1]], [3,5]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 3u);
+    const double a = asNum(x[0]), b = asNum(x[1]), c = asNum(x[2]);
+    EXPECT_NEAR(a + c, 3.0, 1e-12);
+    EXPECT_NEAR(b + c, 5.0, 1e-12);
+    // minimum norm: the component along the null direction [1,1,-1] is zero
+    EXPECT_NEAR(a + b - c, 0.0, 1e-9);
+}
+
+TEST(LinearSolve, NonSquareHasNoDeterminant) {
+    Evaluator ev;
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,0],[1,1],[1,2]], [1,2,3]).det", ev)));
+    EXPECT_FALSE(asBool(evalSrc("linear_solve([[1,0],[1,1],[1,2]], [1,2,3]).singular", ev)));
+}
+
+TEST(LinearSolve, RankDeficientNonSquareIsReportedNotWrong) {
+    // Two identical columns: rank 1, not 2.
+    Evaluator ev;
+    EXPECT_TRUE(asBool(evalSrc("linear_solve([[1,1],[2,2],[3,3]], [1,2,3]).singular", ev)));
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[1,1],[2,2],[3,3]], [1,2,3]).x", ev)));
+}
+
+
+TEST(LinearSolve, WorksUnderBothEngines) {
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e =
+            echoesOf("r = linear_solve([[2,1],[1,3]], [5,10]);\necho(r.x, r.det, r.singular);");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm;
+        EXPECT_NE(e[0].find("[1, 3]"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+        EXPECT_NE(e[0].find("5"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+        EXPECT_NE(e[0].find("false"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+    }
+}
+