## `dilog` -- the dilogarithm function

#### Introduction

`dilog``(x)` represents the dilogarithm function int(ln(t)/(1-t), t=1..x).

#### Call(s)

`dilog(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

`ln`, `polylog`

#### Details

- If `x` is a floating point number, then `dilog``(x)` returns the numerical value of the dilogarithm function. The special values:

  `dilog(-1)` = PI^2/4-I*PI*ln(2),

  `dilog(0)` = PI^2/6,

  `dilog(1/2)` = PI^2/12-ln(2)^2/2,

  `dilog(1)` = 0,

  `dilog(2)` = -PI^2/12,

  `dilog(I)` = PI^2/16-I*CATALAN-I*PI*ln(2)/4,

  `dilog(-I)`= PI^2/16+I*CATALAN+I*PI*ln(2)/4,

  `dilog(1+I)` = -PI^2/48-I*CATALAN,

  `dilog(1-I)` = -PI^2/48+I*CATALAN,

  `dilog(infinity)` = `-infinity`

  are implemented. For all other arguments, `dilog` returns a symbolic function call.

- Functional identities are used to rewrite the result for exact numerical arguments of `Type::Numeric` that have a negative real part or are of absolute value larger than 1. Cf. example 2.
- `dilog``(x)` coincides with `polylog``(2, 1-x)`.

#### Example 1

We demonstrate some calls with exact and symbolic input data:

    >> dilog(0), dilog(2/3), dilog(sqrt(2)), dilog(1 + I), dilog(x)

               2                                           2
             PI                      1/2                 PI
             ---, dilog(2/3), dilog(2   ), - I CATALAN - ---, dilog(x)
              6                                          48

Floating point values are computed for floating point arguments:

    >> dilog(-1.2), dilog(3.4 - 5.6*I)

             2.458586602 - 2.477011851 I, - 2.529187195 + 2.25273709 I

#### Example 2

Arguments built from integers and rational numbers are rewritten, if they lie in the left half of the complex plane or are of absolute value larger than 1. The following arguments have a negative real part:

    >> dilog(-400/3), dilog(-1/2 + I)

            2                           2
          PI                   ln(403/3)
          --- + dilog(3/403) + ---------- - ln(403/3) (I PI + ln(400/3))
           6                       2

                 2              2
               PI    ln(3/2 - I)
             , --- + ------------ + dilog(6/13 + 4/13 I) -
                6         2

             ln(- 1/2 + I) ln(3/2 - I)

The following arguments have an absolute value larger than 1:

    >> dilog(31/30), dilog(1 + 2/3*I)

                                    2                 2
                           ln(31/30)     ln(1 + 2/3 I)
          - dilog(30/31) - ----------, - -------------- -
                               2               2

             dilog(9/13 - 6/13 I)

#### Example 3

The negative real axis is a branch cut of `dilog`. A jump of height I*2*PI*ln(1-x) occurs when crossing this cut at the real point x<0:

    >> dilog(-1.2), dilog(-1.2 + I/10^100), dilog(-1.2 - I/10^100)

          2.458586602 - 2.477011851 I, 2.458586602 - 2.477011851 I,

             2.458586602 + 2.477011851 I

#### Example 4

The functions `diff`, `float`, `limit`, and `series` handle expressions involving `dilog`:

    >> diff(dilog(x), x, x, x), float(ln(3 + dilog(sqrt(PI))))

                 2 ln(x)        2            1
                 -------- + ---------- - ----------, 0.8503829845
                        3            2    2
                 (1 - x)    x (1 - x)    x  (1 - x)

    >> limit(dilog(x^10 + 1)/x, x = infinity)

                                         0

    >> series(dilog(x + 1/x)/x, x = -infinity, 4)

                   2        2
                 PI    ln(x)                  ln(x)
               - --- - ------               - ----- + 1/4
                  6      2      ln(x) + 1       2            / 1  \
               -------------- + --------- + ------------- + O| -- |
                     x              2             3          |  4 |
                                   x             x           \ x  /

#### Background

- `dilog``(x)` coincides with sum((1-x)^k/k^2,k=1..infinity) for |x|<1.
- `dilog` has a branch cut along the negative real axis. The value at a point x on the cut coincides with the limit ``from above'':

               dilog(x)
                =limit(dilog(x+eps*I), eps=0, Right)
                =limit(dilog(x+eps*I), eps=0, Left) - 2*PI*I*ln(1-x).

- Reference: L. Lewin (ed.), ``Structural Properties of Polylogarithms'', Mathematical Surveys and Monographs Vol. 37, American Mathematical Society, Providence (1991).

#### Changes

- Rewriting rules and special values were implemented. The `series` attribute was added.

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