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

Generate and return an array of specified rank and shape of arbitrary intrinsic type and kind with its rectangular core and halo set to the corresponding user-specified values.
More...

Detailed Description

Generate and return an array of specified rank and shape of arbitrary intrinsic type and kind with its rectangular core and halo set to the corresponding user-specified values.

The halo of an array of arbitrary rank is defined as the complement of rectangular core region of arbitrary size within a super-rectangle array.
The following figure illustrates example cores and halos of two 1D and 2D arrays.

Parameters
[in]Size: The input non-negative scalar or vector of size rank(array) of type integer of default kind IK, representing the shape of the output array, array(@Size).
  • If the desired rank of the output array is <= 1, then Size must be a scalar.
  • If the desired rank of the output array is >= 2, then Size must be a vector of size rank(array).
[in]core: The input contiguous array of the same rank as the output array, of the same type and kind as the output array, containing the array value to paste into the rectangular core of array.
The extents of core (i.e., shape(core)) delineate the rectangular core of array into which core will be pasted.
  • If array is of type character, then the condition len(core) <= len(array) must hold.
[in]halo: The input scalar of the same type and kind as the output array, containing the value to write to the halo surrounding the specified rectangular core of the array.
  • If array is a scalar string, then halo must be a single character (with length type parameter 1).
  • If array is an array of type character, then halo can have arbitrary length type parameter satisfying the condition len(halo) <= len(array).
[in]coffset: The input non-negative scalar or vector of size rank(array) of type integer of default kind IK representing the index offset from the first (top-left corner) element of array, such that array(@coffset + 1) represents the indices of first element of the rectangular core of array.
  • If the output array is of rank <= 1, then coffset must be a scalar.
  • If the output array is of rank >= 2, then coffset must be a vector of size rank(array).
Returns
array : The output scalar of,
  • type character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU) of the specified length type parameter size or,
the output array of rank 1, 2, or 3, of the user-specified shape size, of either,
  • type character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU), or
  • type integer of kind any supported by the processor (e.g., IK, IK8, IK16, IK32, or IK64), or
  • type logical of kind any supported by the processor (e.g., LK), or
  • type complex of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128), or
  • type real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128).
On output, the rectangular core and halo of the array will be initialized to the specified input arguments core and halo respectively.


Possible calling interfaces ⛓

use pm_arrayInit, only: getCoreHalo
call getCoreHalo(array, core, halo, coffset) ! `array` is scalar string. All other arguments are scalar.
call getCoreHalo(array(:), core(@shape(array)), halo, coffset) ! `array` and `core` are vectors. All other arguments are scalar.
call getCoreHalo(array(..), core(@shape(array)), halo, coffset(1:rank(array))) ! `array` and `core` are of arbitrary but identical ranks.
!
pm_arrayInit::getCoreHalo
Generate and return an array of specified rank and shape of arbitrary intrinsic type and kind with it...
Definition: pm_arrayInit.F90:181
pm_arrayInit
This module contains procedures and generic interfaces for efficient initialization of arbitrary rect...
Definition: pm_arrayInit.F90:64
Warning
All warnings and conditions associated with setCoreHalo also apply to this generic interface.
These conditions are 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.
Remarks
This generic interface is merely a convenience wrapper around the generic interface setCoreHalo.
See also
setCoreHalo
setResized
setRebound
setRebilled
getCoreHalo
setCoreHalo
setRefilled
getCentered
setCentered
getPadded
setPadded


Example usage ⛓

1program example
2
3 use pm_kind, only: LK
4 use pm_kind, only: SK ! All kinds are supported.
5 use pm_kind, only: IK ! All kinds are supported.
6 use pm_kind, only: CK ! All kinds are supported.
7 use pm_kind, only: RK ! All kinds are supported.
8 use pm_io, only: display_type
9 use pm_arrayInit, only: getCoreHalo
10
11 implicit none
12
13 integer(IK) :: i
14 type(display_type) :: disp
15 disp = display_type(file = "main.out.F90")
16
17#define GET_ARRAY \
18 block; \
19 DECLARATION; \
20 call disp%show("size"); \
21 call disp%show( size, deliml = SK_"""" ); \
22 call disp%show("core"); \
23 call disp%show( core, deliml = SK_"""" ); \
24 call disp%show("halo"); \
25 call disp%show( halo, deliml = SK_"""" ); \
26 call disp%show("coffset"); \
27 call disp%show( coffset, deliml = SK_"""" ); \
28 call disp%show("array = getCoreHalo(size, core, halo, coffset)"); \
29 array = getCoreHalo(size, core, halo, coffset); \
30 call disp%show("array"); \
31 call disp%show( array, deliml = SK_"""" ); \
32 call disp%skip(); \
33 end block;
34
35 call disp%skip()
36 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
37 call disp%show("! Initialize scalar with core and halo values.")
38 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
39 call disp%skip()
40
41#define DECLARATION \
42 integer(IK) :: coffset = 3, size = 21; \
43 character(:), allocatable :: array, core, halo; \
44 core = "In God We Trust"; halo = "*";
45 GET_ARRAY
46
47#define DECLARATION \
48 integer(IK) :: coffset = 2, size = 41; \
49 character(:), allocatable :: array, core, halo; \
50 core = "In Science We Invest"; halo = "~";
51 GET_ARRAY
52
53 call disp%skip()
54 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
55 call disp%show("! Initialize vector with core and halo values.")
56 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
57 call disp%skip()
58
59#define DECLARATION \
60 integer(IK) :: coffset = 3, size = 10; \
61 character(5), allocatable :: array(:), core(:), halo; \
62 core = [character(5) :: "In", "God", "We", "Trust"]; \
63 halo = "*****";
64 GET_ARRAY
65
66#define DECLARATION \
67 integer(IK) :: coffset = 3, size = 10; \
68 character(5), allocatable :: array(:), core(:), halo; \
69 character(7) :: array(10) = "", core(4) = [character(7) :: "In", "Science", "We", "Invest"]; \
70 halo = "~~~~~~~"; \
71 GET_ARRAY
72
73#define DECLARATION \
74 integer(IK) :: coffset = 2, size = 10; \
75 integer, allocatable :: array(:), core(:), halo; \
76 core = [1, 2, 3, 4]; \
77 halo = -1;
78 GET_ARRAY
79
80 call disp%skip()
81 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
82 call disp%show("! Initialize matrix with core and halo values.")
83 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
84 call disp%skip()
85
86#define DECLARATION \
87 integer(IK) :: coffset(2) = [5, 3], size(2) = [10, 10]; \
88 integer, allocatable :: array(:,:), core(:,:), halo; \
89 core = reshape([1, 2, 3, 4, 5, 6], [2, 3]); \
90 halo = -1;
91 GET_ARRAY
92
93#define DECLARATION \
94 integer(IK) :: coffset(2) = [3, 5], size(2) = [10, 10]; \
95 logical, allocatable :: array(:,:), core(:,:), halo; \
96 core = reshape([(.false., i = 1, 9)], [3, 3]); \
97 halo = .true.;
98 GET_ARRAY
99
100#define DECLARATION \
101 integer(IK) :: coffset(2) = [3, 5], size(2) = [10, 10]; \
102 complex, allocatable :: array(:,:), core(:,:), halo; \
103 core = reshape([(i, i = 1, 9)], [3, 3]); \
104 halo = -1;
105 GET_ARRAY
106
107#define DECLARATION \
108 integer(IK) :: coffset(2) = [3, 5], size(2) = [10, 10]; \
109 real, allocatable :: array(:,:), Core(:,:), halo; \
110 core = reshape([(i, i = 1, 9)], [3, 3]); \
111 halo = -1;
112 GET_ARRAY
113
114end program example
pm_io::show
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11726
pm_io::skip
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508
pm_io
This module contains classes and procedures for input/output (IO) or generic display operations on st...
Definition: pm_io.F90:252
pm_io::disp
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393
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::CK
integer, parameter CK
The default complex kind in the ParaMonte library: real64 in Fortran, c_double_complex in C-Fortran I...
Definition: pm_kind.F90:542
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_io::display_type
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
2!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3! Initialize scalar with core and halo values.
4!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5
6size
7"+21"
8core
9"In God We Trust"
10halo
11"*"
12coffset
13"+3"
14array = getCoreHalo(size, core, halo, coffset)
15array
16"***In God We Trust***"
17
18size
19"+41"
20core
21"In Science We Invest"
22halo
23"~"
24coffset
25"+2"
26array = getCoreHalo(size, core, halo, coffset)
27array
28"~~In Science We Invest~~~~~~~~~~~~~~~~~~~"
29
30
31!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32! Initialize vector with core and halo values.
33!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34
35size
36"+10"
37core
38"In ", "God ", "We ", "Trust"
39halo
40"*****"
41coffset
42"+3"
43array = getCoreHalo(size, core, halo, coffset)
44array
45"*****", "*****", "*****", "In ", "God ", "We ", "Trust", "*****", "*****", "*****"
46
47size
48"+10"
49core
50"+1", "+2", "+3", "+4"
51halo
52"-1"
53coffset
54"+2"
55array = getCoreHalo(size, core, halo, coffset)
56array
57"-1", "-1", "+1", "+2", "+3", "+4", "-1", "-1", "-1", "-1"
58
59
60!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
61! Initialize matrix with core and halo values.
62!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
63
64size
65"+10", "+10"
66core
67"+1", "+3", "+5"
68"+2", "+4", "+6"
69halo
70"-1"
71coffset
72"+5", "+3"
73array = getCoreHalo(size, core, halo, coffset)
74array
75"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
76"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
77"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
78"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
79"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
80"-1", "-1", "-1", "+1", "+3", "+5", "-1", "-1", "-1", "-1"
81"-1", "-1", "-1", "+2", "+4", "+6", "-1", "-1", "-1", "-1"
82"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
83"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
84"-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1", "-1"
85
86size
87"+10", "+10"
88core
89"F", "F", "F"
90"F", "F", "F"
91"F", "F", "F"
92halo
93"T"
94coffset
95"+3", "+5"
96array = getCoreHalo(size, core, halo, coffset)
97array
98"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
99"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
100"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
101"T", "T", "T", "T", "T", "F", "F", "F", "T", "T"
102"T", "T", "T", "T", "T", "F", "F", "F", "T", "T"
103"T", "T", "T", "T", "T", "F", "F", "F", "T", "T"
104"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
105"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
106"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
107"T", "T", "T", "T", "T", "T", "T", "T", "T", "T"
108
109size
110"+10", "+10"
111core
112"+1.00000000, +0.00000000", "+4.00000000, +0.00000000", "+7.00000000, +0.00000000"
113"+2.00000000, +0.00000000", "+5.00000000, +0.00000000", "+8.00000000, +0.00000000"
114"+3.00000000, +0.00000000", "+6.00000000, +0.00000000", "+9.00000000, +0.00000000"
115halo
116"-1.00000000, +0.00000000"
117coffset
118"+3", "+5"
119array = getCoreHalo(size, core, halo, coffset)
120array
121"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
122"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
123"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
124"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "+1.00000000, +0.00000000", "+4.00000000, +0.00000000", "+7.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
125"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "+2.00000000, +0.00000000", "+5.00000000, +0.00000000", "+8.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
126"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "+3.00000000, +0.00000000", "+6.00000000, +0.00000000", "+9.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
127"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
128"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
129"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
130"-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000", "-1.00000000, +0.00000000"
131
132size
133"+10", "+10"
134core
135"+1.00000000", "+4.00000000", "+7.00000000"
136"+2.00000000", "+5.00000000", "+8.00000000"
137"+3.00000000", "+6.00000000", "+9.00000000"
138halo
139"-1.00000000"
140coffset
141"+3", "+5"
142array = getCoreHalo(size, core, halo, coffset)
143array
144"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
145"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
146"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
147"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "+1.00000000", "+4.00000000", "+7.00000000", "-1.00000000", "-1.00000000"
148"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "+2.00000000", "+5.00000000", "+8.00000000", "-1.00000000", "-1.00000000"
149"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "+3.00000000", "+6.00000000", "+9.00000000", "-1.00000000", "-1.00000000"
150"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
151"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
152"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
153"-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000", "-1.00000000"
154
155
Test:
test_pm_arrayInit
Todo:
Low Priority: This generic interface can be extended to array arguments of higher ranks.
Todo:
Normal Priority: Unlike setCoreHalo, this functional generic interface lacks the option for scalar input core.
This is because of ambiguity created by scalar core for output array of ranks two and higher.
This can be resolved once the Fortran standard allows deferred rank function output.


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:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 181 of file pm_arrayInit.F90.

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