# Logarithmic functions¶

AUTHORS:

class sage.functions.log.Function_dilog

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

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.1824939607


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


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

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:

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.330366124762


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

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.30258509299
sage: ln(2.718)
0.999896315728952
sage: ln(2.0)
0.693147180559945
sage: ln(float(-1))
3.141592653589793j
sage: ln(complex(-1))
3.141592653589793j


We do not currently support a hold parameter in functional notation:

sage: log(SR(-1),hold=True)
Traceback (most recent call last):
...
TypeError: log() got an unexpected keyword argument 'hold'


This is possible with method notation:

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)
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

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)

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

sage.functions.log.log(x, base=None)

Return the logarithm of x to the given base.

Calls the log method of the object x when computing the logarithm, thus allowing use of logarithm on any object containing a log method. In other words, log works on more than just real numbers.

EXAMPLES:

sage: log(e^2)
2


To change the base of the logarithm, add a second parameter:

sage: log(1000,10)
3


You can use RDF, RealField or n to get a numerical real approximation:

sage: log(1024, 2)
10
sage: RDF(log(1024, 2))
10.0
sage: log(10, 4)
log(10)/log(4)
sage: RDF(log(10, 4))
1.66096404744
sage: log(10, 2)
log(10)/log(2)
sage: n(log(10, 2))
3.32192809488736
sage: log(10, e)
log(10)
sage: n(log(10, e))
2.30258509299405


The log function works for negative numbers, complex numbers, and symbolic numbers too, picking the branch with angle between $$-pi$$ and $$pi$$:

sage: log(-1+0*I)
I*pi
sage: log(CC(-1))
3.14159265358979*I
sage: log(-1.0)
3.14159265358979*I


For input zero, the following behavior occurs:

sage: log(0)
-Infinity
sage: log(CC(0))
-infinity
sage: log(0.0)
-infinity


The log function also works in finite fields as long as the argument lies in the multiplicative group generated by the base:

sage: F = GF(13); g = F.multiplicative_generator(); g
2
sage: a = F(8)
sage: log(a,g); g^log(a,g)
3
8
sage: log(a,3)
Traceback (most recent call last):
...
ValueError: No discrete log of 8 found to base 3
sage: log(F(9), 3)
2


sage: R = Zp(5); R
5-adic Ring with capped relative precision 20
sage: a = R(16); a
1 + 3*5 + O(5^20)
sage: log(a)
3*5 + 3*5^2 + 3*5^4 + 3*5^5 + 3*5^6 + 4*5^7 + 2*5^8 + 5^9 + 5^11 + 2*5^12 + 5^13 + 3*5^15 + 2*5^16 + 4*5^17 + 3*5^18 + 3*5^19 + O(5^20)


Functions

#### Next topic

Trigonometric Functions