README: add Performance section with the lapackdrivers timing plot

The lapackdrivers benchmark example was already producing a timing
figure (`figure1_latest.pdf`) but it lived in nobody's mental model:
no README reference, file name suggesting "draft," cwd-relative output
path so it landed wherever the user happened to invoke the script.

This commit gives the figure a proper home:

  - examples/lapackdrivers_example.py now saves to project root via
    a `__file__`-anchored path (regardless of where the example was
    invoked from), and produces both `lapack_timings.png` (150 dpi,
    bbox tight, README artifact) and `lapack_timings.pdf` (vector
    quality, for printing or reuse). The historical
    `figure1_latest.pdf` name is gone.
  - lapack_timings.png is committed at the project root as the
    canonical README image. The .pdf sibling is gitignored — it is
    just a regenerable build product. The legacy `figure1_latest.pdf`
    name is also gitignored, in case stale copies linger in working
    trees.
  - README.md gains a "## Performance" section between Features and
    Examples, embedding the PNG with a two-paragraph caption that
    explains what the lines mean (parallel batched LAPACK drivers
    vs. a Python loop over numpy.linalg.solve, log–log scale), what
    the takeaway is (most savings come from staying inside nogil
    Cython for the loop and from OpenMP across independent problems),
    and how to regenerate the figure on the reader's own machine.
    Also a short cross-reference from the Speed bullet under
    Features pointing at the new section.

The figure is reproducible across runs and machines now that the
example seeds the legacy global RNG with `np.random.seed(42)`
(committed in the previous patch).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Technologicat

.gitignore

@@ -22,3 +22,12 @@ pdm.lock
 wlsqm/fitter/*.html
 wlsqm/utils/*.html
 .claude/
+
+# Regenerable artifact from examples/lapackdrivers_example.py.
+# The PNG sibling IS committed (it's referenced from README.md), but the
+# PDF is just for vector-quality printing and would just churn whenever
+# someone reruns the example.
+lapack_timings.pdf
+# Old name produced by versions of the example before v1.0; kept for
+# back-compat in case anyone has stale copies in their working tree.
+figure1_latest.pdf

README.md

@@ -72,6 +72,7 @@ Full derivation of the generalized version (including the case of unknown functi
 - **Speed.**
   - Performance-critical code is in Cython with the GIL released.
   - LAPACK is called directly via [SciPy's Cython-level bindings](https://docs.scipy.org/doc/scipy/reference/linalg.cython_lapack.html); no GIL round-trip for the solver loop.
+  - For asymptotic timings of the parallel batched LAPACK drivers vs. a Python loop over `numpy.linalg.solve`, see the figure under "Performance" below.
 - **Accuracy.**
   - Problem matrices are preconditioned by a symmetry-preserving iterative scaling (Ruiz, 2001) before LU factorization, which is critical for high-order fits.
     - Reference: Daniel Ruiz. 2001. *A Scaling Algorithm to Equilibrate Both Rows and Columns Norms in Matrices*. Report RAL-TR-2001-034.
@@ -81,6 +82,23 @@ Full derivation of the generalized version (including the case of unknown functi
   - Optional iterative refinement inside the solver mitigates roundoff further.
 
 
+## Performance
+
+![Average time per problem instance, parallel LAPACK drivers vs. a Python loop over numpy.linalg.solve, log–log scale](lapack_timings.png)
+
+Average time per problem instance for the parallel LAPACK drivers in `wlsqm.utils.lapackdrivers`, on a synthetic batch of independent symmetric and general linear systems of varying matrix size `n`. Generated by [`examples/lapackdrivers_example.py`](examples/lapackdrivers_example.py) (seeded RNG, deterministic). Both axes are log scale.
+
+The takeaway is that the batched parallel drivers (red and green lines) cost a small fraction of what a Python loop calling `numpy.linalg.solve` (black line) costs per instance — most of the savings come from staying inside `nogil` Cython for the loop and from OpenMP parallelism over independent problems. The factorize-once-then-solve pair (green) is essentially as fast as the single-shot solver (red) when the batch is solved exactly once, and pays off when the same factorization is reused against many right-hand sides.
+
+To regenerate the figure on your own machine:
+
+```bash
+python examples/lapackdrivers_example.py
+```
+
+The script writes both `lapack_timings.png` and `lapack_timings.pdf` to the project root.
+
+
 ## Examples
 
 Minimal example using a manufactured solution to produce the input data: fit `f(x,y) = 1 + 2x + 3y + 4xy + 5x² + 6y²` on a scattered point cloud centered at the origin.

examples/lapackdrivers_example.py

@@ -6,13 +6,20 @@
 """
 
 
+import os
 import time
 
 import numpy as np
 from numpy.linalg import solve as numpy_solve  # for comparison purposes
 
 import matplotlib.pyplot as plt
 
+# Where to write the timing-plot output files. Anchor to the project root
+# (one level up from this script) so the PNG and PDF land in a stable,
+# version-controllable location regardless of where the example was
+# invoked from. README.md embeds `lapack_timings.png` from here.
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir))
+
 try:
     import wlsqm.utils.lapackdrivers as drivers
 except ImportError:
@@ -337,7 +344,10 @@ def main():
     plt.grid(visible=True, which='both')
     plt.legend(loc='best')
 
-    plt.savefig('figure1_latest.pdf')
+    # Save both formats: PNG for embedding in README.md, PDF for printing
+    # / vector-quality reuse. Both go to the project root.
+    plt.savefig(os.path.join(PROJECT_ROOT, 'lapack_timings.png'), dpi=150, bbox_inches='tight')
+    plt.savefig(os.path.join(PROJECT_ROOT, 'lapack_timings.pdf'),           bbox_inches='tight')
 
 
 if __name__ == '__main__':