1/* specfunc/gsl_sf_dilog.h
2 *
3 * Copyright (C) 1996, 1997, 1998, 1999, 2000, 2004 Gerard Jungman
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 3 of the License, or (at
8 * your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20/* Author: G. Jungman */
21
22#ifndef __GSL_SF_DILOG_H__
23#define __GSL_SF_DILOG_H__
24
25#include <gsl/gsl_sf_result.h>
26
27#undef __BEGIN_DECLS
28#undef __END_DECLS
29#ifdef __cplusplus
30# define __BEGIN_DECLS extern "C" {
31# define __END_DECLS }
32#else
33# define __BEGIN_DECLS /* empty */
34# define __END_DECLS /* empty */
35#endif
36
37__BEGIN_DECLS
38
39
40/* Real part of DiLogarithm(x), for real argument.
41 * In Lewin's notation, this is Li_2(x).
42 *
43 * Li_2(x) = - Re[ Integrate[ Log[1-s] / s, {s, 0, x}] ]
44 *
45 * The function in the complex plane has a branch point
46 * at z = 1; we place the cut in the conventional way,
47 * on [1, +infty). This means that the value for real x > 1
48 * is a matter of definition; however, this choice does not
49 * affect the real part and so is not relevant to the
50 * interpretation of this implemented function.
51 */
52int gsl_sf_dilog_e(const double x, gsl_sf_result * result);
53double gsl_sf_dilog(const double x);
54
55
56/* DiLogarithm(z), for complex argument z = x + i y.
57 * Computes the principal branch.
58 *
59 * Recall that the branch cut is on the real axis with x > 1.
60 * The imaginary part of the computed value on the cut is given
61 * by -Pi*log(x), which is the limiting value taken approaching
62 * from y < 0. This is a conventional choice, though there is no
63 * true standardized choice.
64 *
65 * Note that there is no canonical way to lift the defining
66 * contour to the full Riemann surface because of the appearance
67 * of a "hidden branch point" at z = 0 on non-principal sheets.
68 * Experts will know the simple algebraic prescription for
69 * obtaining the sheet they want; non-experts will not want
70 * to know anything about it. This is why GSL chooses to compute
71 * only on the principal branch.
72 */
73int
74gsl_sf_complex_dilog_xy_e(
75 const double x,
76 const double y,
77 gsl_sf_result * result_re,
78 gsl_sf_result * result_im
79 );
80
81
82
83/* DiLogarithm(z), for complex argument z = r Exp[i theta].
84 * Computes the principal branch, thereby assuming an
85 * implicit reduction of theta to the range (-2 pi, 2 pi).
86 *
87 * If theta is identically zero, the imaginary part is computed
88 * as if approaching from y > 0. For other values of theta no
89 * special consideration is given, since it is assumed that
90 * no other machine representations of multiples of pi will
91 * produce y = 0 precisely. This assumption depends on some
92 * subtle properties of the machine arithmetic, such as
93 * correct rounding and monotonicity of the underlying
94 * implementation of sin() and cos().
95 *
96 * This function is ok, but the interface is confusing since
97 * it makes it appear that the branch structure is resolved.
98 * Furthermore the handling of values close to the branch
99 * cut is subtle. Perhap this interface should be deprecated.
100 */
101int
102gsl_sf_complex_dilog_e(
103 const double r,
104 const double theta,
105 gsl_sf_result * result_re,
106 gsl_sf_result * result_im
107 );
108
109
110
111/* Spence integral; spence(s) := Li_2(1-s)
112 *
113 * This function has a branch point at 0; we place the
114 * cut on (-infty,0). Because of our choice for the value
115 * of Li_2(z) on the cut, spence(s) is continuous as
116 * s approaches the cut from above. In other words,
117 * we define spence(x) = spence(x + i 0+).
118 */
119int
120gsl_sf_complex_spence_xy_e(
121 const double x,
122 const double y,
123 gsl_sf_result * real_sp,
124 gsl_sf_result * imag_sp
125 );
126
127
128__END_DECLS
129
130#endif /* __GSL_SF_DILOG_H__ */
131