Minor docs changes for functions like minimize() which have same handle in Python and SAGE

[sagetrac-GaryMak]

As a very inexperienced person in this field I found it very difficult from the existing docs to understand the difference in syntax between the python and sage functions "minimize" - and I imagine this applies to other function handles as well: though I will need some guidance as to which function specs I need to amend.

---

See this sage-support discussion:

vars = var('x y')
def gg(x,y): return sin(x) + cos(y)
minimize(gg,[0,0])

gives a TypeError, while

vars = var('x y')
gg = sin(x) + cos(y)
minimize(gg,[0,0])

doesn't, but

sage: def gg(x): return sin(x[0]) + cos(x[1]) 
sage: minimize(gg,[0,0]) 
Optimization terminated successfully. 
          Current function value: -2.000000 
          Iterations: 72 
          Function evaluations: 139 
(-1.5707636272, 3.14159570731) 

does.

The relevant possibly confusing doc is here.

CC: @mforets @dimpase

Component: documentation

Issue created by migration from https://trac.sagemath.org/ticket/14493

[mforets]

comment:7

assuming that this ticket is for documentation only (not for the feature itself), i find that the docstring is currently well and clear in this respect.

this is because it says:

    INPUT:

    - ``func`` -- Either a symbolic function or a Python function whose
      argument is a tuple with `n` components

for this reason i suggest to either close this ticket, or to add an extra note:

- If you use a Python function, the argument must be a tuple with `n` components, e.g. 
``def func(x): return sin(x[0]) + cos(x[1])`` instead of ``def func(x,y): return sin(x) + cos(y)``.

[kcrisman]

comment:8

The latter seems good, because I wouldn't have figured out that syntax from no example.