IDL

TOTAL

TOTAL

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.

Examples


See Additional Examples for more information on using TOTAL.

Example 1

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

Syntax


Result = TOTAL( Array [, Dimension] [, /CUMULATIVE] [, /DOUBLE] [, /INTEGER] [, /NAN] [, /PRESERVE_TYPE] )

Return Value


Returns the array sum for the specified dimensions.

Arguments


Array

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.

Dimension

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:

Keywords


CUMULATIVE

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. Note that if the input only has a single element, then a scalar is returned.

Tip: If the input array is a temporary variable or an expression, and the result type matches the input type (for example by using the PRESERVE_TYPE keyword), then TOTAL will perform the cumulative sum in place and no additional memory will be used.

DOUBLE

Set this keyword to force the summation to be done using double-precision arithmetic. By default, if the input is of type DOUBLE, DCOMPLEX, LONG64, or ULONG64, IDL does the summation using double precision; otherwise IDL does the summation using single precision. If this keyword is set to zero, IDL still does the summation using the default precision, but the result is converted to single precision before returning.

INTEGER

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: If Array has a large number of values or the values themselves are large, then the TOTAL with the INTEGER keyword may easily overflow the largest 64-bit integer and return an incorrect result. In this case you may want to avoid using the INTEGER keyword.

NAN

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.

Note: Since the value NaN is treated as missing data, if Array contains only NaN values the TOTAL routine will return 0.

PRESERVE_TYPE

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: For byte or integer data the TOTAL with PRESERVE_TYPE may easily overflow the largest value for that type. The PRESERVE_TYPE keyword is only useful if you know that your values will not overflow, or you want to exploit the overflow, for example in computing a checksum. Otherwise, you may want to use the INTEGER keyword instead.

Thread Pool Keywords

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 !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.

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 and 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: The computation above was done on a Sun Sparc workstation. Your result will depend on the architecture of your CPU; it may be slightly different, and in the notable case of Intel-compatible X86 CPUs may actually be zero due to the use of internal 80-bit floating point registers on that CPU which give it better than double precision accuracy for some computations. Nonetheless, you should be aware of the fact that the order of operations can influence the result.

Additional Examples


Example 2

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

Version History


Original

Introduced

6.1

Added INTEGER and PRESERVE_TYPE keywords

See Also


FACTORIAL, PRODUCT



Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions