Repository: scipy/scipy

Issue:
Please add citations to the papers for COLAMD
scipy includes COLAMD as a built-in function (used by SuperLU) but the relevant papers are missing from the documentation.

In particular:

        T. A. Davis, J. R. Gilbert, S. Larimore, E. Ng, Algorithm 836:  COLAMD,
        an approximate column minimum degree ordering algorithm, ACM Trans. on
        Mathematical Software, 30(3), 2004, pp. 377--380.
        https://doi.org/10.1145/1024074.1024080

        T. A. Davis, J. R. Gilbert, S. Larimore, E. Ng, A column approximate
        minimum degree ordering algorithm, ACM Trans. on Mathematical Software,
        30(3), 2004, pp. 353--376.
        https://doi.org/10.1145/1024074.1024079

If there are other codes used from SuiteSparse, please see this list for other papers to cite in the documentation:
 https://github.com/DrTimothyAldenDavis/SuiteSparse#how-to-cite-the-suitesparse-meta-package-and-its-component-packages




Discussion:
Thank you for the reminder Tim, references are added to places that we hope to cover all. But please let us know if we missed any other usage with other library components too. 
Thanks!  I also posted other issues for scikit-sparse and scikit-umfpack, which is where most of my packages are wrapped for scipy, from what I understand.
Hi @DrTimothyAldenDavis, @ilayn and @melissawm,
I'd like to contribute to this issue, and want to make sure that my work is correct. From my understanding, I would be replicating the documentation from this [commit](https://github.com/scipy/scipy/pull/15938/files/26773940bf968173a2fc7b96d96cff79c0c5eaf7), but for any C or Python files from this [search](https://github.com/scipy/scipy/search?q=COLAMD) that include COLAMD with no citation ([Example file which I think should be changed](https://github.com/scipy/scipy/blob/8a64c938ddf1ae4c02a08d2c5e38daeb8d061d38/scipy/sparse/linalg/_dsolve/SuperLU/SRC/cgssv.c))

Please let me know if this approach is correct so I can begin moving forward with the issue.
Thanks
You don’t have to change cgssv.c.


@L-Sandler another place these references can be added is `sparse.linalg.splu`. Please follow the example set by gh-15938. Thanks for your interest!

To completely resolve this issue, I'd suggest searching SciPy source code for the names of each [SuiteSparse](https://github.com/DrTimothyAldenDavis/SuiteSparse) component package and adding appropriate references to the public documentation of the functions in which they are used. Really, only the SuiteSparse packages that are permissively licensed (e.g. [BSD](https://github.com/DrTimothyAldenDavis/SuiteSparse/blob/master/CCOLAMD/Doc/License.txt)) need to be checked, as we should not have any packages released with incompatible licenses (e.g. [GPL](https://github.com/DrTimothyAldenDavis/SuiteSparse/blob/master/SPQR/Doc/gpl.txt)) in SciPy. 
Thanks for your responses @mdhaber and @DrTimothyAldenDavis. 
@mdhaber is there any chance you can direct me to the correct location for `sparse.linalg.splu` as [the one I've interpreted from your reply](https://github.com/scipy/scipy/tree/main/scipy/sparse/linalg/splu) does not exist for me. 

@DrTimothyAldenDavis is there any chance you can explain why no citation is necessary for `cgssv.c` although COLAMD is referenced on [line 199](https://github.com/scipy/scipy/blob/8a64c938ddf1ae4c02a08d2c5e38daeb8d061d38/scipy/sparse/linalg/_dsolve/SuperLU/SRC/cgssv.c#L199)? It would be helpful for discerning whether or not references should be added for any others that come up as I'm searching through SciPy.

I appreciate your help and am looking forward to hopefully solving this issue.
Thanks for all your help on this issue.  All that is really needed are
citations in the documentation, not in the various source codes (such as
SuperLU).  There's no need to cite colamd in superlu itself, just in the
user-facing documentation of scipy where the user is given the option to
use colamd.

The SuperLU papers themselves cite COLAMD, so SuperLU (by Sherry Li)
already cites COLAMD just fine.  That's already taken care of.


From what I can tell after downloading scipy and doing a search, is that scipy proper includes only COLAMD.  All of my other codes are wrapped in scikit-sparse and scikit-umfpack.  See:

https://github.com/scikit-sparse/scikit-sparse/issues/75
https://github.com/scikit-umfpack/scikit-umfpack/issues/69

UMFPACK is not in scipy proper, but there is a mention of UMFPACK in this file in scipy:
https://github.com/scipy/scipy/blob/main/scipy/sparse/linalg/_dsolve/linsolve.py
I suppose a cite to an UMFPACK paper could be added there, unless the user is expected to look at the scikit-umfpack documentation for details (where UMFPACK should be cited).  I'm OK either way, however you prefer to cite the codes used in scipy.

Thanks again for your quick response!



@L-Sandler you can usually find where a function lives by clicking on the `[source]` link from the function's documentation. E.g. the documentation for `splu` is [here](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.splu.html#scipy.sparse.linalg.splu) and looks like:
![image](https://user-images.githubusercontent.com/6570539/161866242-132bb32e-c768-403e-a99e-bcc5b4de8f51.png)

Clicking `source` at the right takes you to the location of the documentation in `scipy/sparse/linalg/_dsolve/linsolve.py`. That works here, but there are some times that may not work. In those cases, I'd suggest searching the code on your machine for the name of the function or class (e.g. `def splu`).
Hi there. I've tried a variety of resources from the SciPy documentation, including the detailed guide for [MacOS](https://docs.scipy.org/doc/scipy/dev/contributor/quickstart_mac.html#quickstart-mac), to try and set my environment correctly but am unable to build without errors. I've taken multiple steps like reinstalling my command line tools and reinstalling conda without success. Can anyone suggest any next steps for me? 

Apologies for the delay in resolving this issue as I'm still learning about open source development. Looking forward to moving past this and resolving the issue. Thank you for your patience.
That link is to the 1.8.1 documentation. There have been major updates to the build setup recently, so you might have better luck with the development version of the [contributor guide](http://scipy.github.io/devdocs/dev/contributor/contributor_toc.html). In theory, the [conda development guide](http://scipy.github.io/devdocs/dev/contributor/conda_guide.html#conda-guide) should "just work" for you on MacOS.

Resolving patch:
diff --git a/scipy/sparse/linalg/_dsolve/linsolve.py b/scipy/sparse/linalg/_dsolve/linsolve.py
--- a/scipy/sparse/linalg/_dsolve/linsolve.py
+++ b/scipy/sparse/linalg/_dsolve/linsolve.py
@@ -33,24 +33,46 @@ def use_solver(**kwargs):
     Parameters
     ----------
     useUmfpack : bool, optional
-        Use UMFPACK over SuperLU. Has effect only if scikits.umfpack is
-        installed. Default: True
+        Use UMFPACK [1]_, [2]_, [3]_, [4]_. over SuperLU. Has effect only
+        if ``scikits.umfpack`` is installed. Default: True
     assumeSortedIndices : bool, optional
         Allow UMFPACK to skip the step of sorting indices for a CSR/CSC matrix.
-        Has effect only if useUmfpack is True and scikits.umfpack is installed.
-        Default: False
+        Has effect only if useUmfpack is True and ``scikits.umfpack`` is
+        installed. Default: False
 
     Notes
     -----
-    The default sparse solver is umfpack when available
-    (scikits.umfpack is installed). This can be changed by passing
+    The default sparse solver is UMFPACK when available
+    (``scikits.umfpack`` is installed). This can be changed by passing
     useUmfpack = False, which then causes the always present SuperLU
     based solver to be used.
 
-    Umfpack requires a CSR/CSC matrix to have sorted column/row indices. If
+    UMFPACK requires a CSR/CSC matrix to have sorted column/row indices. If
     sure that the matrix fulfills this, pass ``assumeSortedIndices=True``
     to gain some speed.
 
+    References
+    ----------
+    .. [1] T. A. Davis, Algorithm 832:  UMFPACK - an unsymmetric-pattern
+           multifrontal method with a column pre-ordering strategy, ACM
+           Trans. on Mathematical Software, 30(2), 2004, pp. 196--199.
+           https://dl.acm.org/doi/abs/10.1145/992200.992206
+
+    .. [2] T. A. Davis, A column pre-ordering strategy for the
+           unsymmetric-pattern multifrontal method, ACM Trans.
+           on Mathematical Software, 30(2), 2004, pp. 165--195.
+           https://dl.acm.org/doi/abs/10.1145/992200.992205
+
+    .. [3] T. A. Davis and I. S. Duff, A combined unifrontal/multifrontal
+           method for unsymmetric sparse matrices, ACM Trans. on
+           Mathematical Software, 25(1), 1999, pp. 1--19.
+           https://doi.org/10.1145/305658.287640
+
+    .. [4] T. A. Davis and I. S. Duff, An unsymmetric-pattern multifrontal
+           method for sparse LU factorization, SIAM J. Matrix Analysis and
+           Computations, 18(1), 1997, pp. 140--158.
+           https://doi.org/10.1137/S0895479894246905T.
+
     Examples
     --------
     >>> from scipy.sparse.linalg import use_solver, spsolve
@@ -120,8 +142,9 @@ def spsolve(A, b, permc_spec=None, use_umfpack=True):
         - ``COLAMD``: approximate minimum degree column ordering [1]_, [2]_.
 
     use_umfpack : bool, optional
-        if True (default) then use umfpack for the solution.  This is
-        only referenced if b is a vector and ``scikit-umfpack`` is installed.
+        if True (default) then use UMFPACK for the solution [3]_, [4]_, [5]_,
+        [6]_ . This is only referenced if b is a vector and
+        ``scikits.umfpack`` is installed.
 
     Returns
     -------
@@ -149,6 +172,27 @@ def spsolve(A, b, permc_spec=None, use_umfpack=True):
            minimum degree ordering algorithm, ACM Trans. on Mathematical
            Software, 30(3), 2004, pp. 353--376. :doi:`10.1145/1024074.1024079`
 
+    .. [3] T. A. Davis, Algorithm 832:  UMFPACK - an unsymmetric-pattern
+           multifrontal method with a column pre-ordering strategy, ACM
+           Trans. on Mathematical Software, 30(2), 2004, pp. 196--199.
+           https://dl.acm.org/doi/abs/10.1145/992200.992206
+
+    .. [4] T. A. Davis, A column pre-ordering strategy for the
+           unsymmetric-pattern multifrontal method, ACM Trans.
+           on Mathematical Software, 30(2), 2004, pp. 165--195.
+           https://dl.acm.org/doi/abs/10.1145/992200.992205
+
+    .. [5] T. A. Davis and I. S. Duff, A combined unifrontal/multifrontal
+           method for unsymmetric sparse matrices, ACM Trans. on
+           Mathematical Software, 25(1), 1999, pp. 1--19.
+           https://doi.org/10.1145/305658.287640
+
+    .. [6] T. A. Davis and I. S. Duff, An unsymmetric-pattern multifrontal
+           method for sparse LU factorization, SIAM J. Matrix Analysis and
+           Computations, 18(1), 1997, pp. 140--158.
+           https://doi.org/10.1137/S0895479894246905T.
+
+
     Examples
     --------
     >>> from scipy.sparse import csc_matrix


Test patch: