FastLSQ 0.2.4__tar.gz → 0.2.6__tar.gz

{fastlsq-0.2.4 → fastlsq-0.2.6}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to FastLSQ will be documented in this file.
 
+## [0.2.5] - 2026-06-04
+
+### Fixed
+
+- **`Wave2D_MS` solves via `solve_linear`.** The long-time anisotropic wave
+  returned relative value error 1.0 in every configuration because its
+  `t_max = 100` time normalisation packed ~87 temporal cycles into `tau ∈ [0,1]`:
+  the PDE's second time-derivative amplifies the random-feature *representation*
+  error by `Omega²` (`Omega = pi·sqrt(1+a2)·t_max`), so the one-shot
+  least-squares collocation cannot resolve the oscillation -- even 8000 features
+  with near-hard boundary constraints stay at rel-err 1.0, because the best
+  representable solution itself carries a huge PDE residual. Reducing `t_max` to
+  `4` (~3.5 cycles) and matching the anisotropic temporal feature bandwidth to
+  `Omega` (`scale_multipliers = [1, 1, 7]`) recovers the solution to ~3e-4 at
+  900 features (`scale = 3`); the exactly-consistent `t_max²`-scaled operator is
+  unchanged. Added to the `tests/test_benchmarks_inverse.py` linear smoke test.
+  Resolves the `Wave2D_MS` [0.2.4] known issue.
+- **`ElasticWave2D` solves via the block-stacked vector path.** The coupled
+  2-output elastic-wave problem now declares `n_outputs = 2`, assembles its
+  operator in block-stacked form (`A ∈ ℝ^{Mk×Nk}`, `b ∈ ℝ^{Mk×1}`) via
+  `block_concat`, and gains the `exact_grad` Jacobian (shape `(M, d, k)`, time
+  axis chain-ruled by `t_max`) that the error metric requires. `unpack_beta` now
+  recovers a `(N, 2)` `beta`, so `solve_linear(ElasticWave2D(), scale=5.0)`
+  recovers both components (relative value error ~7e-3 at the default
+  resolution) instead of failing to unpack the vector solution. Added to the
+  `tests/test_benchmarks_inverse.py` linear smoke test. Resolves the
+  `ElasticWave2D` [0.2.4] known issue; the `t_max²` operator scaling from
+  [0.2.2] (consistent with `Wave2D_MS`) is preserved.
+
 ## [0.2.4] - 2026-06-04
 
 ### Added
@@ -18,10 +47,14 @@ All notable changes to FastLSQ will be documented in this file.
 ### Known issues
 
 - `Wave2D_MS` does not solve via `solve_linear` (relative error 1.0 in every
-  configuration tested), and `ElasticWave2D` -- a 2-output vector problem whose
-  `exact()` returns `(N, 2)` -- never sets `n_outputs`, so the scalar API cannot
-  unpack it. Both are pre-existing problem-definition gaps, independent of the
-  solver work, and are excluded from the new smoke test pending a fix.
+  configuration tested) -- a pre-existing problem-definition gap, independent of
+  the solver work, excluded from the new smoke test pending a fix. *(Fixed in
+  [0.2.5]: `t_max` reduced 100 -> 4 so the normalised-time oscillation
+  (~3.5 vs ~87 cycles) is resolvable; now covered by the smoke test.)*
+- `ElasticWave2D` -- a 2-output vector problem whose `exact()` returns `(N, 2)`
+  -- never sets `n_outputs`, so the scalar API cannot unpack it; also excluded
+  here. *(Fixed in [0.2.5]: it now uses the block-stacked vector path and
+  is covered by the smoke test.)*
 
 ## [0.2.3] - 2026-06-04
 

{fastlsq-0.2.4 → fastlsq-0.2.6}/FastLSQ.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.2.4
+Version: 0.2.6
 Summary: One-shot PDE solving via Fourier features with exact analytical derivatives; rank-revealing solvers, learnable anisotropic bandwidth, and CPU/CUDA/MPS support
 Author: Antonin Sulc
 License-Expression: MIT
@@ -55,9 +55,12 @@ analytical derivative engine for random Fourier features.  For sinusoidal
 features `phi_j(x) = sin(W_j . x + b_j)`, every derivative of every order
 admits an exact closed-form expression -- no automatic differentiation needed.
 
-Linear PDEs are solved in a single least-squares step; nonlinear PDEs are
-solved via Newton-Raphson iteration with Tikhonov regularisation,
-1/sqrt(N) feature normalisation, and continuation/homotopy.
+Linear PDEs are solved in a single least-squares step.  The random-feature
+system is typically rank-deficient, so the solve is routed through a
+backward-stable, auto-selected least-squares back-end (Cholesky fast-path ->
+Householder QR -> rank-revealing SVD) that runs on CPU, CUDA, or Apple-MPS.
+Nonlinear PDEs are solved via Newton-Raphson iteration with Tikhonov
+regularisation, 1/sqrt(N) feature normalisation, and continuation/homotopy.
 
 ## Installation
 
@@ -68,7 +71,7 @@ pip install fastlsq
 For development (includes testing and build tools):
 
 ```bash
-git clone https://github.com/asulc/FastLSQ.git
+git clone https://github.com/sulcantonin/FastLSQ.git
 cd FastLSQ
 pip install -e ".[dev]"
 ```
@@ -101,6 +104,26 @@ print(f"Converged in {result['n_iters']} iterations")
 print(f"Value error: {result['metrics']['val_err']:.2e}")
 ```
 
+### Choose a solver back-end and device
+
+The linear solve is routed automatically, but `solve_linear` exposes the
+back-end via `method=` (see [How it works](#how-it-works) for the routing):
+
+```python
+from fastlsq import solve_linear, set_device
+from fastlsq.problems.linear import PoissonND
+
+# "auto" (default) -- Cholesky fast-path -> QR -> rank-revealing SVD
+# "qr"             -- Householder QR; SVD-grade accuracy at QR cost (full-rank A)
+# "svd"            -- rank-revealing truncated SVD; the rank-deficient-safe reference
+# "cholesky"       -- normal-equations Cholesky; fast, well-conditioned A only
+# "rsvd"           -- randomized SVD, O(MNk), for strongly low-rank A
+result = solve_linear(PoissonND(), scale=5.0, method="qr")
+
+# Device selection (CPU / CUDA / Apple-MPS), or set FASTLSQ_DEVICE=cuda
+set_device("cuda")   # the float64 default stays on CPU/CUDA; MPS is float32-only
+```
+
 ### Use the basis directly
 
 ```python
@@ -204,9 +227,10 @@ u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per com
 
 Scalar problems are untouched: `n_outputs` defaults to `1`, `solver.beta` keeps
 shape `(N, 1)`, and `predict_with_grad` returns gradient shape `(M, d)` for
-backward compatibility (the trailing component axis is squeezed when k=1).
-`ElasticWave2D` in [fastlsq/problems/linear.py](fastlsq/problems/linear.py) is
-the canonical coupled vector example.
+backward compatibility (the trailing component axis is squeezed when k=1). The
+`Stokes2D` sketch above and [tests/test_block.py](tests/test_block.py) -- a
+runnable `block_concat` + `unpack_beta` solve that recovers both components of a
+k=2 system -- are the reference for the block-stacked vector path.
 
 ### Plot solutions
 
@@ -258,11 +282,15 @@ derivative engine:
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |
 | `LearnableFastLSQ` | Differentiable solver with learnable bandwidth via reparameterisation trick |
 | `block_concat`, `pack_beta`, `unpack_beta` | Block-structured assembly helpers for vector-valued **u** (coupled systems). `solver.beta` has shape `(N, k)`; scalar problems are the k=1 case |
+| `solve_lstsq` | Multi-back-end least-squares solve (`auto`/`qr`/`svd`/`cholesky`/`rsvd`); rank-revealing by default for the rank-deficient feature matrix |
+| `resolve_device` / `set_device` / `get_device` | CPU / CUDA / Apple-MPS selection, dtype-aware (MPS is float32-only; factorizations fall back to CPU) |
 
 ### How it works
 
 1. **Basis construction.** Given collocation points **x**, construct a
-   `SinusoidalBasis` with random weights W and biases b.
+   `SinusoidalBasis` with random weights W and biases b. The collocation counts
+   default to scale with the feature count
+   (`n_pde = max(3000, 3 * n_blocks * hidden_size)`, `n_bc = max(800, n_pde // 5)`).
 
 2. **Analytical derivatives.** Exploit the cyclic derivative identity:
    the n-th derivative of sin(z) cycles through {sin, cos, -sin, -cos}
@@ -273,8 +301,13 @@ derivative engine:
    (e.g. `Op.laplacian(d=2)`) and apply it to the basis to get the system
    matrix `A`.
 
-4. **Linear solve.** Solve `A beta = b` via least squares
-   (optionally Tikhonov-regularised).
+4. **Linear solve.** Solve `A beta = b` in the least-squares sense. The
+   random-feature matrix `A` is typically rank-deficient (near-duplicate
+   columns), so the default `method="auto"` starts from a Cholesky fast-path
+   (guarded by a cheap conditioning probe), falls back to backward-stable
+   Householder **QR**, and resorts to a rank-revealing **SVD** only if the QR
+   solution blows up. A Tikhonov ridge `mu` enters via the `[A; sqrt(mu) I]`
+   augmentation, not the condition-squaring normal equations.
 
 5. **Newton iteration (nonlinear).** Linearise the PDE residual, solve
    `J delta_beta = -R` with backtracking line search, and repeat.
@@ -336,9 +369,12 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 - **Symbolic PDE operators**: Compose differential operators with `Op` (Laplacian, wave, Helmholtz, biharmonic, custom) via intuitive arithmetic; coefficients can be `nn.Parameter` for AdamW optimisation
 - **Vector-valued solutions**: First-class support for **u**: ℝᵈ → ℝᵏ (elasticity, Stokes, Maxwell). Problems declare `n_outputs = k`; `block_concat` assembles coupled block systems; `solver.predict(x)` returns shape `(M, k)`. Scalar problems are the `k=1` case
 - **High-level API**: Solve PDEs in one line with `solve_linear()` and `solve_nonlinear()`
+- **Robust linear solver**: Pluggable least-squares back-ends; the default `auto` routes Cholesky -> QR -> SVD, and backward-stable QR delivers SVD-grade accuracy at QR cost on the rank-deficient random-feature system
 - **Learnable bandwidth**: `LearnableFastLSQ` optimises the bandwidth (scalar or anisotropic) via reparameterisation
 - **Learnable PDE coefficients**: Plug `nn.Parameter` into `Op` (e.g. Helmholtz wavenumber `k`) and optimise via AdamW; gradients flow through the prebuilt linear solve
 - **Auto-tuning**: Automatic scale selection via grid search
+- **Device support**: CPU / CUDA / Apple-MPS via `set_device()` or the `FASTLSQ_DEVICE` env var, dtype-aware (the float64 high-accuracy path stays on CPU/CUDA)
+- **Adaptive collocation**: `n_pde` / `n_bc` default to feature-count-scaled values, overridable per solve
 - **Built-in plotting**: Solution visualization, convergence plots, spectral sensitivity
 - **Geometry samplers**: Box, ball, sphere, interval, custom samplers
 - **Diagnostics**: Problem validation, conditioning checks, error detection

{fastlsq-0.2.4 → fastlsq-0.2.6}/FastLSQ.egg-info/SOURCES.txt

@@ -32,6 +32,17 @@ examples/run_nonlinear.py
 examples/tutorial_basic.py
 examples/tutorial_nonlinear.py
 examples/vector_basis_stream_vorticity.py
+examples/digital_twins/darcy_heat.py
+examples/digital_twins/pendulum.py
+examples/digital_twins/pendulum_benchmark.py
+examples/digital_twins/plasma_wakefield.py
+examples/digital_twins/plasma_wakefield_2D_1.py
+examples/digital_twins/plasma_wakefield_2D_2.py
+examples/digital_twins/plasma_wakefield_2d_3.py
+examples/digital_twins/plasma_wakefield_parameteric.py
+examples/digital_twins/plot_utils.py
+examples/digital_twins/structural_health_simple.py
+examples/digital_twins/turbulence_gravity_cooling.py
 examples/extras/fred_sde.py
 examples/extras/fred_sde_fastlsq.py
 examples/extras/gaia_potential.py
@@ -73,6 +84,18 @@ examples/extras/scenarios/s12_mems_resonator.py
 examples/extras/scenarios/s13_variable_stars_kepler.py
 examples/extras/scenarios/s14_eeg.py
 examples/extras/scenarios/s15_circadian.py
+examples/inverse/aero_.py
+examples/inverse/denoising_parameter_estimation.py
+examples/inverse/elastic_wave_animation.py
+examples/inverse/heat_from_video.py
+examples/inverse/inverse_turbulence.py
+examples/inverse/shape_ns.py
+examples/inverse/subsurface_imaging.py
+examples/inverse/wing_optimize_simple.py
+examples/sindy/compare_sindy_methods.py
+examples/sindy/sindy_benchmarks.py
+examples/sindy/sindy_differentiable.py
+examples/sindy/sindy_minimal_diff.py
 fastlsq/__init__.py
 fastlsq/api.py
 fastlsq/basis.py
@@ -95,6 +118,16 @@ fastlsq/problems/__init__.py
 fastlsq/problems/linear.py
 fastlsq/problems/nonlinear.py
 fastlsq/problems/regression.py
+misc/fastlsq_teaser.png
+misc/ideal_quadrupole.png
+misc/inverse_heat_source.gif
+misc/inverse_heat_source.png
+misc/inverse_magnetostatics.png
+misc/inverse_magnetostatics_convergence.png
+misc/quadrupole_convergence.png
+misc/quadrupole_optimization.png
+misc/tutorial_nlpoisson_convergence.png
+misc/tutorial_nlpoisson_solution.png
 tests/test_basic.py
 tests/test_benchmarks_inverse.py
 tests/test_block.py

{fastlsq-0.2.4 → fastlsq-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.2.4
+Version: 0.2.6
 Summary: One-shot PDE solving via Fourier features with exact analytical derivatives; rank-revealing solvers, learnable anisotropic bandwidth, and CPU/CUDA/MPS support
 Author: Antonin Sulc
 License-Expression: MIT
@@ -55,9 +55,12 @@ analytical derivative engine for random Fourier features.  For sinusoidal
 features `phi_j(x) = sin(W_j . x + b_j)`, every derivative of every order
 admits an exact closed-form expression -- no automatic differentiation needed.
 
-Linear PDEs are solved in a single least-squares step; nonlinear PDEs are
-solved via Newton-Raphson iteration with Tikhonov regularisation,
-1/sqrt(N) feature normalisation, and continuation/homotopy.
+Linear PDEs are solved in a single least-squares step.  The random-feature
+system is typically rank-deficient, so the solve is routed through a
+backward-stable, auto-selected least-squares back-end (Cholesky fast-path ->
+Householder QR -> rank-revealing SVD) that runs on CPU, CUDA, or Apple-MPS.
+Nonlinear PDEs are solved via Newton-Raphson iteration with Tikhonov
+regularisation, 1/sqrt(N) feature normalisation, and continuation/homotopy.
 
 ## Installation
 
@@ -68,7 +71,7 @@ pip install fastlsq
 For development (includes testing and build tools):
 
 ```bash
-git clone https://github.com/asulc/FastLSQ.git
+git clone https://github.com/sulcantonin/FastLSQ.git
 cd FastLSQ
 pip install -e ".[dev]"
 ```
@@ -101,6 +104,26 @@ print(f"Converged in {result['n_iters']} iterations")
 print(f"Value error: {result['metrics']['val_err']:.2e}")
 ```
 
+### Choose a solver back-end and device
+
+The linear solve is routed automatically, but `solve_linear` exposes the
+back-end via `method=` (see [How it works](#how-it-works) for the routing):
+
+```python
+from fastlsq import solve_linear, set_device
+from fastlsq.problems.linear import PoissonND
+
+# "auto" (default) -- Cholesky fast-path -> QR -> rank-revealing SVD
+# "qr"             -- Householder QR; SVD-grade accuracy at QR cost (full-rank A)
+# "svd"            -- rank-revealing truncated SVD; the rank-deficient-safe reference
+# "cholesky"       -- normal-equations Cholesky; fast, well-conditioned A only
+# "rsvd"           -- randomized SVD, O(MNk), for strongly low-rank A
+result = solve_linear(PoissonND(), scale=5.0, method="qr")
+
+# Device selection (CPU / CUDA / Apple-MPS), or set FASTLSQ_DEVICE=cuda
+set_device("cuda")   # the float64 default stays on CPU/CUDA; MPS is float32-only
+```
+
 ### Use the basis directly
 
 ```python
@@ -204,9 +227,10 @@ u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per com
 
 Scalar problems are untouched: `n_outputs` defaults to `1`, `solver.beta` keeps
 shape `(N, 1)`, and `predict_with_grad` returns gradient shape `(M, d)` for
-backward compatibility (the trailing component axis is squeezed when k=1).
-`ElasticWave2D` in [fastlsq/problems/linear.py](fastlsq/problems/linear.py) is
-the canonical coupled vector example.
+backward compatibility (the trailing component axis is squeezed when k=1). The
+`Stokes2D` sketch above and [tests/test_block.py](tests/test_block.py) -- a
+runnable `block_concat` + `unpack_beta` solve that recovers both components of a
+k=2 system -- are the reference for the block-stacked vector path.
 
 ### Plot solutions
 
@@ -258,11 +282,15 @@ derivative engine:
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |
 | `LearnableFastLSQ` | Differentiable solver with learnable bandwidth via reparameterisation trick |
 | `block_concat`, `pack_beta`, `unpack_beta` | Block-structured assembly helpers for vector-valued **u** (coupled systems). `solver.beta` has shape `(N, k)`; scalar problems are the k=1 case |
+| `solve_lstsq` | Multi-back-end least-squares solve (`auto`/`qr`/`svd`/`cholesky`/`rsvd`); rank-revealing by default for the rank-deficient feature matrix |
+| `resolve_device` / `set_device` / `get_device` | CPU / CUDA / Apple-MPS selection, dtype-aware (MPS is float32-only; factorizations fall back to CPU) |
 
 ### How it works
 
 1. **Basis construction.** Given collocation points **x**, construct a
-   `SinusoidalBasis` with random weights W and biases b.
+   `SinusoidalBasis` with random weights W and biases b. The collocation counts
+   default to scale with the feature count
+   (`n_pde = max(3000, 3 * n_blocks * hidden_size)`, `n_bc = max(800, n_pde // 5)`).
 
 2. **Analytical derivatives.** Exploit the cyclic derivative identity:
    the n-th derivative of sin(z) cycles through {sin, cos, -sin, -cos}
@@ -273,8 +301,13 @@ derivative engine:
    (e.g. `Op.laplacian(d=2)`) and apply it to the basis to get the system
    matrix `A`.
 
-4. **Linear solve.** Solve `A beta = b` via least squares
-   (optionally Tikhonov-regularised).
+4. **Linear solve.** Solve `A beta = b` in the least-squares sense. The
+   random-feature matrix `A` is typically rank-deficient (near-duplicate
+   columns), so the default `method="auto"` starts from a Cholesky fast-path
+   (guarded by a cheap conditioning probe), falls back to backward-stable
+   Householder **QR**, and resorts to a rank-revealing **SVD** only if the QR
+   solution blows up. A Tikhonov ridge `mu` enters via the `[A; sqrt(mu) I]`
+   augmentation, not the condition-squaring normal equations.
 
 5. **Newton iteration (nonlinear).** Linearise the PDE residual, solve
    `J delta_beta = -R` with backtracking line search, and repeat.
@@ -336,9 +369,12 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 - **Symbolic PDE operators**: Compose differential operators with `Op` (Laplacian, wave, Helmholtz, biharmonic, custom) via intuitive arithmetic; coefficients can be `nn.Parameter` for AdamW optimisation
 - **Vector-valued solutions**: First-class support for **u**: ℝᵈ → ℝᵏ (elasticity, Stokes, Maxwell). Problems declare `n_outputs = k`; `block_concat` assembles coupled block systems; `solver.predict(x)` returns shape `(M, k)`. Scalar problems are the `k=1` case
 - **High-level API**: Solve PDEs in one line with `solve_linear()` and `solve_nonlinear()`
+- **Robust linear solver**: Pluggable least-squares back-ends; the default `auto` routes Cholesky -> QR -> SVD, and backward-stable QR delivers SVD-grade accuracy at QR cost on the rank-deficient random-feature system
 - **Learnable bandwidth**: `LearnableFastLSQ` optimises the bandwidth (scalar or anisotropic) via reparameterisation
 - **Learnable PDE coefficients**: Plug `nn.Parameter` into `Op` (e.g. Helmholtz wavenumber `k`) and optimise via AdamW; gradients flow through the prebuilt linear solve
 - **Auto-tuning**: Automatic scale selection via grid search
+- **Device support**: CPU / CUDA / Apple-MPS via `set_device()` or the `FASTLSQ_DEVICE` env var, dtype-aware (the float64 high-accuracy path stays on CPU/CUDA)
+- **Adaptive collocation**: `n_pde` / `n_bc` default to feature-count-scaled values, overridable per solve
 - **Built-in plotting**: Solution visualization, convergence plots, spectral sensitivity
 - **Geometry samplers**: Box, ball, sphere, interval, custom samplers
 - **Diagnostics**: Problem validation, conditioning checks, error detection

{fastlsq-0.2.4 → fastlsq-0.2.6}/README.md

@@ -14,9 +14,12 @@ analytical derivative engine for random Fourier features.  For sinusoidal
 features `phi_j(x) = sin(W_j . x + b_j)`, every derivative of every order
 admits an exact closed-form expression -- no automatic differentiation needed.
 
-Linear PDEs are solved in a single least-squares step; nonlinear PDEs are
-solved via Newton-Raphson iteration with Tikhonov regularisation,
-1/sqrt(N) feature normalisation, and continuation/homotopy.
+Linear PDEs are solved in a single least-squares step.  The random-feature
+system is typically rank-deficient, so the solve is routed through a
+backward-stable, auto-selected least-squares back-end (Cholesky fast-path ->
+Householder QR -> rank-revealing SVD) that runs on CPU, CUDA, or Apple-MPS.
+Nonlinear PDEs are solved via Newton-Raphson iteration with Tikhonov
+regularisation, 1/sqrt(N) feature normalisation, and continuation/homotopy.
 
 ## Installation
 
@@ -27,7 +30,7 @@ pip install fastlsq
 For development (includes testing and build tools):
 
 ```bash
-git clone https://github.com/asulc/FastLSQ.git
+git clone https://github.com/sulcantonin/FastLSQ.git
 cd FastLSQ
 pip install -e ".[dev]"
 ```
@@ -60,6 +63,26 @@ print(f"Converged in {result['n_iters']} iterations")
 print(f"Value error: {result['metrics']['val_err']:.2e}")
 ```
 
+### Choose a solver back-end and device
+
+The linear solve is routed automatically, but `solve_linear` exposes the
+back-end via `method=` (see [How it works](#how-it-works) for the routing):
+
+```python
+from fastlsq import solve_linear, set_device
+from fastlsq.problems.linear import PoissonND
+
+# "auto" (default) -- Cholesky fast-path -> QR -> rank-revealing SVD
+# "qr"             -- Householder QR; SVD-grade accuracy at QR cost (full-rank A)
+# "svd"            -- rank-revealing truncated SVD; the rank-deficient-safe reference
+# "cholesky"       -- normal-equations Cholesky; fast, well-conditioned A only
+# "rsvd"           -- randomized SVD, O(MNk), for strongly low-rank A
+result = solve_linear(PoissonND(), scale=5.0, method="qr")
+
+# Device selection (CPU / CUDA / Apple-MPS), or set FASTLSQ_DEVICE=cuda
+set_device("cuda")   # the float64 default stays on CPU/CUDA; MPS is float32-only
+```
+
 ### Use the basis directly
 
 ```python
@@ -163,9 +186,10 @@ u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per com
 
 Scalar problems are untouched: `n_outputs` defaults to `1`, `solver.beta` keeps
 shape `(N, 1)`, and `predict_with_grad` returns gradient shape `(M, d)` for
-backward compatibility (the trailing component axis is squeezed when k=1).
-`ElasticWave2D` in [fastlsq/problems/linear.py](fastlsq/problems/linear.py) is
-the canonical coupled vector example.
+backward compatibility (the trailing component axis is squeezed when k=1). The
+`Stokes2D` sketch above and [tests/test_block.py](tests/test_block.py) -- a
+runnable `block_concat` + `unpack_beta` solve that recovers both components of a
+k=2 system -- are the reference for the block-stacked vector path.
 
 ### Plot solutions
 
@@ -217,11 +241,15 @@ derivative engine:
 | `FastLSQSolver` | Manages feature blocks; exposes `.basis` for all derivative computations |
 | `LearnableFastLSQ` | Differentiable solver with learnable bandwidth via reparameterisation trick |
 | `block_concat`, `pack_beta`, `unpack_beta` | Block-structured assembly helpers for vector-valued **u** (coupled systems). `solver.beta` has shape `(N, k)`; scalar problems are the k=1 case |
+| `solve_lstsq` | Multi-back-end least-squares solve (`auto`/`qr`/`svd`/`cholesky`/`rsvd`); rank-revealing by default for the rank-deficient feature matrix |
+| `resolve_device` / `set_device` / `get_device` | CPU / CUDA / Apple-MPS selection, dtype-aware (MPS is float32-only; factorizations fall back to CPU) |
 
 ### How it works
 
 1. **Basis construction.** Given collocation points **x**, construct a
-   `SinusoidalBasis` with random weights W and biases b.
+   `SinusoidalBasis` with random weights W and biases b. The collocation counts
+   default to scale with the feature count
+   (`n_pde = max(3000, 3 * n_blocks * hidden_size)`, `n_bc = max(800, n_pde // 5)`).
 
 2. **Analytical derivatives.** Exploit the cyclic derivative identity:
    the n-th derivative of sin(z) cycles through {sin, cos, -sin, -cos}
@@ -232,8 +260,13 @@ derivative engine:
    (e.g. `Op.laplacian(d=2)`) and apply it to the basis to get the system
    matrix `A`.
 
-4. **Linear solve.** Solve `A beta = b` via least squares
-   (optionally Tikhonov-regularised).
+4. **Linear solve.** Solve `A beta = b` in the least-squares sense. The
+   random-feature matrix `A` is typically rank-deficient (near-duplicate
+   columns), so the default `method="auto"` starts from a Cholesky fast-path
+   (guarded by a cheap conditioning probe), falls back to backward-stable
+   Householder **QR**, and resorts to a rank-revealing **SVD** only if the QR
+   solution blows up. A Tikhonov ridge `mu` enters via the `[A; sqrt(mu) I]`
+   augmentation, not the condition-squaring normal equations.
 
 5. **Newton iteration (nonlinear).** Linearise the PDE residual, solve
    `J delta_beta = -R` with backtracking line search, and repeat.
@@ -295,9 +328,12 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 - **Symbolic PDE operators**: Compose differential operators with `Op` (Laplacian, wave, Helmholtz, biharmonic, custom) via intuitive arithmetic; coefficients can be `nn.Parameter` for AdamW optimisation
 - **Vector-valued solutions**: First-class support for **u**: ℝᵈ → ℝᵏ (elasticity, Stokes, Maxwell). Problems declare `n_outputs = k`; `block_concat` assembles coupled block systems; `solver.predict(x)` returns shape `(M, k)`. Scalar problems are the `k=1` case
 - **High-level API**: Solve PDEs in one line with `solve_linear()` and `solve_nonlinear()`
+- **Robust linear solver**: Pluggable least-squares back-ends; the default `auto` routes Cholesky -> QR -> SVD, and backward-stable QR delivers SVD-grade accuracy at QR cost on the rank-deficient random-feature system
 - **Learnable bandwidth**: `LearnableFastLSQ` optimises the bandwidth (scalar or anisotropic) via reparameterisation
 - **Learnable PDE coefficients**: Plug `nn.Parameter` into `Op` (e.g. Helmholtz wavenumber `k`) and optimise via AdamW; gradients flow through the prebuilt linear solve
 - **Auto-tuning**: Automatic scale selection via grid search
+- **Device support**: CPU / CUDA / Apple-MPS via `set_device()` or the `FASTLSQ_DEVICE` env var, dtype-aware (the float64 high-accuracy path stays on CPU/CUDA)
+- **Adaptive collocation**: `n_pde` / `n_bc` default to feature-count-scaled values, overridable per solve
 - **Built-in plotting**: Solution visualization, convergence plots, spectral sensitivity
 - **Geometry samplers**: Box, ball, sphere, interval, custom samplers
 - **Diagnostics**: Problem validation, conditioning checks, error detection