Clarify and complete documentation of function()

[sagetrac-schymans]

The documentation of function() is incomplete and confusing.
For example, none of the methods described in http://www.sagemath.org/doc/reference/calculus/sage/symbolic/function_factory.html show up when I type:

function?

The distinction between

f = function('f')

and

f = function('f', x)

is also not documented. See also #17445 for sources of confusion. Need to explain what happens in the second case above (f = function('f',x)). A symbolic function f is first created and then overwritten by the expression f?
See the following example, where f is first an expression, then becomes redefined to a function in the background, but does not contain any information about its variables.

sage: f = function('f', x); print type(f)
<type 'sage.symbolic.expression.Expression'>
sage: fx = function('f',x); print type(f)
<class 'sage.symbolic.function_factory.NewSymbolicFunction'>
sage: f.variables()
()
sage: fx.variables()
(x,)

See http://ask.sagemath.org/question/9932/how-to-substitute-a-function-within-derivatives/?answer=14752#post-id-14752 for a possible start at how to explain this, at least for those writing this.

CC: @nbruin @kcrisman @sagetrac-tmonteil @zimmermann6

Component: documentation

Author: Nils Bruin, Ralf Stephan

Branch/Commit: 7c029f3

Reviewer: Ralf Stephan, Nils Bruin

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

[kcrisman]

Description changed:

--- 
+++ 
@@ -14,7 +14,7 @@
 ```
 f = function('f', x)
 ```
-is also not documented. See also https://github.com/sagemath/sage-prod/issues/17445 for sources of confusion. Need to explain what happens in the second case above (`f = function('f',x)`). A symbolic function `f` is first created and then overwritten by the expression `f`?
+is also not documented. See also #17445 for sources of confusion. Need to explain what happens in the second case above (`f = function('f',x)`). A symbolic function `f` is first created and then overwritten by the expression `f`?
 See the following example, where f is first an expression, then becomes redefined to a function in the background, but does not contain any information about its variables. 
 
 ```

[kcrisman]

Description changed:

--- 
+++ 
@@ -29,3 +29,4 @@
 
 ```
 
+See http://ask.sagemath.org/question/9932/how-to-substitute-a-function-within-derivatives/?answer=14752#post-id-14752 for a possible start at how to explain this, at least for those writing this.

[nbruin]

comment:3

For the question about creation and overwriting:

The toplevel function has the sideeffect of inserting a binding in the global scope, just as the toplevel var does.

sage: var('U')
U
sage: U
U
sage: function('f')
f
sage: f
f

The library versions of these routines don't do that:

sage: SR.var('V')
V
sage: V
NameError: name 'V' is not defined
sage: sage.symbolic.function_factory.function('g')
g
sage: g
NameError: name 'g' is not defined

The intended use of the toplevel function is not to be assigned but to be called as a statement, just as var. There is plenty of documentation in sage that was written by people unaware of this fact (or possibly they think they're being helpful by providing code that doesn't return an error when used with the library versions of these functions)

As a result x=var('x') and fx=function('f',x) are quite ubiquitous in the docs. The former is fairly inocuous but the second, as you experience, has a rather nasty side effect. We're violating python's convention here: routines with side effects should return None.

I think this is the point where people usually give up fixing this mess (I have). Hopefully you will now follow through.

Note that we can probably not do more than document the issues, which is not going to fix much, because people won't read the doc, but then at least you can point them somewhere when they complain.

I suspect that Zimmerman's calculus book uses this stuff quite extensively, so deprecating/changing the current behaviour will likely lead to pushback from him, and probably rightly so.

(this is the kind of issue that earns sage the reputation of "implement now, design later")

[sagetrac-schymans]

comment:5

Awesome, thank you, Nils. These things always confused me, so I'm relieved to hear that they should be avoided! Even the documentation of var is full of such examples:

sage: x = var('x', domain=RR); x; x.conjugate()
x
x
sage: y = var('y', domain='real'); y.conjugate()
y
sage: y = var('y', domain='positive'); y.abs()
y

Custom latex expression can be assigned to variable:

sage: x = var('sui', latex_name="s_{u,i}"); x._latex_()
's_{u,i}'

Should we change these examples, too?

[nbruin]

Branch: u/nbruin/clarify_and_complete_documentation_of_function__

[nbruin]

comment:6

Don't base any other work on this branch just yet, since it's likely to be rebased. I have deprecated the use of function('f',x) in favour of using function('f')(x). It's hardly longer to type and much less ambiguous. Otherwise, it seems that the documentation here is actually pretty accurate, apart from being terse. As soon as the objects returned by function('f') are consistent, I think users will be forced to learn the (now clear) semantics pretty quickly.

The object returned by function(f) doesn't allow symbolic operations on it, so people will quickly find they need to evaluate it in order to get a symbolic expression.

I haven't changed all doctests to take into account the deprecation, but I've done some files to show the impact of the change (seems relatively minor).

[nbruin]

Commit: fa3ebd6

[nbruin]

comment:7

Not really ready for review but is ready for input. And is mainly ready for someone else to rewrite documentation properly. People CC'd on this ticket look like good candidates to do so.

---

New commits:

b41248b	trac 17447: Deprecation of function('f',x) in favour of function('f')(x)
fa3ebd6	trac 17447: Doctest changes to reflect deprecation of function('f',x)

---

note that the doctest that apparently got removed in b41248b in reality gets moved to var.pyx because it tests the toplevel function, not the library function