## `ln` -- the natural logarithm

#### Introduction

`ln``(x)` represents the natural logarithm of x.

#### Call(s)

`ln(x)`

#### Parameters

`x` | - | an arithmetical expression

#### Returns

an arithmetical expression.

### Overloadable:

`x`

#### Side Effects

When called with a floating point argument, the function is sensitive to the environment variable `DIGITS` which determines the numerical working precision.

#### Related Functions

`dilog`, `log`, `polylog`

#### Details

- The logarithm is defined for all complex arguments x <> 0.
- For most exact arguments an unevaluated function call is returned. It is subject to some simplifications:
  - Arguments of the form x = exp(y) with y of the type `Type::Numeric` yield the result ln(exp(y)) = y + k*2*PI*I. Here k is some suitable integer, such that the imaginary part of the result lies in the interval (-PI,PI].
  - Negative integer and rational arguments x are rewritten according to ln(x) = I*PI + ln(-x). Arguments of the form x = 1/n with some integer n are rewritten according to ln(1/n) = -ln(n).
  - The following special values are implemented: ln(1) = 0, ln(-1) = I*PI, ln(+/- I) = +/- I*PI/2, ln(infinity) = infinity, ln(-infinity) = I*PI + infinity.
- Floating point results are computed for floating point arguments. The imaginary part of the result takes values in the interval (-PI,PI]. The negative real axis is a branch cut, the imaginary part of the result jumps when crossing the cut. On the negative real axis, the imaginary part is PI according to ln(x) = I*PI + ln(-x), x < 0. Cf. example 2.
- Note that arithmetical rules such as ln(x*y) = ln(x) + ln(y) are not valid throughout the complex plane. Use properties to mark identifiers as real and apply functions such as `expand`, `combine` or `simplify` to manipulate expressions involving `ln`. Cf. example 4.

#### Example 1

We demonstrate some calls with exact and symbolic input data:

    >> ln(2), ln(-3), ln(1/4), ln(1 + I), ln(x^2)

                                                              2
                  ln(2), I PI + ln(3), -ln(4), ln(1 + I), ln(x )

Floating point values are computed for floating point arguments:

    >> ln(123.4), ln(5.6 + 7.8*I), ln(1.0/10^20)

              4.815431112, 2.261980065 + 0.948125538 I, -46.05170186

Some special symbolic simplifications are implemented:

    >> ln(1), ln(-1), ln(exp(-5)), ln(exp(5 + 27/4*I))

                        0, I PI, -5, (5 + 27/4 I) - 2 I PI

#### Example 2

The negative real axis is a branch cut. The imaginary part of the values returned by `ln` jump when crossing this cut:

    >> ln(-2.0), ln(-2.0 + I/10^1000), ln(-2.0 - I/10^1000)

          0.6931471806 + 3.141592654 I, 0.6931471806 + 3.141592654 I,

             0.6931471806 - 3.141592654 I

#### Example 3

The functions `diff`, `float`, `limit`, `series` etc. handle expressions involving `ln`:

    >> diff(ln(x^2), x), float(ln(PI + I))

                          2
                          -, 1.192985153 + 0.3081690711 I
                          x

    >> limit(ln(x)/x, x = infinity), series(x*ln(sin(x)), x = 0, 10)

                                 3    5      7      9
                                x    x      x      x         10
                   0, x ln(x) - -- - --- - ---- - ----- + O(x  )
                                6    180   2835   37800

#### Example 4

The functions `expand`, `combine`, and `simplify` react to properties set via `assume`. The following call does not produce an expanded result, because the arithmetical rule ln(x*y) = ln(x) + ln(y) does not hold for arbitrary complex x,y:

    >> expand(ln(x*y))

                                      ln(x y)

However, the rule is valid, if one of the factors is real and positive:

    >> assume(x > 0): expand(ln(x*y))

                                   ln(x) + ln(y)

    >> combine(%, ln)

                                      ln(x y)

    >> simplify(ln(x^3*y) - ln(x) - ln(y))

                                      2 ln(x)

    >> unassume(x):

#### Changes

- Minor changes of the simplification rules.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000