.\"====================================================================
.\" THIS FILE CONTAINS THE HELP FOR SIC INTRINSIC FUNCTIONS (NATIVE
.\" SUPPORT IN THE INTERPRETER) AND PROGRAM-DEFINED FUNCTIONS (DEFINED
.\" BY SIC WITH SIC_DEF_FUNC)
.\"====================================================================
.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 ABS

ABS(A) computes the absolute value of A.
.\"====================================================================
.ti -4
1 ACOS

ACOS(X) computes the arccosine of X (inverse of COS(X)). The result is
in radians and lies in the range [0:pi].
.\"====================================================================
.ti -4
1 ALL

ALL(MASK) determines if all the values are true in MASK. MASK is a
vectorized logical expression, e.g.
.br
  ALL(L)          where L is a logical variable name, or
.br
  ALL(A.GT.1)     where A is a numeric variable name, or
.br
  ALL(C.EQ."abc") where C is a character variable name, etc.
.\"====================================================================
.ti -4
1 ANY

ANY(MASK) determines if any of the values are true in MASK. MASK is a
vectorized logical expression, e.g.
.br
  ANY(L)          where L is a logical variable name, or
.br
  ANY(A.GT.1)     where A is a numeric variable name, or
.br
  ANY(C.EQ."abc") where C is a character variable name, etc.
.\"====================================================================
.ti -4
1 ASIN

ASIN(X) computes the arcsine of X (inverse of SIN(X)). The result is
in radians and lies in the range [-pi/2:pi/2].
.\"====================================================================
.ti -4
1 ATAN

ATAN(X) computes the arctangent of X (inverse of TAN(X)). The result is
in radians and lies in the range [-pi/2:pi/2].
.\"====================================================================
.ti -4
1 ATANH

ATANH(X) computes the inverse hyperbolic tangent of X.
.\"====================================================================
.ti -4
1 ATAN2

ATAN2(Y,X) computes the principal value of the argument function of
the complex number X + i Y. This function can be used to transform
from Cartesian into polar coordinates and allows to determine the
angle in the correct quadrant.

If X is nonzero, the result lies in the range [-pi:pi]. The
sign is positive if Y is positive. If Y is zero, then the result
is zero if X is strictly positive, pi if X is negative and Y is
positive zero (or the processor does not handle signed zeros), and
-pi if X is negative and Y is negative zero. Finally, if X is zero,
then the magnitude of the result is pi/2.
.\"====================================================================
.ti -4
1 BESSEL__I0

BESSEL__I0(X) computes the modified Bessel function of the first kind
of order 0 of X.
.\"====================================================================
.ti -4
1 BESSEL__I1

BESSEL__I1(X) computes the modified Bessel function of the first kind
of order 1 of X.
.\"====================================================================
.ti -4
1 BESSEL__IN

BESSEL__IN(N,X) computes the modified Bessel function of the first
kind of order N of X.
.\"====================================================================
.ti -4
1 BESSEL__J0

BESSEL__J0(X) computes the Bessel function of the first kind of order
0 of X.
.\"====================================================================
.ti -4
1 BESSEL__J1

BESSEL__J1(X) computes the Bessel function of the first kind of order
1 of X.
.\"====================================================================
.ti -4
1 BESSEL__JN

BESSEL__JN(N,X) computes the Bessel function of the first kind of
order N of X.
.\"====================================================================
.ti -4
1 BESSEL__Y0

BESSEL__Y0(X) computes the Bessel function of the second kind of order
0 of X.
.\"====================================================================
.ti -4
1 BESSEL__Y1

BESSEL__Y1(X) computes the Bessel function of the second kind of order
0 of X.
.\"====================================================================
.ti -4
1 BESSEL__YN

BESSEL__YN(N,X) computes the Bessel function of the first kind of order
N of X.
.\"====================================================================
.ti -4
1 CEILING

CEILING(A) returns the least integer greater than or equal to A. 
.\"====================================================================
.ti -4
1 COS

COS(X) computes the cosine of X, with X in radians. The return value
lies in the range [-1:1].
.\"====================================================================
.ti -4
1 COSH

COSH(X) computes the hyperbolic cosine of X. The return value has a
lower bound of 1 (COSH(X)>= 1).
.\"====================================================================
.ti -4
1 DIM

DIM(X,Y) returns the difference X-Y if the result is positive;
otherwise returns zero.
.\"====================================================================
.ti -4
1 EXIST

EXIST(VAR) is a logical function returning YES if the Sic variable
named VAR exists, NO otherwise. The variable name must be unquoted,
e.g.
.nf
  SIC> say 'exist(pi)'
  YES
.fi
.\"====================================================================
.ti -4
1 ERF

ERF(X) computes the error function of X. The return value lies in the
range -1 <= erf(x) <= 1.
.\"====================================================================
.ti -4
1 ERFC

ERFC(X) computes the complementary error function of X. The return
value lies in the range 0 <= erfc(x) <= 2.
.\"====================================================================
.ti -4
1 ERFINV

ERFINV(X) computes the inverse error function of X, such as
ERF(ERFINV(X))=X. The input value must lie in the range -1 < X <
1. The return value is not defined out of this range.
.\"====================================================================
.ti -4
1 ERFCINV

ERFCINV(X) computes the inverse complementary error function of X,
such as ERFC(ERFCINV(X))=X. The input value must lie in the range 0 <
X < 2. The return value is not defined out of this range.
.\"====================================================================
.ti -4
1 EXP

EXP(X) computes the base e exponential of X.
.\"====================================================================
.ti -4
1 FILE

FILE(NAME) is a logical function returning YES if the file named NAME
exists, NO otherwise. The file name can be a quoted character string
providing explictly the name, or an unquoted variable name containing
the name, e.g.

.nf
  SIC> say 'file("myfile.ext")'
  YES
  SIC> define character name*16
  SIC> let name "myfile.ext"
  SIC> say 'file(name)'
  YES
.fi
.\"====================================================================
.ti -4
1 FLOOR

FLOOR(A) returns the greatest integer less than or equal to A.
.\"====================================================================
.ti -4
1 FUNCTION

FUNCTION(Name) returns YES if "Name" is a user function name (defined
with DEFINE FUNCTION), NO otherwise.
.\"====================================================================
.ti -4
1 GAUSSIAN1D

GAUSSIAN1D(X,CENTER,FWHM) returns the gaussian function value at X,
with given X center and full width at half-maximum (FWHM). All 3
parameters must be expressed in the same unit.

The function peaks at 1 if X=CENTER. Any extra amplitude factor can be
added by invoking e.g. 2*GAUSSIAN1D(0,0,1).

This function can perform vectorized computations, as in
.nf
  SIC> DEFINE REAL X[100] Y[100]
  SIC> LET X[I] I
  SIC> LET YY GAUSSIAN1D(X,50,10)
.fi
All 3 arguments can be arrays as long as they are consistant.

See also the function NORMAL1D for a normal distribution function.
.\"====================================================================
.ti -4
1 INT

INT(A) is equivalent to FLOOR(A) and returns the greatest integer less
than or equal to A. In this respect, Sic INT() behaves differently
from Fortran INT().
.\"====================================================================
.ti -4
1 ISNAN

ISNAN(A) determines if A value is IEEE Not-A-Number. A must be a
floating value, expression, or variable (single or double
precision). If A is an array, ISNAN(A) is a logical array of same
shape.
.\"====================================================================
.ti -4
1 ISNUM

ISNUM(String) determines if String represents a Number, or is a Scalar
variable holding a numerical value. It returns YES if these two cases,
NO in any other case.
.\"====================================================================
.ti -4
1 LEN

LEN(A) returns the length (number of characters) of a scalar character
string, e.g.

.nf
  SIC> define character c*12
  SIC> say 'len(c)'
  12
.fi

See also function LEN__TRIM.
.\"====================================================================
.ti -4
1 LEN__TRIM

LEN__TRIM(A) returns the length (number of characters) of a scalar
character string, ignoring trailing blanks, e.g.

.nf
  SIC> define character c*12
  SIC> let c "ABCDEF"
  SIC> say 'len__trim(c)'
  6
.fi

See also function LEN.
.\"====================================================================
.ti -4
1 LOG

LOG(X) computes the natural logarithm of X, i.e. the logarithm to the
base e.
.\"====================================================================
.ti -4
1 LOG10

LOG10(X) computes the base 10 logarithm of X.
.\"====================================================================
.ti -4
1 MAX

MAX(A,B) returns the argument with the largest (most positive) value.
.\"====================================================================
.ti -4
1 MIN

MIN(A,B) returns the argument with the smallest (most negative) value.
.\"====================================================================
.ti -4
1 MOD

MOD(A,P) computes the remainder of the division of A by P. The
returned value has a magnitude less than the magnitude of P.
.\"====================================================================
.ti -4
1 NINT

NINT(A) rounds its argument to the nearest whole number. It returns A
with the fractional portion of its magnitude eliminated by rounding to
the nearest whole number and with its sign preserved.
.\"====================================================================
.ti -4
1 NOISE

NOISE(A) returns a pseudorandom floating point value from a normal
gaussian distribution with RMS equal to A. See also HELP SIC
RANDOM__SEED.

When using implicit loops to fill an array with random values, you
have to ensure that the NOISE() function is reevaluated at each
iteration. For example:
.nf
  DEFINE REAL A[3]
  LET A[I] NOISE(1)   ! Same scalar value replicated in all A values
  LET A[I] NOISE(I)   ! Different values, each with different RMS
  LET A[I] NOISE(I/I) ! Different values, same RMS (1 in this case)
.fi
On the other hand, there is no such issue when using explicit loops:
.nf
  DEFINE REAL A[3]
  FOR I 1 TO 3
    LET A[I] NOISE(1)   ! NOISE(1) is reevaluated at each iteration
  NEXT I
.fi
.\"====================================================================
.ti -4
1 NORMAL1D

NORMAL1D(X,MU,SIGMA) returns the normal distribution gaussian function
value at X, with given MU expected value (peak position in X) and
SIGMA variance. All 3 parameters must be expressed in the same unit.

The function amplitude at X=MU ensures its area is 1. Any extra
amplitude factor can be added by invoking e.g. 2*NORMAL1D(0,0,1).

This function can perform vectorized computations, as in
.nf
  SIC> DEFINE REAL X[100] Y[100]
  SIC> LET X[I] I
  SIC> LET YY NORMAL1D(X,50,10)
.fi
All 3 arguments can be arrays as long as they are consistant.

See also the function GAUSSIAN1D for a basic gaussian function.
.\"====================================================================
.ti -4
1 RANDOM

RANDOM(A) returns a pseudorandom floating point value from a uniform
distribution over the range [0:A]. See also HELP SIC RANDOM__SEED.
.\"====================================================================
.ti -4
1 RANK

RANK(A) returns the rank (number of dimensions) of the Sic variable
A. The result is 0 for scalar variables.
.\"====================================================================
.ti -4
1 SIGN

SIGN(A,B) returns the value of A with the sign of B. If B>=0 then
the result is ABS(A), else it is -ABS(A).
.\"====================================================================
.ti -4
1 SIN

SIN(X) computes the sine of X, with X in radians. The return value
lies in the range [-1:1].
.\"====================================================================
.ti -4
1 SINH

SINH(X) computes the hyperbolic sine of X.
.\"====================================================================
.ti -4
1 SIZE

SIZE(VAR) or SIZE(VAR,DIM) determines the extent of VAR along the
specified dimension DIM, or the total number of elements in VAR if DIM
is absent.
.\"====================================================================
.ti -4
1 SQRT

SQRT(X) computes the square root of X.
.\"====================================================================
.ti -4
1 TAN

TAN(X) computes the tangent of X, with X in radians.
.\"====================================================================
.ti -4
1 TANH

TANH(X) computes the hyperbolic tangent of X. The return value lies in
the range [-1:1].
.\"====================================================================
.ti -4
1 TYPEOF

TYPEOF(VAR) returns the SIC internal integer code describing the type
of the variable (<0 for numerics, >0 for character strings).
.\"====================================================================
.ti -4
1 ENDOFHELP
