### Navigation

- index
- modules |
- next |
- previous |
- Functions »

# Logarithmic functions

AUTHORS:

- Yoora Yi Tenen (2012-11-16): Add documentation for `log()` (trac ticket #12113)

class `sage.functions.log.``Function_dilog`

  Bases: `sage.symbolic.function.GinacFunction`

  The dilogarithm function \(\text{Li}_2(z) = \sum_{k=1}^{\infty} z^k / k^2\).

  This is simply an alias for polylog(2, z).

  EXAMPLES:

      sage: dilog(1)
      1/6*pi^2
      sage: dilog(1/2)
      1/12*pi^2 - 1/2*log(2)^2
      sage: dilog(x^2+1)
      dilog(x^2 + 1)
      sage: dilog(-1)
      -1/12*pi^2
      sage: dilog(-1.1)
      -0.890838090262283
      sage: float(dilog(1))
      1.6449340668482262
      sage: var('z')
      z
      sage: dilog(z).diff(z, 2)
      log(-z + 1)/z^2 - 1/((z - 1)*z)
      sage: dilog(z).series(z==1/2, 3)
      (1/12*pi^2 - 1/2*log(2)^2) + (-2*log(1/2))*(z - 1/2) + (2*log(1/2) + 2)*(z - 1/2)^2 + Order(1/8*(2*z - 1)^3)

      sage: latex(dilog(z))
      {\rm Li}_2\left(z\right)

  TESTS:

  `conjugate(dilog(x))==dilog(conjugate(x))` unless on the branch cuts which run along the positive real axis beginning at 1.:

      sage: conjugate(dilog(x))
      conjugate(dilog(x))
      sage: var('y',domain='positive')
      y
      sage: conjugate(dilog(y))
      conjugate(dilog(y))
      sage: conjugate(dilog(1/19))
      dilog(1/19)
      sage: conjugate(dilog(1/2*I))
      dilog(-1/2*I)
      sage: dilog(conjugate(1/2*I))
      dilog(-1/2*I)
      sage: conjugate(dilog(2))
      conjugate(dilog(2))

class `sage.functions.log.``Function_exp`

  Bases: `sage.symbolic.function.GinacFunction`

  The exponential function, \(\exp(x) = e^x\).

  EXAMPLES:

      sage: exp(-1)
      e^(-1)
      sage: exp(2)
      e^2
      sage: exp(2).n(100)
      7.3890560989306502272304274606
      sage: exp(x^2 + log(x))
      e^(x^2 + log(x))
      sage: exp(x^2 + log(x)).simplify()
      x*e^(x^2)
      sage: exp(2.5)
      12.1824939607035
      sage: exp(float(2.5))
      12.182493960703473
      sage: exp(RDF('2.5'))
      12.182493960703473

  To prevent automatic evaluation, use the `hold` parameter:

      sage: exp(I*pi,hold=True)
      e^(I*pi)
      sage: exp(0,hold=True)
      e^0

  To then evaluate again, we currently must use Maxima via `sage.symbolic.expression.Expression.simplify()`:

      sage: exp(0,hold=True).simplify()
      1

      sage: exp(pi*I/2)
      I
      sage: exp(pi*I)
      -1
      sage: exp(8*pi*I)
      1
      sage: exp(7*pi*I/2)
      -I

  The precision for the result is deduced from the precision of the input. Convert the input to a higher precision explicitly if a result with higher precision is desired:

      sage: t = exp(RealField(100)(2)); t
      7.3890560989306502272304274606
      sage: t.prec()
      100
      sage: exp(2).n(100)
      7.3890560989306502272304274606

  TEST:

      sage: latex(exp(x))
      e^{x}
      sage: latex(exp(sqrt(x)))
      e^{\sqrt{x}}
      sage: latex(exp)
      \exp
      sage: latex(exp(sqrt(x))^x)
      \left(e^{\sqrt{x}}\right)^{x}
      sage: latex(exp(sqrt(x)^x))
      e^{\left(\sqrt{x}^{x}\right)}

  Test conjugates:

      sage: conjugate(exp(x))
      e^conjugate(x)

  Test simplifications when taking powers of exp, #7264:

      sage: var('a,b,c,II')
      (a, b, c, II)
      sage: model_exp = exp(II)**a*(b)
      sage: sol1_l={b: 5.0, a: 1.1}
      sage: model_exp.subs(sol1_l)
      5.00000000000000*(e^II)^1.10000000000000

      sage: exp(3)^II*exp(x)
      (e^3)^II*e^x
      sage: exp(x)*exp(x)
      e^(2*x)
      sage: exp(x)*exp(a)
      e^(a + x)
      sage: exp(x)*exp(a)^2
      e^(2*a + x)

  Another instance of the same problem, #7394:

      sage: 2*sqrt(e)
      2*sqrt(e)

class `sage.functions.log.``Function_lambert_w`

  Bases: `sage.symbolic.function.BuiltinFunction`

  The integral branches of the Lambert W function \(W_n(z)\).

  This function satisfies the equation

  \[z = W_n(z) e^{W_n(z)}\]

  INPUT:

  - `n` - an integer. \(n=0\) corresponds to the principal branch.
  - `z` - a complex number

  If called with a single argument, that argument is `z` and the branch `n` is assumed to be 0 (the principal branch).

  ALGORITHM:

  Numerical evaluation is handled using the mpmath and SciPy libraries.

  REFERENCES:

  - Wikipedia article Lambert_W_function

  EXAMPLES:

  Evaluation of the principal branch:

      sage: lambert_w(1.0)
      0.567143290409784
      sage: lambert_w(-1).n()
      -0.318131505204764 + 1.33723570143069*I
      sage: lambert_w(-1.5 + 5*I)
      1.17418016254171 + 1.10651494102011*I

  Evaluation of other branches:

      sage: lambert_w(2, 1.0)
      -2.40158510486800 + 10.7762995161151*I

  Solutions to certain exponential equations are returned in terms of lambert_w:

      sage: S = solve(e^(5*x)+x==0, x, to_poly_solve=True)
      sage: z = S[0].rhs(); z
      -1/5*lambert_w(5)
      sage: N(z)
      -0.265344933048440

  Check the defining equation numerically at \(z=5\):

      sage: N(lambert_w(5)*exp(lambert_w(5)) - 5)
      0.000000000000000

  There are several special values of the principal branch which are automatically simplified:

      sage: lambert_w(0)
      0
      sage: lambert_w(e)
      1
      sage: lambert_w(-1/e)
      -1

  Integration (of the principal branch) is evaluated using Maxima:

      sage: integrate(lambert_w(x), x)
      (lambert_w(x)^2 - lambert_w(x) + 1)*x/lambert_w(x)
      sage: integrate(lambert_w(x), x, 0, 1)
      (lambert_w(1)^2 - lambert_w(1) + 1)/lambert_w(1) - 1
      sage: integrate(lambert_w(x), x, 0, 1.0)
      0.3303661247616807

  Warning: The integral of a non-principal branch is not implemented, neither is numerical integration using GSL. The `numerical_integral()` function does work if you pass a lambda function:

      sage: numerical_integral(lambda x: lambert_w(x), 0, 1)
      (0.33036612476168054, 3.667800782666048e-15)

class `sage.functions.log.``Function_log`

  Bases: `sage.symbolic.function.GinacFunction`

  The natural logarithm of x. See \(log?\) for more information about its behavior.

  EXAMPLES:

      sage: ln(e^2)
      2
      sage: ln(2)
      log(2)
      sage: ln(10)
      log(10)

      sage: ln(RDF(10))
      2.302585092994046
      sage: ln(2.718)
      0.999896315728952
      sage: ln(2.0)
      0.693147180559945
      sage: ln(float(-1))
      3.141592653589793j
      sage: ln(complex(-1))
      3.141592653589793j

  The `hold` parameter can be used to prevent automatic evaluation:

      sage: log(-1,hold=True)
      log(-1)
      sage: log(-1)
      I*pi
      sage: I.log(hold=True)
      log(I)
      sage: I.log(hold=True).simplify()
      1/2*I*pi

  TESTS:

      sage: latex(x.log())
      \log\left(x\right)
      sage: latex(log(1/4))
      \log\left(\frac{1}{4}\right)
      sage: loads(dumps(ln(x)+1))
      log(x) + 1

  `conjugate(log(x))==log(conjugate(x))` unless on the branch cut which runs along the negative real axis.:

      sage: conjugate(log(x))
      conjugate(log(x))
      sage: var('y', domain='positive')
      y
      sage: conjugate(log(y))
      log(y)
      sage: conjugate(log(y+I))
      conjugate(log(y + I))
      sage: conjugate(log(-1))
      -I*pi
      sage: log(conjugate(-1))
      I*pi

  Check if float arguments are handled properly.:

      sage: from sage.functions.log import function_log as log
      sage: log(float(5))
      1.6094379124341003
      sage: log(float(0))
      -inf
      sage: log(float(-1))
      3.141592653589793j
      sage: log(x).subs(x=float(-1))
      3.141592653589793j

class `sage.functions.log.``Function_polylog`

  Bases: `sage.symbolic.function.GinacFunction`

  The polylog function \(\text{Li}_n(z) = \sum_{k=1}^{\infty} z^k / k^n\).

  INPUT:

  - `n` - object
  - `z` - object

  EXAMPLES:

      sage: polylog(1, x)
      -log(-x + 1)
      sage: polylog(2,1)
      1/6*pi^2
      sage: polylog(2,x^2+1)
      polylog(2, x^2 + 1)
      sage: polylog(4,0.5)
      polylog(4, 0.500000000000000)

      sage: f = polylog(4, 1); f
      1/90*pi^4
      sage: f.n()
      1.08232323371114

      sage: polylog(4, 2).n()
      2.42786280675470 - 0.174371300025453*I
      sage: complex(polylog(4,2))
      (2.4278628067547032-0.17437130002545306j)
      sage: float(polylog(4,0.5))
      0.5174790616738993

      sage: z = var('z')
      sage: polylog(2,z).series(z==0, 5)
      1*z + 1/4*z^2 + 1/9*z^3 + 1/16*z^4 + Order(z^5)

      sage: loads(dumps(polylog))
      polylog

      sage: latex(polylog(5, x))
      {\rm Li}_{5}(x)

  TESTS:

  Check if #8459 is fixed:

      sage: t = maxima(polylog(5,x)).sage(); t
      polylog(5, x)
      sage: t.operator() == polylog
      True
      sage: t.subs(x=.5).n()
      0.508400579242269

### Navigation

- index
- modules |
- next |
- previous |
- Functions »