htswanalysis/MACS/lib/gsl/gsl-1.11/doc/complex.texi

   1 @cindex complex numbers
   2
   3 The functions described in this chapter provide support for complex
   4 numbers.  The algorithms take care to avoid unnecessary intermediate
   5 underflows and overflows, allowing the functions to be evaluated over
   6 as much of the complex plane as possible.
   7
   8 @comment FIXME: this still needs to be
   9 @comment done for the csc,sec,cot,csch,sech,coth functions
  10
  11 For multiple-valued functions the branch cuts have been chosen to follow
  12 the conventions of Abramowitz and Stegun in the @cite{Handbook of
  13 Mathematical Functions}. The functions return principal values which are
  14 the same as those in GNU Calc, which in turn are the same as those in
  15 @cite{Common Lisp, The Language (Second Edition)}@footnote{Note that the
  16 first edition uses different definitions.} and the HP-28/48 series of
  17 calculators.
  18
  19 The complex types are defined in the header file @file{gsl_complex.h},
  20 while the corresponding complex functions and arithmetic operations are
  21 defined in @file{gsl_complex_math.h}.
  22
  23 @menu
  24 * Complex numbers::
  25 * Properties of complex numbers::
  26 * Complex arithmetic operators::
  27 * Elementary Complex Functions::
  28 * Complex Trigonometric Functions::
  29 * Inverse Complex Trigonometric Functions::
  30 * Complex Hyperbolic Functions::
  31 * Inverse Complex Hyperbolic Functions::
  32 * Complex Number References and Further Reading::
  33 @end menu
  34
  35 @node Complex numbers
  36 @section Complex numbers
  37 @cindex representations of complex numbers
  38 @cindex polar form of complex numbers
  39 @tindex gsl_complex
  40
  41 Complex numbers are represented using the type @code{gsl_complex}. The
  42 internal representation of this type may vary across platforms and
  43 should not be accessed directly. The functions and macros described
  44 below allow complex numbers to be manipulated in a portable way.
  45
  46 For reference, the default form of the @code{gsl_complex} type is
  47 given by the following struct,
  48
  49 @example
  50 typedef struct
  51 @{
  52   double dat[2];
  53 @} gsl_complex;
  54 @end example
  55
  56 @noindent
  57 The real and imaginary part are stored in contiguous elements of a two
  58 element array. This eliminates any padding between the real and
  59 imaginary parts, @code{dat[0]} and @code{dat[1]}, allowing the struct to
  60 be mapped correctly onto packed complex arrays.
  61
  62 @deftypefun gsl_complex gsl_complex_rect (double @var{x}, double @var{y})
  63 This function uses the rectangular cartesian components
  64 (@var{x},@var{y}) to return the complex number @math{z = x + i y}.  @inlinefn{}
  65 @end deftypefun
  66
  67 @deftypefun gsl_complex gsl_complex_polar (double @var{r}, double @var{theta})
  68 This function returns the complex number @math{z = r \exp(i \theta) = r
  69 (\cos(\theta) + i \sin(\theta))} from the polar representation
  70 (@var{r},@var{theta}).
  71 @end deftypefun
  72
  73 @defmac GSL_REAL (@var{z})
  74 @defmacx GSL_IMAG (@var{z})
  75 These macros return the real and imaginary parts of the complex number
  76 @var{z}.
  77 @end defmac
  78
  79 @defmac GSL_SET_COMPLEX (@var{zp}, @var{x}, @var{y})
  80 This macro uses the cartesian components (@var{x},@var{y}) to set the
  81 real and imaginary parts of the complex number pointed to by @var{zp}.
  82 For example,
  83
  84 @example
  85 GSL_SET_COMPLEX(&z, 3, 4)
  86 @end example
  87
  88 @noindent
  89 sets @var{z} to be @math{3 + 4i}.
  90 @end defmac
  91
  92 @defmac GSL_SET_REAL (@var{zp},@var{x})
  93 @defmacx GSL_SET_IMAG (@var{zp},@var{y})
  94 These macros allow the real and imaginary parts of the complex number
  95 pointed to by @var{zp} to be set independently.
  96 @end defmac
  97
  98 @node Properties of complex numbers
  99 @section Properties of complex numbers
 100
 101 @deftypefun double gsl_complex_arg (gsl_complex @var{z})
 102 @cindex argument of complex number
 103 This function returns the argument of the complex number @var{z},
 104 @math{\arg(z)}, where @c{$-\pi < \arg(z) \leq \pi$}
 105 @math{-\pi < \arg(z) <= \pi}.
 106 @end deftypefun
 107
 108 @deftypefun double gsl_complex_abs (gsl_complex @var{z})
 109 @cindex magnitude of complex number
 110 This function returns the magnitude of the complex number @var{z}, @math{|z|}.
 111 @end deftypefun
 112
 113 @deftypefun double gsl_complex_abs2 (gsl_complex @var{z})
 114 This function returns the squared magnitude of the complex number
 115 @var{z}, @math{|z|^2}.
 116 @end deftypefun
 117
 118 @deftypefun double gsl_complex_logabs (gsl_complex @var{z})
 119 This function returns the natural logarithm of the magnitude of the
 120 complex number @var{z}, @math{\log|z|}.  It allows an accurate
 121 evaluation of @math{\log|z|} when @math{|z|} is close to one. The direct
 122 evaluation of @code{log(gsl_complex_abs(z))} would lead to a loss of
 123 precision in this case.
 124 @end deftypefun
 125
 126
 127 @node Complex arithmetic operators
 128 @section Complex arithmetic operators
 129 @cindex complex arithmetic
 130
 131 @deftypefun gsl_complex gsl_complex_add (gsl_complex @var{a}, gsl_complex @var{b})
 132 This function returns the sum of the complex numbers @var{a} and
 133 @var{b}, @math{z=a+b}.
 134 @end deftypefun
 135
 136 @deftypefun gsl_complex gsl_complex_sub (gsl_complex @var{a}, gsl_complex @var{b})
 137 This function returns the difference of the complex numbers @var{a} and
 138 @var{b}, @math{z=a-b}.
 139 @end deftypefun
 140
 141 @deftypefun gsl_complex gsl_complex_mul (gsl_complex @var{a}, gsl_complex @var{b})
 142 This function returns the product of the complex numbers @var{a} and
 143 @var{b}, @math{z=ab}.
 144 @end deftypefun
 145
 146 @deftypefun gsl_complex gsl_complex_div (gsl_complex @var{a}, gsl_complex @var{b})
 147 This function returns the quotient of the complex numbers @var{a} and
 148 @var{b}, @math{z=a/b}.
 149 @end deftypefun
 150
 151
 152 @deftypefun gsl_complex gsl_complex_add_real (gsl_complex @var{a}, double @var{x})
 153 This function returns the sum of the complex number @var{a} and the
 154 real number @var{x}, @math{z=a+x}.
 155 @end deftypefun
 156
 157 @deftypefun gsl_complex gsl_complex_sub_real (gsl_complex @var{a}, double @var{x})
 158 This function returns the difference of the complex number @var{a} and the
 159 real number @var{x}, @math{z=a-x}.
 160 @end deftypefun
 161
 162 @deftypefun gsl_complex gsl_complex_mul_real (gsl_complex @var{a}, double @var{x})
 163 This function returns the product of the complex number @var{a} and the
 164 real number @var{x}, @math{z=ax}.
 165 @end deftypefun
 166
 167 @deftypefun gsl_complex gsl_complex_div_real (gsl_complex @var{a}, double @var{x})
 168 This function returns the quotient of the complex number @var{a} and the
 169 real number @var{x}, @math{z=a/x}.
 170 @end deftypefun
 171
 172 @deftypefun gsl_complex gsl_complex_add_imag (gsl_complex @var{a}, double @var{y})
 173 This function returns the sum of the complex number @var{a} and the
 174 imaginary number @math{i}@var{y}, @math{z=a+iy}.
 175 @end deftypefun
 176
 177 @deftypefun gsl_complex gsl_complex_sub_imag (gsl_complex @var{a}, double @var{y})
 178 This function returns the difference of the complex number @var{a} and the
 179 imaginary number @math{i}@var{y}, @math{z=a-iy}.
 180 @end deftypefun
 181
 182 @deftypefun gsl_complex gsl_complex_mul_imag (gsl_complex @var{a}, double @var{y})
 183 This function returns the product of the complex number @var{a} and the
 184 imaginary number @math{i}@var{y}, @math{z=a*(iy)}.
 185 @end deftypefun
 186
 187 @deftypefun gsl_complex gsl_complex_div_imag (gsl_complex @var{a}, double @var{y})
 188 This function returns the quotient of the complex number @var{a} and the
 189 imaginary number @math{i}@var{y}, @math{z=a/(iy)}.
 190 @end deftypefun
 191
 192 @deftypefun gsl_complex gsl_complex_conjugate (gsl_complex @var{z})
 193 @cindex conjugate of complex number
 194 This function returns the complex conjugate of the complex number
 195 @var{z}, @math{z^* = x - i y}.
 196 @end deftypefun
 197
 198 @deftypefun gsl_complex gsl_complex_inverse (gsl_complex @var{z})
 199 This function returns the inverse, or reciprocal, of the complex number
 200 @var{z}, @math{1/z = (x - i y)/(x^2 + y^2)}.
 201 @end deftypefun
 202
 203 @deftypefun gsl_complex gsl_complex_negative (gsl_complex @var{z})
 204 This function returns the negative of the complex number
 205 @var{z}, @math{-z = (-x) + i(-y)}.
 206 @end deftypefun
 207
 208
 209 @node Elementary Complex Functions
 210 @section Elementary Complex Functions
 211
 212 @deftypefun gsl_complex gsl_complex_sqrt (gsl_complex @var{z})
 213 @cindex square root of complex number
 214 This function returns the square root of the complex number @var{z},
 215 @math{\sqrt z}. The branch cut is the negative real axis. The result
 216 always lies in the right half of the complex plane.
 217 @end deftypefun
 218
 219 @deftypefun gsl_complex gsl_complex_sqrt_real (double @var{x})
 220 This function returns the complex square root of the real number
 221 @var{x}, where @var{x} may be negative.
 222 @end deftypefun
 223
 224
 225 @deftypefun gsl_complex gsl_complex_pow (gsl_complex @var{z}, gsl_complex @var{a})
 226 @cindex power of complex number
 227 @cindex exponentiation of complex number
 228 The function returns the complex number @var{z} raised to the complex
 229 power @var{a}, @math{z^a}. This is computed as @math{\exp(\log(z)*a)}
 230 using complex logarithms and complex exponentials.
 231 @end deftypefun
 232
 233 @deftypefun gsl_complex gsl_complex_pow_real (gsl_complex @var{z}, double @var{x})
 234 This function returns the complex number @var{z} raised to the real
 235 power @var{x}, @math{z^x}.
 236 @end deftypefun
 237
 238
 239 @deftypefun gsl_complex gsl_complex_exp (gsl_complex @var{z})
 240 This function returns the complex exponential of the complex number
 241 @var{z}, @math{\exp(z)}.
 242 @end deftypefun
 243
 244 @deftypefun gsl_complex gsl_complex_log (gsl_complex @var{z})
 245 @cindex logarithm of complex number
 246 This function returns the complex natural logarithm (base @math{e}) of
 247 the complex number @var{z}, @math{\log(z)}.  The branch cut is the
 248 negative real axis.
 249 @end deftypefun
 250
 251 @deftypefun gsl_complex gsl_complex_log10 (gsl_complex @var{z})
 252 This function returns the complex base-10 logarithm of
 253 the complex number @var{z}, @c{$\log_{10}(z)$}
 254 @math{\log_10 (z)}.
 255 @end deftypefun
 256
 257 @deftypefun gsl_complex gsl_complex_log_b (gsl_complex @var{z}, gsl_complex @var{b})
 258 This function returns the complex base-@var{b} logarithm of the complex
 259 number @var{z}, @math{\log_b(z)}. This quantity is computed as the ratio
 260 @math{\log(z)/\log(b)}.
 261 @end deftypefun
 262
 263
 264 @node Complex Trigonometric Functions
 265 @section Complex Trigonometric Functions
 266 @cindex trigonometric functions of complex numbers
 267
 268 @deftypefun gsl_complex gsl_complex_sin (gsl_complex @var{z})
 269 @cindex sin, of complex number
 270 This function returns the complex sine of the complex number @var{z},
 271 @math{\sin(z) = (\exp(iz) - \exp(-iz))/(2i)}.
 272 @end deftypefun
 273
 274 @deftypefun gsl_complex gsl_complex_cos (gsl_complex @var{z})
 275 @cindex cosine of complex number
 276 This function returns the complex cosine of the complex number @var{z},
 277 @math{\cos(z) = (\exp(iz) + \exp(-iz))/2}.
 278 @end deftypefun
 279
 280 @deftypefun gsl_complex gsl_complex_tan (gsl_complex @var{z})
 281 @cindex tangent of complex number
 282 This function returns the complex tangent of the complex number @var{z},
 283 @math{\tan(z) = \sin(z)/\cos(z)}.
 284 @end deftypefun
 285
 286 @deftypefun gsl_complex gsl_complex_sec (gsl_complex @var{z})
 287 This function returns the complex secant of the complex number @var{z},
 288 @math{\sec(z) = 1/\cos(z)}.
 289 @end deftypefun
 290
 291 @deftypefun gsl_complex gsl_complex_csc (gsl_complex @var{z})
 292 This function returns the complex cosecant of the complex number @var{z},
 293 @math{\csc(z) = 1/\sin(z)}.
 294 @end deftypefun
 295
 296 @deftypefun gsl_complex gsl_complex_cot (gsl_complex @var{z})
 297 This function returns the complex cotangent of the complex number @var{z},
 298 @math{\cot(z) = 1/\tan(z)}.
 299 @end deftypefun
 300
 301
 302 @node Inverse Complex Trigonometric Functions
 303 @section Inverse Complex Trigonometric Functions
 304 @cindex inverse complex trigonometric functions
 305
 306 @deftypefun gsl_complex gsl_complex_arcsin (gsl_complex @var{z})
 307 This function returns the complex arcsine of the complex number @var{z},
 308 @math{\arcsin(z)}. The branch cuts are on the real axis, less than @math{-1}
 309 and greater than @math{1}.
 310 @end deftypefun
 311
 312 @deftypefun gsl_complex gsl_complex_arcsin_real (double @var{z})
 313 This function returns the complex arcsine of the real number @var{z},
 314 @math{\arcsin(z)}. For @math{z} between @math{-1} and @math{1}, the
 315 function returns a real value in the range @math{[-\pi/2,\pi/2]}. For
 316 @math{z} less than @math{-1} the result has a real part of @math{-\pi/2}
 317 and a positive imaginary part.  For @math{z} greater than @math{1} the
 318 result has a real part of @math{\pi/2} and a negative imaginary part.
 319 @end deftypefun
 320
 321 @deftypefun gsl_complex gsl_complex_arccos (gsl_complex @var{z})
 322 This function returns the complex arccosine of the complex number @var{z},
 323 @math{\arccos(z)}. The branch cuts are on the real axis, less than @math{-1}
 324 and greater than @math{1}.
 325 @end deftypefun
 326
 327 @deftypefun gsl_complex gsl_complex_arccos_real (double @var{z})
 328 This function returns the complex arccosine of the real number @var{z},
 329 @math{\arccos(z)}. For @math{z} between @math{-1} and @math{1}, the
 330 function returns a real value in the range @math{[0,\pi]}. For @math{z}
 331 less than @math{-1} the result has a real part of @math{\pi} and a
 332 negative imaginary part.  For @math{z} greater than @math{1} the result
 333 is purely imaginary and positive.
 334 @end deftypefun
 335
 336 @deftypefun gsl_complex gsl_complex_arctan (gsl_complex @var{z})
 337 This function returns the complex arctangent of the complex number
 338 @var{z}, @math{\arctan(z)}. The branch cuts are on the imaginary axis,
 339 below @math{-i} and above @math{i}.
 340 @end deftypefun
 341
 342 @deftypefun gsl_complex gsl_complex_arcsec (gsl_complex @var{z})
 343 This function returns the complex arcsecant of the complex number @var{z},
 344 @math{\arcsec(z) = \arccos(1/z)}.
 345 @end deftypefun
 346
 347 @deftypefun gsl_complex gsl_complex_arcsec_real (double @var{z})
 348 This function returns the complex arcsecant of the real number @var{z},
 349 @math{\arcsec(z) = \arccos(1/z)}.
 350 @end deftypefun
 351
 352 @deftypefun gsl_complex gsl_complex_arccsc (gsl_complex @var{z})
 353 This function returns the complex arccosecant of the complex number @var{z},
 354 @math{\arccsc(z) = \arcsin(1/z)}.
 355 @end deftypefun
 356
 357 @deftypefun gsl_complex gsl_complex_arccsc_real (double @var{z})
 358 This function returns the complex arccosecant of the real number @var{z},
 359 @math{\arccsc(z) = \arcsin(1/z)}.
 360 @end deftypefun
 361
 362 @deftypefun gsl_complex gsl_complex_arccot (gsl_complex @var{z})
 363 This function returns the complex arccotangent of the complex number @var{z},
 364 @math{\arccot(z) = \arctan(1/z)}.
 365 @end deftypefun
 366
 367
 368 @node Complex Hyperbolic Functions
 369 @section Complex Hyperbolic Functions
 370 @cindex hyperbolic functions, complex numbers
 371
 372 @deftypefun gsl_complex gsl_complex_sinh (gsl_complex @var{z})
 373 This function returns the complex hyperbolic sine of the complex number
 374 @var{z}, @math{\sinh(z) = (\exp(z) - \exp(-z))/2}.
 375 @end deftypefun
 376
 377 @deftypefun gsl_complex gsl_complex_cosh (gsl_complex @var{z})
 378 This function returns the complex hyperbolic cosine of the complex number
 379 @var{z}, @math{\cosh(z) = (\exp(z) + \exp(-z))/2}.
 380 @end deftypefun
 381
 382 @deftypefun gsl_complex gsl_complex_tanh (gsl_complex @var{z})
 383 This function returns the complex hyperbolic tangent of the complex number
 384 @var{z}, @math{\tanh(z) = \sinh(z)/\cosh(z)}.
 385 @end deftypefun
 386
 387
 388 @deftypefun gsl_complex gsl_complex_sech (gsl_complex @var{z})
 389 This function returns the complex hyperbolic secant of the complex
 390 number @var{z}, @math{\sech(z) = 1/\cosh(z)}.
 391 @end deftypefun
 392
 393 @deftypefun gsl_complex gsl_complex_csch (gsl_complex @var{z})
 394 This function returns the complex hyperbolic cosecant of the complex
 395 number @var{z}, @math{\csch(z) = 1/\sinh(z)}.
 396 @end deftypefun
 397
 398 @deftypefun gsl_complex gsl_complex_coth (gsl_complex @var{z})
 399 This function returns the complex hyperbolic cotangent of the complex
 400 number @var{z}, @math{\coth(z) = 1/\tanh(z)}.
 401 @end deftypefun
 402
 403
 404 @node Inverse Complex Hyperbolic Functions
 405 @section Inverse Complex Hyperbolic Functions
 406 @cindex inverse hyperbolic functions, complex numbers
 407
 408 @deftypefun gsl_complex gsl_complex_arcsinh (gsl_complex @var{z})
 409 This function returns the complex hyperbolic arcsine of the
 410 complex number @var{z}, @math{\arcsinh(z)}.  The branch cuts are on the
 411 imaginary axis, below @math{-i} and above @math{i}.
 412 @end deftypefun
 413
 414 @deftypefun gsl_complex gsl_complex_arccosh (gsl_complex @var{z})
 415 This function returns the complex hyperbolic arccosine of the complex
 416 number @var{z}, @math{\arccosh(z)}.  The branch cut is on the real
 417 axis, less than @math{1}.  Note that in this case we use the negative
 418 square root in formula 4.6.21 of Abramowitz & Stegun giving
 419 @c{$\arccosh(z)=\log(z-\sqrt{z^2-1})$}
 420 @math{\arccosh(z)=\log(z-\sqrt@{z^2-1@})}.
 421 @end deftypefun
 422
 423 @deftypefun gsl_complex gsl_complex_arccosh_real (double @var{z})
 424 This function returns the complex hyperbolic arccosine of
 425 the real number @var{z}, @math{\arccosh(z)}.
 426 @end deftypefun
 427
 428 @deftypefun gsl_complex gsl_complex_arctanh (gsl_complex @var{z})
 429 This function returns the complex hyperbolic arctangent of the complex
 430 number @var{z}, @math{\arctanh(z)}.  The branch cuts are on the real
 431 axis, less than @math{-1} and greater than @math{1}.
 432 @end deftypefun
 433
 434 @deftypefun gsl_complex gsl_complex_arctanh_real (double @var{z})
 435 This function returns the complex hyperbolic arctangent of the real
 436 number @var{z}, @math{\arctanh(z)}.
 437 @end deftypefun
 438
 439 @deftypefun gsl_complex gsl_complex_arcsech (gsl_complex @var{z})
 440 This function returns the complex hyperbolic arcsecant of the complex
 441 number @var{z}, @math{\arcsech(z) = \arccosh(1/z)}.
 442 @end deftypefun
 443
 444 @deftypefun gsl_complex gsl_complex_arccsch (gsl_complex @var{z})
 445 This function returns the complex hyperbolic arccosecant of the complex
 446 number @var{z}, @math{\arccsch(z) = \arcsin(1/z)}.
 447 @end deftypefun
 448
 449 @deftypefun gsl_complex gsl_complex_arccoth (gsl_complex @var{z})
 450 This function returns the complex hyperbolic arccotangent of the complex
 451 number @var{z}, @math{\arccoth(z) = \arctanh(1/z)}.
 452 @end deftypefun
 453
 454 @node Complex Number References and Further Reading
 455 @section References and Further Reading
 456
 457 The implementations of the elementary and trigonometric functions are
 458 based on the following papers,
 459
 460 @itemize @asis
 461 @item
 462 T. E. Hull, Thomas F. Fairgrieve, Ping Tak Peter Tang,
 463 ``Implementing Complex Elementary Functions Using Exception
 464 Handling'', @cite{ACM Transactions on Mathematical Software}, Volume 20
 465 (1994), pp 215--244, Corrigenda, p553
 466
 467 @item
 468 T. E. Hull, Thomas F. Fairgrieve, Ping Tak Peter Tang,
 469 ``Implementing the complex arcsin and arccosine functions using exception
 470 handling'', @cite{ACM Transactions on Mathematical Software}, Volume 23
 471 (1997) pp 299--335
 472 @end itemize
 473
 474 @noindent
 475 The general formulas and details of branch cuts can be found in the
 476 following books,
 477
 478 @itemize @asis
 479 @item
 480 Abramowitz and Stegun, @cite{Handbook of Mathematical Functions},
 481 ``Circular Functions in Terms of Real and Imaginary Parts'', Formulas
 482 4.3.55--58,
 483 ``Inverse Circular Functions in Terms of Real and Imaginary Parts'',
 484 Formulas 4.4.37--39,
 485 ``Hyperbolic Functions in Terms of Real and Imaginary Parts'',
 486 Formulas 4.5.49--52,
 487 ``Inverse Hyperbolic Functions---relation to Inverse Circular Functions'',
 488 Formulas 4.6.14--19.
 489
 490 @item
 491 Dave Gillespie, @cite{Calc Manual}, Free Software Foundation, ISBN
 492 1-882114-18-3
 493 @end itemize