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...
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,
-
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.
-
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,
-
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.
-
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,
-
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.
-
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 ⛓
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, direction
= backward,
action = reversed)
cumPropExp
= getCumPropExp(array, direction
= forward,
action = reversed)
end block
!
block
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 ⛓
6 use pm_mathCumPropExp,
only: forward, backward, reverse, nothing, sequence, selection
12 type(display_type) :: disp
18 real,
allocatable :: array(:), cumPropExp(:)
20 call disp%show(
"array = log([1., 2., 3., 4.])")
21 array
= log([
1.,
2.,
3.,
4.])
24 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array))")
28 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array), sequence)")
32 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array), selection)")
37 call disp%show(
"array = array(size(array):1:-1)")
38 array
= array(
size(array):
1:
-1)
41 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array), direction = backward)")
42 cumPropExp
= getCumPropExp(array,
maxval(array), direction
= backward)
46 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array), direction = backward, action = reverse)")
47 cumPropExp
= getCumPropExp(array,
maxval(array), direction
= backward,
action = reverse)
50 call disp%show(
"cumPropExp = getCumPropExp(array, maxval(array), action = reverse)")
51 cumPropExp
= getCumPropExp(array,
maxval(array),
action = reverse)
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.
This is a generic method of the derived type display_type with pass attribute.
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...
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
integer, parameter RKH
The scalar integer constant of intrinsic default kind, representing the highest-precision real kind t...
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort compiler ⛓
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example Windows Batch compile command via Intel ifort compiler ⛓
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran compiler ⛓
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example output ⛓
2array
= log([
1.,
2.,
3.,
4.])
4+0.00000000,
+0.693147182,
+1.09861231,
+1.38629436
7+0.100000001,
+0.300000012,
+0.600000024,
+1.00000000
10+0.100000001,
+0.300000012,
+0.600000024,
+1.00000000
13+0.100000001,
+0.300000012,
+0.600000024,
+1.00000000
15array
= array(
size(array):
1:
-1)
17+1.38629436,
+1.09861231,
+0.693147182,
+0.00000000
18cumPropExp
= getCumPropExp(array,
maxval(array), direction
= backward)
20+0.100000001,
+0.300000012,
+0.600000024,
+1.00000000
22cumPropExp
= getCumPropExp(array,
maxval(array), direction
= backward,
action = reverse)
24+1.00000000,
+0.600000024,
+0.300000012,
+0.100000001
25cumPropExp
= getCumPropExp(array,
maxval(array),
action = reverse)
27+1.00000000,
+0.900000036,
+0.699999988,
+0.400000006
- 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.
-
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.
-
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.
- Copyright
- Computational Data Science Lab
- Author:
- Amir Shahmoradi, April 25, 2015, 2:21 PM, National Institute for Fusion Studies, The University of Texas Austin
Definition at line 178 of file pm_mathCumPropExp.F90.
1.9.3