htswanalysis/MACS/lib/gsl/gsl-1.11/specfunc/gsl_sf_dilog.h

   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  */
  52 int     gsl_sf_dilog_e(const double x, gsl_sf_result * result);
  53 double  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  */
  73 int
  74 gsl_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  */
 101 int
 102 gsl_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  */
 119 int
 120 gsl_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__ */