Trac #17447: Clarify and complete documentation of function()

The documentation of function() is incomplete and confusing.
For example, none of the methods described in http://www.sagemath.org/do
c/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.

URL: http://trac.sagemath.org/17447
Reported by: schymans
Ticket author(s): Nils Bruin, Ralf Stephan
Reviewer(s): Ralf Stephan, Nils Bruin

Author: Release Manager

src/doc/de/tutorial/tour_algebra.rst

@@ -153,7 +153,7 @@ berechnen. Die Gleichung :math:`x'+x-1=0` berechnen Sie wie folgt:
 ::
 
     sage: t = var('t')    # definiere die Variable t
-    sage: x = function('x',t)   # definiere x als Funktion dieser Variablen
+    sage: x = function('x')(t)   # definiere x als Funktion dieser Variablen
     sage: DE = diff(x, t) + x - 1
     sage: desolve(DE, [x,t])
     (_C + e^t)*e^(-t)

src/doc/en/constructions/calculus.rst

@@ -292,7 +292,7 @@ An example, how to solve ODE's symbolically in Sage using the Maxima interface
 
 ::
 
-    sage: y=function('y',x); desolve(diff(y,x,2) + 3*x == y, dvar = y, ics = [1,1,1])
+    sage: y=function('y')(x); desolve(diff(y,x,2) + 3*x == y, dvar = y, ics = [1,1,1])
     3*x - 2*e^(x - 1)
     sage: desolve(diff(y,x,2) + 3*x == y, dvar = y)
     _K2*e^(-x) + _K1*e^x + 3*x
@@ -301,7 +301,7 @@ An example, how to solve ODE's symbolically in Sage using the Maxima interface
     sage: desolve(diff(y,x) + 3*x == y, dvar = y, ics = [1,1]).expand()
     3*x - 5*e^(x - 1) + 3
 
-    sage: f=function('f',x); desolve_laplace(diff(f,x,2) == 2*diff(f,x)-f, dvar = f, ics = [0,1,2])
+    sage: f=function('f')(x); desolve_laplace(diff(f,x,2) == 2*diff(f,x)-f, dvar = f, ics = [0,1,2])
     x*e^x + e^x
 
     sage: desolve_laplace(diff(f,x,2) == 2*diff(f,x)-f, dvar = f)

src/doc/en/prep/Quickstarts/Differential-Equations.rst

@@ -21,7 +21,7 @@ Basic Symbolic Techniques
 
 ::
 
-    sage: y = function('y',x)
+    sage: y = function('y')(x)
     sage: de = diff(y,x) + y -2
     sage: h = desolve(de, y)
 
@@ -102,7 +102,7 @@ gives the last list in the example.
 
 ::
 
-    sage: f=function('f',x)
+    sage: f=function('f')(x)
     sage: desolve_laplace(diff(f,x,2) == 2*diff(f,x)-f, dvar = f, ics = [0,1,2])
     x*e^x + e^x
 
@@ -124,7 +124,7 @@ conditions.
 
 ::
 
-    sage: y = function('y',x)
+    sage: y = function('y')(x)
     sage: de = diff(y,x) + y -2
     sage: h = desolve_rk4(de, y, step=.05, ics=[0,3])
 

src/doc/en/tutorial/tour_algebra.rst

@@ -164,7 +164,7 @@ solve the equation :math:`x'+x-1=0`:
 ::
 
     sage: t = var('t')    # define a variable t
-    sage: x = function('x',t)   # define x to be a function of that variable
+    sage: x = function('x')(t)   # define x to be a function of that variable
     sage: DE = diff(x, t) + x - 1
     sage: desolve(DE, [x,t])
     (_C + e^t)*e^(-t)

src/doc/fr/tutorial/tour_algebra.rst

@@ -129,7 +129,7 @@ ordinaires. Pour résoudre l'équation :math:`x'+x-1=0` :
 ::
 
     sage: t = var('t')    # on définit une variable t
-    sage: function('x',t)   # on déclare x fonction de cette variable
+    sage: function('x')(t)   # on déclare x fonction de cette variable
     x(t)
     sage: DE = lambda y: diff(y,t) + y - 1
     sage: desolve(DE(x(t)), [x(t),t])

src/doc/ja/tutorial/tour_algebra.rst

@@ -164,7 +164,7 @@ Sageを使って常微分方程式を研究することもできる． :math:`x'
 ::
 
     sage: t = var('t')            # 変数 t を定義
-    sage: x = function('x',t)     # x を t の関数とする
+    sage: x = function('x')(t)     # x を t の関数とする
     sage: DE = diff(x, t) + x - 1
     sage: desolve(DE, [x,t])
     (_C + e^t)*e^(-t)

src/doc/pt/tutorial/tour_algebra.rst

@@ -151,7 +151,7 @@ ordinárias. Para resolver a equação :math:`x'+x-1=0`:
 ::
 
     sage: t = var('t')    # define a variable t
-    sage: x = function('x',t)   # define x to be a function of that variable
+    sage: x = function('x')(t)   # define x to be a function of that variable
     sage: DE = diff(x, t) + x - 1
     sage: desolve(DE, [x,t])
     (_C + e^t)*e^(-t)

src/doc/ru/tutorial/tour_algebra.rst

@@ -147,7 +147,7 @@ Sage может использоваться для решения диффер
 ::
 
     sage: t = var('t')    # определение переменной t для символьных вычислений
-    sage: x = function('x',t)   # определение функции x зависящей от t
+    sage: x = function('x')(t)   # определение функции x зависящей от t
     sage: DE = diff(x, t) + x - 1
     sage: desolve(DE, [x,t])
     (_C + e^t)*e^(-t)

src/sage/calculus/calculus.py

@@ -357,7 +357,7 @@
 Check to see that the problem with the variables method mentioned
 in :trac:`3779` is actually fixed::
 
-    sage: f = function('F',x)
+    sage: f = function('F')(x)
     sage: diff(f*SR(1),x)
     D[0](F)(x)
 
@@ -1271,7 +1271,7 @@ def laplace(ex, t, s):
 
     We do a formal calculation::
 
-        sage: f = function('f', x)
+        sage: f = function('f')(x)
         sage: g = f.diff(x); g
         D[0](f)(x)
         sage: g.laplace(x, s)
@@ -1297,8 +1297,8 @@ def laplace(ex, t, s):
         sage: var('t')
         t
         sage: t = var('t')
-        sage: x = function('x', t)
-        sage: y = function('y', t)
+        sage: x = function('x')(t)
+        sage: y = function('y')(t)
         sage: de1 = x.diff(t) + 16*y
         sage: de2 = y.diff(t) + x - 1
         sage: de1.laplace(t, s)
@@ -1424,7 +1424,7 @@ def at(ex, *args, **kwds):
 
         sage: var('s,t')
         (s, t)
-        sage: f=function('f', t)
+        sage: f=function('f')(t)
         sage: f.diff(t,2)
         D[0, 0](f)(t)
         sage: f.diff(t,2).laplace(t,s)
@@ -1521,7 +1521,7 @@ def dummy_diff(*args):
     Here the function is used implicitly::
 
         sage: a = var('a')
-        sage: f = function('cr', a)
+        sage: f = function('cr')(a)
         sage: g = f.diff(a); g
         D[0](cr)(a)
     """
@@ -1539,7 +1539,7 @@ def dummy_integrate(*args):
     EXAMPLES::
 
         sage: from sage.calculus.calculus import dummy_integrate
-        sage: f(x) = function('f',x)
+        sage: f = function('f')
         sage: dummy_integrate(f(x), x)
         integrate(f(x), x)
         sage: a,b = var('a,b')
@@ -1560,7 +1560,7 @@ def dummy_laplace(*args):
 
         sage: from sage.calculus.calculus import dummy_laplace
         sage: s,t = var('s,t')
-        sage: f(t) = function('f',t)
+        sage: f = function('f')
         sage: dummy_laplace(f(t),t,s)
         laplace(f(t), t, s)
     """
@@ -1575,7 +1575,7 @@ def dummy_inverse_laplace(*args):
 
         sage: from sage.calculus.calculus import dummy_inverse_laplace
         sage: s,t = var('s,t')
-        sage: F(s) = function('F',s)
+        sage: F = function('F')
         sage: dummy_inverse_laplace(F(s),s,t)
         ilt(F(s), s, t)
     """
@@ -1649,7 +1649,7 @@ def _laplace_latex_(self, *args):
         sage: from sage.calculus.calculus import _laplace_latex_
         sage: var('s,t')
         (s, t)
-        sage: f = function('f',t)
+        sage: f = function('f')(t)
         sage: _laplace_latex_(0,f,t,s)
         '\\mathcal{L}\\left(f\\left(t\\right), t, s\\right)'
         sage: latex(laplace(f, t, s))
@@ -1668,7 +1668,7 @@ def _inverse_laplace_latex_(self, *args):
         sage: from sage.calculus.calculus import _inverse_laplace_latex_
         sage: var('s,t')
         (s, t)
-        sage: F = function('F',s)
+        sage: F = function('F')(s)
         sage: _inverse_laplace_latex_(0,F,s,t)
         '\\mathcal{L}^{-1}\\left(F\\left(s\\right), s, t\\right)'
         sage: latex(inverse_laplace(F,s,t))
@@ -1731,7 +1731,7 @@ def symbolic_expression_from_maxima_string(x, equals_sub=False, maxima=maxima):
         sage: from sage.calculus.calculus import symbolic_expression_from_maxima_string as sefms
         sage: sefms('x^%e + %e^%pi + %i + sin(0)')
         x^e + e^pi + I
-        sage: f = function('f',x)
+        sage: f = function('f')(x)
         sage: sefms('?%at(f(x),x=2)#1')
         f(2) != 1
         sage: a = sage.calculus.calculus.maxima("x#0"); a

src/sage/calculus/desolvers.py

@@ -135,7 +135,7 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
     EXAMPLES::
 
         sage: x = var('x')
-        sage: y = function('y', x)
+        sage: y = function('y')(x)
         sage: desolve(diff(y,x) + y - 1, y)
         (_C + e^x)*e^(-x)
 
@@ -152,7 +152,7 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
     We can also solve second-order differential equations.::
 
         sage: x = var('x')
-        sage: y = function('y', x)
+        sage: y = function('y')(x)
         sage: de = diff(y,x,2) - y == x
         sage: desolve(de, y)
         _K2*e^(-x) + _K1*e^x - x
@@ -368,7 +368,7 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
 
     :trac:`9961` fixed (allow assumptions on the dependent variable in desolve)::
 
-        sage: y=function('y',x); assume(x>0); assume(y>0)
+        sage: y=function('y')(x); assume(x>0); assume(y>0)
         sage: sage.calculus.calculus.maxima('domain:real')  # needed since Maxima 5.26.0 to get the answer as below
         real
         sage: desolve(x*diff(y,x)-x*sqrt(y^2+x^2)-y == 0, y, contrib_ode=True)
@@ -388,7 +388,7 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
     :trac:`6479` fixed::
 
         sage: x = var('x')
-        sage: y = function('y', x)
+        sage: y = function('y')(x)
         sage: desolve( diff(y,x,x) == 0, y, [0,0,1])
         x
 
@@ -400,15 +400,15 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
     :trac:`9835` fixed::
 
         sage: x = var('x')
-        sage: y = function('y', x)
+        sage: y = function('y')(x)
         sage: desolve(diff(y,x,2)+y*(1-y^2)==0,y,[0,-1,1,1])
         Traceback (most recent call last):
         ...
         NotImplementedError: Unable to use initial condition for this equation (freeofx).
 
     :trac:`8931` fixed::
 
-        sage: x=var('x'); f=function('f',x); k=var('k'); assume(k>0)
+        sage: x=var('x'); f=function('f')(x); k=var('k'); assume(k>0)
         sage: desolve(diff(f,x,2)/f==k,f,ivar=x)
         _K1*e^(sqrt(k)*x) + _K2*e^(-sqrt(k)*x)
 
@@ -432,7 +432,7 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False)
     if is_SymbolicEquation(de):
         de = de.lhs() - de.rhs()
     if is_SymbolicVariable(dvar):
-        raise ValueError("You have to declare dependent variable as a function, eg. y=function('y',x)")
+        raise ValueError("You have to declare dependent variable as a function evaluated at the independent variable, eg. y=function('y')(x)")
     # for backwards compatibility
     if isinstance(dvar, list):
         dvar, ivar = dvar
@@ -550,7 +550,7 @@ def sanitize_var(exprs):
 ##     EXAMPLES:
 ##         sage: from sage.calculus.desolvers import desolve_laplace
 ##         sage: x = var('x')
-##         sage: f = function('f', x)
+##         sage: f = function('f')(x)
 ##         sage: de = lambda y: diff(y,x,x) - 2*diff(y,x) + y
 ##         sage: desolve_laplace(de(f(x)),[f,x])
 ##          #x*%e^x*(?%at('diff('f(x),x,1),x=0))-'f(0)*x*%e^x+'f(0)*%e^x
@@ -598,7 +598,7 @@ def desolve_laplace(de, dvar, ics=None, ivar=None):
 
     EXAMPLES::
 
-        sage: u=function('u',x)
+        sage: u=function('u')(x)
         sage: eq = diff(u,x) - exp(-x) - u == 0
         sage: desolve_laplace(eq,u)
         1/2*(2*u(0) + 1)*e^x - 1/2*e^(-x)
@@ -616,15 +616,15 @@ def desolve_laplace(de, dvar, ics=None, ivar=None):
 
     ::
 
-        sage: f=function('f', x)
+        sage: f=function('f')(x)
         sage: eq = diff(f,x) + f == 0
         sage: desolve_laplace(eq,f,[0,1])
         e^(-x)
 
     ::
 
         sage: x = var('x')
-        sage: f = function('f', x)
+        sage: f = function('f')(x)
         sage: de = diff(f,x,x) - 2*diff(f,x) + f
         sage: desolve_laplace(de,f)
         -x*e^x*f(0) + x*e^x*D[0](f)(0) + e^x*f(0)
@@ -639,7 +639,7 @@ def desolve_laplace(de, dvar, ics=None, ivar=None):
     Trac #4839 fixed::
 
         sage: t=var('t')
-        sage: x=function('x', t)
+        sage: x=function('x')(t)
         sage: soln=desolve_laplace(diff(x,t)+x==1, x, ics=[0,2])
         sage: soln
         e^(-t) + 1
@@ -670,7 +670,7 @@ def desolve_laplace(de, dvar, ics=None, ivar=None):
     if is_SymbolicEquation(de):
         de = de.lhs() - de.rhs()
     if is_SymbolicVariable(dvar):
-        raise ValueError("You have to declare dependent variable as a function, eg. y=function('y',x)")
+        raise ValueError("You have to declare dependent variable as a function evaluated at the independent variable, eg. y=function('y')(x)")
     # for backwards compatibility
     if isinstance(dvar, list):
         dvar, ivar = dvar
@@ -724,8 +724,8 @@ def desolve_system(des, vars, ics=None, ivar=None):
     EXAMPLES::
 
         sage: t = var('t')
-        sage: x = function('x', t)
-        sage: y = function('y', t)
+        sage: x = function('x')(t)
+        sage: y = function('y')(t)
         sage: de1 = diff(x,t) + y - 1 == 0
         sage: de2 = diff(y,t) - x + 1 == 0
         sage: desolve_system([de1, de2], [x,y])
@@ -748,16 +748,16 @@ def desolve_system(des, vars, ics=None, ivar=None):
     Check that :trac:`9823` is fixed::
 
         sage: t = var('t')
-        sage: x = function('x', t)
+        sage: x = function('x')(t)
         sage: de1 = diff(x,t) + 1 == 0
         sage: desolve_system([de1], [x])
         -t + x(0)
 
     Check that :trac:`16568` is fixed::
 
         sage: t = var('t')
-        sage: x = function('x', t)
-        sage: y = function('y', t)
+        sage: x = function('x')(t)
+        sage: y = function('y')(t)
         sage: de1 = diff(x,t) + y - 1 == 0
         sage: de2 = diff(y,t) - x + 1 == 0
         sage: des = [de1,de2]
@@ -783,8 +783,8 @@ def desolve_system(des, vars, ics=None, ivar=None):
 
         sage: t = var('t')
         sage: epsilon = var('epsilon')
-        sage: x1 = function('x1', t)
-        sage: x2 = function('x2', t)
+        sage: x1 = function('x1')(t)
+        sage: x2 = function('x2')(t)
         sage: de1 = diff(x1,t) == epsilon
         sage: de2 = diff(x2,t) == -2
         sage: desolve_system([de1, de2], [x1, x2], ivar=t)
@@ -1156,7 +1156,7 @@ def desolve_rk4(de, dvar, ics=None, ivar=None, end_points=None, step=0.1, output
     desolve function In this example we integrate bakwards, since
     ``end_points < ics[0]``::
 
-        sage: y=function('y',x)
+        sage: y=function('y')(x)
         sage: desolve_rk4(diff(y,x)+y*(y-1) == x-2,y,ics=[1,1],step=0.5, end_points=0)
         [[0.0, 8.904257108962112], [0.5, 1.909327945361535], [1, 1]]