Repository: scipy/scipy
Pull request: DOC: sparse.linalg: add note about complex matrices to `splu` and `spilu`
<!-- 
Thanks for contributing a pull request! Please ensure that
your PR satisfies the checklist before submitting:
https://scipy.github.io/devdocs/dev/contributor/development_workflow.html#checklist-before-submitting-a-pr

Also, please name and describe your PR as you would write a
commit message:
https://scipy.github.io/devdocs/dev/contributor/development_workflow.html#writing-the-commit-message.
However, please only include an issue number in the description, not the title,
and please ensure that any code names containing underscores are enclosed in backticks.

Depending on your changes, you can skip CI operations and save time and energy: 
https://scipy.github.io/devdocs/dev/contributor/continuous_integration.html#skipping

Note that we are a team of volunteers; we appreciate your
patience during the review process.

Again, thanks for contributing!
-->

#### Reference issue
Closes #8140 

Problem statement:
sparse LU decomposition does not solve with complex right-hand side
The `solve` method of the sparse LU-decomposition `splu` or `spilu` throws a `TypeError` if called with a `numpy.array` of type `numpy.complex`. I am actually using `spilu` for preconditioning a gmres-solver required to perform a linear solve in a non-symmetric generalized eigenvalue problem. The eigenvectors are complex and hence the right-hand side for the linear solve can be complex.

### Reproducing code example:
```
import numpy as np
from scipy.sparse import csr_matrix
import scipy.sparse.linalg as sp_sparse_la

A = csr_matrix([[2.,-1.],[-1.,2.]])
n = A.shape[0]

v_real = np.random.randn(n)
v_cmplx = np.random.randn(n) + 1.0J * np.random.randn(n)

luA = sp_sparse_la.splu(A)
x_real = luA.solve(v_real)
x_cmplx = luA.solve(v_cmplx)
```

### Error message:
```
Traceback (most recent call last):
  File "dump.py", line 20, in <module>
    x_cmplx = luA.solve(v_cmplx)
TypeError: Cannot cast array data from dtype('complex128') to dtype('float64') according to the rule 'safe'
```

### Scipy/Numpy/Python version information:
```
('1.0.0', '1.13.3', sys.version_info(major=2, minor=7, micro=12, releaselevel='final', serial=0))
```

Hints from issue discussion:
if you cast your A matrix as complex, then it works in both cases. So probably when the LHS is real it selects a real-typed solver and complains.
Thank you, you are right. Maybe some comments regarding this issue should be added in the documentation.
Good first issue, depending on familiarity with the math.
Hi I'm working on it I'll try to do it by the end of next week
A note such as the following in the docstring of `splu` and `spilu` would close this issue

````When a real array is factorized and the returned SuperLU object ``solve()`` method is used with complex arguments an error is generated. Instead cast the initial matrix to complex and then factorize.````
Hi @j-bowhay, thanks for the comment, I am a first-time contributor to scipy, I would like to start from this issue
We don't assign issues to specific people but please feel free to have a go

Commit message: Fix linting failure

Patch to review:
diff --git a/scipy/sparse/linalg/_dsolve/linsolve.py b/scipy/sparse/linalg/_dsolve/linsolve.py
index d1ab77883163..49b0ce10ff82 100644
--- a/scipy/sparse/linalg/_dsolve/linsolve.py
+++ b/scipy/sparse/linalg/_dsolve/linsolve.py
@@ -371,6 +371,10 @@ def splu(A, permc_spec=None, diag_pivot_thresh=None,
 
     Notes
     -----
+    When a real array is factorized and the returned SuperLU object ``solve()`` method 
+    is used with complex arguments an error is generated. Instead cast the initial
+    matrix to complex and then factorize.
+
     This function uses the SuperLU library.
 
     References
@@ -468,6 +472,10 @@ def spilu(A, drop_tol=None, fill_factor=None, drop_rule=None, permc_spec=None,
 
     Notes
     -----
+    When a real array is factorized and the returned SuperLU object ``solve()`` method
+    is used with complex arguments an error is generated. Instead cast the initial 
+    matrix to complex and then factorize.
+
     To improve the better approximation to the inverse, you may need to
     increase `fill_factor` AND decrease `drop_tol`.
 


Code review comments:
diff_hunk: @@ -371,6 +371,10 @@ def splu(A, permc_spec=None, diag_pivot_thresh=None,
 
     Notes
     -----
+    When a real array is factorized and the returned SuperLU object ``solve()`` method 
+    is used with complex arguments an error is generated. Instead cast the initial
path: scipy/sparse/linalg/_dsolve/linsolve.py
text: @user1:
```suggestion
    is used with complex arguments an error is generated. Instead, cast the initial
```

diff_hunk: @@ -371,6 +371,10 @@ def splu(A, permc_spec=None, diag_pivot_thresh=None,
 
     Notes
     -----
+    When a real array is factorized and the returned SuperLU object ``solve()`` method 
+    is used with complex arguments an error is generated. Instead cast the initial
+    matrix to complex and then factorize.
path: scipy/sparse/linalg/_dsolve/linsolve.py
text: @user1:
```suggestion
    array to complex and then factorize.
```