fsc2: 5.4 Mathematical functions

5.4 Mathematical functions

The following mathematical function can be used in all section of an EDL script that allow the use of functions.

List of all mathematical functions:

`abs()'
`acos()'
`acosh()'
`asin()'
`asinh()'
`atan()'
`atanh()'
`ceil()'
`cos()'
`cosh()'
`float()'
`floor()'
`grandom()'
`index_of_max()'
`index_of_min()'
`int()'
`round()'
`max_of()'
`mean()'
`condense_array()'
`mean_part_array()'
`min_of()'
`random()'
`random2()'
`rms()'
`set_seed()'
`shuffle()'
`sin()'
`sinh()'
`sqrt()'
`square()'
`tan()'
`tanh()'
`add_to_average()'

Descriptions of mathematical functions:

`abs()'

Returns the absolute value of an integer or floating point number (or all the elements of an 1- or more-dimensional array) .

`acos()'

Returns the inverse of the cosine function of the argument (simple number or all elements of an 1- or more-dimensional array) as an angle in radian. The argument must be in the interval [-1, 1], the result an element of the interval [0, pi].

`acosh()'

Returns the inverse of the hyperbolic cosine function of the argument (simple number or all elements of an 1- or more-dimensional array ).

`asin()'

Returns the inverse of the sine function of the argument (simple number or all elements of an 1- or more-dimensional array) as an angle in radian. The argument must be in the interval [-1, 1], the result an element of the interval [-pi/2, pi/2].

`asinh()'

Returns the inverse of the hyperbolic sine function of the argument (simple number or all elements of an 1- or more-dimensional array).

`atan()'

Returns the inverse of the tangent function of the argument (simple number or all elements of an 1- or more-dimensional array) as an angle in radian, the result an element of the interval [-pi, pi].

`atanh()'

Returns the inverse of the hyperbolic tangent function of the argument (simple number or all elements of an 1- or more-dimensional array).

`ceil()'

Converts a floating point number (or all the elements of an 1- or more-dimensional array) to the smallest integer that is not less than the argument, i.e.

round( 8.6 ) = 9     round( -8.6 ) = -8

`cos()'

Returns the cosine of the argument (simple number or all elements of an 1- or more-dimensional array), with the argument interpreted as the angle in radian.

`cosh()'

Returns the hyperbolic cosine of the argument (simple number or all elements of an 1- or more-dimensional array).

`float()'

Converts a number (or all the elements of an 1- or more-dimensional array) to floating point type.

`floor()'

Converts a floating point number (or all the elements of an 1- or more-dimensional array) to the largest integer that is not larger than the argument, i.e.

floor( 8.6 ) = 8    floor( -8.6 ) = -9

`grandom()'

If called without an argument the function returns one of a set of pseudo-random number with Gaussian distribution, a mean of zero and a variance of 1. If called with a non-zero, positive argument it returns an array of Gaussian distributed random numbers where the argument specifies the size of the array. These random numbers are probably better suited for simulating noise than the ones returned by random(). Note that in order to initialize the random generator to something other than the default seed you must call set_seed().

`index_of_max()'

The function expects a 1-dimensional array as its only argument and returns the index of the largest element in the array. If there's more that one element having the maximum value in the array the index designates the first of these elements.

`index_of_min()'

The function expects a 1-dimensional array as its only argument and returns the index of the smallest element in the array. If there's more that one element having the minimum value in the array the index designates the first of these elements.

`int()'

Converts a number (or all the elements of an 1- or more-dimensional array) to integer type by truncating all digits following the decimal point.

`round()'

Converts a floating point number (or all the elements of an 1- or more-dimensional array) to the nearest integer, i.e.

round( 8.5 ) = 9    round( 8.49 ) = 8    round( -1.75 ) = -2

`max_of()'

Returns the largest value of all arguments. Arguments can be any number of numbers or 1- or more-dimensional arrays. If all arguments are integer numbers an integer number is returned, otherwise a floating point value.

`mean()'

Expects an 1- or more-dimensional array as input and returns the mean value of the array elements. Optionally, it accepts up to two more integer arguments, the start index of the first element of the (1-dimensional) array or the index of the first sub-matrix (for more-dimensional array) to be included into the calculation and the number of elements to be used. If the length parameter is missing all elements up to the end of the 1D-array or all remaining sub-matrices of the more-dimensional array are used, otherwise only the number of elements or sub-arrays specified as the third argument are used. .

`condense_array()'

The function expects as its arguments a 1-dimensional arrays of integers or floats and a positive (non-zero) integer, the "chunk size" N. It returns a new array where each element consists of the average of N (consecutive) elements of the original array. The length of this array is the length of the original array divided by N and the first element of this result array is the average of the first N elements of the original array, the second element is the average of the second set of N elements of the input array etc.

The function is meant to speed up calculations in cases where the resolution of measured data is higher than required and you want to calculate an array with a lower resolution by combining sets of sub-arrays of the original array. I.e. if a digitizer returns a curve with each measured point representing a time interval of just 1 ns but you only need a time resolution of 20 ns you can call this function with N equal to 20 to average over each set of 20 points. This returns an array that's shorter by a factor of 20 and with data that represent data for 20 ns time intervals.

Calling the function with a chunk size N of 1 is equivalent to invoking the float() function while calling it with a sub-partition size N equal to the length of the original array itself is equivalent to calling the mean() function on the array.

`mean_part_array()'

The function expects as its arguments a 1-dimensional array of integers or floats and a positive (non-zero) integer, the "chunk size" M. The array is split up into sub-arrays with M elements and these sub-arrays are averaged together. The resulting 1-dimensional float array with M elements is returned, the 1st element of the result array being the average of all the 1st elements of the (M-sized) sub-arrays of the original arrays, the 2nd element being the average of all the 2nd elements of the sub-arrays etc.

The function is meant to speed up calculations in cases where a repeated signal that has been sampled several times in one go and stored in a flat array, is to be averaged.

Calling the function with a chunk size of 1 is equivalent to invoking the mean() function while calling it with a chunk size equal to the length of the array itself is equivalent to calling the float() function on the array.

`min_of()'

Returns the smallest value of all arguments. Arguments can be any number of numbers or 1- or more-dimensional arrays. If all arguments are integer numbers an integer number is returned, otherwise a floating point value.

`random()'

If called with no argument the function returns a single pseudo-random number in the interval [0, 1] (i.e. values larger or equal to 0 and less or equal to 1). If called with a non-zero, positive argument it returns an array of random numbers where the argument specifies the size of the array. Note that in order to initialize the random generator to something other than the default seed you must call set_seed().

`random2()'

If called with no argument the function returns a single pseudo-random number in the interval [0, 1[ (i.e. values larger or equal to 0 and less than 1). If called with a non-zero, positive argument it returns an array of random numbers where the argument specifies the size of the array. Note that in order to initialize the random generator to something other than the default seed you must call set_seed().

`rms()'

Expects an one-dimensional array as input and returns the square root of the sum of the squared array elements, divided by the number of elements. Optionally, it accepts up to two more integer arguments, the index of the first element of the 1-dimensional array or the index of the first sub-matrix (for more-dimensional arrays) to be included into the calculation and the number of elements to be used. If the length parameter is missing all elements up to the end of the array or all remaining sub-arrays are used, otherwise only as many array elements or sub-matrices as specified by the third argument are used..

`set_seed()'

Sets a seed for the random number generator used in the functions random(), random2(), shuffle() and grandom(). The argument has to be a positive integer. Alternatively, when no argument is given, the time in seconds since 00:00:00 UTC, January 1, 1970 is used as the seed.

`shuffle()'

This function expects a 1-dimensional array as its input an returns an array of the same length with the elements of the input array randomly shuffled. Note that you can initialize the random generator used by calling set_seed().

`sin()'

Returns the sine of the argument (simple number or all elements of an 1- or more-dimensional array), with the argument interpreted as the angle in radian.

`sinh()'

Returns the hyperbolic sine of the argument (simple number or all elements of an 1- or more-dimensional array).

`sqrt()'

Returns the square root of an integer or floating point number (or all the elements of an 1- or more-dimensional array). The argument must be a positive number.

`square()'

Returns the square of an integer or floating point number (or all the elements of an 1- or more-dimensional array).

`tan()'

Returns the tangent of the argument (simple number or all elements of an 1- or more-dimensional array), with the argument interpreted as the angle in radian.

`tanh()'

Returns the hyperbolic tangent of the argument (simple number or all elements of an 1- or more-dimensional array).

`add_to_average()'

This is a utility functions to simplify (and speed up) the calculation of averaged data. It takes three arguments, as the first an already averaged (floating point) value or an array of such values, as the second a new value to be added to the average or an array of such data (obviously, both the first and the second argument must be either both simple values or arrays, and if they are arrays, must have the same lengths), and the third argument must be the an integer value which is the new count of the number of data sets having contributed to the average (i.e. if the average consists of already N data sets and now a new one gets added then this value must be N + 1).

With this function you can simply write

avg = add_to_average( avg, data, N + 1 );

instead of

avg = ( N * avg + data ) / ( N + 1 );

which is not only simpler to read but also a lot faster.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.