1 files changed, 493 insertions, 0 deletions
diff --git a/gsl-1.9/doc/complex.texi b/gsl-1.9/doc/complex.texi
new file mode 100644
index 0000000..b84a7ac
--- /dev/null
+++ b/gsl-1.9/doc/complex.texi
@@ -0,0 +1,493 @@
+@cindex complex numbers
+
+The functions described in this chapter provide support for complex
+numbers.  The algorithms take care to avoid unnecessary intermediate
+underflows and overflows, allowing the functions to be evaluated over 
+as much of the complex plane as possible. 
+
+@comment FIXME: this still needs to be
+@comment done for the csc,sec,cot,csch,sech,coth functions
+
+For multiple-valued functions the branch cuts have been chosen to follow
+the conventions of Abramowitz and Stegun in the @cite{Handbook of
+Mathematical Functions}. The functions return principal values which are
+the same as those in GNU Calc, which in turn are the same as those in
+@cite{Common Lisp, The Language (Second Edition)}@footnote{Note that the
+first edition uses different definitions.} and the HP-28/48 series of
+calculators.
+
+The complex types are defined in the header file @file{gsl_complex.h},
+while the corresponding complex functions and arithmetic operations are
+defined in @file{gsl_complex_math.h}.
+
+@menu
+* Complex numbers::             
+* Properties of complex numbers::  
+* Complex arithmetic operators::  
+* Elementary Complex Functions::  
+* Complex Trigonometric Functions::  
+* Inverse Complex Trigonometric Functions::  
+* Complex Hyperbolic Functions::  
+* Inverse Complex Hyperbolic Functions::  
+* Complex Number References and Further Reading::  
+@end menu
+
+@node Complex numbers
+@section Complex numbers
+@cindex representations of complex numbers
+@cindex polar form of complex numbers
+@tpindex gsl_complex
+
+Complex numbers are represented using the type @code{gsl_complex}. The
+internal representation of this type may vary across platforms and
+should not be accessed directly. The functions and macros described
+below allow complex numbers to be manipulated in a portable way.
+
+For reference, the default form of the @code{gsl_complex} type is
+given by the following struct,
+
+@example
+typedef struct
+@{
+  double dat[2];
+@} gsl_complex;
+@end example
+
+@noindent
+The real and imaginary part are stored in contiguous elements of a two
+element array. This eliminates any padding between the real and
+imaginary parts, @code{dat[0]} and @code{dat[1]}, allowing the struct to
+be mapped correctly onto packed complex arrays.
+
+@deftypefun gsl_complex gsl_complex_rect (double @var{x}, double @var{y})
+This function uses the rectangular cartesian components
+(@var{x},@var{y}) to return the complex number @math{z = x + i y}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_polar (double @var{r}, double @var{theta})
+This function returns the complex number @math{z = r \exp(i \theta) = r
+(\cos(\theta) + i \sin(\theta))} from the polar representation
+(@var{r},@var{theta}).
+@end deftypefun
+
+@defmac GSL_REAL (@var{z})
+@defmacx GSL_IMAG (@var{z})
+These macros return the real and imaginary parts of the complex number
+@var{z}.
+@end defmac
+
+@defmac GSL_SET_COMPLEX (@var{zp}, @var{x}, @var{y})
+This macro uses the cartesian components (@var{x},@var{y}) to set the
+real and imaginary parts of the complex number pointed to by @var{zp}.
+For example,
+
+@example
+GSL_SET_COMPLEX(&z, 3, 4)
+@end example
+
+@noindent
+sets @var{z} to be @math{3 + 4i}.
+@end defmac
+
+@defmac GSL_SET_REAL (@var{zp},@var{x})
+@defmacx GSL_SET_IMAG (@var{zp},@var{y})
+These macros allow the real and imaginary parts of the complex number
+pointed to by @var{zp} to be set independently.
+@end defmac
+
+@node Properties of complex numbers
+@section Properties of complex numbers
+
+@deftypefun double gsl_complex_arg (gsl_complex @var{z})
+@cindex argument of complex number 
+This function returns the argument of the complex number @var{z},
+@math{\arg(z)}, where @c{$-\pi < \arg(z) \leq \pi$}
+@math{-\pi < \arg(z) <= \pi}.
+@end deftypefun
+
+@deftypefun double gsl_complex_abs (gsl_complex @var{z})
+@cindex magnitude of complex number 
+This function returns the magnitude of the complex number @var{z}, @math{|z|}.
+@end deftypefun
+
+@deftypefun double gsl_complex_abs2 (gsl_complex @var{z})
+This function returns the squared magnitude of the complex number
+@var{z}, @math{|z|^2}.
+@end deftypefun
+
+@deftypefun double gsl_complex_logabs (gsl_complex @var{z})
+This function returns the natural logarithm of the magnitude of the
+complex number @var{z}, @math{\log|z|}.  It allows an accurate
+evaluation of @math{\log|z|} when @math{|z|} is close to one. The direct
+evaluation of @code{log(gsl_complex_abs(z))} would lead to a loss of
+precision in this case.
+@end deftypefun
+
+
+@node Complex arithmetic operators
+@section Complex arithmetic operators
+@cindex complex arithmetic
+
+@deftypefun gsl_complex gsl_complex_add (gsl_complex @var{a}, gsl_complex @var{b})
+This function returns the sum of the complex numbers @var{a} and
+@var{b}, @math{z=a+b}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_sub (gsl_complex @var{a}, gsl_complex @var{b})
+This function returns the difference of the complex numbers @var{a} and
+@var{b}, @math{z=a-b}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_mul (gsl_complex @var{a}, gsl_complex @var{b})
+This function returns the product of the complex numbers @var{a} and
+@var{b}, @math{z=ab}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_div (gsl_complex @var{a}, gsl_complex @var{b})
+This function returns the quotient of the complex numbers @var{a} and
+@var{b}, @math{z=a/b}.
+@end deftypefun
+
+
+@deftypefun gsl_complex gsl_complex_add_real (gsl_complex @var{a}, double @var{x})
+This function returns the sum of the complex number @var{a} and the
+real number @var{x}, @math{z=a+x}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_sub_real (gsl_complex @var{a}, double @var{x})
+This function returns the difference of the complex number @var{a} and the
+real number @var{x}, @math{z=a-x}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_mul_real (gsl_complex @var{a}, double @var{x})
+This function returns the product of the complex number @var{a} and the
+real number @var{x}, @math{z=ax}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_div_real (gsl_complex @var{a}, double @var{x})
+This function returns the quotient of the complex number @var{a} and the
+real number @var{x}, @math{z=a/x}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_add_imag (gsl_complex @var{a}, double @var{y})
+This function returns the sum of the complex number @var{a} and the
+imaginary number @math{i}@var{y}, @math{z=a+iy}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_sub_imag (gsl_complex @var{a}, double @var{y})
+This function returns the difference of the complex number @var{a} and the
+imaginary number @math{i}@var{y}, @math{z=a-iy}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_mul_imag (gsl_complex @var{a}, double @var{y})
+This function returns the product of the complex number @var{a} and the
+imaginary number @math{i}@var{y}, @math{z=a*(iy)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_div_imag (gsl_complex @var{a}, double @var{y})
+This function returns the quotient of the complex number @var{a} and the
+imaginary number @math{i}@var{y}, @math{z=a/(iy)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_conjugate (gsl_complex @var{z})
+@cindex conjugate of complex number
+This function returns the complex conjugate of the complex number
+@var{z}, @math{z^* = x - i y}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_inverse (gsl_complex @var{z})
+This function returns the inverse, or reciprocal, of the complex number
+@var{z}, @math{1/z = (x - i y)/(x^2 + y^2)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_negative (gsl_complex @var{z})
+This function returns the negative of the complex number
+@var{z}, @math{-z = (-x) + i(-y)}.
+@end deftypefun
+
+
+@node Elementary Complex Functions
+@section Elementary Complex Functions
+
+@deftypefun gsl_complex gsl_complex_sqrt (gsl_complex @var{z})
+@cindex square root of complex number
+This function returns the square root of the complex number @var{z},
+@math{\sqrt z}. The branch cut is the negative real axis. The result
+always lies in the right half of the complex plane.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_sqrt_real (double @var{x})
+This function returns the complex square root of the real number
+@var{x}, where @var{x} may be negative.
+@end deftypefun
+
+
+@deftypefun gsl_complex gsl_complex_pow (gsl_complex @var{z}, gsl_complex @var{a})
+@cindex power of complex number
+@cindex exponentiation of complex number
+The function returns the complex number @var{z} raised to the complex
+power @var{a}, @math{z^a}. This is computed as @math{\exp(\log(z)*a)}
+using complex logarithms and complex exponentials.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_pow_real (gsl_complex @var{z}, double @var{x})
+This function returns the complex number @var{z} raised to the real
+power @var{x}, @math{z^x}.
+@end deftypefun
+
+
+@deftypefun gsl_complex gsl_complex_exp (gsl_complex @var{z})
+This function returns the complex exponential of the complex number
+@var{z}, @math{\exp(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_log (gsl_complex @var{z})
+@cindex logarithm of complex number
+This function returns the complex natural logarithm (base @math{e}) of
+the complex number @var{z}, @math{\log(z)}.  The branch cut is the
+negative real axis. 
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_log10 (gsl_complex @var{z})
+This function returns the complex base-10 logarithm of
+the complex number @var{z}, @c{$\log_{10}(z)$}
+@math{\log_10 (z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_log_b (gsl_complex @var{z}, gsl_complex @var{b})
+This function returns the complex base-@var{b} logarithm of the complex
+number @var{z}, @math{\log_b(z)}. This quantity is computed as the ratio
+@math{\log(z)/\log(b)}.
+@end deftypefun
+
+
+@node Complex Trigonometric Functions
+@section Complex Trigonometric Functions
+@cindex trigonometric functions of complex numbers
+
+@deftypefun gsl_complex gsl_complex_sin (gsl_complex @var{z})
+@cindex sin, of complex number
+This function returns the complex sine of the complex number @var{z},
+@math{\sin(z) = (\exp(iz) - \exp(-iz))/(2i)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_cos (gsl_complex @var{z})
+@cindex cosine of complex number
+This function returns the complex cosine of the complex number @var{z},
+@math{\cos(z) = (\exp(iz) + \exp(-iz))/2}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_tan (gsl_complex @var{z})
+@cindex tangent of complex number
+This function returns the complex tangent of the complex number @var{z},
+@math{\tan(z) = \sin(z)/\cos(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_sec (gsl_complex @var{z})
+This function returns the complex secant of the complex number @var{z},
+@math{\sec(z) = 1/\cos(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_csc (gsl_complex @var{z})
+This function returns the complex cosecant of the complex number @var{z},
+@math{\csc(z) = 1/\sin(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_cot (gsl_complex @var{z})
+This function returns the complex cotangent of the complex number @var{z},
+@math{\cot(z) = 1/\tan(z)}.
+@end deftypefun
+
+
+@node Inverse Complex Trigonometric Functions
+@section Inverse Complex Trigonometric Functions
+@cindex inverse complex trigonometric functions
+
+@deftypefun gsl_complex gsl_complex_arcsin (gsl_complex @var{z})
+This function returns the complex arcsine of the complex number @var{z},
+@math{\arcsin(z)}. The branch cuts are on the real axis, less than @math{-1}
+and greater than @math{1}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arcsin_real (double @var{z})
+This function returns the complex arcsine of the real number @var{z},
+@math{\arcsin(z)}. For @math{z} between @math{-1} and @math{1}, the
+function returns a real value in the range @math{[-\pi/2,\pi/2]}. For
+@math{z} less than @math{-1} the result has a real part of @math{-\pi/2}
+and a positive imaginary part.  For @math{z} greater than @math{1} the
+result has a real part of @math{\pi/2} and a negative imaginary part.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccos (gsl_complex @var{z})
+This function returns the complex arccosine of the complex number @var{z},
+@math{\arccos(z)}. The branch cuts are on the real axis, less than @math{-1}
+and greater than @math{1}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccos_real (double @var{z})
+This function returns the complex arccosine of the real number @var{z},
+@math{\arccos(z)}. For @math{z} between @math{-1} and @math{1}, the
+function returns a real value in the range @math{[0,\pi]}. For @math{z}
+less than @math{-1} the result has a real part of @math{\pi} and a
+negative imaginary part.  For @math{z} greater than @math{1} the result
+is purely imaginary and positive.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arctan (gsl_complex @var{z})
+This function returns the complex arctangent of the complex number
+@var{z}, @math{\arctan(z)}. The branch cuts are on the imaginary axis,
+below @math{-i} and above @math{i}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arcsec (gsl_complex @var{z})
+This function returns the complex arcsecant of the complex number @var{z},
+@math{\arcsec(z) = \arccos(1/z)}. 
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arcsec_real (double @var{z})
+This function returns the complex arcsecant of the real number @var{z},
+@math{\arcsec(z) = \arccos(1/z)}. 
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccsc (gsl_complex @var{z})
+This function returns the complex arccosecant of the complex number @var{z},
+@math{\arccsc(z) = \arcsin(1/z)}. 
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccsc_real (double @var{z})
+This function returns the complex arccosecant of the real number @var{z},
+@math{\arccsc(z) = \arcsin(1/z)}. 
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccot (gsl_complex @var{z})
+This function returns the complex arccotangent of the complex number @var{z},
+@math{\arccot(z) = \arctan(1/z)}. 
+@end deftypefun
+
+
+@node Complex Hyperbolic Functions
+@section Complex Hyperbolic Functions
+@cindex hyperbolic functions, complex numbers
+
+@deftypefun gsl_complex gsl_complex_sinh (gsl_complex @var{z})
+This function returns the complex hyperbolic sine of the complex number
+@var{z}, @math{\sinh(z) = (\exp(z) - \exp(-z))/2}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_cosh (gsl_complex @var{z})
+This function returns the complex hyperbolic cosine of the complex number
+@var{z}, @math{\cosh(z) = (\exp(z) + \exp(-z))/2}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_tanh (gsl_complex @var{z})
+This function returns the complex hyperbolic tangent of the complex number
+@var{z}, @math{\tanh(z) = \sinh(z)/\cosh(z)}.
+@end deftypefun
+
+
+@deftypefun gsl_complex gsl_complex_sech (gsl_complex @var{z})
+This function returns the complex hyperbolic secant of the complex
+number @var{z}, @math{\sech(z) = 1/\cosh(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_csch (gsl_complex @var{z})
+This function returns the complex hyperbolic cosecant of the complex
+number @var{z}, @math{\csch(z) = 1/\sinh(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_coth (gsl_complex @var{z})
+This function returns the complex hyperbolic cotangent of the complex
+number @var{z}, @math{\coth(z) = 1/\tanh(z)}.
+@end deftypefun
+
+
+@node Inverse Complex Hyperbolic Functions
+@section Inverse Complex Hyperbolic Functions
+@cindex inverse hyperbolic functions, complex numbers
+
+@deftypefun gsl_complex gsl_complex_arcsinh (gsl_complex @var{z})
+This function returns the complex hyperbolic arcsine of the
+complex number @var{z}, @math{\arcsinh(z)}.  The branch cuts are on the
+imaginary axis, below @math{-i} and above @math{i}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccosh (gsl_complex @var{z})
+This function returns the complex hyperbolic arccosine of the complex
+number @var{z}, @math{\arccosh(z)}.  The branch cut is on the real
+axis, less than @math{1}.  Note that in this case we use the negative
+square root in formula 4.6.21 of Abramowitz & Stegun giving
+@c{$\arccosh(z)=\log(z-\sqrt{z^2-1})$}
+@math{\arccosh(z)=\log(z-\sqrt@{z^2-1@})}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccosh_real (double @var{z})
+This function returns the complex hyperbolic arccosine of
+the real number @var{z}, @math{\arccosh(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arctanh (gsl_complex @var{z})
+This function returns the complex hyperbolic arctangent of the complex
+number @var{z}, @math{\arctanh(z)}.  The branch cuts are on the real
+axis, less than @math{-1} and greater than @math{1}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arctanh_real (double @var{z})
+This function returns the complex hyperbolic arctangent of the real
+number @var{z}, @math{\arctanh(z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arcsech (gsl_complex @var{z})
+This function returns the complex hyperbolic arcsecant of the complex
+number @var{z}, @math{\arcsech(z) = \arccosh(1/z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccsch (gsl_complex @var{z})
+This function returns the complex hyperbolic arccosecant of the complex
+number @var{z}, @math{\arccsch(z) = \arcsin(1/z)}.
+@end deftypefun
+
+@deftypefun gsl_complex gsl_complex_arccoth (gsl_complex @var{z})
+This function returns the complex hyperbolic arccotangent of the complex
+number @var{z}, @math{\arccoth(z) = \arctanh(1/z)}.
+@end deftypefun
+
+@node Complex Number References and Further Reading
+@section References and Further Reading
+
+The implementations of the elementary and trigonometric functions are
+based on the following papers,
+
+@itemize @asis
+@item
+T. E. Hull, Thomas F. Fairgrieve, Ping Tak Peter Tang,
+``Implementing Complex Elementary Functions Using Exception
+Handling'', @cite{ACM Transactions on Mathematical Software}, Volume 20
+(1994), pp 215--244, Corrigenda, p553
+
+@item
+T. E. Hull, Thomas F. Fairgrieve, Ping Tak Peter Tang,
+``Implementing the complex arcsin and arccosine functions using exception
+handling'', @cite{ACM Transactions on Mathematical Software}, Volume 23
+(1997) pp 299--335
+@end itemize
+
+@noindent
+The general formulas and details of branch cuts can be found in the
+following books,
+
+@itemize @asis
+@item
+Abramowitz and Stegun, @cite{Handbook of Mathematical Functions},
+``Circular Functions in Terms of Real and Imaginary Parts'', Formulas
+4.3.55--58,
+``Inverse Circular Functions in Terms of Real and Imaginary Parts'',
+Formulas 4.4.37--39,
+``Hyperbolic Functions in Terms of Real and Imaginary Parts'',
+Formulas 4.5.49--52,
+``Inverse Hyperbolic Functions---relation to Inverse Circular Functions'',
+Formulas 4.6.14--19.
+
+@item
+Dave Gillespie, @cite{Calc Manual}, Free Software Foundation, ISBN
+1-882114-18-3
+@end itemize