Refine citation references in README, lsmr, and tridiag_sym (#259)

* Mention that a Matfree paper is in preparation

* Add bibtex's for LSMR and Lanczos to the respective functions

* Fix a typo

Author: pnkraemer

Makefile

@@ -23,7 +23,7 @@ doc-preview:
 	python scripts/generate_api_docs.py
 	python scripts/readme_to_dev_docs.py
 	python scripts/tutorials_to_py_light.py
-	mkdocs serve
+	JUPYTER_PLATFORM_DIRS=1 mkdocs serve
 
 doc-build:
 	python scripts/generate_api_docs.py

README.md

@@ -102,9 +102,10 @@ These tutorials include, among other things:
 **Citation**
 
 Thank you for using Matfree!
-If you are using Matfree's differentiable Lanczos or Arnoldi iterations, then you
-are using the algorithms from [this paper](https://arxiv.org/abs/2405.17277).
-We would appreciate it if you cited the paper as follows:
+A dedicated paper about Matfree itself is in preparation.\
+In the meantime, if you are using Matfree's **differentiable Lanczos or Arnoldi iterations**, then you
+are using the algorithms introduced by [this paper](https://arxiv.org/abs/2405.17277).
+We would appreciate it if you cited it as follows:
 
 ```bibtex
 @article{kraemer2024gradients,
@@ -117,9 +118,9 @@ We would appreciate it if you cited the paper as follows:
 }
 ```
 
-If you are using Matfree's differentiable LSMR implementation, then you
+If you are using Matfree's **differentiable LSMR implementation**, then you
 are using the algorithm from [this paper](https://arxiv.org/abs/2510.19634).
-We would appreciate it if you cited the paper as follows:
+We would appreciate it if you cited it as follows:
 
 ```bibtex
 @article{roy2025matrix,

matfree/decomp.py

@@ -37,20 +37,30 @@ def tridiag_sym(
 ):
     r"""Construct an implementation of **tridiagonalisation**.
 
-    Uses pre-allocation, and full reorthogonalisation if `reortho` is set to `"full"`.
-    It tends to be a good idea to use full reorthogonalisation.
-
-    This algorithm assumes a **symmetric matrix**.
-
-    Decompose a matrix into a product of orthogonal-**tridiagonal**-orthogonal matrices.
+    Decompose a **symmetric** matrix into a product of orthogonal-**tridiagonal**-orthogonal matrices.
     Use this algorithm for approximate **eigenvalue** decompositions.
+    The present implementation allocates all Lanczos vectors before running the
+    algorithm. If `reortho` is set to `"full"`, it also uses full reorthogonalisation.
+    It is usually a good idea to use full reorthogonalisation.
+    Matrix-free tridiagonalisation uses Lanczos' (1950) algorithm:
+
+    ??? note "BibTex for Lanczos (1950)"
+        ```bibtex
+        @article{lanczos1950iteration,
+            title={An iteration method for the solution of the eigenvalue problem of linear differential and integral operators},
+            author={Lanczos, Cornelius},
+            journal={Journal of research of the National Bureau of Standards},
+            volume={45},
+            number={4},
+            pages={255--282},
+            year={1950}
+        }
+        ```
 
     Setting `custom_vjp` to `True` implies using efficient, numerically stable
-    gradients of the Lanczos iteration according to what has been proposed by
-    Krämer et al. (2024).
+    gradients of the Lanczos iteration which was proposed by Krämer et al. (2024).
     These gradients are exact, so there is little reason not to use them.
-    If you use this configuration, please consider
-    citing Krämer et al. (2024; bibtex below).
+    If you use this configuration, please cite Krämer et al. (2024):
 
     ??? note "BibTex for Krämer et al. (2024)"
         ```bibtex
@@ -602,9 +612,10 @@ def bidiag(num_matvecs: int, /, materialize: bool = True, reortho: str = "full")
     ??? note "A note about differentiability"
         Unlike [tridiag_sym][matfree.decomp.tridiag_sym] or
         [hessenberg][matfree.decomp.hessenberg], this function's reverse-mode
-        derivatives are very efficient. Custom gradients for bidiagonalisation
-        are a work in progress, and if you need to differentiate the decompositions,
-        consider using [tridiag_sym][matfree.decomp.tridiag_sym] for the time being.
+        derivatives are not efficient. Custom gradients for bidiagonalisation
+        are a work in progress. In the meantime,
+        if you need to differentiate the decompositions, consider using
+        [tridiag_sym][matfree.decomp.tridiag_sym] instead (if possible).
 
     """
 

matfree/lstsq.py

@@ -26,25 +26,38 @@ def lsmr(
 ):
     r"""Construct an experimental implementation of LSMR.
 
-    Follows the [implementation in SciPy](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.lsmr.html),
+    Follows the [SciPy's implementation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.lsmr.html),
     but uses JAX.
+    LSMR is due to Fong and Saunders (2011):
 
+    ??? note "BibTex for Fong and Saunders (2011)"
+        ```bibtex
+        @article{fong2011lsmr,
+            title={{LSMR}: An iterative algorithm for sparse least-squares problems},
+            author={Fong, David Chin-Lung and Saunders, Michael},
+            journal={SIAM Journal on Scientific Computing},
+            volume={33},
+            number={5},
+            pages={2950--2971},
+            year={2011},
+            publisher={SIAM}
+        }
+        ```
 
     Setting `custom_vjp` to `True` implies using the low-memory
     gradients of matrix-free least squares,
     according to what has been proposed by Roy et al. (2025).
     [Here](https://arxiv.org/abs/2510.19634) is a link to the preprint.
     These gradients are exact, so there is little reason not to use them.
-    If you use this configuration, please consider
-    citing Roy et al. (2025; bibtex below).
+    If you use this configuration, please cite Roy et al. (2025):
 
     ??? note "BibTex for Roy et al. (2025)"
         ```bibtex
         @article{roy2025matrix,
-        title={Matrix-Free Least Squares Solvers: Values, Gradients, and What to Do With Them},
-        author={Roy, Hrittik and Hauberg, S{\\o}ren and Kr{\"a}mer, Nicholas},
-        journal={arXiv preprint arXiv:2510.19634},
-        year={2025}
+            title={Matrix-Free Least Squares Solvers: Values, Gradients, and What to Do With Them},
+            author={Roy, Hrittik and Hauberg, S{\\o}ren and Kr{\"a}mer, Nicholas},
+            journal={arXiv preprint arXiv:2510.19634},
+            year={2025}
         }
         ```
     """