arrays-expr.texi

A C++ class library for scientific computing

@table @code
@item abs()
@findex abs()
Absolute value 

@item acos()
@findex acos()
Inverse cosine. For real arguments, the return value is in the range 
@math{[0, \pi]}.  

@item arg()
@findex arg()
Argument of a complex number (@code{atan2(Im,Re)}). 

@item asin()
@findex asin()
Inverse sine. For real arguments, the return value is in the range 
@math{[-\pi/2, \pi/2]}.  

@item atan()
@findex atan()
Inverse tangent.  For real arguments, the return value is in the range
@math{[-\pi/2, \pi/2]}.  See also @code{atan2()} in section
@ref{Math functions 2}.  

@item ceil()
@findex ceil()
Ceiling function: smallest floating-point integer value not less than the
argument. 

@item cexp()
@findex cexp()
Complex exponential; same as @code{exp()}. 

@item conj()
@findex conj()
Conjugate of a complex number. 

@item cos()
@findex cos()
Cosine.  Works for @code{complex<T>}.  

@item cosh()
@findex cosh()
Hyperbolic cosine.  Works for @code{complex<T>}. 

@item csqrt()
@findex csqrt()
Complex square root; same as @code{sqrt()}. 

@item exp()
@findex exp()
Exponential.  Works for @code{complex<T>}. 

@item fabs()
@findex fabs()
Same as @code{abs()}.  

@item floor()
@findex floor()
Floor function: largest floating-point integer value not greater than the
argument. 

@item log()
@findex log()
Natural logarithm.  Works for @code{complex<T>}. 

@item log10()
@findex log10()
Base 10 logarithm.  Works for @code{complex<T>}. 

@item pow2(), pow3(), pow4(), pow5(), pow6(), pow7(), pow8()
@findex pow2()
@findex pow3() 
@findex pow?()
These functions compute an integer power.  They expand to a series of
multiplications, so they can be used on any type for which multiplication is
well-defined.

@item sin()
@findex sin()
Sine.  Works for @code{complex<T>}. 

@item sinh()
@findex sinh()
Hyperbolic sine.  Works for @code{complex<T>}. 

@item sqr()
@findex sqr()
Same as @code{pow2()}.  Computes @code{x*x}. Works for @code{complex<T>}. 

@item sqrt()
@findex sqrt()
Square root.  Works for @code{complex<T>}. 

@item tan()
@findex tan()
Tangent.  Works for @code{complex<T>}. 

@item tanh()
@findex tanh()
Hyperbolic tangent.  Works for @code{complex<T>}. 
@end table

@unnumberedsubsec IEEE/System V math functions

@cindex IEEE math functions
@cindex System V math functions
@findex libm.a
@findex libmsaa.a

These functions are only available on platforms which provide the IEEE Math
library (libm.a) and/or System V Math Library (libmsaa.a).  Apparently not
all platforms provide all of these functions, so what you can use on your
platform may be a subset of these.  If you choose to use one of these
functions, be aware that you may be limiting the portability of your code.

@findex XOPEN_SOURCE
@findex XOPEN_SOURCE_EXTENDED

On some platforms, the preprocessor symbols @code{_XOPEN_SOURCE} and/or
@code{_XOPEN_SOURCE_EXTENDED} need to be defined to use these functions.
These symbols can be enabled by compiling with
@code{-DBZ_ENABLE_XOPEN_SOURCE}.  (In previous version of Blitz++,
@code{_XOPEN_SOURCE} and @code{_XOPEN_SOURCE_EXTENDED} were declared by
default.  This was found to cause too many problems, so users must manually
enable them with @code{-DBZ_ENABLE_XOPEN_SOURCE}.).

In the current version, Blitz++ divides these functions into two groups:
IEEE and System V.  This distinction is probably artificial.  If one of the
functions in a group is missing, Blitz++ won't allow you to use any of them.
You can see the division of these functions in the files
@file{Blitz++/compiler/ieeemath.cpp} and
@file{Blitz++/compiler/sysvmath.cpp}.  This arrangement is unsatisfactory
and will probably change in a future version.

You may have to link with @code{-lm} and/or @code{-lmsaa} to use these
functions.

None of these functions are available for @code{complex<T>}.

@table @code
@item acosh()   
@findex acosh()
Inverse hyperbolic cosine 

@item asinh()
@findex asinh()
Inverse hyperbolic sine 

@item atanh()   
@findex atanh()
Inverse hyperbolic tangent 

@item _class()
@findex _class()
Classification of floating point values.  The return type is integer and
will be one of: 

   @table @code
      @item FP_PLUS_NORM 
@findex FP_PLUS_NORM
			Positive normalized, nonzero 

      @item FP_MINUS_NORM 
@findex FP_MINUS_NORM
			Negative normalized, nonzero 

      @item FP_PLUS_DENORM 
@findex FP_PLUS_DENORM
			Positive denormalized, nonzero 

      @item FP_MINUS_DENORM 
@findex FP_MINUS_DENORM
			Negative denormalized, nonzero 

      @item FP_PLUS_ZERO 
@findex FP_PLUS_ZERO
			+0.0 

      @item FP_MINUS_ZERO 
@findex FP_MINUS_ZERO
			-0.0 

      @item FP_PLUS_INF  
@findex FP_PLUS_INF
			Positive infinity  

      @item FP_MINUS_INF  
@findex FP_MINUS_INF
			Negative infinity 

      @item FP_NANS      
@findex FP_NANS
			Signalling Not a Number (NaNS) 

      @item FP_NANQ      
@findex FP_NANQ
			Quiet Not a Number (NaNQ) 
   @end table

@item cbrt()   
@findex cbrt()
Cubic root 

@item expm1()  
@findex expm1()
Computes exp(x)-1 

@item erf()    
@findex erf()
Computes the error function:  
@tex
$$ {\rm erf}(x) = {2\over\sqrt\pi}\int_{0}^{x} e^{-t^2} dt $$
@end tex
@html
@erf(x) = 2/sqrt(Pi) * integral(exp(-t^2), t=0..x)
@end html
@ifnottex
@ifnothtml
@math{@r{erf}(x) = 2/@r{sqrt}(Pi) * @r{integral}(@r{exp}(-t^2), t=0..x)}
@end ifnothtml
@end ifnottex

Note that for large values of the parameter, calculating can result in
extreme loss of accuracy.  Instead, use @code{erfc()}.

@item erfc()   
@findex erfc()
Computes the complementary error function @math{@r{erfc}(x) = 1 - @r{erf}(x)}.

@item finite()
@findex finite()
Returns a nonzero integer if the parameter is a finite number (i.e.@: not
+INF, -INF, NaNQ or NaNS).

@item ilogb()  
@findex ilogb()
Returns an integer which is equal to the unbiased exponent of
the parameter.               

@item blitz_isnan()  
@findex blitz_isnan()
@findex isnan()
Returns a nonzero integer if the parameter is NaNQ or
NaNS (quiet or signalling Not a Number). 

@item itrunc()
@findex itrunc()
Round a floating-point number to a signed integer.  Returns
the nearest signed integer to the parameter in the direction of 0.

@item j0()     
@findex j0()
@cindex Bessel functions
Bessel function of the first kind, order 0. 

@item j1()     
@findex j1()
Bessel function of the first kind, order 1. 

@item lgamma() 
@findex lgamma() 
@cindex Gamma function
Natural logarithm of the gamma function.  The gamma function
is defined as:
@tex
$$ {\rm Gamma}(x) = \int_0^\infty e^{-t}t^{x-1} dt $$
@end tex
@html
Gamma(x) = integral(e^(-t) * t^(x-1), t=0..infinity))
@end html
@ifnottex
@ifnothtml
@math{@r{Gamma}(x) = @r{integral}(e^(-t) * t^(x-1), t=0..@r{infinity}))}
@end ifnothtml
@end ifnottex
              
@item logb()   
@findex logb()
Returns a floating-point double that is equal to the unbiased
exponent of the parameter. 

@item log1p()  
@findex log1p()
Calculates log(1+x), where x is the parameter. 

@item nearest() 
@findex nearest()
Returns the nearest floating-point integer value to the
parameter.  If the parameter is exactly halfway between two integer values,
an even value is returned. 

@item rint()   
@findex rint()
@cindex rounding
Rounds the parameter and returns a floating-point integer value.  Whether
@code{rint()} rounds up or down or to the nearest integer depends on the
current floating-point rounding mode.  If you haven't altered the rounding
mode, @code{rint()} should be equivalent to @code{nearest()}.  If rounding
mode is set to round towards +INF, @code{rint()} is equivalent to
@code{ceil()}.  If the mode is round toward -INF, @code{rint()} is
equivalent to @code{floor()}.  If the mode is round toward zero,
@code{rint()} is equivalent to @code{trunc()}. 

@item rsqrt()  
@findex rsqrt()
Reciprocal square root. 

@item uitrunc() 
@findex uitrunc()
Returns the nearest unsigned integer to the parameter in the
direction of zero. 

@item y0()     
@findex y0()
Bessel function of the second kind, order 0. 

@item y1()     
@findex y1()
Bessel function of the second kind, order 1. 
@end table

There may be better descriptions of these functions in your
system man pages.

@node Math functions 2
@section Two-argument math functions

The math functions described in this section take two arguments.
Most combinations of these types may be used as arguments:

@itemize @bullet
@item     An Array object
@item     An Array expression
@item     An index placeholder
@item     A scalar of type @code{float}, @code{double}, @code{long double},
or @code{complex<T>}
@end itemize

@unnumberedsubsec ANSI C++ math functions

These math functions are available on all platforms, and work for
complex numbers.

@cindex math functions
@cindex complex math functions

@table @code
@item atan2(x,y)
@findex atan2()
Inverse tangent of (y/x).  The signs of both parameters
are used to determine the quadrant of the return value, which is in the
range @math{[-\pi, \pi]}.  Works for @code{complex<T>}. 

@item blitz::polar(r,t)
@findex polar()
Computes ; i.e.@: converts polar-form to
Cartesian form complex numbers.  The @code{blitz::} scope qualifier is
needed to disambiguate the ANSI C++ function template @code{polar(T,T)}.
This qualifier will hopefully disappear in a future version.

@item pow(x,y)
@findex pow()
Computes x to the exponent y.  Works for @code{complex<T>}. 
@end table

@unnumberedsubsec IEEE/System V math functions

See the notes about IEEE/System V math functions in the previous section.
None of these functions work for complex numbers.  They will all cast their
arguments to double precision.

@table @code
@item copysign(x,y)
@findex copysign()
Returns the x parameter with the same sign as the y parameter. 

@item drem(x,y)
@findex drem() 
@cindex remainder, floating point @code{drem()}
Computes a floating point remainder.  The return value r is equal to r = x -
n * y, where n is equal to @code{nearest(x/y)} (the nearest integer to x/y).
The return value will lie in the range [ -y/2, +y/2 ].  If y is zero or x is
+INF or -INF, NaNQ is returned.

@item fmod(x,y)
@findex fmod() 
@cindex modulo, floating point @code{fmod()}
Computes a floating point modulo remainder.  The return value r is equal to
r = x - n * y, where n is selected so that r has the same sign as x and
magnitude less than abs(y).  In order words, if x > 0, r is in the range [0,
|y|], and if x < 0, r is in the range [-|y|, 0].

@item hypot(x,y)
@findex hypot()
Computes so that underflow does not occur and overflow occurs only if the
final result warrants it. 

@item nextafter(x,y)
@findex nextafter()
Returns the next representable number after x in the direction of y. 

@item remainder(x,y)
@findex remainder()
Equivalent to drem(x,y). 

@item scalb(x,y)
@findex scalb()
Calculates. 

@item unordered(x,y)
@findex unordered()
Returns a nonzero value if a floating-point comparison between x and y would
be unordered.  Otherwise, it returns zero.
@end table

@node User et
@section Declaring your own math functions on arrays

@cindex math functions declaring your own
@cindex Array declaring your own math functions on

There are four macros which make it easy to turn your own scalar functions
into functions defined on arrays.  They are:

@findex BZ_DECLARE_FUNCTION

@example
BZ_DECLARE_FUNCTION(f)                   // 1
BZ_DECLARE_FUNCTION_RET(f,return_type)   // 2
BZ_DECLARE_FUNCTION2(f)                  // 3
BZ_DECLARE_FUNCTION2_RET(f,return_type)  // 4
@end example

Use version 1 when you have a function which takes one argument and returns
a result of the same type.  For example:

@example
#include <blitz/array.h>

using namespace blitz;

double myFunction(double x)
@{ 
    return 1.0 / (1 + x); 
@}

BZ_DECLARE_FUNCTION(myFunction)

int main()
@{
    Array<double,2> A(4,4), B(4,4);  // ...
    B = myFunction(A);
@}
@end example

Use version 2 when you have a one argument function whose return type is
different than the argument type, such as

@example
int g(double x);
@end example

Use version 3 for a function which takes two arguments and returns a result
of the same type, such as:

@example
double g(double x, double y);
@end example

Use version 4 for a function of two arguments which returns a different
type, such as:

@example
int g(double x, double y);
@end example

@section Tensor notation

@cindex tensor notation
@cindex Array tensor notation

Blitz++ arrays support a tensor-like notation.  Here's an example of
real-world tensor notation:
@tex
$$ A^{ijk} = B^{ij} C^k $$
@end tex
@html
<pre>
 ijk    ij k
A    = B  C
</pre>
@end html
@ifnottex
@ifnothtml
@example
 ijk    ij k
A    = B  C
@end example
@end ifnothtml