ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
Data Types | Variables
pm_arrayInsert Module Reference

This module contains procedures and generic interfaces for inserting an insertion into the specified locations of an input arrays of various types. More...

Data Types

interface  getInserted
 Generate and return a new array containing the original array within which the input insertion has been inserted at the specified indices index of the original array. More...
 
interface  setInserted
 Return a new array arrayNew containing the original array within which the input insertion has been inserted at the specified indices index of the original array. More...
 

Variables

character(*, SK), parameter MODULE_NAME = "@pm_arrayInsert"
 

Detailed Description

This module contains procedures and generic interfaces for inserting an insertion into the specified locations of an input arrays of various types.

Benchmarks:


Benchmark :: The runtime performance of setInserted for scalar vs. vector input insertion argument. ⛓

1! Test the performance of setInserted() with a vector `insertion` vs. scalar `insertion`.
2program benchmark
3
4 use iso_fortran_env, only: error_unit
5 use pm_kind, only: IK, LK, RK, SK
6 use pm_bench, only: bench_type
7 use pm_arrayRange, only: getRange
8
9 implicit none
10
11 integer(IK) :: i
12 integer(IK) :: isize
13 integer(IK) :: fileUnit
14 integer(IK) , parameter :: NSIZE = 18_IK
15 integer(IK) , parameter :: NBENCH = 2_IK
16 integer(IK) :: arraySize(NSIZE)
17 logical(LK) :: dummy = .true._LK
18 integer(IK) , allocatable :: index(:)
19 real(RK) , allocatable :: array(:)
20 real(RK) , allocatable :: arrayNew(:)
21 real(RK) :: insertion(1)
22 type(bench_type) :: bench(NBENCH)
23
24 bench(1) = bench_type(name = SK_"scalarInsertion", exec = scalarInsertion , overhead = setOverhead)
25 bench(2) = bench_type(name = SK_"vectorInsertion", exec = vectorInsertion , overhead = setOverhead)
26
27 arraySize = [( 2_IK**isize, isize = 1_IK, NSIZE )]
28
29 write(*,"(*(g0,:,' '))")
30 write(*,"(*(g0,:,' '))") "scalarInsertion() vs. vectorInsertion()"
31 write(*,"(*(g0,:,' '))")
32
33 open(newunit = fileUnit, file = "main.out", status = "replace")
34
35 write(fileUnit, "(*(g0,:,','))") "arraySize", (bench(i)%name, i = 1, NBENCH)
36
37 loopOverArraySize: do isize = 1, NSIZE
38
39 write(*,"(*(g0,:,' '))") "Benchmarking with size", arraySize(isize)
40 allocate(array(arraySize(isize)), arrayNew(arraySize(isize)*2))
41 index = getRange(1_IK, arraySize(isize))
42
43 do i = 1, NBENCH
44 bench(i)%timing = bench(i)%getTiming(minsec = 0.05_RK)
45 end do
46
47 deallocate(array, arrayNew)
48 write(fileUnit,"(*(g0,:,','))") arraySize(isize), (bench(i)%timing%mean, i = 1, NBENCH)
49
50 end do loopOverArraySize
51 write(*,"(*(g0,:,' '))") dummy
52 write(*,"(*(g0,:,' '))")
53
54 close(fileUnit)
55
56contains
57
58 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59 ! procedure wrappers.
60 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
61
62 subroutine setOverhead()
63 call initialize()
64 call finalize()
65 end subroutine
66
67 subroutine initialize()
68 call random_number(insertion)
69 end subroutine
70
71 subroutine finalize()
72 dummy = dummy .and. insertion(1) < 0.5_RK
73 end subroutine
74
75 subroutine scalarInsertion()
76 use pm_arrayInsert, only: setInserted
77 call initialize()
78 call setInserted(arrayNew, array, insertion(1), index)
79 call finalize()
80 end subroutine
81
82 subroutine vectorInsertion()
83 block
84 use pm_arrayInsert, only: setInserted
85 call initialize()
86 call setInserted(arrayNew, array, insertion, index)
87 call finalize()
88 end block
89 end subroutine
90
91end program benchmark
pm_arrayInsert::setInserted
Return a new array arrayNew containing the original array within which the input insertion has been i...
Definition: pm_arrayInsert.F90:1081
pm_arrayRange::getRange
Generate minimally-spaced character, integer, real sequences or sequences at fixed intervals of size ...
Definition: pm_arrayRange.F90:135
pm_bench::getTiming
Generate and return an object of type timing_type containing the benchmark timing information and sta...
Definition: pm_bench.F90:574
pm_arrayInsert
This module contains procedures and generic interfaces for inserting an insertion into the specified ...
Definition: pm_arrayInsert.F90:61
pm_arrayRange
This module contains procedures and generic interfaces for generating ranges of discrete character,...
Definition: pm_arrayRange.F90:36
pm_bench
This module contains abstract interfaces and types that facilitate benchmarking of different procedur...
Definition: pm_bench.F90:41
pm_kind
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268
pm_kind::RK
integer, parameter RK
The default real kind in the ParaMonte library: real64 in Fortran, c_double in C-Fortran Interoperati...
Definition: pm_kind.F90:543
pm_kind::LK
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541
pm_kind::IK
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
pm_kind::SK
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
pm_bench::bench_type
This is the class for creating benchmark and performance-profiling objects.
Definition: pm_bench.F90:386

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

Postprocessing of the benchmark output ⛓
1#!/usr/bin/env python
2
3import matplotlib.pyplot as plt
4import pandas as pd
5import numpy as np
6
7fontsize = 14
8
9methods = ["scalarInsertion", "vectorInsertion"]
10
11df = pd.read_csv("main.out")
12
13
16
17ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
18ax = plt.subplot()
19
20for method in methods:
21 plt.plot( df["arraySize"].values
22 , df[method].values
23 , linewidth = 2
24 )
25
26plt.xticks(fontsize = fontsize)
27plt.yticks(fontsize = fontsize)
28ax.set_xlabel("Array Size", fontsize = fontsize)
29ax.set_ylabel("Runtime [ seconds ]", fontsize = fontsize)
30ax.set_title("Removing array segments with insertion(1) (scalar) vs. insertion(1:1) (vector).\nLower is better.", fontsize = fontsize)
31ax.set_xscale("log")
32ax.set_yscale("log")
33plt.minorticks_on()
34plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
35ax.tick_params(axis = "y", which = "minor")
36ax.tick_params(axis = "x", which = "minor")
37ax.legend ( methods
38 #, loc='center left'
39 #, bbox_to_anchor=(1, 0.5)
40 , fontsize = fontsize
41 )
42
43plt.tight_layout()
44plt.savefig("benchmark.scalarInsertion_vs_vectorInsertion.runtime.png")
45
46
49
50ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
51ax = plt.subplot()
52
53plt.plot( df["arraySize"].values
54 , np.ones(len(df["arraySize"].values))
55 #, linestyle = "--"
56 #, color = "black"
57 , linewidth = 2
58 )
59plt.plot( df["arraySize"].values
60 , df["vectorInsertion"].values / df["scalarInsertion"].values
61 , linewidth = 2
62 )
63
64plt.xticks(fontsize = fontsize)
65plt.yticks(fontsize = fontsize)
66ax.set_xlabel("Array Size", fontsize = fontsize)
67ax.set_ylabel("Runtime compared to scalarInsertion()", fontsize = fontsize)
68ax.set_title("Runtime Ratio: Insert with insertion(1:1) / Insert with insertion(1).\nLower means faster. Lower than 1 means faster than scalarInsertion.", fontsize = fontsize)
69ax.set_xscale("log")
70#ax.set_yscale("log")
71plt.minorticks_on()
72plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
73ax.tick_params(axis = "y", which = "minor")
74ax.tick_params(axis = "x", which = "minor")
75ax.legend ( ["scalarInsertion", "vectorInsertion"]
76 #, bbox_to_anchor = (1, 0.5)
77 #, loc = "center left"
78 , fontsize = fontsize
79 )
80
81plt.tight_layout()
82plt.savefig("benchmark.scalarInsertion_vs_vectorInsertion.runtime.ratio.png")

Visualization of the benchmark output ⛓

Benchmark moral ⛓
  1. The procedures under the generic interface setInserted take both scalar and vector insertion arguments.
    As evidenced by the above benchmark, when the input insertion is vector of length 1, it is much faster, by 4X or more, to pass insertion as a scalar instead of a whole array of length 1.
    This benchmark represents the worst-case scenario.
    Note that this benchmark is likely irrelevant to inserting substrings to Fortran strings.


Benchmark :: The runtime performance of getInserted vs. setInserted ⛓

1! Test the performance of `getInserted()` vs. `setInserted()`.
2program benchmark
3
4 use iso_fortran_env, only: error_unit
5 use pm_arrayRange, only: getRange
6 use pm_kind, only: IK, LK, RK, SK
7 use pm_bench, only: bench_type
8
9 implicit none
10
11 integer(IK) :: i
12 integer(IK) :: isize
13 integer(IK) :: fileUnit
14 integer(IK) , parameter :: NSIZE = 15_IK
15 integer(IK) , parameter :: NBENCH = 2_IK
16 integer(IK) :: arraySize(NSIZE)
17 logical(LK) :: dummy = .true._LK
18 real(RK) :: insertion = 1._RK
19 real(RK) , allocatable :: array(:), arrayNew(:)
20 integer(IK) , allocatable :: index(:)
21 type(bench_type) :: bench(NBENCH)
22
23 bench(1) = bench_type(name = SK_"setInserted", exec = setInserted , overhead = setOverhead)
24 bench(2) = bench_type(name = SK_"getInserted", exec = getInserted , overhead = setOverhead)
25
26 arraySize = [( 2_IK**isize, isize = 1_IK, NSIZE )]
27
28 write(*,"(*(g0,:,' '))")
29 write(*,"(*(g0,:,' '))") "setInserted() vs. getInserted()"
30 write(*,"(*(g0,:,' '))")
31
32 open(newunit = fileUnit, file = "main.out")
33
34 write(fileUnit, "(*(g0,:,','))") "arraySize", (bench(i)%name, i = 1, NBENCH)
35
36 loopOverArraySize: do isize = 1, NSIZE
37
38 write(*,"(*(g0,:,' '))") "Benchmarking with size", arraySize(isize)
39
40 index = getRange(1_IK, arraySize(isize))
41 allocate(arrayNew(arraySize(isize)+size(index)))
42 allocate(array(arraySize(isize)), source = 1._RK)
43 do i = 1, NBENCH
44 bench(i)%timing = bench(i)%getTiming(minsec = 0.05_RK)
45 end do
46 deallocate(array, arrayNew)
47
48 write(fileUnit,"(*(g0,:,','))") arraySize(isize), (bench(i)%timing%mean, i = 1, NBENCH)
49
50 end do loopOverArraySize
51 write(*,"(*(g0,:,' '))") dummy
52 write(*,"(*(g0,:,' '))")
53
54 close(fileUnit)
55
56contains
57
58 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59 ! procedure wrappers.
60 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
61
62 subroutine setOverhead()
63 call initialize()
64 call finalize()
65 end subroutine
66
67 subroutine initialize()
68 call random_number(insertion)
69 end subroutine
70
71 subroutine finalize()
72 dummy = dummy .and. arrayNew(1) == 0.5_RK
73 end subroutine
74
75 subroutine setInserted()
76 block
77 use pm_arrayInsert, only: setInserted
78 call initialize()
79 call setInserted(arrayNew, array, insertion, index, positive = .true._LK, sorted = .true._LK)
80 call finalize()
81 end block
82 end subroutine
83
84 subroutine getInserted()
85 block
86 use pm_arrayInsert, only: getInserted
87 call initialize()
88 arrayNew(:) = getInserted(array, insertion, index, positive = .true._LK, sorted = .true._LK)
89 call finalize()
90 end block
91 end subroutine
92
93end program benchmark
pm_arrayInsert::getInserted
Generate and return a new array containing the original array within which the input insertion has be...
Definition: pm_arrayInsert.F90:165

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

Postprocessing of the benchmark output ⛓
1#!/usr/bin/env python
2
3import matplotlib.pyplot as plt
4import pandas as pd
5import numpy as np
6
7fontsize = 14
8
9methods = ["setInserted", "getInserted"]
10
11df = pd.read_csv("main.out")
12
13
16
17ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
18ax = plt.subplot()
19
20for method in methods:
21 plt.plot( df["arraySize"].values
22 , df[method].values
23 , linewidth = 2
24 )
25
26plt.xticks(fontsize = fontsize)
27plt.yticks(fontsize = fontsize)
28ax.set_xlabel("Array Size", fontsize = fontsize)
29ax.set_ylabel("Runtime [ seconds ]", fontsize = fontsize)
30ax.set_title("setInserted() vs. getInserted()\nLower is better.", fontsize = fontsize)
31ax.set_xscale("log")
32ax.set_yscale("log")
33plt.minorticks_on()
34plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
35ax.tick_params(axis = "y", which = "minor")
36ax.tick_params(axis = "x", which = "minor")
37ax.legend ( methods
38 #, loc='center left'
39 #, bbox_to_anchor=(1, 0.5)
40 , fontsize = fontsize
41 )
42
43plt.tight_layout()
44plt.savefig("benchmark.getInserted_vs_setInserted.runtime.png")
45
46
49
50ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
51ax = plt.subplot()
52
53plt.plot( df["arraySize"].values
54 , np.ones(len(df["arraySize"].values))
55 #, linestyle = "-"
56 #, color = "black"
57 , linewidth = 2
58 )
59plt.plot( df["arraySize"].values
60 , df["getInserted"].values / df["setInserted"].values
61 , linewidth = 2
62 )
63
64plt.xticks(fontsize = fontsize)
65plt.yticks(fontsize = fontsize)
66ax.set_xlabel("Array Size", fontsize = fontsize)
67ax.set_ylabel("Runtime compared to setInserted()", fontsize = fontsize)
68ax.set_title("getInserted() / setInserted()\nLower means faster. Lower than 1 means faster than setInserted().", fontsize = fontsize)
69ax.set_xscale("log")
70#ax.set_yscale("log")
71plt.minorticks_on()
72plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
73ax.tick_params(axis = "y", which = "minor")
74ax.tick_params(axis = "x", which = "minor")
75ax.legend ( ["setInserted", "getInserted"]
76 #, bbox_to_anchor = (1, 0.5)
77 #, loc = "center left"
78 , fontsize = fontsize
79 )
80
81plt.tight_layout()
82plt.savefig("benchmark.getInserted_vs_setInserted.runtime.ratio.png")

Visualization of the benchmark output ⛓

Benchmark moral ⛓
  1. The procedures under the generic interface getInserted are functions while the procedures under the generic interface setInserted are subroutines.
    From the benchmark results, it appears that the functional interface performs slightly less efficiently than the subroutine interface.
    The sole apparent reason for this performance loss seems to be the extra copy of the result to the allocatable arrayNew on return from the function.
    Note that this benchmark does not even include the cost of repeated reallcations, that is, the allocation of arrayNew happen only once in all tests.
  2. Note that this benchmark considers the worst-case scenario where insertion must be inserted at all positions of the input array.
Test:
test_pm_arrayInsert


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.

Copyright
Computational Data Science Lab
Author:
Fatemeh Bagheri, Wednesday 12:20 AM, October 13, 2021, Dallas, TX

Variable Documentation

◆ MODULE_NAME

character(*, SK), parameter pm_arrayInsert::MODULE_NAME = "@pm_arrayInsert"

Definition at line 67 of file pm_arrayInsert.F90.