The TOTAL function returns the sum of the elements of Array. The sum of the array elements over a given dimension is returned if the Dimension argument is present.
Result = TOTAL( Array [, Dimension] [, /CUMULATIVE] [, /DOUBLE] [, /INTEGER] [, /NAN] [, /PRESERVE_TYPE] )
Returns the array sum for the specified dimensions.
The array to be summed. This array can be of any basic type except string. If Array is double-precision floating-point, complex, or double-precision complex, the result is of the same type. Otherwise, the result is single-precision floating-point.
The dimension over which to sum, starting at one. If this argument is not present or zero, the scalar sum of all the array elements is returned. If this argument is present, the result is an array with one less dimension than Array. For example, if the dimensions of Array are N1, N2, N3, and Dimension is 2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the sum:
If this keyword is set, the result is an array of the same size as the input, with each element, i, containing the sum of the input array elements 0 to i. This keyword also works with the Dimension parameter, in which case the sum is performed over the given dimension.
| Tip |
Set this keyword to perform the summation in double-precision floating-point.
Set this keyword to perform the TOTAL using integer arithmetic, and to return an integer result. If Array is of type ULONG64 then unsigned 64-bit integers are used for the computation and the Result is of type ULONG64, otherwise signed 64-bit integers are used and the Result is of type LONG64. If Array is complex and INTEGER is set, then only the real part of each value is used for the computation. The DOUBLE keyword is ignored if INTEGER is set.
| Note |
Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the input data. Elements with the value NaN or Infinity are treated as missing data. (See Special Floating-Point Values for more information on IEEE floating-point values.)
| Note |
Set this keyword to perform the TOTAL using the input type, and to return a result of the same type. The DOUBLE and INTEGER keywords are ignored if PRESERVE_TYPE is set.
| Note |
This routine is written to make use of IDL's thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the
The thread pool is used for non-cumulative sums, and is not used if the CUMULATIVE keyword is specified. In a cumulative sum, each result value depends on all of the previous results, so overlapped execution is not possible.
You should be aware that when summing a large number of values, the result from TOTAL can depend heavily upon the order in which the numbers are added. Since the thread pool will add values in a different order, you may obtain a different - but equally correct - result than that obtained using the standard non-threaded implementation. This effect occurs because TOTAL uses floating point arithmetic, and the mantissa of a floating point value has a fixed number of significant digits. The effect is especially obvious when using single precision arithmetic, but can also affect double precision computations. Such differences do not mean that the sums are incorrect. Rather, they mean that they are equal within the ability of the floating point representation used to represent them. For more information on floating-point numbers, see Accuracy & Floating-Point Operations.
It is also worth noting that this effect, while illustrated by the use of the thread pool, is not caused by the use of threading. It is simply caused by the different order in which the numbers are summed, as can be illustrated by the following non-threaded example:
vec = FINDGEN(100000) PRINT, TOTAL(vec, /TPOOL_NO) - TOTAL(REVERSE(vec), /TPOOL_NO)
IDL prints:
-96768.0
As you can see, the small floating-point errors can accumulate across the sum of a large number of values.
| Note |
This example sums the elements of a one-dimensional array:
; Define a one-dimensional array: A = [20, 10, 5, 5, 3] ; Sum the elements of the array: SUMA = TOTAL([20, 10, 5, 5, 3]) ; Print the results: PRINT, 'A = ', A PRINT, 'Sum of A = ', SUMA
IDL prints:
A = 20 10 5 5 3 Sum of A = 43.0000
The results are different when a multi-dimensional array is used:
; Define a multi-dimensional array: A = FINDGEN(5,5) ; Sum each of the rows in A: SUMROWS = TOTAL(A, 1) ; Sum each of the columns in A: SUMCOLS = TOTAL(A, 2) ; Print the results: PRINT, 'A = ', A PRINT, 'Sum of each row:', SUMROWS PRINT, 'Sum of each column:', SUMCOLS
IDL prints:
A = 0.000000 1.00000 2.00000 3.00000 4.00000 5.00000 6.00000 7.00000 8.00000 9.00000 10.0000 11.0000 12.0000 13.0000 14.0000 15.0000 16.0000 17.0000 18.0000 19.0000 20.0000 21.0000 22.0000 23.0000 24.0000 Sum of each row: 10.0000 35.0000 60.0000 85.0000 110.000 Sum of each column: 50.0000 55.0000 60.0000 65.0000 70.0000
Introduced: Original
INTEGER and PRESERVE_TYPE keywords: 6.1