Ticket #9879: trac_9879-hold-review.patch

File trac_9879-hold-review.patch, 38.8 KB (added by Karl-Dieter Crisman, 12 years ago)

Apply after initial patch

  • sage/functions/hyperbolic.py

    # HG changeset patch
    # User Karl-Dieter Crisman <kcrisman@gmail.com>
    # Date 1286204449 14400
    # Node ID 7a046048d2c46dfb148d36888169928661c9ba60
    # Parent  a975651fae5c7ea069e6bd8284d1d474bc16ca20
    Trac 9879 - reviewer patch.
    
    Mostly adds documentation that functional notation does/doesn't work and how to 'unhold'; adds some other minor fixes.
    
    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/hyperbolic.py
    a b  
    8585
    8686            sage: latex(sinh(x))
    8787            \sinh\left(x\right)
     88
     89        To prevent automatic evaluation, use the ``hold`` parameter::
     90
     91            sage: sinh(arccosh(x),hold=True)
     92            sinh(arccosh(x))
     93
     94        To then evaluate again, we currently must use Maxima via
     95        :meth:`sage.symbolic.expression.Expression.simplify`::
     96
     97            sage: sinh(arccosh(x),hold=True).simplify()
     98            sqrt(x - 1)*sqrt(x + 1)
     99
    88100        """
    89101        GinacFunction.__init__(self, "sinh", latex_name=r"\sinh")
    90102
     
    108120
    109121            sage: latex(cosh(x))
    110122            \cosh\left(x\right)
     123
     124        To prevent automatic evaluation, use the ``hold`` parameter::
     125
     126            sage: cosh(arcsinh(x),hold=True)
     127            cosh(arcsinh(x))
     128
     129        To then evaluate again, we currently must use Maxima via
     130        :meth:`sage.symbolic.expression.Expression.simplify`::
     131
     132            sage: cosh(arcsinh(x),hold=True).simplify()
     133            sqrt(x^2 + 1)
     134
    111135        """
    112136        GinacFunction.__init__(self, "cosh", latex_name=r"\cosh")
    113137
     
    143167            sage: CDF(tanh(pi + I*e))
    144168            0.997524731976 - 0.002790687681*I       
    145169
     170        To prevent automatic evaluation, use the ``hold`` parameter::
     171
     172            sage: tanh(arcsinh(x),hold=True)
     173            tanh(arcsinh(x))
     174
     175        To then evaluate again, we currently must use Maxima via
     176        :meth:`sage.symbolic.expression.Expression.simplify`::
     177
     178            sage: tanh(arcsinh(x),hold=True).simplify()
     179            x/sqrt(x^2 + 1)
     180
    146181        TESTS::
    147182           
    148183            sage: latex(tanh(x))
     
    295330csch = Function_csch()
    296331
    297332
    298 ##########################
    299 # Inverse trig functions #
    300 ##########################
     333################################
     334# Inverse hyperbolic functions #
     335################################
    301336       
    302337class Function_arcsinh(GinacFunction):
    303338    def __init__(self):
     
    315350            sage: arcsinh(1 + I*1.0)
    316351            1.06127506190504 + 0.666239432492515*I
    317352
     353        To prevent automatic evaluation use the ``hold`` argument::
     354
     355            sage: arcsinh(-2,hold=True)
     356            arcsinh(-2)
     357
     358        To then evaluate again, we currently must use Maxima via
     359        :meth:`sage.symbolic.expression.Expression.simplify`::
     360
     361            sage: arcsinh(-2,hold=True).simplify()
     362            -arcsinh(2)
     363
    318364        TESTS::
    319365
    320366            sage: arcsinh(x).operator()
     
    343389            sage: cosh(float(arccosh(2)))
    344390            2.0
    345391
    346         Warning: If the input is real the output will be real or NaN::
     392        .. warning::
     393
     394            If the input is in the complex field or symbolic (which
     395            includes rational and integer input), the output will
     396            be complex.  However, if the input is a real decimal, the
     397            output will be real or `NaN`.  See the examples for details.
     398
     399        ::
    347400
    348401            sage: arccosh(0.5)
    349402            NaN
    350 
    351         But evaluation where the input is in the complex field yields a
    352         complex output::
    353 
     403            sage: arccosh(1/2)
     404            arccosh(1/2)
     405            sage: arccosh(1/2).n()
     406            NaN
    354407            sage: arccosh(CC(0.5))
    355408            1.04719755119660*I
     409            sage: arccosh(0)
     410            1/2*I*pi
     411            sage: arccosh(-1)
     412            I*pi
     413
     414        To prevent automatic evaluation use the ``hold`` argument::
     415
     416            sage: arccosh(-1,hold=True)
     417            arccosh(-1)
     418
     419        To then evaluate again, we currently must use Maxima via
     420        :meth:`sage.symbolic.expression.Expression.simplify`::
     421
     422            sage: arccosh(-1,hold=True).simplify()
     423            I*pi
    356424
    357425        TESTS::
    358426
     
    380448            sage: arctanh(1 + I*1.0)
    381449            0.402359478108525 + 1.01722196789785*I
    382450
     451        To prevent automatic evaluation use the ``hold`` argument::
     452
     453            sage: arctanh(-1/2,hold=True)
     454            arctanh(-1/2)
     455
     456        To then evaluate again, we currently must use Maxima via
     457        :meth:`sage.symbolic.expression.Expression.simplify`::
     458
     459            sage: arctanh(-1/2,hold=True).simplify()
     460            -arctanh(1/2)
     461
    383462        TESTS::
    384463
    385464            sage: arctanh(x).operator()
  • sage/functions/log.py

    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/log.py
    a b  
    3131            sage: exp(RDF('2.5'))
    3232            12.1824939607
    3333
     34        To prevent automatic evaluation, use the ``hold`` parameter::
     35
     36            sage: exp(I*pi,hold=True)
     37            e^(I*pi)
     38            sage: exp(0,hold=True)
     39            e^0
     40
     41        To then evaluate again, we currently must use Maxima via
     42        :meth:`sage.symbolic.expression.Expression.simplify`::
     43
     44            sage: exp(0,hold=True).simplify()
     45            1
     46
    3447        ::
    3548
    3649            sage: exp(pi*I/2)
     
    5770
    5871        Test simplifications when taking powers of exp, #7264::
    5972
    60             sage: var('a,b,c,I')
    61             (a, b, c, I)
    62             sage: model_exp = exp(I)**a*(b)
     73            sage: var('a,b,c,II')
     74            (a, b, c, II)
     75            sage: model_exp = exp(II)**a*(b)
    6376            sage: sol1_l={b: 5.0, a: 1.1}
    6477            sage: model_exp.subs(sol1_l)
    65             5.00000000000000*(e^I)^1.10000000000000
     78            5.00000000000000*(e^II)^1.10000000000000
    6679
    6780        ::
    6881
    69             sage: exp(3)^I*exp(x)
    70             (e^3)^I*e^x
     82            sage: exp(3)^II*exp(x)
     83            (e^3)^II*e^x
    7184            sage: exp(x)*exp(x)
    7285            e^(2*x)
    7386            sage: exp(x)*exp(a)
     
    141154            sage: ln(complex(-1))
    142155            3.1415926535897931j
    143156
     157        We do not currently support a ``hold`` parameter in functional
     158        notation::
     159
     160            sage: log(SR(-1),hold=True)
     161            Traceback (most recent call last):
     162            ...
     163            TypeError: log() got an unexpected keyword argument 'hold'
     164
     165        This is possible with method notation::
     166
     167            sage: I.log(hold=True)
     168            log(I)
     169            sage: I.log(hold=True).simplify()
     170            1/2*I*pi
     171
    144172        TESTS::
    145173
    146174            sage: latex(x.log())
  • sage/functions/other.py

    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/other.py
    a b  
    510510            sage: gamma1(int(5))
    511511            24
    512512
     513        ::
    513514
    514515            sage: plot(gamma1(x),(x,1,5))
    515516
     517        To prevent automatic evaluation use the ``hold`` argument::
     518
     519            sage: gamma1(1/2,hold=True)
     520            gamma(1/2)
     521
     522        To then evaluate again, we currently must use Maxima via
     523        :meth:`sage.symbolic.expression.Expression.simplify`::
     524
     525            sage: gamma1(1/2,hold=True).simplify()
     526            sqrt(pi)
     527
    516528        TESTS:
    517529
    518530        We verify that we can convert this function to Maxima and
     
    961973            sage: factorial(x)^2
    962974            factorial(x)^2
    963975
    964         ::
     976        To prevent automatic evaluation use the ``hold`` argument::
     977
     978            sage: factorial(5,hold=True)
     979            factorial(5)
     980
     981        To then evaluate again, we currently must use Maxima via
     982        :meth:`sage.symbolic.expression.Expression.simplify`::
     983
     984            sage: factorial(5,hold=True).simplify()
     985            120
     986
     987        We can also give input other than nonnegative integers.  For
     988        other nonnegative numbers, the :func:`gamma` function is used::
     989
     990            sage: factorial(1/2)
     991            1/2*sqrt(pi)
     992            sage: factorial(3/4)
     993            gamma(7/4)
     994            sage: factorial(2.3)
     995            2.68343738195577
     996
     997        But negative input always fails::
    965998
    966999            sage: factorial(-32)
    9671000            Traceback (most recent call last):
     
    10671100            sage: binomial(k,i)
    10681101            binomial(k, i)
    10691102
     1103        We can use a ``hold`` parameter to prevent automatic evaluation,
     1104        but only using method notation::
     1105
     1106            sage: SR(5).binomial(3, hold=True)
     1107            binomial(5, 3)
     1108            sage: SR(5).binomial(3, hold=True).simplify()
     1109            10
     1110
    10701111        TESTS: We verify that we can convert this function to Maxima and
    10711112        bring it back into Sage.
    10721113
     
    11621203        -  ``all`` - bool (default: False); if True, return all
    11631204           square roots of self, instead of just one.
    11641205
    1165         EXAMPLES:
     1206        EXAMPLES::
    11661207
    1167         This illustrates that the bug reported in #6171 has been fixed::
    1168 
    1169             sage: a = 1.1
    1170             sage: a.sqrt(prec=100)  # this is supposed to fail
    1171             Traceback (most recent call last):
    1172             ...
    1173             TypeError: sqrt() got an unexpected keyword argument 'prec'
    1174             sage: sqrt(a, prec=100)
    1175             1.0488088481701515469914535137
    1176             sage: sqrt(4.00, prec=250)
    1177             2.0000000000000000000000000000000000000000000000000000000000000000000000000
    11781208            sage: sqrt(-1)
    11791209            I
    11801210            sage: sqrt(2)
     
    11891219            sqrt(x^2)
    11901220            sage: sqrt(2).n()
    11911221            1.41421356237310
     1222
     1223        To prevent automatic evaluation, one can use the ``hold`` parameter
     1224        after coercing to the symbolic ring::
     1225
     1226            sage: sqrt(SR(4),hold=True)
     1227            sqrt(4)
     1228            sage: sqrt(4,hold=True)
     1229            Traceback (most recent call last):
     1230            ...
     1231            TypeError: _do_sqrt() got an unexpected keyword argument 'hold'
     1232
     1233        This illustrates that the bug reported in #6171 has been fixed::
     1234
     1235            sage: a = 1.1
     1236            sage: a.sqrt(prec=100)  # this is supposed to fail
     1237            Traceback (most recent call last):
     1238            ...
     1239            TypeError: sqrt() got an unexpected keyword argument 'prec'
     1240            sage: sqrt(a, prec=100)
     1241            1.0488088481701515469914535137
     1242            sage: sqrt(4.00, prec=250)
     1243            2.0000000000000000000000000000000000000000000000000000000000000000000000000
     1244
     1245        One can use numpy input as well::
     1246
    11921247            sage: import numpy
    11931248            sage: a = numpy.arange(2,5)
    11941249            sage: sqrt(a)
     
    12221277class Function_real_part(GinacFunction):
    12231278    def __init__(self):
    12241279        r"""
     1280        Returns the real part of the (possibly complex) input.
     1281
     1282        It is possible to prevent automatic evaluation using the
     1283        ``hold`` parameter::
     1284
     1285            sage: real_part(I,hold=True)
     1286            real_part(I)
     1287
     1288        To then evaluate again, we currently must use Maxima via
     1289        :meth:`sage.symbolic.expression.Expression.simplify`::
     1290
     1291            sage: real_part(I,hold=True).simplify()
     1292            0
     1293
    12251294        EXAMPLES::
    12261295
    12271296            sage: z = 1+2*I
     
    12711340class Function_imag_part(GinacFunction):
    12721341    def __init__(self):
    12731342        r"""
     1343        Returns the imaginary part of the (possibly complex) input.
     1344
     1345        It is possible to prevent automatic evaluation using the
     1346        ``hold`` parameter::
     1347
     1348            sage: imag_part(I,hold=True)
     1349            imag_part(I)
     1350
     1351        To then evaluate again, we currently must use Maxima via
     1352        :meth:`sage.symbolic.expression.Expression.simplify`::
     1353
     1354            sage: imag_part(I,hold=True).simplify()
     1355            1
     1356
    12741357        TESTS::
    12751358
    12761359            sage: z = 1+2*I
     
    13141397class Function_conjugate(GinacFunction):
    13151398    def __init__(self):
    13161399        r"""
     1400        Returns the complex conjugate of the input.
     1401
     1402        It is possible to prevent automatic evaluation using the
     1403        ``hold`` parameter::
     1404
     1405            sage: conjugate(I,hold=True)
     1406            conjugate(I)
     1407
     1408        To then evaluate again, we currently must use Maxima via
     1409        :meth:`sage.symbolic.expression.Expression.simplify`::
     1410
     1411            sage: conjugate(I,hold=True).simplify()
     1412            -I
     1413
    13171414        TESTS::
    13181415
    13191416            sage: x,y = var('x,y')
  • sage/functions/special.py

    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/special.py
    a b  
    15881588        4.78749174278205
    15891589        sage: log_gamma(x)
    15901590        log_gamma(x)
     1591
     1592    The only current way to prevent automatic evaluation is to
     1593    use the ``hold`` argument with the symbolic method, thus::
     1594
     1595        sage: SR(5).log_gamma(hold=True)
     1596        log_gamma(5)
     1597
     1598    To evaluate again, currently we must use numerical evaluation
     1599    via :meth:`n`::
     1600
     1601        sage: a = SR(5).log_gamma(hold=True); a.n()
     1602        3.17805383034795
     1603
    15911604    """
    15921605    try:
    15931606        return t.log_gamma()
     
    16071620    EXAMPLES::
    16081621       
    16091622        sage: exp_int(6)
    1610         doctest:...: DeprecationWarning: The method expint() is deprecated. Use -Ei(-x) or exponential_integral_1(x) as needed instead.
     1623        doctest:...: DeprecationWarning: The method exp_int() is deprecated. Use -Ei(-x) or exponential_integral_1(x) as needed instead.
    16111624        0.000360082452162659
    16121625    """
    16131626    from sage.misc.misc import deprecation
    1614     deprecation("The method expint() is deprecated. Use -Ei(-x) or exponential_integral_1(x) as needed instead.")
     1627    deprecation("The method exp_int() is deprecated. Use -Ei(-x) or exponential_integral_1(x) as needed instead.")
    16151628    try:
    16161629        return t.eint1()
    16171630    except AttributeError:
  • sage/functions/transcendental.py

    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/transcendental.py
    a b  
    132132            sage: zeta(I).n()
    133133            0.00330022368532410 - 0.418155449141322*I
    134134
     135        It is possible to use the ``hold`` argument to prevent
     136        automatic evaluation::
     137
     138            sage: zeta(2,hold=True)
     139            zeta(2)
     140
     141        To then evaluate again, we currently must use Maxima via
     142        :meth:`sage.symbolic.expression.Expression.simplify`::
     143
     144            sage: a = zeta(2,hold=True); a.simplify()
     145            1/6*pi^2
     146
    135147        TESTS::
    136148
    137149            sage: latex(zeta(x))
  • sage/functions/trig.py

    diff -r a975651fae5c -r 7a046048d2c4 sage/functions/trig.py
    a b  
    2020             0.90929742682568169539601986591
    2121             sage: loads(dumps(sin))
    2222             sin
     23
     24        We can prevent evaluation using the ``hold`` parameter::
     25
     26            sage: sin(0,hold=True)
     27            sin(0)
     28
     29        To then evaluate again, we currently must use Maxima via
     30        :meth:`sage.symbolic.expression.Expression.simplify`::
     31
     32            sage: a = sin(0,hold=True); a.simplify()
     33            0
     34
    2335        """
    2436        GinacFunction.__init__(self, "sin", latex_name=r"\sin",
    2537                conversions=dict(maxima='sin',mathematica='Sin'))
     
    4153            -0.41614683654714238699756822950
    4254            sage: loads(dumps(cos))
    4355            cos
     56
     57        We can prevent evaluation using the ``hold`` parameter::
     58
     59            sage: cos(0,hold=True)
     60            cos(0)
     61
     62        To then evaluate again, we currently must use Maxima via
     63        :meth:`sage.symbolic.expression.Expression.simplify`::
     64
     65            sage: a = cos(0,hold=True); a.simplify()
     66            1
     67
    4468        """
    4569        GinacFunction.__init__(self, "cos", latex_name=r"\cos",
    4670                conversions=dict(maxima='cos',mathematica='Cos'))
     
    6690            tan(1/2)
    6791            sage: RR(tan(1/2))
    6892            0.546302489843790
     93
     94        We can prevent evaluation using the ``hold`` parameter::
     95
     96            sage: tan(pi/4,hold=True)
     97            tan(1/4*pi)
     98
     99        To then evaluate again, we currently must use Maxima via
     100        :meth:`sage.symbolic.expression.Expression.simplify`::
     101
     102            sage: a = tan(pi/4,hold=True); a.simplify()
     103            1
     104
    69105        """
    70106        GinacFunction.__init__(self, "tan", latex_name=r"\tan")
    71107
     
    91127
    92128            sage: latex(sec(x))
    93129            \sec\left(x\right)
     130
     131        We can prevent evaluation using the ``hold`` parameter::
     132
     133            sage: sec(pi/4,hold=True)
     134            sec(1/4*pi)
     135
     136        To then evaluate again, we currently must use Maxima via
     137        :meth:`sage.symbolic.expression.Expression.simplify`::
     138
     139            sage: a = sec(pi/4,hold=True); a.simplify()
     140            sqrt(2)
     141
    94142        """
    95143        BuiltinFunction.__init__(self, "sec", latex_name=r"\sec")
    96144
     
    170218
    171219            sage: latex(csc(x))
    172220            \csc\left(x\right)
     221
     222        We can prevent evaluation using the ``hold`` parameter::
     223
     224            sage: csc(pi/4,hold=True)
     225            csc(1/4*pi)
     226
     227        To then evaluate again, we currently must use Maxima via
     228        :meth:`sage.symbolic.expression.Expression.simplify`::
     229
     230            sage: a = csc(pi/4,hold=True); a.simplify()
     231            sqrt(2)
     232
    173233        """
    174234        BuiltinFunction.__init__(self, "csc", latex_name=r"\csc")
    175235
     
    248308
    249309            sage: latex(cot(x))
    250310            \cot\left(x\right)
     311
     312        We can prevent evaluation using the ``hold`` parameter::
     313
     314            sage: cot(pi/4,hold=True)
     315            cot(1/4*pi)
     316
     317        To then evaluate again, we currently must use Maxima via
     318        :meth:`sage.symbolic.expression.Expression.simplify`::
     319
     320            sage: a = cot(pi/4,hold=True); a.simplify()
     321            1
     322
    251323        """
    252324        BuiltinFunction.__init__(self, "cot", latex_name=r"\cot")
    253325
     
    326398            sage: arcsin(1 + 1.0*I)
    327399            0.666239432492515 + 1.06127506190504*I
    328400
     401        We can delay evaluation using the ``hold`` parameter::
     402
     403            sage: arcsin(0,hold=True)
     404            arcsin(0)
     405
     406        To then evaluate again, we currently must use Maxima via
     407        :meth:`sage.symbolic.expression.Expression.simplify`::
     408
     409            sage: a = arcsin(0,hold=True); a.simplify()
     410            0
     411
    329412        TESTS::
    330413           
    331414            sage: arcsin(x).operator()
     
    352435            sage: arccos(3/4).n(100)
    353436            0.72273424781341561117837735264
    354437
     438        We can delay evaluation using the ``hold`` parameter::
     439
     440            sage: arccos(0,hold=True)
     441            arccos(0)
     442
     443        To then evaluate again, we currently must use Maxima via
     444        :meth:`sage.symbolic.expression.Expression.simplify`::
     445
     446            sage: a = arccos(0,hold=True); a.simplify()
     447            1/2*pi
     448
    355449        TESTS::
    356450
    357451            sage: arccos(x).operator()
     
    378472            sage: arctan(1/2).n(100)
    379473            0.46364760900080611621425623146
    380474
     475        We can delay evaluation using the ``hold`` parameter::
     476
     477            sage: arctan(0,hold=True)
     478            arctan(0)
     479
     480        To then evaluate again, we currently must use Maxima via
     481        :meth:`sage.symbolic.expression.Expression.simplify`::
     482
     483            sage: a = arctan(0,hold=True); a.simplify()
     484            0
     485
    381486        TESTS::
    382487
    383488            sage: arctan(x).operator()
     
    401506            1.10714871779
    402507            sage: arccot(1 + I)
    403508            arccot(I + 1)
     509
     510        We can delay evaluation using the ``hold`` parameter::
     511
     512            sage: arccot(1,hold=True)
     513            arccot(1)
     514
     515        To then evaluate again, we currently must use Maxima via
     516        :meth:`sage.symbolic.expression.Expression.simplify`::
     517
     518            sage: a = arccot(1,hold=True); a.simplify()
     519            1/4*pi
     520
    404521        """
    405522        BuiltinFunction.__init__(self, "arccot", latex_name=r'{\rm arccot}',
    406523                                   conversions=dict(maxima='acot'))
     
    457574            0.523598775598
    458575            sage: arccsc(1 + I)
    459576            arccsc(I + 1)
     577
     578        We can delay evaluation using the ``hold`` parameter::
     579
     580            sage: arccsc(1,hold=True)
     581            arccsc(1)
     582
     583        To then evaluate again, we currently must use Maxima via
     584        :meth:`sage.symbolic.expression.Expression.simplify`::
     585
     586            sage: a = arccsc(1,hold=True); a.simplify()
     587            1/2*pi
     588
    460589        """       
    461590        BuiltinFunction.__init__(self, "arccsc", latex_name=r'{\rm arccsc}',
    462591                                   conversions=dict(maxima='acsc'))
     
    509638            1.0471975512
    510639            sage: arcsec(1 + I)
    511640            arcsec(I + 1)
     641
     642        We can delay evaluation using the ``hold`` parameter::
     643
     644            sage: arcsec(1,hold=True)
     645            arcsec(1)
     646
     647        To then evaluate again, we currently must use Maxima via
     648        :meth:`sage.symbolic.expression.Expression.simplify`::
     649
     650            sage: a = arcsec(1,hold=True); a.simplify()
     651            0
     652
    512653        """       
    513654        BuiltinFunction.__init__(self, "arcsec", latex_name=r'{\rm arcsec}',
    514655                                   conversions=dict(maxima='asec'))
     
    599740            sage: arctan2(2,3).n(100)
    600741            0.58800260354756755124561108063
    601742
     743        We can delay evaluation using the ``hold`` parameter::
     744
     745            sage: arctan2(-1/2,1,hold=True)
     746            arctan2(-1/2, 1)
     747
     748        To then evaluate again, we currently must use Maxima via
     749        :meth:`sage.symbolic.expression.Expression.simplify`::
     750
     751            sage: arctan2(-1/2,1,hold=True).simplify()
     752            -arctan(1/2)
     753
    602754        The function also works with numpy arrays as input::
    603755
    604756            sage: import numpy
  • sage/symbolic/expression.pyx

    diff -r a975651fae5c -r 7a046048d2c4 sage/symbolic/expression.pyx
    a b  
    39563956            x^4
    39573957            sage: (x^2).power(2, hold=True)
    39583958            (x^2)^2
     3959
     3960        To then evaluate again, we currently must use Maxima via
     3961        :meth:`simplify`::
     3962
     3963            sage: a = (x^2).power(2, hold=True); a.simplify()
     3964            x^4
     3965
    39593966        """
    39603967        cdef Expression nexp = self.coerce_in(exp)
    39613968        return new_Expression_from_GEx(self._parent,
     
    39803987            x + x + (x + 2) + x
    39813988            sage: x.add(x, (2+x), x, 2*x, hold=True)
    39823989            x + x + (x + 2) + x + 2*x
     3990
     3991        To then evaluate again, we currently must use Maxima via
     3992        :meth:`simplify`::
     3993
     3994            sage: a = x.add(x, hold=True); a.simplify()
     3995            2*x
    39833996        """
    39843997        nargs = [self.coerce_in(x) for x in args]
    39853998        cdef GExVector vec
     
    40074020            x*x*(x + 2)*x
    40084021            sage: x.mul(x, (2+x), x, 2*x, hold=True)
    40094022            x*x*(x + 2)*x*(2*x)
     4023
     4024        To then evaluate again, we currently must use Maxima via
     4025        :meth:`simplify`::
     4026
     4027            sage: a = x.mul(x, hold=True); a.simplify()
     4028            x^2
     4029
    40104030        """
    40114031        nargs = [self.coerce_in(x) for x in args]
    40124032        cdef GExVector vec
     
    44144434            sage: R(f)
    44154435            2.7182818284590452353602874714*x^3 + 3.1415926535897932384626433833*y^3 + 1.4142135623730950488016887242 + 1.0000000000000000000000000000*I
    44164436
    4417         Using the ``hold`` parameter it is possible to prevent automatic
    4418         evaluation::
    4419 
    4420             sage: SR(I).conjugate(hold=True)
    4421             conjugate(I)
    4422 
    44234437        TESTS:
    44244438
    44254439        This shows that the issue at trac #5755 is fixed (attempting to
     
    45964610            sage: type(abs(SR(-5)))
    45974611            <type 'sage.symbolic.expression.Expression'>
    45984612
    4599         Using the ``hold`` parameter it is possible to prevent automatic
    4600         evaluation::
     4613        Because this overrides a Python builtin function, we do not
     4614        currently support a ``hold`` parameter to prevent automatic
     4615        evaluation::
     4616
     4617            sage: abs(SR(-5),hold=True)
     4618            Traceback (most recent call last):
     4619            ...
     4620            TypeError: abs() takes no keyword arguments
     4621
     4622        But this is possible using the method :meth:`abs`::
    46014623
    46024624            sage: SR(-5).abs(hold=True)
    46034625            abs(-5)
     
    46204642
    46214643            sage: SR(-5).abs(hold=True)
    46224644            abs(-5)
     4645
     4646        To then evaluate again, we currently must use Maxima via
     4647        :meth:`simplify`::
     4648
     4649            sage: a = SR(-5).abs(hold=True); a.simplify()
     4650            5
    46234651        """
    46244652        return new_Expression_from_GEx(self._parent,
    46254653                g_hold_wrapper(g_abs, self._gobj, hold))
     
    46484676            1
    46494677            sage: SR(2).step(hold=True)
    46504678            step(2)
     4679
    46514680        """
    46524681        return new_Expression_from_GEx(self._parent,
    46534682                g_hold_wrapper(g_step, self._gobj, hold))
     
    46804709
    46814710            sage: SR(I).csgn(hold=True)
    46824711            csgn(I)
     4712
    46834713        """
    46844714        return new_Expression_from_GEx(self._parent,
    46854715                g_hold_wrapper(g_csgn, self._gobj, hold))
     
    47104740            -I
    47114741            sage: ( 1+I  + (2-3*I)*x).conjugate()
    47124742            (3*I + 2)*conjugate(x) - I + 1
     4743
     4744        Using the ``hold`` parameter it is possible to prevent automatic
     4745        evaluation::
     4746
     4747            sage: SR(I).conjugate(hold=True)
     4748            conjugate(I)
     4749
     4750        This also works in functional notation::
     4751
     4752            sage: conjugate(I)
     4753            -I
     4754            sage: conjugate(I,hold=True)
     4755            conjugate(I)
     4756
     4757        To then evaluate again, we currently must use Maxima via
     4758        :meth:`simplify`::
     4759
     4760            sage: a = SR(I).conjugate(hold=True); a.simplify()
     4761            -I
     4762
    47134763        """
    47144764        return new_Expression_from_GEx(self._parent,
    47154765                g_hold_wrapper(g_conjugate, self._gobj, hold))
     
    47624812            2
    47634813            sage: SR(2).real_part(hold=True)
    47644814            real_part(2)
     4815
     4816        This also works using functional notation::
     4817
     4818            sage: real_part(I,hold=True)
     4819            real_part(I)
     4820            sage: real_part(I)
     4821            0
     4822
     4823        To then evaluate again, we currently must use Maxima via
     4824        :meth:`simplify`::
     4825
     4826            sage: a = SR(2).real_part(hold=True); a.simplify()
     4827            2
    47654828        """
    47664829        return new_Expression_from_GEx(self._parent,
    47674830                g_hold_wrapper(g_real_part, self._gobj, hold))
     
    48064869            sage: I.imag_part(hold=True)
    48074870            imag_part(I)
    48084871
     4872        This also works using functional notation::
     4873
     4874            sage: imag_part(I,hold=True)
     4875            imag_part(I)
     4876            sage: imag_part(I)
     4877            1
     4878
     4879        To then evaluate again, we currently must use Maxima via
     4880        :meth:`simplify`::
     4881
     4882            sage: a = I.imag_part(hold=True); a.simplify()
     4883            1
     4884
    48094885        TESTS::
    48104886       
    48114887            sage: x = var('x')
     
    48424918            2
    48434919            sage: SR(4).sqrt(hold=True)
    48444920            sqrt(4)
     4921
     4922        To then evaluate again, we currently must use Maxima via
     4923        :meth:`simplify`::
     4924
     4925            sage: a = SR(4).sqrt(hold=True); a.simplify()
     4926            2
     4927
     4928        To use this parameter in functional notation, you must coerce to
     4929        the symbolic ring::
     4930
     4931            sage: sqrt(SR(4),hold=True)
     4932            sqrt(4)
     4933            sage: sqrt(4,hold=True)
     4934            Traceback (most recent call last):
     4935            ...
     4936            TypeError: _do_sqrt() got an unexpected keyword argument 'hold'
    48454937        """
    48464938        return new_Expression_from_GEx(self._parent,
    48474939                g_hold2_wrapper(g_power_construct, self._gobj, g_ex1_2, hold))
     
    48694961            sage: SR(0).sin(hold=True)
    48704962            sin(0)
    48714963
     4964        This also works using functional notation::
     4965
     4966            sage: sin(0,hold=True)
     4967            sin(0)
     4968            sage: sin(0)
     4969            0
     4970
     4971        To then evaluate again, we currently must use Maxima via
     4972        :meth:`simplify`::
     4973
     4974            sage: a = SR(0).sin(hold=True); a.simplify()
     4975            0
     4976
    48724977        TESTS::
    48734978
    48744979            sage: SR(oo).sin()
     
    49195024            sage: pi.cos(hold=True)
    49205025            cos(pi)
    49215026
     5027        This also works using functional notation::
     5028
     5029            sage: cos(pi,hold=True)
     5030            cos(pi)
     5031            sage: cos(pi)
     5032            -1
     5033
     5034        To then evaluate again, we currently must use Maxima via
     5035        :meth:`simplify`::
     5036
     5037            sage: a = pi.cos(hold=True); a.simplify()
     5038            -1
     5039
    49225040        TESTS::
    49235041
    49245042            sage: SR(oo).cos()
     
    49595077            sage: (pi/12).tan(hold=True)
    49605078            tan(1/12*pi)
    49615079
     5080        This also works using functional notation::
     5081
     5082            sage: tan(pi/12,hold=True)
     5083            tan(1/12*pi)
     5084            sage: tan(pi/12)
     5085            -sqrt(3) + 2
     5086
     5087        To then evaluate again, we currently must use Maxima via
     5088        :meth:`simplify`::
     5089
     5090            sage: a = (pi/12).tan(hold=True); a.simplify()
     5091            -sqrt(3) + 2
     5092
    49625093        TESTS::
    49635094
    49645095            sage: SR(oo).tan()
     
    50025133            sage: SR(0).arcsin(hold=True)
    50035134            arcsin(0)
    50045135
     5136        This also works using functional notation::
     5137
     5138            sage: arcsin(0,hold=True)
     5139            arcsin(0)
     5140            sage: arcsin(0)
     5141            0
     5142
     5143        To then evaluate again, we currently must use Maxima via
     5144        :meth:`simplify`::
     5145
     5146            sage: a = SR(0).arcsin(hold=True); a.simplify()
     5147            0
     5148
    50055149        TESTS::
    50065150
    50075151            sage: SR(oo).arcsin()
     
    50395183            sage: SR(1).arccos(hold=True)
    50405184            arccos(1)
    50415185
     5186        This also works using functional notation::
     5187
     5188            sage: arccos(1,hold=True)
     5189            arccos(1)
     5190            sage: arccos(1)
     5191            0
     5192
     5193        To then evaluate again, we currently must use Maxima via
     5194        :meth:`simplify`::
     5195
     5196            sage: a = SR(1).arccos(hold=True); a.simplify()
     5197            0
     5198
    50425199        TESTS::
    50435200
    50445201            sage: SR(oo).arccos()
     
    50775234            sage: SR(1).arctan(hold=True)
    50785235            arctan(1)
    50795236
     5237        This also works using functional notation::
     5238
     5239            sage: arctan(1,hold=True)
     5240            arctan(1)
     5241            sage: arctan(1)
     5242            1/4*pi
     5243
     5244        To then evaluate again, we currently must use Maxima via
     5245        :meth:`simplify`::
     5246
     5247            sage: a = SR(1).arctan(hold=True); a.simplify()
     5248            1/4*pi
     5249
    50805250        TESTS::
    50815251
    50825252            sage: SR(oo).arctan()
     
    51145284            sage: SR(1/2).arctan2(1/2, hold=True)
    51155285            arctan2(1/2, 1/2)
    51165286
     5287        This also works using functional notation::
     5288
     5289            sage: arctan2(1,2,hold=True)
     5290            arctan2(1, 2)
     5291            sage: arctan2(1,2)
     5292            arctan(1/2)
     5293
     5294        To then evaluate again, we currently must use Maxima via
     5295        :meth:`simplify`::
     5296
     5297            sage: a = SR(1/2).arctan2(1/2, hold=True); a.simplify()
     5298            1/4*pi
     5299
    51175300        TESTS:
    51185301
    51195302        We compare a bunch of different evaluation points between
     
    52125395            sage: arccosh(x).sinh(hold=True)
    52135396            sinh(arccosh(x))
    52145397
     5398        This also works using functional notation::
     5399
     5400            sage: sinh(arccosh(x),hold=True)
     5401            sinh(arccosh(x))
     5402            sage: sinh(arccosh(x))
     5403            sqrt(x - 1)*sqrt(x + 1)
     5404
     5405        To then evaluate again, we currently must use Maxima via
     5406        :meth:`simplify`::
     5407
     5408            sage: a = arccosh(x).sinh(hold=True); a.simplify()
     5409            sqrt(x - 1)*sqrt(x + 1)
     5410
    52155411        TESTS::
    52165412
    52175413            sage: SR(oo).sinh()
     
    52565452            sage: arcsinh(x).cosh(hold=True)
    52575453            cosh(arcsinh(x))
    52585454
     5455        This also works using functional notation::
     5456
     5457            sage: cosh(arcsinh(x),hold=True)
     5458            cosh(arcsinh(x))
     5459            sage: cosh(arcsinh(x))
     5460            sqrt(x^2 + 1)
     5461
     5462        To then evaluate again, we currently must use Maxima via
     5463        :meth:`simplify`::
     5464
     5465            sage: a = arcsinh(x).cosh(hold=True); a.simplify()
     5466            sqrt(x^2 + 1)
     5467
    52595468        TESTS::
    52605469
    52615470            sage: SR(oo).cosh()
     
    52975506            sage: arcsinh(x).tanh(hold=True)
    52985507            tanh(arcsinh(x))
    52995508
     5509        This also works using functional notation::
     5510
     5511            sage: tanh(arcsinh(x),hold=True)
     5512            tanh(arcsinh(x))
     5513            sage: tanh(arcsinh(x))
     5514            x/sqrt(x^2 + 1)
     5515
     5516        To then evaluate again, we currently must use Maxima via
     5517        :meth:`simplify`::
     5518
     5519            sage: a = arcsinh(x).tanh(hold=True); a.simplify()
     5520            x/sqrt(x^2 + 1)
     5521
    53005522        TESTS::
    53015523
    53025524            sage: SR(oo).tanh()
     
    53405562            sage: SR(-2).arcsinh(hold=True)
    53415563            arcsinh(-2)
    53425564
     5565        This also works using functional notation::
     5566
     5567            sage: arcsinh(-2,hold=True)
     5568            arcsinh(-2)
     5569            sage: arcsinh(-2)
     5570            -arcsinh(2)
     5571
     5572        To then evaluate again, we currently must use Maxima via
     5573        :meth:`simplify`::
     5574
     5575            sage: a = SR(-2).arcsinh(hold=True); a.simplify()
     5576            -arcsinh(2)
     5577
    53435578        TESTS::
    53445579
    53455580            sage: SR(oo).arcsinh()
     
    53765611            sage: SR(-1).arccosh(hold=True)
    53775612            arccosh(-1)
    53785613
     5614        This also works using functional notation::
     5615
     5616            sage: arccosh(-1,hold=True)
     5617            arccosh(-1)
     5618            sage: arccosh(-1)
     5619            I*pi
     5620
     5621        To then evaluate again, we currently must use Maxima via
     5622        :meth:`simplify`::
     5623
     5624            sage: a = SR(-1).arccosh(hold=True); a.simplify()
     5625            I*pi
     5626
    53795627        TESTS::
    53805628
    53815629            sage: SR(oo).arccosh()
     
    54145662            sage: SR(-1/2).arctanh(hold=True)
    54155663            arctanh(-1/2)
    54165664
     5665        This also works using functional notation::
     5666
     5667            sage: arctanh(-1/2,hold=True)
     5668            arctanh(-1/2)
     5669            sage: arctanh(-1/2)
     5670            -arctanh(1/2)
     5671
     5672        To then evaluate again, we currently must use Maxima via
     5673        :meth:`simplify`::
     5674
     5675            sage: a = SR(-1/2).arctanh(hold=True); a.simplify()
     5676            -arctanh(1/2)
     5677
    54175678        TESTS::
    54185679
    54195680            sage: SR(1).arctanh()
     
    54615722            sage: (pi*I).exp(hold=True)
    54625723            e^(I*pi)
    54635724
     5725        This also works using functional notation::
     5726
     5727            sage: exp(I*pi,hold=True)
     5728            e^(I*pi)
     5729            sage: exp(I*pi)
     5730            -1
     5731
     5732        To then evaluate again, we currently must use Maxima via
     5733        :meth:`simplify`::
     5734
     5735            sage: a = (pi*I).exp(hold=True); a.simplify()
     5736            -1
     5737
    54645738        TESTS:
    54655739
    54665740        Test if #6377 is fixed::
     
    55115785            sage: I.log(hold=True)
    55125786            log(I)
    55135787
     5788        To then evaluate again, we currently must use Maxima via
     5789        :meth:`simplify`::
     5790
     5791            sage: a = I.log(hold=True); a.simplify()
     5792            1/2*I*pi
     5793
     5794        We do not currently support a ``hold`` parameter in functional
     5795        notation::
     5796
     5797            sage: log(SR(-1),hold=True)
     5798            Traceback (most recent call last):
     5799            ...
     5800            TypeError: log() got an unexpected keyword argument 'hold'
     5801
    55145802        TESTS::
    55155803
    55165804            sage: SR(oo).log()
     
    55495837            sage: SR(2).zeta(hold=True)
    55505838            zeta(2)
    55515839
     5840        This also works using functional notation::
     5841
     5842            sage: zeta(2,hold=True)
     5843            zeta(2)
     5844            sage: zeta(2)
     5845            1/6*pi^2
     5846
     5847        To then evaluate again, we currently must use Maxima via
     5848        :meth:`simplify`::
     5849
     5850            sage: a = SR(2).zeta(hold=True); a.simplify()
     5851            1/6*pi^2
     5852
    55525853        TESTS::
    55535854           
    55545855            sage: t = SR(1).zeta(); t
     
    55805881
    55815882            sage: SR(5).factorial(hold=True)
    55825883            factorial(5)
     5884
     5885        This also works using functional notation::
     5886
     5887            sage: factorial(5,hold=True)
     5888            factorial(5)
     5889            sage: factorial(5)
     5890            120
     5891
     5892        To then evaluate again, we currently must use Maxima via
     5893        :meth:`simplify`::
     5894
     5895            sage: a = SR(5).factorial(hold=True); a.simplify()
     5896            120
     5897
    55835898        """
    55845899        _sig_on
    55855900        cdef GEx x = g_hold_wrapper(g_factorial, self._gobj, hold)
     
    56105925            sage: SR(5).binomial(3, hold=True)
    56115926            binomial(5, 3)
    56125927
     5928        To then evaluate again, we currently must use Maxima via
     5929        :meth:`simplify`::
     5930
     5931            sage: a = SR(5).binomial(3, hold=True); a.simplify()
     5932            10
     5933
     5934        We do not currently support a ``hold`` parameter in functional
     5935        notation::
     5936
     5937            sage: binomial(5,3, hold=True)
     5938            Traceback (most recent call last):
     5939            ...
     5940            TypeError: binomial() got an unexpected keyword argument 'hold'
     5941
    56135942        TESTS:
    56145943
    56155944        Check if we handle zero correctly (#8561)::
     
    56505979        """
    56515980        Return the Gamma function evaluated at self.
    56525981       
    5653         EXAMPLES:
     5982        EXAMPLES::
     5983
    56545984            sage: x = var('x')
    56555985            sage: x.gamma()
    56565986            gamma(x)
     
    56635993            sage: SR(CDF(1,1)).gamma()
    56645994            0.498015668118 - 0.154949828302*I
    56655995
     5996        ::
     5997
    56665998            sage: gp('gamma(1+I)') # 32-bit
    56675999            0.4980156681183560427136911175 - 0.1549498283018106851249551305*I
    56686000
     6001        ::
     6002
    56696003            sage: gp('gamma(1+I)') # 64-bit
    56706004            0.49801566811835604271369111746219809195 - 0.15494982830181068512495513048388660520*I
    56716005
     6006        We plot the familiar plot of this log-convex function::
     6007
     6008            sage: plot(gamma(x), -6,4).show(ymin=-3,ymax=3)
     6009
    56726010        To prevent automatic evaluation use the ``hold`` argument::
    56736011
    56746012            sage: SR(1/2).gamma()
     
    56766014            sage: SR(1/2).gamma(hold=True)
    56776015            gamma(1/2)
    56786016
    5679         ::
    5680 
    5681             sage: set_verbose(-1); plot(lambda x: SR(x).gamma(), -6,4).show(ymin=-3,ymax=3)
     6017        This also works using functional notation::
     6018
     6019            sage: gamma(1/2,hold=True)
     6020            gamma(1/2)
     6021            sage: gamma(1/2)
     6022            sqrt(pi)
     6023
     6024        To then evaluate again, we currently must use Maxima via
     6025        :meth:`simplify`::
     6026
     6027            sage: a = SR(1/2).gamma(hold=True); a.simplify()
     6028            sqrt(pi)
    56826029        """
    56836030        _sig_on
    56846031        cdef GEx x = g_hold_wrapper(g_tgamma, self._gobj, hold)
     
    57286075
    57296076            sage: SR(5).log_gamma(hold=True)
    57306077            log_gamma(5)
     6078
     6079        To evaluate again, currently we must use numerical evaluation
     6080        via :meth:`n`::
     6081
     6082            sage: a = SR(5).log_gamma(hold=True); a.n()
     6083            3.17805383034795
     6084
     6085        We do not currently support a ``hold`` parameter in functional
     6086        notation::
     6087
     6088            sage: log_gamma(SR(5),hold=True)
     6089            Traceback (most recent call last):
     6090            ...
     6091            TypeError: log_gamma() got an unexpected keyword argument 'hold'
     6092
    57316093        """
    57326094        _sig_on
    57336095        cdef GEx x = g_hold_wrapper(g_lgamma, self._gobj, hold)