.\"====================================================================
.\" 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 INDEX

INDEX(STRING,SUBSTRING) returns the position of the start of the first
occurrence of string SUBSTRING as a substring in STRING, counting from
one. If SUBSTRING is not present in STRING, zero is returned. Trailing
blanks in SUBSTRING are ignored (i.e. they are not matched in STRING).

STRING and/or SUBSTRING arguments can be quoted character strings or
unquoted variable names, e.g.

.nf
SIC> say 'index("FOOBAR","OO")'
2
SIC>
SIC> define char*12 str sub
SIC> let str "FOOBAR"
SIC> let sub "OB"
SIC> say 'index(str,sub)'
3
SIC> say 'index(str,"BA")'  ! Mixed case
4
SIC> say 'index("FOOBAR",sub)'  ! Mixed case
3
.fi
.\"====================================================================
.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
