src/parsec/disk-image/parsec/parsec-benchmark/pkgs/libs/gsl/src/doc/complex.texi - public/gem5-resources - Git at Google

 @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
	@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