FastLSQ 0.1.0__tar.gz

fastlsq-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to FastLSQ will be documented in this file.
+
+## [0.1.0] - 2026-02-12
+
+### Added
+
+#### High-level API
+- `solve_linear()` - One-line function to solve linear PDEs
+- `solve_nonlinear()` - One-line function to solve nonlinear PDEs via Newton-Raphson
+- Automatic scale selection via `auto_select_scale()`
+
+#### Plotting & Visualization
+- `plot_solution_1d()` - Plot 1D solutions with exact comparison
+- `plot_solution_2d_slice()` - Plot 2D solutions as 1D slices
+- `plot_solution_2d_contour()` - Contour plots for 2D solutions
+- `plot_convergence()` - Newton iteration convergence plots
+- `plot_spectral_sensitivity()` - Error vs scale analysis
+
+#### Geometry & Sampling
+- `sample_box()` - Uniform sampling from hypercubes
+- `sample_ball()` - Uniform sampling from balls
+- `sample_sphere()` - Uniform sampling from sphere surfaces
+- `sample_interval()` - 1D interval sampling
+- `sample_boundary_box()` - Boundary point generation for boxes
+- `get_sampler()` - Get sampler by name
+
+#### Diagnostics & Error Handling
+- `check_problem()` - Validate problem definitions (shapes, gradients, data)
+- `check_solver_conditioning()` - Check linear system conditioning
+- `suggest_scale()` - Heuristic scale suggestions
+
+#### Export & Interoperability
+- `to_numpy()` - Convert predictions to NumPy arrays
+- `to_dict()` / `from_dict()` - Serialize/deserialize solver state
+- `save_checkpoint()` / `load_checkpoint()` - Save/load solver checkpoints
+- `FastLSQModule` - PyTorch Lightning integration (optional)
+
+#### Documentation & Examples
+- `examples/tutorial_basic.py` - Basic linear PDE tutorial
+- `examples/tutorial_nonlinear.py` - Nonlinear PDE tutorial
+- `examples/add_your_own_pde.py` - Guide for adding custom PDEs
+- `examples/custom_features.py` - Extensibility example
+- Comprehensive README with usage examples
+
+#### Infrastructure
+- `benchmarks/run_all.py` - Reproducible benchmark suite
+- `tests/test_basic.py` - Basic test suite
+- `.github/workflows/ci.yml` - GitHub Actions CI/CD
+- `CHANGELOG.md` - This file
+
+### Changed
+
+- Restructured codebase from 2 monolithic files into a proper Python package
+- Unified `FastLSQSolver` with optional normalization parameter
+- Removed code duplication (Bratu, NL-Helmholtz regression inherit from nonlinear versions)
+- Removed non-scientific content (emojis, casual language)
+
+### Fixed
+
+- Fixed missing `solve_lstsq` import in linear solver (was only defined in nonlinear file)
+- Improved error messages and diagnostics

fastlsq-0.1.0/FastLSQ.egg-info/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: FastLSQ
+Version: 0.1.0
+Summary: Solving PDEs in one shot via Fourier features with exact analytical derivatives
+Author: Antonin Sulc
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/asulc/FastLSQ
+Project-URL: Repository, https://github.com/asulc/FastLSQ
+Project-URL: Paper, https://arxiv.org/abs/2602.10541
+Project-URL: Bug Tracker, https://github.com/asulc/FastLSQ/issues
+Project-URL: Changelog, https://github.com/asulc/FastLSQ/blob/main/CHANGELOG.md
+Keywords: pde,partial-differential-equations,fourier-features,least-squares,scientific-computing,neural-network,physics-informed,newton-raphson
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: lightning
+Requires-Dist: pytorch-lightning>=2.0; extra == "lightning"
+Dynamic: license-file
+
+# FastLSQ
+
+<p align="center">
+  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="800"/>
+</p>
+
+**Solving PDEs in one shot via Fourier features with exact analytical derivatives.**
+
+FastLSQ is a lightweight PDE solver that uses Random Fourier Features with
+`sin` activation and closed-form first- and second-order derivatives.
+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.
+
+## Installation
+
+```bash
+pip install fastlsq
+```
+
+For development (includes testing and build tools):
+
+```bash
+git clone https://github.com/asulc/FastLSQ.git
+cd FastLSQ
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Solve a linear PDE in one line
+
+```python
+from fastlsq import solve_linear
+from fastlsq.problems.linear import PoissonND
+
+problem = PoissonND()
+result = solve_linear(problem, scale=5.0)  # Auto-selects scale if None
+
+u_fn = result["u_fn"]
+print(f"Value error: {result['metrics']['val_err']:.2e}")
+```
+
+### Solve a nonlinear PDE
+
+```python
+from fastlsq import solve_nonlinear
+from fastlsq.problems.nonlinear import NLPoisson2D
+
+problem = NLPoisson2D()
+result = solve_nonlinear(problem, max_iter=30)
+
+print(f"Converged in {result['n_iters']} iterations")
+print(f"Value error: {result['metrics']['val_err']:.2e}")
+```
+
+### Plot solutions
+
+```python
+from fastlsq.plotting import plot_solution_2d_contour, plot_convergence
+
+# Plot 2D solution
+plot_solution_2d_contour(result["solver"], problem, save_path="solution.png")
+
+# Plot Newton convergence
+plot_convergence(result["history"], problem_name=problem.name, save_path="convergence.png")
+```
+
+### Check your problem definition
+
+```python
+from fastlsq.diagnostics import check_problem
+
+check_problem(problem)  # Validates shapes, gradients, data consistency
+```
+
+### Benchmarks
+
+```bash
+# Linear PDE benchmark (Fast-LSQ vs PIELM)
+python examples/run_linear.py
+
+# Nonlinear PDE benchmark (Newton-Raphson)
+python examples/run_nonlinear.py
+```
+
+## Features
+
+- **High-level API**: Solve PDEs in one line with `solve_linear()` and `solve_nonlinear()`
+- **Auto-tuning**: Automatic scale selection via grid search
+- **Built-in plotting**: Solution visualization, convergence plots, spectral sensitivity
+- **Geometry samplers**: Box, ball, sphere, interval, custom samplers
+- **Diagnostics**: Problem validation, conditioning checks, error detection
+- **Export utilities**: NumPy conversion, checkpoint saving/loading
+- **PyTorch Lightning**: Integration for training loops
+- **20+ benchmark problems**: Linear, nonlinear, and regression-mode PDEs
+
+## Method overview
+
+1. **Feature construction.** Given collocation points x, compute
+   `H = sin(x W + b)` together with exact derivatives
+   `dH = cos(x W + b) * W` and `ddH = -sin(x W + b) * W^2`.
+
+2. **Linear solve.** Assemble the PDE operator in feature space:
+   `A beta = b`, and solve via least squares (optionally Tikhonov-regularised).
+
+3. **Newton iteration (nonlinear).** Linearise the PDE residual around the
+   current iterate, solve `J delta_beta = -R` with backtracking line search,
+   and repeat until convergence.
+
+## Adding your own PDE
+
+Create a problem class with these methods:
+
+```python
+class MyProblem:
+    def __init__(self):
+        self.name = "My PDE"
+        self.dim = 2  # Spatial dimension
+
+    def exact(self, x):
+        """Analytical solution u(x)."""
+        return torch.sin(np.pi * x[:, 0:1]) * torch.sin(np.pi * x[:, 1:2])
+
+    def exact_grad(self, x):
+        """Gradient of exact solution."""
+        # ... compute gradient analytically
+        return grad_u
+
+    def get_train_data(self, n_pde=5000, n_bc=1000):
+        """Return (x_pde, bcs, f_pde) for training."""
+        # ... sample collocation and boundary points
+        return x_pde, bcs, f_pde
+
+    def build(self, solver, x_pde, bcs, f_pde):
+        """Assemble linear system A beta = b."""
+        # ... build system matrix
+        return A, b
+
+    def get_test_points(self, n=5000):
+        """Random test points for evaluation."""
+        return torch.rand(n, self.dim)
+```
+
+Then solve it:
+
+```python
+problem = MyProblem()
+result = solve_linear(problem)
+```
+
+## Paper
+
+The full preprint is available on [arXiv](https://arxiv.org/abs/2602.10541)
+
+## Citing this work
+
+If you use FastLSQ in your research, please cite:
+
+```bibtex
+@misc{sulc2026solvingpdesshotfourier,
+      title={Solving PDEs in One Shot via Fourier Features with Exact Analytical Derivatives},
+      author={Antonin Sulc},
+      year={2026},
+      eprint={2602.10541},
+      archivePrefix={arXiv},
+      primaryClass={math.NA},
+      url={https://arxiv.org/abs/2602.10541},
+}
+```
+
+## License
+
+This project is licensed under the MIT License -- see [LICENSE](LICENSE) for details.

fastlsq-0.1.0/FastLSQ.egg-info/SOURCES.txt

@@ -0,0 +1,34 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+FastLSQ.egg-info/PKG-INFO
+FastLSQ.egg-info/SOURCES.txt
+FastLSQ.egg-info/dependency_links.txt
+FastLSQ.egg-info/requires.txt
+FastLSQ.egg-info/top_level.txt
+examples/add_your_own_pde.py
+examples/custom_features.py
+examples/run_linear.py
+examples/run_nonlinear.py
+examples/tutorial_basic.py
+examples/tutorial_nonlinear.py
+fastlsq/__init__.py
+fastlsq/api.py
+fastlsq/diagnostics.py
+fastlsq/export.py
+fastlsq/geometry.py
+fastlsq/lightning.py
+fastlsq/linalg.py
+fastlsq/newton.py
+fastlsq/plotting.py
+fastlsq/solvers.py
+fastlsq/tuning.py
+fastlsq/utils.py
+fastlsq/problems/__init__.py
+fastlsq/problems/linear.py
+fastlsq/problems/nonlinear.py
+fastlsq/problems/regression.py
+tests/test_basic.py

fastlsq-0.1.0/FastLSQ.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastlsq-0.1.0/FastLSQ.egg-info/requires.txt

@@ -0,0 +1,12 @@
+torch>=2.0
+numpy>=1.24
+matplotlib>=3.7
+
+[dev]
+pytest>=7.0
+pandas>=2.0
+build
+twine
+
+[lightning]
+pytorch-lightning>=2.0

fastlsq-0.1.0/FastLSQ.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastlsq

fastlsq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonin Sulc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastlsq-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include requirements.txt
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.pyc

fastlsq-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: FastLSQ
+Version: 0.1.0
+Summary: Solving PDEs in one shot via Fourier features with exact analytical derivatives
+Author: Antonin Sulc
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/asulc/FastLSQ
+Project-URL: Repository, https://github.com/asulc/FastLSQ
+Project-URL: Paper, https://arxiv.org/abs/2602.10541
+Project-URL: Bug Tracker, https://github.com/asulc/FastLSQ/issues
+Project-URL: Changelog, https://github.com/asulc/FastLSQ/blob/main/CHANGELOG.md
+Keywords: pde,partial-differential-equations,fourier-features,least-squares,scientific-computing,neural-network,physics-informed,newton-raphson
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: lightning
+Requires-Dist: pytorch-lightning>=2.0; extra == "lightning"
+Dynamic: license-file
+
+# FastLSQ
+
+<p align="center">
+  <img src="misc/fastlsq_teaser.png" alt="FastLSQ method overview" width="800"/>
+</p>
+
+**Solving PDEs in one shot via Fourier features with exact analytical derivatives.**
+
+FastLSQ is a lightweight PDE solver that uses Random Fourier Features with
+`sin` activation and closed-form first- and second-order derivatives.
+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.
+
+## Installation
+
+```bash
+pip install fastlsq
+```
+
+For development (includes testing and build tools):
+
+```bash
+git clone https://github.com/asulc/FastLSQ.git
+cd FastLSQ
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Solve a linear PDE in one line
+
+```python
+from fastlsq import solve_linear
+from fastlsq.problems.linear import PoissonND
+
+problem = PoissonND()
+result = solve_linear(problem, scale=5.0)  # Auto-selects scale if None
+
+u_fn = result["u_fn"]
+print(f"Value error: {result['metrics']['val_err']:.2e}")
+```
+
+### Solve a nonlinear PDE
+
+```python
+from fastlsq import solve_nonlinear
+from fastlsq.problems.nonlinear import NLPoisson2D
+
+problem = NLPoisson2D()
+result = solve_nonlinear(problem, max_iter=30)
+
+print(f"Converged in {result['n_iters']} iterations")
+print(f"Value error: {result['metrics']['val_err']:.2e}")
+```
+
+### Plot solutions
+
+```python
+from fastlsq.plotting import plot_solution_2d_contour, plot_convergence
+
+# Plot 2D solution
+plot_solution_2d_contour(result["solver"], problem, save_path="solution.png")
+
+# Plot Newton convergence
+plot_convergence(result["history"], problem_name=problem.name, save_path="convergence.png")
+```
+
+### Check your problem definition
+
+```python
+from fastlsq.diagnostics import check_problem
+
+check_problem(problem)  # Validates shapes, gradients, data consistency
+```
+
+### Benchmarks
+
+```bash
+# Linear PDE benchmark (Fast-LSQ vs PIELM)
+python examples/run_linear.py
+
+# Nonlinear PDE benchmark (Newton-Raphson)
+python examples/run_nonlinear.py
+```
+
+## Features
+
+- **High-level API**: Solve PDEs in one line with `solve_linear()` and `solve_nonlinear()`
+- **Auto-tuning**: Automatic scale selection via grid search
+- **Built-in plotting**: Solution visualization, convergence plots, spectral sensitivity
+- **Geometry samplers**: Box, ball, sphere, interval, custom samplers
+- **Diagnostics**: Problem validation, conditioning checks, error detection
+- **Export utilities**: NumPy conversion, checkpoint saving/loading
+- **PyTorch Lightning**: Integration for training loops
+- **20+ benchmark problems**: Linear, nonlinear, and regression-mode PDEs
+
+## Method overview
+
+1. **Feature construction.** Given collocation points x, compute
+   `H = sin(x W + b)` together with exact derivatives
+   `dH = cos(x W + b) * W` and `ddH = -sin(x W + b) * W^2`.
+
+2. **Linear solve.** Assemble the PDE operator in feature space:
+   `A beta = b`, and solve via least squares (optionally Tikhonov-regularised).
+
+3. **Newton iteration (nonlinear).** Linearise the PDE residual around the
+   current iterate, solve `J delta_beta = -R` with backtracking line search,
+   and repeat until convergence.
+
+## Adding your own PDE
+
+Create a problem class with these methods:
+
+```python
+class MyProblem:
+    def __init__(self):
+        self.name = "My PDE"
+        self.dim = 2  # Spatial dimension
+
+    def exact(self, x):
+        """Analytical solution u(x)."""
+        return torch.sin(np.pi * x[:, 0:1]) * torch.sin(np.pi * x[:, 1:2])
+
+    def exact_grad(self, x):
+        """Gradient of exact solution."""
+        # ... compute gradient analytically
+        return grad_u
+
+    def get_train_data(self, n_pde=5000, n_bc=1000):
+        """Return (x_pde, bcs, f_pde) for training."""
+        # ... sample collocation and boundary points
+        return x_pde, bcs, f_pde
+
+    def build(self, solver, x_pde, bcs, f_pde):
+        """Assemble linear system A beta = b."""
+        # ... build system matrix
+        return A, b
+
+    def get_test_points(self, n=5000):
+        """Random test points for evaluation."""
+        return torch.rand(n, self.dim)
+```
+
+Then solve it:
+
+```python
+problem = MyProblem()
+result = solve_linear(problem)
+```
+
+## Paper
+
+The full preprint is available on [arXiv](https://arxiv.org/abs/2602.10541)
+
+## Citing this work
+
+If you use FastLSQ in your research, please cite:
+
+```bibtex
+@misc{sulc2026solvingpdesshotfourier,
+      title={Solving PDEs in One Shot via Fourier Features with Exact Analytical Derivatives},
+      author={Antonin Sulc},
+      year={2026},
+      eprint={2602.10541},
+      archivePrefix={arXiv},
+      primaryClass={math.NA},
+      url={https://arxiv.org/abs/2602.10541},
+}
+```
+
+## License
+
+This project is licensed under the MIT License -- see [LICENSE](LICENSE) for details.