algebra: functions

ABS

Returns the absolute value.

This function can take either an Histogram, a Matrix or a Number as argument. The function acts bin-by-bin on Histograms and element-by-element on Matrices and returns a value of the same type as the argument.

ARCCOS

Returns an angle such that cos(angle) equals the argument.

The angle is expressed in radians.

The absolute value of the argument, or of each element of the argument, should be less than or equal to 1.

ARCCOSH

Returns a value such that cosh(value) equals the argument.

The argument, or each element of the argument, should be equal to or larger than 1.

ARCSIN

Returns an angle such that sin(angle) equals the argument.

The angle is expressed in radians.

The absolute value of the argument, or of each element of the argument, should be less than or equal to 1.

ARCSINH

Returns a value such that sinh(value) equals the argument.

ARCTAN

Returns an angle such that tan(angle) equals the argument.

The angle is expressed in radians.

ARCTANH

Returns a value such that tanh(value) equals the argument.

The absolute value of the argument, or of each element of the argument, should be less than 1.

COS

Returns the cosine of an angle, which should be expressed in radians.

COSH

Returns the hyperbolic cosine of the argument.

ENTIER

Returns the largest integer smaller than the argument.

EXP

Returns e to the power of the argument.

The argument, or all elements of the argument, should be less than 88. The exponential of the argument, or an element of the argument, less than -88 raises an error condition unless the IGNORE-UNDERFLOW option has been set.

GLOBAL

GLOBAL is a function that takes a String as argument and which returns the global variable by the same name.

The function returns Nill, of type Undefined, if there is no such global variable.

Example:

Global i=1
Do
   If 'type(global(`SEL_`/string(i)))#`Histogram`' Then Leave
   Call write_histogram_rz(global(`SEL_`/string(i)),`arrival.rz`)
   Global i=i+1
Enddo

The ARRIVAL-TIME-DISTRIBUTION command can create a set of histograms which are numbered SEL_1, SEL_2 etc. These histograms are written to an RZ file by the above set of instructions. The TYPE and GLOBAL functions are used to stop the loop as soon as the last histogram has been written.

LANDAU

Returns the Landau density function.

LOG

Returns the (natural) logarithm of the argument.

The argument, or each element of the argument, should be larger than 0.

MAXIMUM

The MAXIMUM function can take either an Histogram or a Matrix as argument. A Matrix-type argument may have any number of dimensions.

When given an Histogram, it will return the coordinate of the upper edge for the last bin. Using this function with an Histogram is equivalent to calling the INQUIRE_HISTOGRAM procedure and using its maximum argument.

When given a Matrix as argument, it will return the largest value found in the Matrix.

The function returns in either case a value of type Number.

MEAN

Returns the mean of an Histogram or a Matrix.

Using this function with an Histogram is equivalent to calling the INQUIRE_HISTOGRAM procedure and using its mean argument.

This function accepts Matrices with any number of dimensions.

The mean is for both Histograms and Matrices defined as:

        Sum(x)
mean  = ------
          n

The function returns in either case a value of type Number.

Example:

See the RMS function.

MINIMUM

The MINIMUM function can take either an Histogram or a Matrix as argument. A Matrix-type argument may have any number of dimensions.

When given an Histogram, it will return the coordinate of the lower edge for the first bin. Using this function with an Histogram is equivalent to calling the INQUIRE_HISTOGRAM procedure and using its minimum argument.

When given a Matrix as argument, it will return the smallest value found in the Matrix.

The function returns in either case a value of type Number.

NOT

Logical negation of the argument.

The function takes a Logical are argument and returns a Logical.

NUMBER

Converts a variable of type Matrix or String to a variable of type Number.

If the argument is a String, it should contain a simple number, not an expression.

If the argument is a Matrix, then its first element will be returned.

PRODUCT

Returns the product of all channels of an Histogram or of all elements of a Matrix.

The function returns in either case a value of type Number.

REFERENCE

Returns the reference number of a Histogram, a Matrix or a String.

This is the reverse operation of the REF_HISTOGRAM, REF_MATRIX and REF_STRING.

REF_HISTOGRAM

Histograms are normally accessed via the Global variable with which they are associated.

Internally however, the bookkeeping of histograms and of global variables are separated, and it is common that histograms exist which have no associated global. In the rare event that one wishes to access these histograms one uses REF_HISTOGRAM.

REF_HISTOGRAM takes a Number as argument which is interpreted as the number of the histogram in the histogram buffer. The numbers of the histograms can be found in the first column of the output of the LIST_HISTOGRAMS procedure.

Example:

Call delete_histograms
Call book_histogram(a,25,`integer`)
For i From 1 To 10000 Do
   Call fill_histogram(a,rnd_poisson(3))
Enddo
Call plot_histogram(ref_histogram(1))
Call plot_end

By first calling DELETE_HISTOGRAM, we are sure that the next histogram to be booked will have number 1. This histogram is in this case also known as A. It is filled and then plotted, using its number rather than its associated global.

REF_MATRIX

Gives access to a Matrix by the internal reference number.

Such access is rarely required since all user-relevant Matrices can in principle be accessed via a Global variable.

REF_STRING

Gives access to a String by the internal reference number.

Such access is rarely required since all user-relevant Strings can in principle be accessed via a Global variable.

RMS

Returns the RMS of an Histogram or a Matrix.

Using this function with an Histogram is equivalent to calling the INQUIRE_HISTOGRAM procedure and using its rms argument.

This function accepts Matrices with any number of dimensions.

The RMS is for both Histograms and Matrices defined as:

            2       2
   2   Sum(x ) - Sum (x)/n
RMS  = -------------------
               n

The function returns in either case a value of type Number.

Example:

Call book_histogram(a,100)
Call book_matrix(b,10000)
For i From 1 To 10000 Do
   Global entry=rnd_gauss
   Call fill_histogram(a,entry)
   Global b[i]=entry
Enddo
Say "Histogram mean: {mean(a)}, rms: {rms(a)}"
Say "Matrix mean: {mean(b)}, rms: {rms(b)}"

A test to verify that the mean and RMS for matrices and histograms coincide. This should be numerically exact since the mean and RMS for histograms are computed from the entries, not from the bin contents.

RND_EXPONENTIAL

Generates exponentially distributed random numbers.

The optional argument specifies the mean (and the standard deviation) of the distribution to be generated. If the argument is omitted, a mean of 1 is assumed.

The mean is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as mean the corresponding element of the argument.

RND_FUNCTION

Generates random number according to the function that has, on beforehand, been specified with a call to PREPARE_RND_FUNCTION.

A random number sequences according to only one function can be generated at the time.

This generator has no arguments.

RND_GAUSS

Returns a random Number according to a normal distribution, i.e. a Gaussian distribution with mean 0 and sigma 1.

This function has no arguments.

RND_LANDAU

Returns a random Number according to a Landau distribution.

This function has no arguments.

RND_HISTOGRAM

Generates random number according to the Histogram given as argument.

Separate random number sequences according to different histograms can be generated concurrently.

The procedure works by creating a cumulative histogram and reverse-interpolating it for a uniformly distributed random number. Failures can occur for the following reasons:

the histogram contains one or more holes;
the data is concentrated in very few bins;
a significant fraction of the data is in under- or overflow.

If a failure occurs, up to 9 further attempts are made with new uniformly distributed random numbers. If the failure persists, the global variable OK is set to False. Otherwise, it is set to True.

The argument is mandatory.

RND_POISSON

Generates Poisson distributed random Numbers.

The optional argument specifies the mean of the distribution to be generated. If the argument is omitted, a mean of 1 is assumed.

This procedure calls the CERN library routine RNPSSN.

RND_POLYA

Generates Polya distributed random numbers. A Polya distribution with parameter theta is in fact a gamma distribution with parameter theta+1. For theta equal to 0, the Polya distribution reduces to the exponential distribution.

The argument specifies the theta parameter of the distribution to be generated. If the argument is omitted, a theta of 1 is assumed.

This procedure calls the CERN library routine RNGAMA.

The theta parameter is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as theta the corresponding element of the argument.

RND_UNIFORM

Returns a uniformly distributed random Number in the range <0, 1>, end-points excluded, scaled with the optional argument.

This procedure calls the CERN library routine RANLUX.

The scaling factor is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as mean the corresponding element of the argument.

[The default scaling factor is 1.]

ROW

Returns a 1-dimensional Matrix filled with the numbers 1 to n, where n is the argument.

The argument n is mandatory and should be of type Number.

SIN

Returns the sine of an angle expressed in radians.

SINH

Returns the hyperbolic sine of its argument.

SQRT

Returns the square root of the argument.

The argument, or each element of the argument, should be equal to or larger than 0.

STRING

Converts a variable of any type to a variable of type String as follows:

an Undefined value is converted to the string `Undefined`;
a Number is converted to a string that contains the value, formatted in a more or less readable form;
a Logical becomes either the string `True` or the string `False`;
a String remains unchanged;
a Matrix of 1 dimension becomes a string with the first few elements of the vector, Matrices of higher dimensions are converted to the String `Matrix`;
an Histogram becomes the string `Histogram`.

The STRING function is for instance used to create file names that depend on parameters of the chamber being studied:

Global argon 70
Global co2 30
Global gas_file `Argon_`/string(argon)/`_CO2_`/string(co2)/`.gas`
Call inquire_file(gas_file,exist)
If exist Then
   get {gas_file}
Else
   write {gas_file}
   magboltz argon {argon} co2 {co2}
Endif

SUM

Returns the sum of all channels of an Histogram or of all elements of a Matrix.

The function returns in either case a value of type Number.

TAN

Returns the tangent of an angle expressed in radians.

TANH

Returns the hyperbolic tangent of its argument.

TRAILING

Complement of ENTIER.

TYPE

Takes an expression as argument and returns, in the form of a String, one of the following values: `String`, `Number`, `Logical`, `Histogram`, `Matrix` or `Undefined`.

This function provides a functionality which is similar to the INQUIRE_TYPE procedure. The main difference is that it is permissible to give the INQUIRE_TYPE procedure as first argument a variable that does not yet exist while this is not allowed with the TYPE function. The reason for this is that the arguments of procedures are automatically declared if they do not yet exist, while the arguments of functions must be existing variables. If you wish to use the TYPE function and are not sure the variable exists, then use the GLOBAL function".

Examples:

Global a `Hello !`
Say {type(a)}
Say {type(global(`A`))}

Say {type(global(`does not exist`))}

Both Say statements in the first example will display "String", which is the type the variable A gets by executing the Global statement.

The argument of the GLOBAL function in the second example is not a valid name for a global variable, GLOBAL will therefore return NILL, which is of type Undefined.

Go to the top level, to algebra, to functions, to the topic index, to the table of contents, or to the full text.

Formatted on 15/01/01 at 23:07.