diff options
Diffstat (limited to 'gsl-1.9/doc/complex.texi')
-rw-r--r-- | gsl-1.9/doc/complex.texi | 493 |
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 |