FastLSQ 0.1.4__tar.gz → 0.1.5__tar.gz

{fastlsq-0.1.4 → fastlsq-0.1.5}/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to FastLSQ will be documented in this file.
 
 ### Added
 
+- **Vector-valued solutions (`u: ℝᵈ → ℝᵏ`)**: first-class support for coupled
+  systems and decoupled multi-output PDEs. Problems opt in with
+  `self.n_outputs = k`; `solver.beta` has shape `(N, k)` and
+  `solver.predict(x)` returns `(M, k)`. Scalar problems are the `k=1` case
+  and remain bit-for-bit identical (Helmholtz 2D / Poisson 5D / Bratu 2D
+  regressions verified).
+  - New module `fastlsq.block`: `block_concat` assembles a 2-D nested list
+    of `(M_i, N_j)` tensors into a block matrix (with `None` for zero
+    blocks); `pack_beta` / `unpack_beta` convert between `(N, k)` and the
+    block-stacked `(N*k, 1)` solve representation.
+  - `predict_with_grad` / `predict_with_laplacian` einsum fixed to
+    `"idh,hk->idk"` so the output dim no longer collapses for `k>1`. Squeezes
+    back to `(M, d)` when `k=1` for backward compatibility.
+  - `ElasticWave2D` refactored: gains `n_outputs = 2`, `build()` uses
+    `block_concat`, and now exposes `exact_grad` with shape `(M, d, k)`.
+  - `LearnableFastLSQ` accepts `n_outputs`; legacy subclasses that store a
+    flat `(Nk, 1)` `beta` (e.g. `ElasticLearnable` in the elastic wave
+    example) keep working under the default `n_outputs=1`.
 - **Learnable operator coefficients**: `Op` now accepts `nn.Parameter` (and tensors) as coefficients in scalar multiplication. Use `k = nn.Parameter(...)` with `Op.laplacian(d=2) + k**2 * Op.identity(d=2)` and optimise via AdamW; gradients flow through the prebuilt linear solve. See `examples/learnable_helmholtz.py`.
 
 ## [0.2.0] - 2026-03-01

{fastlsq-0.1.4 → fastlsq-0.1.5/FastLSQ.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.1.4
+Version: 0.1.5
 Summary: Solving PDEs in one shot via Fourier features with exact analytical derivatives
 Author: Antonin Sulc
 License-Expression: MIT
@@ -25,6 +25,10 @@ License-File: LICENSE
 Requires-Dist: torch>=2.0
 Requires-Dist: numpy>=1.24
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: battery
+Requires-Dist: progpy>=1.3; extra == "battery"
+Requires-Dist: pandas>=2.0; extra == "battery"
+Requires-Dist: scipy>=1.10; extra == "battery"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
@@ -36,8 +40,11 @@ Dynamic: license-file
 
 # FastLSQ
 
+[BerkeleyLab ATAP Talk](https://github.com/sulcantonin/FastLSQ/raw/main/presentations/ATAP_Sulc_20260324.pptx)
+
+
 <p align="center">
-  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="800"/>
+  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
 </p>
 
 **Solving PDEs in one shot via Fourier features with exact analytical derivatives.**
@@ -128,6 +135,78 @@ A_pde = helmholtz.apply(basis, x)    # (5000, 1500)
 wave = Op.partial(dim=2, order=2, d=3) - c**2 * Op.laplacian(d=3, dims=[0, 1])
 ```
 
+### Vector-valued solutions
+
+`solve_linear` / `solve_nonlinear` support vector-valued **u**: ℝᵈ → ℝᵏ for
+coupled systems (elasticity, Stokes, Maxwell vector potential, …) and for
+decoupled multi-output problems sharing one basis. The math is unchanged; the
+solver just allocates `beta` with shape `(N, k)` so that `solver.predict(x)`
+returns shape `(M, k)` directly.
+
+A problem opts in by setting `self.n_outputs = k` and assembling its operator
+in block-stacked form `A ∈ ℝ^{Mk × Nk}`, `b ∈ ℝ^{Mk × 1}`. The helper
+`block_concat` removes the manual `torch.cat` bookkeeping:
+
+```python
+import torch
+from fastlsq import solve_linear, block_concat
+
+class Stokes2D:
+    n_outputs = 3        # (u, v, p)
+    dim = 2
+    name = "Stokes 2D"
+    # ... exact, exact_grad, get_train_data, get_test_points ...
+
+    def build(self, slv, x, bcs, f):
+        basis = slv.basis
+        cache = basis.cache(x)
+        dx = basis.derivative(x, (1, 0), cache=cache)
+        dy = basis.derivative(x, (0, 1), cache=cache)
+        lap = basis.laplacian(x, cache=cache)
+
+        # Rows = equations (mom_x, mom_y, continuity);
+        # columns = coefficient blocks (u, v, p)
+        A = block_concat([
+            [-lap,  None,  dx  ],   # -Δu + ∂p/∂x = f_x
+            [ None, -lap,  dy  ],   # -Δv + ∂p/∂y = f_y
+            [ dx,   dy,    None],   #  ∂u/∂x + ∂v/∂y = 0
+        ])
+        b = block_concat([[f[:, 0:1]], [f[:, 1:2]], [torch.zeros_like(f[:, 0:1])]])
+        # ... add BC blocks the same way ...
+        return A, b
+
+result = solve_linear(Stokes2D(), scale=5.0)
+u = result["u_fn"](x_test)        # shape (M, 3): columns are (u, v, p)
+```
+
+#### Partial derivatives for a vector u
+
+The basis-level operators (`basis.derivative`, `basis.gradient`,
+`basis.laplacian`, `DiffOperator.apply`) all return shape `(M, N)` regardless
+of how many components `u` has — vector-ness only enters when you contract
+with `beta`:
+
+```python
+# Full Jacobian, then slice (M, d, k) -> per (component, dim)
+u, J = solver.predict_with_grad(x)   # J shape (M, d, k); J[:, j, c] = ∂u_c/∂x_j
+
+# Single operator on a single component
+D_y = solver.basis.derivative(x, alpha=(0, 1))   # (M, N): ∂φ/∂y
+du0_dy = D_y @ solver.beta[:, 0:1]               # ∂u_0/∂y
+
+# Symbolic operator, all components at once
+from fastlsq import Op
+yy = Op.partial(dim=1, order=2, d=2)
+A  = yy.apply(solver.basis, x)                   # (M, N)
+u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per component
+```
+
+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.
+
 ### Plot solutions
 
 ```python
@@ -177,6 +256,7 @@ derivative engine:
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `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 |
 
 ### How it works
 
@@ -253,6 +333,7 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 
 - **Analytical derivative engine**: `SinusoidalBasis` computes arbitrary-order derivatives exactly in O(1) -- the foundation of the entire framework
 - **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()`
 - **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

{fastlsq-0.1.4 → fastlsq-0.1.5}/FastLSQ.egg-info/SOURCES.txt

@@ -22,6 +22,17 @@ examples/run_linear.py
 examples/run_nonlinear.py
 examples/tutorial_basic.py
 examples/tutorial_nonlinear.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/inverse/aero_.py
 examples/inverse/denoising_parameter_estimation.py
 examples/inverse/elastic_wave_animation.py
@@ -37,6 +48,7 @@ examples/sindy/sindy_minimal_diff.py
 fastlsq/__init__.py
 fastlsq/api.py
 fastlsq/basis.py
+fastlsq/block.py
 fastlsq/diagnostics.py
 fastlsq/export.py
 fastlsq/geometry.py

{fastlsq-0.1.4 → fastlsq-0.1.5}/FastLSQ.egg-info/requires.txt

@@ -2,6 +2,11 @@ torch>=2.0
 numpy>=1.24
 matplotlib>=3.7
 
+[battery]
+progpy>=1.3
+pandas>=2.0
+scipy>=1.10
+
 [dev]
 pytest>=7.0
 pandas>=2.0

{fastlsq-0.1.4/FastLSQ.egg-info → fastlsq-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastLSQ
-Version: 0.1.4
+Version: 0.1.5
 Summary: Solving PDEs in one shot via Fourier features with exact analytical derivatives
 Author: Antonin Sulc
 License-Expression: MIT
@@ -25,6 +25,10 @@ License-File: LICENSE
 Requires-Dist: torch>=2.0
 Requires-Dist: numpy>=1.24
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: battery
+Requires-Dist: progpy>=1.3; extra == "battery"
+Requires-Dist: pandas>=2.0; extra == "battery"
+Requires-Dist: scipy>=1.10; extra == "battery"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
@@ -36,8 +40,11 @@ Dynamic: license-file
 
 # FastLSQ
 
+[BerkeleyLab ATAP Talk](https://github.com/sulcantonin/FastLSQ/raw/main/presentations/ATAP_Sulc_20260324.pptx)
+
+
 <p align="center">
-  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="800"/>
+  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
 </p>
 
 **Solving PDEs in one shot via Fourier features with exact analytical derivatives.**
@@ -128,6 +135,78 @@ A_pde = helmholtz.apply(basis, x)    # (5000, 1500)
 wave = Op.partial(dim=2, order=2, d=3) - c**2 * Op.laplacian(d=3, dims=[0, 1])
 ```
 
+### Vector-valued solutions
+
+`solve_linear` / `solve_nonlinear` support vector-valued **u**: ℝᵈ → ℝᵏ for
+coupled systems (elasticity, Stokes, Maxwell vector potential, …) and for
+decoupled multi-output problems sharing one basis. The math is unchanged; the
+solver just allocates `beta` with shape `(N, k)` so that `solver.predict(x)`
+returns shape `(M, k)` directly.
+
+A problem opts in by setting `self.n_outputs = k` and assembling its operator
+in block-stacked form `A ∈ ℝ^{Mk × Nk}`, `b ∈ ℝ^{Mk × 1}`. The helper
+`block_concat` removes the manual `torch.cat` bookkeeping:
+
+```python
+import torch
+from fastlsq import solve_linear, block_concat
+
+class Stokes2D:
+    n_outputs = 3        # (u, v, p)
+    dim = 2
+    name = "Stokes 2D"
+    # ... exact, exact_grad, get_train_data, get_test_points ...
+
+    def build(self, slv, x, bcs, f):
+        basis = slv.basis
+        cache = basis.cache(x)
+        dx = basis.derivative(x, (1, 0), cache=cache)
+        dy = basis.derivative(x, (0, 1), cache=cache)
+        lap = basis.laplacian(x, cache=cache)
+
+        # Rows = equations (mom_x, mom_y, continuity);
+        # columns = coefficient blocks (u, v, p)
+        A = block_concat([
+            [-lap,  None,  dx  ],   # -Δu + ∂p/∂x = f_x
+            [ None, -lap,  dy  ],   # -Δv + ∂p/∂y = f_y
+            [ dx,   dy,    None],   #  ∂u/∂x + ∂v/∂y = 0
+        ])
+        b = block_concat([[f[:, 0:1]], [f[:, 1:2]], [torch.zeros_like(f[:, 0:1])]])
+        # ... add BC blocks the same way ...
+        return A, b
+
+result = solve_linear(Stokes2D(), scale=5.0)
+u = result["u_fn"](x_test)        # shape (M, 3): columns are (u, v, p)
+```
+
+#### Partial derivatives for a vector u
+
+The basis-level operators (`basis.derivative`, `basis.gradient`,
+`basis.laplacian`, `DiffOperator.apply`) all return shape `(M, N)` regardless
+of how many components `u` has — vector-ness only enters when you contract
+with `beta`:
+
+```python
+# Full Jacobian, then slice (M, d, k) -> per (component, dim)
+u, J = solver.predict_with_grad(x)   # J shape (M, d, k); J[:, j, c] = ∂u_c/∂x_j
+
+# Single operator on a single component
+D_y = solver.basis.derivative(x, alpha=(0, 1))   # (M, N): ∂φ/∂y
+du0_dy = D_y @ solver.beta[:, 0:1]               # ∂u_0/∂y
+
+# Symbolic operator, all components at once
+from fastlsq import Op
+yy = Op.partial(dim=1, order=2, d=2)
+A  = yy.apply(solver.basis, x)                   # (M, N)
+u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per component
+```
+
+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.
+
 ### Plot solutions
 
 ```python
@@ -177,6 +256,7 @@ derivative engine:
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `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 |
 
 ### How it works
 
@@ -253,6 +333,7 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 
 - **Analytical derivative engine**: `SinusoidalBasis` computes arbitrary-order derivatives exactly in O(1) -- the foundation of the entire framework
 - **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()`
 - **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

{fastlsq-0.1.4 → fastlsq-0.1.5}/README.md

@@ -1,7 +1,10 @@
 # FastLSQ
 
+[BerkeleyLab ATAP Talk](https://github.com/sulcantonin/FastLSQ/raw/main/presentations/ATAP_Sulc_20260324.pptx)
+
+
 <p align="center">
-  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="800"/>
+  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="400"/>
 </p>
 
 **Solving PDEs in one shot via Fourier features with exact analytical derivatives.**
@@ -92,6 +95,78 @@ A_pde = helmholtz.apply(basis, x)    # (5000, 1500)
 wave = Op.partial(dim=2, order=2, d=3) - c**2 * Op.laplacian(d=3, dims=[0, 1])
 ```
 
+### Vector-valued solutions
+
+`solve_linear` / `solve_nonlinear` support vector-valued **u**: ℝᵈ → ℝᵏ for
+coupled systems (elasticity, Stokes, Maxwell vector potential, …) and for
+decoupled multi-output problems sharing one basis. The math is unchanged; the
+solver just allocates `beta` with shape `(N, k)` so that `solver.predict(x)`
+returns shape `(M, k)` directly.
+
+A problem opts in by setting `self.n_outputs = k` and assembling its operator
+in block-stacked form `A ∈ ℝ^{Mk × Nk}`, `b ∈ ℝ^{Mk × 1}`. The helper
+`block_concat` removes the manual `torch.cat` bookkeeping:
+
+```python
+import torch
+from fastlsq import solve_linear, block_concat
+
+class Stokes2D:
+    n_outputs = 3        # (u, v, p)
+    dim = 2
+    name = "Stokes 2D"
+    # ... exact, exact_grad, get_train_data, get_test_points ...
+
+    def build(self, slv, x, bcs, f):
+        basis = slv.basis
+        cache = basis.cache(x)
+        dx = basis.derivative(x, (1, 0), cache=cache)
+        dy = basis.derivative(x, (0, 1), cache=cache)
+        lap = basis.laplacian(x, cache=cache)
+
+        # Rows = equations (mom_x, mom_y, continuity);
+        # columns = coefficient blocks (u, v, p)
+        A = block_concat([
+            [-lap,  None,  dx  ],   # -Δu + ∂p/∂x = f_x
+            [ None, -lap,  dy  ],   # -Δv + ∂p/∂y = f_y
+            [ dx,   dy,    None],   #  ∂u/∂x + ∂v/∂y = 0
+        ])
+        b = block_concat([[f[:, 0:1]], [f[:, 1:2]], [torch.zeros_like(f[:, 0:1])]])
+        # ... add BC blocks the same way ...
+        return A, b
+
+result = solve_linear(Stokes2D(), scale=5.0)
+u = result["u_fn"](x_test)        # shape (M, 3): columns are (u, v, p)
+```
+
+#### Partial derivatives for a vector u
+
+The basis-level operators (`basis.derivative`, `basis.gradient`,
+`basis.laplacian`, `DiffOperator.apply`) all return shape `(M, N)` regardless
+of how many components `u` has — vector-ness only enters when you contract
+with `beta`:
+
+```python
+# Full Jacobian, then slice (M, d, k) -> per (component, dim)
+u, J = solver.predict_with_grad(x)   # J shape (M, d, k); J[:, j, c] = ∂u_c/∂x_j
+
+# Single operator on a single component
+D_y = solver.basis.derivative(x, alpha=(0, 1))   # (M, N): ∂φ/∂y
+du0_dy = D_y @ solver.beta[:, 0:1]               # ∂u_0/∂y
+
+# Symbolic operator, all components at once
+from fastlsq import Op
+yy = Op.partial(dim=1, order=2, d=2)
+A  = yy.apply(solver.basis, x)                   # (M, N)
+u_yy = A @ solver.beta                           # (M, k): ∂²u/∂y² per component
+```
+
+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.
+
 ### Plot solutions
 
 ```python
@@ -141,6 +216,7 @@ derivative engine:
 | `FeatureBasis` | Adapter for non-sinusoidal solvers (e.g. PIELM with tanh) |
 | `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 |
 
 ### How it works
 
@@ -217,6 +293,7 @@ See `examples/add_your_own_pde.py` for the complete tutorial.
 
 - **Analytical derivative engine**: `SinusoidalBasis` computes arbitrary-order derivatives exactly in O(1) -- the foundation of the entire framework
 - **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()`
 - **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