ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_mathCumPropExp::getCumPropExp Interface Reference

Generate and return the cumulative sum of the proportions of the exponential of the input array, optionally in the backward direction and, optionally reverse the output cumulative sum upon return. More...

Detailed Description

Generate and return the cumulative sum of the proportions of the exponential of the input array, optionally in the backward direction and, optionally reverse the output cumulative sum upon return.

The returned array is normalized such that all of its elements fall in the range \([0,1]\).
All operations are performed while avoiding arithmetic overflow.

Parameters
[in]array: The input contiguous array of shape (:) of type real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128) whose cumulative proportional sum will have to be computed.
[in]maxArray: The input scalar of the same type and kind as the input array representing the maximum value in array (i.e., maxArray = maxval(array)).
[in]control: The input scalar object that can be,
  1. the constant sequence or equivalently, an object of type sequence_type.
    Specifying this value forces the algorithm to skip runtime underflow checks.
    This means all exponentiation operations will be carried out for each element.
    Specifying this value can aid runtime efficiency when the divisions of none or very few of the elements of array (for example, half or less) by maxArray causes underflow.
    In such cases, the potentially expensive runtime branching is avoided at the cost of performing a very few exponentiation operations.
    The typical cost of an if-branch is 7-20 CPU cycles on the contemporary architecture while exponentiation typically costs ~200 CPU cycles.
    See the relevant benchmark here.
  2. the constant selection or equivalently, an object of type selection_type.
    Enabling this option can aid runtime efficiency when the division of a significant number of elements of array (for example, half or more) by maxArray causes underflow.
    In such cases, the exponentiation is avoided if control = selection` leading to faster runtime by avoiding exponentiation since it is highly expensive (on the order of ~200 CPU cycles).
    See the relevant benchmark here.
(optional, default = sequence)
[in]direction: The input scalar object that can be,
  1. the constant forward or equivalently, an object of type forward_type, implying that the output cumulative sum has be computed from the first element to the last element of the input array.
    even though the increments will still be written from the first element of cumPropExp to the last.
  2. the constant backward or equivalently, an object of type backward_type, implying that the output cumulative sum has be computed from the last element to the first element of the input array even though the increments will still be written from the first element of cumPropExp to the last.
(optional, default = sequence)
[in]action: The input scalar object that can be,
  1. the constant nothing or equivalently, an object of type nothing_type, implying no action to be performed on the elements of the output cumPropExp will have be reversed upon return.
  2. the constant reverse or equivalently, an object of type reverse_type, implying that the order of the elements of the output cumPropExp will have be reversed upon return, such that its last element becomes the first.
(optional, default = nothing)
Returns
cumPropExp : The output array of the same size, shape, type, and kind as the input array containing the cumulative sum of proportions of array in the specified direction.


Possible calling interfaces

use pm_mathCumPropExp, only: getCumPropExp, sequence, selection, forward, backward, nothing, reverse
cumPropExp(:) = getCumPropExp(array(:) , maxArray = maxArray, direction = direction, action = action)
cumPropExp(:) = getCumPropExp(array(:), control , maxArray = maxArray, direction = direction, action = action)
Generate and return the cumulative sum of the proportions of the exponential of the input array,...
This module contains the procedures and interfaces for computing the cumulative sum of the exponentia...
Warning
The condition maxArray == maxval(array) must hold for the corresponding arguments.
This condition is verified only if the library is built with the preprocessor macro CHECK_ENABLED=1.
The pure procedure(s) documented herein become impure when the ParaMonte library is compiled with preprocessor macro CHECK_ENABLED=1.
By default, these procedures are pure in release build and impure in debug and testing builds.
Note
The functionalities of the procedures under this generic interface,
block
cumPropExp = getCumPropExp(array)
cumPropExp = getCumPropExp(array, direction = backward)
cumPropExp = getCumPropExp(array, direction = backward, action = reversed)
cumPropExp = getCumPropExp(array, direction = forward, action = reversed)
end block
!
are equivalent to the following lines respectively,
block
use pm_mathCumPropExp, only: getCumSum
cumPropExp = getCumSum(exp(array - maxval(array))); cumPropExp = cumPropExp / cumPropExp(size(array, maxArray, 1, IK))
cumPropExp = getCumSum(exp(array - maxval(array)), direction = backward); cumPropExp = cumPropExp / cumPropExp(size(array, maxArray, 1, IK))
cumPropExp = getCumSum(exp(array - maxval(array)), direction = backward, action = reversed); cumPropExp = cumPropExp / cumPropExp(1)
cumPropExp = getCumSum(exp(array - maxval(array)), direction = forward, action = reversed); cumPropExp = cumPropExp / cumPropExp(1)
end block
!
See also
getCumSum
setCumSum
getCumPropExp
setCumPropExp


Example usage

1program example
2
3 use pm_kind, only: SK, IK, LK
4 use pm_io, only: display_type
6 use pm_mathCumPropExp, only: forward, backward, reverse, nothing, sequence, selection
7 use pm_distUnif, only: setUnifRand
8
9 implicit none
10
11
12 type(display_type) :: disp
13
14 disp = display_type(file = "main.out.F90")
15
16 block
17 use pm_kind, only: RKG => RKH ! all real kinds are supported.
18 real, allocatable :: array(:), cumPropExp(:)
19 call disp%skip
20 call disp%show("array = log([1., 2., 3., 4.])")
21 array = log([1., 2., 3., 4.])
22 call disp%show("array")
23 call disp%show( array )
24 call disp%show("cumPropExp = getCumPropExp(array, maxval(array))")
25 cumPropExp = getCumPropExp(array, maxval(array))
26 call disp%show("cumPropExp")
27 call disp%show( cumPropExp )
28 call disp%show("cumPropExp = getCumPropExp(array, maxval(array), sequence)")
29 cumPropExp = getCumPropExp(array, maxval(array), sequence)
30 call disp%show("cumPropExp")
31 call disp%show( cumPropExp )
32 call disp%show("cumPropExp = getCumPropExp(array, maxval(array), selection)")
33 cumPropExp = getCumPropExp(array, maxval(array), selection)
34 call disp%show("cumPropExp")
35 call disp%show( cumPropExp )
36 call disp%skip
37 call disp%show("array = array(size(array):1:-1)")
38 array = array(size(array):1:-1)
39 call disp%show("array")
40 call disp%show( array )
41 call disp%show("cumPropExp = getCumPropExp(array, maxval(array), direction = backward)")
42 cumPropExp = getCumPropExp(array, maxval(array), direction = backward)
43 call disp%show("cumPropExp")
44 call disp%show( cumPropExp )
45 call disp%skip
46 call disp%show("cumPropExp = getCumPropExp(array, maxval(array), direction = backward, action = reverse)")
47 cumPropExp = getCumPropExp(array, maxval(array), direction = backward, action = reverse)
48 call disp%show("cumPropExp")
49 call disp%show( cumPropExp )
50 call disp%show("cumPropExp = getCumPropExp(array, maxval(array), action = reverse)")
51 cumPropExp = getCumPropExp(array, maxval(array), action = reverse)
52 call disp%show("cumPropExp")
53 call disp%show( cumPropExp )
54 call disp%skip
55 end block
56
57end program example
Return a uniform random scalar or contiguous array of arbitrary rank of randomly uniformly distribute...
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11726
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508
This module contains classes and procedures for computing various statistical quantities related to t...
This module contains classes and procedures for input/output (IO) or generic display operations on st...
Definition: pm_io.F90:252
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
Definition: pm_kind.F90:540
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
Definition: pm_kind.F90:539
integer, parameter RKH
The scalar integer constant of intrinsic default kind, representing the highest-precision real kind t...
Definition: pm_kind.F90:858
Generate and return an object of type display_type.
Definition: pm_io.F90:10282

Example Unix compile command via Intel ifort compiler
1#!/usr/bin/env sh
2rm main.exe
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
4./main.exe

Example Windows Batch compile command via Intel ifort compiler
1del main.exe
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
4main.exe

Example Unix / MinGW compile command via GNU gfortran compiler
1#!/usr/bin/env sh
2rm main.exe
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
4./main.exe

Example output
1
2array = log([1., 2., 3., 4.])
3array
4+0.00000000, +0.693147182, +1.09861231, +1.38629436
5cumPropExp = getCumPropExp(array, maxval(array))
6cumPropExp
7+0.100000001, +0.300000012, +0.600000024, +1.00000000
8cumPropExp = getCumPropExp(array, maxval(array), sequence)
9cumPropExp
10+0.100000001, +0.300000012, +0.600000024, +1.00000000
11cumPropExp = getCumPropExp(array, maxval(array), selection)
12cumPropExp
13+0.100000001, +0.300000012, +0.600000024, +1.00000000
14
15array = array(size(array):1:-1)
16array
17+1.38629436, +1.09861231, +0.693147182, +0.00000000
18cumPropExp = getCumPropExp(array, maxval(array), direction = backward)
19cumPropExp
20+0.100000001, +0.300000012, +0.600000024, +1.00000000
21
22cumPropExp = getCumPropExp(array, maxval(array), direction = backward, action = reverse)
23cumPropExp
24+1.00000000, +0.600000024, +0.300000012, +0.100000001
25cumPropExp = getCumPropExp(array, maxval(array), action = reverse)
26cumPropExp
27+1.00000000, +0.900000036, +0.699999988, +0.400000006
28
29
Test:
test_pm_mathCumPropExp


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, April 25, 2015, 2:21 PM, National Institute for Fusion Studies, The University of Texas at Austin

Definition at line 178 of file pm_mathCumPropExp.F90.


The documentation for this interface was generated from the following file: