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

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

@@ -460,19 +460,58 @@ 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.
 
-- **`matrix_solve(A, b)`** (`src/builtins/function_builtins.cpp`, feature name `matrix-solve`) —
-  one pivoted LU answering three questions from the same factorisation: `.x` (solution; a vector
-  for a vector `b`, a matrix for a matrix `b`, `undef` when `b` is omitted), `.det`, `.singular`.
-  Square systems only — BOSL2's `linear_solve` also does least-squares/minimum-norm via QR, which
-  LU cannot, and those paths are already fast in script. A non-square or non-numeric matrix warns
-  and returns `undef`; a **singular** one is reported (`singular=true`, `det=0`, `x=undef`), not
-  warned about, because asking whether a matrix is singular is a fair question.
-  Why it exists: BOSL2's `determinant()` is a cofactor expansion, O(n!) in time *and* in
-  intermediate list allocation. Measured through the CLI on identical matrices, with identical
-  results: **n=10 3.17s → 0.33s, n=11 31.49s → 0.33s**. Its `linear_solve` is not the problem
-  (128×128 in ~0.18s since its Apr 2026 Householder rewrite) — but its singularity test is a fixed
-  **absolute** `1e-9` on R's diagonal with no scaling by ‖A‖, so `2*I` scaled by 1e-10 is declared
-  singular there and solves correctly here. This one uses a relative threshold.
+- **`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

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

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

{openscad_cpp_evaluator-0.48.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.48.0"
+version = "0.49.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -169,7 +169,7 @@ Value builtinCross(const Value& aArg, const Value& bArg) {
     return Value{};
 }
 
-// -- matrix_solve(A, b) --------------------------------------------------
+// -- 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
@@ -212,26 +212,96 @@ std::optional<std::pair<std::vector<double>, size_t>> numericMatrix(const Value&
     return std::make_pair(std::move(flat), cols);
 }
 
-Value builtinMatrixSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bool haveB,
+// 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("matrix_solve() requires a matrix of numbers", &node.position());
+        ev.warn("linear_solve() requires a matrix of numbers", &node.position());
         return Value{};
     }
     std::vector<double> lu = parsed->first;
-    const size_t cols = parsed->second;
-    const size_t n = lu.size() / cols;
-    if (n != cols) {
-        ev.warn("matrix_solve() requires a square matrix, found " + std::to_string(n) + " x " +
-                    std::to_string(cols),
-                &node.position());
-        return Value{};
-    }
+    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("matrix_solve() matrix contains a non-finite value", &node.position());
+            ev.warn("linear_solve() matrix contains a non-finite value", &node.position());
             return Value{};
         }
         maxAbs = std::max(maxAbs, std::abs(x));
@@ -243,22 +313,22 @@ Value builtinMatrixSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bo
     bool bWasVector = false;
     std::vector<double> rhs;
     if (haveB) {
-        if (const std::optional<std::vector<double>> vec = allNumericList(bArg); vec && vec->size() == n) {
+        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 == n) {
+        } else if (const auto bm = numericMatrix(bArg); bm && bm->first.size() / bm->second == m) {
             k = bm->second;
             rhs = bm->first;
         } else {
-            ev.warn("matrix_solve() right-hand side must be a vector of " + std::to_string(n) +
+            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("matrix_solve() right-hand side contains a non-finite value", &node.position());
+                ev.warn("linear_solve() right-hand side contains a non-finite value", &node.position());
                 return Value{};
             }
         }
@@ -268,8 +338,72 @@ Value builtinMatrixSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bo
     // 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
-    // matrix_solve(A*1e-10) still solvable.
-    const double tol = std::numeric_limits<double>::epsilon() * static_cast<double>(n) * std::max(maxAbs, 1.0);
+    // 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;
@@ -301,7 +435,7 @@ Value builtinMatrixSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bo
     std::vector<std::pair<std::string, Value>> out;
     if (singular) {
         // Not a misuse -- "is this matrix singular?" is a legitimate
-        // question to ask matrix_solve, so it answers rather than warning.
+        // 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});
@@ -616,7 +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",
-        "matrix_solve",
+        "linear_solve",
     };
     return names.count(name) > 0;
 }
@@ -758,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, MatrixSolve,
+    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature, LinearSolve,
 };
 
 // supported_feature("name") -> the level at which this build implements that
@@ -778,7 +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
-        {"matrix-solve", 1.0},       // matrix_solve(A, b) -> {x, det, singular}
+        {"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()
@@ -813,7 +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},
-        {"matrix_solve", BuiltinFnId::MatrixSolve},
+        {"linear_solve", BuiltinFnId::LinearSolve},
     };
     return ids;
 }
@@ -895,7 +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::MatrixSolve, {1, 2, "1 or 2", {kVec}});
+        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}) {
@@ -1210,8 +1344,8 @@ 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::MatrixSolve:
-            return builtinMatrixSolve(ev, getArg(args, 0, "A", Value{}), getArg(args, 1, "b", Value{}),
+        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{});

{openscad_cpp_evaluator-0.48.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", "matrix-solve"};
+                            "render-expr",       "polyhedron-vnf", "linear-solve"};
 
 } // namespace
 

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

@@ -726,7 +726,7 @@ TEST(StringListBuiltins, ChrIsVariadicAndRangeChecked) {
     EXPECT_EQ(asStr(evalSrc("chr(1114112)", ev)), ""); // 0x110000, one past the top
 }
 
-// -- matrix_solve(A, b) --------------------------------------------------
+// -- 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
@@ -737,58 +737,58 @@ TEST(StringListBuiltins, ChrIsVariadicAndRangeChecked) {
 // determinant() is a cofactor expansion, growing x10 per step; this is
 // O(n^3).
 
-TEST(MatrixSolve, SolvesASquareSystem) {
+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("matrix_solve([[2,1],[1,3]], [5,10]).x", ev);
+    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(MatrixSolve, DeterminantComesFreeFromTheSameFactorisation) {
+TEST(LinearSolve, DeterminantComesFreeFromTheSameFactorisation) {
     Evaluator ev;
-    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[2,1],[1,3]]).det", ev)), 5.0, 1e-12);
-    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[1,0,0],[0,1,0],[0,0,1]]).det", ev)), 1.0, 1e-12);
+    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("matrix_solve([[0,1],[1,0]]).det", ev)), -1.0, 1e-12);
+    EXPECT_NEAR(asNum(evalSrc("linear_solve([[0,1],[1,0]]).det", ev)), -1.0, 1e-12);
 }
 
-TEST(MatrixSolve, WithNoRightHandSideThereIsNoSolution) {
+TEST(LinearSolve, WithNoRightHandSideThereIsNoSolution) {
     Evaluator ev;
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[2,1],[1,3]]).x", ev)));
+    EXPECT_TRUE(isUndef(evalSrc("linear_solve([[2,1],[1,3]]).x", ev)));
 }
 
-TEST(MatrixSolve, ASingularMatrixAnswersRatherThanWarning) {
+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("matrix_solve([[1,2],[2,4]], [1,2]).singular", ev)));
-    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[1,2],[2,4]], [1,2]).det", ev)), 0.0, 1e-12);
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[2,4]], [1,2]).x", 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(MatrixSolve, SingularityIsRelativeToTheMatrixNotAbsolute) {
+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("matrix_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).singular", ev)));
-    const Value v = evalSrc("matrix_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).x", 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(MatrixSolve, AMatrixRightHandSideSolvesEveryColumn) {
+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("matrix_solve([[2,1],[1,3]], [[1,0],[0,1]]).x", ev);
+    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]);
@@ -797,26 +797,85 @@ TEST(MatrixSolve, AMatrixRightHandSideSolvesEveryColumn) {
     EXPECT_NEAR(asNum(r0[1]), -0.2, 1e-12);
 }
 
-TEST(MatrixSolve, RejectsWhatItCannotFactor) {
+TEST(LinearSolve, RejectsWhatItCannotFactor) {
     Evaluator ev;
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2,3],[4,5,6]], [1,2])", ev)));   // not square
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,\"x\"]], [1,2])", ev)));   // not numeric
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,4]], [1,2,3])", ev)));     // wrong rhs length
-    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,4,5]], [1,2])", ev)));     // ragged
+    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
 }
 
-TEST(MatrixSolve, NonSquareWarnsWithItsShape) {
-    const std::vector<std::string> w = builtinWarnings("matrix_solve([[1,2,3],[4,5,6]], [1,2])");
-    ASSERT_EQ(w.size(), 1u);
-    EXPECT_NE(w[0].find("matrix_solve() requires a square matrix, found 2 x 3"), std::string::npos)
-        << "got " << w[0];
+// -- 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(MatrixSolve, WorksUnderBothEngines) {
+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 = matrix_solve([[2,1],[1,3]], [5,10]);\necho(r.x, r.det, r.singular);");
+            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];