Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

ID 767251
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

REDUCE

Transformational Intrinsic Function (Generic): Performs general array reduction.

Syntax

result = REDUCE (array, operation [, mask] [, identity] [, ordered])

result = REDUCE (array, operation, dim [, mask] [, identity] [, ordered])

array

(Input) Must be an array of any data type.

operation

(Input) Must be a pure function with two non-optional, scalar, nonallocatable, nonpointer, nonpolymorphic dummy arguments with the same declared type and type-parameters as array. If one argument has the ASYNCHRONOUS, TARGET, or VALUE attribute, the other argument must have the same attribute. The function result must be non-polymorphic and scalar, with the same declared type and type parameters as array. The function should implement a mathematically associated operation; it need not be commutative.

dim

(Input) Must be a scalar integer whose value is greater than or equal to 1 and less than or equal to the rank of array.

mask

(Input; optional) Must be of type logical and conformable with array.

identity

(Input; optional) Must be scalar with the same declared type and type parameters as array.

ordered

(Input; optional) Must be a scalar of type logical.

Results

The result has the same declared type and type parameters as array. If dim does not appear the result is scalar; otherwise if n=RANK (array) the result has shape [d1, d2,...ddim-1, ddim+1,...dn] and rank n–1.

The result value is calculated differently depending on the form of the call:

  1. The result of REDUCE (array, operation [, identity, ordered]) is calculated iteratively over the values of array. The initial order of the sequence is array element order. While there is more than one element in the sequence, each iteration calculates r = operation (a, b) replacing a and b with r.

    If ordered is present with the value .true., a and b must be the first two elements of the sequence. The process continues until the sequence has one value, and that is the value of the reduction. If array is a zero-sized array and identity is present, the result is the value of identity; otherwise error termination is initiated.

  2. The result of REDUCE(array, operation, mask [, identity, ordered] is calculated as for case 1, but the sequence of values consists only of those values of array for which the corresponding element of mask has the value .true..

  3. If array is a rank 1 array, REDUCE (array, operation, dim [, mask, identity, ordered) is equivalent to REDUCE (array, operation [, mask, identity, ordered]); otherwise, the value of element (s1, s2,..., sdim-1,sdim+1,..., sn) of REDUCE (array, operation, dim [, mask, identity, ordered] is equal to REDUCE (array (s1, s2,..., sdim-1, :, sdim+1,..., sn), operation, dim = 1 [, mask(s1, s2,..., sdim-1, :, sdim+1,..., sn), identity, ordered]).

Example

The following examples all use the function my_add, which returns the sum of its two real arguments.

  1. The result of REDUCE ([2.0, 4.0, 6.0], my_add) is 12.0.

  2. REDUCE (array, my_add, mask = array < 0.0, identity = 0.0) returns the sum of the negative elements of array, or 0.0 if array is zero sized or all of arrays elements are non-negative.

  3. If array is declared as

    REAL,DIMENSION(2, 3)  :: array = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]

    then REDUCE (array, my_add, DIM = 2) has the result [5.0, 7.0, 9.0] and REDUCE (array, my_add, DIM = 1) has the result [6.0, 15.0].