include/gsl/gsl_sf_dilog.h

0001 /* specfunc/gsl_sf_dilog.h
0002  *
0003  * Copyright (C) 1996, 1997, 1998, 1999, 2000, 2004 Gerard Jungman
0004  *
0005  * This program is free software; you can redistribute it and/or modify
0006  * it under the terms of the GNU General Public License as published by
0007  * the Free Software Foundation; either version 3 of the License, or (at
0008  * your option) any later version.
0009  *
0010  * This program is distributed in the hope that it will be useful, but
0011  * WITHOUT ANY WARRANTY; without even the implied warranty of
0012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013  * General Public License for more details.
0014  *
0015  * You should have received a copy of the GNU General Public License
0016  * along with this program; if not, write to the Free Software
0017  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
0018  */
0019
0020 /* Author:  G. Jungman */
0021
0022 #ifndef __GSL_SF_DILOG_H__
0023 #define __GSL_SF_DILOG_H__
0024
0025 #include <gsl/gsl_sf_result.h>
0026
0027 #undef __BEGIN_DECLS
0028 #undef __END_DECLS
0029 #ifdef __cplusplus
0030 # define __BEGIN_DECLS extern "C" {
0031 # define __END_DECLS }
0032 #else
0033 # define __BEGIN_DECLS /* empty */
0034 # define __END_DECLS /* empty */
0035 #endif
0036
0037 __BEGIN_DECLS
0038
0039
0040 /* Real part of DiLogarithm(x), for real argument.
0041  * In Lewin's notation, this is Li_2(x).
0042  *
0043  *   Li_2(x) = - Re[ Integrate[ Log[1-s] / s, {s, 0, x}] ]
0044  *
0045  * The function in the complex plane has a branch point
0046  * at z = 1; we place the cut in the conventional way,
0047  * on [1, +infty). This means that the value for real x > 1
0048  * is a matter of definition; however, this choice does not
0049  * affect the real part and so is not relevant to the
0050  * interpretation of this implemented function.
0051  */
0052 int     gsl_sf_dilog_e(const double x, gsl_sf_result * result);
0053 double  gsl_sf_dilog(const double x);
0054
0055
0056 /* DiLogarithm(z), for complex argument z = x + i y.
0057  * Computes the principal branch.
0058  *
0059  * Recall that the branch cut is on the real axis with x > 1.
0060  * The imaginary part of the computed value on the cut is given
0061  * by -Pi*log(x), which is the limiting value taken approaching
0062  * from y < 0. This is a conventional choice, though there is no
0063  * true standardized choice.
0064  *
0065  * Note that there is no canonical way to lift the defining
0066  * contour to the full Riemann surface because of the appearance
0067  * of a "hidden branch point" at z = 0 on non-principal sheets.
0068  * Experts will know the simple algebraic prescription for
0069  * obtaining the sheet they want; non-experts will not want
0070  * to know anything about it. This is why GSL chooses to compute
0071  * only on the principal branch.
0072  */
0073 int
0074 gsl_sf_complex_dilog_xy_e(
0075   const double x,
0076   const double y,
0077   gsl_sf_result * result_re,
0078   gsl_sf_result * result_im
0079   );
0080
0081
0082
0083 /* DiLogarithm(z), for complex argument z = r Exp[i theta].
0084  * Computes the principal branch, thereby assuming an
0085  * implicit reduction of theta to the range (-2 pi, 2 pi).
0086  *
0087  * If theta is identically zero, the imaginary part is computed
0088  * as if approaching from y > 0. For other values of theta no
0089  * special consideration is given, since it is assumed that
0090  * no other machine representations of multiples of pi will
0091  * produce y = 0 precisely. This assumption depends on some
0092  * subtle properties of the machine arithmetic, such as
0093  * correct rounding and monotonicity of the underlying
0094  * implementation of sin() and cos().
0095  *
0096  * This function is ok, but the interface is confusing since
0097  * it makes it appear that the branch structure is resolved.
0098  * Furthermore the handling of values close to the branch
0099  * cut is subtle. Perhap this interface should be deprecated.
0100  */
0101 int
0102 gsl_sf_complex_dilog_e(
0103   const double r,
0104   const double theta,
0105   gsl_sf_result * result_re,
0106   gsl_sf_result * result_im
0107   );
0108
0109
0110
0111 /* Spence integral; spence(s) := Li_2(1-s)
0112  *
0113  * This function has a branch point at 0; we place the
0114  * cut on (-infty,0). Because of our choice for the value
0115  * of Li_2(z) on the cut, spence(s) is continuous as
0116  * s approaches the cut from above. In other words,
0117  * we define spence(x) = spence(x + i 0+).
0118  */
0119 int
0120 gsl_sf_complex_spence_xy_e(
0121   const double x,
0122   const double y,
0123   gsl_sf_result * real_sp,
0124   gsl_sf_result * imag_sp
0125   );
0126
0127
0128 __END_DECLS
0129
0130 #endif /* __GSL_SF_DILOG_H__ */