DOC: document default argument values for some arpack functions

[argriffing]

closes #3829

[coveralls]

Coverage remained the same when pulling 5b7d002 on argriffing:arpack-default-docstrings into 8741fe1 on scipy:master.

[argriffing]

TravisCI had two errored configurations. One failed to download dependencies, and another stalled for 10min during a test.

[rgommers]

this change, and similar ones below, aren't right. The type descriptor should use the actual type here (except if it's array_like), so int and not integer. See section 4 under https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections

[argriffing]

I've seen both ways, so I was just guessing. Does integer have any meaning? For example hypothetically it might be more flexible allowing int and np.int16 and whatever else acts like an integer, whereas int might hypothetically mean exactly Python int type. If not then I'll change them all to int.

[argriffing]

changed this back to int, and made some more integer->int changes.

[rgommers]

No, integer doesn't have an extended meaning. In a sentence in the parameter description you would use integer (because it's a normal word) and in the type descriptor you always use int.

[coveralls]

Coverage increased (+0.03%) when pulling 9ce88c6 on argriffing:arpack-default-docstrings into 8741fe1 on scipy:master.

[rgommers]

Looks to me like default is all zeros, not random. See v0 handling in _ArpackParams.

[rgommers]

Same comment for v0 in other two functions below.

[rgommers]

ncv and maxiter look correct to me.

Could you squash the commits after updating?

[argriffing]

Looks to me like default is all zeros, not random. See v0 handling in _ArpackParams.

Are you sure? I remember having thought the same thing as well, and having spent a lot of time considering this possibility, and concluding that it's actually random and not zeros. I remember having tested this by feeding a v0 that was like np.zeros and this resulted in an exception like "error v0 is all zeros". I think there's a deeper layer that uses a random initial vector if v0 is unspecified at the scipy level.

[rgommers]

I didn't test, just followed the code. It seems simple enough. The only placev0 is used is in lines 317-322:

    if v0 is not None:
        # ARPACK overwrites its initial resid,  make a copy
        self.resid = np.array(v0, copy=True)
        info = 1
    else:
        self.resid = np.zeros(n, tp)
        info = 0

Feeding in v0 = np.zeros(n, tp) should not give you an exception I'd think.

EDIT: or it depends on the info flag.

[rgommers]

Indeed, you are right. A comment behind info = 0 in arpack.py wouldn't hurt.

[rgommers]

Comment in dsaupd.f:

c  INFO    Integer.  (INPUT/OUTPUT)
c          If INFO .EQ. 0, a randomly initial residual vector is used.
c          If INFO .NE. 0, RESID contains the initial residual vector,
c                          possibly from a previous run.

[argriffing]

EDIT: or it depends on the info flag.

Yes I spent some time tracking through the arpack maze, and I think it uses the info flag, eventually using a random initial vector. If you try to give it zeros directly, it tells you to use a more useful initial vector.

[argriffing]

Could you squash the commits after updating?

I think I've done this. It was scary using the force flag in git push -f so I hope it's not screwed up.

[argriffing]

A comment behind info = 0 in arpack.py wouldn't hurt.

Added in the squashed commit.

[coveralls]

Coverage remained the same when pulling e539378 on argriffing:arpack-default-docstrings into 47137df on scipy:master.

[coveralls]

Coverage remained the same when pulling e539378 on argriffing:arpack-default-docstrings into 47137df on scipy:master.

[rgommers]

Thanks, merging.